v_rpn (BPX1VRP, BPX4VRP) — Resolve a path name

Function

The v_rpn service accepts an absolute path name of a file or a directory and returns a vnode token that represents this file or directory, and the VFS token that represents the mounted file system that contains the file or directory. These tokens must be supplied by the server on any subsequent VFS callable services API that is related to these files, directories, or file systems. The v_rpn service also returns file attribute information for the file or directory, and mount information for the file system.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1VRP):	31-bit
AMODE (BPX4VRP):	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 BPX1VRP,(OSS,
              Pathname_length,
              Pathname,
              VFS_token,
              Vnode_token,
              Mnte_length,
              Mnte,
              Attr_length,
              Attr,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4VRP with the same parameters.

Parameters

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).

Pathname_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the full path name of the file or directory that is to be resolved to a token. The name can be up to 1023 bytes long; each component of the name (between delimiters) can be up to 255 bytes long.

Pathname

Supplied parameter

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

The name of an area, of length Pathname_length, that contains the full name of the file or directory that is to be resolved.

VFS_token

Returned parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area in which the v_rpn service returns the VFS token of the file system that contains the file or directory that is supplied in the Pathname parameter.

Vnode_token

Returned parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area in which the v_rpn service returns a vnode token of the file or directory that is supplied in the Pathname parameter.

Mnte_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the area that is passed in the Mnte parameter.

The length of this area must be large enough to contain a mount entry header (MnteH) and one mount entry (Mnte). These fields are mapped by the BPXYMNTE macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Mnte

Returned parameter

Type:: Structure
Length:: Specified by the Mnte_length parameter

The name of an area, of length Mnte_length, in which the v_rpn service returns information about the file system that contains the file or directory that is supplied in the Pathname parameter. This area is mapped by the BPXYMNTE macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Attr_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the area that is passed in the Attr parameter. To determine the value of Attr_length, use the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Attr

Returned parameter

Type:: Structure
Length:: Specified by the Attr_length parameter

The name of an area, of length Attr_length, in which the v_rpn service returns the file attribute structure for the file or directory that is supplied in the Pathname parameter. This area is mapped by the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EINVAL	Parameter error; for example, the Pathname parameter did not contain an absolute path name; or one of the supplied areas was too small. The following reason codes can accompany the return code: JRNoLeadingSlash, JRSmallAttr, JRSmallMnte, JRInvalidOSS, JRNullInPath.
ELOOP	Too many symbolic links were encountered in the path name.
EMFILE	The maximum number of vnode tokens have been created.
ENAMETOOLONG	The path name or a component in the path name is too long.
ENFILE	An error occurred while storage was being obtained for a vnode token.
ENOENT	A directory or file that was supplied in the Pathname parameter does not exist; or the Pathname_length parameter is not greater than 0.
ENOTDIR	A node in the path name is not a directory.
EPERM	The operation is not permitted. The caller of the service is not registered as a server.
ERREMOTE	The object is remote. This return code can be accompanied by reason code JrNoRemote.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_rpn service stores the reason code. The v_rpn 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

Vnode tokens that are returned by the v_rpn service are not inherited across a fork callable service.
VFS tokens that are returned by the v_rpn service are inherited across a fork callable service.
The mount point path name is not returned in the Mnte structure that is returned by v_rpn.
The caller is responsible for freeing the vnode token that is returned by the v_rpn service, by calling to the v_rel service when it is no longer needed.
When the OssNoRemote flag is set v_rpn will not cross over into a remote file system, such as the NFS Client file system. If a remote file system is encountered during the resolution of the path name v_rpn will fail with a return code of ERREMOTE.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1VRP, BPX4VRP (v_rpn).