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