fdopendir.3p (8683B)
- '\" et
- .TH FDOPENDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- fdopendir, opendir
- \(em open directory associated with file descriptor
- .SH SYNOPSIS
- .LP
- .nf
- #include <dirent.h>
- .P
- DIR *fdopendir(int \fIfd\fP);
- DIR *opendir(const char *\fIdirname\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIfdopendir\fR()
- function shall be equivalent to the
- \fIopendir\fR()
- function except that the directory is specified by a file descriptor
- rather than by a name. The file offset associated with the file
- descriptor at the time of the call determines which entries are
- returned.
- .P
- Upon successful return from
- \fIfdopendir\fR(),
- 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
- \fIclosedir\fR(),
- \fIreaddir\fR(),
- \fIreaddir_r\fR(),
- \fIrewinddir\fR(),
- or
- \fIseekdir\fR(),
- the behavior is undefined. Upon calling
- \fIclosedir\fR()
- the file descriptor shall be closed.
- .P
- It is unspecified whether the FD_CLOEXEC flag will be set on the file
- descriptor by a successful call to
- \fIfdopendir\fR().
- .P
- The
- \fIopendir\fR()
- function shall open a directory stream corresponding to the directory
- named by the
- .IR dirname
- argument. The directory stream is positioned at the first entry. If
- the type
- .BR DIR
- is implemented using a file descriptor, applications shall only be
- able to open up to a total of
- {OPEN_MAX}
- files and directories.
- .P
- If the type
- .BR DIR
- is implemented using a file descriptor, the descriptor shall be
- obtained as if the O_DIRECTORY flag was passed to
- \fIopen\fR().
- .SH "RETURN VALUE"
- Upon successful completion, these functions shall return
- a pointer to an object of type
- .BR DIR .
- Otherwise, these functions shall return a null pointer and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fIfdopendir\fR()
- function shall fail if:
- .TP
- .BR EBADF
- The
- .IR fd
- argument is not a valid file descriptor open for reading.
- .TP
- .BR ENOTDIR
- The descriptor
- .IR fd
- is not associated with a directory.
- .P
- The
- \fIopendir\fR()
- function shall fail if:
- .TP
- .BR EACCES
- Search permission is denied for the component of the path prefix of
- .IR dirname
- or read permission is denied for
- .IR dirname .
- .TP
- .BR ELOOP
- A loop exists in symbolic links encountered during resolution of the
- .IR dirname
- argument.
- .TP
- .BR ENAMETOOLONG
- .br
- The length of a component of a pathname is longer than
- {NAME_MAX}.
- .TP
- .BR ENOENT
- A component of
- .IR dirname
- does not name an existing directory or
- .IR dirname
- is an empty string.
- .TP
- .BR ENOTDIR
- A component of
- .IR dirname
- names an existing file that is neither a directory nor a symbolic link
- to a directory.
- .br
- .P
- The
- \fIopendir\fR()
- function may fail if:
- .TP
- .BR ELOOP
- More than
- {SYMLOOP_MAX}
- symbolic links were encountered during resolution of the
- .IR dirname
- argument.
- .TP
- .BR EMFILE
- All file descriptors available to the process are currently open.
- .TP
- .BR ENAMETOOLONG
- .br
- The length of a pathname exceeds
- {PATH_MAX},
- or pathname resolution of a symbolic link produced an intermediate
- result with a length that exceeds
- {PATH_MAX}.
- .TP
- .BR ENFILE
- Too many files are currently open in the system.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Open a Directory Stream"
- .P
- The following program fragment demonstrates how the
- \fIopendir\fR()
- function is used.
- .sp
- .RS 4
- .nf
- #include <dirent.h>
- \&...
- DIR *dir;
- struct dirent *dp;
- \&...
- if ((dir = opendir (".")) == NULL) {
- perror ("Cannot open .");
- exit (1);
- }
- .P
- while ((dp = readdir (dir)) != NULL) {
- \&...
- .fi
- .P
- .RE
- .SS "Find And Open a File"
- .P
- The following program searches through a given directory looking
- for files whose name does not begin with a dot and whose size is
- larger than 1 MiB.
- .sp
- .RS 4
- .nf
- #include <stdio.h>
- #include <dirent.h>
- #include <fcntl.h>
- #include <sys/stat.h>
- #include <stdint.h>
- #include <stdlib.h>
- #include <unistd.h>
- .P
- int
- main(int argc, char *argv[])
- {
- struct stat statbuf;
- DIR *d;
- struct dirent *dp;
- int dfd, ffd;
- .P
- if ((d = fdopendir((dfd = open("./tmp", O_RDONLY)))) == NULL) {
- fprintf(stderr, "Cannot open ./tmp directory\en");
- exit(1);
- }
- while ((dp = readdir(d)) != NULL) {
- if (dp->d_name[0] == \(aq.\(aq)
- continue;
- /* there is a possible race condition here as the file
- * could be renamed between the readdir and the open */
- if ((ffd = openat(dfd, dp->d_name, O_RDONLY)) == -1) {
- perror(dp->d_name);
- continue;
- }
- if (fstat(ffd, &statbuf) == 0 && statbuf.st_size > (1024*1024)) {
- /* found it ... */
- printf("%s: %jdK\en", dp->d_name,
- (intmax_t)(statbuf.st_size / 1024));
- }
- close(ffd);
- }
- closedir(d); // note this implicitly closes dfd
- return 0;
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- The
- \fIopendir\fR()
- function should be used in conjunction with
- \fIreaddir\fR(),
- \fIclosedir\fR(),
- and
- \fIrewinddir\fR()
- to examine the contents of the directory (see the EXAMPLES section in
- .IR "\fIreaddir\fR\^(\|)").
- This method is recommended for portability.
- .SH RATIONALE
- The purpose of the
- \fIfdopendir\fR()
- function is to enable opening files in directories other than the
- current working directory without exposure to race conditions. Any part
- of the path of a file could be changed in parallel to a call to
- \fIopendir\fR(),
- resulting in unspecified behavior.
- .P
- Based on historical implementations, the rules about file descriptors
- apply to directory streams as well. However, this volume of POSIX.1\(hy2017 does not
- mandate that the directory stream be implemented using file
- descriptors. The description of
- \fIclosedir\fR()
- clarifies that if a file descriptor is used for the directory stream,
- it is mandatory that
- \fIclosedir\fR()
- deallocate the file descriptor. When a file descriptor is used to
- implement the directory stream, it behaves as if the FD_CLOEXEC
- had been set for the file descriptor.
- .P
- The directory entries for dot
- and dot-dot
- are optional. This volume of POSIX.1\(hy2017 does not provide a way to test
- .IR "a priori"
- for their existence because an application that is portable must be
- written to look for (and usually ignore) those entries. Writing code
- that presumes that they are the first two entries does not always work,
- as many implementations permit them to be other than the first two
- entries, with a ``normal'' entry preceding them. There is negligible
- value in providing a way to determine what the implementation does
- because the code to deal with dot and dot-dot must be written in any
- case and because such a flag would add to the list of those flags
- (which has proven in itself to be objectionable) and might be abused.
- .P
- Since the structure and buffer allocation, if any, for directory
- operations are defined by the implementation, this volume of POSIX.1\(hy2017 imposes no
- portability requirements for erroneous program constructs, erroneous
- data, or the use of unspecified values such as the use or referencing
- of a
- .IR dirp
- value or a
- .BR dirent
- structure value after a directory stream has been closed or after a
- \fIfork\fR()
- or one of the
- .IR exec
- function calls.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIclosedir\fR\^(\|)",
- .IR "\fIdirfd\fR\^(\|)",
- .IR "\fIfstatat\fR\^(\|)",
- .IR "\fIopen\fR\^(\|)",
- .IR "\fIreaddir\fR\^(\|)",
- .IR "\fIrewinddir\fR\^(\|)",
- .IR "\fIsymlink\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<dirent.h>\fP",
- .IR "\fB<sys_types.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .