| blob | b7c55cf0e159f03c1e77fab3958e6f03ec1c89c3 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
45 .\"
46 .TH READDIR 3C "Jun 26, 2007"
47 .SH NAME
48 readdir, readdir_r \- read directory
49 .SH SYNOPSIS
50 .LP
51 .nf
52 #include <sys/types.h>
53 #include <dirent.h>
55 \fBstruct dirent *\fR\fBreaddir\fR(\fBDIR *\fR\fIdirp\fR);
56 .fi
58 .LP
59 .nf
60 \fBstruct dirent *\fR\fBreaddir_r\fR(\fBDIR *\fR\fIdirp\fR, \fBstruct dirent *\fR\fIentry\fR);
61 .fi
63 .SS "Standard conforming"
64 .LP
65 .nf
66 cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ]
68 \fBint\fR \fBreaddir_r\fR(\fBDIR *restrict\fR \fIdirp\fR, \fBstruct dirent *restrict\fR \fIentry\fR,
69 \fBstruct dirent **restrict\fR \fIresult\fR);
70 .fi
72 .SH DESCRIPTION
73 .sp
74 .LP
75 The type \fBDIR\fR, which is defined in the header <\fBdirent.h\fR>, represents
76 a \fIdirectory stream\fR, which is an ordered sequence of all the directory
77 entries in a particular directory. Directory entries represent files. Files can
78 be removed from a directory or added to a directory asynchronously to the
79 operation of \fBreaddir()\fR and \fBreaddir_r()\fR.
80 .SS "\fBreaddir()\fR"
81 .sp
82 .LP
83 The \fBreaddir()\fR function returns a pointer to a structure representing the
84 directory entry at the current position in the directory stream specified by
85 the argument \fIdirp\fR, and positions the directory stream at the next entry.
86 It returns a null pointer upon reaching the end of the directory stream. The
87 structure \fBdirent\fR defined by the \fB<dirent.h>\fR header describes a
88 directory entry.
89 .sp
90 .LP
91 The \fBreaddir()\fR function will not return directory entries containing empty
92 names. If entries for . (dot) or .. (dot-dot) exist, one entry will be returned
93 for dot and one entry will be returned for dot-dot; otherwise they will not be
94 returned.
95 .sp
96 .LP
97 The pointer returned by \fBreaddir()\fR points to data that can be overwritten
98 by another call to \fBreaddir()\fR on the same directory stream. These data are
99 not overwritten by another call to \fBreaddir()\fR on a different directory
100 stream.
101 .sp
102 .LP
103 If a file is removed from or added to the directory after the most recent call
104 to \fBopendir\fR(3C) or \fBrewinddir\fR(3C), whether a subsequent call to
105 \fBreaddir()\fR returns an entry for that file is unspecified.
106 .sp
107 .LP
108 The \fBreaddir()\fR function can buffer several directory entries per actual
109 read operation. It marks for update the \fBst_atime\fR field of the directory
110 each time the directory is actually read.
111 .sp
112 .LP
113 After a call to \fBfork\fR(2), either the parent or child (but not both) can
114 continue processing the directory stream using \fBreaddir()\fR,
115 \fBrewinddir()\fR or \fBseekdir\fR(3C). If both the parent and child processes
116 use these functions, the result is undefined.
117 .sp
118 .LP
119 If the entry names a symbolic link, the value of the \fBd_ino\fR member is
120 unspecified.
121 .SS "\fBreaddir_r()\fR"
122 .sp
123 .LP
124 Unless the end of the directory stream has been reached or an error occurred,
125 the \fBreaddir_r()\fR function initializes the \fBdirent\fR structure
126 referenced by \fBentry\fR to represent the directory entry at the current
127 position in the directory stream referred to by \fIdirp\fR, and positions the
128 directory stream at the next entry.
129 .sp
130 .LP
131 The caller must allocate storage pointed to by \fIentry\fR to be large enough
132 for a \fBdirent\fR structure with an array of \fBchar\fR \fBd_name\fR member
133 containing at least \fBNAME_MAX\fR (that is, \fBpathconf(directory,
134 _PC_NAME_MAX\fR)) plus one elements. (\fB_PC_NAME_MAX\fR is defined in
135 <\fBunistd.h\fR>.)
136 .sp
137 .LP
138 The \fBreaddir_r()\fR function will not return directory entries containing
139 empty names. It is unspecified whether entries are returned for . (dot) or ..
140 (dot-dot).
141 .sp
142 .LP
143 If a file is removed from or added to the directory after the most recent call
144 to \fBopendir()\fR or \fBrewinddir()\fR, whether a subsequent call to
145 \fBreaddir_r()\fR returns an entry for that file is unspecified.
146 .sp
147 .LP
148 The \fBreaddir_r()\fR function can buffer several directory entries per actual
149 read operation. It marks for update the \fBst_atime\fR field of the directory
150 each time the directory is actually read.
151 .sp
152 .LP
153 The standard-conforming version (see \fBstandards\fR(5)) of the
154 \fBreaddir_r()\fR function performs all of the actions described above and sets
155 the pointer pointed to by \fIresult\fR. If a directory entry is returned, the
156 pointer will be set to the same value as the \fIentry\fR argument; otherwise,
157 it will be set to \fINULL\fR.
158 .SH RETURN VALUES
159 .sp
160 .LP
161 Upon successful completion, \fBreaddir()\fR and the default \fBreaddir_r()\fR
162 return a pointer to an object of type \fBstruct dirent\fR. When an error is
163 encountered, a null pointer is returned and \fBerrno\fR is set to indicate the
164 error. When the end of the directory is encountered, a null pointer is returned
165 and \fBerrno\fR is not changed.
166 .sp
167 .LP
168 The standard-conforming \fBreaddir_r()\fR returns \fB0\fR if the end of the
169 directory is encountered or a directory entry is stored in the structure
170 referenced by \fIentry\fR. Otherwise, an error number is returned to indicate
171 the failure.
172 .SH ERRORS
173 .sp
174 .LP
175 The \fBreaddir()\fR and \fBreaddir_r()\fR functions will fail if:
176 .sp
177 .ne 2
178 .na
179 \fB\fBEOVERFLOW\fR\fR
180 .ad
181 .RS 13n
182 One of the values in the structure to be returned cannot be represented
183 correctly.
184 .RE
186 .sp
187 .LP
188 The \fBreaddir()\fR and \fBreaddir_r()\fR functions may fail if:
189 .sp
190 .ne 2
191 .na
192 \fB\fBEBADF\fR\fR
193 .ad
194 .RS 10n
195 The \fIdirp\fR argument does not refer to an open directory stream.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fBENOENT\fR\fR
202 .ad
203 .RS 10n
204 The current position of the directory stream is invalid.
205 .RE
207 .SH USAGE
208 .sp
209 .LP
210 The \fBreaddir()\fR and \fBreaddir_r()\fR functions should be used in
211 conjunction with \fBopendir()\fR, \fBclosedir()\fR, and \fBrewinddir()\fR to
212 examine the contents of the directory. Since \fBreaddir()\fR and the default
213 \fBreaddir_r()\fR return a null pointer both at the end of the directory and on
214 error, an application wanting to check for error situations should set
215 \fBerrno\fR to 0 before calling either of these functions. If \fBerrno\fR is
216 set to non-zero on return, an error occurred.
217 .sp
218 .LP
219 It is safe to use \fBreaddir()\fR in a threaded application, so long as only
220 one thread reads from the directory stream at any given time. The
221 \fBreaddir()\fR function is generally preferred over the \fBreaddir_r()\fR
222 function.
223 .sp
224 .LP
225 The standard-conforming \fBreaddir_r()\fR returns the error number if an error
226 occurred. It returns 0 on success (including reaching the end of the directory
227 stream).
228 .sp
229 .LP
230 The \fBreaddir()\fR and \fBreaddir_r()\fR functions have transitional
231 interfaces for 64-bit file offsets. See \fBlf64\fR(5).
232 .SH EXAMPLES
233 .LP
234 \fBExample 1 \fRSearch the current directory for the entry \fIname\fR.
235 .sp
236 .LP
237 The following sample program will search the current directory for each of the
238 arguments supplied on the command line:
240 .sp
241 .in +2
242 .nf
243 #include <sys/types.h>
244 #include <dirent.h>
245 #include <errno.h>
246 #include <stdio.h>
247 #include <strings.h>
249 static void lookup(const char *arg)
250 {
251 DIR *dirp;
252 struct dirent *dp;
254 if ((dirp = opendir(".")) == NULL) {
255 perror("couldn't open '.'");
256 return;
257 }
259 do {
260 errno = 0;
261 if ((dp = readdir(dirp)) != NULL) {
262 if (strcmp(dp->d_name, arg) != 0)
263 continue;
265 (void) printf("found %s\en", arg);
266 (void) closedir(dirp);
267 return;
268 }
269 } while (dp != NULL);
271 if (errno != 0)
272 perror("error reading directory");
273 else
274 (void) printf("failed to find %s\en", arg);
275 (void) closedir(dirp);
276 return;
277 }
279 int main(int argc, char *argv[])
280 {
281 int i;
282 for (i = 1; i < argc; i++)
283 lookup(argv[i]);
284 return (0);
285 }
286 .fi
287 .in -2
289 .SH ATTRIBUTES
290 .sp
291 .LP
292 See \fBattributes\fR(5) for descriptions of the following attributes:
293 .sp
295 .sp
296 .TS
297 box;
298 c | c
299 l | l .
300 ATTRIBUTE TYPE ATTRIBUTE VALUE
301 _
302 Interface Stability Standard
303 _
304 MT-Level See below.
305 .TE
307 .sp
308 .LP
309 The \fBreaddir()\fR function is Unsafe. The \fBreaddir_r()\fR function is Safe.
310 .SH SEE ALSO
311 .sp
312 .LP
313 \fBfork\fR(2), \fBlstat\fR(2), \fBsymlink\fR(2), \fBIntro\fR(3),
314 \fBclosedir\fR(3C), \fBopendir\fR(3C), \fBrewinddir\fR(3C), \fBscandir\fR(3C),
315 \fBseekdir\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)
316 .SH NOTES
317 .sp
318 .LP
319 When compiling multithreaded programs, see the \fBMULTITHREADED APPLICATIONS\fR
320 section of \fBIntro\fR(3).
321 .sp
322 .LP
323 Solaris 2.4 and earlier releases provided a \fBreaddir_r()\fR interface as
324 specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
325 interface as described above. Support for the Draft 6 interface is provided for
326 compatibility only and might not be supported in future releases. New
327 applications and libraries should use the standard-conforming interface.
328 .sp
329 .LP
330 For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and
331 \fB_REENTRANT\fR flags are automatically turned on by defining the
332 \fB_POSIX_C_SOURCE\fR flag with a value >= 199506L.