diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/fdopendir.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/fdopendir.3p | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/fdopendir.3p b/man-pages-posix-2017/man3p/fdopendir.3p new file mode 100644 index 0000000..e8ecbad --- /dev/null +++ b/man-pages-posix-2017/man3p/fdopendir.3p @@ -0,0 +1,316 @@ +'\" 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 . |