mirror of https://github.com/mkerrisk/man-pages
158 lines
5.3 KiB
Plaintext
158 lines
5.3 KiB
Plaintext
.\" 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 .
|