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