Opens a specified directory.

    Format

      #include  <dirent.h>

      DIR *opendir  (const char *dir_name);

1 - Argument

 dir_name

    The name of the directory to be opened.

2 - Description

    The opendir function opens the directory specified by dir_name
    and associates a directory stream with it. The dir_name argument
    can be specified in OpenVMS style or UNIX style. The directory
    stream is positioned at the first 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.

    The opendir function also returns a pointer to identify the
    directory stream in subsequent operations. The NULL pointer is
    returned when the directory named by dir_name cannot be accessed,
    or when not enough memory is available to hold the entire stream.

                                  NOTES

       o  An open directory must always be closed with the closedir
          function to ensure that the next attempt to open that
          directory is successful. The opendir function should be
          used with readdir, closedir, and rewinddir to examine the
          contents of the directory.

       o  The opendir function supports UNIX style path name
          specifications.

3 - Example

      See the program example in the description of closedir.

4 - Return Values

    x                  A pointer to an object of type DIR.
    NULL               Indicates an error; errno is set to one of the
                       following values:

                       o  EACCES - Search permission is denied
                          for any component of dir_name or read
                          permission is denied for dir_name.

                       o  ENAMETOOLONG - The length of the dir_name
                          string exceeds PATH_MAX, or a pathname
                          component is longer than NAME_MAX.

                       o  ENOENT - The dir_name argument points to
                          the name of a file that does not exist, or
                          is an empty string.