huschi.net

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 (consult 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 path-
              name 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() clar-
       ifies 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 negligible value in pro-
       viding 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 opera-
       tions   are   defined   by   the   implementation,   this   volume   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 Defi-
       nitions  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, Copyright (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.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                          OPENDIR(3P)