1 .\" $NetBSD: directory.3,v 1.38 2012/10/08 18:15:09 njoly Exp $
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
30 .\" @(#)directory.3 8.1 (Berkeley) 6/4/93
45 .Nd directory operations
51 .Fn opendir "const char *filename"
53 .Fn fdopendir "int fd"
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"
71 represents a directory stream;
72 an ordered sequence of all directory entries in a particular directory.
75 structure is similar to that of the
77 structure maintained by the
81 The following standard directory operations are defined.
83 .It Fn opendir "filename"
86 function opens the directory named by
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
100 function associates a directory stream with the directory file descriptor
102 The file offset associated with
104 at the time of the call determines which entries are returned.
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
118 the behavior is undefined.
119 The file descriptor can be closed by calling
121 .It Fn readdir "dirp"
124 function returns a pointer to the directory entry at the current position
125 in the directory stream specified by
127 and positions the directory stream at the next entry.
130 upon reaching the end of the directory or detecting an invalid
133 The returned structure is described in
136 The returned pointer to the
138 structure points to data which may be overwritten by another call to
140 on the same directory stream.
141 This data is not however overwritten by another call to
143 on a different directory stream.
144 .It Fn readdir_r "dirp" "entry" "result"
148 provides the same functionality as
150 but the caller must provide a directory
152 buffer to store the results in.
153 If the read succeeds,
157 upon reaching the end of the directory
164 returns 0 on success or an error number to indicate failure.
170 function may buffer several directory entries per actual read operation.
171 Both functions mark for update the
175 of the directory each time the directory is actually read.
176 .It Fn telldir "dirp"
179 function returns the current location associated
180 with the directory stream specified by
183 If the most recent operation on the particular directory stream was a
185 the directory position returned from
189 supplied as an argument to the
192 .It Fn seekdir "dirp" "loc"
195 function sets the position of the next
197 operation on the directory stream specified by
201 should come from a previous call to
203 using the same directory stream.
205 The new position reverts to the one associated
206 with the directory stream when the
208 operation was performed.
211 are good only for the lifetime of the
215 from which they are derived.
216 If the directory is closed and then reopened, the
218 value cannot be re-used.
219 .It Fn rewinddir "dirp"
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
227 would have been made.
231 does not refer to a valid directory stream, the behavior is undefined.
232 .It Fn closedir "dirp"
235 function closes the directory stream
236 and frees the structure associated with the
239 returning 0 on success and \-1 on failure.
243 function returns the integer file descriptor
244 associated with the directory stream specified by
249 The returned file descriptor should be closed by
256 is to provide a mechanism by which a file descriptor
257 can be obtained for the use of the
262 Sample code which searches a directory for entry
265 .Bd -literal -offset indent
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);
275 (void)closedir(dirp);
280 The described directory operations have traditionally been problematic
281 in terms of portability.
282 A good example is the semantics around
287 Based on historical implementations,
288 the rules about file descriptors apply to directory streams as well.
291 standard does not however any more mandate that directory streams
292 are necessarily implemented by using file descriptors.
294 The following additional remarks can be noted from the
297 .Bl -bullet -offset 2n
301 is implemented using a file descriptor,
304 applications should be able to open only
306 files and directories.
307 Otherwise the limit is left as unspecified.
309 When a file descriptor is used to implement the directory stream, the
311 function behaves as if the
313 had been set for the file descriptor.
314 In another words, it is mandatory that
316 deallocates the file descriptor.
318 If directory streams are not implemented by using file descriptors,
324 If a file is removed from or added to the directory
325 after the most recent call to
329 it is unspecified whether a subsequent call to
331 returns an entry for that file.
333 When using the function
335 note that if the value of
337 was not obtained from an earlier call to
341 occurred between the calls to
345 any subsequent call to
347 is unspecified, possibly resulting undefined behavior.
351 either the parent or child (but not both) can continue processing the
352 directory stream using
357 However, if both the parent and child processes use these functions,
358 the result is undefined.
362 .\" XXX: The errors should be enumerated.
364 All described functions may set
366 to indicate the error.
382 The other functions conform to
394 functions appeared in