1.\" $NetBSD: directory.3,v 1.18 2002/10/01 16:48:34 wiz 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 August 10, 2002 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 \*[Lt]dirent.h\*[Gt] 52.Ft DIR * 53.Fn opendir "const char *filename" 54.Ft struct dirent * 55.Fn readdir "DIR *dirp" 56.Ft long 57.Fn telldir "const DIR *dirp" 58.Ft void 59.Fn seekdir "DIR *dirp" "long loc" 60.Ft void 61.Fn rewinddir "DIR *dirp" 62.Ft int 63.Fn closedir "DIR *dirp" 64.Ft int 65.Fn dirfd "DIR *dirp" 66.Sh DESCRIPTION 67The 68.Fn opendir 69function 70opens the directory named by 71.Fa filename , 72associates a 73.Em directory stream 74with it 75and 76returns a pointer to be used to identify the 77.Em directory stream 78in subsequent operations. 79The 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. 91It returns 92.Dv NULL 93upon reaching the end of the directory or detecting an invalid 94.Fn seekdir 95operation. 96.Pp 97The 98.Fn telldir 99function 100returns the current location associated with the named 101.Em directory stream . 102.Pp 103The 104.Fn seekdir 105function 106sets the position of the next 107.Fn readdir 108operation on the 109.Em directory stream . 110The new position reverts to the one associated with the 111.Em directory stream 112when the 113.Fn telldir 114operation was performed. 115Values returned by 116.Fn telldir 117are good only for the lifetime of the 118.Dv DIR 119pointer, 120.Fa dirp , 121from which they are derived. 122If the directory is closed and then reopened, the 123.Fn telldir 124value may be invalidated due to undetected directory compaction. 125It is safe to use a previous 126.Fn telldir 127value immediately after a call to 128.Fn opendir 129and before any calls to 130.Fn readdir . 131.Pp 132The 133.Fn rewinddir 134function 135resets the position of the named 136.Em directory stream 137to the beginning of the directory. 138.Pp 139The 140.Fn closedir 141function 142closes the named 143.Em directory stream 144and frees the structure associated with the 145.Fa dirp 146pointer, 147returning 0 on success. 148On failure, \-1 is returned and the global variable 149.Va errno 150is set to indicate the error. 151.Pp 152The 153.Fn dirfd 154function 155returns the integer file descriptor associated with the named 156.Em directory stream , 157see 158.Xr open 2 . 159.Sh EXAMPLES 160Sample code which searches a directory for entry 161.Dq name 162is: 163.Bd -literal -offset indent 164len = strlen(name); 165dirp = opendir("."); 166if (dirp) { 167 while ((dp = readdir(dirp)) != NULL) 168 if (dp-\*[Gt]d_namlen == len \*[Am]\*[Am] !strcmp(dp-\*[Gt]d_name, name)) { 169 (void)closedir(dirp); 170 return (FOUND); 171 } 172 (void)closedir(dirp); 173} 174return (NOT_FOUND); 175.Ed 176.Sh SEE ALSO 177.Xr close 2 , 178.Xr lseek 2 , 179.Xr open 2 , 180.Xr read 2 , 181.Xr dir 5 182.Sh STANDARDS 183The 184.Fn opendir , 185.Fn readdir , 186.Fn rewinddir 187and 188.Fn closedir 189functions conform to 190.St -p1003.1-90 . 191.Sh HISTORY 192The 193.Fn opendir , 194.Fn readdir , 195.Fn telldir , 196.Fn seekdir , 197.Fn rewinddir , 198.Fn closedir , 199and 200.Fn dirfd 201functions appeared in 202.Bx 4.2 . 203