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