1READDIR(3P)                POSIX Programmer's Manual               READDIR(3P)
2
3
4

PROLOG

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

NAME

12       readdir, readdir_r - read a directory
13

SYNOPSIS

15       #include <dirent.h>
16
17       struct dirent *readdir(DIR *dirp);
18
19
20       int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
21              struct dirent **restrict result);
22
23

DESCRIPTION

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
31       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
38       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
43       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
48       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
52       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
56       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
61       If the entry names a symbolic link, the value of the  d_ino  member  is
62       unspecified.
63
64       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
67       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
73       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
77       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
81       The readdir_r() function shall not return directory entries  containing
82       empty names.
83
84       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
88       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
93       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

RETURN VALUE

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
104       If successful, the readdir_r() function shall return  zero;  otherwise,
105       an error number shall be returned to indicate the error.
106

ERRORS

108       The readdir() function shall fail if:
109
110       EOVERFLOW
111              One of the values in the structure to be returned cannot be rep‐
112              resented correctly.
113
114
115       The readdir() function may fail if:
116
117       EBADF  The dirp argument does not refer to an open directory stream.
118
119       ENOENT The current position of the directory stream is invalid.
120
121
122       The readdir_r() function may fail if:
123
124       EBADF  The dirp argument does not refer to an open directory stream.
125
126
127       The following sections are informative.
128

EXAMPLES

130       The following sample program searches the current directory for each of
131       the arguments supplied on the command line.
132
133
134              #include <dirent.h>
135              #include <errno.h>
136              #include <stdio.h>
137              #include <string.h>
138
139
140              static void lookup(const char *arg)
141              {
142                  DIR *dirp;
143                  struct dirent *dp;
144
145
146                  if ((dirp = opendir(".")) == NULL) {
147                      perror("couldn't open '.'");
148                      return;
149                  }
150
151
152                  do {
153                      errno = 0;
154                      if ((dp = readdir(dirp)) != NULL) {
155                          if (strcmp(dp->d_name, arg) != 0)
156                              continue;
157
158
159                          (void) printf("found %s\n", arg);
160                          (void) closedir(dirp);
161                              return;
162
163
164                      }
165                  } while (dp != NULL);
166
167
168                  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
176
177              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

APPLICATION USAGE

186       The  readdir()  function  should be used in conjunction with opendir(),
187       closedir(), and rewinddir() to examine the contents of the directory.
188
189       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

RATIONALE

194       The returned value of readdir() merely represents a directory entry. No
195       equivalence should be inferred.
196
197       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
204       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
212       Routines to deal with this problem more directly were proposed:
213
214
215              int derror (dirp)
216              DIR *dirp;
217
218
219              void clearderr (dirp)
220              DIR *dirp;
221
222       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
227       An  error  or signal indicating that a directory has changed while open
228       was considered but rejected.
229
230       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

FUTURE DIRECTIONS

237       None.
238

SEE ALSO

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 .
253
254
255
256IEEE/The Open Group                  2003                          READDIR(3P)
Impressum