Opening a Directory - The GNU C Library

Next: Reading/Closing Directory, Previous: Directory Entries, Up: Accessing Directories

#### 14.2.2 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 (see 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.)
> `ENOMEM`
>   Not enough memory available.

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

The directory which is opened for reading by `opendir` is identified by the name. In some situations this is not sufficient. Or the way `opendir` implicitly creates a file descriptor for the directory is not the way a program might want it. In these cases an alternative interface can be used.

— Function: DIR * fdopendir (int fd)

> The `fdopendir` function works just like `opendir` but instead of taking a file name and opening a file descriptor for the directory the caller is required to provide a file descriptor. This file descriptor is then used in subsequent uses of the returned directory stream object.

> The caller must make sure the file descriptor is associated with a directory and it allows reading.

> If the `fdopendir` call returns successfully the file descriptor is now under the control of the system. It can be used in the same way the descriptor implicitly created by `opendir` can be used but the program must not close the descriptor.

> In case the function is unsuccessful it returns a null pointer and the file descriptor remains to be usable by the program. The following `errno` error conditions are defined for this function:

> `EBADF`
>   The file descriptor is not valid.
> `ENOTDIR`
>   The file descriptor is not associated with a directory.
> `EINVAL`
>   The descriptor does not allow reading the directory content.
> `ENOMEM`
>   Not enough memory available.

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`.