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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $ 34.\" $DragonFly: src/lib/libc/gen/directory.3,v 1.2 2003/06/17 04:26:42 dillon Exp $ 35.\" 36.Dd August 2, 2009 37.Dt DIRECTORY 3 38.Os 39.Sh NAME 40.Nm fdopendir , 41.Nm opendir , 42.Nm readdir , 43.Nm readdir_r , 44.Nm telldir , 45.Nm seekdir , 46.Nm rewinddir , 47.Nm closedir , 48.Nm dirfd 49.Nd directory operations 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.In sys/types.h 54.In dirent.h 55.Ft DIR * 56.Fn fdopendir "int fd" 57.Ft DIR * 58.Fn opendir "const char *filename" 59.Ft struct dirent * 60.Fn readdir "DIR *dirp" 61.Ft int 62.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result" 63.Ft long 64.Fn telldir "DIR *dirp" 65.Ft void 66.Fn seekdir "DIR *dirp" "long loc" 67.Ft void 68.Fn rewinddir "DIR *dirp" 69.Ft int 70.Fn closedir "DIR *dirp" 71.Ft int 72.Fn dirfd "DIR *dirp" 73.Sh DESCRIPTION 74The 75.Fn opendir 76function 77opens the directory named by 78.Fa filename , 79associates a 80.Em directory stream 81with it 82and 83returns a pointer to be used to identify the 84.Em directory stream 85in subsequent operations. The pointer 86.Dv NULL 87is returned if 88.Fa filename 89cannot be accessed, or if it cannot 90.Xr malloc 3 91enough memory to hold the whole thing. 92.Pp 93The 94.Fn fdopendir 95function associates a 96.Em directory stream 97with the directory file descriptor 98.Fa fd . 99The file offset associated with 100.Fa fd 101at the time of the call determines which entries are returned. 102The file descriptor must not be used further by the caller in any way. 103.Pp 104The 105.Fn readdir 106function 107returns a pointer to the next directory entry. It 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 116provides the same functionality as 117.Fn readdir , 118but the caller must provide a directory 119.Fa entry 120buffer to store the results in. If the read succeeds, 121.Fa result 122is pointed at the 123.Fa entry ; 124upon reaching the end of the directory 125.Fa result 126is set to 127.Dv NULL . 128The 129.Fn readdir_r 130function 131returns 0 on success or an error number to indicate failure. 132.Pp 133The 134.Fn telldir 135function 136returns the current location associated with the named 137.Em directory stream . 138Values returned by 139.Fn telldir 140are good only for the lifetime of the 141.Dv DIR 142pointer, 143.Fa dirp , 144from which they are derived. If the directory is closed and then 145reopened, prior values returned by 146.Fn telldir 147will no longer be valid. 148.Pp 149The 150.Fn seekdir 151function 152sets the position of the next 153.Fn readdir 154operation on the 155.Em directory stream . 156The new position reverts to the one associated with the 157.Em directory stream 158when the 159.Fn telldir 160operation was performed. 161.Pp 162The 163.Fn rewinddir 164function 165resets the position of the named 166.Em directory stream 167to the beginning of the directory. 168.Pp 169The 170.Fn closedir 171function 172closes the named 173.Em directory stream 174and frees the structure associated with the 175.Fa dirp 176pointer, 177returning 0 on success. 178On failure, \-1 is returned and the global variable 179.Va errno 180is set to indicate the error. 181.Pp 182The 183.Fn dirfd 184function 185returns the integer file descriptor associated with the named 186.Em directory stream , 187see 188.Xr open 2 . 189.Pp 190Sample code which searches a directory for entry ``name'' is: 191.Bd -literal -offset indent 192len = strlen(name); 193dirp = opendir("."); 194while ((dp = readdir(dirp)) != NULL) 195 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 196 (void)closedir(dirp); 197 return FOUND; 198 } 199(void)closedir(dirp); 200return NOT_FOUND; 201.Ed 202.Sh SEE ALSO 203.Xr close 2 , 204.Xr lseek 2 , 205.Xr open 2 , 206.Xr read 2 , 207.Xr dir 5 208.Sh HISTORY 209The 210.Fn opendir , 211.Fn readdir , 212.Fn telldir , 213.Fn seekdir , 214.Fn rewinddir , 215.Fn closedir , 216and 217.Fn dirfd 218functions appeared in 219.Bx 4.2 . 220