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.\" 3. 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: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $ 30.\" 31.Dd February 22, 2018 32.Dt DIRECTORY 3 33.Os 34.Sh NAME 35.Nm fdopendir , 36.Nm opendir , 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 fdopendir "int fd" 52.Ft DIR * 53.Fn opendir "const char *filename" 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 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. The pointer 81.Dv NULL 82is returned if 83.Fa filename 84cannot be accessed, or if it cannot 85.Xr malloc 3 86enough memory to hold the whole thing. 87.Pp 88The 89.Fn fdopendir 90function associates a 91.Em directory stream 92with the directory file descriptor 93.Fa fd . 94The file offset associated with 95.Fa fd 96at the time of the call determines which entries are returned. 97The file descriptor must not be used further by the caller in any way. 98.Pp 99The 100.Fn readdir 101function 102returns a pointer to the next directory entry. It returns 103.Dv NULL 104upon reaching the end of the directory or detecting an invalid 105.Fn seekdir 106operation. 107.Pp 108The 109.Fn readdir_r 110function 111provides the same functionality as 112.Fn readdir , 113but the caller must provide a directory 114.Fa entry 115buffer to store the results in. If the read succeeds, 116.Fa result 117is pointed at the 118.Fa entry ; 119upon reaching the end of the directory 120.Fa result 121is set to 122.Dv NULL . 123The 124.Fn readdir_r 125function 126returns 0 on success or an error number to indicate failure. 127.Pp 128The 129.Fn telldir 130function 131returns the current location associated with the named 132.Em directory stream . 133Values returned by 134.Fn telldir 135are good only for the lifetime of the 136.Dv DIR 137pointer, 138.Fa dirp , 139from which they are derived. If the directory is closed and then 140reopened, prior values returned by 141.Fn telldir 142will no longer be valid. 143.Pp 144The 145.Fn seekdir 146function 147sets the position of the next 148.Fn readdir 149operation on the 150.Em directory stream . 151The new position reverts to the one associated with the 152.Em directory stream 153when the 154.Fn telldir 155operation was performed. 156.Pp 157The 158.Fn rewinddir 159function 160resets the position of the named 161.Em directory stream 162to the beginning of the directory. 163.Pp 164The 165.Fn closedir 166function 167closes the named 168.Em directory stream 169and frees the structure associated with the 170.Fa dirp 171pointer, 172returning 0 on success. 173On failure, \-1 is returned and the global variable 174.Va errno 175is set to indicate the error. 176.Pp 177The 178.Fn dirfd 179function 180returns the integer file descriptor associated with the named 181.Em directory stream , 182see 183.Xr open 2 . 184.Pp 185Sample code which searches a directory for entry ``name'' is: 186.Bd -literal -offset indent 187len = strlen(name); 188dirp = opendir("."); 189while ((dp = readdir(dirp)) != NULL) 190 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 191 (void)closedir(dirp); 192 return FOUND; 193 } 194(void)closedir(dirp); 195return NOT_FOUND; 196.Ed 197.Sh SEE ALSO 198.Xr close 2 , 199.Xr lseek 2 , 200.Xr open 2 , 201.Xr read 2 , 202.Xr dir 5 203.Sh HISTORY 204The 205.Fn opendir , 206.Fn readdir , 207.Fn telldir , 208.Fn seekdir , 209.Fn rewinddir , 210.Fn closedir , 211and 212.Fn dirfd 213functions appeared in 214.Bx 4.2 . 215