Next: Reading/Closing Directory, Previous: Directory Entries, Up: Accessing Directories
This section describes how to open a directory stream. All the symbols are declared in the header file dirent.h.
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.
The
opendirfunction opens and returns a directory stream for reading the directory whose file name is dirname. The stream has typeDIR *.If unsuccessful,
opendirreturns a null pointer. In addition to the usual file name errors (see File Name Errors), the followingerrnoerror 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
DIRtype is typically implemented using a file descriptor, and theopendirfunction in terms of theopenfunction. See Low-Level I/O. Directory streams and the underlying file descriptors are closed onexec(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.
The
fdopendirfunction works just likeopendirbut 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
fdopendircall 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 byopendircan 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
errnoerror 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.