The rename callable service changes the name of a file or a directory.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1REN): | 31-bit |
AMODE (BPX4REN): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4REN with the same parameters.
The name of a fullword that contains the length of the pathname of the file or directory that is to be renamed.
The name of a field, of length Old_name_length, that contains the name of the existing file or directory.
The name of a fullword that contains the length of the pathname that is to be given to the existing file or directory.
The name of a field, of length New_name_length, that contains the new pathname of the file or directory.
The name of a fullword in which the rename service returns 0 if the request is successful, or -1 if it is not successful.
Return_code | Explanation |
---|---|
EACCES | One of the following conditions occurred:
|
EAGAIN | One of the files or directories was temporarily unavailable. The following reason code can accompany the return code: JRInvalidVnode. |
EBUSY | Old_name and New_name specify directories but one of them cannot be renamed because it is in use as a root or a mount point, or the file is open by a remote NFS client with a share reservation that conflicts with the requested operation. The following reason code can accompany the return code: JRIsFSRoot. |
EINVAL | This error is returned for one of the following reasons:
The following reason codes can accompany the return code: JRDotOrDotDot and JROldPartOfNew. |
EISDIR | New_name identifies a directory, but Old_name is not a directory. The following reason code can accompany the return code: JRNewIsDir. |
ELOOP | A loop exists in symbolic links that were encountered during resolution of the Old_name or New_name argument. This error is issued if more than 24 symbolic links are detected in the resolution of Old_name or New_name. |
ENAMETOOLONG | Old_name or New_name is longer than 1023 bytes; or a component of one of those names is longer than 255 bytes. Name truncation is not supported. |
ENOENT | No file or directory name Old_name was found; or either Old_name or New_name was not specified. The following reason code can accompany the return code: JROldNoExist. |
ENOSPC | The directory that is intended to contain New_name cannot be extended. |
ENOTDIR | A component of either pathname prefix is not a directory; or Old_name is a directory and New_name is a file that is not a directory. The following reason code can accompany the return code: JRNewNotDir. |
ENOTEMPTY | New_name specifies a directory, but the directory is not empty. It contains files or subdirectories. |
EROFS | Performing the requested service would make it necessary to write on a read-only file system. The following reason code can accompany the return code: JRReadOnlyFS. |
EXDEV | Old_name and New_name identify files or directories on different file systems. Renaming across file systems is not supported. The following reason code can accompany the return code: JRDiffFileSets. |
The name of a fullword in which the rename service stores the reason code. The rename service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
For renaming to succeed, the calling process needs write permission for the directory that contains Old_name and the directory that contains New_name. If Old_name and New_name are the names of directories, the caller does not need write permission for the directories themselves.
There are no restrictions on the use of the rename service.
For an example using this callable service, see BPX1REN (rename) example.