1READDIR(P) POSIX Programmer's Manual READDIR(P)
2
6 readdir, readdir_r - read a directory
7
9 #include <dirent.h>
10 struct dirent *readdir(DIR *dirp);
12 int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
15 struct dirent **restrict result);
16
19 The type DIR, which is defined in the <dirent.h> header, represents a
20 directory stream, which is an ordered sequence of all the directory
21 entries in a particular directory. Directory entries represent files;
22 files may be removed from a directory or added to a directory asyn‐
23 chronously to the operation of readdir().
24 The readdir() function shall return a pointer to a structure represent‐
26 ing the directory entry at the current position in the directory stream
27 specified by the argument dirp, and position the directory stream at
28 the next entry. It shall return a null pointer upon reaching the end of
29 the directory stream. The structure dirent defined in the <dirent.h>
30 header describes a directory entry.
31 The readdir() function shall not return directory entries containing
33 empty names. If entries for dot or dot-dot exist, one entry shall be
34 returned for dot and one entry shall be returned for dot-dot; other‐
35 wise, they shall not be returned.
36 The pointer returned by readdir() points to data which may be overwrit‐
38 ten by another call to readdir() on the same directory stream. This
39 data is not overwritten by another call to readdir() on a different
40 directory stream.
41 If a file is removed from or added to the directory after the most
43 recent call to opendir() or rewinddir(), whether a subsequent call to
44 readdir() returns an entry for that file is unspecified.
45 The readdir() function may buffer several directory entries per actual
47 read operation; readdir() shall mark for update the st_atime field of
48 the directory each time the directory is actually read.
49 After a call to fork(), either the parent or child (but not both) may
51 continue processing the directory stream using readdir(), rewinddir(),
52 or seekdir(). If both the parent and child processes use these func‐
53 tions, the result is undefined.
54 If the entry names a symbolic link, the value of the d_ino member is
56 unspecified.
57 The readdir() function need not be reentrant. A function that is not
59 required to be reentrant is not required to be thread-safe.
60 The readdir_r() function shall initialize the dirent structure refer‐
62 enced by entry to represent the directory entry at the current position
63 in the directory stream referred to by dirp, store a pointer to this
64 structure at the location referenced by result, and position the direc‐
65 tory stream at the next entry.
66 The storage pointed to by entry shall be large enough for a dirent with
68 an array of char d_name members containing at least {NAME_MAX}+1 ele‐
69 ments.
70 Upon successful return, the pointer returned at *result shall have the
72 same value as the argument entry. Upon reaching the end of the direc‐
73 tory stream, this pointer shall have the value NULL.
74 The readdir_r() function shall not return directory entries containing
76 empty names.
77 If a file is removed from or added to the directory after the most
79 recent call to opendir() or rewinddir(), whether a subsequent call to
80 readdir_r() returns an entry for that file is unspecified.
81 The readdir_r() function may buffer several directory entries per
83 actual read operation; the readdir_r() function shall mark for update
84 the st_atime field of the directory each time the directory is actually
85 read.
86 Applications wishing to check for error situations should set errno to
88 0 before calling readdir(). If errno is set to non-zero on return, an
89 error occurred.
90
92 Upon successful completion, readdir() shall return a pointer to an
93 object of type struct dirent. When an error is encountered, a null
94 pointer shall be returned and errno shall be set to indicate the error.
95 When the end of the directory is encountered, a null pointer shall be
96 returned and errno is not changed.
97 If successful, the readdir_r() function shall return zero; otherwise,
99 an error number shall be returned to indicate the error.
100
102 The readdir() function shall fail if:
103 EOVERFLOW
105 One of the values in the structure to be returned cannot be rep‐
106 resented correctly.
107 The readdir() function may fail if:
110 EBADF The dirp argument does not refer to an open directory stream.
112 ENOENT The current position of the directory stream is invalid.
114 The readdir_r() function may fail if:
117 EBADF The dirp argument does not refer to an open directory stream.
119 The following sections are informative.
122
124 The following sample program searches the current directory for each of
125 the arguments supplied on the command line.
126 #include <dirent.h>
129 #include <errno.h>
130 #include <stdio.h>
131 #include <string.h>
132 static void lookup(const char *arg)
135 {
136 DIR *dirp;
137 struct dirent *dp;
138 if ((dirp = opendir(".")) == NULL) {
141 perror("couldn't open '.'");
142 return;
143 }
144 do {
147 errno = 0;
148 if ((dp = readdir(dirp)) != NULL) {
149 if (strcmp(dp->d_name, arg) != 0)
150 continue;
151 (void) printf("found %s\n", arg);
154 (void) closedir(dirp);
155 return;
156 }
159 } while (dp != NULL);
160 if (errno != 0)
163 perror("error reading directory");
164 else
165 (void) printf("failed to find %s\n", arg);
166 (void) closedir(dirp);
167 return;
168 }
169 int main(int argc, char *argv[])
172 {
173 int i;
174 for (i = 1; i < argc; i++)
175 lookup(arvg[i]);
176 return (0);
177 }
178
180 The readdir() function should be used in conjunction with opendir(),
181 closedir(), and rewinddir() to examine the contents of the directory.
182 The readdir_r() function is thread-safe and shall return values in a
184 user-supplied buffer instead of possibly using a static data area that
185 may be overwritten by each call.
186
188 The returned value of readdir() merely represents a directory entry. No
189 equivalence should be inferred.
190 Historical implementations of readdir() obtain multiple directory
192 entries on a single read operation, which permits subsequent readdir()
193 operations to operate from the buffered information. Any wording that
194 required each successful readdir() operation to mark the directory
195 st_atime field for update would disallow such historical performance-
196 oriented implementations.
197 Since readdir() returns NULL when it detects an error and when the end
199 of the directory is encountered, an application that needs to tell the
200 difference must set errno to zero before the call and check it if NULL
201 is returned. Since the function must not change errno in the second
202 case and must set it to a non-zero value in the first case, a zero
203 errno after a call returning NULL indicates end-of-directory; other‐
204 wise, an error.
205 Routines to deal with this problem more directly were proposed:
207 int derror (dirp)
210 DIR *dirp;
211 void clearderr (dirp)
214 DIR *dirp;
215 The first would indicate whether an error had occurred, and the second
217 would clear the error indication. The simpler method involving errno
218 was adopted instead by requiring that readdir() not change errno when
219 end-of-directory is encountered.
220 An error or signal indicating that a directory has changed while open
222 was considered but rejected.
223 The thread-safe version of the directory reading function returns val‐
225 ues in a user-supplied buffer instead of possibly using a static data
226 area that may be overwritten by each call. Either the {NAME_MAX} com‐
227 pile-time constant or the corresponding pathconf() option can be used
228 to determine the maximum sizes of returned pathnames.
229
231 None.
232
234 closedir() , lstat() , opendir() , rewinddir() , symlink() , the Base
235 Definitions volume of IEEE Std 1003.1-2001, <dirent.h>, <sys/types.h>
236
238 Portions of this text are reprinted and reproduced in electronic form
239 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
240 -- Portable Operating System Interface (POSIX), The Open Group Base
241 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
242 Electrical and Electronics Engineers, Inc and The Open Group. In the
243 event of any discrepancy between this version and the original IEEE and
244 The Open Group Standard, the original IEEE and The Open Group Standard
245 is the referee document. The original Standard can be obtained online
246 at http://www.opengroup.org/unix/online.html .
247IEEE/The Open Group 2003 READDIR(P)