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