1SELECT(2)                  Linux Programmer's Manual                 SELECT(2)
2
3
4

NAME

6       select,  pselect,  FD_CLR,  FD_ISSET, FD_SET, FD_ZERO - synchronous I/O
7       multiplexing
8

SYNOPSIS

10       #include <sys/select.h>
11
12       int select(int nfds, fd_set *readfds, fd_set *writefds,
13                  fd_set *exceptfds, struct timeval *timeout);
14
15       void FD_CLR(int fd, fd_set *set);
16       int  FD_ISSET(int fd, fd_set *set);
17       void FD_SET(int fd, fd_set *set);
18       void FD_ZERO(fd_set *set);
19
20       int pselect(int nfds, fd_set *readfds, fd_set *writefds,
21                   fd_set *exceptfds, const struct timespec *timeout,
22                   const sigset_t *sigmask);
23
24   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
25
26       pselect(): _POSIX_C_SOURCE >= 200112L
27

DESCRIPTION

29       select() allows a program to monitor multiple file descriptors, waiting
30       until one or more of the file descriptors become "ready" for some class
31       of I/O operation (e.g., input possible).  A file descriptor is  consid‐
32       ered  ready  if it is possible to perform a corresponding I/O operation
33       (e.g., read(2), or a sufficiently small write(2)) without blocking.
34
35       select() can monitor only file descriptors numbers that are  less  than
36       FD_SETSIZE;  poll(2)  and  epoll(7)  do  not have this limitation.  See
37       BUGS.
38
39   File descriptor sets
40       The principal arguments of select() are three "sets" of  file  descrip‐
41       tors  (declared  with  the type fd_set), which allow the caller to wait
42       for three classes of events on the specified set of  file  descriptors.
43       Each  of  the  fd_set arguments may be specified as NULL if no file de‐
44       scriptors are to be watched for the corresponding class of events.
45
46       Note well: Upon return, each of the file descriptor sets is modified in
47       place  to indicate which file descriptors are currently "ready".  Thus,
48       if using select() within a loop, the sets must be reinitialized  before
49       each  call.  The implementation of the fd_set arguments as value-result
50       arguments is a design error that is avoided in poll(2) and epoll(7).
51
52       The contents of a file descriptor set can be manipulated using the fol‐
53       lowing macros:
54
55       FD_ZERO()
56              This  macro  clears (removes all file descriptors from) set.  It
57              should be employed as the first step in initializing a file  de‐
58              scriptor set.
59
60       FD_SET()
61              This  macro  adds  the file descriptor fd to set.  Adding a file
62              descriptor that is already present in the set is  a  no-op,  and
63              does not produce an error.
64
65       FD_CLR()
66              This  macro removes the file descriptor fd from set.  Removing a
67              file descriptor that is not present in the set is a  no-op,  and
68              does not produce an error.
69
70       FD_ISSET()
71              select()  modifies  the  contents  of  the sets according to the
72              rules described below.  After calling select(),  the  FD_ISSET()
73              macro  can be used to test if a file descriptor is still present
74              in a set.  FD_ISSET() returns nonzero if the file descriptor  fd
75              is present in set, and zero if it is not.
76
77   Arguments
78       The arguments of select() are as follows:
79
80       readfds
81              The  file descriptors in this set are watched to see if they are
82              ready for reading.  A file descriptor is ready for reading if  a
83              read  operation will not block; in particular, a file descriptor
84              is also ready on end-of-file.
85
86              After select() has returned, readfds will be cleared of all file
87              descriptors except for those that are ready for reading.
88
89       writefds
90              The  file descriptors in this set are watched to see if they are
91              ready for writing.  A file descriptor is ready for writing if  a
92              write  operation  will  not  block.  However, even if a file de‐
93              scriptor indicates as writable, a large write may still block.
94
95              After select() has returned, writefds will  be  cleared  of  all
96              file descriptors except for those that are ready for writing.
97
98       exceptfds
99              The  file  descriptors  in this set are watched for "exceptional
100              conditions".  For examples of some exceptional  conditions,  see
101              the discussion of POLLPRI in poll(2).
102
103              After  select()  has  returned, exceptfds will be cleared of all
104              file descriptors except for those for which an exceptional  con‐
105              dition has occurred.
106
107       nfds   This  argument  should  be  set to the highest-numbered file de‐
108              scriptor in any of the three sets, plus 1.  The  indicated  file
109              descriptors  in  each set are checked, up to this limit (but see
110              BUGS).
111
112       timeout
113              The timeout argument is a timeval structure (shown  below)  that
114              specifies  the interval that select() should block waiting for a
115              file descriptor to become ready.  The call will block until  ei‐
116              ther:
117
118              • a file descriptor becomes ready;
119
120              • the call is interrupted by a signal handler; or
121
122              • the timeout expires.
123
124              Note  that the timeout interval will be rounded up to the system
125              clock granularity, and kernel scheduling delays  mean  that  the
126              blocking interval may overrun by a small amount.
127
128              If  both fields of the timeval structure are zero, then select()
129              returns immediately.  (This is useful for polling.)
130
131              If timeout is specified as NULL,  select()  blocks  indefinitely
132              waiting for a file descriptor to become ready.
133
134   pselect()
135       The  pselect()  system  call allows an application to safely wait until
136       either a file descriptor becomes ready or until a signal is caught.
137
138       The operation of select() and pselect() is identical, other than  these
139       three differences:
140
141select()  uses  a  timeout that is a struct timeval (with seconds and
142         microseconds), while pselect() uses a struct timespec  (with  seconds
143         and nanoseconds).
144
145select()  may  update  the timeout argument to indicate how much time
146         was left.  pselect() does not change this argument.
147
148select() has no sigmask argument, and  behaves  as  pselect()  called
149         with NULL sigmask.
150
151       sigmask  is  a  pointer to a signal mask (see sigprocmask(2)); if it is
152       not NULL, then pselect() first replaces the current signal mask by  the
153       one  pointed  to  by sigmask, then does the "select" function, and then
154       restores the original signal mask.  (If sigmask  is  NULL,  the  signal
155       mask is not modified during the pselect() call.)
156
157       Other than the difference in the precision of the timeout argument, the
158       following pselect() call:
159
160           ready = pselect(nfds, &readfds, &writefds, &exceptfds,
161                           timeout, &sigmask);
162
163       is equivalent to atomically executing the following calls:
164
165           sigset_t origmask;
166
167           pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
168           ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
169           pthread_sigmask(SIG_SETMASK, &origmask, NULL);
170
171       The reason that pselect() is needed is that if one wants  to  wait  for
172       either  a  signal  or  for  a  file descriptor to become ready, then an
173       atomic test is needed to prevent race conditions.  (Suppose the  signal
174       handler  sets  a  global  flag and returns.  Then a test of this global
175       flag followed by a call of select() could hang indefinitely if the sig‐
176       nal arrived just after the test but just before the call.  By contrast,
177       pselect() allows one to first block signals, handle  the  signals  that
178       have  come  in,  then call pselect() with the desired sigmask, avoiding
179       the race.)
180
181   The timeout
182       The timeout argument for select() is a structure of the following type:
183
184           struct timeval {
185               time_t      tv_sec;         /* seconds */
186               suseconds_t tv_usec;        /* microseconds */
187           };
188
189       The corresponding argument for pselect() has the following type:
190
191           struct timespec {
192               time_t      tv_sec;         /* seconds */
193               long        tv_nsec;        /* nanoseconds */
194           };
195
196       On Linux, select() modifies timeout to reflect the amount of  time  not
197       slept; most other implementations do not do this.  (POSIX.1 permits ei‐
198       ther behavior.)  This causes problems both when Linux code which  reads
199       timeout  is  ported to other operating systems, and when code is ported
200       to Linux that reuses a struct timeval for multiple select()s in a  loop
201       without  reinitializing it.  Consider timeout to be undefined after se‐
202       lect() returns.
203

