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 May 6, 2015 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 fdclosedir , 44.Nm dirfd 45.Nd directory operations 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In sys/types.h 50.In dirent.h 51.Ft DIR * 52.Fn opendir "const char *filename" 53.Ft DIR * 54.Fn fdopendir "int fd" 55.Ft struct dirent * 56.Fn readdir "DIR *dirp" 57.Ft int 58.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result" 59.Ft long 60.Fn telldir "DIR *dirp" 61.Ft void 62.Fn seekdir "DIR *dirp" "long loc" 63.Ft void 64.Fn rewinddir "DIR *dirp" 65.Ft int 66.Fn closedir "DIR *dirp" 67.Ft int 68.Fn fdclosedir "DIR *dirp" 69.Ft int 70.Fn dirfd "DIR *dirp" 71.Sh DESCRIPTION 72The 73.Fn opendir 74function 75opens the directory named by 76.Fa filename , 77associates a 78.Em directory stream 79with it 80and 81returns a pointer to be used to identify the 82.Em directory stream 83in subsequent operations. 84The pointer 85.Dv NULL 86is returned if 87.Fa filename 88cannot be accessed, or if it cannot 89.Xr malloc 3 90enough memory to hold the whole thing. 91.Pp 92The 93.Fn fdopendir 94function is equivalent to the 95.Fn opendir 96function except that the directory is specified by a file descriptor 97.Fa fd 98rather than by a name. 99The file offset associated with the file descriptor at the time of the call 100determines which entries are returned. 101.Pp 102Upon successful return from 103.Fn fdopendir , 104the file descriptor is under the control of the system, 105and if any attempt is made to close the file descriptor, 106or to modify the state of the associated description other than by means 107of 108.Fn closedir , 109.Fn readdir , 110.Fn readdir_r , 111or 112.Fn rewinddir , 113the behavior is undefined. 114Upon calling 115.Fn closedir 116the file descriptor is closed. 117The 118.Dv FD_CLOEXEC 119flag is set on the file descriptor by a successful call to 120.Fn fdopendir . 121.Pp 122The 123.Fn readdir 124function 125returns a pointer to the next directory entry. 126It returns 127.Dv NULL 128upon reaching the end of the directory or on error. 129In the event of an error, 130.Va errno 131may be set to any of the values documented for the 132.Xr getdirentries 2 133system call. 134.Pp 135The 136.Fn readdir_r 137function 138provides the same functionality as 139.Fn readdir , 140but the caller must provide a directory 141.Fa entry 142buffer to store the results in. 143If the read succeeds, 144.Fa result 145is pointed at the 146.Fa entry ; 147upon reaching the end of the directory 148.Fa result 149is set to 150.Dv NULL . 151The 152.Fn readdir_r 153function 154returns 0 on success or an error number to indicate failure. 155.Pp 156The 157.Fn telldir 158function 159returns a token representing the current location associated with the named 160.Em directory stream . 161Values returned by 162.Fn telldir 163are good only for the lifetime of the 164.Dv DIR 165pointer, 166.Fa dirp , 167from which they are derived. 168If the directory is closed and then 169reopened, prior values returned by 170.Fn telldir 171will no longer be valid. 172Values returned by 173.Fn telldir 174are also invalidated by a call to 175.Fn rewinddir . 176.Pp 177The 178.Fn seekdir 179function 180sets the position of the next 181.Fn readdir 182operation on the 183.Em directory stream . 184The new position reverts to the one associated with the 185.Em directory stream 186when the 187.Fn telldir 188operation was performed. 189.Pp 190The 191.Fn rewinddir 192function 193resets the position of the named 194.Em directory stream 195to the beginning of the directory. 196.Pp 197The 198.Fn closedir 199function 200closes the named 201.Em directory stream 202and frees the structure associated with the 203.Fa dirp 204pointer, 205returning 0 on success. 206On failure, \-1 is returned and the global variable 207.Va errno 208is set to indicate the error. 209.Pp 210The 211.Fn fdclosedir 212function is equivalent to the 213.Fn closedir 214function except that this function returns directory file descriptor instead of 215closing it. 216.Pp 217The 218.Fn dirfd 219function 220returns the integer file descriptor associated with the named 221.Em directory stream , 222see 223.Xr open 2 . 224.Pp 225Sample code which searches a directory for entry ``name'' is: 226.Bd -literal -offset indent 227dirp = opendir("."); 228if (dirp == NULL) 229 return (ERROR); 230len = strlen(name); 231while ((dp = readdir(dirp)) != NULL) { 232 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) { 233 (void)closedir(dirp); 234 return (FOUND); 235 } 236} 237(void)closedir(dirp); 238return (NOT_FOUND); 239.Ed 240.Sh SEE ALSO 241.Xr close 2 , 242.Xr lseek 2 , 243.Xr open 2 , 244.Xr read 2 , 245.Xr dir 5 246.Sh HISTORY 247The 248.Fn opendir , 249.Fn readdir , 250.Fn telldir , 251.Fn seekdir , 252.Fn rewinddir , 253.Fn closedir , 254and 255.Fn dirfd 256functions appeared in 257.Bx 4.2 . 258The 259.Fn fdopendir 260function appeared in 261.Fx 8.0 . 262.Fn fdclosedir 263function appeared in 264.Fx 10.0 . 265.Sh BUGS 266The behaviour of 267.Fn telldir 268and 269.Fn seekdir 270is likely to be wrong if there are parallel unlinks happening 271and the directory is larger than one page. 272There is code to ensure that a 273.Fn seekdir 274to the location given by a 275.Fn telldir 276immediately before the last 277.Fn readdir 278will always set the correct location to return the same value as that last 279.Fn readdir 280performed. 281This is enough for some applications which want to "push back the last entry read" E.g. Samba. 282Seeks back to any other location, 283other than the beginning of the directory, 284may result in unexpected behaviour if deletes are present. 285It is hoped that this situation will be resolved with changes to 286.Fn getdirentries 287and the VFS. 288