PSELECT(3)                 POSIX Programmer's Manual                PSELECT(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       pselect, select -- synchronous I/O multiplexing

SSYYNNOOPPSSIISS
       #include <sys/select.h>

       int pselect(int _n_f_d_s, fd_set *restrict _r_e_a_d_f_d_s,
           fd_set *restrict _w_r_i_t_e_f_d_s, fd_set *restrict _e_r_r_o_r_f_d_s,
           const struct timespec *restrict _t_i_m_e_o_u_t,
           const sigset_t *restrict _s_i_g_m_a_s_k);
       int select(int _n_f_d_s, fd_set *restrict _r_e_a_d_f_d_s,
           fd_set *restrict _w_r_i_t_e_f_d_s, fd_set *restrict _e_r_r_o_r_f_d_s,
           struct timeval *restrict _t_i_m_e_o_u_t);
       void FD_CLR(int _f_d, fd_set *_f_d_s_e_t);
       int FD_ISSET(int _f_d, fd_set *_f_d_s_e_t);
       void FD_SET(int _f_d, fd_set *_f_d_s_e_t);
       void FD_ZERO(fd_set *_f_d_s_e_t);

DDEESSCCRRIIPPTTIIOONN
       The _p_s_e_l_e_c_t() function shall examine the file descriptor sets whose
       addresses are passed in the _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_r_r_o_r_f_d_s parameters
       to see whether some of their descriptors are ready for reading, are
       ready for writing, or have an exceptional condition pending,
       respectively.

       The _s_e_l_e_c_t() function shall be equivalent to the _p_s_e_l_e_c_t() function,
       except as follows:

        *  For the _s_e_l_e_c_t() function, the timeout period is given in seconds
           and microseconds in an argument of type ssttrruucctt ttiimmeevvaall, whereas for
           the _p_s_e_l_e_c_t() function the timeout period is given in seconds and
           nanoseconds in an argument of type ssttrruucctt ttiimmeessppeecc.

        *  The _s_e_l_e_c_t() function has no _s_i_g_m_a_s_k argument; it shall behave as
           _p_s_e_l_e_c_t() does when _s_i_g_m_a_s_k is a null pointer.

        *  Upon successful completion, the _s_e_l_e_c_t() function may modify the
           object pointed to by the _t_i_m_e_o_u_t argument.

       The _p_s_e_l_e_c_t() and _s_e_l_e_c_t() functions shall support regular files,
       terminal and pseudo-terminal devices, STREAMS-based files, FIFOs,
       pipes, and sockets. The behavior of _p_s_e_l_e_c_t() and _s_e_l_e_c_t() on file
       descriptors that refer to other types of file is unspecified.

       The _n_f_d_s argument specifies the range of descriptors to be tested. The
       first _n_f_d_s descriptors shall be checked in each set; that is, the
       descriptors from zero through _n_f_d_s-1 in the descriptor sets shall be
       examined.

       If the _r_e_a_d_f_d_s argument is not a null pointer, it points to an object
       of type ffdd__sseett 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 _w_r_i_t_e_f_d_s argument is not a null pointer, it points to an object
       of type ffdd__sseett 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 _e_r_r_o_r_f_d_s argument is not a null pointer, it points to an object
       of type ffdd__sseett 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 _p_s_e_l_e_c_t() or _s_e_l_e_c_t() function shall
       modify the objects pointed to by the _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_r_r_o_r_f_d_s
       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 _n_f_d_s, 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 _p_s_e_l_e_c_t() or _s_e_l_e_c_t() function shall block until at
       least one of the requested operations becomes ready, until the _t_i_m_e_o_u_t
       occurs, or until interrupted by a signal.  The _t_i_m_e_o_u_t parameter
       controls how long the _p_s_e_l_e_c_t() or _s_e_l_e_c_t() function shall take before
       timing out. If the _t_i_m_e_o_u_t 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 _t_i_m_e_o_u_t parameter is
       a null pointer, then the call to _p_s_e_l_e_c_t() or _s_e_l_e_c_t() shall block
       indefinitely until at least one descriptor meets the specified
       criteria. To effect a poll, the _t_i_m_e_o_u_t parameter should not be a null
       pointer, and should point to a zero-valued ttiimmeessppeecc structure.

       The use of a timeout does not affect any pending timers set up by
       _a_l_a_r_m() or _s_e_t_i_t_i_m_e_r().

       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 _t_i_m_e_o_u_t 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 _s_i_g_m_a_s_k is not a null pointer, then the _p_s_e_l_e_c_t() function shall
       replace the signal mask of the caller by the set of signals pointed to
       by _s_i_g_m_a_s_k 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, _p_s_e_l_e_c_t() or _s_e_l_e_c_t() 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
       _r_e_c_v_m_s_g() 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 _a_c_c_e_p_t()
       function shall complete without blocking.

       If a descriptor refers to a socket, the implied output function is the
       _s_e_n_d_m_s_g() 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 _c_o_n_n_e_c_t() 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 _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_r_r_o_r_f_d_s arguments are all null pointers
       and the _t_i_m_e_o_u_t argument is not a null pointer, the _p_s_e_l_e_c_t() or
       _s_e_l_e_c_t() function shall block for the time specified, or until
       interrupted by a signal. If the _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_r_r_o_r_f_d_s
       arguments are all null pointers and the _t_i_m_e_o_u_t argument is a null
       pointer, the _p_s_e_l_e_c_t() or _s_e_l_e_c_t() 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 _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and
       _e_r_r_o_r_f_d_s 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 _r_e_a_d_f_d_s,
       _w_r_i_t_e_f_d_s, and _e_r_r_o_r_f_d_s arguments shall have all bits set to 0.

       File descriptor masks of type ffdd__sseett can be initialized and tested with
       _F_D___C_L_R(), _F_D___I_S_S_E_T(), _F_D___S_E_T(), and _F_D___Z_E_R_O().  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.

       _F_D___C_L_R(_f_d, _f_d_s_e_t_p) shall remove the file descriptor _f_d from the set
       pointed to by _f_d_s_e_t_p.  If _f_d is not a member of this set, there shall
       be no effect on the set, nor will an error be returned.

       _F_D___I_S_S_E_T(_f_d, _f_d_s_e_t_p) shall evaluate to non-zero if the file descriptor
       _f_d is a member of the set pointed to by _f_d_s_e_t_p, and shall evaluate to
       zero otherwise.

       _F_D___S_E_T(_f_d, _f_d_s_e_t_p) shall add the file descriptor _f_d to the set pointed
       to by _f_d_s_e_t_p.  If the file descriptor _f_d is already in this set, there
       shall be no effect on the set, nor will an error be returned.

       _F_D___Z_E_R_O(_f_d_s_e_t_p) shall initialize the descriptor set pointed to by
       _f_d_s_e_t_p to the null set. No error is returned if the set is not empty at
       the time _F_D___Z_E_R_O() is invoked.

       The behavior of these macros is undefined if the _f_d argument is less
       than 0 or greater than or equal to FD_SETSIZE, or if _f_d is not a valid
       file descriptor, or if any of the arguments are expressions with side-
       effects.

       If a thread gets canceled during a _p_s_e_l_e_c_t() 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
       _p_s_e_l_e_c_t() call.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, the _p_s_e_l_e_c_t() and _s_e_l_e_c_t() functions shall
       return the total number of bits set in the bit masks.  Otherwise, -1
       shall be returned, and _e_r_r_n_o shall be set to indicate the error.

       _F_D___C_L_R(), _F_D___S_E_T(), and _F_D___Z_E_R_O() do not return a value.  _F_D___I_S_S_E_T()
       shall return a non-zero value if the bit for the file descriptor _f_d is
       set in the file descriptor set pointed to by _f_d_s_e_t, and 0 otherwise.

