NAME

dirfd — extract the file descriptor used by a DIR stream

SYNOPSIS

#include <dirent.h>

int dirfd(DIR *dirp);


DESCRIPTION

If the directory stream referenced by dirp has an associated file descriptor, dirfd() shall return that file descriptor. Otherwise, dirfd() shall open a new file description referring to the directory associated with the directory stream as if by calling:

open(DirectoryName, O_RDONLY | O_DIRECTORY | O_CLOEXEC);

except that no pathname for use as DirectoryName need exist or be accessible. It shall then associate the new file descriptor with the directory stream, and return that file descriptor.

Upon successful return from dirfd(), the file descriptor is under the control of the system, and if any attempt is made to close the file descriptor, or to modify the state of the associated description, other than by means of closedir(), readdir(), readdir_r(), rewinddir(), or ^[XSI] seekdir(), the behavior is undefined. Upon calling closedir() the file descriptor shall be closed.

RETURN VALUE

Upon successful completion, the dirfd() function shall return an integer which contains a file descriptor for the stream pointed to by dirp. Otherwise, it shall return -1 and shall set errno to indicate the error.

ERRORS

The dirfd() function shall fail if:

[EMFILE]

A new file descriptor is required and all file descriptors available to the process are currently open.

[ENFILE]

A new file descriptor is required and the maximum allowable number of files is currently open in the system.

The dirfd() function may fail if:

[EINVAL]

The dirp argument does not refer to a valid directory stream.

EXAMPLES

None.

APPLICATION USAGE

The dirfd() function is intended to be a mechanism by which an application may obtain a file descriptor to use for the fchdir() function.

RATIONALE

This interface was introduced because the Base Definitions volume of POSIX.1-2024 does not make public the DIR data structure. Applications tend to use the fchdir() function on the file descriptor returned by this interface, and this has proven useful for security reasons; in particular, it is a better technique than others where directory names might change.

On an implementation where reading from a directory stream does not use a file descriptor, opendir() need not allocate one to be returned by dirfd(). The implementation can instead delay the allocation of a suitable file descriptor until the first time dirfd() is called for the stream. A file descriptor allocated by dirfd() must be closed by closedir().

FUTURE DIRECTIONS

None.

SEE ALSO

closedir, fchdir, fdopendir, fileno, open, readdir

XBD <dirent.h>

CHANGE HISTORY

First released in Issue 7.

POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0067 [422] is applied.

POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0076 [572] is applied.

Issue 8

Austin Group Defects 391 and 1359 are applied, changing the DESCRIPTION and RATIONALE sections, and adding the [EMFILE] and [ENFILE] errors.