1readdir(3C)              Standard C Library Functions              readdir(3C)
2
3
4

NAME

6       readdir, readdir_r - read directory
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <dirent.h>
11
12       struct dirent *readdir(DIR *dirp);
13
14
15       struct dirent *readdir_r(DIR *dirp, struct dirent *entry);
16
17
18   Standard conforming
19       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
20
21       int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
22            struct dirent **restrict result);
23
24

DESCRIPTION

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
32   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
40
41       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
46
47       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
52
53       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
57
58       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
62
63       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
68
69       If  the  entry  names a symbolic link, the value of the d_ino member is
70       unspecified.
71
72   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
79
80       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
85
86       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
90
91       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
95
96       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
100
101       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

RETURN VALUES

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
114
115       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

ERRORS

121       The readdir() and readdir_r() functions will fail if:
122
123       EOVERFLOW    One of the values in the structure to be  returned  cannot
124                    be represented correctly.
125
126
127
128       The readdir() and readdir_r() functions may fail if:
129
130       EBADF     The dirp argument does not refer to an open directory stream.
131
132
133       ENOENT    The current position of the directory stream is invalid.
134
135

USAGE

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
145
146       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
150
151       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
155
156       The  readdir()  and  readdir_r() functions have transitional interfaces
157       for 64-bit file offsets.  See lf64(5).
158

EXAMPLES

160       Example 1 Search the current directory for the entry name.
161
162
163       The following sample program will search the current directory for each
164       of the arguments supplied on the command line:
165
166
167         #include <sys/types.h>
168         #include <dirent.h>
169         #include <errno.h>
170         #include <stdio.h>
171         #include <strings.h>
172
173         static void lookup(const char *arg)
174         {
175                 DIR *dirp;
176                 struct dirent *dp;
177
178                 if ((dirp = opendir(".")) == NULL) {
179                         perror("couldn't open '.'");
180                         return;
181                 }
182
183                 do {
184                         errno = 0;
185                         if ((dp = readdir(dirp)) != NULL) {
186                                 if (strcmp(dp->d_name, arg) != 0)
187                                         continue;
188
189                                 (void) printf("found %s\n", arg);
190                                 (void) closedir(dirp);
191                                 return;
192                         }
193                 } while (dp != NULL);
194
195                 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
203         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
211

ATTRIBUTES

213       See attributes(5) for descriptions of the following attributes:
214
215
216
217
218       ┌─────────────────────────────┬─────────────────────────────┐
219       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
220       ├─────────────────────────────┼─────────────────────────────┤
221       │Interface Stability          │Standard                     │
222       ├─────────────────────────────┼─────────────────────────────┤
223       │MT-Level                     │See below.                   │
224       └─────────────────────────────┴─────────────────────────────┘
225
226
227       The readdir() function is Unsafe. The readdir_r() function is Safe.
228

SEE ALSO

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

NOTES

235       When  compiling  multithreaded programs, see the MULTITHREADED APPLICA‐
236       TIONS section of Intro(3).
237
238
239       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
246
247       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.
250
251
252
253SunOS 5.11                        26 Jun 2007                      readdir(3C)
Impressum