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