Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists
Syntax
#include <Qp0lstdi.h> int Qp0lRenameKeep(const char *old, const char *new);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The Qp0lRenameKeep() function renames a file or a directory specified by old to the name given by new. The old pointer must specify the name of an existing file or directory. Both old and new must be of the same type; that is, both directories or both files. The last element of old and new must not be "dot" (.) or "dot-dot" (..).
If new already exists, Qp0lRenameKeep() fails with the [EEXIST] error.
If the old argument points to a symbolic link, the symbolic link is renamed. Qp0lRenameKeep() does not affect any file or directory named by the contents of the symbolic link. See Usage Notes for more information.
When Qp0lRenameKeep() is successful, it updates the change and modification times for the parent directories of old and new.
If the old object is checked out, Qp0lRenameKeep() fails with the [EBUSY] error.
Parameters
- old
- (Input) A pointer to the null-terminated path name of the file to be
renamed.
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.
See QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path name) for a description and an example of supplying the old in any CCSID.
- new
- (Input) A pointer to the null-terminated path name of the new name of the
file.
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.
The new file name is assumed to be represented in the language and country or region currently in effect for the job.
See QlgRenameKeep()--Rename File or Directory, Keep "new" If It Exists (using NLS-enabled path name) for a description and an example of supplying the new in any CCSID.
Authorities
Note: Adopted authority is not used.
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in old path name preceding the object to be renamed | *X | EACCES |
Parent directory of old object | *WX | EACCES |
old object if it is a directory | *OBJMGT + *W | EACCES |
old object if it is not a directory | *OBJMGT | EACCES |
Each directory in new path name preceding the object | *X | EACCES |
Parent directory of new object | *WX | EACCES |
Parent directory of the old object has the S_ISVTX mode bit set to binary one (see Note). | *ALLOBJ, or owner of the old object, or owner of the parent directory of the old object | EPERM |
Note: 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.
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in old path name preceding the object to be renamed | *X | EACCES |
Parent directory of old object if the object is a database file member | *OBJMGT | EACCES |
Parent directory of the parent directory of old object if the object is a database file member | *UPD | EACCES |
Parent directory of old object if the object is not a database file member | *RWX | EACCES |
old object if it is a database file member | None | None |
old object if it is not a database file member | *OBJMGT | EACCES |
Each directory in new path name preceding the object | *X | EACCES |
Parent directory of new object if object is not a database file member | *RWX | EACCES |
Authorization Required for Qp0lRenameKeep() in the QDLS File System
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in old path name preceding the object to be renamed | *X | EACCES |
Parent directory of old object | *CHANGE | EACCES |
old object | *ALL | EACCES |
Each directory in new path name preceding the object | *X | EACCES |
Parent directory of new object | *CHANGE | EACCES |
Authorization Required for Qp0lRenameKeep() in the QOPT File System
Object Referred to | Authority Required | errno |
---|---|---|
Volume authorization list for volume to be renamed in a media library device | *ALL | EACCES |
Volume authorization list for volume to be renamed in a stand alone device | *CHANGE | EACCES |
Volume authorization list for volume containing object to be renamed | *CHANGE | EACCES |
Root directory (/) of volume to be renamed if volume media format is Universal Disk Format (UDF) | *RWX | EACCES |
Each directory in old path name preceding the object to be renamed if volume media format is Universal Disk Format (UDF) | *X | EACCES |
Parent directory of old object if volume media format is Universal Disk Format (UDF) | *WX | EACCES |
Old object if volume media format is Universal Disk Format (UDF) | *W | EACCES |
Each directory in new path name preceding the object if volume media format is Universal Disk Format (UDF) | *X | EACCES |
Parent directory of new object if volume media format is Universal Disk format (UDF) | *WX | EACCES |
Object and parent directories if volume media format is not Universal Disk format (UDF) | None | None |
Return Value
- 0
- Qp0lRenameKeep() was successful.
- -1
- Qp0lRenameKeep() was not successful. The errno global variable is set to indicate the error.
Error Conditions
If Qp0lRenameKeep() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
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. |
[EAGAIN] | |
[EBADFID] | |
[EBADNAME] | |
[EBUSY] | |
[ECONVERT] | |
[EDAMAGE] | |
[EDATALINK] | |
[EEXIST] | |
[EFAULT] | |
[EFILECVT] | |
[EINTR] | |
[EINVAL] |
For example, may be returned if the directories preceding the object to be renamed in the old path name are part of new, or if either name refers to dot or dot-dot. |
[EIO] | |
[EISDIR] |
new is a directory, but old is not a directory. |
[EJRNDAMAGE] | |
[EJRNENTTOOLONG] | |
[EJRNINACTIVE] | |
[EJRNRCVSPC] | |
[ELOOP] | |
[EMLINK] |
old is a directory and the link count of the parent directory of new would exceed LINK_MAX. |
[ENAMETOOLONG] | |
[ENEWJRN] | |
[ENEWJRNRCV] | |
[ENOENT] | |
[ENOMEM] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTDIR] | |
[ENOTSAFE] | |
[ENOTSUP] | |
[EPERM] | |
[EROOBJ] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] | |
[EXDEV] |
old and new identify files or directories in different file systems. Links between different file systems are not allowed. |
If interaction with a file server is required to access the object, errno could also indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
- Where multiple threads exist in the job.
- 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:
- "Root" (/)
- QOpenSys
- User-defined
- QNTC
- QSYS.LIB
- Independent ASP QSYS.LIB
- QOPT
- Network File System
- QFileSvr.400
- Where multiple threads exist in the job.
- About the Rename Functions
The integrated file system provides two functions that rename a file or directory. Both rename the old path name to a new path name. The difference is determined by what happens when new already exists:
- If new already exists when using
Qp0lRenameKeep(), the rename fails with the [EEXIST] error.
- If new already exists when using Qp0lRenameUnlink(), the existing path name is unlinked (removed) before old is renamed to new.
These functions are defined in the <Qp0lstdi.h> header file. When <Qp0lstdi.h> is included, the rename() function is defined to be either Qp0lRenameUnlink() or Qp0lRenameKeep(), depending on the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros:
- When _POSIX_SOURCE and _POSIX1_SOURCE are not defined,
rename() is defined to be Qp0lRenameKeep().
Either rename() or Qp0lRenameKeep() can be
used to rename a file or directory with the semantics of
Qp0lRenameKeep().
- When _POSIX_SOURCE or _POSIX1_SOURCE is defined, rename() is defined to be Qp0lRenameUnlink(). Either rename() or Qp0lRenameUnlink() can be used to rename a file or directory with the semantics of Qp0lRenameUnlink().
When the <Qp0lstdi.h> header file is not included, rename() 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.
- If new already exists when using
Qp0lRenameKeep(), the rename fails with the [EEXIST] error.
- QSYS.LIB and Independent ASP QSYS.LIB File System Differences
- When a database member is being renamed, the part of the new path
name preceding the object must be the same as that of the old path
name. That is, the sequence of "directories" (library and file) preceding the
object in the new path name must be the same as the sequence of
directories preceding the object in the old path name.
- 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].
- When a library is being renamed, the part of the new path name preceding the object must be the same as that of the old 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 new path name must be the same as the sequence of directories preceding the object in the old path name [EINVAL].
- When a database member is being renamed, the part of the new path
name preceding the object must be the same as that of the old path
name. That is, the sequence of "directories" (library and file) preceding the
object in the new path name must be the same as the sequence of
directories preceding the object in the old path name.
- QDLS File System Differences
When a folder is being renamed, the part of the new path name preceding the object must be the same as that of the old path name. That is, a folder must remain in the same parent folder.
- QOPT File System Differences
You can rename only a volume or a file, not a directory.
- QFileSvr.400 File System Differences
You cannot rename the first-level directory. For example, you cannot rename Dir1 in the path name /QFileSvr.400/Dir1/Dir2/Object. The first-level directory identifies the target system in a communications connection.
- QNTC File System Differences
The new and the old files or directories must exist on the same Windows NT® server. This function cannot be used to move data from one server to another.
- "Root" (/) and User-defined File System Differences
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 old and new refer to the same link, but their case is different (eg. /ABC and /Abc), Qp0lRenameUnlink() changes the link name to the new name.
- 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.
Related Information
- The <stdio.h> file (see Header
Files for UNIX®-Type Functions)
- The <Qp0lstdi.h> file (see
Header Files for UNIX-Type Functions)
- pathconf()--Get Configurable Path Name
Variables
- rename()--Rename File or Directory
- QlgRenameKeep()--Rename File or Directory, Keep
"new" If It Exists (using NLS-enabled path name)
- Qp0lRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists
Example
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 Qp0lRenameKeep().
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <Qp0lstdi.h> 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" ); }
API introduced: V3R1