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