select/selectex (BPX1SEL, BPX4SEL) — Select on file descriptors and message queues

Function

The select/selectex callable service checks the I/O status of multiple open file descriptors and message queues. The file descriptors can be for character special files, pipes, sockets, or files.

Requirements

Parameters

Number_msgsfds

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword of which the first halfword (the high-order 16 bits) contains the number of message queues and the second halfword (the low-order 16 bits) contains the number of file descriptors.

The number of file descriptors should be the highest file descriptor that is being checked for status, plus 1.

For example, if you are interested in the I/O status of file descriptors 5 and 9, the second halfword of Number_msgsfds would be 10. Ten is the number of file descriptors that are contained in each of the bit sets (fd 0 through 9 equals 10 fds), and 10 is the highest file descriptor that is being checked, plus 1 (9 plus 1 equals 10). If you want to check file descriptors for status along with message queues, the highest file descriptor you can specify is 2047.

The number of message queues indicates the number of elements (queue IDs) in each of the arrays contained in Read_list, Write_list, and Exception_list. For example, if you specify a value of 10 in the first halfword of Number-msgsfds, it is expected that arrays of 10 elements each are given in Read_list, Write_list, and Exception_list. If you specify a value of 0, it is assumed that no arrays are given and that no message queues are to be checked. The maximum number of message queues that you can specify is 32 767.

Note: In order to select on descriptor numbers higher than 65 534, the descriptor limit of the process must be at least 65 536, and one of the bit lists that is passed must be at least 8192 bytes long. When both of these facts are true, and the fullword value is between 65 536 and the system descriptor maximum, the entire fullword parameter will be assumed to represent the number of file descriptors, and no message queues will be processed.

Read_list_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the length, in bytes, of the Read_list. The length is actually the sum of the length (rounded up to a multiple of 4 bytes) of the bit set specifying file descriptors and the length of the array of message queue identifiers. When both file descriptors and message queues are specified, this field should contain a value greater than 256 bytes. If 0 is specified, the Read_list is not checked by the select service.

Read_list

Supplied and returned parameter

Type:

Structure

Length:

Length specified by Read_list_length

The name of a structure that contains the bit set for the specified file descriptors and/or the array of message queue identifiers. Note that the bit set must be padded with extra bytes, if necessary, to round up its length to the next multiple of 4 bytes. The bits in the bit set should be turned on for the corresponding descriptors to be checked for reading. The format of the bits can be specified with the User_option field. On return, the bits that are set indicate the descriptors that are ready for reading.

If Read_list contains both a bit set and an array of message queue identifiers, the bit set must be 256 bytes in length. If only file descriptors are to be checked, the bit set can have any valid size.

Each element of the array of message queue identifiers is 4 bytes in length. Elements with a value of -1 are acceptable and are ignored. On return, the array is altered such that message queue identifiers that do not meet the criterion are replaced with a value of -1.

Write_list_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the length, in bytes, of the Write_list. The length is actually the sum of the length (rounded up to a multiple of 4 bytes) of the bit set specifying file descriptors and the length of the array of message queue identifiers. When both file descriptors and message queues are specified, this field should contain a value greater than 256 bytes. If 0 is specified, the Write_list is not checked by the select service.

Write_list

Supplied and returned parameter

Type:

Structure

Length:

Length specified by Write_list_length

The name of a structure that contains the bit set for the specified file descriptors and/or the array of message queue identifiers. Note that the bit set must be padded with extra bytes, if necessary, to round up its length to the next multiple of 4 bytes. The bits in the bit set should be turned on for the corresponding descriptors to be checked for writing. The format of the bits can be specified with the User_option field. On return, the bits that are set indicate the descriptors that are ready for writing.

If Write_list contains both a bit set and an array of message queue identifiers, the bit set must be 256 bytes in length. If only file descriptors are to be checked, the bit set can have any valid size.

Each element of the array of message queue identifiers is 4 bytes in length. Elements with a value of -1 are acceptable and are ignored. On return, the array is altered such that message queue identifiers that do not meet the criterion are replaced with a value of -1.

Exception_list_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the length in bytes of the Exception_list. The length is actually the sum of the length (rounded up to a multiple of 4 bytes) of the bit set specifying file descriptors and the length of the array of message queue identifiers. When both file descriptors and message queues are specified, this field should contain a value greater than 256 bytes. If 0 is specified, the Exception_list is not checked by select.

Exception_list

Supplied and returned parameter

Type:

Structure

Length:

Length specified by Exception_list_length

