diff options
Diffstat (limited to 'man2/select.2')
| -rw-r--r-- | man2/select.2 | 70 |
1 files changed, 35 insertions, 35 deletions
diff --git a/man2/select.2 b/man2/select.2 index a62ffaa9..dcc7dc9b 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -67,40 +67,40 @@ const struct timespec *\fItimeout\fB, const sigset_t *\fIsigmask\fB); .fi .SH DESCRIPTION The functions -.B select +.BR select () and -.B pselect +.BR pselect () wait for a number of file descriptors to change status. .PP Their function is identical, with three differences: .TP (i) The -.B select +.BR select () function uses a timeout that is a .I struct timeval (with seconds and microseconds), while -.B pselect +.BR pselect () uses a .I struct timespec (with seconds and nanoseconds). .TP (ii) The -.B select +.BR select () function may update the .I timeout parameter to indicate how much time was left. The -.B pselect +.BR pselect () function does not change this parameter. .TP (iii) The -.B select +.BR select () function has no .I sigmask parameter, and behaves as -.B pselect +.BR pselect () called with NULL .IR sigmask . .PP @@ -118,15 +118,15 @@ will be watched for exceptions. On exit, the sets are modified in place to indicate which descriptors actually changed status. .PP Four macros are provided to manipulate the sets. -.B FD_ZERO +.BR FD_ZERO () will clear a set. -.B FD_SET +.BR FD_SET () and -.B FD_CLR +.BR FD_CLR () add or remove a given descriptor from a set. -.B FD_ISSET +.BR FD_ISSET () tests to see if a descriptor is part of the set; this is useful after -.B select +.BR select () returns. .PP .I n @@ -134,27 +134,27 @@ is the highest-numbered descriptor in any of the three sets, plus 1. .PP .I timeout is an upper bound on the amount of time elapsed before -.B select +.BR select () returns. It may be zero, causing -.B select +.BR select () to return immediately. (This is useful for polling.) If .I timeout is NULL (no timeout), -.B select +.BR select () can block indefinitely. .PP .I sigmask is a pointer to a signal mask (see .BR sigprocmask (2)); if it is not NULL, then -.B pselect +.BR pselect () first replaces the current signal mask by the one pointed to by .IR sigmask , then does the `select' function, and then restores the original signal mask again. .PP The idea of -.B pselect +.BR pselect () is that if one wants to wait for an event, either a signal or something on a file descriptor, an atomic test is needed to prevent race conditions. (Suppose the signal handler sets a global flag and @@ -162,7 +162,7 @@ returns. Then a test of this global flag followed by a call of .BR select () could hang indefinitely if the signal arrived just after the test but just before the call. On the other hand, -.B pselect +.BR pselect () allows one to first block signals, handle the signals that have come in, then call .BR pselect () @@ -200,7 +200,7 @@ struct timespec { (However, see below on the POSIX 1003.1-2001 versions.) .PP Some code calls -.B select +.BR select () with all three sets empty, .I n zero, and a non-null @@ -208,7 +208,7 @@ zero, and a non-null as a fairly portable way to sleep with subsecond precision. .PP On Linux, the function -.B select +.BR select () modifies .I timeout to reflect the amount of time not slept; most other implementations @@ -216,11 +216,11 @@ do not do this. This causes problems both when Linux code which reads .I timeout is ported to other operating systems, and when code is ported to Linux that reuses a struct timeval for multiple -.BR select s +.BR select ()s in a loop without reinitializing it. Consider .I timeout to be undefined after -.B select +.BR select () returns. .\" .PP - it is rumoured that: .\" On BSD, when a timeout occurs, the file descriptor bits are not changed. @@ -228,9 +228,9 @@ returns. .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. .SH "RETURN VALUE" On success, -.B select +.BR select () and -.B pselect +.BR pselect () return the number of descriptors contained in the three returned descriptor sets (that is, the total number of one bits in .IR readfds , @@ -258,7 +258,7 @@ is negative or the value contained within is invalid. .TP .B ENOMEM -.B select +.BR select () was unable to allocate memory for internal tables. .SH EXAMPLE .nf @@ -296,14 +296,14 @@ main(void) { .fi .SH "CONFORMING TO" 4.4BSD (the -.B select +.BR select () function first appeared in 4.2BSD). Generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System V variants). However, note that the System V variant typically sets the timeout variable before exit, but the BSD variant does not. .PP The -.B pselect +.BR pselect () function is defined in IEEE Std 1003.1g-2000 (POSIX.1g), and part of POSIX 1003.1-2001. It is found in glibc2.1 and later. @@ -342,20 +342,20 @@ Concerning prototypes, the classical situation is that one should include .I <time.h> for -.BR select . +.BR select (). The POSIX 1003.1-2001 situation is that one should include .I <sys/select.h> for -.B select +.BR select () and -.BR pselect . +.BR pselect (). Libc4 and libc5 do not have a .I <sys/select.h> header; under glibc 2.0 and later this header exists. Under glibc 2.0 it unconditionally gives the wrong prototype for -.BR pselect , +.BR pselect (), under glibc 2.1-2.2.1 it gives -.B pselect +.BR pselect () when .B _GNU_SOURCE is defined, under glibc 2.2.2-2.2.4 it gives it when @@ -363,14 +363,14 @@ is defined, under glibc 2.2.2-2.2.4 it gives it when is defined and has a value of 600 or larger. No doubt, since POSIX 1003.1-2001, it should give the prototype by default. .SH BUGS -.B pselect +.BR pselect () is currently emulated with a user-space wrapper that has a race condition. For reliable (and more portable) signal trapping, use the self-pipe trick. (Where a signal handler writes to a pipe whose other end is read by the main loop.) Under Linux, -.B select +.BR select () may report a socket file descriptor as "ready for reading", while nevertheless a subsequent read blocks. This could for example happen when data has arrived but upon examination has wrong |