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       int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
19           struct dirent **restrict result);
20

DESCRIPTION

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
28       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
39       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
44       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
54       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
58       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
62       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
67       The readdir() function need not be thread-safe.
68
69       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
73       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
79       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
83       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
87       The  readdir_r() function shall not return directory entries containing
88       empty names.
89
90       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
94       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

RETURN VALUE

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

ERRORS

110       These functions shall fail if:
111
112       EOVERFLOW
113              One of the values in the structure to be returned cannot be rep‐
114              resented correctly.
115
116       These functions may fail if:
117
118       EBADF  The dirp argument does not refer to an open directory stream.
119
120       ENOENT The current position of the directory stream is invalid.
121
122       The following sections are informative.
123

EXAMPLES

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

APPLICATION USAGE

174       The readdir() function should be used in  conjunction  with  opendir(),
175       closedir(), and rewinddir() to examine the contents of the directory.
176
177       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

RATIONALE

182       The returned value of readdir() merely represents a directory entry. No
183       equivalence should be inferred.
184
185       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
192       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
198       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
206       Routines to deal with this problem more directly were proposed:
207
208
209           int derror (dirp)
210           DIR *dirp;
211
212           void clearderr (dirp)
213           DIR *dirp;
214
215       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
220       An error or signal indicating that a directory has changed  while  open
221       was considered but rejected.
222
223       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

FUTURE DIRECTIONS

230       None.
231

SEE ALSO

233       closedir(),  dirfd(),  exec,  fdopendir(), fstatat(), rewinddir(), sym‐
234       link()
235
236       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
249       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 .
253
254
255
256IEEE/The Open Group                  2017                          READDIR(3P)
Impressum