dirfd

dirfd is a POSIX function that returns the integer file descriptor associated with a directory stream. It is declared in dirent.h and is used with a DIR* object obtained from opendir or fdopendir. The function provides access to the underlying directory file descriptor without altering the current working directory, enabling subsequent relative-file operations such as openat, fstatat, or other fd-based calls.

The typical usage is to obtain a DIR* for a directory and then query its descriptor with dirfd. For example, after opening a directory with opendir, dirfd(dirp) yields the file descriptor of that directory, which can be supplied to other system calls that take a directory fd. This can be useful for performing actions relative to a directory while keeping the process’s working directory unchanged.

If the call succeeds, dirfd returns the directory’s file descriptor. If an error occurs, the function returns -1 and sets errno to indicate the issue. Possible error conditions include an invalid or closed directory stream; in such cases, errno may reflect EBADF or other related errors, and no valid descriptor is returned. Passing an invalid argument (for instance, a NULL or otherwise non-directory stream) will also result in an error.

Portability and notes: dirfd is defined by POSIX and is widely supported on modern Unix-like systems, including Linux and BSD variants. Its availability on non-POSIX or older implementations may vary. Users should include <dirent.h> and ensure compatibility with their target environments when relying on dirfd for directory-relative operations.

See also: opendir, readdir, fdopendir, fstatat, openat, dirent.