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.\" 4. 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.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 29.\" $FreeBSD$ 30.\" 31.Dd August 18, 2013 32.Dt DIRECTORY 3 33.Os 34.Sh NAME 35.Nm opendir , 36.Nm fdopendir , 37.Nm readdir , 38.Nm readdir_r , 39.Nm telldir , 40.Nm seekdir , 41.Nm rewinddir , 42.Nm closedir , 43.Nm fdclosedir , 44.Nm dirfd 45.Nd directory operations 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In sys/types.h 50.In dirent.h 51.Ft DIR * 52.Fn opendir "const char *filename" 53.Ft DIR * 54.Fn fdopendir "int fd" 55.Ft struct dirent * 56.Fn readdir "DIR *dirp" 57.Ft int 58.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result" 59.Ft long 60.Fn telldir "DIR *dirp" 61.Ft void 62.Fn seekdir "DIR *dirp" "long loc" 63.Ft void 64.Fn rewinddir "DIR *dirp" 65.Ft int 66.Fn closedir "DIR *dirp" 67.Ft int 68.Fn fdclosedir "DIR *dirp" 69.Ft int 70.Fn dirfd "DIR *dirp" 71.Sh DESCRIPTION 72The 73.Fn opendir 74function 75opens the directory named by 76.Fa filename , 77associates a 78.Em directory stream 79with it 80and 81returns a pointer to be used to identify the 82.Em directory stream 83in subsequent operations. 84The pointer 85.Dv NULL 86is returned if 87.Fa filename 88cannot be accessed, or if it cannot 89.Xr malloc 3 90enough memory to hold the whole thing. 91.Pp 92The 93.Fn fdopendir 94function is equivalent to the 95.Fn opendir 96function except that the directory is specified by a file descriptor 97.Fa fd 98rather than by a name. 99The file offset associated with the file descriptor at the time of the call 100determines which entries are returned. 101.Pp 102Upon successful return from 103.Fn fdopendir , 104the file descriptor is under the control of the system, 105and if any attempt is made to close the file descriptor, 106or to modify the state of the associated description other than by means 107of 108.Fn closedir , 109.Fn readdir , 110.Fn readdir_r , 111or 112.Fn rewinddir , 113the behavior is undefined. 114Upon calling 115.Fn closedir 116the file descriptor is closed. 117The 118.Dv FD_CLOEXEC 119flag is set on the file descriptor by a successful call to 120.Fn fdopendir . 121.Pp 122The 123.Fn readdir 124function 125returns a pointer to the next directory entry. 126It returns 127.Dv NULL 128upon reaching the end of the directory or on error. 129In the event of an error, 130.Va errno 131may be set to any of the values documented for the 132.Xr getdirentries 2 133system call. 134.Pp 135The 136.Fn readdir_r 137function 138provides the same functionality as 139.Fn readdir , 140but the caller must provide a directory 141.Fa entry 142buffer to store the results in. 143If the read succeeds, 144.Fa result 145is pointed at the 146.Fa entry ; 147upon reaching the end of the directory 148.Fa result 149is set to 150.Dv NULL . 151The 152.Fn readdir_r 153function 154returns 0 on success or an error number to indicate failure. 155.Pp 156The 157.Fn telldir 158function 159returns a token representing the current location associated with the named 160.Em directory stream . 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 169reopened, prior values returned by 170.Fn telldir 171will no longer be valid. 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. 185State associated with the token returned by 186.Fn telldir is freed when it is passed to 187.Fn seekdir . 188If you wish return to the same location again, 189then you must create a new token with another 190.Fn telldir 191call. 192.Pp 193The 194.Fn rewinddir 195function 196resets the position of the named 197.Em directory stream 198to the beginning of the directory. 199.Pp 200The 201.Fn closedir 202function 203closes the named 204.Em directory stream 205and frees the structure associated with the 206.Fa dirp 207pointer, 208returning 0 on success. 209On failure, \-1 is returned and the global variable 210.Va errno 211is set to indicate the error. 212.Pp 213The 214.Fn fdclosedir 215function is equivalent to the 216.Fn closedir 217function except that this function returns directory file descriptor instead of 218closing it. 219.Pp 220The 221.Fn dirfd 222function 223returns the integer file descriptor associated with the named 224.Em directory stream , 225see 226.Xr open 2 . 227.Pp 228Sample code which searches a directory for entry ``name'' is: 229.Bd -literal -offset indent 230dirp = opendir("."); 231if (dirp == NULL) 232 return (ERROR); 233len = strlen(name); 234while ((dp = readdir(dirp)) != NULL) { 235 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) { 236 (void)closedir(dirp); 237 return (FOUND); 238 } 239} 240(void)closedir(dirp); 241return (NOT_FOUND); 242.Ed 243.Sh SEE ALSO 244.Xr close 2 , 245.Xr lseek 2 , 246.Xr open 2 , 247.Xr read 2 , 248.Xr dir 5 249.Sh HISTORY 250The 251.Fn opendir , 252.Fn readdir , 253.Fn telldir , 254.Fn seekdir , 255.Fn rewinddir , 256.Fn closedir , 257and 258.Fn dirfd 259functions appeared in 260.Bx 4.2 . 261The 262.Fn fdopendir 263function appeared in 264.Fx 8.0 . 265.Fn fdclosedir 266function appeared in 267.Fx 10.0 . 268.Sh BUGS 269The invalidation of 270.Fn telldir 271tokens when calling 272.Fn seekdir 273is non-standard. 274