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(3), readdir(3),
readdir_r(3), rewinddir(3), or
[XSI]
seekdir(3), the behavior is undefined. Upon calling
closedir(3) 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(3) 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(3) 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(3) 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(3).
FUTURE DIRECTIONS
None.
SEE ALSO
closedir(3), fchdir(3), fdopendir(3), fileno(3), open(3), readdir(3)
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.