1 files changed, 157 insertions, 0 deletions
diff --git a/man3p/opendir.3p b/man3p/opendir.3p
new file mode 100644
index 000000000..b7db3047e
--- /dev/null
+++ b/man3p/opendir.3p
@@ -0,0 +1,157 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "OPENDIR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" opendir 
+.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 .