pselect, select — synchronous I/O multiplexing
#include <sys/select.h>
int pselect(int nfds, fd_set *restrict readfds,
fd_set *restrict writefds, fd_set *restrict errorfds,
const struct timespec *restrict timeout,
const sigset_t *restrict sigmask);
int select(int nfds, fd_set *restrict readfds,
fd_set *restrict writefds, fd_set *restrict errorfds,
struct timeval *restrict timeout);
void FD_CLR(int fd, fd_set *fdset);
int FD_ISSET(int fd, const fd_set *fdset);
void FD_SET(int fd, fd_set *fdset);
void FD_ZERO(fd_set *fdset);
The pselect() function shall examine the file descriptor sets whose addresses are passed in the readfds, writefds, and errorfds parameters to see whether some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively.
The select() function shall be equivalent to the pselect() function, except as follows:
For the select() function, the timeout period is given in seconds and microseconds in an argument of type struct timeval, whereas for the pselect() function the timeout period is given in seconds and nanoseconds in an argument of type struct timespec.
The select() function has no sigmask argument; it shall behave as pselect() does when sigmask is a null pointer.
Upon successful completion, the select() function may modify the object pointed to by the timeout argument.
The pselect() and select() functions shall support regular files, terminal and pseudo-terminal devices, FIFOs, pipes, and sockets. The behavior of pselect() and select() on file descriptors that refer to other types of file is unspecified.
The nfds argument specifies the range of descriptors to be tested. The first nfds descriptors shall be checked in each set; that is, the descriptors from zero through nfds-1 in the descriptor sets shall be examined.
If the readfds argument is not a null pointer, it points to an object of type fd_set that on input specifies the file descriptors to be checked for being ready to read, and on output indicates which file descriptors are ready to read.
If the writefds argument is not a null pointer, it points to an object of type fd_set that on input specifies the file descriptors to be checked for being ready to write, and on output indicates which file descriptors are ready to write.
If the errorfds argument is not a null pointer, it points to an object of type fd_set that on input specifies the file descriptors to be checked for error conditions pending, and on output indicates which file descriptors have error conditions pending.
Upon successful completion, the pselect() or select() function shall modify the objects pointed to by the readfds, writefds, and errorfds arguments to indicate which file descriptors are ready for reading, ready for writing, or have an error condition pending, respectively, and shall return the total number of ready descriptors in all the output sets. For each file descriptor less than nfds, the corresponding bit shall be set upon successful completion if it was set on input and the associated condition is true for that file descriptor.
If none of the selected descriptors are ready for the requested operation, the pselect() or select() function shall block until at least one of the requested operations becomes ready, until the timeout occurs, or until interrupted by a signal. The timeout parameter controls how long the pselect() or select() function shall take before timing out. If the timeout parameter is not a null pointer, it specifies a maximum interval to wait for the selection to complete. If the specified time interval expires without any requested operation becoming ready, the function shall return. If the timeout parameter is a null pointer, then the call to pselect() or select() shall block indefinitely until at least one descriptor meets the specified criteria. To effect a poll, the timeout parameter should not be a null pointer, and should point to a zero-valued timespec structure.
The use of a timeout does not affect any pending timers set up by alarm().
Implementations may place limitations on the maximum timeout interval supported. All implementations shall support a maximum timeout interval of at least 31 days. If the timeout argument specifies a timeout interval greater than the implementation-defined maximum value, the maximum value shall be used as the actual timeout value. Implementations may also place limitations on the granularity of timeout intervals. If the requested timeout interval requires a finer granularity than the implementation supports, the actual timeout interval shall be rounded up to the next supported value.
If sigmask is not a null pointer, then the pselect() function shall replace the signal mask of the caller by the set of signals pointed to by sigmask before examining the descriptors, and shall restore the signal mask of the calling thread before returning. If a signal is unmasked as a result of the signal mask being altered by pselect(), and a signal-catching function is called for that signal during the execution of the pselect() function, and SA_RESTART is clear for the interrupting signal, then
If none of the selected file descriptors are ready, pselect() shall immediately fail with the [EINTR] error after the signal-catching function returns.
If one or more of the selected file descriptors are ready, it is unspecified whether pselect() behaves the same as if none of the descriptors were ready (failing with [EINTR] as above) or behaves the same as if it was not interrupted (returning the total number of ready descriptors).
A descriptor shall be considered ready for reading when a call to an input function with O_NONBLOCK clear would not block, whether or not the function would transfer data successfully. (The function might return data, an end-of-file indication, or an error other than one indicating that it is blocked, and in each of these cases the descriptor shall be considered ready for reading.)
A descriptor shall be considered ready for writing when a call to an output function with O_NONBLOCK clear would not block, whether or not the function would transfer data successfully.
If a socket has a pending error, it shall be considered to have an exceptional condition pending. Otherwise, what constitutes an exceptional condition is file type-specific. For a file descriptor for use with a socket, it is protocol-specific except as noted below. For other file types it is implementation-defined. If the operation is meaningless for a particular file type, pselect() or select() shall indicate that the descriptor is ready for read or write operations, and shall indicate that the descriptor has no exceptional condition pending.
If a descriptor refers to a socket, the implied input function is the recvmsg() function with parameters requesting normal and ancillary data, such that the presence of either type shall cause the socket to be marked as readable. The presence of out-of-band data shall be checked if the socket option SO_OOBINLINE has been enabled, as out-of-band data is enqueued with normal data. If the socket is currently listening, then it shall be marked as readable if an incoming connection request has been received, and a call to the accept() or accept4() function shall complete without blocking.
If a descriptor refers to a socket, the implied output function is the sendmsg() function supplying an amount of normal data equal to the current value of the SO_SNDLOWAT option for the socket. If a non-blocking call to the connect() function has been made for a socket, and the connection attempt has either succeeded or failed leaving a pending error, the socket shall be marked as writable.
A socket shall be considered to have an exceptional condition pending if a receive operation with O_NONBLOCK clear for the open file description and with the MSG_OOB flag set would return out-of-band data without blocking. (It is protocol-specific whether the MSG_OOB flag would be used to read out-of-band data.) A socket shall also be considered to have an exceptional condition pending if an out-of-band data mark is present in the receive queue. Other circumstances under which a socket may be considered to have an exceptional condition pending are protocol-specific and implementation-defined.
If the readfds, writefds, and errorfds arguments are all null pointers and the timeout argument is not a null pointer, the pselect() or select() function shall block for the time specified, or until interrupted by a signal. If the readfds, writefds, and errorfds arguments are all null pointers and the timeout argument is a null pointer, the pselect() or select() function shall block until interrupted by a signal.
File descriptors associated with regular files shall always select true for ready to read, ready to write, and error conditions.
On failure, the objects pointed to by the readfds, writefds, and errorfds arguments shall not be modified. If the timeout interval expires without the specified condition being true for any of the specified file descriptors, the objects pointed to by the readfds, writefds, and errorfds arguments shall have all bits set to 0.
File descriptor masks of type fd_set can be initialized and tested with FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO(). It is unspecified whether each of these is a macro or a function. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with any of these names, the behavior is undefined.
FD_CLR(fd, fdsetp) shall remove the file descriptor fd from the set pointed to by fdsetp. If fd is not a member of this set, there shall be no effect on the set, and this shall not be treated as an error.
FD_ISSET(fd, fdsetp) shall evaluate to non-zero if the file descriptor fd is a member of the set pointed to by fdsetp, and shall evaluate to zero otherwise.
FD_SET(fd, fdsetp) shall add the file descriptor fd to the set pointed to by fdsetp. If the file descriptor fd is already in this set, there shall be no effect on the set, and this shall not be treated as an error.
FD_ZERO(fdsetp) shall initialize the descriptor set pointed to by fdsetp to the null set. No error is returned if the set is not empty at the time FD_ZERO() is invoked.
The behavior of these macros is undefined if the fd argument is less than 0 or greater than or equal to FD_SETSIZE, or if fd is not a valid file descriptor, or if any of the arguments are expressions with side-effects.
If a thread gets canceled during a pselect() call, the signal mask in effect when executing the registered cleanup functions is either the original signal mask or the signal mask installed as part of the pselect() call.
Upon successful completion, the pselect() and select() functions shall return the total number of bits set in the bit masks. Otherwise, -1 shall be returned, and errno shall be set to indicate the error.
FD_CLR(), FD_SET(), and FD_ZERO() do not return a value. FD_ISSET() shall return a non-zero value if the bit for the file descriptor fd is set in the file descriptor set pointed to by fdset, and 0 otherwise.
Under the following conditions, pselect() and select() shall fail and set errno to:
- [EBADF]
- One or more of the file descriptor sets specified a file descriptor that is not a valid open file descriptor.
- [EINTR]
- The function was interrupted by a signal.
If SA_RESTART has been set for the interrupting signal, it is implementation-defined whether the function restarts or returns with [EINTR].
- [EINVAL]
- An invalid timeout interval was specified.
- [EINVAL]
- The nfds argument is less than 0 or greater than FD_SETSIZE.
None.
The use of select() and pselect() requires that the application construct the set of file descriptors to work on each time through a polling loop, and is inherently limited from operating on file descriptors larger than FD_SETSIZE. Also, the amount of work to perform scales as nfds increases, even if the number of file descriptors selected within the larger set remains the same. Thus, applications may wish to consider using poll() and ppoll() instead, for better scaling.
When a pselect() or select() call indicates a file descriptor is ready for reading, this means that if an attempt to read data had been made at the time that the status of the file descriptor was checked, it would have returned at least one byte of data, an end-of-file indication, or an error, without blocking (even if O_NONBLOCK is clear). When a pselect() or select() call indicates that a file descriptor is ready for writing, this means that if an attempt to write one byte of data had been made at the time that the status of the file descriptor was checked, it would have written that byte or returned an error, without blocking. However, if an attempt to write more than one byte had been made, it might have blocked (if O_NONBLOCK is clear). In both cases, by the time the call returns and a subsequent I/O operation is attempted, the state of the file descriptor might have changed (for example, because another thread read or wrote some data) and, if O_NONBLOCK is clear, there is no guarantee that the operation will not block (unless it would not block for some other reason, such as setting MIN=0 and TIME=0 for a terminal in non-canonical mode). Therefore it is recommended that applications always set O_NONBLOCK on file descriptors whose readiness for I/O they query with pselect() or select().
In earlier versions of the Single UNIX Specification, the select() function was defined in the <sys/time.h> header. This is now changed to <sys/select.h>. The rationale for this change was as follows: the introduction of the pselect() function included the <sys/select.h> header and the <sys/select.h> header defines all the related definitions for the pselect() and select() functions. Backwards-compatibility to existing XSI implementations is handled by allowing <sys/time.h> to include <sys/select.h>.
Code which wants to avoid the ambiguity of the signal mask for thread cancellation handlers can install an additional cancellation handler which resets the signal mask to the expected value.
void cleanup(void *arg) { sigset_t *ss = (sigset_t *) arg; pthread_sigmask(SIG_SETMASK, ss, NULL); }
int call_pselect(int nfds, fd_set *readfds, fd_set *writefds, fd_set errorfds, const struct timespec *timeout, const sigset_t *sigmask) { sigset_t oldmask; int result; pthread_sigmask(SIG_SETMASK, NULL, &oldmask); pthread_cleanup_push(cleanup, &oldmask); result = pselect(nfds, readfds, writefds, errorfds, timeout, sigmask); pthread_cleanup_pop(0); return result; }
None.
accept , alarm , connect , fcntl , poll , read , recvmsg , sendmsg , write
XBD <sys/select.h> , <sys/time.h>
First released in Issue 4, Version 2.
Moved from X/OPEN UNIX extension to BASE.
In the ERRORS section, the text has been changed to indicate that [EINVAL] is returned when nfds is less than 0 or greater than FD_SETSIZE. It previously stated less than 0, or greater than or equal to FD_SETSIZE.
Text about timeout is moved from the APPLICATION USAGE section to the DESCRIPTION.
The Open Group Corrigendum U026/6 is applied, changing the occurrences of readfs and writefs in the select() DESCRIPTION to be readfds and writefds.
Text referring to sockets is added to the DESCRIPTION.
The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are marked as part of the XSI STREAMS Option Group.
The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:
These functions are now mandatory.
The pselect() function is added for alignment with IEEE Std 1003.1g-2000 and additional detail related to sockets semantics is added to the DESCRIPTION.
The select() function now requires inclusion of <sys/select.h>.
The restrict keyword is added to the select() prototype for alignment with the ISO/IEC 9899:1999 standard.
IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/70 is applied, updating the DESCRIPTION to reference the signal mask in terms of the calling thread rather than the process.
SD5-XSH-ERN-122 is applied, adding text to the DESCRIPTION for when a thread is canceled during a call to pselect(), and adding example code to the RATIONALE.
Functionality relating to the XSI STREAMS option is marked obsolescent.
Functionality relating to the Threads option is moved to the Base.
POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0446 [372] is applied.
POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0259 [680] is applied.
Austin Group Defect 220 is applied, adding const to the second parameter of FD_ISSET().
Austin Group Defect 411 is applied, adding accept4().
Austin Group Defect 1186 is applied, clarifying the behavior when the pselect() function is interrupted by a signal.
Austin Group Defect 1263 is applied, changing the APPLICATION USAGE section.
Austin Group Defect 1330 is applied, removing obsolescent interfaces.
Austin Group Defect 1448 is applied, changing the APPLICATION USAGE section.
return to top of page