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.\" 3. 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.\" 30.Dd August 1, 2020 31.Dt DIRECTORY 3 32.Os 33.Sh NAME 34.Nm opendir , 35.Nm fdopendir , 36.Nm readdir , 37.Nm readdir_r , 38.Nm telldir , 39.Nm seekdir , 40.Nm rewinddir , 41.Nm closedir , 42.Nm fdclosedir , 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 DIR * 52.Fn fdopendir "int fd" 53.Ft struct dirent * 54.Fn readdir "DIR *dirp" 55.Ft int 56.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result" 57.Ft long 58.Fn telldir "DIR *dirp" 59.Ft void 60.Fn seekdir "DIR *dirp" "long loc" 61.Ft void 62.Fn rewinddir "DIR *dirp" 63.Ft int 64.Fn closedir "DIR *dirp" 65.Ft int 66.Fn fdclosedir "DIR *dirp" 67.Ft int 68.Fn dirfd "DIR *dirp" 69.Sh DESCRIPTION 70.Bf -symbolic 71The 72.Fn readdir_r 73interface is deprecated 74because it cannot be used correctly unless 75.Brq Va NAME_MAX 76is a fixed value. 77.Ef 78.Pp 79The 80.Fn opendir 81function 82opens the directory named by 83.Fa filename , 84associates a 85.Em directory stream 86with it 87and 88returns a pointer to be used to identify the 89.Em directory stream 90in subsequent operations. 91The pointer 92.Dv NULL 93is returned if 94.Fa filename 95cannot be accessed, or if it cannot 96.Xr malloc 3 97enough memory to hold the whole thing. 98.Pp 99The 100.Fn fdopendir 101function is equivalent to the 102.Fn opendir 103function except that the directory is specified by a file descriptor 104.Fa fd 105rather than by a name. 106The file offset associated with the file descriptor at the time of the call 107determines which entries are returned. 108.Pp 109Upon successful return from 110.Fn fdopendir , 111the file descriptor is under the control of the system, 112and if any attempt is made to close the file descriptor, 113or to modify the state of the associated description other than by means 114of 115.Fn closedir , 116.Fn readdir , 117.Fn readdir_r , 118or 119.Fn rewinddir , 120the behavior is undefined. 121Upon calling 122.Fn closedir 123the file descriptor is closed. 124The 125.Dv FD_CLOEXEC 126flag is set on the file descriptor by a successful call to 127.Fn fdopendir . 128.Pp 129The 130.Fn readdir 131function 132returns a pointer to the next directory entry. 133The directory entry remains valid until the next call to 134.Fn readdir 135or 136.Fn closedir 137on the same 138.Em directory stream . 139The function returns 140.Dv NULL 141upon reaching the end of the directory or on error. 142In the event of an error, 143.Va errno 144may be set to any of the values documented for the 145.Xr getdirentries 2 146system call. 147.Pp 148The 149.Fn readdir_r 150function 151provides the same functionality as 152.Fn readdir , 153but the caller must provide a directory 154.Fa entry 155buffer to store the results in. 156The buffer must be large enough for a 157.Vt struct dirent 158with a 159.Va d_name 160array with 161.Brq Va NAME_MAX 162+ 1 elements. 163If the read succeeds, 164.Fa result 165is pointed at the 166.Fa entry ; 167upon reaching the end of the directory 168.Fa result 169is set to 170.Dv NULL . 171The 172.Fn readdir_r 173function 174returns 0 on success or an error number to indicate failure. 175.Pp 176The 177.Fn telldir 178function 179returns a token representing the current location associated with the named 180.Em directory stream . 181Values returned by 182.Fn telldir 183are good only for the lifetime of the 184.Dv DIR 185pointer, 186.Fa dirp , 187from which they are derived. 188If the directory is closed and then 189reopened, prior values returned by 190.Fn telldir 191will no longer be valid. 192Values returned by 193.Fn telldir 194are also invalidated by a call to 195.Fn rewinddir . 196.Pp 197The 198.Fn seekdir 199function 200sets the position of the next 201.Fn readdir 202operation on the 203.Em directory stream . 204The new position reverts to the one associated with the 205.Em directory stream 206when the 207.Fn telldir 208operation was performed. 209.Pp 210The 211.Fn rewinddir 212function 213resets the position of the named 214.Em directory stream 215to the beginning of the directory. 216.Pp 217The 218.Fn closedir 219function 220closes the named 221.Em directory stream 222and frees the structure associated with the 223.Fa dirp 224pointer, 225returning 0 on success. 226On failure, \-1 is returned and the global variable 227.Va errno 228is set to indicate the error. 229.Pp 230The 231.Fn fdclosedir 232function is equivalent to the 233.Fn closedir 234function except that this function returns directory file descriptor instead of 235closing it. 236.Pp 237The 238.Fn dirfd 239function 240returns the integer file descriptor associated with the named 241.Em directory stream , 242see 243.Xr open 2 . 244.Sh EXAMPLES 245Sample code which searches a directory for entry ``name'' is: 246.Bd -literal -offset indent 247dirp = opendir("."); 248if (dirp == NULL) 249 return (ERROR); 250len = strlen(name); 251while ((dp = readdir(dirp)) != NULL) { 252 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) { 253 (void)closedir(dirp); 254 return (FOUND); 255 } 256} 257(void)closedir(dirp); 258return (NOT_FOUND); 259.Ed 260.Sh ERRORS 261The 262.Fn opendir 263function will fail if: 264.Bl -tag -width Er 265.It Bq Er EACCES 266Search permission is denied for the component of the path prefix of 267.Fa filename 268or read permission is denied for 269.Fa filename . 270.It Bq Er ELOOP 271A loop exists in symbolic links encountered during resolution of the 272.Fa filename 273argument. 274.It Bq Er ENAMETOOLONG 275The length of the 276.Fa filename 277argument exceeds 278.Brq Dv PATH_MAX 279or 280a pathname component is longer than 281.Brq Dv NAME_MAX . 282.It Bq Er ENOENT 283A component of 284.Fa filename 285does not name an existing directory or 286.Fa filename 287is an empty string. 288.It Bq Er ENOTDIR 289A component of 290.Fa filename 291is not a directory. 292.El 293.Pp 294The 295.Fn fdopendir 296function will fail if: 297.Bl -tag -width Er 298.It Bq Er EBADF 299The 300.Fa fd 301argument is not a valid file descriptor open for reading. 302.It Bq Er ENOTDIR 303The descriptor 304.Fa fd 305is not associated with a directory. 306.El 307.Pp 308The 309.Fn readdir 310and 311.Fn readdir_r 312functions may also fail and set 313.Va errno 314for any of the errors specified for the routine 315.Xr getdents 2 . 316.Pp 317The 318.Fn telldir 319function may also fail and set 320.Va errno 321for any of the errors specified for the routine 322.Xr realloc 3 . 323.Pp 324The 325.Fn closedir 326function may also fail and set 327.Va errno 328for any of the errors specified for the routine 329.Xr close 2 . 330.Sh SEE ALSO 331.Xr close 2 , 332.Xr lseek 2 , 333.Xr open 2 , 334.Xr read 2 , 335.Xr dir 5 336.Sh STANDARDS 337The 338.Fn closedir , 339.Fn dirfd , 340.Fn fdopendir , 341.Fn opendir , 342.Fn readdir , 343.Fn readdir_r , 344.Fn rewinddir , 345.Fn seekdir 346and 347.Fn telldir 348functions are expected to conform to 349.St -p1003.1-2008 . 350The 351.Fn fdclosedir 352function and the 353.Fa d_off , 354.Fa d_reclen 355and 356.Fa d_type 357fields of 358.Vt struct dirent 359are non-standard, and should not be used in portable programs. 360.Sh HISTORY 361The 362.Fn opendir , 363.Fn readdir , 364.Fn telldir , 365.Fn seekdir , 366.Fn rewinddir , 367.Fn closedir , 368and 369.Fn dirfd 370functions appeared in 371.Bx 4.2 . 372The 373.Fn fdopendir 374function appeared in 375.Fx 8.0 . 376.Fn fdclosedir 377function appeared in 378.Fx 10.0 . 379.Sh BUGS 380The behaviour of 381.Fn telldir 382and 383.Fn seekdir 384is likely to be wrong if there are parallel unlinks happening 385and the directory is larger than one page. 386There is code to ensure that a 387.Fn seekdir 388to the location given by a 389.Fn telldir 390immediately before the last 391.Fn readdir 392will always set the correct location to return the same value as that last 393.Fn readdir 394performed. 395This is enough for some applications which want to 396"push back the last entry read", e.g., Samba. 397Seeks back to any other location, 398other than the beginning of the directory, 399may result in unexpected behaviour if deletes are present. 400It is hoped that this situation will be resolved with changes to 401.Fn getdirentries 402and the VFS. 403