1 .\" This manpage is copyright (C) 2001 Paul Sheer.
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" very minor changes, aeb
27 .\" Modified 5 June 2002, Michael Kerrisk <mtk.manpages@gmail.com>
28 .\" 2006-05-13, mtk, removed much material that is redundant with select.2
29 .\" various other changes
30 .\" 2008-01-26, mtk, substantial changes and rewrites
32 .TH SELECT_TUT 2 2019-03-06 "Linux" "Linux Programmer's Manual"
34 select, pselect \- synchronous I/O multiplexing
44 system calls are used to efficiently monitor multiple file descriptors,
45 to see if any of them is, or becomes, "ready";
46 that is, to see whether I/O becomes possible,
47 or an "exceptional condition" has occurred on any of the file descriptors.
49 This page provides background and tutorial information
50 on the use of these system calls.
51 For details of the arguments and semantics of
59 .SS Combining signal and data events
61 is useful if you are waiting for a signal as well as
62 for file descriptor(s) to become ready for I/O.
63 Programs that receive signals
64 normally use the signal handler only to raise a global flag.
65 The global flag will indicate that the event must be processed
66 in the main loop of the program.
67 A signal will cause the
71 call to return with \fIerrno\fP set to \fBEINTR\fP.
72 This behavior is essential so that signals can be processed
73 in the main loop of the program, otherwise
75 would block indefinitely.
78 in the main loop will be a conditional to check the global flag.
80 what if a signal arrives after the conditional, but before the
85 would block indefinitely, even though an event is actually pending.
86 This race condition is solved by the
89 This call can be used to set the signal mask to a set of signals
90 that are to be received only within the
93 For instance, let us say that the event in question
94 was the exit of a child process.
95 Before the start of the main loop, we
96 would block \fBSIGCHLD\fP using
102 by using an empty signal mask.
103 Our program would look like:
106 static volatile sig_atomic_t got_SIGCHLD = 0;
109 child_sig_handler(int sig)
115 main(int argc, char *argv[])
117 sigset_t sigmask, empty_mask;
119 fd_set readfds, writefds, exceptfds;
122 sigemptyset(&sigmask);
123 sigaddset(&sigmask, SIGCHLD);
124 if (sigprocmask(SIG_BLOCK, &sigmask, NULL) == \-1) {
125 perror("sigprocmask");
130 sa.sa_handler = child_sig_handler;
131 sigemptyset(&sa.sa_mask);
132 if (sigaction(SIGCHLD, &sa, NULL) == \-1) {
137 sigemptyset(&empty_mask);
139 for (;;) { /* main loop */
140 /* Initialize readfds, writefds, and exceptfds
141 before the pselect() call. (Code omitted.) */
143 r = pselect(nfds, &readfds, &writefds, &exceptfds,
145 if (r == \-1 && errno != EINTR) {
152 /* Handle signalled event here; e.g., wait() for all
153 terminated children. (Code omitted.) */
156 /* main body of program */
161 So what is the point of
163 Can't I just read and write to my file descriptors whenever I want?
167 multiple descriptors at the same time and properly puts the process to
168 sleep if there is no activity.
169 UNIX programmers often find
170 themselves in a position where they have to handle I/O from more than one
171 file descriptor where the data flow may be intermittent.
172 If you were to merely create a sequence of
177 find that one of your calls may block waiting for data from/to a file
178 descriptor, while another file descriptor is unused though ready for I/O.
180 efficiently copes with this situation.
182 Many people who try to use
184 come across behavior that is
185 difficult to understand and produces nonportable or borderline results.
186 For instance, the above program is carefully written not to
187 block at any point, even though it does not set its file descriptors to
189 It is easy to introduce
190 subtle errors that will remove the advantage of using
192 so here is a list of essentials to watch for when using
196 You should always try to use
200 should have nothing to do if there is no data available.
202 depends on timeouts is not usually portable and is difficult to debug.
205 The value \fInfds\fP must be properly calculated for efficiency as
209 No file descriptor must be added to any set if you do not intend
210 to check its result after the
212 call, and respond appropriately.
218 returns, all file descriptors in all sets
219 should be checked to see if they are ready.
228 do \fInot\fP necessarily read/write the full amount of data
229 that you have requested.
230 If they do read/write the full amount, it's
231 because you have a low traffic load and a fast stream.
232 This is not always going to be the case.
233 You should cope with the case of your
234 functions managing to send or receive only a single byte.
237 Never read/write only in single bytes at a time unless you are really
238 sure that you have a small amount of data to process.
240 inefficient not to read/write as much data as you can buffer each time.
241 The buffers in the example below are 1024 bytes although they could
242 easily be made larger.
252 can fail with the error
262 set to \fBEAGAIN\fP (\fBEWOULDBLOCK\fP).
263 These results must be properly managed (not done properly above).
264 If your program is not going to receive any signals, then
265 it is unlikely you will get \fBEINTR\fP.
266 If your program does not set nonblocking I/O,
267 you will not get \fBEAGAIN\fP.
268 .\" Nonetheless, you should still cope with these errors for completeness.
277 with a buffer length of zero.
286 fail with errors other than those listed in \fB7.\fP,
287 or one of the input functions returns 0, indicating end of file,
288 then you should \fInot\fP pass that file descriptor to
291 In the example below,
292 I close the file descriptor immediately, and then set it to \-1
293 to prevent it being included in a set.
296 The timeout value must be initialized with each new call to
298 since some operating systems modify the structure.
300 however does not modify its timeout structure.
305 modifies its file descriptor sets,
306 if the call is being used in a loop,
307 then the sets must be reinitialized before each call.
308 .\" "I have heard" does not fill me with confidence, and doesn't
309 .\" belong in a man page, so I've commented this point out.
312 .\" I have heard that the Windows socket layer does not cope with OOB data
314 .\" It also does not cope with
316 .\" calls when no file descriptors are set at all.
317 .\" Having no file descriptors set is a useful
318 .\" way to sleep the process with subsecond precision by using the timeout.
319 .\" (See further on.)
325 all operating systems that support sockets also support
329 many problems in a portable and efficient way that naive programmers try
330 to solve in a more complicated manner using
331 threads, forking, IPCs, signals, memory sharing, and so on.
335 system call has the same functionality as
337 and is somewhat more efficient when monitoring sparse
338 file descriptor sets.
339 It is nowadays widely available, but historically was less portable than
344 API provides an interface that is more efficient than
348 when monitoring large numbers of file descriptors.
350 Here is an example that better demonstrates the true utility of
352 The listing below is a TCP forwarding program that forwards
353 from one TCP port to another.
359 #include <sys/select.h>
362 #include <sys/socket.h>
363 #include <netinet/in.h>
364 #include <arpa/inet.h>
367 static int forward_port;
370 #define max(x,y) ((x) > (y) ? (x) : (y))
373 listen_socket(int listen_port)
375 struct sockaddr_in addr;
379 lfd = socket(AF_INET, SOCK_STREAM, 0);
386 if (setsockopt(lfd, SOL_SOCKET, SO_REUSEADDR,
387 &yes, sizeof(yes)) == \-1) {
388 perror("setsockopt");
393 memset(&addr, 0, sizeof(addr));
394 addr.sin_port = htons(listen_port);
395 addr.sin_family = AF_INET;
396 if (bind(lfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
402 printf("accepting connections on port %d\en", listen_port);
408 connect_socket(int connect_port, char *address)
410 struct sockaddr_in addr;
413 cfd = socket(AF_INET, SOCK_STREAM, 0);
419 memset(&addr, 0, sizeof(addr));
420 addr.sin_port = htons(connect_port);
421 addr.sin_family = AF_INET;
423 if (!inet_aton(address, (struct in_addr *) &addr.sin_addr.s_addr)) {
424 fprintf(stderr, "inet_aton(): bad IP address format\en");
429 if (connect(cfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) {
431 shutdown(cfd, SHUT_RDWR);
438 #define SHUT_FD1 do { \e
440 shutdown(fd1, SHUT_RDWR); \e
446 #define SHUT_FD2 do { \e
448 shutdown(fd2, SHUT_RDWR); \e
454 #define BUF_SIZE 1024
457 main(int argc, char *argv[])
460 int fd1 = \-1, fd2 = \-1;
461 char buf1[BUF_SIZE], buf2[BUF_SIZE];
462 int buf1_avail = 0, buf1_written = 0;
463 int buf2_avail = 0, buf2_written = 0;
466 fprintf(stderr, "Usage\en\etfwd <listen\-port> "
467 "<forward\-to\-port> <forward\-to\-ip\-address>\en");
471 signal(SIGPIPE, SIG_IGN);
473 forward_port = atoi(argv[2]);
475 h = listen_socket(atoi(argv[1]));
482 fd_set readfds, writefds, exceptfds;
490 if (fd1 > 0 && buf1_avail < BUF_SIZE)
491 FD_SET(fd1, &readfds);
492 /* Note: nfds is updated below, when fd1 is added to
494 if (fd2 > 0 && buf2_avail < BUF_SIZE)
495 FD_SET(fd2, &readfds);
497 if (fd1 > 0 && buf2_avail \- buf2_written > 0)
498 FD_SET(fd1, &writefds);
499 if (fd2 > 0 && buf1_avail \- buf1_written > 0)
500 FD_SET(fd2, &writefds);
503 FD_SET(fd1, &exceptfds);
504 nfds = max(nfds, fd1);
507 FD_SET(fd2, &exceptfds);
508 nfds = max(nfds, fd2);
511 ready = select(nfds + 1, &readfds, &writefds, &exceptfds, NULL);
513 if (ready == \-1 && errno == EINTR)
521 if (FD_ISSET(h, &readfds)) {
523 struct sockaddr_in client_addr;
526 addrlen = sizeof(client_addr);
527 memset(&client_addr, 0, addrlen);
528 fd = accept(h, (struct sockaddr *) &client_addr, &addrlen);
534 buf1_avail = buf1_written = 0;
535 buf2_avail = buf2_written = 0;
537 fd2 = connect_socket(forward_port, argv[3]);
541 printf("connect from %s\en",
542 inet_ntoa(client_addr.sin_addr));
544 /* Skip any events on the old, closed file
551 /* NB: read OOB data before normal reads */
553 if (fd1 > 0 && FD_ISSET(fd1, &exceptfds)) {
556 nbytes = recv(fd1, &c, 1, MSG_OOB);
560 send(fd2, &c, 1, MSG_OOB);
562 if (fd2 > 0 && FD_ISSET(fd2, &exceptfds)) {
565 nbytes = recv(fd2, &c, 1, MSG_OOB);
569 send(fd1, &c, 1, MSG_OOB);
571 if (fd1 > 0 && FD_ISSET(fd1, &readfds)) {
572 nbytes = read(fd1, buf1 + buf1_avail,
573 BUF_SIZE \- buf1_avail);
577 buf1_avail += nbytes;
579 if (fd2 > 0 && FD_ISSET(fd2, &readfds)) {
580 nbytes = read(fd2, buf2 + buf2_avail,
581 BUF_SIZE \- buf2_avail);
585 buf2_avail += nbytes;
587 if (fd1 > 0 && FD_ISSET(fd1, &writefds) && buf2_avail > 0) {
588 nbytes = write(fd1, buf2 + buf2_written,
589 buf2_avail \- buf2_written);
593 buf2_written += nbytes;
595 if (fd2 > 0 && FD_ISSET(fd2, &writefds) && buf1_avail > 0) {
596 nbytes = write(fd2, buf1 + buf1_written,
597 buf1_avail \- buf1_written);
601 buf1_written += nbytes;
604 /* Check if write data has caught read data */
606 if (buf1_written == buf1_avail)
607 buf1_written = buf1_avail = 0;
608 if (buf2_written == buf2_avail)
609 buf2_written = buf2_avail = 0;
611 /* One side has closed the connection, keep
612 writing to the other side until empty */
614 if (fd1 < 0 && buf1_avail \- buf1_written == 0)
616 if (fd2 < 0 && buf2_avail \- buf2_written == 0)
623 The above program properly forwards most kinds of TCP connections
624 including OOB signal data transmitted by \fBtelnet\fP servers.
625 It handles the tricky problem of having data flow in both directions
627 You might think it more efficient to use a
629 call and devote a thread to each stream.
630 This becomes more tricky than you might suspect.
631 Another idea is to set nonblocking I/O using
633 This also has its problems because you end up using
634 inefficient timeouts.
636 The program does not handle more than one simultaneous connection at a
637 time, although it could easily be extended to do this with a linked list
638 of buffers\(emone for each connection.
640 connections cause the current connection to be dropped.
653 .\" This man page was written by Paul Sheer.