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
13 readdir, readdir_r — read a directory
14
16 #include <dirent.h>
17 struct dirent *readdir(DIR *dirp);
19 int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
20 struct dirent **restrict result);
21
23 The type DIR, which is defined in the <dirent.h> header, represents a
24 directory stream, which is an ordered sequence of all the directory
25 entries in a particular directory. Directory entries represent files;
26 files may be removed from a directory or added to a directory asyn‐
27 chronously to the operation of readdir().
28 The readdir() function shall return a pointer to a structure represent‐
30 ing the directory entry at the current position in the directory stream
31 specified by the argument dirp, and position the directory stream at
32 the next entry. It shall return a null pointer upon reaching the end of
33 the directory stream. The structure dirent defined in the <dirent.h>
34 header describes a directory entry. The value of the structure's d_ino
35 member shall be set to the file serial number of the file named by the
36 d_name member. If the d_name member names a symbolic link, the value of
37 the d_ino member shall be set to the file serial number of the symbolic
38 link itself.
39 The readdir() function shall not return directory entries containing
41 empty names. If entries for dot or dot-dot exist, one entry shall be
42 returned for dot and one entry shall be returned for dot-dot; other‐
43 wise, they shall not be returned.
44 The application shall not modify the structure to which the return
46 value of readdir() points, nor any storage areas pointed to by pointers
47 within the structure. The returned pointer, and pointers within the
48 structure, might be invalidated or the structure or the storage areas
49 might be overwritten by a subsequent call to readdir() on the same
50 directory stream. They shall not be affected by a call to readdir() on
51 a different directory stream.
52 If a file is removed from or added to the directory after the most
54 recent call to opendir() or rewinddir(), whether a subsequent call to
55 readdir() returns an entry for that file is unspecified.
56 The readdir() function may buffer several directory entries per actual
58 read operation; readdir() shall mark for update the last data access
59 timestamp of the directory each time the directory is actually read.
60 After a call to fork(), either the parent or child (but not both) may
62 continue processing the directory stream using readdir(), rewinddir(),
63 or seekdir(). If both the parent and child processes use these func‐
64 tions, the result is undefined.
65 The readdir() function need not be thread-safe.
67 Applications wishing to check for error situations should set errno to
69 0 before calling readdir(). If errno is set to non-zero on return, an
70 error occurred.
71 The readdir_r() function shall initialize the dirent structure refer‐
73 enced by entry to represent the directory entry at the current position
74 in the directory stream referred to by dirp, store a pointer to this
75 structure at the location referenced by result, and position the direc‐
76 tory stream at the next entry.
77 The storage pointed to by entry shall be large enough for a dirent with
79 an array of char d_name members containing at least {NAME_MAX}+1 ele‐
80 ments.
81 Upon successful return, the pointer returned at *result shall have the
83 same value as the argument entry. Upon reaching the end of the direc‐
84 tory stream, this pointer shall have the value NULL.
85 The readdir_r() function shall not return directory entries containing
87 empty names.
88 If a file is removed from or added to the directory after the most
90 recent call to opendir() or rewinddir(), whether a subsequent call to
91 readdir_r() returns an entry for that file is unspecified.
92 The readdir_r() function may buffer several directory entries per
94 actual read operation; readdir_r() shall mark for update the last data
95 access timestamp of the directory each time the directory is actually
96 read.
97
99 Upon successful completion, readdir() shall return a pointer to an
100 object of type struct dirent. When an error is encountered, a null
101 pointer shall be returned and errno shall be set to indicate the error.
102 When the end of the directory is encountered, a null pointer shall be
103 returned and errno is not changed.
104 If successful, the readdir_r() function shall return zero; otherwise,
106 an error number shall be returned to indicate the error.
107
109 These functions shall fail if:
110 EOVERFLOW
112 One of the values in the structure to be returned cannot be rep‐
113 resented correctly.
114 These functions 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 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>
128 #include <errno.h>
129 #include <stdio.h>
130 #include <string.h>
131 static void lookup(const char *arg)
133 {
134 DIR *dirp;
135 struct dirent *dp;
136 if ((dirp = opendir(".")) == NULL) {
138 perror("couldn't open '.'");
139 return;
140 }
141 do {
143 errno = 0;
144 if ((dp = readdir(dirp)) != NULL) {
145 if (strcmp(dp->d_name, arg) != 0)
146 continue;
147 (void) printf("found %s\n", arg);
149 (void) closedir(dirp);
150 return;
151 }
153 } while (dp != NULL);
154 if (errno != 0)
156 perror("error reading directory");
157 else
158 (void) printf("failed to find %s\n", arg);
159 (void) closedir(dirp);
160 return;
161 }
162 int main(int argc, char *argv[])
164 {
165 int i;
166 for (i = 1; i < argc; i++)
167 lookup(argv[i]);
168 return (0);
169 }
170
172 The readdir() function should be used in conjunction with opendir(),
173 closedir(), and rewinddir() to examine the contents of the directory.
174 The readdir_r() function is thread-safe and shall return values in a
176 user-supplied buffer instead of possibly using a static data area that
177 may be overwritten by each call.
178
180 The returned value of readdir() merely represents a directory entry. No
181 equivalence should be inferred.
182 Historical implementations of readdir() obtain multiple directory
184 entries on a single read operation, which permits subsequent readdir()
185 operations to operate from the buffered information. Any wording that
186 required each successful readdir() operation to mark the directory last
187 data access timestamp for update would disallow such historical perfor‐
188 mance-oriented implementations.
189 When returning a directory entry for the root of a mounted file system,
191 some historical implementations of readdir() returned the file serial
192 number of the underlying mount point, rather than of the root of the
193 mounted file system. This behavior is considered to be a bug, since the
194 underlying file serial number has no significance to applications.
195 Since readdir() returns NULL when it detects an error and when the end
197 of the directory is encountered, an application that needs to tell the
198 difference must set errno to zero before the call and check it if NULL
199 is returned. Since the function must not change errno in the second
200 case and must set it to a non-zero value in the first case, a zero
201 errno after a call returning NULL indicates end-of-directory; other‐
202 wise, an error.
203 Routines to deal with this problem more directly were proposed:
205 int derror (dirp)
207 DIR *dirp;
208 void clearderr (dirp)
210 DIR *dirp;
211 The first would indicate whether an error had occurred, and the second
213 would clear the error indication. The simpler method involving errno
214 was adopted instead by requiring that readdir() not change errno when
215 end-of-directory is encountered.
216 An error or signal indicating that a directory has changed while open
218 was considered but rejected.
219 The thread-safe version of the directory reading function returns val‐
221 ues in a user-supplied buffer instead of possibly using a static data
222 area that may be overwritten by each call. Either the {NAME_MAX} com‐
223 pile-time constant or the corresponding pathconf() option can be used
224 to determine the maximum sizes of returned pathnames.
225
227 None.
228
230 closedir(), dirfd(), exec, fdopendir(), fstatat(), rewinddir(), sym‐
231 link()
232 The Base Definitions volume of POSIX.1‐2008, <dirent.h>, <sys_types.h>
234
236 Portions of this text are reprinted and reproduced in electronic form
237 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
238 -- Portable Operating System Interface (POSIX), The Open Group Base
239 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
240 cal and Electronics Engineers, Inc and The Open Group. (This is
241 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
242 event of any discrepancy between this version and the original IEEE and
243 The Open Group Standard, the original IEEE and The Open Group Standard
244 is the referee document. The original Standard can be obtained online
245 at http://www.unix.org/online.html .
246 Any typographical or formatting errors that appear in this page are
248 most likely to have been introduced during the conversion of the source
249 files to man page format. To report such errors, see https://www.ker‐
250 nel.org/doc/man-pages/reporting_bugs.html .
251IEEE/The Open Group 2013 READDIR(3P)