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.\" 34.Dd June 4, 1993 35.Dt DIRECTORY 3 36.Os BSD 4.2 37.Sh NAME 38.Nm opendir , 39.Nm readdir , 40.Nm telldir , 41.Nm seekdir , 42.Nm rewinddir , 43.Nm closedir , 44.Nm dirfd 45.Nd directory operations 46.Sh SYNOPSIS 47.Fd #include <sys/types.h> 48.Fd #include <dirent.h> 49.Ft DIR * 50.Fn opendir "const char *filename" 51.Ft struct dirent * 52.Fn readdir "DIR *dirp" 53.Ft long 54.Fn telldir "const DIR *dirp" 55.Ft void 56.Fn seekdir "DIR *dirp" "long loc" 57.Ft void 58.Fn rewinddir "DIR *dirp" 59.Ft int 60.Fn closedir "DIR *dirp" 61.Ft int 62.Fn dirfd "DIR *dirp" 63.Sh DESCRIPTION 64The 65.Fn opendir 66function 67opens the directory named by 68.Fa filename , 69associates a 70.Em directory stream 71with it 72and 73returns a pointer to be used to identify the 74.Em directory stream 75in subsequent operations. The pointer 76.Dv NULL 77is returned if 78.Fa filename 79cannot be accessed, or if it cannot 80.Xr malloc 3 81enough memory to hold the whole thing. 82.Pp 83The 84.Fn readdir 85function 86returns a pointer to the next directory entry. It returns 87.Dv NULL 88upon reaching the end of the directory or detecting an invalid 89.Fn seekdir 90operation. 91.Pp 92The 93.Fn telldir 94function 95returns the current location associated with the named 96.Em directory stream . 97.Pp 98The 99.Fn seekdir 100function 101sets the position of the next 102.Fn readdir 103operation on the 104.Em directory stream . 105The new position reverts to the one associated with the 106.Em directory stream 107when the 108.Fn telldir 109operation was performed. Values returned by 110.Fn telldir 111are good only for the lifetime of the 112.Dv DIR 113pointer, 114.Fa dirp , 115from which they are derived. 116If the directory is closed and then reopened, the 117.Fn telldir 118value may be invalidated due to undetected directory compaction. 119It is safe to use a previous 120.Fn telldir 121value immediately after a call to 122.Fn opendir 123and before any calls to 124.Fn readdir . 125.Pp 126The 127.Fn rewinddir 128function 129resets the position of the named 130.Em directory stream 131to the beginning of the directory. 132.Pp 133The 134.Fn closedir 135function 136closes the named 137.Em directory stream 138and frees the structure associated with the 139.Fa dirp 140pointer, 141returning 0 on success. 142On failure, \-1 is returned and the global variable 143.Va errno 144is set to indicate the error. 145.Pp 146The 147.Fn dirfd 148function 149returns the integer file descriptor associated with the named 150.Em directory stream , 151see 152.Xr open 2 . 153.Pp 154Sample code which searches a directory for entry ``name'' is: 155.Bd -literal -offset indent 156len = strlen(name); 157dirp = opendir("."); 158while ((dp = readdir(dirp)) != NULL) 159 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 160 (void)closedir(dirp); 161 return FOUND; 162 } 163(void)closedir(dirp); 164return NOT_FOUND; 165.Ed 166.Sh SEE ALSO 167.Xr close 2 , 168.Xr lseek 2 , 169.Xr open 2 , 170.Xr read 2 , 171.Xr dir 5 172.Sh HISTORY 173The 174.Fn opendir , 175.Fn readdir , 176.Fn telldir , 177.Fn seekdir , 178.Fn rewinddir , 179.Fn closedir , 180and 181.Fn dirfd 182functions appeared in 183.Bx 4.2 . 184