EERRRROORRSS
       Under the following conditions, _p_s_e_l_e_c_t() and _s_e_l_e_c_t() shall fail and
       set _e_r_r_n_o to:

       EEBBAADDFF  One or more of the file descriptor sets specified a file
              descriptor that is not a valid open file descriptor.

       EEIINNTTRR  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 [[EEIINNTTRR]].

       EEIINNVVAALL An invalid timeout interval was specified.

       EEIINNVVAALL The _n_f_d_s argument is less than 0 or greater than FD_SETSIZE.

       EEIINNVVAALL One of the specified file descriptors refers to a STREAM or
              multiplexer that is linked (directly or indirectly) downstream
              from a multiplexer.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       In earlier versions of the Single UNIX Specification, the _s_e_l_e_c_t()
       function was defined in the _<_s_y_s_/_t_i_m_e_._h_> header. This is now changed to
       _<_s_y_s_/_s_e_l_e_c_t_._h_>.  The rationale for this change was as follows: the
       introduction of the _p_s_e_l_e_c_t() function included the _<_s_y_s_/_s_e_l_e_c_t_._h_>
       header and the _<_s_y_s_/_s_e_l_e_c_t_._h_> header defines all the related
       definitions for the _p_s_e_l_e_c_t() and _s_e_l_e_c_t() functions. Backwards-
       compatibility to existing XSI implementations is handled by allowing
       _<_s_y_s_/_t_i_m_e_._h_> to include _<_s_y_s_/_s_e_l_e_c_t_._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;
           }

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _a_c_c_e_p_t(), _a_l_a_r_m(), _c_o_n_n_e_c_t(), _f_c_n_t_l(), _g_e_t_i_t_i_m_e_r(), _p_o_l_l(), _r_e_a_d(),
       _r_e_c_v_m_s_g(), _s_e_n_d_m_s_g(), _w_r_i_t_e()

       The Base Definitions volume of POSIX.1-2017, <<ssyyss__sseelleecctt..hh>>,
       <<ssyyss__ttiimmee..hh>>

CCOOPPYYRRIIGGHHTT
       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 at http://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, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                           PSELECT(3)
