diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/opendir.3p')
-rw-r--r-- | man-pages-posix-2003/man3p/opendir.3p | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/opendir.3p b/man-pages-posix-2003/man3p/opendir.3p new file mode 100644 index 0000000..fddea80 --- /dev/null +++ b/man-pages-posix-2003/man3p/opendir.3p @@ -0,0 +1,162 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "OPENDIR" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" opendir +.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 +opendir \- open a directory +.SH SYNOPSIS +.LP +\fB#include <dirent.h> +.br +.sp +DIR *opendir(const char *\fP\fIdirname\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIopendir\fP() function shall open a directory stream corresponding +to the directory named by the \fIdirname\fP argument. +The directory stream is positioned at the first entry. If the type +\fBDIR\fP is implemented using a file descriptor, applications +shall only be able to open up to a total of {OPEN_MAX} files and directories. +.SH RETURN VALUE +.LP +Upon successful completion, \fIopendir\fP() shall return a pointer +to an object of type \fBDIR\fP. Otherwise, a null pointer +shall be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIopendir\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for the component of the path prefix of +\fIdirname\fP or read permission is denied for +\fIdirname\fP. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIdirname\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIdirname\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIdirname\fP does not name an existing directory or +\fIdirname\fP is an empty string. +.TP 7 +.B ENOTDIR +A component of \fIdirname\fP is not a directory. +.sp +.LP +The \fIopendir\fP() function may fail if: +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIdirname\fP argument. +.TP 7 +.B EMFILE +{OPEN_MAX} file descriptors are currently open in the calling process. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIdirname\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.TP 7 +.B ENFILE +Too many files are currently open in the system. +.sp +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Open a Directory Stream +.LP +The following program fragment demonstrates how the \fIopendir\fP() +function is used. +.sp +.RS +.nf + +\fB#include <sys/types.h> +#include <dirent.h> +#include <libgen.h> +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { + perror ("Cannot open ."); + exit (1); + } +.sp + + while ((dp = readdir (dir)) != NULL) { +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIopendir\fP() function should be used in conjunction with \fIreaddir\fP(), +\fIclosedir\fP(), and \fIrewinddir\fP() to +examine the contents of the directory (see the EXAMPLES section in +\fIreaddir\fP()). This method is +recommended for portability. +.SH RATIONALE +.LP +Based on historical implementations, the rules about file descriptors +apply to directory streams as well. However, this volume +of IEEE\ Std\ 1003.1-2001 does not mandate that the directory stream +be implemented using file descriptors. The description +of \fIclosedir\fP() clarifies that if a file descriptor is used for +the directory stream, +it is mandatory that \fIclosedir\fP() 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. +.LP +The directory entries for dot and dot-dot are optional. This volume +of IEEE\ Std\ 1003.1-2001 does not provide a way to +test \fIa priori\fP 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. +.LP +Since the structure and buffer allocation, if any, for directory operations +are defined by the implementation, this volume of +IEEE\ Std\ 1003.1-2001 imposes no portability requirements for erroneous +program constructs, erroneous data, or the use of +unspecified values such as the use or referencing of a \fIdirp\fP +value or a \fBdirent\fP structure value after a directory +stream has been closed or after a \fIfork\fP() or one of the \fIexec\fP +function calls. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIclosedir\fP(), \fIlstat\fP(), \fIreaddir\fP(), \fIrewinddir\fP(), +\fIsymlink\fP(), +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<dirent.h>\fP, +\fI<limits.h>\fP, \fI<sys/types.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |