1.\" $NetBSD: directory.3,v 1.43 2021/02/17 23:51:04 dholland Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd February 17, 2021 33.Dt DIRECTORY 3 34.Os 35.Sh NAME 36.Nm fdopendir , 37.Nm opendir , 38.Nm readdir , 39.Nm readdir_r , 40.Nm telldir , 41.Nm seekdir , 42.Nm rewinddir , 43.Nm closedir , 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 * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict 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 dirfd "DIR *dirp" 68.Sh DESCRIPTION 69The type 70.Vt DIR 71represents a directory stream; 72an ordered sequence of all directory entries in a particular directory. 73The purpose of the 74.Vt DIR 75structure is similar to that of the 76.Vt FILE 77structure maintained by the 78.Xr stdio 3 79library functions. 80.Sh FUNCTIONS 81The following standard directory operations are defined. 82.Bl -tag -width XXX 83.It Fn opendir "filename" 84The 85.Fn opendir 86function opens the directory named by 87.Fa filename 88and associates a directory stream with it. 89The directory stream is positioned at the first entry. 90Upon successful completion, a pointer to 91.Vt DIR 92type is returned. 93Otherwise, 94.Fn opendir 95returns 96.Dv NULL . 97.It Fn fdopendir "fd" 98The 99.Fn fdopendir 100function associates a directory stream with the directory file descriptor 101.Fa fd . 102The file offset associated with 103.Fa fd 104at the time of the call determines which entries are returned. 105.Pp 106Upon failure, 107.Fn fdopendir 108returns 109.Dv NULL . 110Otherwise the file descriptor is under the control of the system, 111and if any attempt is made to close the file descriptor, 112or to modify the state of the associated description, 113other than by means of 114.Fn closedir , 115.Fn readdir , 116.Fn readdir_r , 117.Fn rewinddir , 118the behavior is undefined. 119The file descriptor can be closed by calling 120.Fn closedir . 121.It Fn readdir "dirp" 122The 123.Fn readdir 124function returns a pointer to the directory entry at the current position 125in the directory stream specified by 126.Fa dirp , 127and positions the directory stream at the next entry. 128It returns 129.Dv NULL 130upon reaching the end of the directory or detecting an invalid 131.Fn seekdir 132operation. 133The returned structure is described in 134.Xr dirent 3 . 135.Pp 136The returned pointer to the 137.Em dirent 138structure points to data which may be overwritten by another call to 139.Fn readdir 140on the same directory stream. 141This data is not however overwritten by another call to 142.Fn readdir 143on a different directory stream. 144.It Fn readdir_r "dirp" "entry" "result" 145The 146.Fn readdir_r 147function 148provides the same functionality as 149.Fn readdir , 150but the caller must provide a directory 151.Fa entry 152buffer to store the results in. 153If the read succeeds, 154.Fa result 155is pointed at the 156.Fa entry ; 157upon reaching the end of the directory 158.Fa result 159is set to 160.Dv NULL . 161The 162.Fn readdir_r 163function 164returns 0 on success or an error number to indicate failure. 165.Pp 166Like 167.Fn readdir , 168the 169.Fn readdir_r 170function may buffer several directory entries per actual read operation. 171Both functions mark for update the 172.Em st_atime 173field (see 174.Xr stat 2 ) 175of the directory each time the directory is actually read. 176.It Fn telldir "dirp" 177The 178.Fn telldir 179function returns the current location associated 180with the directory stream specified by 181.Fa dirp . 182.Pp 183If the most recent operation on the particular directory stream was a 184.Fn seekdir , 185the directory position returned from 186.Fn telldir 187is the same as 188.Fa loc 189supplied as an argument to the 190.Fn seekdir 191call. 192.It Fn seekdir "dirp" "loc" 193The 194.Fn seekdir 195function sets the position of the next 196.Fn readdir 197operation on the directory stream specified by 198.Fa dirp . 199The value of 200.Fa loc 201should come from a previous call to 202.Fn telldir 203using the same directory stream. 204.Pp 205The new position reverts to the one associated 206with the directory stream when the 207.Fn telldir 208operation was performed. 209Values returned by 210.Fn telldir 211are good only for the lifetime of the 212.Vt DIR 213pointer, 214.Fa dirp , 215from which they are derived. 216If the directory is closed and then reopened, the 217.Fn telldir 218value cannot be re-used. 219.It Fn rewinddir "dirp" 220The 221.Fn rewinddir 222function resets the position of the named directory 223stream to the beginning of the directory. 224It also causes the directory stream to refer to the 225current state of the corresponding directory, as if a call to 226.Fn opendir 227was made. 228It is not specified whether this refers to the ``corresponding directory'' 229by name or by underlying object. 230(These can differ if 231.Xr rename 2 232has been used.) 233.\" Note: currently the underlying fd is reopened if and only if 234.\" __DTF_READALL is in effect, which is true for union mounts and 235.\" nfs; documenting that exactly seems inadvisable since it might 236.\" change. -- dholland 20210217 237.Pp 238If 239.Fa dirp 240does not refer to a valid directory stream, the behavior is undefined. 241.It Fn closedir "dirp" 242The 243.Fn closedir 244function closes the directory stream 245and frees the structure associated with the 246.Fa dirp 247pointer, 248returning 0 on success and \-1 on failure. 249.It Fn dirfd "dirp" 250The 251.Fn dirfd 252function returns the integer file descriptor 253associated with the directory stream specified by 254.Fa dirp . 255Upon failure, 256.Fn dirfd 257returns \-1. 258The returned file descriptor should not be closed by 259.Xr close 2 , 260it will be released when 261.Fa dirp 262is closed with 263.Fn closedir . 264.Pp 265The rationale of 266.Fn dirfd 267is to provide a mechanism by which a file descriptor 268can be obtained for the use of the 269.Xr fchdir 2 270function. 271.El 272.Sh EXAMPLES 273Sample code which searches a directory for entry 274.Dq name 275is: 276.Bd -literal -offset indent 277len = strlen(name); 278dirp = opendir("."); 279if (dirp != NULL) { 280 while ((dp = readdir(dirp)) != NULL) 281 if (dp->d_namlen == len && 282 !strcmp(dp->d_name, name)) { 283 (void)closedir(dirp); 284 return (FOUND); 285 } 286 (void)closedir(dirp); 287} 288return (NOT_FOUND); 289.Ed 290.Sh COMPATIBILITY 291The described directory operations have traditionally been problematic 292in terms of portability. 293A good example is the semantics of 294.Sq \&. 295(dot) and 296.Sq \&.. 297(dot-dot). 298Based on historical implementations, 299the rules about file descriptors apply to directory streams as well. 300The 301.St -p1003.1-2008 302standard no longer mandates that directory streams be 303implemented by using file descriptors. 304.Pp 305The following additional remarks can be noted from the 306.St -p1003.1-2008 307standard. 308.Bl -bullet -offset 2n 309.It 310If the type 311.Vt DIR 312is implemented using a file descriptor, 313like in 314.Nx , 315applications should be able to open only 316.Dv OPEN_MAX 317files and directories. 318Otherwise the limit is left as unspecified. 319.It 320When a file descriptor is used to implement the directory stream, the 321.Fn closedir 322function behaves as if the 323.Dv FD_CLOEXEC 324had been set for the file descriptor. 325In other words, it is mandatory that 326.Fn closedir 327deallocates the file descriptor. 328.It 329If directory streams are not implemented by using file descriptors, 330functions such as 331.Fn dirfd 332may fail with 333.Er ENOTSUP . 334.It 335If a file is removed from or added to the directory 336after the most recent call to 337.Fn opendir 338or 339.Fn rewinddir , 340it is unspecified whether a subsequent call to 341.Fn readdir 342returns an entry for that file. 343.It 344When using the function 345.Fn seekdir , 346note that if the value of 347.Fa loc 348was not obtained from an earlier call to 349.Fn telldir , 350or if a call to 351.Fn rewinddir 352occurred between the calls to 353.Fn telldir 354and 355.Fn seekdir , 356the results of any subsequent call to 357.Fn readdir 358are unspecified, possibly resulting in undefined behavior. 359.It 360After a call to 361.Xr fork 2 , 362either the parent or child (but not both) can continue processing the 363directory stream using 364.Fn readdir , 365.Fn rewinddir , 366or 367.Fn seekdir . 368However, if both the parent and child processes use these functions, 369the result is undefined. 370.El 371.Sh ERRORS 372.\" 373.\" XXX: The errors should be enumerated. 374.\" 375All described functions may set 376.Vt errno 377to indicate the error. 378.Sh SEE ALSO 379.Xr close 2 , 380.Xr lseek 2 , 381.Xr open 2 , 382.Xr read 2 , 383.Xr dirent 3 384.Sh STANDARDS 385The 386.Fn opendir , 387.Fn readdir , 388.Fn rewinddir 389and 390.Fn closedir 391functions conform to 392.St -p1003.1-90 . 393The other functions conform to 394.St -p1003.1-2008 . 395.Sh HISTORY 396The 397.Fn opendir , 398.Fn readdir , 399.Fn telldir , 400.Fn seekdir , 401.Fn rewinddir , 402.Fn closedir , 403and 404.Fn dirfd 405functions appeared in 406.Bx 4.2 . 407The 408.Fn fdopendir 409function appeared in 410.Nx 6.0 . 411