1.\" $NetBSD: directory.3,v 1.10 1999/03/22 19:44:39 garbled Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd June 4, 1993 37.Dt DIRECTORY 3 38.Os 39.Sh NAME 40.Nm opendir , 41.Nm readdir , 42.Nm telldir , 43.Nm seekdir , 44.Nm rewinddir , 45.Nm closedir , 46.Nm dirfd 47.Nd directory operations 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.Fd #include <sys/types.h> 52.Fd #include <dirent.h> 53.Ft DIR * 54.Fn opendir "const char *filename" 55.Ft struct dirent * 56.Fn readdir "DIR *dirp" 57.Ft long 58.Fn telldir "const DIR *dirp" 59.Ft void 60.Fn seekdir "DIR *dirp" "long loc" 61.Ft void 62.Fn rewinddir "DIR *dirp" 63.Ft int 64.Fn closedir "DIR *dirp" 65.Ft int 66.Fn dirfd "DIR *dirp" 67.Sh DESCRIPTION 68The 69.Fn opendir 70function 71opens the directory named by 72.Fa filename , 73associates a 74.Em directory stream 75with it 76and 77returns a pointer to be used to identify the 78.Em directory stream 79in subsequent operations. The pointer 80.Dv NULL 81is returned if 82.Fa filename 83cannot be accessed, or if it cannot 84.Xr malloc 3 85enough memory to hold the whole thing. 86.Pp 87The 88.Fn readdir 89function 90returns a pointer to the next directory entry. It returns 91.Dv NULL 92upon reaching the end of the directory or detecting an invalid 93.Fn seekdir 94operation. 95.Pp 96The 97.Fn telldir 98function 99returns the current location associated with the named 100.Em directory stream . 101.Pp 102The 103.Fn seekdir 104function 105sets the position of the next 106.Fn readdir 107operation on the 108.Em directory stream . 109The new position reverts to the one associated with the 110.Em directory stream 111when the 112.Fn telldir 113operation was performed. Values returned by 114.Fn telldir 115are good only for the lifetime of the 116.Dv DIR 117pointer, 118.Fa dirp , 119from which they are derived. 120If the directory is closed and then reopened, the 121.Fn telldir 122value may be invalidated due to undetected directory compaction. 123It is safe to use a previous 124.Fn telldir 125value immediately after a call to 126.Fn opendir 127and before any calls to 128.Fn readdir . 129.Pp 130The 131.Fn rewinddir 132function 133resets the position of the named 134.Em directory stream 135to the beginning of the directory. 136.Pp 137The 138.Fn closedir 139function 140closes the named 141.Em directory stream 142and frees the structure associated with the 143.Fa dirp 144pointer, 145returning 0 on success. 146On failure, \-1 is returned and the global variable 147.Va errno 148is set to indicate the error. 149.Pp 150The 151.Fn dirfd 152function 153returns the integer file descriptor associated with the named 154.Em directory stream , 155see 156.Xr open 2 . 157.Pp 158Sample code which searchs a directory for entry ``name'' is: 159.Bd -literal -offset indent 160len = strlen(name); 161dirp = opendir("."); 162while ((dp = readdir(dirp)) != NULL) 163 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 164 (void)closedir(dirp); 165 return FOUND; 166 } 167(void)closedir(dirp); 168return NOT_FOUND; 169.Ed 170.Sh SEE ALSO 171.Xr open 2 , 172.Xr close 2 , 173.Xr read 2 , 174.Xr lseek 2 , 175.Xr dir 5 176.Sh STANDARDS 177The 178.Fn opendir , 179.Fn readdir , 180.Fn rewinddir 181and 182.Fn closedir 183functions conform to 184.St -p1003.1-90 . 185.Sh HISTORY 186The 187.Fn opendir , 188.Fn readdir , 189.Fn telldir , 190.Fn seekdir , 191.Fn rewinddir , 192.Fn closedir , 193and 194.Fn dirfd 195functions appeared in 196.Bx 4.2 . 197