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 . 97Values returned by 98.Fn telldir 99are good only for the lifetime of the 100.Dv DIR 101pointer, 102.Fa dirp , 103from which they are derived. If the directory is closed and then 104reopened, prior values returned by 105.Fn telldir 106will no longer be valid. 107.Pp 108The 109.Fn seekdir 110function 111sets the position of the next 112.Fn readdir 113operation on the 114.Em directory stream . 115The new position reverts to the one associated with the 116.Em directory stream 117when the 118.Fn telldir 119operation was performed. 120.Pp 121The 122.Fn rewinddir 123function 124resets the position of the named 125.Em directory stream 126to the beginning of the directory. 127.Pp 128The 129.Fn closedir 130function 131closes the named 132.Em directory stream 133and frees the structure associated with the 134.Fa dirp 135pointer, 136returning 0 on success. 137On failure, \-1 is returned and the global variable 138.Va errno 139is set to indicate the error. 140.Pp 141The 142.Fn dirfd 143function 144returns the integer file descriptor associated with the named 145.Em directory stream , 146see 147.Xr open 2 . 148.Pp 149Sample code which searches a directory for entry ``name'' is: 150.Bd -literal -offset indent 151len = strlen(name); 152dirp = opendir("."); 153while ((dp = readdir(dirp)) != NULL) 154 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 155 (void)closedir(dirp); 156 return FOUND; 157 } 158(void)closedir(dirp); 159return NOT_FOUND; 160.Ed 161.Sh SEE ALSO 162.Xr close 2 , 163.Xr lseek 2 , 164.Xr open 2 , 165.Xr read 2 , 166.Xr dir 5 167.Sh HISTORY 168The 169.Fn opendir , 170.Fn readdir , 171.Fn telldir , 172.Fn seekdir , 173.Fn rewinddir , 174.Fn closedir , 175and 176.Fn dirfd 177functions appeared in 178.Bx 4.2 . 179