From 3539d3e72da3fb0042e8c05a196d1f50a408c3cd Mon Sep 17 00:00:00 2001 From: sharkdp Date: Wed, 14 Oct 2020 22:49:38 +0200 Subject: [PATCH] Add Manpage syntax regression test for select(2) --- .../highlighted/Manpage/select-2.man | 330 ++++++++++++++++++ .../syntax-tests/source/Manpage/select-2.man | 330 ++++++++++++++++++ 2 files changed, 660 insertions(+) create mode 100644 tests/syntax-tests/highlighted/Manpage/select-2.man create mode 100644 tests/syntax-tests/source/Manpage/select-2.man diff --git a/tests/syntax-tests/highlighted/Manpage/select-2.man b/tests/syntax-tests/highlighted/Manpage/select-2.man new file mode 100644 index 00000000..5ca67908 --- /dev/null +++ b/tests/syntax-tests/highlighted/Manpage/select-2.man @@ -0,0 +1,330 @@ +SELECT(2) Linux Programmer's Manual SELECT(2) + +NAME + select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O multiplexing + +SYNOPSIS + #include <sys/select.h> + + int select(int nfds, fd_set *readfds, fd_set *writefds, + fd_set *exceptfds, struct timeval *timeout); + + void FD_CLR(int fd, fd_set *set); + int FD_ISSET(int fd, fd_set *set); + void FD_SET(int fd, fd_set *set); + void FD_ZERO(fd_set *set); + + int pselect(int nfds, fd_set *readfds, fd_set *writefds, + fd_set *exceptfds, const struct timespec *timeout, + const sigset_t *sigmask); + + Feature Test Macro Requirements for glibc (see feature_test_macros(7)): + + pselect(): _POSIX_C_SOURCE >= 200112L + +DESCRIPTION + select() allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become + "ready" for some class of I/O operation (e.g., input possible). A file descriptor is considered ready if it is possible to + perform a corresponding I/O operation (e.g., read(2), or a sufficiently small write(2)) without blocking. + + select() can monitor only file descriptors numbers that are less than FD_SETSIZE; poll(2) and epoll(7) do not have this limi‐ + tation. See BUGS. + + File descriptor sets + The principal arguments of select() are three "sets" of file descriptors (declared with the type fd_set), which allow the + caller to wait for three classes of events on the specified set of file descriptors. Each of the fd_set arguments may be + specified as NULL if no file descriptors are to be watched for the corresponding class of events. + + Note well: Upon return, each of the file descriptor sets is modified in place to indicate which file descriptors are currently + "ready". Thus, if using select() within a loop, the sets must be reinitialized before each call. The implementation of the + fd_set arguments as value-result arguments is a design error that is avoided in poll(2) and epoll(7). + + The contents of a file descriptor set can be manipulated using the following macros: + + FD_ZERO() + This macro clears (removes all file descriptors from) set. It should be employed as the first step in initializing a + file descriptor set. + + FD_SET() + This macro adds the file descriptor fd to set. Adding a file descriptor that is already present in the set is a no-op, + and does not produce an error. + + FD_CLR() + This macro removes the file descriptor fd from set. Removing a file descriptor that is not present in the set is a no- + op, and does not produce an error. + + FD_ISSET() + select() modifies the contents of the sets according to the rules described below. After calling select(), the FD_IS‐ + SET() macro can be used to test if a file descriptor is still present in a set. FD_ISSET() returns nonzero if the file + descriptor fd is present in set, and zero if it is not. + + Arguments + The arguments of select() are as follows: + + readfds + The file descriptors in this set are watched to see if they are ready for reading. A file descriptor is ready for + reading if a read operation will not block; in particular, a file descriptor is also ready on end-of-file. + + After select() has returned, readfds will be cleared of all file descriptors except for those that are ready for read‐ + ing. + + writefds + The file descriptors in this set are watched to see if they are ready for writing. 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. + + After select() has returned, writefds will be cleared of all file descriptors except for those that are ready for writ‐ + ing. + + exceptfds + The file descriptors in this set are watched for "exceptional conditions". For examples of some exceptional condi‐ + tions, see the discussion of POLLPRI in poll(2). + + After select() has returned, exceptfds will be cleared of all file descriptors except for those for which an excep‐ + tional condition has occurred. + + nfds This argument should be set to the highest-numbered file descriptor in any of the three sets, plus 1. The indicated + file descriptors in each set are checked, up to this limit (but see BUGS). + + timeout + The timeout argument is a timeval structure (shown below) that specifies the interval that select() should block wait‐ + ing for a file descriptor to become ready. The call will block until either: + + • a file descriptor becomes ready; + + • the call is interrupted by a signal handler; or + + • the timeout expires. + + Note that the timeout interval will be rounded up to the system clock granularity, and kernel scheduling delays mean + that the blocking interval may overrun by a small amount. + + If both fields of the timeval structure are zero, then select() returns immediately. (This is useful for polling.) + + If timeout is specified as NULL, select() blocks indefinitely waiting for a file descriptor to become ready. + + pselect() + The pselect() system call allows an application to safely wait until either a file descriptor becomes ready or until a signal + is caught. + + The operation of select() and pselect() is identical, other than these three differences: + + • select() uses a timeout that is a struct timeval (with seconds and microseconds), while pselect() uses a struct timespec + (with seconds and nanoseconds). + + • select() may update the timeout argument to indicate how much time was left. pselect() does not change this argument. + + • select() has no sigmask argument, and behaves as pselect() called with NULL sigmask. + + sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is not NULL, then pselect() first replaces the current sig‐ + nal mask by the one pointed to by sigmask, then does the "select" function, and then restores the original signal mask. (If + sigmask is NULL, the signal mask is not modified during the pselect() call.) + + Other than the difference in the precision of the timeout argument, the following pselect() call: + + ready = pselect(nfds, &readfds, &writefds, &exceptfds, + timeout, &sigmask); + + is equivalent to atomically executing the following calls: + + sigset_t origmask; + + pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); + ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); + pthread_sigmask(SIG_SETMASK, &origmask, NULL); + + The reason that pselect() is needed is that if one wants to wait for either a signal or for a file descriptor to become ready, + then an atomic test is needed to prevent race conditions. (Suppose the signal handler sets a global flag and returns. Then a + test of this global flag followed by a call of select() could hang indefinitely if the signal arrived just after the test but + just before the call. By contrast, pselect() allows one to first block signals, handle the signals that have come in, then + call pselect() with the desired sigmask, avoiding the race.) + + The timeout + The timeout argument for select() is a structure of the following type: + + struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ + }; + + The corresponding argument for pselect() has the following type: + + struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ + }; + + On Linux, select() modifies timeout to reflect the amount of time not slept; most other implementations do not do this. + (POSIX.1 permits either behavior.) This causes problems both when Linux code which reads timeout is ported to other operating + systems, and when code is ported to Linux that reuses a struct timeval for multiple select()s in a loop without reinitializing + it. Consider timeout to be undefined after select() returns. + +RETURN VALUE + On success, select() and pselect() return the number of file descriptors contained in the three returned descriptor sets (that + is, the total number of bits that are set in readfds, writefds, exceptfds). The return value may be zero if the timeout ex‐ + pired before any file descriptors became ready. + + On error, -1 is returned, and errno is set to indicate the error; the file descriptor sets are unmodified, and timeout becomes + undefined. + +ERRORS + EBADF An invalid file descriptor was given in one of the sets. (Perhaps a file descriptor that was already closed, or one on + which an error has occurred.) However, see BUGS. + + EINTR A signal was caught; see signal(7). + + EINVAL nfds is negative or exceeds the RLIMIT_NOFILE resource limit (see getrlimit(2)). + + EINVAL The value contained within timeout is invalid. + + ENOMEM Unable to allocate memory for internal tables. + +VERSIONS + pselect() was added to Linux in kernel 2.6.16. Prior to this, pselect() was emulated in glibc (but see BUGS). + +CONFORMING TO + select() conforms to POSIX.1-2001, POSIX.1-2008, and 4.4BSD (select() 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 returning, but the BSD variant does not. + + pselect() is defined in POSIX.1g, and in POSIX.1-2001 and POSIX.1-2008. + +NOTES + An fd_set is a fixed size buffer. Executing FD_CLR() or FD_SET() with a value of fd that is negative or is equal to or larger + than FD_SETSIZE will result in undefined behavior. Moreover, POSIX requires fd to be a valid file descriptor. + + The operation of select() and pselect() is not affected by the O_NONBLOCK flag. + + On some other UNIX systems, select() can fail with the error EAGAIN if the system fails to allocate kernel-internal resources, + rather than ENOMEM as Linux does. POSIX specifies this error for poll(2), but not for select(). Portable programs may wish + to check for EAGAIN and loop, just as with EINTR. + + The self-pipe trick + On systems that lack pselect(), reliable (and more portable) signal trapping can be achieved using the self-pipe trick. In + this technique, a signal handler writes a byte to a pipe whose other end is monitored by select() in the main program. (To + avoid possibly blocking when writing to a pipe that may be full or reading from a pipe that may be empty, nonblocking I/O is + used when reading from and writing to the pipe.) + + Emulating usleep(3) + Before the advent of usleep(3), some code employed a call to select() with all three sets empty, nfds zero, and a non-NULL + timeout as a fairly portable way to sleep with subsecond precision. + + Correspondence between select() and poll() notifications + Within the Linux kernel source, we find the following definitions which show the correspondence between the readable, + writable, and exceptional condition notifications of select() and the event notifications provided by poll(2) and epoll(7): + + #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | + EPOLLHUP | EPOLLERR) + /* Ready for reading */ + #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT | + EPOLLERR) + /* Ready for writing */ + #define POLLEX_SET (EPOLLPRI) + /* Exceptional condition */ + + Multithreaded applications + If a file descriptor being monitored by select() is closed in another thread, the result is unspecified. On some UNIX sys‐ + tems, select() unblocks and returns, with an indication that the file descriptor is ready (a subsequent I/O operation will + likely fail with an error, unless another process reopens file descriptor between the time select() returned and the I/O oper‐ + ation is performed). On Linux (and some other systems), closing the file descriptor in another thread has no effect on se‐ + lect(). In summary, any application that relies on a particular behavior in this scenario must be considered buggy. + + C library/kernel differences + The Linux kernel allows file descriptor sets of arbitrary size, determining the length of the sets to be checked from the + value of nfds. However, in the glibc implementation, the fd_set type is fixed in size. See also BUGS. + + The pselect() interface described in this page is implemented by glibc. The underlying Linux system call is named pselect6(). + This system call has somewhat different behavior from the glibc wrapper function. + + The Linux pselect6() system call modifies its timeout argument. However, the glibc wrapper function hides this behavior by + using a local variable for the timeout argument that is passed to the system call. Thus, the glibc pselect() function does + not modify its timeout argument; this is the behavior required by POSIX.1-2001. + + The final argument of the pselect6() system call is not a sigset_t * pointer, but is instead a structure of the form: + + struct { + const kernel_sigset_t *ss; /* Pointer to signal set */ + size_t ss_len; /* Size (in bytes) of object + pointed to by 'ss' */ + }; + + This allows the system call to obtain both a pointer to the signal set and its size, while allowing for the fact that most ar‐ + chitectures support a maximum of 6 arguments to a system call. See sigprocmask(2) for a discussion of the difference between + the kernel and libc notion of the signal set. + + Historical glibc details + Glibc 2.0 provided an incorrect version of pselect() that did not take a sigmask argument. + + In glibc versions 2.1 to 2.2.1, one must define _GNU_SOURCE in order to obtain the declaration of pselect() from . + +BUGS + POSIX allows an implementation to define an upper limit, advertised via the constant FD_SETSIZE, on the range of file descrip‐ + tors that can be specified in a file descriptor set. The Linux kernel imposes no fixed limit, but the glibc implementation + makes fd_set a fixed-size type, with FD_SETSIZE defined as 1024, and the FD_*() macros operating according to that limit. To + monitor file descriptors greater than 1023, use poll(2) or epoll(7) instead. + + According to POSIX, select() should check all specified file descriptors in the three file descriptor sets, up to the limit + nfds-1. However, the current implementation ignores any file descriptor in these sets that is greater than the maximum file + descriptor number that the process currently has open. According to POSIX, any such file descriptor that is specified in one + of the sets should result in the error EBADF. + + Starting with version 2.1, glibc provided an emulation of pselect() that was implemented using sigprocmask(2) and select(). + This implementation remained vulnerable to the very race condition that pselect() was designed to prevent. Modern versions of + glibc use the (race-free) pselect() system call on kernels where it is provided. + + On Linux, 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 the wrong checksum and is discarded. There may + be other circumstances in which a file descriptor is spuriously reported as ready. Thus it may be safer to use O_NONBLOCK on + sockets that should not block. + + On Linux, select() also modifies timeout if the call is interrupted by a signal handler (i.e., the EINTR error return). This + is not permitted by POSIX.1. The Linux pselect() system call has the same behavior, but the glibc wrapper hides this behavior + by internally copying the timeout to a local variable and passing that variable to the system call. + +EXAMPLES + #include  + #include  + #include  + + int + main(void) + { + fd_set rfds; + struct timeval tv; + int retval; + + /* Watch stdin (fd 0) to see when it has input. */ + + FD_ZERO(&rfds); + FD_SET(0, &rfds); + + /* Wait up to five seconds. */ + + tv.tv_sec = 5; + tv.tv_usec = 0; + + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don't rely on the value of tv now! */ + + if (retval == -1) + perror("select()"); + else if (retval) + printf("Data is available now.\n"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\n"); + + exit(EXIT_SUCCESS); + } + +SEE ALSO + accept(2), connect(2), poll(2), read(2), recv(2), restart_syscall(2), send(2), sigprocmask(2), write(2), epoll(7), time(7) + + For a tutorial with discussion and examples, see select_tut(2). + +COLOPHON + This page is part of release 5.08 of the Linux man-pages project. A description of the project, information about reporting + bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/. + +Linux 2020-04-11 SELECT(2) diff --git a/tests/syntax-tests/source/Manpage/select-2.man b/tests/syntax-tests/source/Manpage/select-2.man new file mode 100644 index 00000000..c11e411b --- /dev/null +++ b/tests/syntax-tests/source/Manpage/select-2.man @@ -0,0 +1,330 @@ +SELECT(2) Linux Programmer's Manual SELECT(2) + +NAME + select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O multiplexing + +SYNOPSIS + #include + + int select(int nfds, fd_set *readfds, fd_set *writefds, + fd_set *exceptfds, struct timeval *timeout); + + void FD_CLR(int fd, fd_set *set); + int FD_ISSET(int fd, fd_set *set); + void FD_SET(int fd, fd_set *set); + void FD_ZERO(fd_set *set); + + int pselect(int nfds, fd_set *readfds, fd_set *writefds, + fd_set *exceptfds, const struct timespec *timeout, + const sigset_t *sigmask); + + Feature Test Macro Requirements for glibc (see feature_test_macros(7)): + + pselect(): _POSIX_C_SOURCE >= 200112L + +DESCRIPTION + select() allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become + "ready" for some class of I/O operation (e.g., input possible). A file descriptor is considered ready if it is possible to + perform a corresponding I/O operation (e.g., read(2), or a sufficiently small write(2)) without blocking. + + select() can monitor only file descriptors numbers that are less than FD_SETSIZE; poll(2) and epoll(7) do not have this limi‐ + tation. See BUGS. + + File descriptor sets + The principal arguments of select() are three "sets" of file descriptors (declared with the type fd_set), which allow the + caller to wait for three classes of events on the specified set of file descriptors. Each of the fd_set arguments may be + specified as NULL if no file descriptors are to be watched for the corresponding class of events. + + Note well: Upon return, each of the file descriptor sets is modified in place to indicate which file descriptors are currently + "ready". Thus, if using select() within a loop, the sets must be reinitialized before each call. The implementation of the + fd_set arguments as value-result arguments is a design error that is avoided in poll(2) and epoll(7). + + The contents of a file descriptor set can be manipulated using the following macros: + + FD_ZERO() + This macro clears (removes all file descriptors from) set. It should be employed as the first step in initializing a + file descriptor set. + + FD_SET() + This macro adds the file descriptor fd to set. Adding a file descriptor that is already present in the set is a no-op, + and does not produce an error. + + FD_CLR() + This macro removes the file descriptor fd from set. Removing a file descriptor that is not present in the set is a no- + op, and does not produce an error. + + FD_ISSET() + select() modifies the contents of the sets according to the rules described below. After calling select(), the FD_IS‐ + SET() macro can be used to test if a file descriptor is still present in a set. FD_ISSET() returns nonzero if the file + descriptor fd is present in set, and zero if it is not. + + Arguments + The arguments of select() are as follows: + + readfds + The file descriptors in this set are watched to see if they are ready for reading. A file descriptor is ready for + reading if a read operation will not block; in particular, a file descriptor is also ready on end-of-file. + + After select() has returned, readfds will be cleared of all file descriptors except for those that are ready for read‐ + ing. + + writefds + The file descriptors in this set are watched to see if they are ready for writing. 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. + + After select() has returned, writefds will be cleared of all file descriptors except for those that are ready for writ‐ + ing. + + exceptfds + The file descriptors in this set are watched for "exceptional conditions". For examples of some exceptional condi‐ + tions, see the discussion of POLLPRI in poll(2). + + After select() has returned, exceptfds will be cleared of all file descriptors except for those for which an excep‐ + tional condition has occurred. + + nfds This argument should be set to the highest-numbered file descriptor in any of the three sets, plus 1. The indicated + file descriptors in each set are checked, up to this limit (but see BUGS). + + timeout + The timeout argument is a timeval structure (shown below) that specifies the interval that select() should block wait‐ + ing for a file descriptor to become ready. The call will block until either: + + • a file descriptor becomes ready; + + • the call is interrupted by a signal handler; or + + • the timeout expires. + + Note that the timeout interval will be rounded up to the system clock granularity, and kernel scheduling delays mean + that the blocking interval may overrun by a small amount. + + If both fields of the timeval structure are zero, then select() returns immediately. (This is useful for polling.) + + If timeout is specified as NULL, select() blocks indefinitely waiting for a file descriptor to become ready. + + pselect() + The pselect() system call allows an application to safely wait until either a file descriptor becomes ready or until a signal + is caught. + + The operation of select() and pselect() is identical, other than these three differences: + + • select() uses a timeout that is a struct timeval (with seconds and microseconds), while pselect() uses a struct timespec + (with seconds and nanoseconds). + + • select() may update the timeout argument to indicate how much time was left. pselect() does not change this argument. + + • select() has no sigmask argument, and behaves as pselect() called with NULL sigmask. + + sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is not NULL, then pselect() first replaces the current sig‐ + nal mask by the one pointed to by sigmask, then does the "select" function, and then restores the original signal mask. (If + sigmask is NULL, the signal mask is not modified during the pselect() call.) + + Other than the difference in the precision of the timeout argument, the following pselect() call: + + ready = pselect(nfds, &readfds, &writefds, &exceptfds, + timeout, &sigmask); + + is equivalent to atomically executing the following calls: + + sigset_t origmask; + + pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); + ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); + pthread_sigmask(SIG_SETMASK, &origmask, NULL); + + The reason that pselect() is needed is that if one wants to wait for either a signal or for a file descriptor to become ready, + then an atomic test is needed to prevent race conditions. (Suppose the signal handler sets a global flag and returns. Then a + test of this global flag followed by a call of select() could hang indefinitely if the signal arrived just after the test but + just before the call. By contrast, pselect() allows one to first block signals, handle the signals that have come in, then + call pselect() with the desired sigmask, avoiding the race.) + + The timeout + The timeout argument for select() is a structure of the following type: + + struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ + }; + + The corresponding argument for pselect() has the following type: + + struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* nanoseconds */ + }; + + On Linux, select() modifies timeout to reflect the amount of time not slept; most other implementations do not do this. + (POSIX.1 permits either behavior.) This causes problems both when Linux code which reads timeout is ported to other operating + systems, and when code is ported to Linux that reuses a struct timeval for multiple select()s in a loop without reinitializing + it. Consider timeout to be undefined after select() returns. + +RETURN VALUE + On success, select() and pselect() return the number of file descriptors contained in the three returned descriptor sets (that + is, the total number of bits that are set in readfds, writefds, exceptfds). The return value may be zero if the timeout ex‐ + pired before any file descriptors became ready. + + On error, -1 is returned, and errno is set to indicate the error; the file descriptor sets are unmodified, and timeout becomes + undefined. + +ERRORS + EBADF An invalid file descriptor was given in one of the sets. (Perhaps a file descriptor that was already closed, or one on + which an error has occurred.) However, see BUGS. + + EINTR A signal was caught; see signal(7). + + EINVAL nfds is negative or exceeds the RLIMIT_NOFILE resource limit (see getrlimit(2)). + + EINVAL The value contained within timeout is invalid. + + ENOMEM Unable to allocate memory for internal tables. + +VERSIONS + pselect() was added to Linux in kernel 2.6.16. Prior to this, pselect() was emulated in glibc (but see BUGS). + +CONFORMING TO + select() conforms to POSIX.1-2001, POSIX.1-2008, and 4.4BSD (select() 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 returning, but the BSD variant does not. + + pselect() is defined in POSIX.1g, and in POSIX.1-2001 and POSIX.1-2008. + +NOTES + An fd_set is a fixed size buffer. Executing FD_CLR() or FD_SET() with a value of fd that is negative or is equal to or larger + than FD_SETSIZE will result in undefined behavior. Moreover, POSIX requires fd to be a valid file descriptor. + + The operation of select() and pselect() is not affected by the O_NONBLOCK flag. + + On some other UNIX systems, select() can fail with the error EAGAIN if the system fails to allocate kernel-internal resources, + rather than ENOMEM as Linux does. POSIX specifies this error for poll(2), but not for select(). Portable programs may wish + to check for EAGAIN and loop, just as with EINTR. + + The self-pipe trick + On systems that lack pselect(), reliable (and more portable) signal trapping can be achieved using the self-pipe trick. In + this technique, a signal handler writes a byte to a pipe whose other end is monitored by select() in the main program. (To + avoid possibly blocking when writing to a pipe that may be full or reading from a pipe that may be empty, nonblocking I/O is + used when reading from and writing to the pipe.) + + Emulating usleep(3) + Before the advent of usleep(3), some code employed a call to select() with all three sets empty, nfds zero, and a non-NULL + timeout as a fairly portable way to sleep with subsecond precision. + + Correspondence between select() and poll() notifications + Within the Linux kernel source, we find the following definitions which show the correspondence between the readable, + writable, and exceptional condition notifications of select() and the event notifications provided by poll(2) and epoll(7): + + #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | + EPOLLHUP | EPOLLERR) + /* Ready for reading */ + #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT | + EPOLLERR) + /* Ready for writing */ + #define POLLEX_SET (EPOLLPRI) + /* Exceptional condition */ + + Multithreaded applications + If a file descriptor being monitored by select() is closed in another thread, the result is unspecified. On some UNIX sys‐ + tems, select() unblocks and returns, with an indication that the file descriptor is ready (a subsequent I/O operation will + likely fail with an error, unless another process reopens file descriptor between the time select() returned and the I/O oper‐ + ation is performed). On Linux (and some other systems), closing the file descriptor in another thread has no effect on se‐ + lect(). In summary, any application that relies on a particular behavior in this scenario must be considered buggy. + + C library/kernel differences + The Linux kernel allows file descriptor sets of arbitrary size, determining the length of the sets to be checked from the + value of nfds. However, in the glibc implementation, the fd_set type is fixed in size. See also BUGS. + + The pselect() interface described in this page is implemented by glibc. The underlying Linux system call is named pselect6(). + This system call has somewhat different behavior from the glibc wrapper function. + + The Linux pselect6() system call modifies its timeout argument. However, the glibc wrapper function hides this behavior by + using a local variable for the timeout argument that is passed to the system call. Thus, the glibc pselect() function does + not modify its timeout argument; this is the behavior required by POSIX.1-2001. + + The final argument of the pselect6() system call is not a sigset_t * pointer, but is instead a structure of the form: + + struct { + const kernel_sigset_t *ss; /* Pointer to signal set */ + size_t ss_len; /* Size (in bytes) of object + pointed to by 'ss' */ + }; + + This allows the system call to obtain both a pointer to the signal set and its size, while allowing for the fact that most ar‐ + chitectures support a maximum of 6 arguments to a system call. See sigprocmask(2) for a discussion of the difference between + the kernel and libc notion of the signal set. + + Historical glibc details + Glibc 2.0 provided an incorrect version of pselect() that did not take a sigmask argument. + + In glibc versions 2.1 to 2.2.1, one must define _GNU_SOURCE in order to obtain the declaration of pselect() from . + +BUGS + POSIX allows an implementation to define an upper limit, advertised via the constant FD_SETSIZE, on the range of file descrip‐ + tors that can be specified in a file descriptor set. The Linux kernel imposes no fixed limit, but the glibc implementation + makes fd_set a fixed-size type, with FD_SETSIZE defined as 1024, and the FD_*() macros operating according to that limit. To + monitor file descriptors greater than 1023, use poll(2) or epoll(7) instead. + + According to POSIX, select() should check all specified file descriptors in the three file descriptor sets, up to the limit + nfds-1. However, the current implementation ignores any file descriptor in these sets that is greater than the maximum file + descriptor number that the process currently has open. According to POSIX, any such file descriptor that is specified in one + of the sets should result in the error EBADF. + + Starting with version 2.1, glibc provided an emulation of pselect() that was implemented using sigprocmask(2) and select(). + This implementation remained vulnerable to the very race condition that pselect() was designed to prevent. Modern versions of + glibc use the (race-free) pselect() system call on kernels where it is provided. + + On Linux, 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 the wrong checksum and is discarded. There may + be other circumstances in which a file descriptor is spuriously reported as ready. Thus it may be safer to use O_NONBLOCK on + sockets that should not block. + + On Linux, select() also modifies timeout if the call is interrupted by a signal handler (i.e., the EINTR error return). This + is not permitted by POSIX.1. The Linux pselect() system call has the same behavior, but the glibc wrapper hides this behavior + by internally copying the timeout to a local variable and passing that variable to the system call. + +EXAMPLES + #include + #include + #include + + int + main(void) + { + fd_set rfds; + struct timeval tv; + int retval; + + /* Watch stdin (fd 0) to see when it has input. */ + + FD_ZERO(&rfds); + FD_SET(0, &rfds); + + /* Wait up to five seconds. */ + + tv.tv_sec = 5; + tv.tv_usec = 0; + + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don't rely on the value of tv now! */ + + if (retval == -1) + perror("select()"); + else if (retval) + printf("Data is available now.\n"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\n"); + + exit(EXIT_SUCCESS); + } + +SEE ALSO + accept(2), connect(2), poll(2), read(2), recv(2), restart_syscall(2), send(2), sigprocmask(2), write(2), epoll(7), time(7) + + For a tutorial with discussion and examples, see select_tut(2). + +COLOPHON + This page is part of release 5.08 of the Linux man-pages project. A description of the project, information about reporting + bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/. + +Linux 2020-04-11 SELECT(2)