1.\" $NetBSD: directory.3,v 1.24 2003/08/07 16:42:47 agc 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd May 28, 2003 33.Dt DIRECTORY 3 34.Os 35.Sh NAME 36.Nm opendir , 37.Nm readdir , 38.Nm readdir_r , 39.Nm telldir , 40.Nm seekdir , 41.Nm rewinddir , 42.Nm closedir , 43.Nm dirfd 44.Nd directory operations 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 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 * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict result" 55.Ft long 56.Fn telldir "const 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. If the read succeeds, 104.Fa result 105is pointed at the 106.Fa entry ; 107upon reaching the end of the directory 108.Fa result 109is set to 110.Dv NULL . 111The 112.Fn readdir_r 113function 114returns 0 on success or an error number to indicate failure. 115.Pp 116The 117.Fn telldir 118function 119returns the current location associated with the named 120.Em directory stream . 121.Pp 122The 123.Fn seekdir 124function 125sets the position of the next 126.Fn readdir 127operation on the 128.Em directory stream . 129The new position reverts to the one associated with the 130.Em directory stream 131when the 132.Fn telldir 133operation was performed. 134Values returned by 135.Fn telldir 136are good only for the lifetime of the 137.Dv DIR 138pointer, 139.Fa dirp , 140from which they are derived. 141If the directory is closed and then reopened, the 142.Fn telldir 143value may be invalidated due to undetected directory compaction. 144It is safe to use a previous 145.Fn telldir 146value immediately after a call to 147.Fn opendir 148and before any calls to 149.Fn readdir . 150.Pp 151The 152.Fn rewinddir 153function 154resets the position of the named 155.Em directory stream 156to the beginning of the directory. 157.Pp 158The 159.Fn closedir 160function 161closes the named 162.Em directory stream 163and frees the structure associated with the 164.Fa dirp 165pointer, 166returning 0 on success. 167On failure, \-1 is returned and the global variable 168.Va errno 169is set to indicate the error. 170.Pp 171The 172.Fn dirfd 173function 174returns the integer file descriptor associated with the named 175.Em directory stream , 176see 177.Xr open 2 . 178.Sh EXAMPLES 179Sample code which searches a directory for entry 180.Dq name 181is: 182.Bd -literal -offset indent 183len = strlen(name); 184dirp = opendir("."); 185if (dirp != NULL) { 186 while ((dp = readdir(dirp)) != NULL) 187 if (dp-\*[Gt]d_namlen == len \*[Am]\*[Am] 188 !strcmp(dp-\*[Gt]d_name, name)) { 189 (void)closedir(dirp); 190 return (FOUND); 191 } 192 (void)closedir(dirp); 193} 194return (NOT_FOUND); 195.Ed 196.Sh SEE ALSO 197.Xr close 2 , 198.Xr lseek 2 , 199.Xr open 2 , 200.Xr read 2 , 201.Xr dir 5 202.Sh STANDARDS 203The 204.Fn opendir , 205.Fn readdir , 206.Fn rewinddir 207and 208.Fn closedir 209functions conform to 210.St -p1003.1-90 . 211.Sh HISTORY 212The 213.Fn opendir , 214.Fn readdir , 215.Fn telldir , 216.Fn seekdir , 217.Fn rewinddir , 218.Fn closedir , 219and 220.Fn dirfd 221functions appeared in 222.Bx 4.2 . 223