GNU Info

(libc.info)Opening a Directory

---

Next: Reading/Closing Directory Prev: Directory Entries Up: Accessing Directories

---

Enter node , (file) or (file)node

Opening a Directory Stream
--------------------------

   This section describes how to open a directory stream.  All the
symbols are declared in the header file `dirent.h'.

 - Data Type: DIR
     The `DIR' data type represents a directory stream.

   You shouldn't ever allocate objects of the `struct dirent' or `DIR'
data types, since the directory access functions do that for you.
Instead, you refer to these objects using the pointers returned by the
following functions.

 - Function: DIR * opendir (const char *DIRNAME)
     The `opendir' function opens and returns a directory stream for
     reading the directory whose file name is DIRNAME.  The stream has
     type `DIR *'.

     If unsuccessful, `opendir' returns a null pointer.  In addition to
     the usual file name errors (Note: File Name Errors), the
     following `errno' error conditions are defined for this function:

    `EACCES'
          Read permission is denied for the directory named by
          `dirname'.

    `EMFILE'
          The process has too many files open.

    `ENFILE'
          The entire system, or perhaps the file system which contains
          the directory, cannot support any additional open files at
          the moment.  (This problem cannot happen on the GNU system.)

     The `DIR' type is typically implemented using a file descriptor,
     and the `opendir' function in terms of the `open' function.  Note:
     Low-Level I/O.  Directory streams and the underlying file
     descriptors are closed on `exec' (Note: Executing a File).

   In some situations it can be desirable to get hold of the file
descriptor which is created by the `opendir' call.  For instance, to
switch the current working directory to the directory just read the
`fchdir' function could be used.  Historically the `DIR' type was
exposed and programs could access the fields.  This does not happen in
the GNU C library.  Instead a separate function is provided to allow
access.

 - Function: int dirfd (DIR *DIRSTREAM)
     The function `dirfd' returns the file descriptor associated with
     the directory stream DIRSTREAM.  This descriptor can be used until
     the directory is closed with `closedir'.  If the directory stream
     implementation is not using file descriptors the return value is
     `-1'.