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