select(3C) Standard C Library Functions select(3C)NAME
select, pselect, FD_SET, FD_CLR, FD_ISSET, FD_ZERO - synchronous I/O
multiplexing
SYNOPSIS
#include <sys/time.h>
int select(int nfds,
fd_set *restrict readfds, fd_set *restrict writefds,
fd_set *restrict errorfds,
struct timeval *restrict timeout);
int pselect(int nfds,
fd_set *restrict readfds, fd_set *restrict writefds,
fd_set *restrict errorfds,
const struct timespec *restrict timeout,
const sigset_t *restrict sigmask);
void FD_SET(int fd, fd_set *fdset);
void FD_CLR(int fd, fd_set *fdset);
int FD_ISSET(int fd, fd_set *fdset);
void FD_ZERO(fd_set *fdset);
DESCRIPTION
The pselect() function examines the file descriptor sets whose
addresses are passed in the readfds, writefds, and errorfds parameters
to see if some of their descriptors are ready for reading, are ready
for writing, or have an exceptional condition pending, respectively.
The select() function is equivalent to the pselect() function, except
as follows:
o For the select() function, the timeout period is given in
seconds and microseconds in an argument of type struct
timeval, whereas for the pselect() function the timeout
period is given in seconds and nanoseconds in an argument of
type struct timespec.
o The select() function has no sigmask argument. It behaves as
pselect() does when sigmask is a null pointer.
o Upon successful completion, the select() function might mod‐
ify the object pointed to by the timeout argument.
The select() and pselect() functions support regular files, terminal
and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and
sockets. The behavior of select() and pselect() on file descriptors
that refer to other types of file is unspecified.
The nfds argument specifies the range of file descriptors to be tested.
The first nfds descriptors are checked in each set; that is, the
descriptors from zero through nfds-1 in the descriptor sets are exam‐
ined.
If the readfs argument is not a null pointer, it points to an object of
type fd_set that on input specifies the file descriptors to be checked
for being ready to read, and on output indicates which file descriptors
are ready to read.
If the writefs argument is not a null pointer, it points to an object
of type fd_set that on input specifies the file descriptors to be
checked for being ready to write, and on output indicates which file
descriptors are ready to write.
If the errorfds argument is not a null pointer, it points to an object
of type fd_set that on input specifies the file descriptors to be
checked for error conditions pending, and on output indicates which
file descriptors have error conditions pending.
Upon successful completion, the objects pointed to by the readfs,
writefs, and errorfds arguments are modified to indicate which file
descriptors are ready for reading, ready for writing, or have an error
condition pending, respectively, and return the total number of ready
descriptors in all the output sets. For each file descriptor less than
nfds, the corresponding bit will be set on successful completion if it
was set on input and the associated condition is true for that file
descriptor.
If none of the selected descriptors are ready for the requested opera‐
tion, the select() or pselect() function blocks until at least one of
the requested operations becomes ready, until the timeout occurs, or
until interrupted by a signal. The timeout parameter controls how long
the select() or pselect() function takes before timing out. If the
timeout parameter is not a null pointer, it specifies a maximum inter‐
val to wait for the selection to complete. If the specified time inter‐
val expires without any requested operation becoming ready, the func‐
tion returns. If the timeout parameter is a null pointer, then the call
to select() or pselect() blocks indefinitely until at least one
descriptor meets the specified criteria. To effect a poll, the timeout
parameter should not be a null pointer, and should point to a zero-val‐
ued timespec structure.
The use of a timeout does not affect any pending timers set up by
alarm(2), ualarm(3C), or setitimer(2).
If sigmask is not a null pointer, then the pselect() function replaces
the signal mask of the process by the set of signals pointed to by sig‐
mask before examining the descriptors, and restores the signal mask of
the process before returning.
A descriptor is considered ready for reading when a call to an input
function with O_NONBLOCK clear would not block, whether or not the
function would transfer data successfully. (The function might return
data, an end-of-file indication, or an error other than one indicating
that it is blocked, and in each of these cases the descriptor will be
considered ready for reading.)
A descriptor is considered ready for writing when a call to an output
function with O_NONBLOCK clear would not block, whether or not the
function would transfer data successfully.
If a socket has a pending error, it is considered to have an excep‐
tional condition pending. Otherwise, what constitutes an exceptional
condition is file type-specific. For a file descriptor for use with a
socket, it is protocol-specific except as noted below. For other file
types, if the operation is meaningless for a particular file type,
select() or pselect() indicates that the descriptor is ready for read
or write operations and indicates that the descriptor has no excep‐
tional condition pending.
If a descriptor refers to a socket, the implied input function is the
recvmsg(3XNET) function with parameters requesting normal and ancillary
data, such that the presence of either type causes the socket to be
marked as readable. The presence of out-of-band data is checked if the
socket option SO_OOBINLINE has been enabled, as out-of-band data is
enqueued with normal data. If the socket is currently listening, then
it is marked as readable if an incoming connection request has been
received, and a call to the accept function completes without blocking.
If a descriptor refers to a socket, the implied output function is the
sendmsg(3XNET) function supplying an amount of normal data equal to the
current value of the SO_SNDLOWAT option for the socket. If a non-block‐
ing call to the connect function has been made for a socket, and the
connection attempt has either succeeded or failed leaving a pending
error, the socket is marked as writable.
A socket is considered to have an exceptional condition pending if a
receive operation with O_NONBLOCK clear for the open file description
and with the MSG_OOB flag set would return out-of-band data without
blocking. (It is protocol-specific whether the MSG_OOB flag would be
used to read out-of-band data.) A socket will also be considered to
have an exceptional condition pending if an out-of-band data mark is
present in the receive queue.
A file descriptor for a socket that is listening for connections will
indicate that it is ready for reading, when connections are available.
A file descriptor for a socket that is connecting asynchronously will
indicate that it is ready for writing, when a connection has been
established.
Selecting true for reading on a socket descriptor upon which a lis‐
ten(3XNET) call has been performed indicates that a subsequent
accept(3XNET) call on that descriptor will not block.
If the timeout argument is not a null pointer, it points to an object
of type struct timeval that specifies a maximum interval to wait for
the selection to complete. If the timeout argument points to an object
of type struct timeval whose members are 0, select() does not block. If
the timeout argument is a null pointer, select() blocks until an event
causes one of the masks to be returned with a valid (non-zero) value.
If the time limit expires before any event occurs that would cause one
of the masks to be set to a non-zero value, select() completes success‐
fully and returns 0.
If the readfs, writefs, and errorfds arguments are all null pointers
and the timeout argument is not a null pointer, select() or pselect()
blocks for the time specified, or until interrupted by a signal. If the
readfs, writefs, and errorfds arguments are all null pointers and the
timeout argument is a null pointer, select() blocks until interrupted
by a signal.
File descriptors associated with regular files always select true for
ready to read, ready to write, and error conditions.
On failure, the objects pointed to by the readfs, writefs, and errorfds
arguments are not modified. If the timeout interval expires without
the specified condition being true for any of the specified file
descriptors, the objects pointed to by the readfs, writefs, and
errorfds arguments have all bits set to 0.
File descriptor masks of type fd_set can be initialized and tested with
the macros FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO().
FD_CLR(fd, &fdset) Clears the bit for the file descriptor fd in
the file descriptor set fdset.
FD_ISSET(fd, &fdset) Returns a non-zero value if the bit for the
file descriptor fd is set in the file descrip‐
tor set pointed to by fdset, and 0 otherwise.
FD_SET(fd, &fdset) Sets the bit for the file descriptor fd in the
file descriptor set fdset.
FD_ZERO(&fdset) Initializes the file descriptor set fdset to
have zero bits for all file descriptors.
The behavior of these macros is undefined if the fd argument is less
than 0 or greater than or equal to FD_SETSIZE, or if fd is not a valid
file descriptor, or if any of the arguments are expressions with side
effects.
RETURN VALUES
On successful completion, select() and pselect() return the total num‐
ber of bits set in the bit masks. Otherwise, −1 is returned and errno
is set to indicate the error.
The FD_CLR(), FD_SET(), and FD_ZERO() macros return no value. The
FD_ISSET() macro returns a non-zero value if the bit for the file
descriptor fd is set in the file descriptor set pointed to by fdset,
and 0 otherwise.
ERRORS
The select() and pselect() functions will fail if:
EBADF One or more of the file descriptor sets specified a file
descriptor that is not a valid open file descriptor.
EINTR The function was interrupted before any of the selected
events occurred and before the timeout interval expired.
If SA_RESTART has been set for the interrupting signal, it is
implementation-dependent whether select() restarts or returns
with EINTR.
EINVAL An invalid timeout interval was specified.
EINVAL The nfds argument is less than 0 or greater than FD_SETSIZE.
EINVAL One of the specified file descriptors refers to a STREAM or
multiplexer that is linked (directly or indirectly) down‐
stream from a multiplexer.
EINVAL A component of the pointed-to time limit is outside the
acceptable range: t_sec must be between 0 and 10^8, inclu‐
sive. t_usec must be greater than or equal to 0, and less
than 10^6.
USAGE
The poll(2) function is preferred over this function. It must be used
when the number of file descriptors exceeds FD_SETSIZE.
The use of a timeout does not affect any pending timers set up by
alarm(2), ualarm(3C) or setitimer(2).
On successful completion, the object pointed to by the timeout argument
may be modified.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
├─────────────────────────────┼─────────────────────────────┤
│Standard │See standards(5). │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOalarm(2), fcntl(2), poll(2), read(2), setitimer(2), write(2),
accept(3SOCKET), listen(3SOCKET), ualarm(3C), attributes(5), stan‐
dards(5)NOTES
The default value for FD_SETSIZE (currently 1024) is larger than the
default limit on the number of open files. To accommodate 32-bit appli‐
cations that wish to use a larger number of open files with select(),
it is possible to increase this size at compile time by providing a
larger definition of FD_SETSIZE before the inclusion of any system-sup‐
plied header. The maximum supported size for FD_SETSIZE is 65536. The
default value is already 65536 for 64-bit applications.
SunOS 5.11 1 Nov 2004 select(3C)
