[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions , Volume 2
Checks the I/O status of multiple
file descriptors and message queues.
Standard C Library
(libc.a)
#include <sys/time.h>
#include <sys/select.h>
#include <sys/types.h>
int select (Nfdsmsgs, ReadList, WriteList, ExceptList, TimeOut)
int Nfdsmsgs;
struct sellist * ReadList, *WriteList, *ExceptList;
struct timeval * TimeOut;
The select subroutine
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.
When selecting on an unconnected
stream socket, select returns when the connection is made. If selecting
on a connected stream socket, then the ready message indicates that data can
be sent or received. Files descriptors of regular files always select
true for read, write, and exception conditions. For more information on
sockets, refer to "Understanding Socket Connections" and
the related "Checking for Pending Connections Example
Program" dealing with pending connections in AIX 5L Version
5.1 Communications Programming Concepts.
| Nfdsmsgs
| 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 a value of 0, the
corresponding bit mask or array is assumed not to be present.
|
| TimeOut
| Specifies either a null pointer or a pointer to a timeval
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 /usr/include/sys/time.h file and it
contains the following members:
struct timeval {
int tv_sec; /* seconds */
int tv_usec; /* microseconds */
};
The number of microseconds
specified in TimeOut.tv_usec, a value from 0 to
999999, is set to one millisecond by Version 3 of the operating system if the
process does not have root user authority and the value is less than one
millisecond.
If the TimeOut parameter
is a null pointer, the select subroutine waits indefinitely, until
at least one of the selection criteria is met. If the
TimeOut parameter points to a timeval structure that
contains zeros, the file and message queue status is polled, and the
select subroutine returns immediately.
|
| ReadList,
WriteList, ExceptList
| 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 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 mod
bits)) in the array element
fdsmask[n / BITS(int)].
(The BITS macro is defined in the values.h
file.) Each bit that is set to 1 indicates that the status of the
corresponding file descriptor is to be checked.
Note: 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, 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,
you must not define an 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, you must not define a
msgids array in the sellist structure.
Note: The arrays specified by the ReadList,
WriteList, and ExceptList parameters 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 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 specifies the size of the
msgids array, and each declarator is the name of a
variable to be declared as having this type.
|
Upon successful completion,
the select subroutine 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 can be counted up to three times. You can
use the NFDS and NMSGS macros found in the
sys/select.h file to separate out these two values from the
return value. For example, if rc contains the value returned
from the select subroutine, NFDS(rc) is the
number of files selected, and NMSGS(rc) is the number of
message queues selected.
If the time limit specified by the
TimeOut parameter expires, the select subroutine returns
a value of 0.
If a connection-based socket is
specified in the Readlist parameter and the connection disconnects,
the select subroutine returns successfully, but the recv subroutine on the socket will return a value
of 0 to indicate the socket connection has been closed.
If the select subroutine
is unsuccessful, it returns a value of -1 and sets the global variable
errno to indicate the error. In this case, the contents of
the structures pointed to by the ReadList, WriteList,
and ExceptList parameters are unpredictable.
The select subroutine is
unsuccessful if one of the following are true:
| EBADF
| An invalid file descriptor or message queue identifier was
specified.
|
| EAGAIN
| Allocation of internal data structures was unsuccessful.
|
| EINTR
| A signal was caught during the select subroutine and the
signal handler was installed with an indication that subroutines are not to be
restarted.
|
| EINVAL
| One of the parameters to the select subroutine contained a
value that is not valid.
|
| EFAULT
| The ReadList, WriteList, ExceptList, or
TimeOut parameter points to a location outside of the address space
of the process.
|
This subroutine is part of Base
Operating System (BOS) Runtime.
The select subroutine is
also supported for compatibility with previous releases of this operating
system and with BSD systems.
The poll subroutine.
The Input and
Output Handling Programmer's Overview in AIX 5L Version
5.1 General Programming Concepts: Writing and Debugging
Programs.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]