1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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. 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.
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
28 .\" @(#)directory.3 8.1 (Berkeley) 6/4/93
29 .\" $FreeBSD: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $
44 .Nd directory operations
51 .Fn fdopendir "int fd"
53 .Fn opendir "const char *filename"
55 .Fn readdir "DIR *dirp"
57 .Fn readdir_r "DIR * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict result"
59 .Fn telldir "DIR *dirp"
61 .Fn seekdir "DIR *dirp" "long loc"
63 .Fn rewinddir "DIR *dirp"
65 .Fn closedir "DIR *dirp"
72 opens the directory named by
78 returns a pointer to be used to identify the
80 in subsequent operations. The pointer
84 cannot be accessed, or if it cannot
86 enough memory to hold the whole thing.
92 with the directory file descriptor
94 The file offset associated with
96 at the time of the call determines which entries are returned.
97 The file descriptor must not be used further by the caller in any way.
102 returns a pointer to the next directory entry. It returns
104 upon reaching the end of the directory or detecting an invalid
111 provides the same functionality as
113 but the caller must provide a directory
115 buffer to store the results in. If the read succeeds,
119 upon reaching the end of the directory
126 returns 0 on success or an error number to indicate failure.
131 returns the current location associated with the named
132 .Em directory stream .
135 are good only for the lifetime of the
139 from which they are derived. If the directory is closed and then
140 reopened, prior values returned by
142 will no longer be valid.
147 sets the position of the next
150 .Em directory stream .
151 The new position reverts to the one associated with the
155 operation was performed.
160 resets the position of the named
162 to the beginning of the directory.
169 and frees the structure associated with the
172 returning 0 on success.
173 On failure, \-1 is returned and the global variable
175 is set to indicate the error.
180 returns the integer file descriptor associated with the named
181 .Em directory stream ,
185 Sample code which searches a directory for entry ``name'' is:
186 .Bd -literal -offset indent
189 while ((dp = readdir(dirp)) != NULL)
190 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
191 (void)closedir(dirp);
194 (void)closedir(dirp);
213 functions appeared in