1readdir(3C) Standard C Library Functions readdir(3C)
2
6 readdir, readdir_r - read directory
7
9 #include <sys/types.h>
10 #include <dirent.h>
11 struct dirent *readdir(DIR *dirp);
13 struct dirent *readdir_r(DIR *dirp, struct dirent *entry);
16 Standard conforming
19 cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
20 int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
22 struct dirent **restrict result);
23
26 The type DIR, which is defined in the header <dirent.h>, represents a
27 directory stream, which is an ordered sequence of all the directory
28 entries in a particular directory. Directory entries represent files.
29 Files can be removed from a directory or added to a directory asyn‐
30 chronously to the operation of readdir() and readdir_r().
31 readdir()
33 The readdir() function returns a pointer to a structure representing
34 the directory entry at the current position in the directory stream
35 specified by the argument dirp, and positions the directory stream at
36 the next entry. It returns a null pointer upon reaching the end of the
37 directory stream. The structure dirent defined by the <dirent.h> header
38 describes a directory entry.
39 The readdir() function will not return directory entries containing
42 empty names. If entries for . (dot) or .. (dot-dot) exist, one entry
43 will be returned for dot and one entry will be returned for dot-dot;
44 otherwise they will not be returned.
45 The pointer returned by readdir() points to data that can be overwrit‐
48 ten by another call to readdir() on the same directory stream. These
49 data are not overwritten by another call to readdir() on a different
50 directory stream.
51 If a file is removed from or added to the directory after the most
54 recent call to opendir(3C) or rewinddir(3C), whether a subsequent call
55 to readdir() returns an entry for that file is unspecified.
56 The readdir() function can buffer several directory entries per actual
59 read operation. It marks for update the st_atime field of the directory
60 each time the directory is actually read.
61 After a call to fork(2), either the parent or child (but not both) can
64 continue processing the directory stream using readdir(), rewinddir()
65 or seekdir(3C). If both the parent and child processes use these func‐
66 tions, the result is undefined.
67 If the entry names a symbolic link, the value of the d_ino member is
70 unspecified.
71 readdir_r()
73 Unless the end of the directory stream has been reached or an error
74 occurred, the readdir_r() function initializes the dirent structure
75 referenced by entry to represent the directory entry at the current
76 position in the directory stream referred to by dirp, and positions
77 the directory stream at the next entry.
78 The caller must allocate storage pointed to by entry to be large enough
81 for a dirent structure with an array of char d_name member containing
82 at least NAME_MAX (that is, pathconf(directory, _PC_NAME_MAX)) plus one
83 elements. (_PC_NAME_MAX is defined in <unistd.h>.)
84 The readdir_r() function will not return directory entries containing
87 empty names. It is unspecified whether entries are returned for . (dot)
88 or .. (dot-dot).
89 If a file is removed from or added to the directory after the most
92 recent call to opendir() or rewinddir(), whether a subsequent call to
93 readdir_r() returns an entry for that file is unspecified.
94 The readdir_r() function can buffer several directory entries per
97 actual read operation. It marks for update the st_atime field of the
98 directory each time the directory is actually read.
99 The standard-conforming version (see standards(5)) of the readdir_r()
102 function performs all of the actions described above and sets the
103 pointer pointed to by result. If a directory entry is returned, the
104 pointer will be set to the same value as the entry argument; otherwise,
105 it will be set to NULL.
106
108 Upon successful completion, readdir() and the default readdir_r()
109 return a pointer to an object of type struct dirent. When an error is
110 encountered, a null pointer is returned and errno is set to indicate
111 the error. When the end of the directory is encountered, a null pointer
112 is returned and errno is not changed.
113 The standard-conforming readdir_r() returns 0 if the end of the direc‐
116 tory is encountered or a directory entry is stored in the structure
117 referenced by entry. Otherwise, an error number is returned to indicate
118 the failure.
119
121 The readdir() and readdir_r() functions will fail if:
122 EOVERFLOW One of the values in the structure to be returned cannot
124 be represented correctly.
125 The readdir() and readdir_r() functions may fail if:
129 EBADF The dirp argument does not refer to an open directory stream.
131 ENOENT The current position of the directory stream is invalid.
134
137 The readdir() and readdir_r() functions should be used in conjunction
138 with opendir(), closedir(), and rewinddir() to examine the contents of
139 the directory. Since readdir() and the default readdir_r() return a
140 null pointer both at the end of the directory and on error, an applica‐
141 tion wanting to check for error situations should set errno to 0 before
142 calling either of these functions. If errno is set to non-zero on
143 return, an error occurred.
144 It is safe to use readdir() in a threaded application, so long as only
147 one thread reads from the directory stream at any given time. The read‐
148 dir() function is generally preferred over the readdir_r() function.
149 The standard-conforming readdir_r() returns the error number if an
152 error occurred. It returns 0 on success (including reaching the end of
153 the directory stream).
154 The readdir() and readdir_r() functions have transitional interfaces
157 for 64-bit file offsets. See lf64(5).
158
160 Example 1 Search the current directory for the entry name.
161 The following sample program will search the current directory for each
164 of the arguments supplied on the command line:
165 #include <sys/types.h>
168 #include <dirent.h>
169 #include <errno.h>
170 #include <stdio.h>
171 #include <strings.h>
172 static void lookup(const char *arg)
174 {
175 DIR *dirp;
176 struct dirent *dp;
177 if ((dirp = opendir(".")) == NULL) {
179 perror("couldn't open '.'");
180 return;
181 }
182 do {
184 errno = 0;
185 if ((dp = readdir(dirp)) != NULL) {
186 if (strcmp(dp->d_name, arg) != 0)
187 continue;
188 (void) printf("found %s\n", arg);
190 (void) closedir(dirp);
191 return;
192 }
193 } while (dp != NULL);
194 if (errno != 0)
196 perror("error reading directory");
197 else
198 (void) printf("failed to find %s\n", arg);
199 (void) closedir(dirp);
200 return;
201 }
202 int main(int argc, char *argv[])
204 {
205 int i;
206 for (i = 1; i < argc; i++)
207 lookup(argv[i]);
208 return (0);
209 }
210
213 See attributes(5) for descriptions of the following attributes:
214 ┌─────────────────────────────┬─────────────────────────────┐
219 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
220 ├─────────────────────────────┼─────────────────────────────┤
221 │Interface Stability │Standard │
222 ├─────────────────────────────┼─────────────────────────────┤
223 │MT-Level │See below. │
224 └─────────────────────────────┴─────────────────────────────┘
225 The readdir() function is Unsafe. The readdir_r() function is Safe.
228
230 fork(2), lstat(2), symlink(2), Intro(3), closedir(3C), opendir(3C),
231 rewinddir(3C), scandir(3C), seekdir(3C), attributes(5), lf64(5), stan‐
232 dards(5)
233
235 When compiling multithreaded programs, see the MULTITHREADED APPLICA‐
236 TIONS section of Intro(3).
237 Solaris 2.4 and earlier releases provided a readdir_r() interface as
240 specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
241 interface as described above. Support for the Draft 6 interface is pro‐
242 vided for compatibility only and might not be supported in future
243 releases. New applications and libraries should use the standard-con‐
244 forming interface.
245 For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
248 _REENTRANT flags are automatically turned on by defining the
249 _POSIX_C_SOURCE flag with a value >= 199506L.
250SunOS 5.11 26 Jun 2007 readdir(3C)