SELECT(2,L) AIX Technical Reference SELECT(2,L)
-------------------------------------------------------------------------------
select
PURPOSE
Checks the I/O status of multiple file descriptors and message queues.
SYNTAX
#include <sys/select.h>
#include <sys/types.h>
#include <sys/time.h>
int select (nfdsmsgs, readlist, writelist, exceptlist, timeout)
int nfdsmsgs;
struct sellist *readlist, *writelist, *exceptlist;
struct timeval *timeout;
int select (nfds, readfds, writefds, exceptfds, timeout)
int nfds;
fd_set *readfds, *writefds, *exceptfds;
struct timeval *timeout;
DESCRIPTION
The select system call checks the specified file descriptors and message queues
to see if they are ready for reading (receiving) or writing (sending), or if
they have an exceptional condition pending. There are two user interfaces to
select. The first one is actually a superset of the second, although that is
not obvious from the syntax. The second interface is provided to achieve
source code compatibility with software from 4.3BSD systems.
Note: The select system call applies only to character devices, pipes, and
message queues. Not all character device drivers support it.
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 parameter 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,
Processed November 7, 1990 SELECT(2,L) 1
SELECT(2,L) AIX Technical Reference SELECT(2,L)
which can specify both file descriptors 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 criteria to be met. The timeval structure is defined in the
sys/select.h header file, and it contains the following members:
"long tv_sec;" Seconds "long 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 parameter 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 parameters 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:
Processed November 7, 1990 SELECT(2,L) 2
SELECT(2,L) AIX Technical Reference SELECT(2,L)
SELLIST(f, m) declarator...;
where f specifies the size of the fdsmask array, m specifies 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 PS/2, 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.
The arguments to the second interface are for file descriptors only. nfds is
the number of file descriptors represented in the file descriptor masks. The
readfds, writefds, and exceptfds arguments are pointers to masks indicating the
file descriptor sets. The timeout parameter has the function described above.
The descriptor sets are stored as bit fields in arrays of ints. The following
macros are provided for manipulating such descriptor sets:
FD_ZERO(&fdset) Initializes a descriptor set fdset to the null set.
FD_SET(fd, &fdset)
Includes a particular descriptor fd in fdset.
FD_CLR(fd, &fdset)
Removes fd from fdset.
FD_ISSET(fd, &fdset)
Is nonzero if fd is a member of fdset, 0 otherwise.
Processed November 7, 1990 SELECT(2,L) 3
SELECT(2,L) AIX Technical Reference SELECT(2,L)
The behavior of these macros is undefined if a descriptor value is less than 0
or greater than or equal to FD_SETSIZE, which is normally at least equal to the
maximum number of descriptors supported by the system.
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 or fdset 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 through the first interface 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. The return value through the second interface is the sum
total that meets each of the read, write, and exception criteria.
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, 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 unpredictable. If the
time limit specified by the timeout parameter expires, select returns a value
of 0.
ERROR CONDITIONS
The select system call fails if one or more of the following 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 points to a
location outside of the process's allocated address space.
EINVAL One of the parameters contains an invalid value.
EFAULT The readfds, writefds, exceptfds, or timeout parameter points to a
location outside of the process's allocated address space.
RELATED INFORMATION
Processed November 7, 1990 SELECT(2,L) 4
SELECT(3,L) AIX Technical Reference SELECT(3,L)
In this book: "close, closex," "fcntl, flock, lockf," "ioctlx, ioctl, gtty,
stty," "msgctl," "msgget," "msgrcv," "msgsnd," "msgxrcv," "open, openx,
creat," "read, readv, readx," "write, writex," and "values.h."
Processed November 7, 1990 SELECT(3,L) 5