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       /* According to POSIX.1-2001 */
11       #include <sys/select.h>
12
13       /* According to earlier standards */
14       #include <sys/time.h>
15       #include <sys/types.h>
16       #include <unistd.h>
17
18       int select(int nfds, fd_set *readfds, fd_set *writefds,
19                  fd_set *exceptfds, struct timeval *timeout);
20
21       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
26       #include <sys/select.h>
27
28       int pselect(int nfds, fd_set *readfds, fd_set *writefds,
29                   fd_set *exceptfds, const struct timespec *timeout,
30                   const sigset_t *sigmask);
31
32   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
33
34       pselect(): _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600
35

DESCRIPTION

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
43       The operation of select() and pselect() is identical, with  three  dif‐
44       ferences:
45
46       (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
50       (ii)   select()  may  update  the timeout argument to indicate how much
51              time was left.  pselect() does not change this argument.
52
53       (iii)  select() has no  sigmask  argument,  and  behaves  as  pselect()
54              called with NULL sigmask.
55
56       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
67       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
72       nfds  is the highest-numbered file descriptor in any of the three sets,
73       plus 1.
74
75       timeout is an upper bound on the amount of time elapsed before select()
76       returns.   If  both  fields  of  the  timeval  stucture  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
80       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
85       Other than the difference in the precision of the timeout argument, the
86       following pselect() call:
87
88           ready = pselect(nfds, &readfds, &writefds, &exceptfds,
89                           timeout, &sigmask);
90
91       is equivalent to atomically executing the following calls:
92
93           sigset_t origmask;
94
95           sigprocmask(SIG_SETMASK, &sigmask, &origmask);
96           ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
97           sigprocmask(SIG_SETMASK, &origmask, NULL);
98
99       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
109   The timeout
110       The time structures involved are defined in <sys/time.h> and look like
111
112           struct timeval {
113               long    tv_sec;         /* seconds */
114               long    tv_usec;        /* microseconds */
115           };
116
117       and
118
119           struct timespec {
120               long    tv_sec;         /* seconds */
121               long    tv_nsec;        /* nanoseconds */
122           };
123
124       (However, see below on the POSIX.1-2001 versions.)
125
126       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
130       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

RETURN VALUE

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

ERRORS

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
152       EINTR  A signal was caught; see signal(7).
153
154       EINVAL nfds  is  negative  or  the  value  contained  within timeout is
155              invalid.
156
157       ENOMEM unable to allocate memory for internal tables.
158

VERSIONS

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

CONFORMING TO

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
170       pselect() is defined in POSIX.1g, and in POSIX.1-2001.
171

NOTES

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
178       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
183           struct timeval {
184               time_t         tv_sec;     /* seconds */
185               suseconds_t    tv_usec;    /* microseconds */
186           };
187
188       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
191       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
195       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
201   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

BUGS

209       Glibc 2.0 provided a version of pselect() that did not take  a  sigmask
210       argument.
211
212       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
220       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
227       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

EXAMPLE

235       #include <stdio.h>
236       #include <stdlib.h>
237       #include <sys/time.h>
238       #include <sys/types.h>
239       #include <unistd.h>
240
241       int
242       main(void)
243       {
244           fd_set rfds;
245           struct timeval tv;
246           int retval;
247
248           /* Watch stdin (fd 0) to see when it has input. */
249           FD_ZERO(&rfds);
250           FD_SET(0, &rfds);
251
252           /* Wait up to five seconds. */
253           tv.tv_sec = 5;
254           tv.tv_usec = 0;
255
256           retval = select(1, &rfds, NULL, NULL, &tv);
257           /* Don't rely on the value of tv now! */
258
259           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
267           exit(EXIT_SUCCESS);
268       }
269

SEE ALSO

271       For a tutorial with discussion and examples, see select_tut(2).
272
273       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

COLOPHON

277       This page is part of release 3.22 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/.
280
281
282
283Linux                             2008-12-05                         SELECT(2)
Impressum