rename (BPX1REN, BPX4REN) — Rename a file or directory

Function

The rename callable service changes the name of a file or a directory.

Requirements

Parameters

Old_name_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the pathname of the file or directory that is to be renamed.

Old_name

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Old_name_length parameter

The name of a field, of length Old_name_length, that contains the name of the existing file or directory.

New_name_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the pathname that is to be given to the existing file or directory.

New_name

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the New_name_length parameter

The name of a field, of length New_name_length, that contains the new pathname of the file or directory.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

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

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the rename service stores the return code. The rename service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The rename service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	One of the following conditions occurred: The process did not have search permission on some component of the old or new pathname; or did not have write permission on the parent directory of the file or directory that is to be renamed. The S_ISVTX flag is set for the directory that contains Old_name. The caller is neither the owner of Old_name nor the owner of the parent directory, nor does the caller have appropriate privileges (see Authorization). New_name refers to an existing file. The S_ISVTX flag is set for the directory containing New_name, and the caller is neither the owner of New_name nor the owner of the parent directory, nor does the caller have appropriate privileges.
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: Old_name is part of the pathname prefix of New_name. Old_name refers to either . (dot) or .. (dot-dot). New_name refers to either . (dot) or .. (dot-dot). 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.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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.

Usage notes

1. The rename service changes the name of a file or directory from Old_name to New_name. When the renaming request completes successfully, the change and modification times for the parent directories of Old_name and New_name are updated.

   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.

2. If the S_ISVTX flag is set for the directory that contains Old_name, one of the following conditions must be true, or the request will fail with EACCES:
   • The caller is the owner of the file named Old_name
   • The caller is the owner of the parent directory that contains Old_name
   • The caller has appropriate privileges (see Authorization)
   If the S_ISVTX flag is set for the directory that contains New_name, where New_name refers to an existing file, one of the following conditions must be true, or the request will fail with EACCES:

   • The caller is the owner of the file named New_name
   • The caller is the owner of the parent directory containing New_name
   • The caller has appropriate privileges
3. Renaming files:
   • If Old_name and New_name are links that refer to the same file, the rename service simply returns successfully.
   • If Old_name is the name of a file, New_name must also name a file, not a directory. If New_name is an existing file, it is unlinked, and then the file that is specified as Old_name is given New_name. The pathname New_name always stays in existence. At the beginning of the operation, New_name refers to its original file, and at the end, it refers to the file that used to be Old_name.
   • The rename will fail with EBUSY if New_name refers to an existing file that is currently open by a remote NFS client with a share reservation that prevents the file from being opened for writing. Refer to open (BPX1OPN, BPX4OPN) — Open a file for details about the NFS share reservations.
4. Renaming directories:
   • If Old_name is the name of a directory, New_name must also name a directory, not a file. If New_name is an existing directory, it must be empty, containing no files or subdirectories. If it is empty, it is removed, as described in rmdir (BPX1RMD, BPX4RMD) — Remove a directory.
   • New_name cannot be a directory under Old_name; that is, the old directory cannot be part of the pathname prefix of the new one.

Related services

• link (BPX1LNK, BPX4LNK) — Create a link to a file
• rmdir (BPX1RMD, BPX4RMD) — Remove a directory
• unlink (BPX1UNL, BPX4UNL) — Remove a directory entry

Characteristics and restrictions

There are no restrictions on the use of the rename service.