git.iko.soy/bat
on master help sign in
Add Manpage syntax regression test for select(2)
commit3539d3e72da3fb0042e8c05a196d1f50a408c3cd authorsharkdp <davidpeter@web.de> dateWed 14 Oct 2020, 22:49 (6 years ago) parentbb25111
2 files changed+660
compare with master
unifiedsplit
tests/syntax-tests/highlighted/Manpage/select-2.man+330 tests/syntax-tests/source/Manpage/select-2.man+330
tests/syntax-tests/highlighted/Manpage/select-2.mannew file+330
@@ -0,0 +1,330 @@
1+SELECT(2) Linux Programmer's Manual SELECT(2)
2+
3+NAME
4+ select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O multiplexing
5+
6+SYNOPSIS
7+ #include <sys/select.h>
8+
9+ int select(int nfds, fd_set *readfds, fd_set *writefds,
10+ fd_set *exceptfds, struct timeval *timeout);
11+
12+ void FD_CLR(int fd, fd_set *set);
13+ int FD_ISSET(int fd, fd_set *set);
14+ void FD_SET(int fd, fd_set *set);
15+ void FD_ZERO(fd_set *set);
16+
17+ int pselect(int nfds, fd_set *readfds, fd_set *writefds,
18+ fd_set *exceptfds, const struct timespec *timeout,
19+ const sigset_t *sigmask);
20+
21+ Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22+
23+ pselect(): _POSIX_C_SOURCE >= 200112L
24+
25+DESCRIPTION
26+ select() allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become
27+ "ready" for some class of I/O operation (e.g., input possible). A file descriptor is considered ready if it is possible to
28+ perform a corresponding I/O operation (e.g., read(2), or a sufficiently small write(2)) without blocking.
29+
30+ select() can monitor only file descriptors numbers that are less than FD_SETSIZE; poll(2) and epoll(7) do not have this limi‐
31+ tation. See BUGS.
32+
33+ File descriptor sets
34+ The principal arguments of select() are three "sets" of file descriptors (declared with the type fd_set), which allow the
35+ caller to wait for three classes of events on the specified set of file descriptors. Each of the fd_set arguments may be
36+ specified as NULL if no file descriptors are to be watched for the corresponding class of events.
37+
38+ Note well: Upon return, each of the file descriptor sets is modified in place to indicate which file descriptors are currently
39+ "ready". Thus, if using select() within a loop, the sets must be reinitialized before each call. The implementation of the
40+ fd_set arguments as value-result arguments is a design error that is avoided in poll(2) and epoll(7).
41+
42+ The contents of a file descriptor set can be manipulated using the following macros:
43+
44+ FD_ZERO()
45+ This macro clears (removes all file descriptors from) set. It should be employed as the first step in initializing a
46+ file descriptor set.
47+
48+ FD_SET()
49+ This macro adds the file descriptor fd to set. Adding a file descriptor that is already present in the set is a no-op,
50+ and does not produce an error.
51+
52+ FD_CLR()
53+ This macro removes the file descriptor fd from set. Removing a file descriptor that is not present in the set is a no-
54+ op, and does not produce an error.
55+
56+ FD_ISSET()
57+ select() modifies the contents of the sets according to the rules described below. After calling select(), the FD_IS‐
58+ SET() macro can be used to test if a file descriptor is still present in a set. FD_ISSET() returns nonzero if the file
59+ descriptor fd is present in set, and zero if it is not.
60+
61+ Arguments
62+ The arguments of select() are as follows:
63+
64+ readfds
65+ The file descriptors in this set are watched to see if they are ready for reading. A file descriptor is ready for
66+ reading if a read operation will not block; in particular, a file descriptor is also ready on end-of-file.
67+
68+ After select() has returned, readfds will be cleared of all file descriptors except for those that are ready for read‐
69+ ing.
70+
71+ writefds
72+ The file descriptors in this set are watched to see if they are ready for writing. A file descriptor is ready for
73+ writing if a write operation will not block. However, even if a file descriptor indicates as writable, a large write
74+ may still block.
75+
76+ After select() has returned, writefds will be cleared of all file descriptors except for those that are ready for writ‐
77+ ing.
78+
79+ exceptfds
80+ The file descriptors in this set are watched for "exceptional conditions". For examples of some exceptional condi‐
81+ tions, see the discussion of POLLPRI in poll(2).
82+
83+ After select() has returned, exceptfds will be cleared of all file descriptors except for those for which an excep‐
84+ tional condition has occurred.
85+
86+ nfds This argument should be set to the highest-numbered file descriptor in any of the three sets, plus 1. The indicated
87+ file descriptors in each set are checked, up to this limit (but see BUGS).
88+
89+ timeout
90+ The timeout argument is a timeval structure (shown below) that specifies the interval that select() should block wait‐
91+ ing for a file descriptor to become ready. The call will block until either:
92+
93+ • a file descriptor becomes ready;
94+
95+ • the call is interrupted by a signal handler; or
96+
97+ • the timeout expires.
98+
99+ Note that the timeout interval will be rounded up to the system clock granularity, and kernel scheduling delays mean
100+ that the blocking interval may overrun by a small amount.
101+
102+ If both fields of the timeval structure are zero, then select() returns immediately. (This is useful for polling.)
103+
104+ If timeout is specified as NULL, select() blocks indefinitely waiting for a file descriptor to become ready.
105+
106+ pselect()
107+ The pselect() system call allows an application to safely wait until either a file descriptor becomes ready or until a signal
108+ is caught.
109+
110+ The operation of select() and pselect() is identical, other than these three differences:
111+
112+ • select() uses a timeout that is a struct timeval (with seconds and microseconds), while pselect() uses a struct timespec
113+ (with seconds and nanoseconds).
114+
115+ • select() may update the timeout argument to indicate how much time was left. pselect() does not change this argument.
116+
117+ • select() has no sigmask argument, and behaves as pselect() called with NULL sigmask.
118+
119+ sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is not NULL, then pselect() first replaces the current sig‐
120+ nal mask by the one pointed to by sigmask, then does the "select" function, and then restores the original signal mask. (If
121+ sigmask is NULL, the signal mask is not modified during the pselect() call.)
122+
123+ Other than the difference in the precision of the timeout argument, the following pselect() call:
124+
125+ ready = pselect(nfds, &readfds, &writefds, &exceptfds,
126+ timeout, &sigmask);
127+
128+ is equivalent to atomically executing the following calls:
129+
130+ sigset_t origmask;
131+
132+ pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
133+ ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
134+ pthread_sigmask(SIG_SETMASK, &origmask, NULL);
135+
136+ 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,
137+ then an atomic test is needed to prevent race conditions. (Suppose the signal handler sets a global flag and returns. Then a
138+ test of this global flag followed by a call of select() could hang indefinitely if the signal arrived just after the test but
139+ just before the call. By contrast, pselect() allows one to first block signals, handle the signals that have come in, then
140+ call pselect() with the desired sigmask, avoiding the race.)
141+
142+ The timeout
143+ The timeout argument for select() is a structure of the following type:
144+
145+ struct timeval {
146+ time_t tv_sec; /* seconds */
147+ suseconds_t tv_usec; /* microseconds */
148+ };
149+
150+ The corresponding argument for pselect() has the following type:
151+
152+ struct timespec {
153+ time_t tv_sec; /* seconds */
154+ long tv_nsec; /* nanoseconds */
155+ };
156+
157+ On Linux, select() modifies timeout to reflect the amount of time not slept; most other implementations do not do this.
158+ (POSIX.1 permits either behavior.) This causes problems both when Linux code which reads timeout is ported to other operating
159+ systems, and when code is ported to Linux that reuses a struct timeval for multiple select()s in a loop without reinitializing
160+ it. Consider timeout to be undefined after select() returns.
161+
162+RETURN VALUE
163+ On success, select() and pselect() return the number of file descriptors contained in the three returned descriptor sets (that
164+ is, the total number of bits that are set in readfds, writefds, exceptfds). The return value may be zero if the timeout ex‐
165+ pired before any file descriptors became ready.
166+
167+ On error, -1 is returned, and errno is set to indicate the error; the file descriptor sets are unmodified, and timeout becomes
168+ undefined.
169+
170+ERRORS
171+ EBADF An invalid file descriptor was given in one of the sets. (Perhaps a file descriptor that was already closed, or one on
172+ which an error has occurred.) However, see BUGS.
173+
174+ EINTR A signal was caught; see signal(7).
175+
176+ EINVAL nfds is negative or exceeds the RLIMIT_NOFILE resource limit (see getrlimit(2)).
177+
178+ EINVAL The value contained within timeout is invalid.
179+
180+ ENOMEM Unable to allocate memory for internal tables.
181+
182+VERSIONS
183+ pselect() was added to Linux in kernel 2.6.16. Prior to this, pselect() was emulated in glibc (but see BUGS).
184+
185+CONFORMING TO
186+ select() conforms to POSIX.1-2001, POSIX.1-2008, and 4.4BSD (select() first appeared in 4.2BSD). Generally portable to/from
187+ non-BSD systems supporting clones of the BSD socket layer (including System V variants). However, note that the System V
188+ variant typically sets the timeout variable before returning, but the BSD variant does not.
189+
190+ pselect() is defined in POSIX.1g, and in POSIX.1-2001 and POSIX.1-2008.
191+
192+NOTES
193+ 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
194+ than FD_SETSIZE will result in undefined behavior. Moreover, POSIX requires fd to be a valid file descriptor.
195+
196+ The operation of select() and pselect() is not affected by the O_NONBLOCK flag.
197+
198+ On some other UNIX systems, select() can fail with the error EAGAIN if the system fails to allocate kernel-internal resources,
199+ rather than ENOMEM as Linux does. POSIX specifies this error for poll(2), but not for select(). Portable programs may wish
200+ to check for EAGAIN and loop, just as with EINTR.
201+
202+ The self-pipe trick
203+ On systems that lack pselect(), reliable (and more portable) signal trapping can be achieved using the self-pipe trick. In
204+ this technique, a signal handler writes a byte to a pipe whose other end is monitored by select() in the main program. (To
205+ 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
206+ used when reading from and writing to the pipe.)
207+
208+ Emulating usleep(3)
209+ Before the advent of usleep(3), some code employed a call to select() with all three sets empty, nfds zero, and a non-NULL
210+ timeout as a fairly portable way to sleep with subsecond precision.
211+
212+ Correspondence between select() and poll() notifications
213+ Within the Linux kernel source, we find the following definitions which show the correspondence between the readable,
214+ writable, and exceptional condition notifications of select() and the event notifications provided by poll(2) and epoll(7):
215+
216+ #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
217+ EPOLLHUP | EPOLLERR)
218+ /* Ready for reading */
219+ #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT |
220+ EPOLLERR)
221+ /* Ready for writing */
222+ #define POLLEX_SET (EPOLLPRI)
223+ /* Exceptional condition */
224+
225+ Multithreaded applications
226+ If a file descriptor being monitored by select() is closed in another thread, the result is unspecified. On some UNIX sys‐
227+ tems, select() unblocks and returns, with an indication that the file descriptor is ready (a subsequent I/O operation will
228+ likely fail with an error, unless another process reopens file descriptor between the time select() returned and the I/O oper‐
229+ ation is performed). On Linux (and some other systems), closing the file descriptor in another thread has no effect on se‐
230+ lect(). In summary, any application that relies on a particular behavior in this scenario must be considered buggy.
231+
232+ C library/kernel differences
233+ The Linux kernel allows file descriptor sets of arbitrary size, determining the length of the sets to be checked from the
234+ value of nfds. However, in the glibc implementation, the fd_set type is fixed in size. See also BUGS.
235+
236+ The pselect() interface described in this page is implemented by glibc. The underlying Linux system call is named pselect6().
237+ This system call has somewhat different behavior from the glibc wrapper function.
238+
239+ The Linux pselect6() system call modifies its timeout argument. However, the glibc wrapper function hides this behavior by
240+ using a local variable for the timeout argument that is passed to the system call. Thus, the glibc pselect() function does
241+ not modify its timeout argument; this is the behavior required by POSIX.1-2001.
242+
243+ The final argument of the pselect6() system call is not a sigset_t * pointer, but is instead a structure of the form:
244+
245+ struct {
246+ const kernel_sigset_t *ss; /* Pointer to signal set */
247+ size_t ss_len; /* Size (in bytes) of object
248+ pointed to by 'ss' */
249+ };
250+
251+ 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‐
252+ chitectures support a maximum of 6 arguments to a system call. See sigprocmask(2) for a discussion of the difference between
253+ the kernel and libc notion of the signal set.
254+
255+ Historical glibc details
256+ Glibc 2.0 provided an incorrect version of pselect() that did not take a sigmask argument.
257+
258+ In glibc versions 2.1 to 2.2.1, one must define _GNU_SOURCE in order to obtain the declaration of pselect() from <sys/se‐
259+ lect.h>.
260+
261+BUGS
262+ POSIX allows an implementation to define an upper limit, advertised via the constant FD_SETSIZE, on the range of file descrip‐
263+ tors that can be specified in a file descriptor set. The Linux kernel imposes no fixed limit, but the glibc implementation
264+ makes fd_set a fixed-size type, with FD_SETSIZE defined as 1024, and the FD_*() macros operating according to that limit. To
265+ monitor file descriptors greater than 1023, use poll(2) or epoll(7) instead.
266+
267+ According to POSIX, select() should check all specified file descriptors in the three file descriptor sets, up to the limit
268+ nfds-1. However, the current implementation ignores any file descriptor in these sets that is greater than the maximum file
269+ descriptor number that the process currently has open. According to POSIX, any such file descriptor that is specified in one
270+ of the sets should result in the error EBADF.
271+
272+ Starting with version 2.1, glibc provided an emulation of pselect() that was implemented using sigprocmask(2) and select().
273+ This implementation remained vulnerable to the very race condition that pselect() was designed to prevent. Modern versions of
274+ glibc use the (race-free) pselect() system call on kernels where it is provided.
275+
276+ On Linux, select() may report a socket file descriptor as "ready for reading", while nevertheless a subsequent read blocks.
277+ This could for example happen when data has arrived but upon examination has the wrong checksum and is discarded. There may
278+ be other circumstances in which a file descriptor is spuriously reported as ready. Thus it may be safer to use O_NONBLOCK on
279+ sockets that should not block.
280+
281+ On Linux, select() also modifies timeout if the call is interrupted by a signal handler (i.e., the EINTR error return). This
282+ is not permitted by POSIX.1. The Linux pselect() system call has the same behavior, but the glibc wrapper hides this behavior
283+ by internally copying the timeout to a local variable and passing that variable to the system call.
284+
285+EXAMPLES
286+ #include <stdio.h>
287+ #include <stdlib.h>
288+ #include <sys/select.h>
289+
290+ int
291+ main(void)
292+ {
293+ fd_set rfds;
294+ struct timeval tv;
295+ int retval;
296+
297+ /* Watch stdin (fd 0) to see when it has input. */
298+
299+ FD_ZERO(&rfds);
300+ FD_SET(0, &rfds);
301+
302+ /* Wait up to five seconds. */
303+
304+ tv.tv_sec = 5;
305+ tv.tv_usec = 0;
306+
307+ retval = select(1, &rfds, NULL, NULL, &tv);
308+ /* Don't rely on the value of tv now! */
309+
310+ if (retval == -1)
311+ perror("select()");
312+ else if (retval)
313+ printf("Data is available now.\n");
314+ /* FD_ISSET(0, &rfds) will be true. */
315+ else
316+ printf("No data within five seconds.\n");
317+
318+ exit(EXIT_SUCCESS);
319+ }
320+
321+SEE ALSO
322+ accept(2), connect(2), poll(2), read(2), recv(2), restart_syscall(2), send(2), sigprocmask(2), write(2), epoll(7), time(7)
323+
324+ For a tutorial with discussion and examples, see select_tut(2).
325+
326+COLOPHON
327+ This page is part of release 5.08 of the Linux man-pages project. A description of the project, information about reporting
328+ bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.
329+
330+Linux 2020-04-11 SELECT(2)
tests/syntax-tests/source/Manpage/select-2.mannew file+330
@@ -0,0 +1,330 @@
1+SELECT(2) Linux Programmer's Manual SELECT(2)
2+
3+NAME
4+ select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O multiplexing
5+
6+SYNOPSIS
7+ #include <sys/select.h>
8+
9+ int select(int nfds, fd_set *readfds, fd_set *writefds,
10+ fd_set *exceptfds, struct timeval *timeout);
11+
12+ void FD_CLR(int fd, fd_set *set);
13+ int FD_ISSET(int fd, fd_set *set);
14+ void FD_SET(int fd, fd_set *set);
15+ void FD_ZERO(fd_set *set);
16+
17+ int pselect(int nfds, fd_set *readfds, fd_set *writefds,
18+ fd_set *exceptfds, const struct timespec *timeout,
19+ const sigset_t *sigmask);
20+
21+ Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22+
23+ pselect(): _POSIX_C_SOURCE >= 200112L
24+
25+DESCRIPTION
26+ select() allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become
27+ "ready" for some class of I/O operation (e.g., input possible). A file descriptor is considered ready if it is possible to
28+ perform a corresponding I/O operation (e.g., read(2), or a sufficiently small write(2)) without blocking.
29+
30+ select() can monitor only file descriptors numbers that are less than FD_SETSIZE; poll(2) and epoll(7) do not have this limi‐
31+ tation. See BUGS.
32+
33+ File descriptor sets
34+ The principal arguments of select() are three "sets" of file descriptors (declared with the type fd_set), which allow the
35+ caller to wait for three classes of events on the specified set of file descriptors. Each of the fd_set arguments may be
36+ specified as NULL if no file descriptors are to be watched for the corresponding class of events.
37+
38+ Note well: Upon return, each of the file descriptor sets is modified in place to indicate which file descriptors are currently
39+ "ready". Thus, if using select() within a loop, the sets must be reinitialized before each call. The implementation of the
40+ fd_set arguments as value-result arguments is a design error that is avoided in poll(2) and epoll(7).
41+
42+ The contents of a file descriptor set can be manipulated using the following macros:
43+
44+ FD_ZERO()
45+ This macro clears (removes all file descriptors from) set. It should be employed as the first step in initializing a
46+ file descriptor set.
47+
48+ FD_SET()
49+ This macro adds the file descriptor fd to set. Adding a file descriptor that is already present in the set is a no-op,
50+ and does not produce an error.
51+
52+ FD_CLR()
53+ This macro removes the file descriptor fd from set. Removing a file descriptor that is not present in the set is a no-
54+ op, and does not produce an error.
55+
56+ FD_ISSET()
57+ select() modifies the contents of the sets according to the rules described below. After calling select(), the FD_IS‐
58+ SET() macro can be used to test if a file descriptor is still present in a set. FD_ISSET() returns nonzero if the file
59+ descriptor fd is present in set, and zero if it is not.
60+
61+ Arguments
62+ The arguments of select() are as follows:
63+
64+ readfds
65+ The file descriptors in this set are watched to see if they are ready for reading. A file descriptor is ready for
66+ reading if a read operation will not block; in particular, a file descriptor is also ready on end-of-file.
67+
68+ After select() has returned, readfds will be cleared of all file descriptors except for those that are ready for read‐
69+ ing.
70+
71+ writefds
72+ The file descriptors in this set are watched to see if they are ready for writing. A file descriptor is ready for
73+ writing if a write operation will not block. However, even if a file descriptor indicates as writable, a large write
74+ may still block.
75+
76+ After select() has returned, writefds will be cleared of all file descriptors except for those that are ready for writ‐
77+ ing.
78+
79+ exceptfds
80+ The file descriptors in this set are watched for "exceptional conditions". For examples of some exceptional condi‐
81+ tions, see the discussion of POLLPRI in poll(2).
82+
83+ After select() has returned, exceptfds will be cleared of all file descriptors except for those for which an excep‐
84+ tional condition has occurred.
85+
86+ nfds This argument should be set to the highest-numbered file descriptor in any of the three sets, plus 1. The indicated
87+ file descriptors in each set are checked, up to this limit (but see BUGS).
88+
89+ timeout
90+ The timeout argument is a timeval structure (shown below) that specifies the interval that select() should block wait‐
91+ ing for a file descriptor to become ready. The call will block until either:
92+
93+ • a file descriptor becomes ready;
94+
95+ • the call is interrupted by a signal handler; or
96+
97+ • the timeout expires.
98+
99+ Note that the timeout interval will be rounded up to the system clock granularity, and kernel scheduling delays mean
100+ that the blocking interval may overrun by a small amount.
101+
102+ If both fields of the timeval structure are zero, then select() returns immediately. (This is useful for polling.)
103+
104+ If timeout is specified as NULL, select() blocks indefinitely waiting for a file descriptor to become ready.
105+
106+ pselect()
107+ The pselect() system call allows an application to safely wait until either a file descriptor becomes ready or until a signal
108+ is caught.
109+
110+ The operation of select() and pselect() is identical, other than these three differences:
111+
112+ • select() uses a timeout that is a struct timeval (with seconds and microseconds), while pselect() uses a struct timespec
113+ (with seconds and nanoseconds).
114+
115+ • select() may update the timeout argument to indicate how much time was left. pselect() does not change this argument.
116+
117+ • select() has no sigmask argument, and behaves as pselect() called with NULL sigmask.
118+
119+ sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is not NULL, then pselect() first replaces the current sig‐
120+ nal mask by the one pointed to by sigmask, then does the "select" function, and then restores the original signal mask. (If
121+ sigmask is NULL, the signal mask is not modified during the pselect() call.)
122+
123+ Other than the difference in the precision of the timeout argument, the following pselect() call:
124+
125+ ready = pselect(nfds, &readfds, &writefds, &exceptfds,
126+ timeout, &sigmask);
127+
128+ is equivalent to atomically executing the following calls:
129+
130+ sigset_t origmask;
131+
132+ pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
133+ ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
134+ pthread_sigmask(SIG_SETMASK, &origmask, NULL);
135+
136+ 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,
137+ then an atomic test is needed to prevent race conditions. (Suppose the signal handler sets a global flag and returns. Then a
138+ test of this global flag followed by a call of select() could hang indefinitely if the signal arrived just after the test but
139+ just before the call. By contrast, pselect() allows one to first block signals, handle the signals that have come in, then
140+ call pselect() with the desired sigmask, avoiding the race.)
141+
142+ The timeout
143+ The timeout argument for select() is a structure of the following type:
144+
145+ struct timeval {
146+ time_t tv_sec; /* seconds */
147+ suseconds_t tv_usec; /* microseconds */
148+ };
149+
150+ The corresponding argument for pselect() has the following type:
151+
152+ struct timespec {
153+ time_t tv_sec; /* seconds */
154+ long tv_nsec; /* nanoseconds */
155+ };
156+
157+ On Linux, select() modifies timeout to reflect the amount of time not slept; most other implementations do not do this.
158+ (POSIX.1 permits either behavior.) This causes problems both when Linux code which reads timeout is ported to other operating
159+ systems, and when code is ported to Linux that reuses a struct timeval for multiple select()s in a loop without reinitializing
160+ it. Consider timeout to be undefined after select() returns.
161+
162+RETURN VALUE
163+ On success, select() and pselect() return the number of file descriptors contained in the three returned descriptor sets (that
164+ is, the total number of bits that are set in readfds, writefds, exceptfds). The return value may be zero if the timeout ex‐
165+ pired before any file descriptors became ready.
166+
167+ On error, -1 is returned, and errno is set to indicate the error; the file descriptor sets are unmodified, and timeout becomes
168+ undefined.
169+
170+ERRORS
171+ EBADF An invalid file descriptor was given in one of the sets. (Perhaps a file descriptor that was already closed, or one on
172+ which an error has occurred.) However, see BUGS.
173+
174+ EINTR A signal was caught; see signal(7).
175+
176+ EINVAL nfds is negative or exceeds the RLIMIT_NOFILE resource limit (see getrlimit(2)).
177+
178+ EINVAL The value contained within timeout is invalid.
179+
180+ ENOMEM Unable to allocate memory for internal tables.
181+
182+VERSIONS
183+ pselect() was added to Linux in kernel 2.6.16. Prior to this, pselect() was emulated in glibc (but see BUGS).
184+
185+CONFORMING TO
186+ select() conforms to POSIX.1-2001, POSIX.1-2008, and 4.4BSD (select() first appeared in 4.2BSD). Generally portable to/from
187+ non-BSD systems supporting clones of the BSD socket layer (including System V variants). However, note that the System V
188+ variant typically sets the timeout variable before returning, but the BSD variant does not.
189+
190+ pselect() is defined in POSIX.1g, and in POSIX.1-2001 and POSIX.1-2008.
191+
192+NOTES
193+ 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
194+ than FD_SETSIZE will result in undefined behavior. Moreover, POSIX requires fd to be a valid file descriptor.
195+
196+ The operation of select() and pselect() is not affected by the O_NONBLOCK flag.
197+
198+ On some other UNIX systems, select() can fail with the error EAGAIN if the system fails to allocate kernel-internal resources,
199+ rather than ENOMEM as Linux does. POSIX specifies this error for poll(2), but not for select(). Portable programs may wish
200+ to check for EAGAIN and loop, just as with EINTR.
201+
202+ The self-pipe trick
203+ On systems that lack pselect(), reliable (and more portable) signal trapping can be achieved using the self-pipe trick. In
204+ this technique, a signal handler writes a byte to a pipe whose other end is monitored by select() in the main program. (To
205+ 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
206+ used when reading from and writing to the pipe.)
207+
208+ Emulating usleep(3)
209+ Before the advent of usleep(3), some code employed a call to select() with all three sets empty, nfds zero, and a non-NULL
210+ timeout as a fairly portable way to sleep with subsecond precision.
211+
212+ Correspondence between select() and poll() notifications
213+ Within the Linux kernel source, we find the following definitions which show the correspondence between the readable,
214+ writable, and exceptional condition notifications of select() and the event notifications provided by poll(2) and epoll(7):
215+
216+ #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
217+ EPOLLHUP | EPOLLERR)
218+ /* Ready for reading */
219+ #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT |
220+ EPOLLERR)
221+ /* Ready for writing */
222+ #define POLLEX_SET (EPOLLPRI)
223+ /* Exceptional condition */
224+
225+ Multithreaded applications
226+ If a file descriptor being monitored by select() is closed in another thread, the result is unspecified. On some UNIX sys‐
227+ tems, select() unblocks and returns, with an indication that the file descriptor is ready (a subsequent I/O operation will
228+ likely fail with an error, unless another process reopens file descriptor between the time select() returned and the I/O oper‐
229+ ation is performed). On Linux (and some other systems), closing the file descriptor in another thread has no effect on se‐
230+ lect(). In summary, any application that relies on a particular behavior in this scenario must be considered buggy.
231+
232+ C library/kernel differences
233+ The Linux kernel allows file descriptor sets of arbitrary size, determining the length of the sets to be checked from the
234+ value of nfds. However, in the glibc implementation, the fd_set type is fixed in size. See also BUGS.
235+
236+ The pselect() interface described in this page is implemented by glibc. The underlying Linux system call is named pselect6().
237+ This system call has somewhat different behavior from the glibc wrapper function.
238+
239+ The Linux pselect6() system call modifies its timeout argument. However, the glibc wrapper function hides this behavior by
240+ using a local variable for the timeout argument that is passed to the system call. Thus, the glibc pselect() function does
241+ not modify its timeout argument; this is the behavior required by POSIX.1-2001.
242+
243+ The final argument of the pselect6() system call is not a sigset_t * pointer, but is instead a structure of the form:
244+
245+ struct {
246+ const kernel_sigset_t *ss; /* Pointer to signal set */
247+ size_t ss_len; /* Size (in bytes) of object
248+ pointed to by 'ss' */
249+ };
250+
251+ 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‐
252+ chitectures support a maximum of 6 arguments to a system call. See sigprocmask(2) for a discussion of the difference between
253+ the kernel and libc notion of the signal set.
254+
255+ Historical glibc details
256+ Glibc 2.0 provided an incorrect version of pselect() that did not take a sigmask argument.
257+
258+ In glibc versions 2.1 to 2.2.1, one must define _GNU_SOURCE in order to obtain the declaration of pselect() from <sys/se‐
259+ lect.h>.
260+
261+BUGS
262+ POSIX allows an implementation to define an upper limit, advertised via the constant FD_SETSIZE, on the range of file descrip‐
263+ tors that can be specified in a file descriptor set. The Linux kernel imposes no fixed limit, but the glibc implementation
264+ makes fd_set a fixed-size type, with FD_SETSIZE defined as 1024, and the FD_*() macros operating according to that limit. To
265+ monitor file descriptors greater than 1023, use poll(2) or epoll(7) instead.
266+
267+ According to POSIX, select() should check all specified file descriptors in the three file descriptor sets, up to the limit
268+ nfds-1. However, the current implementation ignores any file descriptor in these sets that is greater than the maximum file
269+ descriptor number that the process currently has open. According to POSIX, any such file descriptor that is specified in one
270+ of the sets should result in the error EBADF.
271+
272+ Starting with version 2.1, glibc provided an emulation of pselect() that was implemented using sigprocmask(2) and select().
273+ This implementation remained vulnerable to the very race condition that pselect() was designed to prevent. Modern versions of
274+ glibc use the (race-free) pselect() system call on kernels where it is provided.
275+
276+ On Linux, select() may report a socket file descriptor as "ready for reading", while nevertheless a subsequent read blocks.
277+ This could for example happen when data has arrived but upon examination has the wrong checksum and is discarded. There may
278+ be other circumstances in which a file descriptor is spuriously reported as ready. Thus it may be safer to use O_NONBLOCK on
279+ sockets that should not block.
280+
281+ On Linux, select() also modifies timeout if the call is interrupted by a signal handler (i.e., the EINTR error return). This
282+ is not permitted by POSIX.1. The Linux pselect() system call has the same behavior, but the glibc wrapper hides this behavior
283+ by internally copying the timeout to a local variable and passing that variable to the system call.
284+
285+EXAMPLES
286+ #include <stdio.h>
287+ #include <stdlib.h>
288+ #include <sys/select.h>
289+
290+ int
291+ main(void)
292+ {
293+ fd_set rfds;
294+ struct timeval tv;
295+ int retval;
296+
297+ /* Watch stdin (fd 0) to see when it has input. */
298+
299+ FD_ZERO(&rfds);
300+ FD_SET(0, &rfds);
301+
302+ /* Wait up to five seconds. */
303+
304+ tv.tv_sec = 5;
305+ tv.tv_usec = 0;
306+
307+ retval = select(1, &rfds, NULL, NULL, &tv);
308+ /* Don't rely on the value of tv now! */
309+
310+ if (retval == -1)
311+ perror("select()");
312+ else if (retval)
313+ printf("Data is available now.\n");
314+ /* FD_ISSET(0, &rfds) will be true. */
315+ else
316+ printf("No data within five seconds.\n");
317+
318+ exit(EXIT_SUCCESS);
319+ }
320+
321+SEE ALSO
322+ accept(2), connect(2), poll(2), read(2), recv(2), restart_syscall(2), send(2), sigprocmask(2), write(2), epoll(7), time(7)
323+
324+ For a tutorial with discussion and examples, see select_tut(2).
325+
326+COLOPHON
327+ This page is part of release 5.08 of the Linux man-pages project. A description of the project, information about reporting
328+ bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.
329+
330+Linux 2020-04-11 SELECT(2)