1.\" $NetBSD: directory.3,v 1.36 2010/12/17 19:20:42 njoly 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 June 4, 2010 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 227would have been made. 228.Pp 229If 230.Fa dirp 231does not refer to a valid directory stream, the behavior is undefined. 232.It Fn closedir "dirp" 233The 234.Fn closedir 235function closes the directory stream 236and frees the structure associated with the 237.Fa dirp 238pointer, 239returning 0 on success and \-1 on failure. 240.It Fn dirfd "dirp" 241The 242.Fn dirfd 243function returns the integer file descriptor 244associated with the directory stream specified by 245.Fa dirp . 246Upon failure, 247.Fn dirfd 248returns \-1. 249The returned file descriptor should be closed by 250.Fn closedir 251instead of 252.Xr close 2 . 253.Pp 254The rationale of 255.Fn dirfd 256is to provide a mechanism by which a file descriptor 257can be obtained for the use of the 258.Xr fchdir 2 259function. 260.El 261.Sh EXAMPLES 262Sample code which searches a directory for entry 263.Dq name 264is: 265.Bd -literal -offset indent 266len = strlen(name); 267dirp = opendir("."); 268if (dirp != NULL) { 269 while ((dp = readdir(dirp)) != NULL) 270 if (dp-\*[Gt]d_namlen == len \*[Am]\*[Am] 271 !strcmp(dp-\*[Gt]d_name, name)) { 272 (void)closedir(dirp); 273 return (FOUND); 274 } 275 (void)closedir(dirp); 276} 277return (NOT_FOUND); 278.Ed 279.Sh COMPATIBILITY 280The described directory operations have traditionally been problematic 281in terms of portability. 282A good example is the semantics around 283.Sq \&. 284(dot) and 285.Sq \&.. 286(dot-dot). 287Based on historical implementations, 288the rules about file descriptors apply to directory streams as well. 289The 290.St -p1003.1-2008 291standard does not however any more mandate that directory streams 292are necessarily implemented by using file descriptors. 293.Pp 294The following additional remarks can be noted from the 295.St -p1003.1-2008 296standard. 297.Bl -bullet -offset 2n 298.It 299If the type 300.Vt DIR 301is implemented using a file descriptor, 302like in 303.Nx , 304applications should be able to open only 305.Dv OPEN_MAX 306files and directories. 307Otherwise the limit is left as unspecified. 308.It 309When a file descriptor is used to implement the directory stream, the 310.Fn closedir 311function behaves as if the 312.Dv FD_CLOEXEC 313had been set for the file descriptor. 314In another words, it is mandatory that 315.Fn closedir 316deallocates the file descriptor. 317.It 318If directory streams are not implemented by using file descriptors, 319functions such as 320.Fn dirfd 321may fail with 322.Er ENOTSUP . 323.It 324If a file is removed from or added to the directory 325after the most recent call to 326.Fn opendir 327or 328.Fn rewinddir , 329it is unspecified whether a subsequent call to 330.Fn readdir 331returns an entry for that file. 332.It 333When using the function 334.Fn seekdir , 335note that if the value of 336.Fa loc 337was not obtained from an earlier call to 338.Fn telldir , 339or if a call to 340.Fn rewinddir 341occurred between the calls to 342.Fn telldir 343and 344.Fn seekdir , 345any subsequent call to 346.Fn readdir 347is unspecified, possibly resulting undefined behavior. 348.It 349After a call to 350.Xr fork 2 , 351either the parent or child (but not both) can continue processing the 352directory stream using 353.Fn readdir , 354.Fn rewinddir , 355or 356.Fn seekdir . 357However, if both the parent and child processes use these functions, 358the result is undefined. 359.El 360.Sh ERRORS 361.\" 362.\" XXX: The errors should be enumerated. 363.\" 364All described functions may set 365.Vt errno 366to indicate the error. 367.Sh SEE ALSO 368.Xr close 2 , 369.Xr lseek 2 , 370.Xr open 2 , 371.Xr read 2 , 372.Xr dirent 3 373.Sh STANDARDS 374The 375.Fn opendir , 376.Fn readdir , 377.Fn rewinddir 378and 379.Fn closedir 380functions conform to 381.St -p1003.1-90 . 382The other functions conform to 383.St -p1003.1-2008 . 384.Sh HISTORY 385The 386.Fn opendir , 387.Fn readdir , 388.Fn telldir , 389.Fn seekdir , 390.Fn rewinddir , 391.Fn closedir , 392and 393.Fn dirfd 394functions appeared in 395.Bx 4.2 . 396