| 1 |
.\" Copyright 1992, Drew Eckhardt <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH select 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \- |
| 9 |
synchronous I/O multiplexing |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.B #include <sys/select.h> |
| 16 |
.P |
| 17 |
.BR typedef " /* .\|.\|.\& */ " fd_set; |
| 18 |
.P |
| 19 |
.BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds , |
| 20 |
.BI " fd_set *_Nullable restrict " writefds , |
| 21 |
.BI " fd_set *_Nullable restrict " exceptfds , |
| 22 |
.BI " struct timeval *_Nullable restrict " timeout ); |
| 23 |
.P |
| 24 |
.BI "void FD_CLR(int " fd ", fd_set *" set ); |
| 25 |
.BI "int FD_ISSET(int " fd ", const fd_set *" set ); |
| 26 |
.BI "void FD_SET(int " fd ", fd_set *" set ); |
| 27 |
.BI "void FD_ZERO(fd_set *" set ); |
| 28 |
.P |
| 29 |
.BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds , |
| 30 |
.BI " fd_set *_Nullable restrict " writefds , |
| 31 |
.BI " fd_set *_Nullable restrict " exceptfds , |
| 32 |
.BI " const struct timespec *_Nullable restrict " timeout , |
| 33 |
.BI " const sigset_t *_Nullable restrict " sigmask ); |
| 34 |
.fi |
| 35 |
.P |
| 36 |
.RS -4 |
| 37 |
Feature Test Macro Requirements for glibc (see |
| 38 |
.BR feature_test_macros (7)): |
| 39 |
.RE |
| 40 |
.P |
| 41 |
.BR pselect (): |
| 42 |
.nf |
| 43 |
_POSIX_C_SOURCE >= 200112L |
| 44 |
.fi |
| 45 |
.SH DESCRIPTION |
| 46 |
.BR "WARNING" : |
| 47 |
.BR select () |
| 48 |
can monitor only file descriptors numbers that are less than |
| 49 |
.B FD_SETSIZE |
| 50 |
(1024)\[em]an unreasonably low limit for many modern applications\[em]and |
| 51 |
this limitation will not change. |
| 52 |
All modern applications should instead use |
| 53 |
.BR poll (2) |
| 54 |
or |
| 55 |
.BR epoll (7), |
| 56 |
which do not suffer this limitation. |
| 57 |
.P |
| 58 |
.BR select () |
| 59 |
allows a program to monitor multiple file descriptors, |
| 60 |
waiting until one or more of the file descriptors become "ready" |
| 61 |
for some class of I/O operation (e.g., input possible). |
| 62 |
A file descriptor is considered ready if it is possible to |
| 63 |
perform a corresponding I/O operation (e.g., |
| 64 |
.BR read (2), |
| 65 |
or a sufficiently small |
| 66 |
.BR write (2)) |
| 67 |
without blocking. |
| 68 |
.\" |
| 69 |
.SS fd_set |
| 70 |
A structure type that can represent a set of file descriptors. |
| 71 |
According to POSIX, |
| 72 |
the maximum number of file descriptors in an |
| 73 |
.I fd_set |
| 74 |
structure is the value of the macro |
| 75 |
.BR FD_SETSIZE . |
| 76 |
.\" |
| 77 |
.SS File descriptor sets |
| 78 |
The principal arguments of |
| 79 |
.BR select () |
| 80 |
are three "sets" of file descriptors (declared with the type |
| 81 |
.IR fd_set ), |
| 82 |
which allow the caller to wait for three classes of events |
| 83 |
on the specified set of file descriptors. |
| 84 |
Each of the |
| 85 |
.I fd_set |
| 86 |
arguments may be specified as NULL if no file descriptors are |
| 87 |
to be watched for the corresponding class of events. |
| 88 |
.P |
| 89 |
.BR "Note well" : |
| 90 |
Upon return, each of the file descriptor sets is modified in place |
| 91 |
to indicate which file descriptors are currently "ready". |
| 92 |
Thus, if using |
| 93 |
.BR select () |
| 94 |
within a loop, the sets |
| 95 |
.I must be reinitialized |
| 96 |
before each call. |
| 97 |
.P |
| 98 |
The contents of a file descriptor set can be manipulated |
| 99 |
using the following macros: |
| 100 |
.TP |
| 101 |
.BR FD_ZERO () |
| 102 |
This macro clears (removes all file descriptors from) |
| 103 |
.IR set . |
| 104 |
It should be employed as the first step in initializing a file descriptor set. |
| 105 |
.TP |
| 106 |
.BR FD_SET () |
| 107 |
This macro adds the file descriptor |
| 108 |
.I fd |
| 109 |
to |
| 110 |
.IR set . |
| 111 |
Adding a file descriptor that is already present in the set is a no-op, |
| 112 |
and does not produce an error. |
| 113 |
.TP |
| 114 |
.BR FD_CLR () |
| 115 |
This macro removes the file descriptor |
| 116 |
.I fd |
| 117 |
from |
| 118 |
.IR set . |
| 119 |
Removing a file descriptor that is not present in the set is a no-op, |
| 120 |
and does not produce an error. |
| 121 |
.TP |
| 122 |
.BR FD_ISSET () |
| 123 |
.BR select () |
| 124 |
modifies the contents of the sets according to the rules |
| 125 |
described below. |
| 126 |
After calling |
| 127 |
.BR select (), |
| 128 |
the |
| 129 |
.BR FD_ISSET () |
| 130 |
macro |
| 131 |
can be used to test if a file descriptor is still present in a set. |
| 132 |
.BR FD_ISSET () |
| 133 |
returns nonzero if the file descriptor |
| 134 |
.I fd |
| 135 |
is present in |
| 136 |
.IR set , |
| 137 |
and zero if it is not. |
| 138 |
.\" |
| 139 |
.SS Arguments |
| 140 |
The arguments of |
| 141 |
.BR select () |
| 142 |
are as follows: |
| 143 |
.TP |
| 144 |
.I readfds |
| 145 |
The file descriptors in this set are watched to see if they are |
| 146 |
ready for reading. |
| 147 |
A file descriptor is ready for reading if a read operation will not block; |
| 148 |
in particular, |
| 149 |
a file descriptor is also ready on end-of-file. |
| 150 |
.IP |
| 151 |
After |
| 152 |
.BR select () |
| 153 |
has returned, |
| 154 |
.I readfds |
| 155 |
will be |
| 156 |
cleared of all file descriptors except for those that are ready for reading. |
| 157 |
.TP |
| 158 |
.I writefds |
| 159 |
The file descriptors in this set are watched to see if they are |
| 160 |
ready for writing. |
| 161 |
A file descriptor is ready for writing if a write operation will not block. |
| 162 |
However, even if a file descriptor indicates as writable, |
| 163 |
a large write may still block. |
| 164 |
.IP |
| 165 |
After |
| 166 |
.BR select () |
| 167 |
has returned, |
| 168 |
.I writefds |
| 169 |
will be |
| 170 |
cleared of all file descriptors except for those that are ready for writing. |
| 171 |
.TP |
| 172 |
.I exceptfds |
| 173 |
The file descriptors in this set are watched for "exceptional conditions". |
| 174 |
For examples of some exceptional conditions, see the discussion of |
| 175 |
.B POLLPRI |
| 176 |
in |
| 177 |
.BR poll (2). |
| 178 |
.IP |
| 179 |
After |
| 180 |
.BR select () |
| 181 |
has returned, |
| 182 |
.I exceptfds |
| 183 |
will be cleared of all file descriptors except for those |
| 184 |
for which an exceptional condition has occurred. |
| 185 |
.TP |
| 186 |
.I nfds |
| 187 |
This argument should be set to the highest-numbered file descriptor in any |
| 188 |
of the three sets, plus 1. |
| 189 |
The indicated file descriptors in each set are checked, up to this limit |
| 190 |
(but see BUGS). |
| 191 |
.TP |
| 192 |
.I timeout |
| 193 |
The |
| 194 |
.I timeout |
| 195 |
argument is a |
| 196 |
.I timeval |
| 197 |
structure (shown below) that specifies the interval that |
| 198 |
.BR select () |
| 199 |
should block waiting for a file descriptor to become ready. |
| 200 |
The call will block until either: |
| 201 |
.RS |
| 202 |
.IP \[bu] 3 |
| 203 |
a file descriptor becomes ready; |
| 204 |
.IP \[bu] |
| 205 |
the call is interrupted by a signal handler; |
| 206 |
or |
| 207 |
.IP \[bu] |
| 208 |
the timeout expires. |
| 209 |
.RE |
| 210 |
.IP |
| 211 |
Note that the |
| 212 |
.I timeout |
| 213 |
interval will be rounded up to the system clock granularity, |
| 214 |
and kernel scheduling delays mean that the blocking interval |
| 215 |
may overrun by a small amount. |
| 216 |
.IP |
| 217 |
If both fields of the |
| 218 |
.I timeval |
| 219 |
structure are zero, then |
| 220 |
.BR select () |
| 221 |
returns immediately. |
| 222 |
(This is useful for polling.) |
| 223 |
.IP |
| 224 |
If |
| 225 |
.I timeout |
| 226 |
is specified as NULL, |
| 227 |
.BR select () |
| 228 |
blocks indefinitely waiting for a file descriptor to become ready. |
| 229 |
.\" |
| 230 |
.SS pselect() |
| 231 |
The |
| 232 |
.BR pselect () |
| 233 |
system call allows an application to safely wait until either |
| 234 |
a file descriptor becomes ready or until a signal is caught. |
| 235 |
.P |
| 236 |
The operation of |
| 237 |
.BR select () |
| 238 |
and |
| 239 |
.BR pselect () |
| 240 |
is identical, other than these three differences: |
| 241 |
.IP \[bu] 3 |
| 242 |
.BR select () |
| 243 |
uses a timeout that is a |
| 244 |
.I struct timeval |
| 245 |
(with seconds and microseconds), while |
| 246 |
.BR pselect () |
| 247 |
uses a |
| 248 |
.I struct timespec |
| 249 |
(with seconds and nanoseconds). |
| 250 |
.IP \[bu] |
| 251 |
.BR select () |
| 252 |
may update the |
| 253 |
.I timeout |
| 254 |
argument to indicate how much time was left. |
| 255 |
.BR pselect () |
| 256 |
does not change this argument. |
| 257 |
.IP \[bu] |
| 258 |
.BR select () |
| 259 |
has no |
| 260 |
.I sigmask |
| 261 |
argument, and behaves as |
| 262 |
.BR pselect () |
| 263 |
called with NULL |
| 264 |
.IR sigmask . |
| 265 |
.P |
| 266 |
.I sigmask |
| 267 |
is a pointer to a signal mask (see |
| 268 |
.BR sigprocmask (2)); |
| 269 |
if it is not NULL, then |
| 270 |
.BR pselect () |
| 271 |
first replaces the current signal mask by the one pointed to by |
| 272 |
.IR sigmask , |
| 273 |
then does the "select" function, and then restores the original |
| 274 |
signal mask. |
| 275 |
(If |
| 276 |
.I sigmask |
| 277 |
is NULL, |
| 278 |
the signal mask is not modified during the |
| 279 |
.BR pselect () |
| 280 |
call.) |
| 281 |
.P |
| 282 |
Other than the difference in the precision of the |
| 283 |
.I timeout |
| 284 |
argument, the following |
| 285 |
.BR pselect () |
| 286 |
call: |
| 287 |
.P |
| 288 |
.in +4n |
| 289 |
.EX |
| 290 |
ready = pselect(nfds, &readfds, &writefds, &exceptfds, |
| 291 |
timeout, &sigmask); |
| 292 |
.EE |
| 293 |
.in |
| 294 |
.P |
| 295 |
is equivalent to |
| 296 |
.I atomically |
| 297 |
executing the following calls: |
| 298 |
.P |
| 299 |
.in +4n |
| 300 |
.EX |
| 301 |
sigset_t origmask; |
| 302 |
\& |
| 303 |
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); |
| 304 |
ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); |
| 305 |
pthread_sigmask(SIG_SETMASK, &origmask, NULL); |
| 306 |
.EE |
| 307 |
.in |
| 308 |
.P |
| 309 |
The reason that |
| 310 |
.BR pselect () |
| 311 |
is needed is that if one wants to wait for either a signal |
| 312 |
or for a file descriptor to become ready, then |
| 313 |
an atomic test is needed to prevent race conditions. |
| 314 |
(Suppose the signal handler sets a global flag and |
| 315 |
returns. |
| 316 |
Then a test of this global flag followed by a call of |
| 317 |
.BR select () |
| 318 |
could hang indefinitely if the signal arrived just after the test |
| 319 |
but just before the call. |
| 320 |
By contrast, |
| 321 |
.BR pselect () |
| 322 |
allows one to first block signals, handle the signals that have come in, |
| 323 |
then call |
| 324 |
.BR pselect () |
| 325 |
with the desired |
| 326 |
.IR sigmask , |
| 327 |
avoiding the race.) |
| 328 |
.SS The timeout |
| 329 |
The |
| 330 |
.I timeout |
| 331 |
argument for |
| 332 |
.BR select () |
| 333 |
is a structure of the following type: |
| 334 |
.P |
| 335 |
.in +4n |
| 336 |
.EX |
| 337 |
struct timeval { |
| 338 |
time_t tv_sec; /* seconds */ |
| 339 |
suseconds_t tv_usec; /* microseconds */ |
| 340 |
}; |
| 341 |
.EE |
| 342 |
.in |
| 343 |
.P |
| 344 |
The corresponding argument for |
| 345 |
.BR pselect () |
| 346 |
is a |
| 347 |
.BR timespec (3) |
| 348 |
structure. |
| 349 |
.P |
| 350 |
On Linux, |
| 351 |
.BR select () |
| 352 |
modifies |
| 353 |
.I timeout |
| 354 |
to reflect the amount of time not slept; |
| 355 |
most other implementations |
| 356 |
do not do this. |
| 357 |
(POSIX.1 permits either behavior.) |
| 358 |
This causes problems both when Linux code which reads |
| 359 |
.I timeout |
| 360 |
is ported to other operating systems, and when code is ported to Linux |
| 361 |
that reuses a |
| 362 |
.I struct\ timeval |
| 363 |
for multiple |
| 364 |
.BR select ()s |
| 365 |
in a loop without reinitializing it. |
| 366 |
Consider |
| 367 |
.I timeout |
| 368 |
to be undefined after |
| 369 |
.BR select () |
| 370 |
returns. |
| 371 |
.\" .P - it is rumored that: |
| 372 |
.\" On BSD, when a timeout occurs, the file descriptor bits are not changed. |
| 373 |
.\" - it is certainly true that: |
| 374 |
.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. |
| 375 |
.SH RETURN VALUE |
| 376 |
On success, |
| 377 |
.BR select () |
| 378 |
and |
| 379 |
.BR pselect () |
| 380 |
return the number of file descriptors contained in the three returned |
| 381 |
descriptor sets (that is, the total number of bits that are set in |
| 382 |
.IR readfds , |
| 383 |
.IR writefds , |
| 384 |
.IR exceptfds ). |
| 385 |
The return value may be zero if the timeout expired before any |
| 386 |
file descriptors became ready. |
| 387 |
.P |
| 388 |
On error, \-1 is returned, and |
| 389 |
.I errno |
| 390 |
is set to indicate the error; |
| 391 |
the file descriptor sets are unmodified, |
| 392 |
and |
| 393 |
.I timeout |
| 394 |
becomes undefined. |
| 395 |
.SH ERRORS |
| 396 |
.TP |
| 397 |
.B EBADF |
| 398 |
An invalid file descriptor was given in one of the sets. |
| 399 |
(Perhaps a file descriptor that was already closed, |
| 400 |
or one on which an error has occurred.) |
| 401 |
However, see BUGS. |
| 402 |
.TP |
| 403 |
.B EINTR |
| 404 |
A signal was caught; |
| 405 |
see |
| 406 |
.BR signal (7). |
| 407 |
.TP |
| 408 |
.B EINVAL |
| 409 |
.I nfds |
| 410 |
is negative or exceeds the |
| 411 |
.B RLIMIT_NOFILE |
| 412 |
resource limit (see |
| 413 |
.BR getrlimit (2)). |
| 414 |
.TP |
| 415 |
.B EINVAL |
| 416 |
The value contained within |
| 417 |
.I timeout |
| 418 |
is invalid. |
| 419 |
.TP |
| 420 |
.B ENOMEM |
| 421 |
Unable to allocate memory for internal tables. |
| 422 |
.SH VERSIONS |
| 423 |
On some other UNIX systems, |
| 424 |
.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett |
| 425 |
.BR select () |
| 426 |
can fail with the error |
| 427 |
.B EAGAIN |
| 428 |
if the system fails to allocate kernel-internal resources, rather than |
| 429 |
.B ENOMEM |
| 430 |
as Linux does. |
| 431 |
POSIX specifies this error for |
| 432 |
.BR poll (2), |
| 433 |
but not for |
| 434 |
.BR select (). |
| 435 |
Portable programs may wish to check for |
| 436 |
.B EAGAIN |
| 437 |
and loop, just as with |
| 438 |
.BR EINTR . |
| 439 |
.SH STANDARDS |
| 440 |
POSIX.1-2024. |
| 441 |
.SH HISTORY |
| 442 |
.TP |
| 443 |
.BR select () |
| 444 |
POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD). |
| 445 |
.IP |
| 446 |
Generally portable to/from |
| 447 |
non-BSD systems supporting clones of the BSD socket layer (including |
| 448 |
System\ V variants). |
| 449 |
However, note that the System\ V variant typically |
| 450 |
sets the timeout variable before returning, but the BSD variant does not. |
| 451 |
.TP |
| 452 |
.BR pselect () |
| 453 |
Linux 2.6.16. |
| 454 |
POSIX.1g, POSIX.1-2001. |
| 455 |
.IP |
| 456 |
Prior to this, |
| 457 |
it was emulated in glibc (but see BUGS). |
| 458 |
.TP |
| 459 |
.B fd_set |
| 460 |
POSIX.1-2001. |
| 461 |
.SH NOTES |
| 462 |
The following header also provides the |
| 463 |
.I fd_set |
| 464 |
type: |
| 465 |
.IR <sys/time.h> . |
| 466 |
.P |
| 467 |
An |
| 468 |
.I fd_set |
| 469 |
is a fixed size buffer. |
| 470 |
Executing |
| 471 |
.BR FD_CLR () |
| 472 |
or |
| 473 |
.BR FD_SET () |
| 474 |
with a value of |
| 475 |
.I fd |
| 476 |
that is negative or is equal to or larger than |
| 477 |
.B FD_SETSIZE |
| 478 |
will result |
| 479 |
in undefined behavior. |
| 480 |
Moreover, POSIX requires |
| 481 |
.I fd |
| 482 |
to be a valid file descriptor. |
| 483 |
.P |
| 484 |
The operation of |
| 485 |
.BR select () |
| 486 |
and |
| 487 |
.BR pselect () |
| 488 |
is not affected by the |
| 489 |
.B O_NONBLOCK |
| 490 |
flag. |
| 491 |
.\" |
| 492 |
.SS The self-pipe trick |
| 493 |
On systems that lack |
| 494 |
.BR pselect (), |
| 495 |
reliable (and more portable) signal trapping can be achieved |
| 496 |
using the self-pipe trick. |
| 497 |
In this technique, |
| 498 |
a signal handler writes a byte to a pipe whose other end |
| 499 |
is monitored by |
| 500 |
.BR select () |
| 501 |
in the main program. |
| 502 |
(To avoid possibly blocking when writing to a pipe that may be full |
| 503 |
or reading from a pipe that may be empty, |
| 504 |
nonblocking I/O is used when reading from and writing to the pipe.) |
| 505 |
.\" |
| 506 |
.SS Emulating usleep(3) |
| 507 |
Before the advent of |
| 508 |
.BR usleep (3), |
| 509 |
some code employed a call to |
| 510 |
.BR select () |
| 511 |
with all three sets empty, |
| 512 |
.I nfds |
| 513 |
zero, and a non-NULL |
| 514 |
.I timeout |
| 515 |
as a fairly portable way to sleep with subsecond precision. |
| 516 |
.\" |
| 517 |
.SS Correspondence between select() and poll() notifications |
| 518 |
Within the Linux kernel source, |
| 519 |
.\" fs/select.c |
| 520 |
we find the following definitions which show the correspondence |
| 521 |
between the readable, writable, and exceptional condition notifications of |
| 522 |
.BR select () |
| 523 |
and the event notifications provided by |
| 524 |
.BR poll (2) |
| 525 |
and |
| 526 |
.BR epoll (7): |
| 527 |
.P |
| 528 |
.in +4n |
| 529 |
.EX |
| 530 |
#define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | |
| 531 |
EPOLLHUP | EPOLLERR) |
| 532 |
/* Ready for reading */ |
| 533 |
#define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT | |
| 534 |
EPOLLERR) |
| 535 |
/* Ready for writing */ |
| 536 |
#define POLLEX_SET (EPOLLPRI) |
| 537 |
/* Exceptional condition */ |
| 538 |
.EE |
| 539 |
.in |
| 540 |
.\" |
| 541 |
.SS Multithreaded applications |
| 542 |
If a file descriptor being monitored by |
| 543 |
.BR select () |
| 544 |
is closed in another thread, the result is unspecified. |
| 545 |
On some UNIX systems, |
| 546 |
.BR select () |
| 547 |
unblocks and returns, with an indication that the file descriptor is ready |
| 548 |
(a subsequent I/O operation will likely fail with an error, |
| 549 |
unless another process reopens the file descriptor between the time |
| 550 |
.BR select () |
| 551 |
returned and the I/O operation is performed). |
| 552 |
On Linux (and some other systems), |
| 553 |
closing the file descriptor in another thread has no effect on |
| 554 |
.BR select (). |
| 555 |
In summary, any application that relies on a particular behavior |
| 556 |
in this scenario must be considered buggy. |
| 557 |
.\" |
| 558 |
.SS C library/kernel differences |
| 559 |
The Linux kernel allows file descriptor sets of arbitrary size, |
| 560 |
determining the length of the sets to be checked from the value of |
| 561 |
.IR nfds . |
| 562 |
However, in the glibc implementation, the |
| 563 |
.I fd_set |
| 564 |
type is fixed in size. |
| 565 |
See also BUGS. |
| 566 |
.P |
| 567 |
The |
| 568 |
.BR pselect () |
| 569 |
interface described in this page is implemented by glibc. |
| 570 |
The underlying Linux system call is named |
| 571 |
.BR pselect6 (). |
| 572 |
This system call has somewhat different behavior from the glibc |
| 573 |
wrapper function. |
| 574 |
.P |
| 575 |
The Linux |
| 576 |
.BR pselect6 () |
| 577 |
system call modifies its |
| 578 |
.I timeout |
| 579 |
argument. |
| 580 |
However, the glibc wrapper function hides this behavior |
| 581 |
by using a local variable for the timeout argument that |
| 582 |
is passed to the system call. |
| 583 |
Thus, the glibc |
| 584 |
.BR pselect () |
| 585 |
function does not modify its |
| 586 |
.I timeout |
| 587 |
argument; |
| 588 |
this is the behavior required by POSIX.1-2001. |
| 589 |
.P |
| 590 |
The final argument of the |
| 591 |
.BR pselect6 () |
| 592 |
system call is not a |
| 593 |
.I "sigset_t\ *" |
| 594 |
pointer, but is instead a structure of the form: |
| 595 |
.P |
| 596 |
.in +4n |
| 597 |
.EX |
| 598 |
struct { |
| 599 |
const kernel_sigset_t *ss; /* Pointer to signal set */ |
| 600 |
size_t ss_len; /* Size (in bytes) of object |
| 601 |
pointed to by \[aq]ss\[aq] */ |
| 602 |
}; |
| 603 |
.EE |
| 604 |
.in |
| 605 |
.P |
| 606 |
This allows the system call to obtain both |
| 607 |
a pointer to the signal set and its size, |
| 608 |
while allowing for the fact that most architectures |
| 609 |
support a maximum of 6 arguments to a system call. |
| 610 |
See |
| 611 |
.BR sigprocmask (2) |
| 612 |
for a discussion of the difference between the kernel and libc |
| 613 |
notion of the signal set. |
| 614 |
.\" |
| 615 |
.SS Historical glibc details |
| 616 |
glibc 2.0 provided an incorrect version of |
| 617 |
.BR pselect () |
| 618 |
that did not take a |
| 619 |
.I sigmask |
| 620 |
argument. |
| 621 |
.P |
| 622 |
From glibc 2.1 to glibc 2.2.1, |
| 623 |
one must define |
| 624 |
.B _GNU_SOURCE |
| 625 |
in order to obtain the declaration of |
| 626 |
.BR pselect () |
| 627 |
from |
| 628 |
.IR <sys/select.h> . |
| 629 |
.SH BUGS |
| 630 |
POSIX allows an implementation to define an upper limit, |
| 631 |
advertised via the constant |
| 632 |
.BR FD_SETSIZE , |
| 633 |
on the range of file descriptors that can be specified |
| 634 |
in a file descriptor set. |
| 635 |
The Linux kernel imposes no fixed limit, but the glibc implementation makes |
| 636 |
.I fd_set |
| 637 |
a fixed-size type, with |
| 638 |
.B FD_SETSIZE |
| 639 |
defined as 1024, and the |
| 640 |
.BR FD_* () |
| 641 |
macros operating according to that limit. |
| 642 |
To monitor file descriptors greater than 1023, use |
| 643 |
.BR poll (2) |
| 644 |
or |
| 645 |
.BR epoll (7) |
| 646 |
instead. |
| 647 |
.P |
| 648 |
The implementation of the |
| 649 |
.I fd_set |
| 650 |
arguments as value-result arguments is a design error that is avoided in |
| 651 |
.BR poll (2) |
| 652 |
and |
| 653 |
.BR epoll (7). |
| 654 |
.P |
| 655 |
According to POSIX, |
| 656 |
.BR select () |
| 657 |
should check all specified file descriptors in the three file descriptor sets, |
| 658 |
up to the limit |
| 659 |
.IR nfds\-1 . |
| 660 |
However, the current implementation ignores any file descriptor in |
| 661 |
these sets that is greater than the maximum file descriptor number |
| 662 |
that the process currently has open. |
| 663 |
According to POSIX, any such file descriptor that is specified in one |
| 664 |
of the sets should result in the error |
| 665 |
.BR EBADF . |
| 666 |
.P |
| 667 |
Starting with glibc 2.1, glibc provided an emulation of |
| 668 |
.BR pselect () |
| 669 |
that was implemented using |
| 670 |
.BR sigprocmask (2) |
| 671 |
and |
| 672 |
.BR select (). |
| 673 |
This implementation remained vulnerable to the very race condition that |
| 674 |
.BR pselect () |
| 675 |
was designed to prevent. |
| 676 |
Modern versions of glibc use the (race-free) |
| 677 |
.BR pselect () |
| 678 |
system call on kernels where it is provided. |
| 679 |
.P |
| 680 |
On Linux, |
| 681 |
.BR select () |
| 682 |
may report a socket file descriptor as "ready for reading", while |
| 683 |
nevertheless a subsequent read blocks. |
| 684 |
This could for example |
| 685 |
happen when data has arrived but upon examination has the wrong |
| 686 |
checksum and is discarded. |
| 687 |
There may be other circumstances |
| 688 |
in which a file descriptor is spuriously reported as ready. |
| 689 |
.\" Stevens discusses a case where accept can block after select |
| 690 |
.\" returns successfully because of an intervening RST from the client. |
| 691 |
Thus it may be safer to use |
| 692 |
.B O_NONBLOCK |
| 693 |
on sockets that should not block. |
| 694 |
.\" Maybe the kernel should have returned EIO in such a situation? |
| 695 |
.P |
| 696 |
On Linux, |
| 697 |
.BR select () |
| 698 |
also modifies |
| 699 |
.I timeout |
| 700 |
if the call is interrupted by a signal handler (i.e., the |
| 701 |
.B EINTR |
| 702 |
error return). |
| 703 |
This is not permitted by POSIX.1. |
| 704 |
The Linux |
| 705 |
.BR pselect () |
| 706 |
system call has the same behavior, |
| 707 |
but the glibc wrapper hides this behavior by internally copying the |
| 708 |
.I timeout |
| 709 |
to a local variable and passing that variable to the system call. |
| 710 |
.SH EXAMPLES |
| 711 |
.\" SRC BEGIN (select.c) |
| 712 |
.EX |
| 713 |
#include <stdio.h> |
| 714 |
#include <stdlib.h> |
| 715 |
#include <sys/select.h> |
| 716 |
#include <sys/time.h> |
| 717 |
\& |
| 718 |
int |
| 719 |
main(void) |
| 720 |
{ |
| 721 |
int retval; |
| 722 |
fd_set rfds; |
| 723 |
struct timeval tv; |
| 724 |
\& |
| 725 |
/* Watch stdin (fd 0) to see when it has input. */ |
| 726 |
\& |
| 727 |
FD_ZERO(&rfds); |
| 728 |
FD_SET(0, &rfds); |
| 729 |
\& |
| 730 |
/* Wait up to five seconds. */ |
| 731 |
\& |
| 732 |
tv.tv_sec = 5; |
| 733 |
tv.tv_usec = 0; |
| 734 |
\& |
| 735 |
retval = select(1, &rfds, NULL, NULL, &tv); |
| 736 |
/* Don\[aq]t rely on the value of tv now! */ |
| 737 |
\& |
| 738 |
if (retval == \-1) |
| 739 |
perror("select()"); |
| 740 |
else if (retval) |
| 741 |
printf("Data is available now.\[rs]n"); |
| 742 |
/* FD_ISSET(0, &rfds) will be true. */ |
| 743 |
else |
| 744 |
printf("No data within five seconds.\[rs]n"); |
| 745 |
\& |
| 746 |
exit(EXIT_SUCCESS); |
| 747 |
} |
| 748 |
.EE |
| 749 |
.\" SRC END |
| 750 |
.SH SEE ALSO |
| 751 |
.BR accept (2), |
| 752 |
.BR connect (2), |
| 753 |
.BR poll (2), |
| 754 |
.BR read (2), |
| 755 |
.BR recv (2), |
| 756 |
.BR restart_syscall (2), |
| 757 |
.BR send (2), |
| 758 |
.BR sigprocmask (2), |
| 759 |
.BR write (2), |
| 760 |
.BR timespec (3), |
| 761 |
.BR epoll (7), |
| 762 |
.BR time (7) |
| 763 |
.P |
| 764 |
For a tutorial with discussion and examples, see |
| 765 |
.BR select_tut (2). |