1.\" $OpenBSD: opendir.3,v 1.3 2024/03/23 16:30:01 guenther 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: March 23 2024 $ 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 is a deprecated variant of 116.Fn readdir . 117Like 118.Fn readdir , 119it initializes the 120.Vt dirent 121structure referenced by 122.Fa entry 123to represent the next directory entry in the named directory stream 124.Fa dirp , 125and stores a pointer to this structure at the location referenced by 126.Fa result . 127The storage pointed to by 128.Fa entry 129must be large enough for a dirent with a 130.Fa d_name 131array member containing at least 132.Dv NAME_MAX 133plus one elements. 134.Fn readdir_r 135returns 0 on success, or an error number if an error occurs; see 136.Sx ERRORS . 137On successful return, the pointer returned at 138.Fa "*result" 139will have the same value as the argument 140.Fa entry . 141Upon reaching the end of the directory stream, this pointer shall have the value 142.Dv NULL . 143.Pp 144The 145.Fn telldir 146function returns the current location associated with the named 147directory stream 148.Fa dirp . 149On failure, \-1 is returned and 150.Va errno 151is set to indicate the error. 152.Pp 153The 154.Fn seekdir 155function sets the position of the next 156.Fn readdir 157operation on the named directory stream 158.Fa dirp . 159The new position reverts to the one associated with the 160directory stream when the 161.Fn telldir 162operation was performed. 163Values returned by 164.Fn telldir 165are good only for the lifetime of the 166.Dv DIR 167pointer, 168.Fa dirp , 169from which they are derived. 170If the directory is closed and then reopened, the 171.Fn telldir 172value may be invalidated due to undetected directory compaction. 173.Pp 174The 175.Fn rewinddir 176function resets the position of the named directory stream 177.Fa dirp 178to the beginning of the directory. 179.Pp 180The 181.Fn closedir 182function closes the named directory stream and frees the structure 183associated with the 184.Fa dirp 185pointer, returning 0 on success. 186On failure, \-1 is returned and the global variable 187.Va errno 188is set to indicate the error. 189.Pp 190The 191.Fn dirfd 192function returns the integer file descriptor associated with the named 193directory stream 194.Fa dirp 195(see 196.Xr open 2 ) . 197.Sh EXAMPLES 198Sample code which searches a directory for entry 199.Dq name 200is: 201.Bd -literal -offset indent 202len = strlen(name); 203dirp = opendir("."); 204if (dirp) { 205 while ((dp = readdir(dirp)) != NULL) 206 if (dp->d_namlen == len && 207 !strcmp(dp->d_name, name)) { 208 closedir(dirp); 209 return FOUND; 210 } 211 closedir(dirp); 212} 213return NOT_FOUND; 214.Ed 215.Sh ERRORS 216The 217.Fn opendir 218function will fail if: 219.Bl -tag -width Er 220.It Bq Er ENOTDIR 221The supplied 222.Fa filename 223is not a directory. 224.El 225.Pp 226The 227.Fn opendir 228function may also fail and set 229.Va errno 230for any of the errors specified for the routines 231.Xr fcntl 2 , 232.Xr fstat 2 , 233.Xr open 2 , 234and 235.Xr malloc 3 . 236.Pp 237The 238.Fn fdopendir 239function will fail if: 240.Bl -tag -width Er 241.It Bq Er EBADF 242The 243.Fa fd 244argument is not a valid file descriptor open for reading. 245.It Bq Er ENOTDIR 246The descriptor 247.Fa fd 248is not associated with a directory. 249.El 250.Pp 251The 252.Fn readdir 253and 254.Fn readdir_r 255functions may also fail and set 256.Va errno 257for any of the errors specified for the routine 258.Xr getdents 2 . 259.Pp 260The 261.Fn telldir 262function may also fail and set 263.Va errno 264for any of the errors specified for the routine 265.Xr realloc 3 . 266.Pp 267The 268.Fn closedir 269function may also fail and set 270.Va errno 271for any of the errors specified for the routine 272.Xr close 2 . 273.Sh SEE ALSO 274.Xr close 2 , 275.Xr getdents 2 , 276.Xr lseek 2 , 277.Xr open 2 , 278.Xr dir 5 279.Sh STANDARDS 280The 281.Fn opendir , 282.Fn fdopendir , 283.Fn readdir , 284.Fn readdir_r , 285.Fn telldir , 286.Fn seekdir , 287.Fn rewinddir , 288.Fn closedir , 289and 290.Fn dirfd 291functions conform to 292.St -p1003.1-2008 . 293.Sh HISTORY 294The 295.Fn opendir , 296.Fn readdir , 297.Fn telldir , 298.Fn seekdir , 299.Fn rewinddir , 300.Fn closedir , 301and 302.Fn dirfd 303functions appeared in 304.Bx 4.2 . 305The 306.Fn fdopendir 307function appeared in 308.Ox 5.0 . 309.Sh CAVEATS 310The 311.Fn readdir_r 312function was intended to provide a thread-safe version of 313.Fn readdir . 314However, it was later found to be both unnecessary in the typical 315usage and unportable due to insufficient buffer sizing guidance. 316It was therefore officially deprecated in issue 8. 317