#include <Qp0lstdi.h> int Qp0lRenameUnlink(const char *old, const char *new);Service Program Name: QP0LLIB1
The Qp0lRenameUnlink() 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, it is removed before old is renamed to new. Therefore, if new specifies the name of an existing directory, the directory must be empty.
If the old argument points to a symbolic link, the symbolic link is renamed. If the new argument points to a symbolic link, the link is removed and old is renamed to new. Qp0lRenameUnlink() does not affect any file or directory named by the contents of the symbolic link.
If old and new both refer to the same file, Qp0lRenameUnlink() returns successfully and performs no other action. See Usage Notes for more information.
When Qp0lRenameUnlink() is successful, it updates the change and modification times for the parent directories of old and new.
If the old object is checked out, Qp0lRenameUnlink() fails with the [EBUSY] error.
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 QlgRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists (using NLS-enabled path name) for a description and an example of supplying the old in any CCSID.
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 process.
See QlgRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists (using NLS-enabled path name) for a description and an example of supplying the new in any CCSID.
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 |
| New object, if it exists | *OBJEXIST | 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 |
| Parent directory of the new object, if it exists, has the S_ISVTX mode bit set to binary one (see Note). | *ALLOBJ, or owner of the new object, or owner of the parent directory of the new 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, Ownership required if new object already exists | EACCES |
| old object if it is a *FILE object type | *OBJMGT, *OBJOPR, Ownership required if new object already exists | 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 |
| new object if object already exists and is not a database file member, *PGM, *MENU, *FILE, *LIB, or *SBSD object type | *OBJEXIST, *OBJMGT | EACCES |
| new object if object already exists and is a *PGM object type | *OBJEXIST, *OBJMGT, *READ | EACCES |
| new object if object already exists and is a *MENU or *FILE object type | *OBJEXIST, *OBJOPR | EACCES |
| new object if object already exists and is a *LIB or *SBSD object type | *OBJEXIST, *OBJMGT, *RX | EACCES |
Authorization Required for Qp0lRenameUnlink() 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 Qp0lRenameUnlink() in the QOPT File System
| Object Referred to | Authority Required | errno |
|---|---|---|
| Volume to be renamed | *ALL | EACCES |
| Volume containing object to be renamed | *CHANGE | EACCES |
| Object within volume | None | None |
If Qp0lRenameUnlink() 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] | |
| [ENAMETOOLONG] | |
| [ENEWJRN] | |
| [ENEWJRNRCV] | |
| [ENOTAVAIL] | |
| [ENOTEMPTY] | |
| [ENOENT] | |
| [ENOMEM] | |
| [ENOSPC] | |
| [ENOTDIR] | |
| [ENOTSAFE] | |
| [ENOTSUP] | |
| [EMLINK] |
old is a directory and the link count of the parent directory of new would exceed LINK_MAX. |
| [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] |
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. |
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:
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 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.
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.
If the object identified by the new path name exists, QDLS returns the [EEXIST] error.
You can rename only a volume or a file, not a directory.
If the object identified by the new path name exists, QOPT returns the [EEXIST] error.
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.
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.
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.
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 Qp0lRenameUnlink().
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 ( Qp0lRenameUnlink( argv[1], argv[2] ) != 0
perror ( "Could not rename file" );
}