RETURN VALUE

205       On success, select() and pselect() return the number of  file  descrip‐
206       tors  contained in the three returned descriptor sets (that is, the to‐
207       tal number of bits that are set in readfds, writefds, exceptfds).   The
208       return  value  may  be  zero if the timeout expired before any file de‐
209       scriptors became ready.
210
211       On error, -1 is returned, and errno is set to indicate the  error;  the
212       file descriptor sets are unmodified, and timeout becomes undefined.
213

ERRORS

215       EBADF  An  invalid file descriptor was given in one of the sets.  (Per‐
216              haps a file descriptor that was already closed, or one on  which
217              an error has occurred.)  However, see BUGS.
218
219       EINTR  A signal was caught; see signal(7).
220
221       EINVAL nfds  is  negative  or  exceeds the RLIMIT_NOFILE resource limit
222              (see getrlimit(2)).
223
224       EINVAL The value contained within timeout is invalid.
225
226       ENOMEM Unable to allocate memory for internal tables.
227

VERSIONS

229       pselect() was added to Linux in kernel 2.6.16.   Prior  to  this,  pse‐
230       lect() was emulated in glibc (but see BUGS).
231

CONFORMING TO

233       select()  conforms  to POSIX.1-2001, POSIX.1-2008, and 4.4BSD (select()
234       first appeared in 4.2BSD).  Generally portable to/from non-BSD  systems
235       supporting  clones  of  the  BSD socket layer (including System V vari‐
236       ants).  However, note that the  System V  variant  typically  sets  the
237       timeout variable before returning, but the BSD variant does not.
238
239       pselect() is defined in POSIX.1g, and in POSIX.1-2001 and POSIX.1-2008.
240

