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, other than these
44 three differences:
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 The timeout argument specifies the minimum interval that select()
76 should block waiting for a file descriptor to become ready. (This
77 interval will be rounded up to the system clock granularity, and kernel
78 scheduling delays mean that the blocking interval may overrun by a
79 small amount.) If both fields of the timeval structure are zero, then
80 select() returns immediately. (This is useful for polling.) If time‐
81 out is NULL (no timeout), select() can block indefinitely.
82 sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is
84 not NULL, then pselect() first replaces the current signal mask by the
85 one pointed to by sigmask, then does the "select" function, and then
86 restores the original signal mask.
87 Other than the difference in the precision of the timeout argument, the
89 following pselect() call:
90 ready = pselect(nfds, &readfds, &writefds, &exceptfds,
92 timeout, &sigmask);
93 is equivalent to atomically executing the following calls:
95 sigset_t origmask;
97 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
99 ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
100 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
101 The reason that pselect() is needed is that if one wants to wait for
103 either a signal or for a file descriptor to become ready, then an
104 atomic test is needed to prevent race conditions. (Suppose the signal
105 handler sets a global flag and returns. Then a test of this global
106 flag followed by a call of select() could hang indefinitely if the sig‐
107 nal arrived just after the test but just before the call. By contrast,
108 pselect() allows one to first block signals, handle the signals that
109 have come in, then call pselect() with the desired sigmask, avoiding
110 the race.)
111 The timeout
113 The time structures involved are defined in <sys/time.h> and look like
114 struct timeval {
116 long tv_sec; /* seconds */
117 long tv_usec; /* microseconds */
118 };
119 and
121 struct timespec {
123 long tv_sec; /* seconds */
124 long tv_nsec; /* nanoseconds */
125 };
126 (However, see below on the POSIX.1-2001 versions.)
128 Some code calls select() with all three sets empty, nfds zero, and a
130 non-NULL timeout as a fairly portable way to sleep with subsecond pre‐
131 cision.
132 On Linux, select() modifies timeout to reflect the amount of time not
134 slept; most other implementations do not do this. (POSIX.1-2001 per‐
135 mits either behavior.) This causes problems both when Linux code which
136 reads timeout is ported to other operating systems, and when code is
137 ported to Linux that reuses a struct timeval for multiple select()s in
138 a loop without reinitializing it. Consider timeout to be undefined
139 after select() returns.
140
142 On success, select() and pselect() return the number of file descrip‐
143 tors contained in the three returned descriptor sets (that is, the
144 total number of bits that are set in readfds, writefds, exceptfds)
145 which may be zero if the timeout expires before anything interesting
146 happens. On error, -1 is returned, and errno is set appropriately; the
147 sets and timeout become undefined, so do not rely on their contents
148 after an error.
149
151 EBADF An invalid file descriptor was given in one of the sets. (Per‐
152 haps a file descriptor that was already closed, or one on which
153 an error has occurred.)
154 EINTR A signal was caught; see signal(7).
156 EINVAL nfds is negative or the value contained within timeout is
158 invalid.
159 ENOMEM unable to allocate memory for internal tables.
161
163 pselect() was added to Linux in kernel 2.6.16. Prior to this, pse‐
164 lect() was emulated in glibc (but see BUGS).
165
167 select() conforms to POSIX.1-2001 and 4.4BSD (select() first appeared
168 in 4.2BSD). Generally portable to/from non-BSD systems supporting
169 clones of the BSD socket layer (including System V variants). However,
170 note that the System V variant typically sets the timeout variable
171 before exit, but the BSD variant does not.
172 pselect() is defined in POSIX.1g, and in POSIX.1-2001.
174
176 An fd_set is a fixed size buffer. Executing FD_CLR() or FD_SET() with
177 a value of fd that is negative or is equal to or larger than FD_SETSIZE
178 will result in undefined behavior. Moreover, POSIX requires fd to be a
179 valid file descriptor.
180 Concerning the types involved, the classical situation is that the two
182 fields of a timeval structure are typed as long (as shown above), and
183 the structure is defined in <sys/time.h>. The POSIX.1-2001 situation
184 is
185 struct timeval {
187 time_t tv_sec; /* seconds */
188 suseconds_t tv_usec; /* microseconds */
189 };
190 where the structure is defined in <sys/select.h> and the data types
192 time_t and suseconds_t are defined in <sys/types.h>.
193 Concerning prototypes, the classical situation is that one should
195 include <time.h> for select(). The POSIX.1-2001 situation is that one
196 should include <sys/select.h> for select() and pselect().
197 Libc4 and libc5 do not have a <sys/select.h> header; under glibc 2.0
199 and later this header exists. Under glibc 2.0 it unconditionally gives
200 the wrong prototype for pselect(). Under glibc 2.1 to 2.2.1 it gives
201 pselect() when _GNU_SOURCE is defined. Since glibc 2.2.2 the require‐
202 ments are as shown in the SYNOPSIS.
203 Multithreaded applications
205 If a file descriptor being monitored by select() is closed in another
206 thread, the result is unspecified. On some UNIX systems, select()
207 unblocks and returns, with an indication that the file descriptor is
208 ready (a subsequent I/O operation will likely fail with an error,
209 unless another the file descriptor reopened between the time select()
210 returned and the I/O operations was performed). On Linux (and some
211 other systems), closing the file descriptor in another thread has no
212 effect on select(). In summary, any application that relies on a par‐
213 ticular behavior in this scenario must be considered buggy.
214 Linux notes
216 The pselect() interface described in this page is implemented by glibc.
217 The underlying Linux system call is named pselect6(). This system call
218 has somewhat different behavior from the glibc wrapper function.
219 The Linux pselect6() system call modifies its timeout argument. How‐
221 ever, the glibc wrapper function hides this behavior by using a local
222 variable for the timeout argument that is passed to the system call.
223 Thus, the glibc pselect() function does not modify its timeout argu‐
224 ment; this is the behavior required by POSIX.1-2001.
225 The final argument of the pselect6() system call is not a sigset_t *
227 pointer, but is instead a structure of the form:
228 struct {
230 const sigset_t *ss; /* Pointer to signal set */
231 size_t ss_len; /* Size (in bytes) of object pointed
232 to by 'ss' */
233 };
234 This allows the system call to obtain both a pointer to the signal set
236 and its size, while allowing for the fact that most architectures sup‐
237 port a maximum of 6 arguments to a system call.
238
240 Glibc 2.0 provided a version of pselect() that did not take a sigmask
241 argument.
242 Starting with version 2.1, glibc provided an emulation of pselect()
244 that was implemented using sigprocmask(2) and select(). This implemen‐
245 tation remained vulnerable to the very race condition that pselect()
246 was designed to prevent. Modern versions of glibc use the (race-free)
247 pselect() system call on kernels where it is provided.
248 On systems that lack pselect(), reliable (and more portable) signal
250 trapping can be achieved using the self-pipe trick. In this technique,
251 a signal handler writes a byte to a pipe whose other end is monitored
252 by select() in the main program. (To avoid possibly blocking when
253 writing to a pipe that may be full or reading from a pipe that may be
254 empty, nonblocking I/O is used when reading from and writing to the
255 pipe.)
256 Under Linux, select() may report a socket file descriptor as "ready for
258 reading", while nevertheless a subsequent read blocks. This could for
259 example happen when data has arrived but upon examination has wrong
260 checksum and is discarded. There may be other circumstances in which a
261 file descriptor is spuriously reported as ready. Thus it may be safer
262 to use O_NONBLOCK on sockets that should not block.
263 On Linux, select() also modifies timeout if the call is interrupted by
265 a signal handler (i.e., the EINTR error return). This is not permitted
266 by POSIX.1-2001. The Linux pselect() system call has the same behav‐
267 ior, but the glibc wrapper hides this behavior by internally copying
268 the timeout to a local variable and passing that variable to the system
269 call.
270
272 #include <stdio.h>
273 #include <stdlib.h>
274 #include <sys/time.h>
275 #include <sys/types.h>
276 #include <unistd.h>
277 int
279 main(void)
280 {
281 fd_set rfds;
282 struct timeval tv;
283 int retval;
284 /* Watch stdin (fd 0) to see when it has input. */
286 FD_ZERO(&rfds);
287 FD_SET(0, &rfds);
288 /* Wait up to five seconds. */
290 tv.tv_sec = 5;
291 tv.tv_usec = 0;
292 retval = select(1, &rfds, NULL, NULL, &tv);
294 /* Don't rely on the value of tv now! */
295 if (retval == -1)
297 perror("select()");
298 else if (retval)
299 printf("Data is available now.\n");
300 /* FD_ISSET(0, &rfds) will be true. */
301 else
302 printf("No data within five seconds.\n");
303 exit(EXIT_SUCCESS);
305 }
306
308 accept(2), connect(2), poll(2), read(2), recv(2), send(2), sigproc‐
309 mask(2), write(2), epoll(7), time(7)
310 For a tutorial with discussion and examples, see select_tut(2).
312
314 This page is part of release 3.53 of the Linux man-pages project. A
315 description of the project, and information about reporting bugs, can
316 be found at http://www.kernel.org/doc/man-pages/.
317Linux 2012-08-17 SELECT(2)