vfs_batsel — Select/poll on a batch of vnodes

Function

The vfs_batsel operation monitors activity on a batch of vnodes (multiple vnodes) to see if they are ready for reading or writing, or if they have an exceptional condition pending. The vnodes can be for a socket, pipe, regular, or pseudoterminal file.

Environment on entry and exit

See Environment for PFS operations.

Input parameter format

vfs_batsel  (Token_structure,
             OSI_structure,
             Audit_structure,
             Reserved_1,
             Function,
             Batch-Select_Structure
             Reserved_2,
             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 system (VFS) being operated on. It contains the PFS's initialization token and mount 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 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 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.

Reserved_1

Supplied parameter

Type:: Integer
Length:: Fullword

The value 0. This parameter is reserved to maintain consistency with the vn_select operation interface.

Function

Supplied parameter

Type:: Integer
Length:: Fullword

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

Function specifies the type of select that is being requested:

Query (SEL_BATSELQ or SEL_BATPOLLQ): The PFS should perform the following for query:
1. Check each of the files in the Batch-Select_Structure to see if any of the specified events for a file can be satisfied immediately. If so, the BSIC Response fields for those files are updated, and the status for any one of them is returned in the Return_value parameter.
2. If there is no immediate status to report for any file in the Batch-Select_Structure, the PFS records that a select is pending for each of the files 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 select pending for each of the files.
  The occurrence of an event and the subsequent invocation of osi_selpost happen asynchronously on another thread or MVS™ task.
Cancel (SEL_BATSELC or SEL_BATPOLLC): The PFS performs the following for cancel:
1. If there is a pending select recorded for a file with the same SelectToken that was specified on a previous query, it must be canceled in such a way that osi_selpost is not invoked.
2. Check each of the files that are specified in the Batch-Select_Structure to see if any of the specified events can be immediately satisfied. If at least one file has status, that status is returned in the Return_value parameter, and the status for each of the selected files is returned in the BSIC Response fields for those files. If a file does not have status, a 0 is returned in the BSIC Response field for that file. If none of the files have status, 0 is returned in the Return_value parameter.

Batch-Select_Structure

Returned parameter

Type:: BSIC
Length:: Calculated: A BSIC header plus one BSIC entry for each selected file.

An area that contains information about the selected files and events. It specifies which files and events are being selected, a SelectToken for each file, a response area for status, and work area pointers for use by the PFS. This area is mapped by the BSIC typedef in the BPXYPFSI header file (see Interface structures for C language servers and clients). The events that can be selected for select requests are:

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. This could happen when a socket connection becomes inoperative because of network problems, or when the other end of the socket is closed.

For poll requests, the events that can be selected are documented in other manuals (for instance, z/OS XL C/C++ Runtime Library Reference). The mapping for these fields is defined in the BPXYPFSI header file.

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 events are ready for any of the selected files, the PFS immediately returns the status for one of the files in the Return_value parameter, using the same bit mapping that is used in the BSIC Response field.

Reserved_2

Supplied parameter

Type:: Integer
Length:: Fullword

The value 0. This parameter is reserved, to maintain consistency with the vn_select operation interface.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the vfs_batsel 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 for any of the files in the Batch-Select_Structure, and the operation was successful.

For query (SEL_BATSELQ or SEL_BATPOLLQ): The PFS is set up to invoke osi_selpost when the requested event occurs.
For cancel (SEL_BATSELC or SEL_BATPOLLC): The PFS has canceled the request to invoke osi_selpost, or it was never set up to do so. The PFS will not invoke osi_selpost after returning from this call.

Greater than 0

Status is being returned in the Batch-Select_Structure. The returned status in this parameter has the same format as the BSIC Response field.

For query (SEL_BATSELQ or SEL_BATPOLLQ): The operation is complete and the PFS will not invoke osi_selpost for this request.
For cancel (SEL_BATSELC or SEL_BATPOLLC): The PFS has canceled the request to invoke osi_selpost if it had been recorded.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

The vfs_batsel operation is identical to the vn_select operation, except that a batch of files (multiple files) are selected using the Batch-Select_Structure, instead of only one. 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 mentioned in Finding more information about sockets for the select function.

Specific processing notes

On the query request, the PFS should save the BSIC SelectToken for each file passed in the Batch-Select_Structure. 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 BSIC entry workptr field in the Batch-Select_Structure to save information about each file during a query request. It can also use the BSIC header workptr field to save information about the entire query (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 matching SelectToken values.

Serialization provided by the LFS

None.

Security calls to be made by the PFS

None.

Related services

vn_select — Select or poll on a vnode