234 lines
8.5 KiB
HTML
234 lines
8.5 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>opendir</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="opendir"></a> <a name="tag_03_411"></a><!-- opendir -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_411_01"></a>NAME</h4>
|
|
|
|
<blockquote>opendir - open a directory</blockquote>
|
|
|
|
<h4><a name="tag_03_411_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/dirent.h.html">dirent.h</a>><br>
|
|
<br>
|
|
DIR *opendir(const char *</tt><i>dirname</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>opendir</i>() function shall open a directory stream corresponding to the directory named by the <i>dirname</i> argument.
|
|
The directory stream is positioned at the first entry. If the type <b>DIR</b> is implemented using a file descriptor, applications
|
|
shall only be able to open up to a total of {OPEN_MAX} files and directories.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>opendir</i>() shall return a pointer to an object of type <b>DIR</b>. Otherwise, a null pointer
|
|
shall be returned and <i>errno</i> set to indicate the error.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>opendir</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EACCES]</dt>
|
|
|
|
<dd>Search permission is denied for the component of the path prefix of <i>dirname</i> or read permission is denied for
|
|
<i>dirname</i>.</dd>
|
|
|
|
<dt>[ELOOP]</dt>
|
|
|
|
<dd>A loop exists in symbolic links encountered during resolution of the <i>dirname</i> argument.</dd>
|
|
|
|
<dt>[ENAMETOOLONG]</dt>
|
|
|
|
<dd>
|
|
The length of the <i>dirname</i> argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.</dd>
|
|
|
|
<dt>[ENOENT]</dt>
|
|
|
|
<dd>A component of <i>dirname</i> does not name an existing directory or <i>dirname</i> is an empty string.</dd>
|
|
|
|
<dt>[ENOTDIR]</dt>
|
|
|
|
<dd>A component of <i>dirname</i> is not a directory.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>opendir</i>() function may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[ELOOP]</dt>
|
|
|
|
<dd>More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the <i>dirname</i> argument.</dd>
|
|
|
|
<dt>[EMFILE]</dt>
|
|
|
|
<dd>{OPEN_MAX} file descriptors are currently open in the calling process.</dd>
|
|
|
|
<dt>[ENAMETOOLONG]</dt>
|
|
|
|
<dd>
|
|
As a result of encountering a symbolic link in resolution of the <i>dirname</i> argument, the length of the substituted pathname
|
|
string exceeded {PATH_MAX}.</dd>
|
|
|
|
<dt>[ENFILE]</dt>
|
|
|
|
<dd>Too many files are currently open in the system.</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_411_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<h5><a name="tag_03_411_06_01"></a>Open a Directory Stream</h5>
|
|
|
|
<p>The following program fragment demonstrates how the <i>opendir</i>() function is used.</p>
|
|
|
|
<pre>
|
|
<tt>#include <sys/types.h>
|
|
#include <dirent.h>
|
|
#include <libgen.h>
|
|
...
|
|
DIR *dir;
|
|
struct dirent *dp;
|
|
...
|
|
if ((dir = opendir (".")) == NULL) {
|
|
perror ("Cannot open .");
|
|
exit (1);
|
|
}
|
|
<br>
|
|
while ((dp = readdir (dir)) != NULL) {
|
|
...
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>opendir</i>() function should be used in conjunction with <a href="../functions/readdir.html"><i>readdir</i>()</a>, <a
|
|
href="../functions/closedir.html"><i>closedir</i>()</a>, and <a href="../functions/rewinddir.html"><i>rewinddir</i>()</a> to
|
|
examine the contents of the directory (see the EXAMPLES section in <a href="readdir.html"><i>readdir</i>()</a> ). This method is
|
|
recommended for portability.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>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 <a href="../functions/closedir.html"><i>closedir</i>()</a> clarifies that if a file descriptor is used for the directory stream,
|
|
it is mandatory that <a href="../functions/closedir.html"><i>closedir</i>()</a> 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>
|
|
|
|
<p>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 <i>a priori</i> 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>
|
|
|
|
<p>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 <i>dirp</i> value or a <b>dirent</b> structure value after a directory
|
|
stream has been closed or after a <a href="../functions/fork.html"><i>fork</i>()</a> or one of the <i><a href=
|
|
"../functions/exec.html">exec</a></i> function calls.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="closedir.html"><i>closedir</i>()</a> , <a href="lstat.html"><i>lstat</i>()</a> , <a href=
|
|
"readdir.html"><i>readdir</i>()</a> , <a href="rewinddir.html"><i>rewinddir</i>()</a> , <a href="symlink.html"><i>symlink</i>()</a>
|
|
, the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/dirent.h.html"><i><dirent.h></i></a>,
|
|
<a href="../basedefs/limits.h.html"><i><limits.h></i></a>, <a href=
|
|
"../basedefs/sys/types.h.html"><i><sys/types.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_411_12"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>In the SYNOPSIS, the optional include of the <a href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> header is
|
|
removed.</p>
|
|
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The requirement to include <a href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> has been removed. Although <a
|
|
href="../basedefs/sys/types.h.html"><i><sys/types.h></i></a> was required for conforming implementations of previous POSIX
|
|
specifications, it was not required for UNIX applications.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The [ELOOP] mandatory error condition is added.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A second [ENAMETOOLONG] is added as an optional error condition.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The following changes were made to align with the IEEE P1003.1a draft standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The [ELOOP] optional error condition is added.</p>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|