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

727 lines
18 KiB
HTML
Raw Permalink 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_r()--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 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 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_r()--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;
int readdir_r(DIR <em>*dirp</em>, struct dirent <em>*entry</em>,
struct dirent <em>**result</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: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>readdir_r()</strong> function initializes the <samp>
dirent</samp> structure that is referenced by <em>entry</em> to represent the
next directory entry in the directory stream that is associated with <em>
dirp</em>. The <strong>readdir_r()</strong> function then stores a pointer to
the <em>entry</em> structure at the location referenced by <em>result</em>.</p>
<p>The storage pointed to by <em>entry</em> must be large enough for a <samp>
dirent</samp> structure.</p>
<p>If the call to <strong>readdir_r()</strong> actually reads the directory,
the access time of the directory is updated.</p>
<p>The <strong>readdir_r()</strong> function performs translation, if
necessary, to convert the directory entry name into the coded character set
identifier (CCSID) 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.</p>
<br>
</dd>
<dt><strong><em>entry</em></strong></dt>
<dd>(Output) A pointer to a <samp>dirent</samp> structure in which the
directory entry is to be placed.<br>
</dd>
<dt><strong><em>result</em></strong></dt>
<dd>(Output) A pointer to a pointer to a <samp>dirent</samp> structure. Upon
successfully reading a directory entry, this <samp>dirent</samp> pointer is set
to the same value as <em>entry</em>. Upon reaching the end of the directory
stream, this pointer will be set to NULL.</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 that is associated with the d_name field.</dd>
<dt><em>char language_id[3]</em></dt>
<dd>Language identifier that is 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>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>readdir_r()</strong> was successful. The <em>result</em> parameter
points to one of the following:<br>
<br>
<ul>
<li>A pointer to a <samp>dirent</samp> structure that describes the next
directory entry in the directory stream. This will be the same value as the
<em>entry</em> parameter.</li>
<li>A NULL pointer. <strong>readdir_r()</strong> reached the end of the
directory stream. The <em>errno</em> global variable is not changed.</li>
</ul>
</dd>
<dt><em>error code</em></dt>
<dd><strong>readdir_r()</strong> was not successful. This value is set to the
same value as the <em>errno</em> global variable.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>readdir_r()</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>
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
<ol type="1">
<li>
<p>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:</p>
<ul>
<li>Where multiple threads exist in the job.</li>
<li>The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QOPT</li>
<li>Network File System</li>
<li>QFileSvr.400</li>
</ul>
<br>
</li>
</ul>
<br>
</li>
<li>
<p><strong>readdir_r()</strong> is threadsafe only when directed to a directory
in a threadsafe file system.</p>
</li>
<li>
<p>If the <em>dirp</em> argument that is passed to <strong>readdir_r()</strong>
does not refer to an open directory stream, <strong>readdir_r()</strong>
returns the [EBADF] error.</p>
</li>
<li>
<p><strong>readdir_r()</strong> caches multiple directory entries to improve
performance. This means the directory is not actually read on each call to
<strong>readdir_r()</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_r()</strong>, and files that are
removed may still be returned on calls to <strong>readdir_r()</strong>.</p>
</li>
<li>
<p><strong>readdir_r()</strong> also returns directory entries for dot (.) and
dot-dot (..) subdirectories.</p>
</li>
<li>
<p>QSYS.LIB and Independent ASP QSYS.LIB File System Differences</p>
<p>Calls to <strong>readdir_r()</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>
<p>QDLS File System Differences</p>
<p>The access time of the directory is updated on <strong>opendir()</strong>.
The access time is not affected by <strong>readdir_r()</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_r()</strong> operation specifies the /QDLS directory,
the user must have *USE authority to each object in 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_r()</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>
<p>QOPT File System Differences</p>
<p>The access time of the directory is not updated on a <strong>
readdir_r()</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>) &gt;</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="readdirrts64.htm">readdir_r_ts64()</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() {
int return_code;
DIR *dir;
struct dirent entry;
struct dirent *result;
if ((dir = opendir("/")) == NULL)
perror("opendir() error");
else {
puts("contents of root:");
for (return_code = readdir_r(dir, &amp;entry, &amp;result);
result != NULL &amp;&amp; return_code == 0;
return_code = readdir_r(dir, &amp;entry, &amp;result))
printf(" %s\n", entry.d_name);
if (return_code != 0)
perror("readdir_r() error");
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