| blob | 432cf60aee8980281fb80cedf598509f2bbc7edd |
1 .\" $NetBSD: directory.3,v 1.36 2010/12/17 19:20:42 njoly 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 June 4, 2010
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 opendir "const char *filename"
52 .Ft DIR *
53 .Fn fdopendir "int fd"
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 type
70 .Vt DIR
71 represents a directory stream;
72 an ordered sequence of all directory entries in a particular directory.
73 The purpose of the
74 .Vt DIR
75 structure is similar to that of the
76 .Vt FILE
77 structure maintained by the
78 .Xr stdio 3
79 library functions.
80 .Sh FUNCTIONS
81 The following standard directory operations are defined.
82 .Bl -tag -width XXX
83 .It Fn opendir "filename"
84 The
85 .Fn opendir
86 function opens the directory named by
87 .Fa filename
88 and associates a directory stream with it.
89 The directory stream is positioned at the first entry.
90 Upon successful completion, a pointer to
91 .Vt DIR
92 type is returned.
93 Otherwise,
94 .Fn opendir
95 returns
96 .Dv NULL .
97 .It Fn fdopendir "fd"
98 The
99 .Fn fdopendir
100 function associates a directory stream with the directory file descriptor
101 .Fa fd .
102 The file offset associated with
103 .Fa fd
104 at the time of the call determines which entries are returned.
105 .Pp
106 Upon failure,
107 .Fn fdopendir
108 returns
109 .Dv NULL .
110 Otherwise the file descriptor is under the control of the system,
111 and if any attempt is made to close the file descriptor,
112 or to modify the state of the associated description,
113 other than by means of
114 .Fn closedir ,
115 .Fn readdir ,
116 .Fn readdir_r ,
117 .Fn rewinddir ,
118 the behavior is undefined.
119 The file descriptor can be closed by calling
120 .Fn closedir .
121 .It Fn readdir "dirp"
122 The
123 .Fn readdir
124 function returns a pointer to the directory entry at the current position
125 in the directory stream specified by
126 .Fa dirp ,
127 and positions the directory stream at the next entry.
128 It returns
129 .Dv NULL
130 upon reaching the end of the directory or detecting an invalid
131 .Fn seekdir
132 operation.
133 The returned structure is described in
134 .Xr dirent 3 .
135 .Pp
136 The returned pointer to the
137 .Em dirent
138 structure points to data which may be overwritten by another call to
139 .Fn readdir
140 on the same directory stream.
141 This data is not however overwritten by another call to
142 .Fn readdir
143 on a different directory stream.
144 .It Fn readdir_r "dirp" "entry" "result"
145 The
146 .Fn readdir_r
147 function
148 provides the same functionality as
149 .Fn readdir ,
150 but the caller must provide a directory
151 .Fa entry
152 buffer to store the results in.
153 If the read succeeds,
154 .Fa result
155 is pointed at the
156 .Fa entry ;
157 upon reaching the end of the directory
158 .Fa result
159 is set to
160 .Dv NULL .
161 The
162 .Fn readdir_r
163 function
164 returns 0 on success or an error number to indicate failure.
165 .Pp
166 Like
167 .Fn readdir ,
168 the
169 .Fn readdir_r
170 function may buffer several directory entries per actual read operation.
171 Both functions mark for update the
172 .Em st_atime
173 field (see
174 .Xr stat 2 )
175 of the directory each time the directory is actually read.
176 .It Fn telldir "dirp"
177 The
178 .Fn telldir
179 function returns the current location associated
180 with the directory stream specified by
181 .Fa dirp .
182 .Pp
183 If the most recent operation on the particular directory stream was a
184 .Fn seekdir ,
185 the directory position returned from
186 .Fn telldir
187 is the same as
188 .Fa loc
189 supplied as an argument to the
190 .Fn seekdir
191 call.
192 .It Fn seekdir "dirp" "loc"
193 The
194 .Fn seekdir
195 function sets the position of the next
196 .Fn readdir
197 operation on the directory stream specified by
198 .Fa dirp .
199 The value of
200 .Fa loc
201 should come from a previous call to
202 .Fn telldir
203 using the same directory stream.
204 .Pp
205 The new position reverts to the one associated
206 with the directory stream when the
207 .Fn telldir
208 operation was performed.
209 Values returned by
210 .Fn telldir
211 are good only for the lifetime of the
212 .Vt DIR
213 pointer,
214 .Fa dirp ,
215 from which they are derived.
216 If the directory is closed and then reopened, the
217 .Fn telldir
218 value cannot be re-used.
219 .It Fn rewinddir "dirp"
220 The
221 .Fn rewinddir
222 function resets the position of the named directory
223 stream to the beginning of the directory.
224 It also causes the directory stream to refer to the
225 current state of the corresponding directory, as if a call to
226 .Fn opendir
227 would have been made.
228 .Pp
229 If
230 .Fa dirp
231 does not refer to a valid directory stream, the behavior is undefined.
232 .It Fn closedir "dirp"
233 The
234 .Fn closedir
235 function closes the directory stream
236 and frees the structure associated with the
237 .Fa dirp
238 pointer,
239 returning 0 on success and \-1 on failure.
240 .It Fn dirfd "dirp"
241 The
242 .Fn dirfd
243 function returns the integer file descriptor
244 associated with the directory stream specified by
245 .Fa dirp .
246 Upon failure,
247 .Fn dirfd
248 returns \-1.
249 The returned file descriptor should be closed by
250 .Fn closedir
251 instead of
252 .Xr close 2 .
253 .Pp
254 The rationale of
255 .Fn dirfd
256 is to provide a mechanism by which a file descriptor
257 can be obtained for the use of the
258 .Xr fchdir 2
259 function.
260 .El
261 .Sh EXAMPLES
262 Sample code which searches a directory for entry
263 .Dq name
264 is:
265 .Bd -literal -offset indent
266 len = strlen(name);
267 dirp = opendir(".");
268 if (dirp != NULL) {
269 while ((dp = readdir(dirp)) != NULL)
270 if (dp-\*[Gt]d_namlen == len \*[Am]\*[Am]
271 !strcmp(dp-\*[Gt]d_name, name)) {
272 (void)closedir(dirp);
273 return (FOUND);
274 }
275 (void)closedir(dirp);
276 }
277 return (NOT_FOUND);
278 .Ed
279 .Sh COMPATIBILITY
280 The described directory operations have traditionally been problematic
281 in terms of portability.
282 A good example is the semantics around
283 .Sq \&.
284 (dot) and
285 .Sq \&..
286 (dot-dot).
287 Based on historical implementations,
288 the rules about file descriptors apply to directory streams as well.
289 The
290 .St -p1003.1-2008
291 standard does not however any more mandate that directory streams
292 are necessarily implemented by using file descriptors.
293 .Pp
294 The following additional remarks can be noted from the
295 .St -p1003.1-2008
296 standard.
297 .Bl -bullet -offset 2n
298 .It
299 If the type
300 .Vt DIR
301 is implemented using a file descriptor,
302 like in
303 .Nx ,
304 applications should be able to open only
305 .Dv OPEN_MAX
306 files and directories.
307 Otherwise the limit is left as unspecified.
308 .It
309 When a file descriptor is used to implement the directory stream, the
310 .Fn closedir
311 function behaves as if the
312 .Dv FD_CLOEXEC
313 had been set for the file descriptor.
314 In another words, it is mandatory that
315 .Fn closedir
316 deallocates the file descriptor.
317 .It
318 If directory streams are not implemented by using file descriptors,
319 functions such as
320 .Fn dirfd
321 may fail with
322 .Er ENOTSUP .
323 .It
324 If a file is removed from or added to the directory
325 after the most recent call to
326 .Fn opendir
327 or
328 .Fn rewinddir ,
329 it is unspecified whether a subsequent call to
330 .Fn readdir
331 returns an entry for that file.
332 .It
333 When using the function
334 .Fn seekdir ,
335 note that if the value of
336 .Fa loc
337 was not obtained from an earlier call to
338 .Fn telldir ,
339 or if a call to
340 .Fn rewinddir
341 occurred between the calls to
342 .Fn telldir
343 and
344 .Fn seekdir ,
345 any subsequent call to
346 .Fn readdir
347 is unspecified, possibly resulting undefined behavior.
348 .It
349 After a call to
350 .Xr fork 2 ,
351 either the parent or child (but not both) can continue processing the
352 directory stream using
353 .Fn readdir ,
354 .Fn rewinddir ,
355 or
356 .Fn seekdir .
357 However, if both the parent and child processes use these functions,
358 the result is undefined.
359 .El
360 .Sh ERRORS
361 .\"
362 .\" XXX: The errors should be enumerated.
363 .\"
364 All described functions may set
365 .Vt errno
366 to indicate the error.
367 .Sh SEE ALSO
368 .Xr close 2 ,
369 .Xr lseek 2 ,
370 .Xr open 2 ,
371 .Xr read 2 ,
372 .Xr dirent 3
373 .Sh STANDARDS
374 The
375 .Fn opendir ,
376 .Fn readdir ,
377 .Fn rewinddir
378 and
379 .Fn closedir
380 functions conform to
381 .St -p1003.1-90 .
382 The other functions conform to
383 .St -p1003.1-2008 .
384 .Sh HISTORY
385 The
386 .Fn opendir ,
387 .Fn readdir ,
388 .Fn telldir ,
389 .Fn seekdir ,
390 .Fn rewinddir ,
391 .Fn closedir ,
392 and
393 .Fn dirfd
394 functions appeared in
395 .Bx 4.2 .