Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
|
Format
X/Open:
#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);
Berkeley sockets:
#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.
See select() for more information.
- 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.
If the return value is greater than 0, the files/sockets that are
ready in each bit set are set to 1. Files/Sockets in each bit set
that are not ready are set to zero. Use the macro FD_ISSET() with
each socket to test its status. For those message queues that do not
meet the conditions their identifiers in the msgsid array will be
replaced with a value of -1.
- 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.