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