/* Void Main's man pages */
{ phpMan } else { main(); }
READDIR(3P) POSIX Programmer's Manual READDIR(3P)
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (con-
sult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on
Linux.
NAME
readdir, readdir_r - read a directory
SYNOPSIS
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
int readdir_r(DIR *restrict dirp, struct dirent *restrict entry,
struct dirent **restrict result);
DESCRIPTION
The type DIR, which is defined in the <dirent.h> header, represents a directory stream, which is an ordered sequence of
all the directory entries in a particular directory. Directory entries represent files; files may be removed from a
directory or added to a directory asynchronously to the operation of readdir().
The readdir() function shall return a pointer to a structure representing the directory entry at the current position in
the directory stream specified by the argument dirp, and position the directory stream at the next entry. It shall return
a null pointer upon reaching the end of the directory stream. The structure dirent defined in the <dirent.h> header
describes a directory entry.
The readdir() function shall not return directory entries containing empty names. If entries for dot or dot-dot exist,
one entry shall be returned for dot and one entry shall be returned for dot-dot; otherwise, they shall not be returned.
The pointer returned by readdir() points to data which may be overwritten by another call to readdir() on the same direc-
tory stream. This data is not overwritten by another call to readdir() on a different directory stream.
If a file is removed from or added to the directory after the most recent call to opendir() or rewinddir(), whether a
subsequent call to readdir() returns an entry for that file is unspecified.
The readdir() function may buffer several directory entries per actual read operation; readdir() shall mark for update
the st_atime field of the directory each time the directory is actually read.
After a call to fork(), either the parent or child (but not both) may continue processing the directory stream using
readdir(), rewinddir(), or seekdir(). If both the parent and child processes use these functions, the result is unde-
fined.
If the entry names a symbolic link, the value of the d_ino member is unspecified.
The readdir() function need not be reentrant. A function that is not required to be reentrant is not required to be
thread-safe.
The readdir_r() function shall initialize the dirent structure referenced by entry to represent the directory entry at
the current position in the directory stream referred to by dirp, store a pointer to this structure at the location ref-
erenced by result, and position the directory stream at the next entry.
The storage pointed to by entry shall be large enough for a dirent with an array of char d_name members containing at
least {NAME_MAX}+1 elements.
Upon successful return, the pointer returned at *result shall have the same value as the argument entry. Upon reaching
the end of the directory stream, this pointer shall have the value NULL.
The readdir_r() function shall not return directory entries containing empty names.
If a file is removed from or added to the directory after the most recent call to opendir() or rewinddir(), whether a
subsequent call to readdir_r() returns an entry for that file is unspecified.
The readdir_r() function may buffer several directory entries per actual read operation; the readdir_r() function shall
mark for update the st_atime field of the directory each time the directory is actually read.
Applications wishing to check for error situations should set errno to 0 before calling readdir(). If errno is set to
non-zero on return, an error occurred.
RETURN VALUE
Upon successful completion, readdir() shall return a pointer to an object of type struct dirent. When an error is encoun-
tered, a null pointer shall be returned and errno shall be set to indicate the error. When the end of the directory is
encountered, a null pointer shall be returned and errno is not changed.
If successful, the readdir_r() function shall return zero; otherwise, an error number shall be returned to indicate the
error.
ERRORS
The readdir() function shall fail if:
EOVERFLOW
One of the values in the structure to be returned cannot be represented correctly.
The readdir() function may fail if:
EBADF The dirp argument does not refer to an open directory stream.
ENOENT The current position of the directory stream is invalid.
The readdir_r() function may fail if:
EBADF The dirp argument does not refer to an open directory stream.
The following sections are informative.
EXAMPLES
The following sample program searches the current directory for each of the arguments supplied on the command line.
#include <dirent.h>
#include <errno.h>
#include <stdio.h>
#include <string.h>
static void lookup(const char *arg)
{
DIR *dirp;
struct dirent *dp;
if ((dirp = opendir(".")) == NULL) {
perror("couldn't open '.'");
return;
}
do {
errno = 0;
if ((dp = readdir(dirp)) != NULL) {
if (strcmp(dp->d_name, arg) != 0)
continue;
(void) printf("found %s\n", arg);
(void) closedir(dirp);
return;
}
} while (dp != NULL);
if (errno != 0)
perror("error reading directory");
else
(void) printf("failed to find %s\n", arg);
(void) closedir(dirp);
return;
}
int main(int argc, char *argv[])
{
int i;
for (i = 1; i < argc; i++)
lookup(arvg[i]);
return (0);
}
APPLICATION USAGE
The readdir() function should be used in conjunction with opendir(), closedir(), and rewinddir() to examine the contents
of the directory.
The readdir_r() function is thread-safe and shall return values in a user-supplied buffer instead of possibly using a
static data area that may be overwritten by each call.
RATIONALE
The returned value of readdir() merely represents a directory entry. No equivalence should be inferred.
Historical implementations of readdir() obtain multiple directory entries on a single read operation, which permits sub-
sequent readdir() operations to operate from the buffered information. Any wording that required each successful read-
dir() operation to mark the directory st_atime field for update would disallow such historical performance-oriented
implementations.
Since readdir() returns NULL when it detects an error and when the end of the directory is encountered, an application
that needs to tell the difference must set errno to zero before the call and check it if NULL is returned. Since the
function must not change errno in the second case and must set it to a non-zero value in the first case, a zero errno
after a call returning NULL indicates end-of-directory; otherwise, an error.
Routines to deal with this problem more directly were proposed:
int derror (dirp)
DIR *dirp;
void clearderr (dirp)
DIR *dirp;
The first would indicate whether an error had occurred, and the second would clear the error indication. The simpler
method involving errno was adopted instead by requiring that readdir() not change errno when end-of-directory is encoun-
tered.
An error or signal indicating that a directory has changed while open was considered but rejected.
The thread-safe version of the directory reading function returns values in a user-supplied buffer instead of possibly
using a static data area that may be overwritten by each call. Either the {NAME_MAX} compile-time constant or the corre-
sponding pathconf() option can be used to determine the maximum sizes of returned pathnames.
FUTURE DIRECTIONS
None.
SEE ALSO
closedir(), lstat(), opendir(), rewinddir(), symlink(), the Base Definitions volume of IEEE Std 1003.1-2001, <dirent.h>,
<sys/types.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for
Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group
Standard is the referee document. The original Standard can be obtained online at http://www.open-
group.org/unix/online.html .
IEEE/The Open Group 2003 READDIR(3P)
