directory(3)                                               directory(3)

  opendir()

  NAME

    opendir(), wcs_opendir(), readdir(), readdir_r(), rewinddir(), closedir(),
    telldir(), seekdir(), dirfd() - directory operations

  SYNOPSIS

    #include 
    #include 

    DIR * opendir (const char *filename)
    DIR * wcs_opendir (const wchar_t *filename)
    struct dirent * readdir (DIR *dirp)
    int readdir_r (DIR *dirp, struct dirent *entry,
           struct dirent **result);
    void rewinddir (DIR *dirp)
    int closedir (DIR *dirp)
    long telldir (DIR *dirp)
    void seekdir (DIR *dirp, long loc)
    int dirfd (DIR *dirp)

  DESCRIPTION

    The opendir(3) and wcs_opendir(3) functions are identical, except that
    wcs_opendir(3) accepts wide characters in the filename argument.

    These calls create, remove, read, and search directories. They make use of
    the DIR type, defined in the header , which represents a
    directory stream A directory stream is an ordered sequence of all the
    directory entries in a particular directory. Each directory entry
    represents a file.

    The opendir(3) or wcs_opendir(3) function opens the directory named by
    filename, associates a directory stream with it and returns a pointer to
    be used to identify the directory stream in subsequent operations. The
    readdir(2) function returns NULL if filename cannot be accessed, or if it
    cannot malloc(3) enough memory to hold the whole thing.

    The readdir(2) function returns a pointer to the next directory entry. It
    returns NULL upon reaching the end of the directory. 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 reentrant readdir_r(3) function initializes the dirent structure
    identified by the entry argument to represent the directory entry at the
    current position in the directory stream identified by dirp, stores a
    pointer to this structure at the location identified by result, and
    positions the directory stream at the next entry.

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

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

    The readdir_r(3) function does not return directory entries containing
    empty names.

    The rewinddir(3) function resets the position of the named directory
    stream to the beginning of the directory.

    The closedir(3) function closes the named directory stream and frees the
    structure associated with the dirp pointer, returning 0 on success.

    The telldir(3) call returns the current location associated with the
    directory stream indicated by dirp.

    The seekdir(3) function sets the position of the next readdir(2) operation
    on the directory stream. The new position reverts to the one associated
    with the directory stream when the telldir(3) operation was performed.
    Values returned by telldir(3) are good only for the lifetime of the DIR
    pointer, dirp, from which they are derived. If the directory is closed and
    then reopened, the telldir(3) value may be invalidated due to undetected
    directory compaction. It is safe to use a previous telldir(3) value
    immediately after a call to opendir(3) or wcs_opendir(3) and before any
    calls to readdir(2).

    The dirfd(3) function returns the integer file descriptor associated with
    the named directory stream, see open(2).

  RETURN VALUES

    The opendir(3) or wcs_opendir(3) function returns a pointer to a DIR on
    success. On failure, it returns NULL and sets errno

    readdir(2) returns a pointer to a struct dirent on success; when it
    reaches the end of the directory, it returns NULL and doesn't set errno.
    On failure, it returns NULL and does set errno.

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

    closedir(3) and dirfd(3) return 0 on success; on error, they return -1 and
    set errno.

    rewinddir(3) and seekdir(3) don't return a value.

    On success, telldir(3) returns the current location of the directory
    stream.

  EXAMPLE

    To search the current directory for the entry name:

    dirp = opendir(".");
    while ((dp = readdir(dirp)) != NULL)
         if (!strcmp(dp->d_name, name)) {
              (void)closedir(dirp);
              return FOUND;
         }
    (void)closedir(dirp);
    return NOT_FOUND;

  ERRORS

    The opendir(3) or wcs_opendir(3) function can set errno to the following
    values:

    [EACCES]
        The process doesn't have search permission for a component of the path
        filename, or it doesn't have read permission for the directory itself.

    [EMFILE]
        The process has too many file descriptors open.

    [ENFILE]
        The system has too many file descriptors open.

    [ENAMETOOLONG]
        A component of filename exceeded {NAME_MAX} characters, or the entire
        pathname exceeded {PATH_MAX} characters.

    [ENOENT]
        The directory named by filename doesn't exist, or filename is an empty
        string.

    [ENOTDIR]
        Some component of filename isn't a directory.

    The closedir(3), dirfd(3) and readdir(2) functions can set errno to the
    following value:

    [EBADF]
        Dirp doesn't refer to an open directory stream.

    The readdir_r(3) function may fail if:

    [EBADF]
        The dirp argument does not refer to an open directory stream.

  SEE ALSO

    open(2)

    close(2)

    lseek(2)

    read(2)

  USAGE NOTES

    The opendir, closedir, dirfd, readdir_r, rewinddir, seekdir, telldir,
    wcs_opendir functions are thread safe. The following function is not
    thread safe: readdir.

    None of these functions are async-signal safe.