.TH readdir() "" "" "General Function (libc)"
.PC "Read a directory stream"
.B "#include <sys/types.h>"
.B "#include <dirent.h>"
\fBstruct dirent *readdir(\fIdirp\^\fB)\fR
\fBDIR *\fIdirp\^\fB;\fR
.PP
The \*(CO function
.B readdir()
is one of a set of \*(CO routines that manipulate directories in a
device-independent manner.
It reads the directory stream pointed to by
.I dirp
and returns information about the next active entry within the stream.
It does not report on inactive entries.
.PP
.B readdir()
returns a pointer to a structure of type
.BR dirent ,
which contains information about the next active entry within the stream.
The internal structure may be overwritten by
another operation on the same directory stream.
The amount of memory needed to hold a copy
of the internal structure is given by the value of a macro,
.BR DIRENTSIZ(strlen(direntp\->d_name)) ,
not by
.B "sizeof(struct dirent)"
as one might expect.
.PP
.B readdir()
returns NULL if it has reached the end of the directory,
has detected an invalid location within the directory,
or if an error occurs while it is reading the directory.
If an error occurs,
.B readdir()
exits and sets
.B errno
to an appropriate value.
.SH Example
For an example of this function, see the Lexicon entry for
.BR opendir() .
.SH "See Also"
.Xr "closedir()," closedir
.Xr "dirent.h," dirent.h
.Xr "getdents()," getdents
.Xr "libc," libc
.Xr "opendir()," opendir
.Xr "rewinddir()," rewinddir
.Xr "seekdir()," seekdir
.Xr "telldir()" telldir
.br
\*(PX Standard, \(sc5.1.2
.SH Notes
The
.B dirent
routines buffer directories; and because directory entries
can appear and disappear as other users manipulate the directory,
your application should continually rescan
a directory to keep an accurate picture of its active entries.
.PP
.II "Gwynn, D."
The \*(CO implementation of the
.B dirent
routines was written by D. Gwynn.
