v_readlink (BPX1VRA, BPX4VRA) — Read a symbolic link

Function

The v_readlink service reads the symbolic link file that is represented by Vnode_token, and returns the contents in the buffer that is described by UIO. The symbolic link file contains the path name or external name that was specified when the symbolic link was defined (see v_symlink (BPX1VSY, BPX4VSY) — Create a symbolic link).

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1VRA):	31-bit
AMODE (BPX4VRA):	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 BPX1VRA,(Vnode_token,
              OSS,
              UIO,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4VRA with the same parameters. The FUIO can contain a 64-bit address.

Parameters

Vnode_token

Supplied parameter

Type:: Token
Length:: 8 bytes

The name of an 8-byte area that contains a vnode token that represents the symbolic link file to read.

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

UIO

Supplied and returned parameter

Type:: Structure
Length:: Fuio#Len (from the BPXYFUIO macro)

The name of an area that contains the user input and output block. This area is mapped by the BPXYFUIO macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the v_readlink service returns the number of bytes read into the buffer 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_readlink service stores the return code. The v_readlink 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_readlink service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	Parameter error; for example, a supplied area was too small. The following reason codes can accompany the return code: JRInvalidFuio, JrFileNotSymLink, JRVTokenFreed, JRWrongPID, JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS.
EPERM	The operation is not permitted. The caller of the service is not registered as a server.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

The following UIO fields are provided by the caller:
FuioID

Contains Fuio#ID (from the BPXYFUIO macro).

FuioLen

Contains the length of the UIO structure.

FuioBufferAddr

Contains the address of a buffer where the link contents are to be returned.

FuioBuff64Vaddr

Contains the 64-bit virtual address of a buffer where the link contents are to be returned.

FuioIBytesRW

Specifies the maximum number of bytes that can be written to the output buffer.
The following UIO field is returned by the v_readlink service.:
FuioPSWKey

Is set to the caller's key.
If the buffer that is supplied to v_readlink is too small to contain the contents of the symbolic link, the value is truncated to the length of the buffer (FuioBytesRW). The length of the symbolic link can be determined from an ATTR structure that is returned on a call to the VFS callable services API (that is, to v_getattr (BPX1VGA, BPX4VGA) — Get the attributes of a file). The maximum length is 1023 bytes.
The FuioAddr64 setting determines whether the pointer to the user buffer is a 64-bit pointer in FuioBuff64Vaddr or a 31-bit pointer in FuioBufferAddr.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1VRA, BPX4VRA (v_readlink).