Function
The v_get service returns a vnode
token for the file or directory that is represented by the input FID
within the mounted file system that is represented by the input VFS
token.
Requirements
Operation |
Environment |
---|
Authorization: |
Supervisor state or problem state, any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN = HASN |
AMODE (BPX1VGT): |
31-bit |
AMODE (BPX4VGT): |
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 BPX1VGT,(VFS_token,
OSS,
FID,
Vnode_token,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4VGT with the same parameters.
Parameters
- VFS_token
- Supplied parameter
- Type:
- Token
- Length:
- 8 bytes
The name of an 8-byte area that contains the VFS
token for the mounted file system that contains the file or directory
that is specified by the FID parameter. This token is obtained from
the v_rpn callable service.
- 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).
- FID
- Supplied parameter
- Type:
- Token
- Length:
- 8 bytes
The name of an 8-byte area that contains the file
identifier of the file or directory for which a vnode token is to
be returned. The FID for a file is contained in the attribute structure
for the file in the AttrFid field; the ATTR structure describes the
attribute structure.
- Vnode_token
- Returned parameter
- Type:
- Token
- Length:
- 8 bytes
The name of an 8-byte area in which the v_get service
returns a vnode token of the file or directory that is supplied in
the FID parameter. The token is used to identify the file or directory
to other callable services.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the v_get service
returns 0 if the request completes successfully (the
file or directory exists), or -1 if the request is
not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the v_get service
stores the return code. The v_get 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_get service can return one of the following values in the Return_code
parameter:
Return_code |
Explanation |
---|
EINVAL |
Parameter error; for example, the VFS token parameter is obsolete.The
following reason codes can accompany the return code: JRStaleVFSTok,
JRInvalidOSS. |
EMFILE |
The maximum number of vnode tokens have been created. |
ENFILE |
An error occurred obtaining storage for a vnode token. |
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_get service
stores the reason code. The v_get 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 FID (file identifier) uniquely identifies a file in a particular
mounted file system. For files associated with a physical DASD resource,
the FID validly persists across mounting and unmounting of the file
system, as well as z/OS UNIX re-IPLS.
This distinguishes the FID from the vnode token, which relates to
a file in active use, and whose validity persists only until the token
is released via the v_rel callable service. Note that automount-managed
directories are virtual, and the FID is unique only as long as the
directory is being referenced.
A server application uses v_get to
convert a FID to a vnode token when it is preparing to use a file,
because the Vnode token identifies the file to the other VFS callable
services.
- The FID for a file is returned in the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls), by such services as v_rpn and v_lookup.
- vnode tokens that are returned by the v_get service are not inherited
across a fork callable service.
- The caller is responsible for freeing vnode tokens that are returned
by the v_get service by calling to the v_rel service when they are
no longer needed.