The name of a structure that contains the bit set for the specified file descriptors and/or the array of message queue identifiers. Note that the bit set must be padded with extra bytes, if necessary, to round up its length to the next multiple of 4 bytes. The bits in the bit set should be turned on for the corresponding descriptors to be checked for exceptions. The format of the bits can be specified with the User_option field. On return, the bits that are set indicate the descriptors that have had exceptions.

If Exception_list contains both a bit set and an array of message queue identifiers, the bit set must be 256 bytes in length. If only file descriptors are to be checked, the bit set can have any valid size.

Each element of the array of message queue identifiers is 4 bytes in length. Elements with a value of -1 are acceptable and will be ignored. On return, the array is altered such that message queue identifiers that do not meet the criterion are replaced with a value of -1.

Timeout_pointer

Supplied parameter

Type:

Pointer

Length:

Fullword (doubleword)

The name of a fullword (doubleword) field that contains a pointer to a timeout value that controls how the file descriptors are checked:

1. Wait indefinitely:

   If the timeout_pointer is zero, the select system call waits (indefinitely) until one of the selected descriptors is ready.

2. Wait for a specified period of time:
   If the timeout_pointer is nonzero, it points to a timeout value mapped by the BPXYSELT macro, which contains the number of microseconds and/or seconds to wait for one of the conditions to occur before returning to the caller. The maximum time that can be specified is 31 days. See BPXYSELT — Map the timeout value for the select syscall for more information.

   • Microseconds can be a value in the range from 0 to 1 000 000. (1 000 000 microseconds equal 1 second).
   • Seconds can be a value in the range from 0 to 2 678 400. (2 678 400 seconds equal 31 days).

   Note: Microseconds and seconds are added together to determine the timeout value. If the timeout value is more than 0 and less than 300 microseconds, the value is rounded up to 300 microseconds.
3. No Waiting:

   If the timeout value is 0, select returns immediately after checking the selected descriptors; no waiting is done.

Ecb_pointer

Supplied parameter

Type:

Pointer

Length:

Fullword (doubleword)

This can be any of the following values:

1. The name of a fullword (doubleword) field that contains a pointer to a user event control block. To specify this usage of Ecb_pointer, set the high-order bit in Ecb_pointer to B'0'.

   If a doubleword is used for Ecb_pointer, the high half must be set to zero (ECBs must be below the bar). In this case, the high-order bit that indicates Ecb_pointer usage is the high bit in the lower half of the doubleword.

2. The name of a fullword (doubleword) field that contains a pointer to a list of ECBs. To specify this usage of Ecb_pointer, set the high-order bit in Ecb_pointer B'1'.

   The list can contain the pointers for up to 1013 ECBs. The high-order bit of the last pointer in the list must be set to B'1'. If the input Ecb_pointer is a doubleword, the high half must be zero, and the bit that is checked is the high-order bit of the lower half of the doubleword. If the high-order bit is a 1, the lower half of the doubleword points to a list of Ecb_pointers. All Ecb_pointers in the list must be 31-bit pointers.

3. The name of a fullword (doubleword) field that contains 0. This indicates that no ECBs are specified.

User_option_field

Supplied and returned parameter

Type:

Integer

Length:

Fullword

A dual-purpose field that is used as input to specify the format of the read, write, and exception bit lists, and as output to contain the first selected file descriptor that was not supported by the select service.

On input, specify one of the following (the values are defined in BPXYSEL — Map the select options):

• SEL#BITSBACKWARD – Bit-backward order by word:
  Bits are read from right to left within each word, with the low-order bit on the right and the high-order bit on the left. For example:

    Word 1               Word 2                   Word 3
   -------------------  -----------------------  ----------------------
   31 30 29...3 2 1 0   63 62 61...35 34 33 32   95 94 93...67 66 65 64
   -------------------  -----------------------  ----------------------

  Note: In this example, file descriptor 0 is represented by the last bit on the right in Word 1.
• SEL#BITSFORWARD – Bit-forward order by word:
  Bits are read from left to right within each word, with the low-order bit on the left and the high-order bit on the right. For example:

   Word 1               Word 2                   Word 3
  -------------------  -----------------------  ----------------------
  0 1 2 3...29 30 31   32 33 34 35...61 62 63   64 65 66.67...93 94 95
  -------------------  -----------------------  ----------------------

  Note: In this example, file descriptor 0 is represented by the first bit on the left in Word 1.

On output, the select service returns one of the following:

• -1, if all the selected file descriptors supported the select callable service.
• The first selected file descriptor that did not support the select callable service.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the select service returns one of the following:

