vn_ioctl — I/O control

Function

The vn_ioctl operation conveys a command for a file or device driver. The specific commands that are supported are defined by the PFS.

Environment on entry and exit

See Environment for PFS operations.

Input parameter format

vn_ioctl    (Token_structure,
             OSI_structure,
             Audit_structure,
             Open_flags,
             Command,
             Argument_length,
             Argument,
             Return_value,
             Return_code,
             Reason_code)

Parameters

Token_structure

Supplied parameter

Type:: TOKSTR
Length:: Specified by TOKSTR.ts_hdr.cblen.

The Token_structure represents the file (vnode) that is being operated on. It contains the PFS's initialization token, mount token, and the file token. Refer to LFS/PFS control block structure for a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI in Interface structures for C language servers and clients for its mapping.

OSI_structure

Supplied and returned parameter

Type:: OSI
Length:: Specified by OSI.osi_hdr.cblen.

The OSI_structure contains information that is used by the OSI operations that may be called by the PFS. See OSI services for more information.

It also contains MVS-specific information that needs to be passed to the PFS, including SMF accounting fields, a work area, a recovery area, and an optional pointer to an output ATTR structure. For more details on the OSI structure, see The OSI structure.

This area is mapped by the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.

Audit_structure

Supplied parameter

Type:: CRED
Length:: Specified by CRED.cred_hdr.cblen.

The Audit_structure contains information that is used by the security product for access checks and auditing. It is passed to most SAF routines that are invoked by the PFS.

Refer to Security responsibilities and considerations for a discussion of security processing, and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for the mapping of this structure.

Open_flags

Supplied parameter

Type:: Structure
Length:: Fullword

An area that contains the open options that are associated with the file. These flags are defined in fcntl.h.

Command

Supplied parameter

Type:: Integer
Length:: Fullword

The command indicates the function that is to be performed by the PFS. The values that are defined in ioctl.h are for regular calls. The special values for sockets initialization are defined in BPXYPFSI (see Interface structures for C language servers and clients).

Argument_length

Supplied and returned parameter

Type:: Integer
Length:: Fullword

Argument_length contains the length of the argument.

Argument

Supplied and returned parameter

Type:: Defined by the PFS or the Device Driver
Length:: Specified by Argument_length

Argument is the buffer that is to be processed by the PFS. It may contain input data to be processed, data placed in it by the PFS or device driver, or both.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_ioctl service returns the results of the operation, as one of the following:

Return_value: Meaning
-1: The operation was not successful. The Return_code and Reason_Code values must be filled in by the PFS when Return_value is -1.
0: The operation was successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_ioctl service stores the return code. The vn_ioctl service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of supported return code values.

The vn_ioctl service should support at least the following error value:

Return_code	Explanation
ENODEV	The requested function is not supported by the PFS.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_ioctl service stores the reason code. The vn_ioctl service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. These reason codes are documented by the PFS.

Implementation notes

Overview of vn_ioctl processing

vn_ioctl provides a vehicle by which a PFS may provide functions not described by the POSIX standard.

Specific processing notes

The PFS could use vn_ioctl to support unique file operations.
vn_ioctl could be used to allow direct access to devices that are controlled by the PFS. You should avoid passing addresses with this service (using argument), and instead include all data in the buffer.
The maximum Argument_length that is supported by the LFS is 1024 bytes.
Refer to Common INET sockets for information about the commands that a PFS must support in order to be an AF_INET socket PFS.
Open_flags are all zero when vn_ioctl is the result of the w_pioctl (BPX1PIO) function, since the file being operated on has not been opened. The PFS may want to include a special access check in this case.
For those cases in which user data addresses are passed in the argument, the user's storage key is passed to the PFS. This key should be used with MVCSK/MVCDK or osi_copyin/osi_copyout to reference the user data areas.
The key is passed in the first word of the system data area of the Token_structure, ts_sysd1, with a format of X'PPPP020K', where K is the four-bit key value. When ts_sysd1 is all zeros, keys are not passed.

The first two bytes of ts_sysdl, when byte 3 is X'02', are the first and third bytes of the user's PSW, which are the bytes that contain the user's AMODE and Supervisor State bits.

This information is passed in ts_sysdl for all instances of program ioctl() calls, but some internal uses of vn_ioctl, mostly for FIONBIO, do not do so. These cases do not contain addresses in the argument.

Serialization provided by the LFS

The vn_ioctl operation is invoked with an exclusive latch held on the vnode of the file.

Security calls to be made by the PFS

The PFS may choose to invoke SAF's Check Access callable service to verify that the user has write permission to the file or device.