mirror of https://github.com/mkerrisk/man-pages
select.2: Rewrite DESCRIPTION
Improve structure and readability, at the same time incorporating text and details that were formerly in select_tut(2). Also move a few details in other parts of the page into DESCRIPTION. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
f7cd286592
commit
095d8388cf
172
man2/select.2
172
man2/select.2
|
@ -1,5 +1,6 @@
|
||||||
.\" This manpage is copyright (C) 1992 Drew Eckhardt,
|
.\" This manpage is copyright (C) 1992 Drew Eckhardt,
|
||||||
.\" copyright (C) 1995 Michael Shields.
|
.\" copyright (C) 1995 Michael Shields,
|
||||||
|
.\" copyright (C) 2001 Paul Sheer,
|
||||||
.\" copyright (C) 2006, 2019 Michael Kerrisk <mtk.manpages@gmail.com>
|
.\" copyright (C) 2006, 2019 Michael Kerrisk <mtk.manpages@gmail.com>
|
||||||
.\"
|
.\"
|
||||||
.\" %%%LICENSE_START(VERBATIM)
|
.\" %%%LICENSE_START(VERBATIM)
|
||||||
|
@ -80,56 +81,122 @@ without blocking.
|
||||||
can monitor only file descriptors numbers that are less than
|
can monitor only file descriptors numbers that are less than
|
||||||
.BR FD_SETSIZE ;
|
.BR FD_SETSIZE ;
|
||||||
.BR poll (2)
|
.BR poll (2)
|
||||||
does not have this limitation.
|
and
|
||||||
|
.BR epoll (7)
|
||||||
|
do not have this limitation.
|
||||||
See BUGS.
|
See BUGS.
|
||||||
|
.\"
|
||||||
|
.SS File descriptor sets
|
||||||
|
The principal arguments of
|
||||||
|
.BR select ()
|
||||||
|
are three "sets" of file descriptors (declared with the type
|
||||||
|
.IR fd_set ),
|
||||||
|
which allow the caller to wait for three classes of events
|
||||||
|
on the specified set of file descriptors.
|
||||||
|
Each of the
|
||||||
|
.I fd_set
|
||||||
|
arguments may be specified as NULL if no file descriptors are
|
||||||
|
to be watched for the corresponding class of events.
|
||||||
.PP
|
.PP
|
||||||
Three independent sets of file descriptors are watched.
|
.BR "Note well" :
|
||||||
The file descriptors listed in
|
Upon return, each of the file descriptor sets is modified in place
|
||||||
|
to indicate which file descriptors are currently "ready".
|
||||||
|
Thus, if using
|
||||||
|
.BR select ()
|
||||||
|
within a loop, the sets \fImust be reinitialized\fP before each call.
|
||||||
|
.PP
|
||||||
|
The implementation of the
|
||||||
|
.I fd_set
|
||||||
|
arguments as value-result arguments is a design error that is avoided in
|
||||||
|
.BR poll (2)
|
||||||
|
and
|
||||||
|
.BR epoll (7).
|
||||||
|
.PP
|
||||||
|
The contents of a file descriptor set can be manipulated
|
||||||
|
using the following macros:
|
||||||
|
.TP
|
||||||
|
.BR FD_ZERO ()
|
||||||
|
This macro clears (removes all file descriptors from)
|
||||||
|
.IR set .
|
||||||
|
It should be employed as the first step in initializing a file descriptor set.
|
||||||
|
.TP
|
||||||
|
.BR FD_SET ()
|
||||||
|
This macro adds the file descriptor
|
||||||
|
.I fd
|
||||||
|
to
|
||||||
|
.IR set .
|
||||||
|
.TP
|
||||||
|
.BR FD_CLR ()
|
||||||
|
This macro removes the file descriptor
|
||||||
|
.I fd
|
||||||
|
from
|
||||||
|
.IR set .
|
||||||
|
.TP
|
||||||
|
.BR FD_ISSET ()
|
||||||
|
.BR select ()
|
||||||
|
modifies the contents of the sets according to the rules
|
||||||
|
described below.
|
||||||
|
After calling
|
||||||
|
.BR select (),
|
||||||
|
the
|
||||||
|
.BR FD_ISSET ()
|
||||||
|
macro
|
||||||
|
can be used to test if a file descriptor is still present in a set.
|
||||||
|
.BR FD_ISSET ()
|
||||||
|
returns nonzero if the file descriptor
|
||||||
|
.I fd
|
||||||
|
is present in
|
||||||
|
.IR set ,
|
||||||
|
and zero if it is not.
|
||||||
|
.\"
|
||||||
|
.SS Arguments
|
||||||
|
The arguments of
|
||||||
|
.BR select ()
|
||||||
|
are as follows:
|
||||||
|
.TP
|
||||||
.I readfds
|
.I readfds
|
||||||
will be watched to see if characters become
|
The file descriptors in this set are watched to see if they are
|
||||||
available for reading (more precisely, to see if a read will not
|
ready for reading.
|
||||||
block; in particular, a file descriptor is also ready on end-of-file).
|
A file descriptor is ready for reading if a read operation will not
|
||||||
The file descriptors in
|
block; in particular, a file descriptor is also ready on end-of-file.
|
||||||
|
.IP
|
||||||
|
After
|
||||||
|
.BR select ()
|
||||||
|
has returned, \fIreadfds\fP will be
|
||||||
|
cleared of all file descriptors except for those that are ready for reading.
|
||||||
|
.TP
|
||||||
.I writefds
|
.I writefds
|
||||||
will be watched to see if space is available for write (though a large
|
The file descriptors in this set are watched to see if they are
|
||||||
write may still block).
|
ready for writing.
|
||||||
The file descriptors in
|
A file descriptor is ready for writing if a write operation will not block.
|
||||||
|
However, even if a file descriptor indicates as writable,
|
||||||
|
a large write may still block.
|
||||||
|
.IP
|
||||||
|
After
|
||||||
|
.BR select ()
|
||||||
|
has returned, \fIwritefds\fP will be
|
||||||
|
cleared of all file descriptors except for those that are ready for writing.
|
||||||
|
.TP
|
||||||
.I exceptfds
|
.I exceptfds
|
||||||
will be watched for exceptional conditions.
|
The file descriptors in this set are watched for "exceptional conditions".
|
||||||
(For examples of some exceptional conditions, see the discussion of
|
For examples of some exceptional conditions, see the discussion of
|
||||||
.B POLLPRI
|
.B POLLPRI
|
||||||
in
|
in
|
||||||
.BR poll (2).)
|
.BR poll (2).
|
||||||
.PP
|
.IP
|
||||||
Upon return, each of the file descriptor sets is modified in place
|
After
|
||||||
to indicate which file descriptors actually changed status.
|
|
||||||
(Thus, if using
|
|
||||||
.BR select ()
|
.BR select ()
|
||||||
within a loop, the sets must be reinitialized before each call.)
|
has returned,
|
||||||
.PP
|
\fIexceptfds\fP will be cleared of all file descriptors except for those
|
||||||
Each of the three file descriptor sets may be specified as NULL
|
for which an exceptional condition has occurred.
|
||||||
if no file descriptors are to be watched for the corresponding class
|
.TP
|
||||||
of events.
|
|
||||||
.PP
|
|
||||||
Four macros are provided to manipulate the sets.
|
|
||||||
.BR FD_ZERO ()
|
|
||||||
clears a set.
|
|
||||||
.BR FD_SET ()
|
|
||||||
and
|
|
||||||
.BR FD_CLR ()
|
|
||||||
add and remove a given file descriptor from a set.
|
|
||||||
.BR FD_ISSET ()
|
|
||||||
tests to see if a file descriptor is part of the set;
|
|
||||||
this is useful after
|
|
||||||
.BR select ()
|
|
||||||
returns.
|
|
||||||
.PP
|
|
||||||
.I nfds
|
.I nfds
|
||||||
should be set to the highest-numbered file descriptor in any
|
This argument should be set to the highest-numbered file descriptor in any
|
||||||
of the three sets, plus 1.
|
of the three sets, plus 1.
|
||||||
The indicated file descriptors in each set are checked, up to this limit
|
The indicated file descriptors in each set are checked, up to this limit
|
||||||
(but see BUGS).
|
(but see BUGS).
|
||||||
.PP
|
.TP
|
||||||
|
.I timeout
|
||||||
The
|
The
|
||||||
.I timeout
|
.I timeout
|
||||||
argument is a
|
argument is a
|
||||||
|
@ -138,29 +205,33 @@ structure (shown below) that specifies the interval that
|
||||||
.BR select ()
|
.BR select ()
|
||||||
should block waiting for a file descriptor to become ready.
|
should block waiting for a file descriptor to become ready.
|
||||||
The call will block until either:
|
The call will block until either:
|
||||||
|
.RS
|
||||||
.IP * 3
|
.IP * 3
|
||||||
a file descriptor becomes ready;
|
a file descriptor becomes ready;
|
||||||
.IP *
|
.IP *
|
||||||
the call is interrupted by a signal handler; or
|
the call is interrupted by a signal handler; or
|
||||||
.IP *
|
.IP *
|
||||||
the timeout expires.
|
the timeout expires.
|
||||||
.PP
|
.RE
|
||||||
|
.IP
|
||||||
Note that the
|
Note that the
|
||||||
.I timeout
|
.I timeout
|
||||||
interval will be rounded up to the system clock granularity,
|
interval will be rounded up to the system clock granularity,
|
||||||
and kernel scheduling delays mean that the blocking interval
|
and kernel scheduling delays mean that the blocking interval
|
||||||
may overrun by a small amount.
|
may overrun by a small amount.
|
||||||
|
.IP
|
||||||
If both fields of the
|
If both fields of the
|
||||||
.I timeval
|
.I timeval
|
||||||
structure are zero, then
|
structure are zero, then
|
||||||
.BR select ()
|
.BR select ()
|
||||||
returns immediately.
|
returns immediately.
|
||||||
(This is useful for polling.)
|
(This is useful for polling.)
|
||||||
|
.IP
|
||||||
If
|
If
|
||||||
.I timeout
|
.I timeout
|
||||||
is NULL (no timeout),
|
is specified as NULL,
|
||||||
.BR select ()
|
.BR select ()
|
||||||
can block indefinitely.
|
blocks indefinitely waiting for a file descriptor to become ready.
|
||||||
.\"
|
.\"
|
||||||
.SS pselect()
|
.SS pselect()
|
||||||
.PP
|
.PP
|
||||||
|
@ -211,6 +282,12 @@ first replaces the current signal mask by the one pointed to by
|
||||||
.IR sigmask ,
|
.IR sigmask ,
|
||||||
then does the "select" function, and then restores the original
|
then does the "select" function, and then restores the original
|
||||||
signal mask.
|
signal mask.
|
||||||
|
(If
|
||||||
|
.I sigmask
|
||||||
|
is NULL,
|
||||||
|
the signal mask is not modified during the
|
||||||
|
.BR pselect ()
|
||||||
|
call.)
|
||||||
.PP
|
.PP
|
||||||
Other than the difference in the precision of the
|
Other than the difference in the precision of the
|
||||||
.I timeout
|
.I timeout
|
||||||
|
@ -567,17 +644,10 @@ defined as 1024, and the
|
||||||
macros operating according to that limit.
|
macros operating according to that limit.
|
||||||
To monitor file descriptors greater than 1023, use
|
To monitor file descriptors greater than 1023, use
|
||||||
.BR poll (2)
|
.BR poll (2)
|
||||||
|
or
|
||||||
|
.BR epoll (7)
|
||||||
instead.
|
instead.
|
||||||
.PP
|
.PP
|
||||||
The implementation of the
|
|
||||||
.I fd_set
|
|
||||||
arguments as value-result arguments means that they must be
|
|
||||||
reinitialized on each call to
|
|
||||||
.BR select ().
|
|
||||||
This design error is avoided by
|
|
||||||
.BR poll (2),
|
|
||||||
which uses separate structure fields for the input and output of the call.
|
|
||||||
.PP
|
|
||||||
According to POSIX,
|
According to POSIX,
|
||||||
.BR select ()
|
.BR select ()
|
||||||
should check all specified file descriptors in the three file descriptor sets,
|
should check all specified file descriptors in the three file descriptor sets,
|
||||||
|
|
Loading…
Reference in New Issue