• The number of read, write, and exceptional conditions that were found among the given message queues; and the number of read, write, and exceptional conditions that were found among the specified file descriptors. These two values are returned, respectively, in the first halfword and the second halfword of Return_value. Should the return value for message queues exceed 32 767, only 32 767 is reported. This is to ensure that Return_value does not appear to be negative. Should the return value for file descriptors be greater than 65 535, only 65 535 is reported.
• 0, if the timeout value expired before any of the conditions were met.
• -1, if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the select service stores the return code. The select 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 select service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINTR	The select service request was interrupted by a signal for the caller.
EINVAL	One of the parameters contains a value that is not correct. The following reason codes can accompany this return code: JRNoLists, JRListTooShort, JRMsOutOfRange, JRInvUserOp, JRSecOutOfRange, JRNoFds, JRTooManyMsgQIds,JRTooManyFds, JRListLenBad.
EIO	One of the descriptors in the select mask has become inoperative, and it is being included repeatedly in a select, even though other operations against this descriptor have been failing with EIO. A socket descriptor can become inoperative, for example, if TCP/IP is shut down. When a descriptor fails, a failure from select does not tell you which descriptor has failed. The select call usually succeeds, and the descriptors are reported to you as being ready for whatever events were specified on the select call. When the descriptor is subsequently used on a receive or other operation, you will receive the EIO failure and can then react to the problem with that individual descriptor. In general, you would close() the descriptor and remove it from the next select mask. If the individual descriptor's failing return code is ignored, however, and an inoperative descriptor is repeatedly selected on and used (even though each time it is used the call fails with EIO), the select call itself will eventually fail with EIO.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the select service stores the reason code. The select service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. The bit set for the read_list, write_list, and exception_list is a string of bits such that if X is an element of the set, the bit that represents X is set to 1. For example, if descriptor 1 is to be checked, bit 1 should be turned on in the bit set. Here is how that byte would look:
   • Bit-forward order: B'01000000'.
   • Bit-backward order: B'00000010'.
2. When a positive value is specified for the number of file descriptors:
   • At least one bit set (read, write, or exception) must be specified, and its length must be large enough (rounded up to the next multiple of 4) to contain the bit that represents the largest descriptor you specified.
   • If more than one bit set is specified, each bit set must be the same length.
     For example, if you want to check the read status for file descriptor 59 and the write status for file descriptor 6:

     Number of fds = 60

     Read_list_length = 8
     Read_list = the bit representing fd 59 is set on (see User_option_field
     to determine which bit that would be)

     Write_list_length = 8
     Write_list = the bit representing fd 6 is set on (see User_option_field
     to determine which bit that would be)

     Exception_list_length = 0

3. When both the first and second halfwords of Number_msgsfds contain a positive value, the Read_list, Write_list, and Exception_list must each contain both a bit set and an array of message queue identifiers, unless a value of 0 is specified for its length.

   When the fullword value is between 65 536 and the system descriptor maximum, one of the lists that is passed is at least 8 192 bytes long, and the descriptor limit of the process is at least 65 536, the fullword value is considered as the number of descriptors in the lists, and no message queues will be processed.

   The following example illustrates what you must do:

   Suppose you want to check the read status for file descriptors 3 and 5 and the write status for message queues whose identifiers are 7 and 8.

   Number of fds = 6 (the largest fd plus 1)
   Number of message queues = 2

   Read_list_length = 264 (256 byte bit set length + 8 byte array length) Read_list = the 256-byte bit set with appropriate bits set on for fds 3 and 5, followed by a two-element array that contains the value of -1 in both elements.

   Write_list_length = 264 (same length as for read) Write_list = the 256-byte bit set with all its bits set off followed by the two-element array that contains the numbers 7 and 8.

   Exception_list_length = 0

4. You can use the select service as a timer-only function by specifying zero for the Read_list_length, Write_list_length, and Exception_list_length, and by specifying timeout_pointer and timeout_value. If you specify zero for timeout_pointer, the select service blocks forever. If you specify zero for timeout_value, no blocking is done, and the select service returns immediately to the caller.
5. You can also specify an Ecb_pointer with the timer only function.
6. Regular files are always ready for reading and writing.
7. When the storage key of the first (or only) ECB matches the caller's PSW key, the kernel performs the wait in the caller's PSW key; otherwise, the kernel performs the wait in the TCB key (TCBPFK). However, if the caller is running in key 0, then the kernel performs the wait in key 0, regardless of the storage key.

Characteristics and restrictions

There are no restrictions on the use of the select service.