Finds entries in a directory.

    Format

      #include  <dirent.h>

      struct dirent *readdir  (DIR *dir_pointer);

      int readdir_r  (DIR *dir_pointer, struct dirent *entry, struct
                     dirent **result);

1 - Arguments

 dir_pointer

    A pointer to the dir structure of an open directory.

 entry

    A pointer to a dirent structure that will be initialized with the
    directory entry at the current position of the specified stream.

 result

    Upon successful completion, the location where a pointer to entry
    is stored.

2 - Description

    The readdir function returns a pointer to a structure
    representing the directory entry at the current position in the
    directory stream specified by dir_pointer, and positions the
    directory stream at the next entry. It returns a NULL pointer
    upon reaching the end of the directory stream. The dirent
    structure defined in the <dirent.h> header file describes a
    directory entry.

    The type DIR defined in the <dirent.h> header file represents a
    directory stream. A directory stream is an ordered sequence of
    all the directory entries in a particular directory. Directory
    entries represent files. You can remove files from or add files
    to a directory asynchronously to the operation of the readdir
    function.

    The pointer returned by the readdir function points to data
    that you can overwrite 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 the opendir or rewinddir function, a
    subsequent call to the readdir function might not return an entry
    for that file.

    When it reaches the end of the directory, or when it detects an
    invalid seekdir operation, the readdir function returns the null
    value.

    An attempt to seek to an invalid location causes the readdir
    function to return the null value the next time it is called. A
    previous telldir function call returns the position.

    The readdir_r function is a reentrant version of readdir. In
    addition to dir_pointer, you must specify a pointer to a dirent
    structure in which the current directory entry of the specified
    stream is returned.

    If the operation is successful, readdir_r returns 0 and stores
    one of the following two pointers in result:

    o  Pointer to entry if the entry was found

    o  NULL pointer if the end of the directory stream was reached

    The storage pointed to by entry must be large enough for a dirent
    with an array of char d_name member containing at least NAME_MAX
    + 1 elements.

    If an error occurred, an error value is returned that indicates
    the cause of the error.

    Applications wishing to check for error situations should set
    errno to 0 before calling readdir. If errno is set to nonzero on
    return, then an error occurred.

3 - Example

      See the description of closedir for an example.

4 - Return Values

    x                  On successful completion of readdir, a pointer
                       to an object of type struct dirent.
    0                  Successful completion of readdir_r.
    x                  On error, an error value (readdir_r only).
    NULL               An error occurred or end of the directory
                       stream (readdir_r only). If an error occurred,
                       errno is set to a value indicating the cause.