Standard conforming

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 can 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.

The readdir() function will not return directory entries containing empty names. 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 that can be overwritten
by another call to readdir() on the same directory stream. These data
are 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 can buffer several directory entries per actual read operation.
It 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) can continue processing the directory stream using readdir(), rewinddir() or seekdir(3C).
If both the parent and child processes use these functions, the result
is undefined.

If the entry names a symbolic link, the value of the d_ino
member is unspecified.

readdir_r()

Unless the end of the directory stream has been reached or an
error occurred, 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 chard_name member
containing at least NAME_MAX (that is, pathconf(directory, _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 can buffer several directory entries per actual read operation.
It marks for update the st_atime field of the directory each time
the directory is actually read.

The standard-conforming version (see standards(5)) of the readdir_r() function performs all of
the actions described above and sets the pointer pointed to by result. If
a directory entry is returned, the pointer will be set to the
same value as the entry argument; otherwise, it will be set to
NULL.

Return Values

Upon successful completion, readdir() and the default 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 standard-conforming readdir_r() returns 0 if the end of the directory
is encountered or a directory entry is stored in the structure referenced
by entry. Otherwise, an error number is returned to indicate the failure.

Errors

The readdir() and readdir_r() functions will fail if:

EOVERFLOW

One of the values in the structure to be returned cannot be represented correctly.

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() and readdir_r() functions should be used in conjunction with
opendir(), closedir(), and rewinddir() to examine the contents of the directory.
Since readdir() and the default readdir_r() return a null pointer both at the
end of the directory and on error, an application wanting to check
for error situations should set errno to 0 before calling either of
these functions. If errno is set to non-zero on return, an error occurred.

It is safe to use readdir() in a threaded application, so long
as only one thread reads from the directory stream at any given
time. The readdir() function is generally preferred over the readdir_r() function.

The standard-conforming readdir_r() returns the error number if an error occurred. It
returns 0 on success (including reaching the end of the directory stream).

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 program will search the current directory for each of
the arguments supplied on the command line:

See Also

Notes

When compiling multithreaded programs, see the MULTITHREADED APPLICATIONS section of Intro(3).

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 compatibility only
and might not be supported in future releases. New applications and libraries should
use the standard-conforming interface.

For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and _REENTRANT flags are automatically turned on
by defining the _POSIX_C_SOURCE flag with a value >= 199506L.