NOTES

242       An  fd_set is a fixed size buffer.  Executing FD_CLR() or FD_SET() with
243       a value of fd that is negative or is equal to or larger than FD_SETSIZE
244       will result in undefined behavior.  Moreover, POSIX requires fd to be a
245       valid file descriptor.
246
247       The operation of select() and pselect() is not affected by  the  O_NON‐
248       BLOCK flag.
249
250       On  some other UNIX systems, select() can fail with the error EAGAIN if
251       the system fails to allocate  kernel-internal  resources,  rather  than
252       ENOMEM  as Linux does.  POSIX specifies this error for poll(2), but not
253       for select().  Portable programs may wish to check for EAGAIN and loop,
254       just as with EINTR.
255
256   The self-pipe trick
257       On  systems  that  lack  pselect(), reliable (and more portable) signal
258       trapping can be achieved using the self-pipe trick.  In this technique,
259       a  signal  handler writes a byte to a pipe whose other end is monitored
260       by select() in the main program.   (To  avoid  possibly  blocking  when
261       writing  to  a pipe that may be full or reading from a pipe that may be
262       empty, nonblocking I/O is used when reading from  and  writing  to  the
263       pipe.)
264
265   Emulating usleep(3)
266       Before  the  advent of usleep(3), some code employed a call to select()
267       with all three sets empty, nfds zero,  and  a  non-NULL  timeout  as  a
268       fairly portable way to sleep with subsecond precision.
269
270   Correspondence between select() and poll() notifications
271       Within the Linux kernel source, we find the following definitions which
272       show the correspondence between the readable, writable, and exceptional
273       condition  notifications  of  select() and the event notifications pro‐
274       vided by poll(2) and epoll(7):
275
276           #define POLLIN_SET  (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
277                                EPOLLHUP | EPOLLERR)
278                              /* Ready for reading */
279           #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT |
280                                EPOLLERR)
281                              /* Ready for writing */
282           #define POLLEX_SET  (EPOLLPRI)
283                              /* Exceptional condition */
284
285   Multithreaded applications
286       If a file descriptor being monitored by select() is closed  in  another
287       thread,  the result is unspecified.  On some UNIX systems, select() un‐
288       blocks and returns, with an indication  that  the  file  descriptor  is
289       ready  (a  subsequent I/O operation will likely fail with an error, un‐
290       less another process reopens file descriptor between the time  select()
291       returned and the I/O operation is performed).  On Linux (and some other
292       systems), closing the file descriptor in another thread has  no  effect
293       on  select().   In summary, any application that relies on a particular
294       behavior in this scenario must be considered buggy.
295
296   C library/kernel differences
297       The Linux kernel allows file descriptor sets of arbitrary size,  deter‐
298       mining  the  length  of  the sets to be checked from the value of nfds.
299       However, in the glibc implementation, the fd_set type is fixed in size.
300       See also BUGS.
301
302       The pselect() interface described in this page is implemented by glibc.
303       The underlying Linux system call is named pselect6().  This system call
304       has somewhat different behavior from the glibc wrapper function.
305
306       The  Linux  pselect6() system call modifies its timeout argument.  How‐
307       ever, the glibc wrapper function hides this behavior by using  a  local
308       variable  for  the  timeout argument that is passed to the system call.
309       Thus, the glibc pselect() function does not modify  its  timeout  argu‐
310       ment; this is the behavior required by POSIX.1-2001.
311
312       The  final  argument  of the pselect6() system call is not a sigset_t *
313       pointer, but is instead a structure of the form:
314
315           struct {
316               const kernel_sigset_t *ss;   /* Pointer to signal set */
317               size_t ss_len;               /* Size (in bytes) of object
318                                               pointed to by 'ss' */
319           };
320
321       This allows the system call to obtain both a pointer to the signal  set
322       and  its size, while allowing for the fact that most architectures sup‐
323       port a maximum of 6 arguments to a system call.  See sigprocmask(2) for
324       a  discussion  of  the difference between the kernel and libc notion of
325       the signal set.
326
327   Historical glibc details
328       Glibc 2.0 provided an incorrect version of pselect() that did not  take
329       a sigmask argument.
330
331       In glibc versions 2.1 to 2.2.1, one must define _GNU_SOURCE in order to
332       obtain the declaration of pselect() from <sys/select.h>.
333

