| .\" Hey Emacs! This file is -*- nroff -*- source. |
| .\" |
| .\" This manpage is copyright (C) 1992 Drew Eckhardt, |
| .\" copyright (C) 1995 Michael Shields. |
| .\" |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" |
| .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com> |
| .\" Sun Feb 11 14:07:00 MET 1996 Martin Schulze <joey@linux.de> |
| .\" * layout slightly modified |
| .\" |
| .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb |
| .\" Modified Thu Feb 9 22:32:09 CET 2001 by bert hubert <ahu@ds9a.nl>, aeb |
| .\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard <ben@zork.net> |
| .\" 2005-03-11, mtk, modified pselect() text (it is now a system |
| .\" call in 2.6.16. |
| .\" |
| .TH SELECT 2 2008-07-14 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- |
| synchronous I/O multiplexing |
| .SH SYNOPSIS |
| .nf |
| /* According to POSIX.1-2001 */ |
| .br |
| .B #include <sys/select.h> |
| .sp |
| /* According to earlier standards */ |
| .br |
| .B #include <sys/time.h> |
| .br |
| .B #include <sys/types.h> |
| .br |
| .B #include <unistd.h> |
| .sp |
| .BI "int select(int " nfds ", fd_set *" readfds ", fd_set *" writefds , |
| .BI " fd_set *" exceptfds ", struct timeval *" timeout ); |
| .sp |
| .BI "void FD_CLR(int " fd ", fd_set *" set ); |
| .br |
| .BI "int FD_ISSET(int " fd ", fd_set *" set ); |
| .br |
| .BI "void FD_SET(int " fd ", fd_set *" set ); |
| .br |
| .BI "void FD_ZERO(fd_set *" set ); |
| .sp |
| .B #include <sys/select.h> |
| .sp |
| .BI "int pselect(int " nfds ", fd_set *" readfds ", fd_set *" writefds , |
| .BI " fd_set *" exceptfds ", const struct timespec *" timeout , |
| .BI " const sigset_t *" sigmask ); |
| .fi |
| .sp |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .sp |
| .BR pselect (): |
| _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600 |
| .SH DESCRIPTION |
| .BR select () |
| and |
| .BR pselect () |
| allow a program to monitor multiple file descriptors, |
| waiting until one or more of the file descriptors become "ready" |
| for some class of I/O operation (e.g., input possible). |
| A file descriptor is considered ready if it is possible to |
| perform the corresponding I/O operation (e.g., |
| .BR read (2)) |
| without blocking. |
| .PP |
| The operation of |
| .BR select () |
| and |
| .BR pselect () |
| is identical, with three differences: |
| .TP |
| (i) |
| .BR select () |
| uses a timeout that is a |
| .I struct timeval |
| (with seconds and microseconds), while |
| .BR pselect () |
| uses a |
| .I struct timespec |
| (with seconds and nanoseconds). |
| .TP |
| (ii) |
| .BR select () |
| may update the |
| .I timeout |
| argument to indicate how much time was left. |
| .BR pselect () |
| does not change this argument. |
| .TP |
| (iii) |
| .BR select () |
| has no |
| .I sigmask |
| argument, and behaves as |
| .BR pselect () |
| called with NULL |
| .IR sigmask . |
| .PP |
| Three independent sets of file descriptors are watched. |
| Those listed in |
| .I readfds |
| will be watched to see if characters become |
| available for reading (more precisely, to see if a read will not |
| block; in particular, a file descriptor is also ready on end-of-file), |
| those in |
| .I writefds |
| will be watched to see if a write will not block, and |
| those in |
| .I exceptfds |
| will be watched for exceptions. |
| On exit, the sets are modified in place |
| to indicate which file descriptors actually changed status. |
| Each of the three file descriptor sets may be specified as NULL |
| if no file descriptors are to be watched for the corresponding class |
| of events. |
| .PP |
| Four macros are provided to manipulate the sets. |
| .BR FD_ZERO () |
| clears a set. |
| .BR FD_SET () |
| and |
| .BR FD_CLR () |
| respectively add and remove a given file descriptor from a set. |
| .BR FD_ISSET () |
| tests to see if a file descriptor is part of the set; |
| this is useful after |
| .BR select () |
| returns. |
| .PP |
| .I nfds |
| is the highest-numbered file descriptor in any of the three sets, plus 1. |
| .PP |
| .I timeout |
| is an upper bound on the amount of time elapsed before |
| .BR select () |
| returns. |
| If both fields of the |
| .I timeval |
| stucture are zero, then |
| .BR select () |
| returns immediately. |
| (This is useful for polling.) |
| If |
| .I timeout |
| is NULL (no timeout), |
| .BR select () |
| can block indefinitely. |
| .PP |
| .I sigmask |
| is a pointer to a signal mask (see |
| .BR sigprocmask (2)); |
| if it is not NULL, then |
| .BR pselect () |
| first replaces the current signal mask by the one pointed to by |
| .IR sigmask , |
| then does the "select" function, and then restores the original |
| signal mask. |
| .PP |
| Other than the difference in the precision of the |
| .I timeout |
| argument, the following |
| .BR pselect () |
| call: |
| .nf |
| |
| ready = pselect(nfds, &readfds, &writefds, &exceptfds, |
| timeout, &sigmask); |
| |
| .fi |
| is equivalent to |
| .I atomically |
| executing the following calls: |
| .nf |
| |
| sigset_t origmask; |
| |
| sigprocmask(SIG_SETMASK, &sigmask, &origmask); |
| ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); |
| sigprocmask(SIG_SETMASK, &origmask, NULL); |
| .fi |
| .PP |
| The reason that |
| .BR pselect () |
| is needed is that if one wants to wait for either a signal |
| or for a file descriptor to become ready, then |
| an atomic test is needed to prevent race conditions. |
| (Suppose the signal handler sets a global flag and |
| returns. |
| Then a test of this global flag followed by a call of |
| .BR select () |
| could hang indefinitely if the signal arrived just after the test |
| but just before the call. |
| By contrast, |
| .BR pselect () |
| allows one to first block signals, handle the signals that have come in, |
| then call |
| .BR pselect () |
| with the desired |
| .IR sigmask , |
| avoiding the race.) |
| .SS "The timeout" |
| The time structures involved are defined in |
| .I <sys/time.h> |
| and look like |
| |
| .in +4n |
| .nf |
| struct timeval { |
| long tv_sec; /* seconds */ |
| long tv_usec; /* microseconds */ |
| }; |
| .fi |
| .in |
| |
| and |
| |
| .in +4n |
| .nf |
| struct timespec { |
| long tv_sec; /* seconds */ |
| long tv_nsec; /* nanoseconds */ |
| }; |
| .fi |
| .in |
| |
| (However, see below on the POSIX.1-2001 versions.) |
| .PP |
| Some code calls |
| .BR select () |
| with all three sets empty, |
| .I nfds |
| zero, and a non-NULL |
| .I timeout |
| as a fairly portable way to sleep with subsecond precision. |
| .PP |
| On Linux, |
| .BR select () |
| modifies |
| .I timeout |
| to reflect the amount of time not slept; most other implementations |
| do not do this. |
| (POSIX.1-2001 permits either behavior.) |
| This causes problems both when Linux code which reads |
| .I timeout |
| is ported to other operating systems, and when code is ported to Linux |
| that reuses a \fIstruct timeval\fP for multiple |
| .BR select ()s |
| in a loop without reinitializing it. |
| Consider |
| .I timeout |
| to be undefined after |
| .BR select () |
| returns. |
| .\" .PP - it is rumored that: |
| .\" On BSD, when a timeout occurs, the file descriptor bits are not changed. |
| .\" - it is certainly true that: |
| .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. |
| .SH "RETURN VALUE" |
| On success, |
| .BR select () |
| and |
| .BR pselect () |
| return the number of file descriptors contained in the three returned |
| descriptor sets (that is, the total number of bits that are set in |
| .IR readfds , |
| .IR writefds , |
| .IR exceptfds ) |
| which may be zero if the timeout expires before anything interesting happens. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately; the sets and |
| .I timeout |
| become undefined, so do not |
| rely on their contents after an error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| An invalid file descriptor was given in one of the sets. |
| (Perhaps a file descriptor that was already closed, |
| or one on which an error has occurred.) |
| .TP |
| .B EINTR |
| A signal was caught; see |
| .BR signal (7). |
| .TP |
| .B EINVAL |
| .I nfds |
| is negative or the value contained within |
| .I timeout |
| is invalid. |
| .TP |
| .B ENOMEM |
| unable to allocate memory for internal tables. |
| .SH VERSIONS |
| .BR pselect () |
| was added to Linux in kernel 2.6.16. |
| Prior to this, |
| .BR pselect () |
| was emulated in glibc (but see BUGS). |
| .SH "CONFORMING TO" |
| .BR select () |
| conforms to POSIX.1-2001 and |
| 4.4BSD |
| .RB ( select () |
| first appeared in 4.2BSD). |
| Generally portable to/from |
| non-BSD systems supporting clones of the BSD socket layer (including |
| System V variants). |
| However, note that the System V variant typically |
| sets the timeout variable before exit, but the BSD variant does not. |
| .PP |
| .BR pselect () |
| is defined in POSIX.1g, and in |
| POSIX.1-2001. |
| .SH NOTES |
| An |
| .I fd_set |
| is a fixed size buffer. |
| Executing |
| .BR FD_CLR () |
| or |
| .BR FD_SET () |
| with a value of |
| .I fd |
| that is negative or is equal to or larger than |
| .B FD_SETSIZE |
| will result |
| in undefined behavior. |
| Moreover, POSIX requires |
| .I fd |
| to be a valid file descriptor. |
| |
| Concerning the types involved, the classical situation is that |
| the two fields of a |
| .I timeval |
| structure are typed as |
| .I long |
| (as shown above), and the structure is defined in |
| .IR <sys/time.h> . |
| The POSIX.1-2001 situation is |
| |
| .in +4n |
| .nf |
| struct timeval { |
| time_t tv_sec; /* seconds */ |
| suseconds_t tv_usec; /* microseconds */ |
| }; |
| .fi |
| .in |
| |
| where the structure is defined in |
| .I <sys/select.h> |
| and the data types |
| .I time_t |
| and |
| .I suseconds_t |
| are defined in |
| .IR <sys/types.h> . |
| .LP |
| Concerning prototypes, the classical situation is that one should |
| include |
| .I <time.h> |
| for |
| .BR select (). |
| The POSIX.1-2001 situation is that one should include |
| .I <sys/select.h> |
| for |
| .BR select () |
| and |
| .BR pselect (). |
| Libc4 and libc5 do not have a |
| .I <sys/select.h> |
| header; under glibc 2.0 and later this header exists. |
| Under glibc 2.0 it unconditionally gives the wrong prototype for |
| .BR pselect (), |
| under glibc 2.1-2.2.1 it gives |
| .BR pselect () |
| when |
| .B _GNU_SOURCE |
| is defined, under glibc 2.2.2-2.2.4 it gives it when |
| .B _XOPEN_SOURCE |
| is defined and has a value of 600 or larger. |
| No doubt, since POSIX.1-2001, it should give the prototype by default. |
| .SS "Linux Notes" |
| The Linux |
| .BR pselect () |
| system call modifies its |
| .I timeout |
| argument. |
| However, the glibc wrapper function hides this behavior |
| by using a local variable for the timeout argument that |
| is passed to the system call. |
| Thus, the glibc |
| .BR pselect () |
| function does not modify its timeout argument; |
| this is the behavior required by POSIX.1-2001. |
| .SH BUGS |
| Glibc 2.0 provided a version of |
| .BR pselect () |
| that did not take a |
| .I sigmask |
| argument. |
| |
| Since version 2.1, glibc has provided an emulation of |
| .BR pselect () |
| that is implemented using |
| .BR sigprocmask (2) |
| and |
| .BR select (). |
| This implementation remains vulnerable to the very race condition that |
| .BR pselect () |
| was designed to prevent. |
| On systems that lack |
| .BR pselect () |
| reliable (and more portable) signal trapping can be achieved |
| using the self-pipe trick |
| (where a signal handler writes a byte to a pipe whose other end |
| is monitored by |
| .BR select () |
| in the main program.) |
| |
| Under Linux, |
| .BR select () |
| may report a socket file descriptor as "ready for reading", while |
| nevertheless a subsequent read blocks. |
| This could for example |
| happen when data has arrived but upon examination has wrong |
| checksum and is discarded. |
| There may be other circumstances |
| in which a file descriptor is spuriously reported as ready. |
| .\" Stevens discusses a case where accept can block after select |
| .\" returns successfully because of an intervening RST from the client. |
| Thus it may be safer to use |
| .B O_NONBLOCK |
| on sockets that should not block. |
| .\" Maybe the kernel should have returned EIO in such a situation? |
| |
| On Linux, |
| .BR select () |
| also modifies |
| .I timeout |
| if the call is interrupted by a signal handler (i.e., the |
| .B EINTR |
| error return). |
| This is not permitted by POSIX.1-2001. |
| The Linux |
| .BR pselect () |
| system call has the same behavior, |
| but the glibc wrapper hides this behavior by internally copying the |
| .I timeout |
| to a local variable and passing that variable to the system call. |
| .SH EXAMPLE |
| .nf |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <sys/time.h> |
| #include <sys/types.h> |
| #include <unistd.h> |
| |
| int |
| main(void) |
| { |
| fd_set rfds; |
| struct timeval tv; |
| int retval; |
| |
| /* Watch stdin (fd 0) to see when it has input. */ |
| FD_ZERO(&rfds); |
| FD_SET(0, &rfds); |
| |
| /* Wait up to five seconds. */ |
| tv.tv_sec = 5; |
| tv.tv_usec = 0; |
| |
| retval = select(1, &rfds, NULL, NULL, &tv); |
| /* Don't rely on the value of tv now! */ |
| |
| if (retval == \-1) |
| perror("select()"); |
| else if (retval) |
| printf("Data is available now.\\n"); |
| /* FD_ISSET(0, &rfds) will be true. */ |
| else |
| printf("No data within five seconds.\\n"); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .fi |
| .SH "SEE ALSO" |
| For a tutorial with discussion and examples, see |
| .BR select_tut (2). |
| .LP |
| For vaguely related stuff, see |
| .BR accept (2), |
| .BR connect (2), |
| .BR poll (2), |
| .BR read (2), |
| .BR recv (2), |
| .BR send (2), |
| .BR sigprocmask (2), |
| .BR write (2), |
| .BR epoll (7), |
| .BR time (7) |