selectex() — Monitor activity on files or sockets and message queues
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX | both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#define _ALL_SOURCE
#define _OPEN_MSGQ_EXT
#include <sys/types.h>
#include <sys/time.h>
#include <sys/msg.h>
int selectex(int nmsgsfds, fd_set *readlist,
fd_set *writelist,
fd_set *exceptlist,
struct timeval *timeout, int *ecbptr);
#define _OE_SOCKETS
#define _ALL_SOURCE
#define _OPEN_MSGQ_EXT
#include <sys/types.h>
#include <sys/time.h>
#include <sys/msg.h>
int selectex(int nmsgsfds, fd_set *readlist,
fd_set *writelist,
fd_set *exceptlist,
struct timeval *timeout, int *ecbptr);
_OPEN_MSGQ_EXT must be defined if message queues are to be monitored (X/Open sockets only).
General description
The selectex() function provides an extension to the select() call by allowing you to use an ECB that defines an event not described by readlist, writelist, or exceptlist.
The selectex() call monitors activity on a set of files/sockets and message queues until a timeout occurs, or until the ECB is posted, to see if any of the files/sockets and message queues have read, write, or exception processing conditions pending.
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.
- Parameter
- Description
- nmsgsfds
- The number of message queues and the number of file or socket
descriptors to check. (Refer to select() for a full description of
this and other parameters below.)
Note: This function is limited to descriptor numbers less than or equal to 65535.
- readlist
- A pointer to an fd_set type, array of message queue identifiers, or sellist structure specifying descriptors and message queues to check for reading.
- writelist
- A pointer to an fd_set type, array of message queue identifiers, or sellist structure specifying descriptors and message queues to check for writing.
- exceptlist
- A pointer to an fd_set type, array of message queue identifiers, or sellist structure specifying descriptors and message queues to be checked for exceptional pending conditions.
- timeout
- The pointer to the time to wait for the selectex() call to complete.
- ecbptr
- This variable can contain one of the following values:
- A pointer to a user event control block. To specify this usage of ecbptr, the high-order bit must be set to '0'B.
- A pointer to a list of ECBs. To specify this usage of ecbptr,
the high-order bit must be set to '1'B.
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 '1'B.
- A NULL pointer. This indicates no ECBs are specified.
Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Returned value
The value -1 indicates the error code should be checked for an error. The value 0 indicates an expired time limit or that the ECB is posted.
When the return value is greater than 0, then it is similar to nmsgsfds in that the high-order 16 bits give the number of message queues, and the low-order 16 bits give the number of descriptors. These values indicate the sum total that meet each of the read, write, and exception criteria. Note that a descriptor or a message queue may be counted multiple times if it meets more than one requested criterion. Should the return value for message queues exceed the value 32767, only 32767 will be reported. This is to ensure that the return value does not appear to be negative. Should the return value for file/socket descriptors be greater than 65535, only 65535 will be reported.
- Error Code
- Description
- EBADF
- One of the descriptor sets specified an incorrect descriptor or a message queue identifier is invalid.
- EFAULT
- One of the parameters contained an invalid address.
- EINTR
- selectex() was interrupted before any of the selected events occurred and before the timeout interval expired.
- EINVAL
- One of the fields in the timeval structure is incorrect.
- EIO
- One of the descriptors in the select mask has become inoperative and it is being repeatedly included in a select even though other operations against this descriptor have been failing with EIO. A socket descriptor, for example, can become inoperative if TCP/IP is shut down. A failure from select can not tell you which descriptor has failed so generally select will succeed and these descriptors will be reported to you as being ready for whatever event they were being selected for. Subsequently when the descriptor is used on a receive or other operation you will receive the EIO failure and can react to the problem with the 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 though and an inoperative descriptor is repeatedly selected on and used, even though each time it is used that call fails with EIO, eventually the select call itself will fail with EIO.
Related information
- sys/msg.h
- sys/times.h
- sys/types.h
- accept() — Accept a new connection on a socket
- connect() — Connect a socket
- msgctl() — Message control operations
- msgget() — Get message queue
- msgrcv() — Message receive operation
- msgsnd() — Message send operations
- poll() — Monitor activity on file descriptors and message queues
- recv() — Receive data on a socket
- send() — Send data on a socket