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 July 5, 2012 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 dirfd 44.Nd directory operations 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In sys/types.h 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 *dirp" "struct dirent *entry" "struct dirent **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 70.Fn opendir 71function 72opens the directory named by 73.Fa filename , 74associates a 75.Em directory stream 76with it 77and 78returns a pointer to be used to identify the 79.Em directory stream 80in subsequent operations. 81The pointer 82.Dv NULL 83is returned if 84.Fa filename 85cannot be accessed, or if it cannot 86.Xr malloc 3 87enough memory to hold the whole thing. 88.Pp 89The 90.Fn fdopendir 91function is equivalent to the 92.Fn opendir 93function except that the directory is specified by a file descriptor 94.Fa fd 95rather than by a name. 96The file offset associated with the file descriptor at the time of the call 97determines which entries are returned. 98.Pp 99Upon successful return from 100.Fn fdopendir , 101the file descriptor is under the control of the system, 102and if any attempt is made to close the file descriptor, 103or to modify the state of the associated description other than by means 104of 105.Fn closedir , 106.Fn readdir , 107.Fn readdir_r , 108or 109.Fn rewinddir , 110the behavior is undefined. 111Upon calling 112.Fn closedir 113the file descriptor is closed. 114The 115.Dv FD_CLOEXEC 116flag is set on the file descriptor by a successful call to 117.Fn fdopendir . 118.Pp 119The 120.Fn readdir 121function 122returns a pointer to the next directory entry. 123It returns 124.Dv NULL 125upon reaching the end of the directory or on error. 126In the event of an error, 127.Va errno 128may be set to any of the values documented for the 129.Xr getdirentries 2 130system call. 131.Pp 132The 133.Fn readdir_r 134function 135provides the same functionality as 136.Fn readdir , 137but the caller must provide a directory 138.Fa entry 139buffer to store the results in. 140If the read succeeds, 141.Fa result 142is pointed at the 143.Fa entry ; 144upon reaching the end of the directory 145.Fa result 146is set to 147.Dv NULL . 148The 149.Fn readdir_r 150function 151returns 0 on success or an error number to indicate failure. 152.Pp 153The 154.Fn telldir 155function 156returns a token representing the current location associated with the named 157.Em directory stream . 158Values returned by 159.Fn telldir 160are good only for the lifetime of the 161.Dv DIR 162pointer, 163.Fa dirp , 164from which they are derived. 165If the directory is closed and then 166reopened, prior values returned by 167.Fn telldir 168will no longer be valid. 169.Pp 170The 171.Fn seekdir 172function 173sets the position of the next 174.Fn readdir 175operation on the 176.Em directory stream . 177The new position reverts to the one associated with the 178.Em directory stream 179when the 180.Fn telldir 181operation was performed. 182State associated with the token returned by 183.Fn telldir is freed when it is passed to 184.Fn seekdir . 185If you wish return to the same location again, 186then you must create a new token with another 187.Fn telldir 188call. 189.Pp 190The 191.Fn rewinddir 192function 193resets the position of the named 194.Em directory stream 195to the beginning of the directory. 196.Pp 197The 198.Fn closedir 199function 200closes the named 201.Em directory stream 202and frees the structure associated with the 203.Fa dirp 204pointer, 205returning 0 on success. 206On failure, \-1 is returned and the global variable 207.Va errno 208is set to indicate the error. 209.Pp 210The 211.Fn dirfd 212function 213returns the integer file descriptor associated with the named 214.Em directory stream , 215see 216.Xr open 2 . 217.Pp 218Sample code which searches a directory for entry ``name'' is: 219.Bd -literal -offset indent 220dirp = opendir("."); 221if (dirp == NULL) 222 return (ERROR); 223len = strlen(name); 224while ((dp = readdir(dirp)) != NULL) { 225 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) { 226 (void)closedir(dirp); 227 return (FOUND); 228 } 229} 230(void)closedir(dirp); 231return (NOT_FOUND); 232.Ed 233.Sh SEE ALSO 234.Xr close 2 , 235.Xr lseek 2 , 236.Xr open 2 , 237.Xr read 2 , 238.Xr dir 5 239.Sh HISTORY 240The 241.Fn opendir , 242.Fn readdir , 243.Fn telldir , 244.Fn seekdir , 245.Fn rewinddir , 246.Fn closedir , 247and 248.Fn dirfd 249functions appeared in 250.Bx 4.2 . 251The 252.Fn fdopendir 253function appeared in 254.Fx 8.0 . 255.Sh BUGS 256The invalidation of 257.Fn telldir 258tokens when calling 259.Fn seekdir 260is non-standard. 261