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,
19 struct dirent **restrict result);
20
22 The type DIR, which is defined in the <dirent.h> header, represents a
23 directory stream, which is an ordered sequence of all the directory
24 entries in a particular directory. Directory entries represent files;
25 files may be removed from a directory or added to a directory asyn‐
26 chronously to the operation of readdir().
27 The readdir() function shall return a pointer to a structure represent‐
29 ing the directory entry at the current position in the directory stream
30 specified by the argument dirp, and position the directory stream at
31 the next entry. It shall return a null pointer upon reaching the end of
32 the directory stream. The structure dirent defined in the <dirent.h>
33 header describes a directory entry. The value of the structure's d_ino
34 member shall be set to the file serial number of the file named by the
35 d_name member. If the d_name member names a symbolic link, the value of
36 the d_ino member shall be set to the file serial number of the symbolic
37 link itself.
38 The readdir() function shall not return directory entries containing
40 empty names. If entries for dot or dot-dot exist, one entry shall be
41 returned for dot and one entry shall be returned for dot-dot; other‐
42 wise, they shall not be returned.
43 The application shall not modify the structure to which the return
45 value of readdir() points, nor any storage areas pointed to by pointers
46 within the structure. The returned pointer, and pointers within the
47 structure, might be invalidated or the structure or the storage areas
48 might be overwritten by a subsequent call to readdir() on the same
49 directory stream. They shall not be affected by a call to readdir() on
50 a different directory stream. The returned pointer, and pointers within
51 the structure, might also be invalidated if the calling thread is ter‐
52 minated.
53 If a file is removed from or added to the directory after the most
55 recent call to opendir() or rewinddir(), whether a subsequent call to
56 readdir() returns an entry for that file is unspecified.
57 The readdir() function may buffer several directory entries per actual
59 read operation; readdir() shall mark for update the last data access
60 timestamp of the directory each time the directory is actually read.
61 After a call to fork(), either the parent or child (but not both) may
63 continue processing the directory stream using readdir(), rewinddir(),
64 or seekdir(). If both the parent and child processes use these func‐
65 tions, the result is undefined.
66 The readdir() function need not be thread-safe.
68 Applications wishing to check for error situations should set errno to
70 0 before calling readdir(). If errno is set to non-zero on return, an
71 error occurred.
72 The readdir_r() function shall initialize the dirent structure refer‐
74 enced by entry to represent the directory entry at the current position
75 in the directory stream referred to by dirp, store a pointer to this
76 structure at the location referenced by result, and position the direc‐
77 tory stream at the next entry.
78 The storage pointed to by entry shall be large enough for a dirent with
80 an array of char d_name members containing at least {NAME_MAX}+1 ele‐
81 ments.
82 Upon successful return, the pointer returned at *result shall have the
84 same value as the argument entry. Upon reaching the end of the direc‐
85 tory stream, this pointer shall have the value NULL.
86 The readdir_r() function shall not return directory entries containing
88 empty names.
89 If a file is removed from or added to the directory after the most
91 recent call to opendir() or rewinddir(), whether a subsequent call to
92 readdir_r() returns an entry for that file is unspecified.
93 The readdir_r() function may buffer several directory entries per
95 actual read operation; readdir_r() shall mark for update the last data
96 access timestamp of the directory each time the directory is actually
97 read.
98
100 Upon successful completion, readdir() shall return a pointer to an
101 object of type struct dirent. When an error is encountered, a null
102 pointer shall be returned and errno shall be set to indicate the error.
103 When the end of the directory is encountered, a null pointer shall be
104 returned and errno is not changed.
105 If successful, the readdir_r() function shall return zero; otherwise,
107 an error number shall be returned to indicate the error.
108
110 These functions shall fail if:
111 EOVERFLOW
113 One of the values in the structure to be returned cannot be rep‐
114 resented correctly.
115 These functions may fail if:
117 EBADF The dirp argument does not refer to an open directory stream.
119 ENOENT The current position of the directory stream is invalid.
121 The following sections are informative.
123
125 The following sample program searches the current directory for each of
126 the arguments supplied on the command line.
127 #include <dirent.h>
130 #include <errno.h>
131 #include <stdio.h>
132 #include <string.h>
133 static void lookup(const char *arg)
135 {
136 DIR *dirp;
137 struct dirent *dp;
138 if ((dirp = opendir(".")) == NULL) {
140 perror("couldn't open '.'");
141 return;
142 }
143 do {
145 errno = 0;
146 if ((dp = readdir(dirp)) != NULL) {
147 if (strcmp(dp->d_name, arg) != 0)
148 continue;
149 (void) printf("found %s\n", arg);
151 (void) closedir(dirp);
152 return;
153 }
155 } while (dp != NULL);
156 if (errno != 0)
158 perror("error reading directory");
159 else
160 (void) printf("failed to find %s\n", arg);
161 (void) closedir(dirp);
162 return;
163 }
164 int main(int argc, char *argv[])
166 {
167 int i;
168 for (i = 1; i < argc; i++)
169 lookup(argv[i]);
170 return (0);
171 }
172
174 The readdir() function should be used in conjunction with opendir(),
175 closedir(), and rewinddir() to examine the contents of the directory.
176 The readdir_r() function is thread-safe and shall return values in a
178 user-supplied buffer instead of possibly using a static data area that
179 may be overwritten by each call.
180
182 The returned value of readdir() merely represents a directory entry. No
183 equivalence should be inferred.
184 Historical implementations of readdir() obtain multiple directory
186 entries on a single read operation, which permits subsequent readdir()
187 operations to operate from the buffered information. Any wording that
188 required each successful readdir() operation to mark the directory last
189 data access timestamp for update would disallow such historical perfor‐
190 mance-oriented implementations.
191 When returning a directory entry for the root of a mounted file system,
193 some historical implementations of readdir() returned the file serial
194 number of the underlying mount point, rather than of the root of the
195 mounted file system. This behavior is considered to be a bug, since the
196 underlying file serial number has no significance to applications.
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)
213 DIR *dirp;
214 The first would indicate whether an error had occurred, and the second
216 would clear the error indication. The simpler method involving errno
217 was adopted instead by requiring that readdir() not change errno when
218 end-of-directory is encountered.
219 An error or signal indicating that a directory has changed while open
221 was considered but rejected.
222 The thread-safe version of the directory reading function returns val‐
224 ues in a user-supplied buffer instead of possibly using a static data
225 area that may be overwritten by each call. Either the {NAME_MAX} com‐
226 pile-time constant or the corresponding pathconf() option can be used
227 to determine the maximum sizes of returned pathnames.
228
230 None.
231
233 closedir(), dirfd(), exec, fdopendir(), fstatat(), rewinddir(), sym‐
234 link()
235 The Base Definitions volume of POSIX.1‐2017, <dirent.h>, <sys_types.h>
237
239 Portions of this text are reprinted and reproduced in electronic form
240 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
241 table Operating System Interface (POSIX), The Open Group Base Specifi‐
242 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
243 Electrical and Electronics Engineers, Inc and The Open Group. In the
244 event of any discrepancy between this version and the original IEEE and
245 The Open Group Standard, the original IEEE and The Open Group Standard
246 is the referee document. The original Standard can be obtained online
247 at http://www.opengroup.org/unix/online.html .
248 Any typographical or formatting errors that appear in this page are
250 most likely to have been introduced during the conversion of the source
251 files to man page format. To report such errors, see https://www.ker‐
252 nel.org/doc/man-pages/reporting_bugs.html .
253IEEE/The Open Group 2017 READDIR(3P)