1.\" $OpenBSD: opendir.3,v 1.1 2019/09/02 21:18:41 deraadt 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.Dd $Mdocdate: September 2 2019 $ 31.Dt OPENDIR 3 32.Os 33.Sh NAME 34.Nm opendir , 35.Nm fdopendir , 36.Nm readdir , 37.Nm readdir_r , 38.Nm telldir , 39.Nm seekdir , 40.Nm rewinddir , 41.Nm closedir , 42.Nm dirfd 43.Nd directory operations 44.Sh SYNOPSIS 45.In sys/types.h 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 "const 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 dirfd "DIR *dirp" 65.Sh DESCRIPTION 66The 67.Fn opendir 68function opens the directory named by 69.Fa filename , 70associates a directory stream with it, and returns a pointer to be used 71to identify the directory stream in subsequent operations. 72On failure, 73.Dv NULL 74is returned and 75.Va errno 76is set to indicate the error. 77.Pp 78The 79.Fn fdopendir 80function is equivalent to 81.Fn opendir 82except that the directory is specified by file descriptor rather than by name. 83The file offset associated with the file descriptor at the time of the call 84determines which entries are returned. 85.Pp 86Upon successful return from 87.Fn fdopendir , 88the file descriptor is under the control of the system, 89and if any attempt is made to close the file descriptor 90or to modify the state of the associated directory, 91other than by means of 92.Fn closedir , 93.Fn readdir , 94.Fn readdir_r , 95or 96.Fn rewinddir , 97the behavior is undefined. 98Upon calling 99.Fn closedir 100the file descriptor shall be closed. 101.Pp 102The 103.Fn readdir 104function returns a pointer to the next directory entry in the named 105directory stream 106.Fa dirp . 107It returns 108.Dv NULL 109upon reaching the end of the directory or detecting an invalid 110.Fn seekdir 111operation. 112.Pp 113The 114.Fn readdir_r 115function (much like 116.Fn readdir ) 117initializes the 118.Li dirent 119structure referenced by 120.Fa entry 121to represent the next directory entry in the named directory stream 122.Fa dirp , 123and stores a pointer to this structure at the location referenced by 124.Fa result . 125The storage pointed to by 126.Fa entry 127must be large enough for a dirent with a 128.Fa d_name 129array member containing at least 130.Dv NAME_MAX 131plus one elements. 132.Fn readdir_r 133returns 0 on success, or an error number if an error occurs; see 134.Sx ERRORS . 135On successful return, the pointer returned at 136.Fa "*result" 137will have the same value as the argument 138.Fa entry . 139Upon reaching the end of the directory stream, this pointer shall have the value 140.Dv NULL . 141.Pp 142The 143.Fn telldir 144function returns the current location associated with the named 145directory stream 146.Fa dirp . 147On failure, \-1 is returned and 148.Va errno 149is set to indicate the error. 150.Pp 151The 152.Fn seekdir 153function sets the position of the next 154.Fn readdir 155operation on the named directory stream 156.Fa dirp . 157The new position reverts to the one associated with the 158directory stream when the 159.Fn telldir 160operation was performed. 161Values returned by 162.Fn telldir 163are good only for the lifetime of the 164.Dv DIR 165pointer, 166.Fa dirp , 167from which they are derived. 168If the directory is closed and then reopened, the 169.Fn telldir 170value may be invalidated due to undetected directory compaction. 171.Pp 172The 173.Fn rewinddir 174function resets the position of the named directory stream 175.Fa dirp 176to the beginning of the directory. 177.Pp 178The 179.Fn closedir 180function closes the named directory stream and frees the structure 181associated with the 182.Fa dirp 183pointer, returning 0 on success. 184On failure, \-1 is returned and the global variable 185.Va errno 186is set to indicate the error. 187.Pp 188The 189.Fn dirfd 190function returns the integer file descriptor associated with the named 191directory stream 192.Fa dirp 193(see 194.Xr open 2 ) . 195.Sh EXAMPLES 196Sample code which searches a directory for entry 197.Dq name 198is: 199.Bd -literal -offset indent 200len = strlen(name); 201dirp = opendir("."); 202if (dirp) { 203 while ((dp = readdir(dirp)) != NULL) 204 if (dp->d_namlen == len && 205 !strcmp(dp->d_name, name)) { 206 closedir(dirp); 207 return FOUND; 208 } 209 closedir(dirp); 210} 211return NOT_FOUND; 212.Ed 213.Sh ERRORS 214The 215.Fn opendir 216function will fail if: 217.Bl -tag -width Er 218.It Bq Er ENOTDIR 219The supplied 220.Fa filename 221is not a directory. 222.El 223.Pp 224The 225.Fn opendir 226function may also fail and set 227.Va errno 228for any of the errors specified for the routines 229.Xr fcntl 2 , 230.Xr fstat 2 , 231.Xr open 2 , 232and 233.Xr malloc 3 . 234.Pp 235The 236.Fn fdopendir 237function will fail if: 238.Bl -tag -width Er 239.It Bq Er EBADF 240The 241.Fa fd 242argument is not a valid file descriptor open for reading. 243.It Bq Er ENOTDIR 244The descriptor 245.Fa fd 246is not associated with a directory. 247.El 248.Pp 249The 250.Fn readdir 251and 252.Fn readdir_r 253functions may also fail and set 254.Va errno 255for any of the errors specified for the routine 256.Xr getdents 2 . 257.Pp 258The 259.Fn telldir 260function may also fail and set 261.Va errno 262for any of the errors specified for the routine 263.Xr realloc 3 . 264.Pp 265The 266.Fn closedir 267function may also fail and set 268.Va errno 269for any of the errors specified for the routine 270.Xr close 2 . 271.Sh SEE ALSO 272.Xr close 2 , 273.Xr getdents 2 , 274.Xr lseek 2 , 275.Xr open 2 , 276.Xr dir 5 277.Sh STANDARDS 278The 279.Fn opendir , 280.Fn fdopendir , 281.Fn readdir , 282.Fn readdir_r , 283.Fn telldir , 284.Fn seekdir , 285.Fn rewinddir , 286.Fn closedir , 287and 288.Fn dirfd 289functions conform to 290.St -p1003.1-2008 . 291.Sh HISTORY 292The 293.Fn opendir , 294.Fn readdir , 295.Fn telldir , 296.Fn seekdir , 297.Fn rewinddir , 298.Fn closedir , 299and 300.Fn dirfd 301functions appeared in 302.Bx 4.2 . 303The 304.Fn fdopendir 305function appeared in 306.Ox 5.0 . 307