BUGS

335       POSIX allows an implementation to define an upper limit, advertised via
336       the  constant  FD_SETSIZE, on the range of file descriptors that can be
337       specified in a file descriptor set.  The Linux kernel imposes no  fixed
338       limit,  but  the  glibc  implementation makes fd_set a fixed-size type,
339       with FD_SETSIZE defined as 1024, and the FD_*()  macros  operating  ac‐
340       cording  to that limit.  To monitor file descriptors greater than 1023,
341       use poll(2) or epoll(7) instead.
342
343       According to POSIX, select() should check all specified  file  descrip‐
344       tors  in  the three file descriptor sets, up to the limit nfds-1.  How‐
345       ever, the current implementation ignores any file descriptor  in  these
346       sets  that  is greater than the maximum file descriptor number that the
347       process currently has open.  According to POSIX, any such file descrip‐
348       tor  that  is  specified  in one of the sets should result in the error
349       EBADF.
350
351       Starting with version 2.1, glibc provided  an  emulation  of  pselect()
352       that was implemented using sigprocmask(2) and select().  This implemen‐
353       tation remained vulnerable to the very race  condition  that  pselect()
354       was  designed to prevent.  Modern versions of glibc use the (race-free)
355       pselect() system call on kernels where it is provided.
356
357       On Linux, select() may report a socket file descriptor  as  "ready  for
358       reading",  while nevertheless a subsequent read blocks.  This could for
359       example happen when data has arrived but upon examination has the wrong
360       checksum and is discarded.  There may be other circumstances in which a
361       file descriptor is spuriously reported as ready.  Thus it may be  safer
362       to use O_NONBLOCK on sockets that should not block.
363
364       On  Linux, select() also modifies timeout if the call is interrupted by
365       a signal handler (i.e., the EINTR error return).  This is not permitted
366       by POSIX.1.  The Linux pselect() system call has the same behavior, but
367       the glibc wrapper hides this behavior by internally copying the timeout
368       to a local variable and passing that variable to the system call.
369

EXAMPLES

371       #include <stdio.h>
372       #include <stdlib.h>
373       #include <sys/select.h>
374
375       int
376       main(void)
377       {
378           fd_set rfds;
379           struct timeval tv;
380           int retval;
381
382           /* Watch stdin (fd 0) to see when it has input. */
383
384           FD_ZERO(&rfds);
385           FD_SET(0, &rfds);
386
387           /* Wait up to five seconds. */
388
389           tv.tv_sec = 5;
390           tv.tv_usec = 0;
391
392           retval = select(1, &rfds, NULL, NULL, &tv);
393           /* Don't rely on the value of tv now! */
394
395           if (retval == -1)
396               perror("select()");
397           else if (retval)
398               printf("Data is available now.\n");
399               /* FD_ISSET(0, &rfds) will be true. */
400           else
401               printf("No data within five seconds.\n");
402
403           exit(EXIT_SUCCESS);
404       }
405

SEE ALSO

407       accept(2),  connect(2),  poll(2), read(2), recv(2), restart_syscall(2),
408       send(2), sigprocmask(2), write(2), epoll(7), time(7)
409
410       For a tutorial with discussion and examples, see select_tut(2).
411

COLOPHON

413       This page is part of release 5.10 of the Linux  man-pages  project.   A
414       description  of  the project, information about reporting bugs, and the
415       latest    version    of    this    page,    can     be     found     at
416       https://www.kernel.org/doc/man-pages/.
417
418
419
420Linux                             2020-11-01                         SELECT(2)
Impressum