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