readdir(3C)
NAME
readdir, readdir_r - read directory
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
struct dirent *readdir_r(DIR *dirp, struct dirent *entry);
POSIX
cc [ flag ... ] file ... -D_POSIX_PTHREAD_SEMANTICS [ library ... ]
int readdir_r(DIR *dirp, struct dirent *entry, struct dirent
**result);
DESCRIPTION
The type DIR, which is defined in the header <dirent.h>,
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() and readdir_r().
readdir()
The readdir() function returns a pointer to a structure
representing the directory entry at the current position in
the directory stream specified by the argument dirp, and
positions the directory stream at the next entry. It returns
a null pointer upon reaching the end of the directory
stream. The structure dirent defined by the <dirent.h>
header describes a directory entry.
If entries for . (dot) or .. (dot-dot) exist, one entry will
be returned for dot and one entry will be returned for dot-
dot; otherwise they will not be returned.
The pointer returned by readdir() points to data which may
be overwritten by another call to readdir() on the same
directory 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(3C) or rewinddir(3C),
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() marks for update the
st_atime field of the directory each time the directory is
actually read.
After a call to fork(2), either the parent or child (but not
both) may continue processing the directory stream using
readdir(), rewinddir() or seekdir(3C). 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.
readdir_r()
The readdir_r() function initializes the dirent structure
referenced by entry to represent the directory entry at the
current position in the directory stream referred to by
dirp, and positions the directory stream at the next entry.
The caller must allocate storage pointed to by entry to be
large enough for a dirent structure with an array of char
d_name member containing at least NAME_MAX (that is,
pathconf(_PC_NAME_MAX)) plus one elements. _PC_NAME_MAX is
defined in <unistd.h>.
The readdir_r() function will not return directory entries
containing empty names. It is unspecified whether entries
are returned for . (dot) or .. (dot-dot).
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
marks for update the st_atime field of the directory each
time the directory is actually read.
The POSIX version (see standards(5)) of the readdir_r()
function initializes the structure referenced by entry and
stores a pointer to this structure in result. On successful
return, the pointer returned at *result will the same value
as the argument entry. Upon reaching the end of the direc-
tory stream, this pointer will have the value NULL.
RETURN VALUES
Upon successful completion, readdir() and readdir_r() return
a pointer to an object of type struct dirent. When an error
is encountered, a null pointer is returned and errno is set
to indicate the error. When the end of the directory is
encountered, a null pointer is returned and errno is not
changed. The POSIX readdir_r() returns 0 if successful or
an error number to indicate failure.
ERRORS
The readdir() function will fail if:
EOVERFLOW
One of the values in the structure to be returned can-
not be represented correctly.
The readdir() and readdir_r() functions will fail if:
EBADF The file descriptor determined by the DIR stream is no
longer valid. This results if the DIR stream has been
closed.
ENOENT
The current file pointer for the directory is not
located at a valid entry.
The readdir() and readdir_r() functions 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.
USAGE
The readdir() function should be used in conjunction with
opendir(), closedir(), and rewinddir() to examine the con-
tents of the directory. As readdir() returns a null pointer
both at the end of the directory and on error, an applica-
tion wishing to check for error situations should set errno
to 0, then call readdir(), then check errno and if it is
non-zero, assume an error has occurred.
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.
The readdir() and readdir_r() functions have transitional
interfaces for 64-bit file offsets. See lf64(5).
EXAMPLES
Example 1: Search the current directory for the entry name.
The following sample code will search the current directory
for the entry name:
dirp = opendir(".");
while (dirp) {
errno = 0;
if ((dp = readdir(dirp)) != NULL) {
if (strcmp(dp->d_name, name) == 0) {
closedir(dirp);
return FOUND;
}
} else {
if (errno == 0) {
closedir(dirp);
return NOT_FOUND;
}
closedir(dirp);
return READ_ERROR;
}
}
return OPEN_ERROR;
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | See NOTES below. |
|_____________________________|_____________________________|
NOTES
When compiling multithreaded programs, see Intro(3), Notes
On Multithreaded Applications.
The readdir() function is unsafe in multithreaded applica-
tions. The readdir_r() function is safe, and should be used
instead.
Solaris 2.4 and earlier releases provided a readdir_r()
interface as specified in POSIX.1c Draft 6. The final
POSIX.1c standard changed the interface as described above.
Support for the Draft 6 interface is provided for compati-
bility only and may not be supported in future releases.
New applications and libraries should use the POSIX standard
interface.
For POSIX.1c-compliant applications, the
_POSIX_PTHREAD_SEMANTICS and _REENTRANT flags are automati-
cally turned on by defining the _POSIX_C_SOURCE flag with a
value >= 199506L.
SEE ALSO
fork(2), lstat(2), symlink(2), Intro(3), closedir(3C),
opendir(3C), rewinddir(3C), seekdir(3C), attributes(5),
lf64(5), standards(5)
Man(1) output converted with
man2html