1SELECT(2) Linux Programmer's Manual SELECT(2)
2
6 select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O
7 multiplexing
8
10 /* According to POSIX.1-2001 */
11 #include <sys/select.h>
12 /* According to earlier standards */
14 #include <sys/time.h>
15 #include <sys/types.h>
16 #include <unistd.h>
17 int select(int nfds, fd_set *readfds, fd_set *writefds,
19 fd_set *exceptfds, struct timeval *timeout);
20 void FD_CLR(int fd, fd_set *set);
22 int FD_ISSET(int fd, fd_set *set);
23 void FD_SET(int fd, fd_set *set);
24 void FD_ZERO(fd_set *set);
25 #include <sys/select.h>
27 int pselect(int nfds, fd_set *readfds, fd_set *writefds,
29 fd_set *exceptfds, const struct timespec *timeout,
30 const sigset_t *sigmask);
31 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
33 pselect(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600
35
37 select() and pselect() allow a program to monitor multiple file
38 descriptors, waiting until one or more of the file descriptors become
39 "ready" for some class of I/O operation (e.g., input possible). A file
40 descriptor is considered ready if it is possible to perform the corre‐
41 sponding I/O operation (e.g., read(2)) without blocking.
42 The operation of select() and pselect() is identical, with three dif‐
44 ferences:
45 (i) select() uses a timeout that is a struct timeval (with seconds
47 and microseconds), while pselect() uses a struct timespec (with
48 seconds and nanoseconds).
49 (ii) select() may update the timeout argument to indicate how much
51 time was left. pselect() does not change this argument.
52 (iii) select() has no sigmask argument, and behaves as pselect()
54 called with NULL sigmask.
55 Three independent sets of file descriptors are watched. Those listed
57 in readfds will be watched to see if characters become available for
58 reading (more precisely, to see if a read will not block; in particu‐
59 lar, a file descriptor is also ready on end-of-file), those in writefds
60 will be watched to see if a write will not block, and those in
61 exceptfds will be watched for exceptions. On exit, the sets are modi‐
62 fied in place to indicate which file descriptors actually changed sta‐
63 tus. Each of the three file descriptor sets may be specified as NULL
64 if no file descriptors are to be watched for the corresponding class of
65 events.
66 Four macros are provided to manipulate the sets. FD_ZERO() clears a
68 set. FD_SET() and FD_CLR() respectively add and remove a given file
69 descriptor from a set. FD_ISSET() tests to see if a file descriptor is
70 part of the set; this is useful after select() returns.
71 nfds is the highest-numbered file descriptor in any of the three sets,
73 plus 1.
74 timeout is an upper bound on the amount of time elapsed before select()
76 returns. If both fields of the timeval structure are zero, then
77 select() returns immediately. (This is useful for polling.) If time‐
78 out is NULL (no timeout), select() can block indefinitely.
79 sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is
81 not NULL, then pselect() first replaces the current signal mask by the
82 one pointed to by sigmask, then does the "select" function, and then
83 restores the original signal mask.
84 Other than the difference in the precision of the timeout argument, the
86 following pselect() call:
87 ready = pselect(nfds, &readfds, &writefds, &exceptfds,
89 timeout, &sigmask);
90 is equivalent to atomically executing the following calls:
92 sigset_t origmask;
94 sigprocmask(SIG_SETMASK, &sigmask, &origmask);
96 ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
97 sigprocmask(SIG_SETMASK, &origmask, NULL);
98 The reason that pselect() is needed is that if one wants to wait for
100 either a signal or for a file descriptor to become ready, then an
101 atomic test is needed to prevent race conditions. (Suppose the signal
102 handler sets a global flag and returns. Then a test of this global
103 flag followed by a call of select() could hang indefinitely if the sig‐
104 nal arrived just after the test but just before the call. By contrast,
105 pselect() allows one to first block signals, handle the signals that
106 have come in, then call pselect() with the desired sigmask, avoiding
107 the race.)
108 The timeout
110 The time structures involved are defined in <sys/time.h> and look like
111 struct timeval {
113 long tv_sec; /* seconds */
114 long tv_usec; /* microseconds */
115 };
116 and
118 struct timespec {
120 long tv_sec; /* seconds */
121 long tv_nsec; /* nanoseconds */
122 };
123 (However, see below on the POSIX.1-2001 versions.)
125 Some code calls select() with all three sets empty, nfds zero, and a
127 non-NULL timeout as a fairly portable way to sleep with subsecond pre‐
128 cision.
129 On Linux, select() modifies timeout to reflect the amount of time not
131 slept; most other implementations do not do this. (POSIX.1-2001 per‐
132 mits either behavior.) This causes problems both when Linux code which
133 reads timeout is ported to other operating systems, and when code is
134 ported to Linux that reuses a struct timeval for multiple select()s in
135 a loop without reinitializing it. Consider timeout to be undefined
136 after select() returns.
137
139 On success, select() and pselect() return the number of file descrip‐
140 tors contained in the three returned descriptor sets (that is, the
141 total number of bits that are set in readfds, writefds, exceptfds)
142 which may be zero if the timeout expires before anything interesting
143 happens. On error, -1 is returned, and errno is set appropriately; the
144 sets and timeout become undefined, so do not rely on their contents
145 after an error.
146
148 EBADF An invalid file descriptor was given in one of the sets. (Per‐
149 haps a file descriptor that was already closed, or one on which
150 an error has occurred.)
151 EINTR A signal was caught; see signal(7).
153 EINVAL nfds is negative or the value contained within timeout is
155 invalid.
156 ENOMEM unable to allocate memory for internal tables.
158
160 pselect() was added to Linux in kernel 2.6.16. Prior to this, pse‐
161 lect() was emulated in glibc (but see BUGS).
162
164 select() conforms to POSIX.1-2001 and 4.4BSD (select() first appeared
165 in 4.2BSD). Generally portable to/from non-BSD systems supporting
166 clones of the BSD socket layer (including System V variants). However,
167 note that the System V variant typically sets the timeout variable
168 before exit, but the BSD variant does not.
169 pselect() is defined in POSIX.1g, and in POSIX.1-2001.
171
173 An fd_set is a fixed size buffer. Executing FD_CLR() or FD_SET() with
174 a value of fd that is negative or is equal to or larger than FD_SETSIZE
175 will result in undefined behavior. Moreover, POSIX requires fd to be a
176 valid file descriptor.
177 Concerning the types involved, the classical situation is that the two
179 fields of a timeval structure are typed as long (as shown above), and
180 the structure is defined in <sys/time.h>. The POSIX.1-2001 situation
181 is
182 struct timeval {
184 time_t tv_sec; /* seconds */
185 suseconds_t tv_usec; /* microseconds */
186 };
187 where the structure is defined in <sys/select.h> and the data types
189 time_t and suseconds_t are defined in <sys/types.h>.
190 Concerning prototypes, the classical situation is that one should
192 include <time.h> for select(). The POSIX.1-2001 situation is that one
193 should include <sys/select.h> for select() and pselect().
194 Libc4 and libc5 do not have a <sys/select.h> header; under glibc 2.0
196 and later this header exists. Under glibc 2.0 it unconditionally gives
197 the wrong prototype for pselect(). Under glibc 2.1 to 2.2.1 it gives
198 pselect() when _GNU_SOURCE is defined. Since glibc 2.2.2 the require‐
199 ments are as shown in the SYNOPSIS.
200 Linux Notes
202 The Linux pselect() system call modifies its timeout argument. How‐
203 ever, the glibc wrapper function hides this behavior by using a local
204 variable for the timeout argument that is passed to the system call.
205 Thus, the glibc pselect() function does not modify its timeout argu‐
206 ment; this is the behavior required by POSIX.1-2001.
207
209 Glibc 2.0 provided a version of pselect() that did not take a sigmask
210 argument.
211 Since version 2.1, glibc has provided an emulation of pselect() that is
213 implemented using sigprocmask(2) and select(). This implementation
214 remains vulnerable to the very race condition that pselect() was
215 designed to prevent. On systems that lack pselect(), reliable (and
216 more portable) signal trapping can be achieved using the self-pipe
217 trick (where a signal handler writes a byte to a pipe whose other end
218 is monitored by select() in the main program.)
219 Under Linux, select() may report a socket file descriptor as "ready for
221 reading", while nevertheless a subsequent read blocks. This could for
222 example happen when data has arrived but upon examination has wrong
223 checksum and is discarded. There may be other circumstances in which a
224 file descriptor is spuriously reported as ready. Thus it may be safer
225 to use O_NONBLOCK on sockets that should not block.
226 On Linux, select() also modifies timeout if the call is interrupted by
228 a signal handler (i.e., the EINTR error return). This is not permitted
229 by POSIX.1-2001. The Linux pselect() system call has the same behav‐
230 ior, but the glibc wrapper hides this behavior by internally copying
231 the timeout to a local variable and passing that variable to the system
232 call.
233
235 #include <stdio.h>
236 #include <stdlib.h>
237 #include <sys/time.h>
238 #include <sys/types.h>
239 #include <unistd.h>
240 int
242 main(void)
243 {
244 fd_set rfds;
245 struct timeval tv;
246 int retval;
247 /* Watch stdin (fd 0) to see when it has input. */
249 FD_ZERO(&rfds);
250 FD_SET(0, &rfds);
251 /* Wait up to five seconds. */
253 tv.tv_sec = 5;
254 tv.tv_usec = 0;
255 retval = select(1, &rfds, NULL, NULL, &tv);
257 /* Don't rely on the value of tv now! */
258 if (retval == -1)
260 perror("select()");
261 else if (retval)
262 printf("Data is available now.\n");
263 /* FD_ISSET(0, &rfds) will be true. */
264 else
265 printf("No data within five seconds.\n");
266 exit(EXIT_SUCCESS);
268 }
269
271 For a tutorial with discussion and examples, see select_tut(2).
272 For vaguely related stuff, see accept(2), connect(2), poll(2), read(2),
274 recv(2), send(2), sigprocmask(2), write(2), epoll(7), time(7)
275
277 This page is part of release 3.25 of the Linux man-pages project. A
278 description of the project, and information about reporting bugs, can
279 be found at http://www.kernel.org/doc/man-pages/.
280Linux 2008-12-05 SELECT(2)