Standard C Library Functions select(3C)
NAME
select, pselect, FDSET, FDCLR, FDISET, FDZERO - syn-
chronous I/O multiplexing
SYNOPSIS
#include
int select(int nfds,
fdset *restrict readfds, fdset *restrict writefds,
fdset *restrict errorfds,
struct timeval *restrict timeout);
int pselect(int nfds,
fdset *restrict readfds, fdset *restrict writefds,
fdset *restrict errorfds,
const struct timespec *restrict timeout,
const sigsett *restrict sigmask);
void FDSET(int fd, fdset *fdset);
void FDCLR(int fd, fdset *fdset);
int FDISET(int fd, fdset *fdset);
void FDZERO(fdset *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 excep-
tional condition pending, respectively.
The select() function is equivalent to the pselect() func-
tion, 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.
SunOS 5.11 Last change: 1 Nov 2004 1
Standard C Library Functions select(3C)
o Upon successful completion, the select() function
might modify 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 examined.
If the readfs argument is not a null pointer, it points to
an object of type fdset 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 fdset 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 fdset that on input specifies the file
descriptors to be checked for error conditions pending, and
on output indicates which file descriptors have error condi-
tions 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, respec-
tively, 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 com-
pletion 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 operation, the select() or pselect() function
blocks until at least one of the requested operations
becomes ready, until the timeout occurs, or until
SunOS 5.11 Last change: 1 Nov 2004 2
Standard C Library Functions select(3C)
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 interval to wait for the selection to
complete. If the specified time interval expires without any
requested operation becoming ready, the function 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-valued 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() func-
tion replaces the signal mask of the process by the set of
signals pointed to by sigmask before examining the descrip-
tors, 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 ONONBLOCK clear would not block,
whether or not the function would transfer data success-
fully. (The function might return data, an end-of-file indi-
cation, 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 ONONBLOCK clear would not block,
whether or not the function would transfer data success-
fully.
If a socket has a pending error, it is considered to have an
exceptional 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 opera-
tion 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
exceptional condition pending.
If a descriptor refers to a socket, the implied input func-
tion is the recvmsg(3XNET) function with parameters
SunOS 5.11 Last change: 1 Nov 2004 3
Standard C Library Functions select(3C)
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 SOBINLINE 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 con-
nection request has been received, and a call to the accept
function completes without blocking.
If a descriptor refers to a socket, the implied output func-
tion is the sendmsg(3XNET) function supplying an amount of
normal data equal to the current value of the SOSNDLOWAT
option for the socket. If a non-blocking 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 ONONBLOCK clear for the
open file description and with the MSGOB flag set would
return out-of-band data without blocking. (It is protocol-
specific whether the MSGOB 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 connec-
tions will indicate that it is ready for reading, when con-
nections 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 listen(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 successfully and returns
SunOS 5.11 Last change: 1 Nov 2004 4
Standard C Library Functions select(3C)
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 inter-
rupted by a signal.
File descriptors associated with regular files always select
true for ready to read, ready to write, and error condi-
tions.
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 fdset can be initialized and
tested with the macros FDCLR(), FDISET(), FDSET(), and
FDZERO().
FDCLR(fd, &fdset) Clears the bit for the file descrip-
tor fd in the file descriptor set
fdset.
FDISET(fd, &fdset) 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.
FDSET(fd, &fdset) Sets the bit for the file descriptor
fd in the file descriptor set fdset.
FDZERO(&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 FDSETSIZE, or if
SunOS 5.11 Last change: 1 Nov 2004 5
Standard C Library Functions select(3C)
fd is not a valid file descriptor, or if any of the argu-
ments are expressions with side effects.
RETURN VALUES
On successful completion, select() and pselect() return the
total number of bits set in the bit masks. Otherwise, -1 is
returned and errno is set to indicate the error.
The FDCLR(), FDSET(), and FDZERO() macros return no
value. The FDISET() 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.
ERORS
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 SARESTART 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
FDSETSIZE.
EINVAL One of the specified file descriptors refers to a
STREAM or multiplexer that is linked (directly or
indirectly) downstream from a multiplexer.
EINVAL A component of the pointed-to time limit is out-
side the acceptable range: tsec must be between 0
and 10^8, inclusive. tusec 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
SunOS 5.11 Last change: 1 Nov 2004 6
Standard C Library Functions select(3C)
FDSETSIZE.
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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
alarm(2), fcntl(2), poll(2), read(2), setitimer(2),
write(2), accept(3SOCKET), listen(3SOCKET), ualarm(3C),
attributes(5), standards(5)
NOTES
The default value for FDSETSIZE (currently 1024) is larger
than the default limit on the number of open files. To
accommodate 32-bit applications 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 FDSETSIZE before the inclusion of any
system-supplied header. The maximum supported size for
FDSETSIZE is 65536. The default value is already 65536 for
64-bit applications.
SunOS 5.11 Last change: 1 Nov 2004 7
|
