friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/readdir.htm

665 lines
16 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>readdir()--Read Directory Entry</title>
<!-- Begin Header Records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- file cleaned -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 021021 VONBERGE: Add new qsys.lib usrprf auth reqs. D99381.1 -->
<!-- 050407 JTROUS: fix enums, no change flag, V5R4 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>readdir()--Read Directory Entry</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;dirent.h&gt;
struct dirent *readdir(DIR <em>*dirp</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>readdir()</strong> function returns a pointer to a <samp>
dirent</samp> structure describing the next directory entry in the directory
stream associated with <em>dirp</em>.</p>
<p>A call to <strong>readdir()</strong> overwrites data produced by a previous
call to <strong>readdir()</strong> on the same directory stream. Calls for
different directory streams do not overwrite the data of each other.</p>
<p>If the call to <strong>readdir()</strong> actually reads the directory, the
access time of the directory is updated.</p>
<p><strong>readdir()</strong> performs translation if necessary to convert the
directory entry name into the CCSID (coded character set identifier) of the job
at the time of the call to <strong>opendir()</strong>.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>dirp</em></strong></dt>
<dd>(Input) A pointer to a <samp>DIR</samp> that refers to the open directory
stream to be read. This pointer is returned by <strong>opendir()</strong> (see
<a href="opendir.htm">opendir()</a>--Open Directory).
<p>See <a href="readdiru.htm">QlgReaddir()</a>--Read Directory Entry for a
description and an example of supplying the <em>dirp</em> in any CCSID, using a
<samp>dirent_lg</samp> structure.</p>
</dd>
</dl>
<p>A <samp>dirent</samp> structure has the following contents:</p>
<table border>
<tr>
<td align="left" valign="top" width="15%">char</td>
<td align="left" valign="top" width="15%">d_reserved1[16]</td>
<td align="left" valign="top" width="70%">Reserved.</td>
</tr>
<tr>
<td align="left" valign="top">unsigned int</td>
<td align="left" valign="top">d_fileno_gen_id</td>
<td align="left" valign="top">The generation ID associated with the file
ID.</td>
</tr>
<tr>
<td align="left" valign="top">ino_t</td>
<td align="left" valign="top">d_fileno</td>
<td align="left" valign="top">The file ID of the file. This number uniquely
identifies the object within a file system.</td>
</tr>
<tr>
<td align="left" valign="top">unsigned int</td>
<td align="left" valign="top">d_reclen</td>
<td align="left" valign="top">The length of the directory entry in bytes.</td>
</tr>
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">d_reserved3</td>
<td align="left" valign="top">Reserved.</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">d_reserved4[6]</td>
<td align="left" valign="top">Reserved.</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">d_reserved5[2]</td>
<td align="left" valign="top">Reserved.</td>
</tr>
<tr>
<td align="left" valign="top">qlg_nls_t</td>
<td align="left" valign="top">d_nlsinfo</td>
<td align="left" valign="top">National language information about d_name. The
following fields are defined:
<dl>
<dt><em>int ccsid</em></dt>
<dd>CCSID of the characters in the d_name field.</dd>
<dt><em>char country_id[2]</em></dt>
<dd>Country or region identifier associated with the d_name field.</dd>
<dt><em>char language_id[3]</em></dt>
<dd>Language identifier associated with the d_name field.</dd>
<dt><em>char nls_reserved[3]</em></dt>
<dd>Reserved.</dd>
</dl>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned int</td>
<td align="left" valign="top">d_namelen</td>
<td align="left" valign="top">The length of the name in bytes, excluding the
null terminator.</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">d_name[640]</td>
<td align="left" valign="top">A string that gives the name of a file in the
directory. This string ends in a terminating null, and has a maximum length of
{NAME_MAX} bytes, not including the terminating NULL (see <a href=
"pathconf.htm">pathconf()--Get Configurable Path Name Variables</a>).</td>
</tr>
</table>
<br>
<br>
<h3>Authorities</h3>
<p>No authorization is required. Authorization is verified during <strong>
opendir()</strong>.</p>
<p><strong>Note:</strong>
When reading the contents of the /QSYS.LIB directory, user profile (*USRPRF)
objects to which the caller does not have any authority (i.e., *EXCLUDE)
will not be returned from <strong>readdir()</strong>.</p>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>value</em></dt>
<dd><strong>readdir()</strong> was successful. The value returned is a pointer
to a <samp>dirent</samp> structure describing the next directory entry in the
directory stream.</dd>
<dt><em>NULL pointer</em></dt>
<dd>One of the following has occurred:<br>
<br>
<ul>
<li><strong>readdir()</strong> reached the end of the directory stream. The
<em>errno</em> global variable is not changed.</li>
<li><strong>readdir()</strong> was not successful. The <em>errno</em> is
set.</li>
</ul>
</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>readdir()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file may also fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADF">EBADF</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could indicate one of the following errors:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EADDRNOTAVAIL">EADDRNOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<br>
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
<ol type="1">
<li>The <strong>readdir_r()</strong> API should be used to read a directory
when running in a multithreaded job.<br><br>
</li>
<li>Save the data from <strong>readdir()</strong>, if required, before calling
<strong>closedir()</strong>, because <strong>closedir()</strong> frees the
data.<br><br>
</li>
<li>If the <em>dirp</em> argument passed to <strong>readdir()</strong> does not
refer to an open directory stream, <strong>readdir()</strong> returns the
[EBADF] error.<br><br>
</li>
<li><strong>readdir()</strong> buffers multiple directory entries to improve
performance. This means the directory is not actually read on each call to
<strong>readdir()</strong>. As a result, files that are added to the directory
after <strong>opendir()</strong> or <strong>rewinddir()</strong> may not be
returned on calls to <strong>readdir()</strong>, and files that are removed may
still be returned on calls to <strong>readdir()</strong>.<br><br>
</li>
<li><strong>readdir()</strong> also returns directory entries for dot (.) and
dot-dot (..) subdirectories.<br><br>
</li>
<li>QSYS.LIB and Independent ASP QSYS.LIB File System Differences
<p>Calls to <strong>readdir()</strong> that update the access time of the
directory use the normal rules that apply to libraries and database files. At
most, the access time is updated once per day.</p>
</li>
<li>QDLS File System Differences
<p>The access time of the directory is updated on <strong>opendir()</strong>.
The access time is not affected by <strong>readdir()</strong>.</p>
<p>When objects in QDLS are accessed, the country or region ID and language ID
of the directory entry name are always set to the country or region ID and
language ID of the system.</p>
<p>When a <strong>readdir()</strong> operation specifies the /QDLS directory,
the user must have *USE authority to each child object of the /QDLS directory
(that is, *USE authority to each object immediately below QDLS in the directory
hierarchy). A directory entry is returned only for those objects for which the
user has *USE authority. If the <strong>readdir()</strong> operation specifies
a directory below QDLS, a directory entry is returned for all objects, even if
the user does not have *USE authority for some of the objects.</p>
</li>
<li>QOPT File System Differences
<p>The access time of the directory is not updated on a <strong>
readdir()</strong> operation.</p>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>sys/types.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li>The &lt;<strong>dirent.h</strong>&gt; file see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)</li>
<li><a href="opendir.htm">opendir()</a>--Open Directory</li>
<li><a href="readdiru.htm">QlgReaddir()</a>--Read Directory Entry</li>
<li><a href="rewinddi.htm">rewinddir()</a>--Reset Directory Stream to
Beginning</li>
<li><a href="closedir.htm">closedir()</a>--Close Directory</li>
<li><a href="pathconf.htm">pathconf()-</a>-Get Configurable Path Name
Variables</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example reads the contents of the "root" (/) directory:</p>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;dirent.h&gt;
#include &lt;errno.h&gt;
#include &lt;stdio.h&gt;
main() {
DIR *dir;
struct dirent *entry;
if ((dir = opendir("/")) == NULL)
perror("opendir() error");
else {
puts("contents of root:");
while ((entry = readdir(dir)) != NULL)
printf(" %s\n", entry-&gt;d_name);
closedir(dir);
}
}
</pre>
<p><strong>Output:</strong></p>
<pre>
contents of root:
.
..
QSYS.LIB
QDLS
QOpenSys
QOPT
home
</pre>
<br>
<hr>
API introduced: V3R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink