NAME

readdir, readdir_r - read directory

 SYNOPSIS

#include <sys/types.h>
#include <dirent.h>

struct dirent *readdir(DIR *dirp);
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().

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() 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() marks 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 undefined.

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

The readdir() interface need not be reentrant.

The readdir_r() function initialises 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 referenced by result, and positions the directory stream at the next entry.

The storage pointed to by entry will be large enough for a dirent with an array of char d_name member containing at least {NAME_MAX} plus one elements.

On successful return, the pointer returned at *result will have the same value as the argument entry. Upon reaching the end of the directory stream, this pointer will have the value NULL.

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.

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() returns 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.

If successful, the readdir_r() function returns zero. Otherwise, an error number is returned to indicate the error.

 ERRORS

The readdir() function will 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.

 EXAMPLES

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;

 APPLICATION USAGE

The readdir() function should be used in conjunction with opendir(), closedir() and rewinddir() to examine the contents of the directory.

 FUTURE DIRECTIONS

None.

 SEE ALSO

closedir(), lstat(), opendir(), rewinddir(), symlink(), <dirent.h>, <sys/types.h>.

DERIVATION

readdir_r() derived from the POSIX Threads Extension (1003.1c-1995).