vn_select — Select or poll on a vnode

Function

The vn_select operation monitors activity on a vnode to see if it is ready for reading or writing, or if it has an exceptional condition pending. The vnode can be for a socket, a pipe, a regular file, or a pseudoterminal file.

Environment on entry and exit

See Environment for PFS operations.

Input parameter format

vn_select   (Token_structure,
             OSI_structure,
             Audit_structure,
             Select_token,
             Function,
             Select_option,
             Pfs_work_token,
             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.

Select_token

Supplied and returned parameter

Type:: Token
Length:: 16 Bytes

An area that the PFS copies into its own storage and later uses to tell the LFS that a selected event has occurred for this vnode.

This token is unique among all active vn_selects on the system, and can be used to correlate a query request (SEL_QUERY or SEL_POLLQUERY) with its corresponding cancel request (SEL_CANCEL or SEL_POLLCANCEL).

Function

Supplied parameter

Type:: Integer
Length:: Fullword

A fullword that specifies whether this is a query or a cancel request, and whether the request is for select or poll. The values for this field are defined in the BPXYPFSI header file (see Interface structures for C language servers and clients). The Function parameter specifies the subfunction that is being requested:

Table 1. vn_select subfunctions
Function	Description
SEL_QUERY, SEL_POLLQUERY	The PFS should perform the following: Check the events that are specified in Select_option to see if any of them can be immediately satisfied. If so, this status is returned in the Return_Value parameter. If there is no immediate status to report, the PFS records that a select is pending on this file and sets up to invoke osi_selpost later, when one of the selected events has occurred. The PFS returns a value of `0` in Return_Value after it has performed its internal processing to set up for select pending. The occurrence of the event and the subsequent invocation of osi_selpost happen asynchronously on another thread or MVS™ task.
SEL_CANCEL, SEL_POLLCANCEL	The PFS performs the following: If there is a pending select/poll recorded for a prior query with the same Select_token, it must be canceled in such a way that osi_selpost is not invoked. Check the events that are specified in Select_option to see if any of them can be immediately satisfied. If so, this status is returned in the Return_Value parameter.

Select_option

Supplied parameter

Type:: Integer
Length:: Fullword

A fullword that contains the bits that describe the options that are requested for this vnode. The values for this field are defined in the BPXYPFSI header file (see Interface structures for C language servers and clients).

Select_option indicates the conditions or events that are being checked for. If this is a select request, the conditions are:

Option: Description
SEL_READ: A read that is issued against this file will not block.
SEL_WRITE: A write that is issued against this file will not block.
SEL_XCEPT: An exceptional condition, as defined by the particular PFS, has occurred. Typically this could occur because a socket connection has become inoperative because of network problems, or the other end of the socket has been closed.

For reading and writing, an error condition that would cause the read or write to fail means that the operation will not block, and therefore the file is ready for that operation.

If one or more of the selected conditions are ready, the PFS returns the information in the Return_Value parameter immediately, using the same bit mapping to indicate which conditions are ready.

The conditions that can be specified for poll are explained in other documents (for instance, z/OS XL C/C++ Language Reference). The mapping for these fields is defined in the BPXYPFSI header file (see Appendix D).

Pfs_work_token

Supplied or returned parameter

Type:: Token
Length:: Fullword

A fullword that is returned on a query request and passed on a subsequent cancel request. This allows the LFS to store data that the PFS will need on the cancel request, if any is needed.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the vn_select service returns the results of the operation, as one of the following:

Return_value

Meaning

-1

The operation was not successful. This causes the whole select() or poll() request, as made by the application program, to fail. The Return_code and Reason_Code values are passed back to the application program.

0

There is no status, and the operation was successful.

For query ( SEL_QUERY or SEL_POLLQUERY):
The PFS is set up to invoke osi_selpost when the requested event occurs.
For cancel ( SEL_CANCEL or SEL_POLLCANCEL):
The PFS has canceled the request to invoke osi_selpost, or it has never been set up to do so. The PFS does not invoke osi_selpost after returning from this call.

Greater than 0

There is status being returned in this parameter. The returned status has the same format as the Select_option parameter.

For query ( SEL_QUERY or SEL_POLLQUERY):
The operation is complete and the PFS will not invoke osi_selpost for this request.
For cancel ( SEL_CANCEL or SEL_POLLCANCEL):
The PFS has canceled the request to invoke osi_selpost if it had been recorded, or it has never been set up to do so.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_select operation stores the return code. The vn_select operation returns Return_code only if Return_value is -1. For a complete list of supported return code values, see z/OS UNIX System Services Messages and Codes.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_select operation stores the reason code. The vn_select operation 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_select processing

For information about vn_select, refer to Select/poll processing.

For more information about the semantics of this operation for a POSIX-conforming PFS, refer to the publications that are mentioned in Finding more information about sockets for the select() function.

Specific processing notes

The PFS should save the Select_token that is passed on the query request. This token is used both during the cancel request (to delete the request), and when an event occurs that the LFS should be informed of through the osi_selpost function.
The PFS can use the Pfs_work_token parameter on a query request to return data (such as an address where it has stored information about this request), so that it can be found during a cancel request. The data is used to correlate the cancel request with its matching query request. This provides an alternative to scanning the PFS control blocks for a matching Select_token value.
If the session being selected becomes inoperative, the PFS must fail the operation with a Return_code of EIO. For sockets, this is critical to Common Inet processing so that a stack can be removed from a socket during the internal vn_select that is done to implement blocking reads and accepts. For application select() calls, the LFS will convert EIO from vn_select to ready status for the descriptor so that the application receives the EIO notification on the specific descriptor to which it applies.

Serialization provided by the LFS

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

Security calls to be made by the PFS

None.