OPENDIR(3P)                                         POSIX Programmer's Manual                                        OPENDIR(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       opendir - open a directory

SYNOPSIS
       #include <dirent.h>

       DIR *opendir(const char *dirname);


DESCRIPTION
       The  opendir()  function shall open a directory stream corresponding to the directory named by the dirname argument.  The
       directory stream is positioned at the first entry. If the type DIR is implemented using a file  descriptor,  applications
       shall only be able to open up to a total of {OPEN_MAX} files and directories.

RETURN VALUE
       Upon successful completion, opendir() shall return a pointer to an object of type DIR. Otherwise, a null pointer shall be
       returned and errno set to indicate the error.

ERRORS
       The opendir() function shall fail if:

       EACCES Search permission is denied for the component of the path prefix of dirname  or  read  permission  is  denied  for
              dirname.

       ELOOP  A loop exists in symbolic links encountered during resolution of the dirname argument.

       ENAMETOOLONG
              The length of the dirname argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

       ENOENT A component of dirname does not name an existing directory or dirname is an empty string.

       ENOTDIR
              A component of dirname is not a directory.


       The opendir() function may fail if:

       ELOOP  More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the dirname argument.

       EMFILE {OPEN_MAX} file descriptors are currently open in the calling process.

       ENAMETOOLONG
              As  a  result of encountering a symbolic link in resolution of the dirname argument, the length of the substituted
              pathname string exceeded {PATH_MAX}.

       ENFILE Too many files are currently open in the system.



       The following sections are informative.

EXAMPLES
   Open a Directory Stream
       The following program fragment demonstrates how the opendir() function is used.


              #include <sys/types.h>
              #include <dirent.h>
              #include <libgen.h>
              ...
                  DIR *dir;
                  struct dirent *dp;
              ...
                  if ((dir = opendir (".")) == NULL) {
                      perror ("Cannot open .");
                      exit (1);
                  }


                  while ((dp = readdir (dir)) != NULL) {
              ...

APPLICATION USAGE
       The opendir() function should be used in conjunction with readdir(), closedir(), and rewinddir() to examine the  contents
       of the directory (see the EXAMPLES section in readdir()). This method is recommended for portability.

RATIONALE
       Based  on  historical implementations, the rules about file descriptors apply to directory streams as well. However, this
       volume of IEEE Std 1003.1-2001 does not mandate that the directory stream be  implemented  using  file  descriptors.  The
       description  of  closedir()  clarifies  that  if a file descriptor is used for the directory stream, it is mandatory that
       closedir() deallocate the file descriptor.  When a file descriptor is used to implement the directory stream, it  behaves
       as if the FD_CLOEXEC had been set for the file descriptor.

       The  directory  entries  for  dot and dot-dot are optional. This volume of IEEE Std 1003.1-2001 does not provide a way to
       test a priori for their existence because an application that is portable must  be  written  to  look  for  (and  usually
       ignore)  those  entries.  Writing  code  that  presumes that they are the first two entries does not always work, as many
       implementations permit them to be other than the first two entries, with a "normal" entry preceding them. There is negli-
       gible  value  in  providing a way to determine what the implementation does because the code to deal with dot and dot-dot
       must be written in any case and because such a flag would add to the list of those flags (which has proven in  itself  to
       be objectionable) and might be abused.

       Since  the structure and buffer allocation, if any, for directory operations are defined by the implementation, this vol-
       ume of IEEE Std 1003.1-2001 imposes no portability requirements for erroneous program constructs, erroneous data, or  the
       use  of  unspecified  values such as the use or referencing of a dirp value or a dirent structure value after a directory
       stream has been closed or after a fork() or one of the exec function calls.

FUTURE DIRECTIONS
       None.

SEE ALSO
       closedir(), lstat(), readdir(), rewinddir(), symlink(), the Base Definitions volume of IEEE Std 1003.1-2001,  <dirent.h>,
       <limits.h>, <sys/types.h>

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for
       Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6,  Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open  Group
       Standard   is   the   referee   document.   The   original   Standard   can   be   obtained  online  at  http://www.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                   OPENDIR(3P)