HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
PROLOG |NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |EXAMPLES |APPLICATION USAGE |RATIONALE |FUTURE DIRECTIONS |SEE ALSO |COPYRIGHT | |
PSELECT(3P) POSIX Programmer's ManualPSELECT(3P)This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.
pselect, select — synchronous I/O multiplexing
#include <sys/select.h> int pselect(intnfds, fd_set *restrictreadfds, fd_set *restrictwritefds, fd_set *restricterrorfds, const struct timespec *restricttimeout, const sigset_t *restrictsigmask); int select(intnfds, fd_set *restrictreadfds, fd_set *restrictwritefds, fd_set *restricterrorfds, struct timeval *restricttimeout); void FD_CLR(intfd, fd_set *fdset); int FD_ISSET(intfd, fd_set *fdset); void FD_SET(intfd, fd_set *fdset); void FD_ZERO(fd_set *fdset);
Thepselect() function shall examine the file descriptor sets whose addresses are passed in thereadfds,writefds, anderrorfds parameters to see whether some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. Theselect() function shall be equivalent to thepselect() function, except as follows: * For theselect() function, the timeout period is given in seconds and microseconds in an argument of typestructtimeval, whereas for thepselect() function the timeout period is given in seconds and nanoseconds in an argument of typestruct timespec. * Theselect() function has nosigmask argument; it shall behave aspselect() does whensigmask is a null pointer. * Upon successful completion, theselect() function may modify the object pointed to by thetimeout argument. Thepselect() andselect() functions shall support regular files, terminal and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and sockets. The behavior ofpselect() andselect() on file descriptors that refer to other types of file is unspecified. Thenfds argument specifies the range of descriptors to be tested. The firstnfds descriptors shall be checked in each set; that is, the descriptors from zero throughnfds-1 in the descriptor sets shall be examined. If thereadfds argument is not a null pointer, it points to an object of typefd_setthat 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 thewritefds argument is not a null pointer, it points to an object of typefd_setthat 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 theerrorfds argument is not a null pointer, it points to an object of typefd_setthat 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, thepselect() orselect() function shall modify the objects pointed to by thereadfds,writefds, anderrorfds 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 thannfds, 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, thepselect() orselect() function shall block until at least one of the requested operations becomes ready, until thetimeout occurs, or until interrupted by a signal. Thetimeout parameter controls how long thepselect() orselect() function shall take before timing out. If thetimeout 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 thetimeout parameter is a null pointer, then the call topselect() orselect() shall block indefinitely until at least one descriptor meets the specified criteria. To effect a poll, thetimeout parameter should not be a null pointer, and should point to a zero-valuedtimespecstructure. The use of a timeout does not affect any pending timers set up byalarm() orsetitimer(). Implementations may place limitations on the maximum timeout interval supported. All implementations shall support a maximum timeout interval of at least 31 days. If thetimeout 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. Ifsigmask is not a null pointer, then thepselect() function shall replace the signal mask of the caller by the set of signals pointed to bysigmask before examining the descriptors, and shall restore the signal mask of the calling thread before returning. 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() orselect() 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 therecvmsg() 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 theaccept() function shall complete without blocking. If a descriptor refers to a socket, the implied output function is thesendmsg() 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 theconnect() 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 thereadfds,writefds, anderrorfds arguments are all null pointers and thetimeout argument is not a null pointer, thepselect() orselect() function shall block for the time specified, or until interrupted by a signal. If thereadfds,writefds, anderrorfds arguments are all null pointers and thetimeout argument is a null pointer, thepselect() orselect() 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 thereadfds,writefds, anderrorfds 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 thereadfds,writefds, anderrorfds arguments shall have all bits set to 0. File descriptor masks of typefd_setcan be initialized and tested withFD_CLR(),FD_ISSET(),FD_SET(), andFD_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 descriptorfd from the set pointed to byfdsetp. Iffd is not a member of this set, there shall be no effect on the set, nor will an error be returned.FD_ISSET(fd,fdsetp) shall evaluate to non-zero if the file descriptorfd is a member of the set pointed to byfdsetp, and shall evaluate to zero otherwise.FD_SET(fd,fdsetp) shall add the file descriptorfd to the set pointed to byfdsetp. If the file descriptorfd is already in this set, there shall be no effect on the set, nor will an error be returned.FD_ZERO(fdsetp) shall initialize the descriptor set pointed to byfdsetp to the null set. No error is returned if the set is not empty at the timeFD_ZERO() is invoked. The behavior of these macros is undefined if thefd argument is less than 0 or greater than or equal to FD_SETSIZE, or iffd is not a valid file descriptor, or if any of the arguments are expressions with side-effects. If a thread gets canceled during apselect() 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 thepselect() call.
Upon successful completion, thepselect() andselect() functions shall return the total number of bits set in the bit masks. Otherwise, -1 shall be returned, anderrno shall be set to indicate the error.FD_CLR(),FD_SET(), andFD_ZERO() do not return a value.FD_ISSET() shall return a non-zero value if the bit for the file descriptorfd is set in the file descriptor set pointed to byfdset, and 0 otherwise.
Under the following conditions,pselect() andselect() shall fail and seterrno to:EBADFOne or more of the file descriptor sets specified a file descriptor that is not a valid open file descriptor.EINTRThe function was interrupted while blocked waiting for any of the selected descriptors to become ready and before the timeout interval expired. If SA_RESTART has been set for the interrupting signal, it is implementation-defined whether the function restarts or returns with[EINTR].EINVALAn invalid timeout interval was specified.EINVALThenfds argument is less than 0 or greater than FD_SETSIZE.EINVALOne of the specified file descriptors refers to a STREAM or multiplexer that is linked (directly or indirectly) downstream from a multiplexer.The following sections are informative.
None.
None.
In earlier versions of the Single UNIX Specification, theselect() 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 thepselect() function included the<sys/select.h> header and the<sys/select.h> header defines all the related definitions for thepselect() andselect() 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(3p),alarm(3p),connect(3p),fcntl(3p),getitimer(3p),poll(3p),read(3p),recvmsg(3p),sendmsg(3p),write(3p) The Base Definitions volume of POSIX.1‐2017,sys_select.h(0p),sys_time.h(0p)
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online athttp://www.opengroup.org/unix/online.html . Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group 2017PSELECT(3P)Pages that refer to this page:sys_select.h(0p), sys_time.h(0p), connect(3p), FD_CLR(3p), poll(3p), recv(3p), recvfrom(3p), recvmsg(3p), select(3p), send(3p), sendmsg(3p), sendto(3p), shutdown(3p), sockatmark(3p)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |