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/renamekp.htm

1150 lines
29 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>Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It
Exists</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: -->
<!-- 010320 JTROUS Include Journal ERRNOs, should have in V5R1 -->
<!-- 010503 JTROUS Add new Usage note, V5R2a, 98761 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020131 JTROUS Changes from API Review 3, V5R2 -->
<!-- 020524 VONBERGE Updated QSYS.LIB authorities table -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 020829 RTHEIS : S_ISVTX mode bit, V5R3 -->
<!-- 021216 JTROUS : Add EDATALINK errno,usage note, V5R3 -->
<!-- 050406 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>Qp0lRenameKeep()--Rename File or Directory, Keep "new"
If It Exists</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;Qp0lstdi.h&gt;
int Qp0lRenameKeep(const char <em>*old</em>, const char <em>*new</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="#HDRrnmkpUS">Usage
Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>Qp0lRenameKeep()</strong> function renames a file or a directory
specified by <em>old</em> to the name given by <em>new</em>. The <em>old</em>
pointer must specify the name of an existing file or directory. Both <em>
old</em> and <em>new</em> must be of the same type; that is, both directories
or both files. The last element of <em>old</em> and <em>new</em> must not be
"dot" (.) or "dot-dot" (..).</p>
<p>If <em>new</em> already exists, <strong>Qp0lRenameKeep()</strong> fails with
the [EEXIST] error.</p>
<p>If the <em>old</em> argument points to a symbolic link, the symbolic link is
renamed. <strong>Qp0lRenameKeep()</strong> does not affect any file or
directory named by the contents of the symbolic link. See <a href=
"#HDRrnmkpUS">Usage Notes</a> for more information.</p>
<p>When <strong>Qp0lRenameKeep()</strong> is successful, it updates the change
and modification times for the parent directories of <em>old</em> and <em>
new</em>.</p>
<p>If the <em>old</em> object is checked out, <strong>Qp0lRenameKeep()</strong>
fails with the [EBUSY] error.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>old</em></strong></dt>
<dd>(Input) A pointer to the null-terminated path name of the file to be
renamed.
<p>This parameter is assumed to be represented in the CCSID (coded character
set identifier) currently in effect for the job. If the CCSID of the job is
65535, this parameter is assumed to be represented in the default CCSID of the
job.</p>
<p>See <a href="renamekpu.htm">QlgRenameKeep()--Rename File or Directory, Keep
"new" If It Exists (using NLS-enabled path name)</a> for a description and an
example of supplying the <em>old</em> in any CCSID.</p>
<br>
</dd>
<dt><strong><em>new</em></strong></dt>
<dd>(Input) A pointer to the null-terminated path name of the new name of the
file.
<p>This parameter is assumed to be represented in the CCSID currently in effect
for the job. If the CCSID of the job is 65535, this parameter is assumed to be
represented in the default CCSID of the job.</p>
<p>The new file name is assumed to be represented in the language and country
or region currently in effect for the job.</p>
<p>See <a href="renamekpu.htm">QlgRenameKeep()--Rename File or Directory, Keep
"new" If It Exists (using NLS-enabled path name)</a> for a description and an
example of supplying the <em>new</em> in any CCSID.</p>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<p><strong><a name="TBLARNMKP">Authorization Required for Qp0lRenameKeep()
(excluding QSYS.LIB, independent ASP QSYS.LIB, QDLS, and QOPT)</a></strong></p>
<br>
<table border width="100%">
<!-- 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">Each directory in <em>old</em> path
name preceding the object to be renamed</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>old</em>
object</td>
<td align="left" valign="top">*WX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top"><em>old</em> object if it is a
directory</td>
<td align="left" valign="top">*OBJMGT + *W</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top"><em>old</em> object if it is not a
directory</td>
<td align="left" valign="top">*OBJMGT</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Each directory in <em>new</em> path
name preceding the object</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>new</em>
object</td>
<td align="left" valign="top">*WX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of the
<em>old</em> object has the S_ISVTX mode bit set to binary one (see <b>Note</b>).</td>
<td align="left" valign="top">*ALLOBJ, or owner of the <em>old</em>
object, or owner of the parent directory of the <em>old</em> object</td>
<td align="left" valign="top">EPERM</td>
</tr>
</table>
<p><b>Note:</b> The S_ISVTX mode bit
(which is equivalent to the 'Restricted rename and unlink' object attribute)
restriction only applies to objects in the "root" (/), QOpenSys, and user-defined file systems.</p>
<br>
<p><strong><a name="TBLARNMKP2">Authorization Required for Qp0lRenameKeep() in
the QSYS.LIB and independent ASP QSYS.LIB File Systems</a></strong></p>
<table border width="100%">
<!-- 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">Each directory in <em>old</em> path
name preceding the object to be renamed</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>old</em>
object if the object is a database file member</td>
<td align="left" valign="top">*OBJMGT</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of the parent
directory of <em>old</em> object if the object is a database file member</td>
<td align="left" valign="top">*UPD</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>old</em>
object if the object is not a database file member</td>
<td align="left" valign="top">*RWX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top"><em>old</em> object if it is a
database file member</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
<tr>
<td align="left" valign="top"><em>old</em> object if it is not a
database file member</td>
<td align="left" valign="top">*OBJMGT</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Each directory in <em>new</em> path
name preceding the object</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>new</em>
object if object is not a database file member</td>
<td align="left" valign="top">*RWX</td>
<td align="left" valign="top">EACCES</td>
</tr>
</table>
<br>
<p><strong><a name="TBLARNMKP3">Authorization Required for Qp0lRenameKeep() in
the QDLS File System</a></strong></p>
<table border width="100%">
<!-- 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">Each directory in <em>old</em> path
name preceding the object to be renamed</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>old</em>
object</td>
<td align="left" valign="top">*CHANGE</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top"><em>old</em> object</td>
<td align="left" valign="top">*ALL</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Each directory in <em>new</em> path
name preceding the object</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of <em>new</em>
object</td>
<td align="left" valign="top">*CHANGE</td>
<td align="left" valign="top">EACCES</td>
</tr>
</table>
<br>
<p><strong><a name="TBLARNMKP4">Authorization Required for Qp0lRenameKeep() in
the QOPT File System</a></strong></p>
<table border width="100%">
<!-- 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">Volume authorization list for volume
to be renamed in a media library device</td>
<td align="left" valign="top">*ALL</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Volume authorization list for volume
to be renamed in a stand alone device</td>
<td align="left" valign="top">*CHANGE</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Volume authorization list for volume
containing object to be renamed</td>
<td align="left" valign="top">*CHANGE</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Root directory (/) of volume to be
renamed if volume media format is Universal Disk Format (UDF)</td>
<td align="left" valign="top">*RWX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Each directory in old path name
preceding the object to be renamed if volume media format is Universal Disk
Format (UDF)</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of old object if
volume media format is Universal Disk Format (UDF)</td>
<td align="left" valign="top">*WX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Old object if volume media format is
Universal Disk Format (UDF)</td>
<td align="left" valign="top">*W</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Each directory in new path name
preceding the object if volume media format is Universal Disk Format (UDF)</td>
<td align="left" valign="top">*X</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of new object if
volume media format is Universal Disk format (UDF)</td>
<td align="left" valign="top">*WX</td>
<td align="left" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object and parent directories if
volume media format is not Universal Disk format (UDF)</td>
<td align="left" valign="top">None</td>
<td align="left" valign="top">None</td>
</tr>
</table>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>Qp0lRenameKeep()</strong> was successful.</dd>
<dt><em>-1</em></dt>
<dd><strong>Qp0lRenameKeep()</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>Qp0lRenameKeep()</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#EBADNAME">EBADNAME</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#ECONVERT">ECONVERT</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#EDATALINK">EDATALINK</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EEXIST">EEXIST</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#EFILECVT">EFILECVT</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">
<p>For example, may be returned if
the directories preceding the object to be renamed in the <em>old</em> path
name are part of <em>new</em>, or if either name refers to dot or dot-dot.</p>
</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#EISDIR">EISDIR</a>]</em></td>
<td align="left" valign="top">
<p><em>new</em> is a directory, but <em>old</em> is not a
directory.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNDAMAGE">EJRNDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNENTTOOLONG">EJRNENTTOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNINACTIVE">EJRNINACTIVE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EJRNRCVSPC">EJRNRCVSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EMLINK">EMLINK</a>]</em></td>
<td align="left" valign="top">
<p><em>old</em> is a directory and the link count of the parent directory of
<em>new</em> would exceed LINK_MAX.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENEWJRN">ENEWJRN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENEWJRNRCV">ENEWJRNRCV</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#ENOMEM">ENOMEM</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#EPERM">EPERM</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>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EXDEV">EXDEV</a>]</em></td>
<td align="left" valign="top">
<p><em>old</em> and <em>new</em> identify files or directories in different
file systems. Links between different file systems are not allowed.</p>
</td>
</tr>
</table>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could also 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#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>
<br>
<h3><a name="HDRrnmkpUS">Usage Notes</a></h3>
<ol type="1">
<li>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
<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:
<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>
<br>
</li>
<li>About the Rename Functions
<p>The integrated file system provides two functions that rename a file or
directory. Both rename the <em>old</em> path name to a <em>new</em> path name.
The difference is determined by what happens when <em>new</em> already
exists:</p>
<ul>
<li>If <em>new</em> already exists when using <strong>
Qp0lRenameKeep()</strong>, the rename fails with the [EEXIST] error.<br>
</li>
<li>If <em>new</em> already exists when using <strong>
Qp0lRenameUnlink()</strong>, the existing path name is unlinked (removed)
before <em>old</em> is renamed to <em>new</em>.</li>
</ul>
<p>These functions are defined in the <strong>&lt;Qp0lstdi.h&gt;</strong>
header file. When <strong>&lt;Qp0lstdi.h&gt;</strong> is included, the <strong>
rename()</strong> function is defined to be either <strong>
Qp0lRenameUnlink()</strong> or <strong>Qp0lRenameKeep()</strong>, depending on
the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros:</p>
<ul>
<li>When _POSIX_SOURCE and _POSIX1_SOURCE are <strong>not</strong> defined,
<strong>rename()</strong> is defined to be <strong>Qp0lRenameKeep()</strong>.
Either <strong>rename()</strong> or <strong>Qp0lRenameKeep()</strong> can be
used to rename a file or directory with the semantics of <strong>
Qp0lRenameKeep()</strong>.<br>
</li>
<li>When _POSIX_SOURCE or _POSIX1_SOURCE is defined, <strong>rename()</strong>
is defined to be <strong>Qp0lRenameUnlink()</strong>. Either <strong>
rename()</strong> or <strong>Qp0lRenameUnlink()</strong> can be used to rename
a file or directory with the semantics of <strong>
Qp0lRenameUnlink()</strong>.</li>
</ul>
<p>When the <strong>&lt;Qp0lstdi.h&gt;</strong> header file is <strong>
not</strong> included, <strong>rename()</strong> operates only on database
files in the QSYS.LIB and independent ASP QSYS.LIB file systems, as it did
before the introduction of the integrated file system.</p>
<br>
</li>
<li>QSYS.LIB and Independent ASP QSYS.LIB File System Differences
<ul>
<li>When a database member is being renamed, the part of the <em>new</em> path
name preceding the object must be the same as that of the <em>old</em> path
name. That is, the sequence of "directories" (library and file) preceding the
object in the <em>new</em> path name must be the same as the sequence of
directories preceding the object in the <em>old</em> path name.<br>
</li>
<li>The following object types cannot be renamed when there are secondary
threads active in the job: *CFGL, *CNNL, *CTLD, *DEVD, *LIND, *NWID. The
operation will fail with error code [ENOTSAFE].</li>
<li>When a library is being renamed, the part of the <em>new</em> path name
preceding the object must be the same as that of the <em>old</em> path name.
That is, the sequence of "directories" (/QSYS.LIB or /asp_name/QSYS.LIB, where
asp_name is the independent Auxiliary Storage Pool name) preceding the object
in the <em>new</em> path name must be the same as the sequence of directories
preceding the object in the <em>old</em> path name [EINVAL].</li>
</ul>
<br>
</li>
<li>QDLS File System Differences
<p>When a folder is being renamed, the part of the <em>new</em> path name
preceding the object must be the same as that of the <em>old</em> path name.
That is, a folder must remain in the same parent folder.</p>
<br>
</li>
<li>QOPT File System Differences
<p>You can rename only a volume or a file, not a directory.</p>
<br>
</li>
<li>QFileSvr.400 File System Differences
<p>You cannot rename the first-level directory. For example, you cannot rename
<samp>Dir1</samp> in the path name <samp>/QFileSvr.400/Dir1/Dir2/Object</samp>.
The first-level directory identifies the target system in a communications
connection.</p>
<br>
</li>
<li>QNetWare File System Differences
<p>The new and old files or directories must exist on the same NetWare server.
This function cannot be used to move data from one server to another.</p>
<br>
</li>
<li>QNTC File System Differences
<p>The <em>new</em> and the <em>old</em> files or directories must exist on the
same Windows NT server. This function cannot be used to move data from one
server to another.<br>
</p>
<br>
</li>
<li>"Root" (/) and User-defined File System Differences
<p>If the file being renamed is in the "root" (/) file system or in a monocase
user-defined file system, and the file system has the *TYPE2 directory format,
and both <em>old</em> and <em>new</em> refer to the same link, but their case
is different (eg. /ABC and /Abc), Qp0lRenameUnlink() changes the link name to
the <em>new</em> name.</p>
</li>
<li>The file cannot be renamed if the file is a DataLink column
in an SQL table and a row in that SQL table references this file.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>stdio.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
</li>
<li>The &lt;<strong>Qp0lstdi.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)<br>
</li>
<li><a href="pathconf.htm">pathconf()</a>--Get Configurable Path Name
Variables<br>
</li>
<li><a href="renamefs.htm">rename()</a>--Rename File or Directory<br>
</li>
<li><a href="renamekpu.htm">QlgRenameKeep()</a>--Rename File or Directory, Keep
"new" If It Exists (using NLS-enabled path name)<br>
</li>
<li><a href="renameun.htm">Qp0lRenameUnlink()</a>--Rename File or Directory,
Unlink "new" If It Exists</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>When you pass two file names to this example, it will try to change the file
name from the first name to the second using <strong>
Qp0lRenameKeep()</strong>.</p>
<pre>
#include &lt;Qp0lstdi.h&gt;
int main(int argc, char ** argv ) {
if ( argc != 3 )
printf( "Usage: %s old_fn new_fn\n", argv[0] );
else if ( Qp0lRenameKeep( argv[1], argv[2] ) != 0
perror ( "Could not rename file" );
}
</pre>
<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