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