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

589 lines
13 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>fchdir()--Change Current Directory by Descriptor</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: -->
<!-- 010301 JTROUS Creation Date, based on chdir.htm -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020514 JET This file has undergone html cleanup -->
<!-- 020618 EMIG Updates for NFS threadsafety, V5R3 -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 040216 JTROUS Fix up authority information, V5R4 -->
<!-- 050323 JTROUS: fix enums, no change flag, V5R4 -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- End Header Records --><!--Java sync-link-->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2> <a name="HDRFCHDIR">fchdir()--Change Current Directory by
Descriptor</a></h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
int fchdir(int <em>fildes</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>fchdir()</strong> function makes the directory named by <em>
fildes</em> the new current directory. If the <strong>fchdir()</strong>
function fails, the current directory is unchanged.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>fildes</em></strong></dt>
<dd>(Input) The file descriptor of the directory.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<p><strong><a name="TBLAFCHDIR">Authorization Required for
fchdir()</a></strong><br>
</p>
<table border width="100%" cellpadding="5">
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="90%">
<img src="delta.gif" alt="Start of change">
The directory named by <em>fildes</em>.
<img src="deltaend.gif" alt="End of change">
</td>
<td align="center" valign="top" width="5%">*X</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
</table>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>fchdir()</strong> was successful.</dd>
<dt><em>-1</em></dt>
<dd><strong>fchdir()</strong> was not successful. The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>fchdir()</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#EBADF">EBADF</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#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#EINTR">EINTR</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#ENOENT">ENOENT</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#ENOTDIR">ENOTDIR</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#ENOTSUP">ENOTSUP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EROOBJ">EROOBJ</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%" cellpadding="5">
<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>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.<br>
</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:<br>
<br>
<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>
</li>
</ul>
<p>The <strong>fchdir()</strong> API operates on two objects: the previous
current working directory and the new one. If either of these objects is
managed by a file system that is not threadsafe, <strong>fchdir()</strong>
fails with the ENOTSAFE error code.</p>
</li>
<li>Network File System Differences
<p>If the local storage of attributes and names is not suppressed (option noac
when the file system is mounted), then one can potentially use the <strong>
fchdir()</strong> API to change to a directory which has been removed. This
depends on how often and when the local storage of attributes and names is
refreshed.</p>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>unistd.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)
</li>
<li>The &lt;<strong>limits.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)
</li>
<li><a href="chdir.htm">chdir()</a>--Change Current Directory
</li>
<li><a href="getcwd.htm">getcwd()</a>--Get Current Directory
</li>
<li><a href="chdiru.htm">QlgChdir()</a>--Change Current Directory
</li>
<li><a href="getcwdu.htm">QlgGetcwd()</a>--Get Current Directory</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 uses <strong>fchdir()</strong>:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;fcntl.h&gt;
main() {
char dir[]="tempfile";
int file_descriptor;
int oflag1 = O_RDONLY | O_CCSID;
mode_t mode = S_IRUSR | S_IWUSR | S_IXUSR;
unsigned int open_ccsid = 37;
if ((file_descriptor = open(dir,oflag1,mode,open_ccsid)) &lt; 0)
perror("open() error");
else {
if (fchdir(file_descriptor) != 0)
perror("fchdir() to tempfile failed");
close(file_descriptor);
}
}
</pre>
<p><strong>Output:</strong></p>
<pre>
fchdir() to tempfile failed: Not a directory.
</pre>
<br>
<hr>
API introduced: V5R2
<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