1.\" $NetBSD: directory.3,v 1.26 2006/05/18 15:30:36 christos Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd May 18, 2006 33.Dt DIRECTORY 3 34.Os 35.Sh NAME 36.Nm opendir , 37.Nm readdir , 38.Nm readdir_r , 39.Nm telldir , 40.Nm seekdir , 41.Nm rewinddir , 42.Nm closedir , 43.Nm dirfd 44.Nd directory operations 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In dirent.h 49.Ft DIR * 50.Fn opendir "const char *filename" 51.Ft struct dirent * 52.Fn readdir "DIR *dirp" 53.Ft int 54.Fn readdir_r "DIR * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict result" 55.Ft long 56.Fn telldir "DIR *dirp" 57.Ft void 58.Fn seekdir "DIR *dirp" "long loc" 59.Ft void 60.Fn rewinddir "DIR *dirp" 61.Ft int 62.Fn closedir "DIR *dirp" 63.Ft int 64.Fn dirfd "DIR *dirp" 65.Sh DESCRIPTION 66The 67.Fn opendir 68function 69opens the directory named by 70.Fa filename , 71associates a 72.Em directory stream 73with it 74and 75returns a pointer to be used to identify the 76.Em directory stream 77in subsequent operations. 78The pointer 79.Dv NULL 80is returned if 81.Fa filename 82cannot be accessed, or if it cannot 83.Xr malloc 3 84enough memory to hold the whole thing. 85.Pp 86The 87.Fn readdir 88function 89returns a pointer to the next directory entry. 90It returns 91.Dv NULL 92upon reaching the end of the directory or detecting an invalid 93.Fn seekdir 94operation. 95.Pp 96The 97.Fn readdir_r 98function 99provides the same functionality as 100.Fn readdir , 101but the caller must provide a directory 102.Fa entry 103buffer to store the results in. If the read succeeds, 104.Fa result 105is pointed at the 106.Fa entry ; 107upon reaching the end of the directory 108.Fa result 109is set to 110.Dv NULL . 111The 112.Fn readdir_r 113function 114returns 0 on success or an error number to indicate failure. 115.Pp 116The 117.Fn telldir 118function 119returns the current location associated with the named 120.Em directory stream . 121.Pp 122The 123.Fn seekdir 124function 125sets the position of the next 126.Fn readdir 127operation on the 128.Em directory stream . 129The new position reverts to the one associated with the 130.Em directory stream 131when the 132.Fn telldir 133operation was performed. 134Values returned by 135.Fn telldir 136are good only for the lifetime of the 137.Dv DIR 138pointer, 139.Fa dirp , 140from which they are derived. 141If the directory is closed and then reopened, the 142.Fn telldir 143value cannot be re-used. 144.Pp 145The 146.Fn rewinddir 147function 148resets the position of the named 149.Em directory stream 150to the beginning of the directory. 151.Pp 152The 153.Fn closedir 154function 155closes the named 156.Em directory stream 157and frees the structure associated with the 158.Fa dirp 159pointer, 160returning 0 on success. 161On failure, \-1 is returned and the global variable 162.Va errno 163is set to indicate the error. 164.Pp 165The 166.Fn dirfd 167function 168returns the integer file descriptor associated with the named 169.Em directory stream , 170see 171.Xr open 2 . 172.Sh EXAMPLES 173Sample code which searches a directory for entry 174.Dq name 175is: 176.Bd -literal -offset indent 177len = strlen(name); 178dirp = opendir("."); 179if (dirp != NULL) { 180 while ((dp = readdir(dirp)) != NULL) 181 if (dp-\*[Gt]d_namlen == len \*[Am]\*[Am] 182 !strcmp(dp-\*[Gt]d_name, name)) { 183 (void)closedir(dirp); 184 return (FOUND); 185 } 186 (void)closedir(dirp); 187} 188return (NOT_FOUND); 189.Ed 190.Sh SEE ALSO 191.Xr close 2 , 192.Xr lseek 2 , 193.Xr open 2 , 194.Xr read 2 , 195.Xr dir 5 196.Sh STANDARDS 197The 198.Fn opendir , 199.Fn readdir , 200.Fn rewinddir 201and 202.Fn closedir 203functions conform to 204.St -p1003.1-90 . 205.Sh HISTORY 206The 207.Fn opendir , 208.Fn readdir , 209.Fn telldir , 210.Fn seekdir , 211.Fn rewinddir , 212.Fn closedir , 213and 214.Fn dirfd 215functions appeared in 216.Bx 4.2 . 217