v_rename (BPX1VRN, BPX4VRN) — Rename a file or directory

Function

The v_rename service renames a file or a directory that is specified by the Old_name parameter in the directory that is represented by Old_directory_vnode_token to the name that is specified by the New_name parameter in the directory that is represented by New_directory_vnode_token.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1VRN):	31-bit
AMODE (BPX4VRN):	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.

Format

CALL BPX1VRN,(Old_directory_vnode_token,
              OSS,
              Old_name_length,
              Old_name,
              New_directory_vnode_token,
              New_name_length,
              New_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4VRN with the same parameters.

Parameters

Old_directory_vnode_token

Supplied parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area that contains a vnode token that represents the directory in which the file or directory that is to be renamed exists.

OSS

Supplied and returned parameter

Type:: Structure
Length:: OSS#LENGTH (from the BPXYOSS macro)

The name of an area that contains operating system specific parameters. This area is mapped by the BPXYOSS macro, see BPXYOSS — Map operating system specific information.

Old_name_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the file or directory name that is to be renamed. The name can be up to 255 bytes long.

Old_name

Supplied parameter

Type:: Character string
Length:: Specified by Old_name_length parameter

The name of an area, of length Old_name_length, that contains the file or directory name that is to be renamed. It must not contain null characters (X'00').

New_directory_vnode_token

Supplied parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area that contains a vnode token that represents the directory in which the renamed file or directory is to exist.

New_name_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the file or directory name to which the file or directory is to be renamed. The name can be up to 255 bytes long.

New_name

Supplied parameter

Type:: Character string
Length:: Specified by New_name_length parameter

The name of an area, of length New_name_length, that contains the file or directory name to which the file or directory is to be renamed. It must not contain null characters (X'00').

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_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 v_rename service stores the return code. The v_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 v_rename service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The calling process does not have permission to write in a specified directory.
EAGAIN	One of the files or directories was temporarily unavailable. The following reason code can accompany the return code: JRInvalidVnode.
EBUSY	The name that was specified is in use as 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	Parameter error—for example, attempting to rename a file named "`..`" The following reason codes can accompany the return code: JRDotorDotDot, JrOldPartOfNew, JrNoName, JrNullInPath, JRVTokenFreed, JRWrongPID, JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS.
EISDIR	An attempt was made to rename something other than a directory to a directory.
ENAMETOOLONG	A name is longer than 255 characters.
ENOSPC	The directory that is intended to contain New_name cannot be extended.
ENOTDIR	The supplied token did not represent a directory; or an attempt was made to rename a directory to something other than a directory.
ENOTEMPTY	New_name specified an existing directory that was not empty.
EPERM	The operation is not permitted. The caller of the service is not registered as a server.
EROFS	The specified file system is read-only. The following reason code can accompany the return code: JRReadOnlyFS.
EXDEV	An attempt was made to rename across file systems.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_rename service stores the reason code. The v_rename service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

If the sticky bit is on in the parent directory, special ownership is required to rename the file.
The v_rename service changes the name of a file or a directory from Old_name to New_name. When renaming 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.
Renaming Files:
- If Old_name and New_name are links that refer to the same file, v_rename returns successfully and does not perform any other action.
- 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. 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.
- If Old_name is the name of a file that is currently open by a remote NFS client with a share reservation that would prevent the file from being opened for writing, the file cannot be renamed.
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 empty, it is removed, as described in v_remove (BPX1VRM, BPX4VRM) — Remove a link to a file.

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

v_reg (BPX1VRG, BPX4VRG) — Register a process as a server

Characteristics and restrictions

A process must be registered as a server before the v_rename service is permitted; see v_reg (BPX1VRG, BPX4VRG) — Register a process as a server.

Examples

For an example using this callable service, see BPX1VRN, BPX4VRN (v_rename).