select
Purpose
Checks the I/O status of multiple file descriptors and
message queues.
Syntax
#include <sys/select.h>
int select (nfdsmsgs, readlist, writelist, exceptlist, timeout)
int nfdsmsgs;
struct sellist *readlist, *writelist, *exceptlist;
struct timeval *timeout;
Description
The select system call checks the specified file descrip-
tors and message queues to see if they are ready for
reading (receiving) or writing (sending), or if they have
an exceptional condition pending.
Note: The select system call applies only to character
devices, pipes, and message queues. Not all character
device drivers support it. See the descriptions of indi-
vidual character devices in Chapter 4, "Special Files"
for information about whether and how specific device
drivers support select.
The nfdsmsgs parameter specifies the number of file
descriptors and the number of message queues to check.
The low-order 16 bits give the length of a bit mask that
specifies which file descriptors to check; the high-order
16 bits give the size of an array that contains message
queue identifiers. If either half of the nfdsmsgs param-
eter is equal to 0, it is assumed the corresponding bit
mask or array not present.
The readlist, writelist, and exceptlist parameters
specify what to check for reading, writing, and
exceptions, respectively. Together, they specify the
selection criteria. Each of these parameters points to a
sellist structure, which can specify both file descrip-
tors and message queues. Your program must define the
sellist structure in the following form:
struct sellist
{
int fdsmask[f|; /* file descriptor bit mask */
int msgids[m|; /* message queue identifiers */
};
The fdsmask array is treated as a bit string in which
each bit corresponds to a file descriptor. File
descriptor n is represented by the bit (1 << n) in the
array element fdsmask[n / BITS(int)|. (The BITS macro is
defined in the values.h header file.) Each bit that is
set to 1 indicates that the status of the corresponding
file descriptor is to be checked. Note that the low-
order 16 bits of the nfdsmsgs parameter specify the
number of bits (not elements) in the fdsmask array that
make up the file descriptor mask. If only part of the
last int is included in the mask, then the appropriate
number of low-order bits are used, and the remaining
high-order bits are ignored. If you set the low-order 16
bits of the nfdsmsgs parameter to 0, then you must not
define a fdsmask array in the sellist structure.
Each int of the msgids array specifies a message queue
identifier whose status is to be checked. Elements with
a value of -1 are ignored. The high-order 16 bits of the
nfdsmsgs parameter specify the number of elements in the
msgids array. If you set the high-order 16 bits of the
nfdsmsgs parameter to 0, then you must not define a
msgids array in the sellist structure.
If the timeout parameter is not a NULL pointer, then it
points to a structure that specifies the maximum length
of time to wait for at least one of the selection cri-
teria to be met. The timeval structure is defined in the
sys/select.h header file, and it contains the following
members:
"int tv_sec;" Seconds "int tv_usec;" Microseconds
The number of microseconds specified in timeout.tv_usec,
a value from 0 to 999999, is rounded to the nearest
second by the AIX Operating System.
If the timeout parameter is a NULL pointer, then the
select system call waits indefinitely, until at least one
of the selection criteria is met. If the timeout param-
eter points to a timeval structure that contains zeros,
then the file and message queue status is polled, and the
select system call returns immediately.
Note: The arrays specified by readlist, writelist, and
exceptlist are the same size because each of these param-
eters points to the same sellist structure type.
However, you need not specify the same number of file
descriptors or message queues in each. Set the file
descriptor bits that are not of interest to 0, and set
the extra elements of the msgids array to -1.
You can use the SELLIST macro defined in the sys/select.h
header file to define the sellist structure. The format
of this macro is:
SELLIST(f, m) declarator . . . ;
where f specifies the size of the fdsmask array, m speci-
fies the size of the msgids array, and each declarator is
the name of a variable to be declared as having this
structure type.
For example, suppose you want to test file descriptors 1,
2, and 35 in addition to five message queues. On the
RT PC, which has 32-bit integers, this requires two ints
for the bit mask. Five ints are required to specify the
message queue identifiers. The structures can be defined
like this:
SELLIST(2, 5) rd, wr, ex;
This macro expands to:
struct
{
int fdsmask[2];
int msgids[5];
} rd, wr, ex;
Note that the SELLIST macro does not define the structure
with a tag (that is, as struct sellist).
The SELLIST macro cannot be used if you specify either
half of the nfdsmsgs parameter as 0, indicating that one
of the arrays is not present. Trying to use
"SELLIST(0,5)", for example, results in a compiler error
caused by defining an array with a dimension of 0. In
this case, you must define the structure yourself,
including only the desired array.
Return Value
Upon successful completion, the select system call
returns a value that indicates the total number of file
descriptors and message queues that satisfy the selection
criteria. The fdsmask bit masks are modified so that
bits set to 1 indicate file descriptors that meet the
criteria. The msgids arrays are altered so that message
queue identifiers that do not meet the criteria are
replaced with a value of -1.
The return value is similar to the nfdsmsgs parameter in
that the low-order 16 bits give the number of file
descriptors, and the high-order 16 bits give the number
of message queue identifiers. These values indicate the
sum total that meet each of the read, write and exception
criteria. Therefore, the same file descriptor or message
queue may be counted up to three times.
You can use the NFDS and NMSGS macros to separate out
these two values from the return value. If "rc" contains
the value returned from the select system call, then
"NFDS(rc)" is the number of files selected, and
"NMSGS(rc)" is the number of message queues selected.
If the select system call fails, then it returns a value
of -1 and sets errno to indicate the error. In this
case, the contents of the structures pointed to by the
readlist, writelist, and exceptlist parameters are unpre-
dictable. If the time limit specified by the timeout
parameter expires, then select returns a value of 0.
Diagnostics
The select system call fails if one or more of the fol-
lowing is true:
EBADF An invalid file descriptor or message queue
identifier is specified.
EINTR A signal was encountered before any of the
selected events occurred, or before the time
limit expired.
EFAULT The readlist, writelist, exceptlist, or
timeout parameter &pointsout..
EINVAL One of the parameters contains an invalid
value.
Related Information
In this book: "close," "fcntl," "ioctl," "msgctl,"
"msgget," "msgrcv," "msgsnd," "msgxrcv," "open,"
"read, readx," "write, writex," "values.h," and
Chapter 4, "Special Files.",
See ddselect in Device Driver Development Guide.