usr/src/boot: add .PARALLEL to makefiles
[unleashed.git] / lib / libc / readdir.3
blob58b495dcc223087ce35b21aaff1f4c97aac1a237
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
4 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
7 .\"  This notice shall appear on any product containing this material.
8 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
10 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
11 .Dd Dec 5, 2016
12 .Dt READDIR 3
13 .Os
15 .Sh NAME
17 .Nm readdir ,
18 .Nm readdir_r
19 .Nd read directory
21 .Sh SYNOPSIS
23 .In dirent.h
25 .Ft "struct dirent *"
26 .Fo readdir
27 .Fa "DIR *dirp"
28 .Fc
30 .Ft int
31 .Fo readdir_r
32 .Fa "DIR *restrict dirp"
33 .Fa "struct dirent **restrict result"
34 .Fc
36 .Sh DESCRIPTION
37 The type
38 .Vt DIR ,
39 which is defined in the header
40 .In dirent.h ,
41 represents
43 .Em directory stream ,
44 which is an ordered sequence of all the directory
45 entries in a particular directory.
46 Directory entries represent files.
47 Files can be removed from a directory or added to a directory asynchronously
48 to the operation of
49 .Fn readdir
50 and
51 .Fn readdir_r .
52 .Ss Fn readdir
53 The
54 .Fn readdir
55 function returns a pointer to a structure representing the directory entry at
56 the current position in the directory stream specified by the argument
57 .Fa dirp ,
58 and positions the directory stream at the next entry.
59 It returns a null pointer upon reaching the end of the directory stream.
60 The structure
61 .Vt dirent
62 defined by the
63 .In dirent.h
64 header describes a directory entry.
65 .Lp
66 The
67 .Fn readdir
68 function will not return directory entries containing empty names.
69 If entries for . (dot) or .. (dot-dot) exist, one entry will be returned
70 for dot and one entry will be returned for dot-dot; otherwise they will not be
71 returned.
72 .Lp
73 The pointer returned by
74 .Fn readdir
75 points to data that can be overwritten by another call to
76 .Fn readdir
77 on the same directory stream.
78 These data are not overwritten by another call to
79 .Fn readdir
80 on a different directory stream.
81 .Lp
82 If a file is removed from or added to the directory after the most recent call
84 .Xr opendir 3C
86 .Xr rewinddir 3C ,
87 whether a subsequent call to
88 .Fn readdir
89 returns an entry for that file is unspecified.
90 .Lp
91 The
92 .Fn readdir
93 function can buffer several directory entries per actual read operation.
94 It marks for update the
95 .Vt st_atime
96 field of the directory each time the directory is actually read.
97 .Lp
98 After a call to
99 .Xr fork 2 ,
100 either the parent or child (but not both) can
101 continue processing the directory stream using
102 .Fn readdir ,
103 .Xr rewinddir 3C
105 .Xr seekdir 3C .
106 If both the parent and child processes
107 use these functions, the result is undefined.
109 If the entry names a symbolic link, the value of the
110 .Vt d_ino
111 member is unspecified.
112 .Ss Fn readdir_r
113 Unless the end of the directory stream has been reached or an error occurred,
115 .Fn readdir_r
116 function initializes the
117 .Vt dirent
118 structure referenced by
119 .Fa entry
120 to represent the directory entry at the current
121 position in the directory stream referred to by
122 .Fa dirp ,
123 and positions the directory stream at the next entry.
125 The caller must allocate storage pointed to by
126 .Fa entry
127 to be large enough for a
128 .Vt dirent
129 structure with an array of
130 .Vt char Vn d_name
131 member containing at least
132 .Bro Dv NAME_MAX Brc Ns Li +1
133 elements.
136 .Fn readdir_r
137 function will not return directory entries containing empty names.
138 It is unspecified whether entries are returned for . (dot) or ..
139 (dot-dot).
141 If a file is removed from or added to the directory after the most recent call
143 .Xr opendir 3C
145 .Xr rewinddir 3C ,
146 whether a subsequent call to
147 .Fn readdir_r
148 returns an entry for that file is unspecified.
151 .Fn readdir_r
152 function can buffer several directory entries per actual read operation.
153 It marks for update the
154 .Vt st_atime
155 field of the directory each time the directory is actually read.
158 .Fn readdir_r
159 also sets the pointer pointed to by
160 .Fa result .
161 If a directory entry is returned,
162 the pointer will be set to the same value as the
163 .Fa entry
164 argument; otherwise, it will be set to
165 .Dv NULL .
167 .Sh RETURN VALUES
169 Upon successful completion,
170 .Fn readdir
171 function returns a pointer to an object of type
172 .Vt "struct dirent" .
173 When an error is encountered, a null pointer is returned and
174 .Va errno
175 is set to indicate the error.
176 When the end of the directory is encountered, a null pointer is returned
178 .Va errno
179 is not changed.
181 The readdir_r
182 function returns 0 if the end of the
183 directory is encountered or a directory entry is stored in the structure
184 referenced by
185 .Fa entry .
186 Otherwise, an error number is returned to indicate the failure.
188 .Sh EXAMPLES
190 .Ss Example 1 Search the current directory for an entry.
191 The following sample program will search the current directory for each of the
192 arguments supplied on the command line:
193 .Bd -literal -offset Ds
194 #include <sys/types.h>
195 #include <dirent.h>
196 #include <errno.h>
197 #include <stdio.h>
198 #include <strings.h>
200 static void lookup(const char *arg)
202         DIR *dirp;
203         struct dirent *dp;
205         if ((dirp = opendir(".")) == NULL) {
206                 perror("couldn't open '.'");
207                 return;
208         }
210         do {
211                 errno = 0;
212                 if ((dp = readdir(dirp)) != NULL) {
213                         if (strcmp(dp->d_name, arg) != 0)
214                                 continue;
216                         (void) printf("found %s\en", arg);
217                         (void) closedir(dirp);
218                         return;
219                 }
220         } while (dp != NULL);
222         if (errno != 0)
223                 perror("error reading directory");
224         else
225                 (void) printf("failed to find %s\en", arg);
226         (void) closedir(dirp);
227         return;
230 int main(int argc, char *argv[])
232         int i;
233         for (i = 1; i < argc; i++)
234                 lookup(argv[i]);
235         return (0);
239 .Sh ERRORS
242 .Fn readdir
244 .Fn readdir_r
245 functions will fail if:
246 .Bl -tag -width Er
247 .It Bq Er EOVERFLOW
248 One of the values in the structure to be returned cannot be represented
249 correctly.
253 .Fn readdir
255 .Fn readdir_r
256 functions may fail if:
257 .Bl -tag -width Er
258 .It Bq Er EBADF
260 .Fa dirp
261 argument does not refer to an open directory stream.
262 .It Bq Er ENOENT
263 The current position of the directory stream is invalid.
266 .Sh USAGE
269 .Fn readdir
271 .Fn readdir_r
272 functions should be used in
273 conjunction with
274 .Xr opendir 3C ,
275 .Xr closedir 3C , and
276 .Xr rewinddir 3C
277 to examine the contents of the directory.
278 Since
279 .Fn readdir
280 returns a null pointer both at the end of the directory and on error,
281 an application wanting to check for error situations should set
282 .Va errno
283 to 0 before calling this function.
285 .Va errno
286 is set to non-zero on return, an error occurred.
288 It is safe to use
289 .Fn readdir
290 in a threaded application, so long as only
291 one thread reads from the directory stream at any given time.
293 These functions have transitional interfaces for 64-bit file offsets.
295 .Xr lf64 5 .
297 .Sh SEE ALSO
298 .Xr fork 2 ,
299 .Xr lstat 2 ,
300 .Xr symlink 2 ,
301 .Xr Intro 3 ,
302 .Xr closedir 3C ,
303 .Xr opendir 3C ,
304 .Xr rewinddir 3C ,
305 .Xr scandir 3C ,
306 .Xr seekdir 3C ,
307 .Xr lf64 5
309 .Sh STANDARDS
310 .Fn readdir
312 .Fn readdir_r
313 conform to
314 .St -p1003.1-2008 .