select(2)select(2)NAMEselect - Synchronous I/O multiplexing
SYNOPSIS
#include <sys/time.h>
int select(
int nfds,
fd_set *readfds,
fd_set *writefds,
fd_set *exceptfds,
struct timeval *timeout ); void FD_CLR(
int fd,
fd_set *fdset ); int FD_ISSET(
int fd,
fd_set *fdset ); void FD_SET(
int fd,
fd_set *fdset ); void FD_ZERO(
fd_set *fdset );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
select(): XSH4.2, XSH5.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the number of open objects that may be ready for reading or
writing or that have exceptions pending. The nfds parameter cannot be
greater than FD_SETSIZE. Points to an I/O descriptor set consisting of
file descriptors of objects opened for reading. When the readfds
parameter is a null pointer, the read I/O descriptor set is ignored by
the select() function. Points to an I/O descriptor set consisting of
file descriptors for objects opened for writing. When the writefds
parameter is a null pointer, the write I/O descriptor set is ignored.
Points to an I/O descriptor set consisting of file descriptors for
objects opened for reading or writing that have an exception pending.
When the exceptfds parameter is a null pointer, the exception I/O
descriptor set is ignored. Points to a type timeval structure that
specifies the maximum time to wait for a response to a select() func‐
tion. When the timeout parameter has a nonzero value, the maximum time
interval to wait for the select() function to complete is specified by
values stored in space reserved by the type timeval structure pointed
to by the timeout parameter.
When the timeout parameter is a null pointer, the select() func‐
tion blocks indefinitely. To poll, the timeout parameter should
be specified as a nonzero value and point to a zero-valued
timeval structure.
The use of a timeout does not affect any pending timers set up
by alarm(), unalarm(), or settimer(). Specifies a file descrip‐
tor. Points to an I/O descriptor set.
DESCRIPTION
The select() function checks the status of objects identified by bit
masks called I/O descriptor sets. Each I/O descriptor set consists of
an array of bits whose relative position and state represent a file
descriptor and the status of its corresponding object. There is an I/O
descriptor set for reading, writing, and for pending exceptions. These
I/O descriptor sets are pointed to by the readfds, writefds, and
exceptfds parameters, respectively. The I/O descriptor sets provide a
means of monitoring the read, write, and exception status of objects
represented by file descriptors.
The status of nfds-1 file descriptors in each referenced I/O descriptor
set is checked when the select() function is called. The select() func‐
tion returns a modified I/O descriptor set, which has the following
characteristics: for any selected I/O descriptor set pointed to by the
readfds, writefds, or exceptfds parameters, if the state of any bit
corresponding with an active file descriptor is set on entry, when the
object represented by the set bit is ready for reading, writing, or its
exception condition has been satisfied, a corresponding bit position is
also set in the returned I/O descriptor set pointed to by the readfds,
writefds, or exceptfds parameters.
When it returns successfully, select() first replaces the original I/O
descriptor sets with the corresponding I/O descriptor sets (that have a
set bit for each file descriptor representing those objects that are
ready for the requested operation). Then, the function returns the
total number of ready objects represented by set bits in all the I/O
descriptor sets.
Note: When objects are ready for the requested operation, the operation
will not block. This does not necessarily mean, however, that data is
available for the operation. See read(2) and write(2) for information
on when these calls would block.
After an I/O descriptor set is created, it may be modified with the
following macros: Clears the I/O descriptor bit specified by file
descriptor fd in the I/O descriptor set addressed by fdset. Returns a
nonzero value when the I/O descriptor bit for fd is included in the I/O
descriptor set addressed by fdset. Otherwise 0 (zero) is returned.
Includes the particular I/O descriptor bit specified by fd in the I/O
descriptor set addressed by fdset. Initializes the I/O descriptor set
addressed by fdset to a null value.
The behavior of these macros is undefined when parameter fd has a value
less than 0 (zero) or greater than or equal to FD_SETSIZE, which is
normally at least equal to the maximum number of file descriptors sup‐
ported by the system.
The select() function supports regular files, terminal and pseudo-ter‐
minal devices, STREAMS-based files, FIFOs, and pipes. The behavior of
the select() function on file descriptors that refer to other types of
files is unspecified.
For sockets, a file descriptor for a socket that is listening for con‐
nections indicates that it is ready for reading when connections are
available. A file descriptor for a socket that is connecting asyn‐
chronously indicates that it is ready for writing after a connection is
established.
NOTES
By default, this function supports up to 4K open file descriptors per
process. However, up to 64K open file descriptors per process is sup‐
ported if an application has enabled this capability by using the
SSI_FD_NEWMAX operation in a setsysinfo() call and the RLIMIT_NOFILE
argument in a setrlimit() call. For summary information on retrieving
and setting limits on the number of open file descriptors per process,
see the description of the open_max_hard and open_max_soft system
attributes in sys_attrs_proc(5).
In addition to the requirement that limits greater than 4K must be
enabled by the setsysinfo() and setrlimit() calls, programmers must
specify an alternate value for FD_SETSIZE--one that does not exceed
64K--before they include <sys/select.h> in a program to be compiled. If
not set to be a higher value in the program before compilation, FD_SET‐
SIZE is set in the <sys/select.h> header file to be 4K.
For a more in-depth discussion of this subject, refer to the section
about tuning open file limits in the System Configuration and Tuning
manual.
RETURN VALUES
Upon successful completion, the select() function returns the number of
ready objects represented by corresponding file descriptor bits in the
I/O descriptor sets. When an error occurs, -1 is returned and errno is
set to indicate the error.
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 (zero).
When select() returns an error, including a process interrupt, the I/O
descriptor sets pointed to by the readfds, writefds, and exceptfds
parameters remain unmodified.
ERRORS
The select() function sets errno to the specified values for the fol‐
lowing conditions:
One or more of the I/O descriptor sets specified an invalid file
descriptor. A signal was delivered before the time limit specified by
the timeout parameter expired and before any of the selected events
occurred. The time limit specified by the timeout parameter is
invalid.
The nfds parameter is less than 0, or greater than or equal to
FD_SETSIZE.
One of the specified file descriptors refers to a STREAM or mul‐
tiplexer that is linked (directly or indirectly) downstream from
a multiplexer. [Tru64 UNIX] Allocation of internal data struc‐
tures failed. A later call to the select() function may complete
successfully.
SEE ALSO
Functions: accept(2), connect(2), getdtablesize(2), poll(2)read(2),
recv(2), send(2), setsysinfo(2), write(2)
Standards: standards(5)select(2)
