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 #define _XOPEN_SOURCE 600
27 #include <sys/select.h>
28 int pselect(int nfds, fd_set *readfds, fd_set *writefds,
30 fd_set *exceptfds, const struct timespec *timeout,
31 const sigset_t *sigmask);
32
34 select() and pselect() allow a program to monitor multiple file
35 descriptors, waiting until one or more of the file descriptors become
36 "ready" for some class of I/O operation (e.g., input possible). A file
37 descriptor is considered ready if it is possible to perform the corre‐
38 sponding I/O operation (e.g., read(2)) without blocking.
39 The operation of select() and pselect() is identical, with three dif‐
41 ferences:
42 (i) select() uses a timeout that is a struct timeval (with seconds
44 and microseconds), while pselect() uses a struct timespec (with
45 seconds and nanoseconds).
46 (ii) select() may update the timeout argument to indicate how much
48 time was left. pselect() does not change this argument.
49 (iii) select() has no sigmask argument, and behaves as pselect()
51 called with NULL sigmask.
52 Three independent sets of file descriptors are watched. Those listed
54 in readfds will be watched to see if characters become available for
55 reading (more precisely, to see if a read will not block; in particu‐
56 lar, a file descriptor is also ready on end-of-file), those in writefds
57 will be watched to see if a write will not block, and those in
58 exceptfds will be watched for exceptions. On exit, the sets are modi‐
59 fied in place to indicate which file descriptors actually changed sta‐
60 tus. Each of the three file descriptor sets may be specified as NULL
61 if no file descriptors are to be watched for the corresponding class of
62 events.
63 Four macros are provided to manipulate the sets. FD_ZERO() clears a
65 set. FD_SET() and FD_CLR() respectively add and remove a given file
66 descriptor from a set. FD_ISSET() tests to see if a file descriptor is
67 part of the set; this is useful after select() returns.
68 nfds is the highest-numbered file descriptor in any of the three sets,
70 plus 1.
71 timeout is an upper bound on the amount of time elapsed before select()
73 returns. It may be zero, causing select() to return immediately. (This
74 is useful for polling.) If timeout is NULL (no timeout), select() can
75 block indefinitely.
76 sigmask is a pointer to a signal mask (see sigprocmask(2)); if it is
78 not NULL, then pselect() first replaces the current signal mask by the
79 one pointed to by sigmask, then does the `select' function, and then
80 restores the original signal mask.
81 Other than the difference in the precision of the timeout argument, the
83 following pselect() call:
84 ready = pselect(nfds, &readfds, &writefds, &exceptfds,
86 timeout, &sigmask);
87 is equivalent to atomically executing the following calls:
89 sigset_t origmask;
91 sigprocmask(SIG_SETMASK, &sigmask, &origmask);
93 ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
94 sigprocmask(SIG_SETMASK, &origmask, NULL);
95 The reason that pselect() is needed is that if one wants to wait for
97 either a signal or for a file descriptor to become ready, then an
98 atomic test is needed to prevent race conditions. (Suppose the signal
99 handler sets a global flag and returns. Then a test of this global flag
100 followed by a call of select() could hang indefinitely if the signal
101 arrived just after the test but just before the call. By contrast,
102 pselect() allows one to first block signals, handle the signals that
103 have come in, then call pselect() with the desired sigmask, avoiding
104 the race.)
105 The timeout
107 The time structures involved are defined in <sys/time.h> and look like
108 struct timeval {
110 long tv_sec; /* seconds */
111 long tv_usec; /* microseconds */
112 };
113 and
115 struct timespec {
117 long tv_sec; /* seconds */
118 long tv_nsec; /* nanoseconds */
119 };
120 (However, see below on the POSIX.1-2001 versions.)
122 Some code calls select() with all three sets empty, nfds zero, and a
124 non-NULL timeout as a fairly portable way to sleep with subsecond pre‐
125 cision.
126 On Linux, select() modifies timeout to reflect the amount of time not
128 slept; most other implementations do not do this. (POSIX.1-2001 per‐
129 mits either behaviour.) This causes problems both when Linux code
130 which reads timeout is ported to other operating systems, and when code
131 is ported to Linux that reuses a struct timeval for multiple select()s
132 in a loop without reinitializing it. Consider timeout to be undefined
133 after select() returns.
134
136 On success, select() and pselect() return the number of file descrip‐
137 tors contained in the three returned descriptor sets (that is, the
138 total number of bits that are set in readfds, writefds, exceptfds)
139 which may be zero if the timeout expires before anything interesting
140 happens. On error, -1 is returned, and errno is set appropriately; the
141 sets and timeout become undefined, so do not rely on their contents
142 after an error.
143
145 EBADF An invalid file descriptor was given in one of the sets. (Per‐
146 haps a file descriptor that was already closed, or one on which
147 an error has occurred.)
148 EINTR A signal was caught.
150 EINVAL nfds is negative or the value contained within timeout is
152 invalid.
153 ENOMEM unable to allocate memory for internal tables.
155
157 #include <stdio.h>
158 #include <sys/time.h>
159 #include <sys/types.h>
160 #include <unistd.h>
161 int
163 main(void) {
164 fd_set rfds;
165 struct timeval tv;
166 int retval;
167 /* Watch stdin (fd 0) to see when it has input. */
169 FD_ZERO(&rfds);
170 FD_SET(0, &rfds);
171 /* Wait up to five seconds. */
173 tv.tv_sec = 5;
174 tv.tv_usec = 0;
175 retval = select(1, &rfds, NULL, NULL, &tv);
177 /* Don't rely on the value of tv now! */
178 if (retval == -1)
180 perror("select()");
181 else if (retval)
182 printf("Data is available now.\n");
183 /* FD_ISSET(0, &rfds) will be true. */
184 else
185 printf("No data within five seconds.\n");
186 return 0;
188 }
189
191 select() conforms to POSIX.1-2001 and 4.4BSD (select() first appeared
192 in 4.2BSD). Generally portable to/from non-BSD systems supporting
193 clones of the BSD socket layer (including System V variants). However,
194 note that the System V variant typically sets the timeout variable
195 before exit, but the BSD variant does not.
196 pselect() is defined in POSIX.1g, and in POSIX.1-2001.
198
200 An fd_set is a fixed size buffer. Executing FD_CLR() or FD_SET() with
201 a value of fd that is negative or is equal to or larger than FD_SETSIZE
202 will result in undefined behavior. Moreover, POSIX requires fd to be a
203 valid file descriptor.
204 Concerning the types involved, the classical situation is that the two
206 fields of a timeval structure are longs (as shown above), and the
207 structure is defined in <sys/time.h>. The POSIX.1-2001 situation is
208 struct timeval {
210 time_t tv_sec; /* seconds */
211 suseconds_t tv_usec; /* microseconds */
212 };
213 where the structure is defined in <sys/select.h> and the data types
215 time_t and suseconds_t are defined in <sys/types.h>.
216 Concerning prototypes, the classical situation is that one should
218 include <time.h> for select(). The POSIX.1-2001 situation is that one
219 should include <sys/select.h> for select() and pselect(). Libc4 and
220 libc5 do not have a <sys/select.h> header; under glibc 2.0 and later
221 this header exists. Under glibc 2.0 it unconditionally gives the wrong
222 prototype for pselect(), under glibc 2.1-2.2.1 it gives pselect() when
223 _GNU_SOURCE is defined, under glibc 2.2.2-2.2.4 it gives it when
224 _XOPEN_SOURCE is defined and has a value of 600 or larger. No doubt,
225 since POSIX.1-2001, it should give the prototype by default.
226
228 pselect() was added to Linux in kernel 2.6.16. Prior to this, pse‐
229 lect() was emulated in glibc (but see BUGS).
230
232 The Linux pselect() system call modifies its timeout argument. How‐
233 ever, the glibc wrapper function hides this behaviour by using a local
234 variable for the timeout argument that is passed to the system call.
235 Thus, the glibc pselect() function does not modify its timeout argu‐
236 ment; this is the behaviour required by POSIX.1-2001.
237
239 Glibc 2.0 provided a version of pselect() that did not take a sigmask
240 argument.
241 Since version 2.1, glibc has provided an emulation of pselect() that is
243 implemented using sigprocmask(2) and select(). This implementation
244 remains vulnerable to the very race condition that pselect() was
245 designed to prevent. On systems that lack pselect() reliable (and more
246 portable) signal trapping can be achieved using the self-pipe trick
247 (where a signal handler writes a byte to a pipe whose other end is mon‐
248 itored by select() in the main program.)
249 Under Linux, select() may report a socket file descriptor as "ready for
251 reading", while nevertheless a subsequent read blocks. This could for
252 example happen when data has arrived but upon examination has wrong
253 checksum and is discarded. There may be other circumstances in which a
254 file descriptor is spuriously reported as ready. Thus it may be safer
255 to use O_NONBLOCK on sockets that should not block.
256
258 For a tutorial with discussion and examples, see select_tut(2).
259 For vaguely related stuff, see accept(2), connect(2), poll(2), read(2),
261 recv(2), send(2), sigprocmask(2), write(2), epoll(7), fea‐
262 ture_test_macros(7)
263Linux 2.6.16 2006-03-11 SELECT(2)