Annotation of src/lib/libc/gen/directory.3, Revision 1.41
1.41 ! wiz 1: .\" $NetBSD: directory.3,v 1.40 2016/01/22 09:32:50 pgoyette Exp $
1.7 cgd 2: .\"
1.6 jtc 3: .\" Copyright (c) 1983, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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.
1.24 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 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: .\"
1.6 jtc 30: .\" @(#)directory.3 8.1 (Berkeley) 6/4/93
1.1 cgd 31: .\"
1.39 plunky 32: .Dd January 22, 2016
1.1 cgd 33: .Dt DIRECTORY 3
1.10 garbled 34: .Os
1.1 cgd 35: .Sh NAME
1.27 ad 36: .Nm fdopendir ,
1.1 cgd 37: .Nm opendir ,
38: .Nm readdir ,
1.21 christos 39: .Nm readdir_r ,
1.1 cgd 40: .Nm telldir ,
41: .Nm seekdir ,
42: .Nm rewinddir ,
43: .Nm closedir ,
44: .Nm dirfd
45: .Nd directory operations
1.9 perry 46: .Sh LIBRARY
47: .Lb libc
1.1 cgd 48: .Sh SYNOPSIS
1.20 wiz 49: .In dirent.h
1.1 cgd 50: .Ft DIR *
1.30 jruoho 51: .Fn opendir "const char *filename"
52: .Ft DIR *
1.27 ad 53: .Fn fdopendir "int fd"
1.4 jtc 54: .Ft struct dirent *
1.1 cgd 55: .Fn readdir "DIR *dirp"
1.21 christos 56: .Ft int
1.22 kleink 57: .Fn readdir_r "DIR * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict result"
1.1 cgd 58: .Ft long
1.25 christos 59: .Fn telldir "DIR *dirp"
1.1 cgd 60: .Ft void
1.38 njoly 61: .Fn seekdir "DIR *dirp" "long loc"
1.1 cgd 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
1.30 jruoho 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"
1.1 cgd 84: The
85: .Fn opendir
1.27 ad 86: function opens the directory named by
87: .Fa filename
1.30 jruoho 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
1.32 wiz 92: type is returned.
93: Otherwise,
1.30 jruoho 94: .Fn opendir
95: returns
96: .Dv NULL .
97: .It Fn fdopendir "fd"
1.27 ad 98: The
99: .Fn fdopendir
1.30 jruoho 100: function associates a directory stream with the directory file descriptor
1.27 ad 101: .Fa fd .
1.30 jruoho 102: The file offset associated with
1.27 ad 103: .Fa fd
1.30 jruoho 104: at the time of the call determines which entries are returned.
1.1 cgd 105: .Pp
1.30 jruoho 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 ,
1.31 jruoho 117: .Fn rewinddir ,
1.30 jruoho 118: the behavior is undefined.
119: The file descriptor can be closed by calling
120: .Fn closedir .
121: .It Fn readdir "dirp"
1.1 cgd 122: The
123: .Fn readdir
1.30 jruoho 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.
1.18 wiz 128: It returns
1.1 cgd 129: .Dv NULL
130: upon reaching the end of the directory or detecting an invalid
131: .Fn seekdir
132: operation.
1.30 jruoho 133: The returned structure is described in
1.35 jruoho 134: .Xr dirent 3 .
1.21 christos 135: .Pp
1.30 jruoho 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"
1.23 wiz 145: The
1.21 christos 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
1.28 wiz 152: buffer to store the results in.
153: If the read succeeds,
1.21 christos 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.
1.1 cgd 165: .Pp
1.30 jruoho 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"
1.1 cgd 177: The
178: .Fn telldir
1.30 jruoho 179: function returns the current location associated
180: with the directory stream specified by
181: .Fa dirp .
1.1 cgd 182: .Pp
1.30 jruoho 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"
1.1 cgd 193: The
194: .Fn seekdir
1.30 jruoho 195: function sets the position of the next
1.1 cgd 196: .Fn readdir
1.30 jruoho 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
1.1 cgd 207: .Fn telldir
1.18 wiz 208: operation was performed.
209: Values returned by
1.1 cgd 210: .Fn telldir
211: are good only for the lifetime of the
1.30 jruoho 212: .Vt DIR
1.1 cgd 213: pointer,
214: .Fa dirp ,
215: from which they are derived.
1.11 wiz 216: If the directory is closed and then reopened, the
1.1 cgd 217: .Fn telldir
1.26 christos 218: value cannot be re-used.
1.30 jruoho 219: .It Fn rewinddir "dirp"
1.1 cgd 220: The
221: .Fn rewinddir
1.30 jruoho 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.
1.1 cgd 228: .Pp
1.30 jruoho 229: If
230: .Fa dirp
231: does not refer to a valid directory stream, the behavior is undefined.
232: .It Fn closedir "dirp"
1.1 cgd 233: The
234: .Fn closedir
1.30 jruoho 235: function closes the directory stream
1.1 cgd 236: and frees the structure associated with the
237: .Fa dirp
238: pointer,
1.30 jruoho 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.
1.39 plunky 249: The returned file descriptor should not be closed by
250: .Xr close 2 ,
251: it will be released when
252: .Fa dirp
253: is closed with
254: .Fn closedir .
1.1 cgd 255: .Pp
1.30 jruoho 256: The rationale of
257: .Fn dirfd
258: is to provide a mechanism by which a file descriptor
259: can be obtained for the use of the
1.32 wiz 260: .Xr fchdir 2
1.30 jruoho 261: function.
262: .El
1.32 wiz 263: .Sh EXAMPLES
264: Sample code which searches a directory for entry
265: .Dq name
266: is:
267: .Bd -literal -offset indent
268: len = strlen(name);
269: dirp = opendir(".");
270: if (dirp != NULL) {
271: while ((dp = readdir(dirp)) != NULL)
1.41 ! wiz 272: if (dp->d_namlen == len &&
! 273: !strcmp(dp->d_name, name)) {
1.32 wiz 274: (void)closedir(dirp);
275: return (FOUND);
276: }
277: (void)closedir(dirp);
278: }
279: return (NOT_FOUND);
280: .Ed
1.30 jruoho 281: .Sh COMPATIBILITY
282: The described directory operations have traditionally been problematic
283: in terms of portability.
284: A good example is the semantics around
285: .Sq \&.
286: (dot) and
287: .Sq \&..
288: (dot-dot).
289: Based on historical implementations,
290: the rules about file descriptors apply to directory streams as well.
291: The
292: .St -p1003.1-2008
1.40 pgoyette 293: standard no longer mandates that directory streams be
294: implemented by using file descriptors.
1.30 jruoho 295: .Pp
296: The following additional remarks can be noted from the
297: .St -p1003.1-2008
298: standard.
299: .Bl -bullet -offset 2n
300: .It
301: If the type
302: .Vt DIR
303: is implemented using a file descriptor,
304: like in
305: .Nx ,
306: applications should be able to open only
307: .Dv OPEN_MAX
308: files and directories.
309: Otherwise the limit is left as unspecified.
310: .It
311: When a file descriptor is used to implement the directory stream, the
312: .Fn closedir
313: function behaves as if the
314: .Dv FD_CLOEXEC
315: had been set for the file descriptor.
316: In another words, it is mandatory that
317: .Fn closedir
318: deallocates the file descriptor.
319: .It
320: If directory streams are not implemented by using file descriptors,
321: functions such as
1.1 cgd 322: .Fn dirfd
1.30 jruoho 323: may fail with
324: .Er ENOTSUP .
325: .It
326: If a file is removed from or added to the directory
327: after the most recent call to
328: .Fn opendir
329: or
330: .Fn rewinddir ,
331: it is unspecified whether a subsequent call to
332: .Fn readdir
333: returns an entry for that file.
334: .It
335: When using the function
336: .Fn seekdir ,
337: note that if the value of
338: .Fa loc
339: was not obtained from an earlier call to
340: .Fn telldir ,
341: or if a call to
342: .Fn rewinddir
343: occurred between the calls to
344: .Fn telldir
345: and
346: .Fn seekdir ,
347: any subsequent call to
348: .Fn readdir
1.40 pgoyette 349: is unspecified, possibly resulting in undefined behavior.
1.30 jruoho 350: .It
351: After a call to
352: .Xr fork 2 ,
353: either the parent or child (but not both) can continue processing the
354: directory stream using
355: .Fn readdir ,
356: .Fn rewinddir ,
357: or
358: .Fn seekdir .
359: However, if both the parent and child processes use these functions,
360: the result is undefined.
361: .El
1.33 jruoho 362: .Sh ERRORS
363: .\"
364: .\" XXX: The errors should be enumerated.
365: .\"
1.34 jruoho 366: All described functions may set
1.33 jruoho 367: .Vt errno
368: to indicate the error.
1.1 cgd 369: .Sh SEE ALSO
1.12 wiz 370: .Xr close 2 ,
371: .Xr lseek 2 ,
1.1 cgd 372: .Xr open 2 ,
373: .Xr read 2 ,
1.36 njoly 374: .Xr dirent 3
1.8 kleink 375: .Sh STANDARDS
376: The
377: .Fn opendir ,
378: .Fn readdir ,
379: .Fn rewinddir
380: and
381: .Fn closedir
382: functions conform to
383: .St -p1003.1-90 .
1.32 wiz 384: The other functions conform to
1.30 jruoho 385: .St -p1003.1-2008 .
1.1 cgd 386: .Sh HISTORY
387: The
388: .Fn opendir ,
389: .Fn readdir ,
390: .Fn telldir ,
391: .Fn seekdir ,
392: .Fn rewinddir ,
393: .Fn closedir ,
394: and
395: .Fn dirfd
396: functions appeared in
397: .Bx 4.2 .
1.37 rmind 398: The
399: .Fn fdopendir
400: function appeared in
401: .Nx 6.0 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to directory.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen