# pselect

## PROLOG



           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.
    


## NAME



           pselect, select — synchronous I/O multiplexing
    


## SYNOPSIS



           #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_ , fd_set *_fdset_);
           void FD_SET(int _fd_ , fd_set *_fdset_);
           void FD_ZERO(fd_set *_fdset_);
    


## DESCRIPTION



           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, STREAMS-based files, 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_() or _setitimer_().
    
           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.
    
           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_() 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, nor will an error be
           returned.
    
           _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, nor will an error
           be returned.
    
           _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.
    


## RETURN VALUE



           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.
    


## ERRORS



           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 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]**.
    
           **EINVAL** An invalid timeout interval was specified.
    
           **EINVAL** The _nfds_ argument is less than 0 or greater than
                  FD_SETSIZE.
    
           **EINVAL** One 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._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           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;
               }
    


## FUTURE DIRECTIONS



           None.
    


* * *