path: root/upstream/archlinux/man3p/pselect.3p

'\" et
.TH PSELECT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH 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.
.\"
.SH NAME
pselect,
select
\(em synchronous I/O multiplexing
.SH SYNOPSIS
.LP
.nf
#include <sys/select.h>
.P
int pselect(int \fInfds\fP, fd_set *restrict \fIreadfds\fP,
    fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP,
    const struct timespec *restrict \fItimeout\fP,
    const sigset_t *restrict \fIsigmask\fP);
int select(int \fInfds\fP, fd_set *restrict \fIreadfds\fP,
    fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP,
    struct timeval *restrict \fItimeout\fP);
void FD_CLR(int \fIfd\fP, fd_set *\fIfdset\fP);
int FD_ISSET(int \fIfd\fP, fd_set *\fIfdset\fP);
void FD_SET(int \fIfd\fP, fd_set *\fIfdset\fP);
void FD_ZERO(fd_set *\fIfdset\fP);
.fi
.SH DESCRIPTION
The
\fIpselect\fR()
function shall examine the file descriptor sets whose addresses are
passed in the
.IR readfds ,
.IR writefds ,
and
.IR errorfds
parameters to see whether some of their descriptors are ready for reading,
are ready for writing, or have an exceptional condition pending,
respectively.
.P
The
\fIselect\fR()
function shall be equivalent to the
\fIpselect\fR()
function, except as follows:
.IP " *" 4
For the
\fIselect\fR()
function, the timeout period is given in seconds and microseconds in an
argument of type
.BR "struct timeval" ,
whereas for the
\fIpselect\fR()
function the timeout period is given in seconds and nanoseconds in an
argument of type
.BR "struct timespec" .
.IP " *" 4
The
\fIselect\fR()
function has no
.IR sigmask
argument; it shall behave as
\fIpselect\fR()
does when
.IR sigmask
is a null pointer.
.IP " *" 4
Upon successful completion, the
\fIselect\fR()
function may modify the object pointed to by the
.IR timeout
argument.
.P
The
\fIpselect\fR()
and
\fIselect\fR()
functions shall support regular files, terminal and pseudo-terminal
devices,
STREAMS-based files,
FIFOs, pipes, and sockets. The behavior of
\fIpselect\fR()
and
\fIselect\fR()
on file descriptors that refer to other types of file is unspecified.
.P
The
.IR nfds
argument specifies the range of descriptors to be tested. The first
.IR nfds
descriptors shall be checked in each set; that is, the descriptors from
zero through
.IR nfds \-1
in the descriptor sets shall be examined.
.P
If the
.IR readfds
argument is not a null pointer, it points to an object of type
.BR 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.
.P
If the
.IR writefds
argument is not a null pointer, it points to an object of type
.BR 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.
.P
If the
.IR errorfds
argument is not a null pointer, it points to an object of type
.BR 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.
.P
Upon successful completion, the
\fIpselect\fR()
or
\fIselect\fR()
function shall modify the objects pointed to by the
.IR readfds ,
.IR writefds ,
and
.IR 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
.IR 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.
.P
If none of the selected descriptors are ready for the requested
operation, the
\fIpselect\fR()
or
\fIselect\fR()
function shall block until at least one of the requested operations
becomes ready, until the
.IR timeout
occurs, or until interrupted by a signal.
The
.IR timeout
parameter controls how long the
\fIpselect\fR()
or
\fIselect\fR()
function shall take before timing out. If the
.IR 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
.IR timeout
parameter is a null pointer, then the call to
\fIpselect\fR()
or
\fIselect\fR()
shall block indefinitely until at least one descriptor meets the
specified criteria. To effect a poll, the
.IR timeout
parameter should not be a null pointer, and should point to a
zero-valued
.BR timespec
structure.
.P
The use of a timeout does not affect any pending timers set up by
\fIalarm\fR()
or
\fIsetitimer\fR().
.P
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
.IR 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.
.P
If
.IR sigmask
is not a null pointer, then the
\fIpselect\fR()
function shall replace the signal mask of the caller by the set of
signals pointed to by
.IR sigmask
before examining the descriptors, and shall restore the signal mask of
the calling thread before returning.
.P
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.)
.P
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.
.P
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,
\fIpselect\fR()
or
\fIselect\fR()
shall indicate that the descriptor is ready for read or write
operations, and shall indicate that the descriptor has no exceptional
condition pending.
.P
If a descriptor refers to a socket, the implied input function is the
\fIrecvmsg\fR()
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
\fIaccept\fR()
function shall complete without blocking.
.P
If a descriptor refers to a socket, the implied output function is the
\fIsendmsg\fR()
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
\fIconnect\fR()
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.
.P
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.
.P
If the
.IR readfds ,
.IR writefds ,
and
.IR errorfds
arguments are all null pointers and the
.IR timeout
argument is not a null pointer, the
\fIpselect\fR()
or
\fIselect\fR()
function shall block for the time specified, or until interrupted by
a signal. If the
.IR readfds ,
.IR writefds ,
and
.IR errorfds
arguments are all null pointers and the
.IR timeout
argument is a null pointer, the
\fIpselect\fR()
or
\fIselect\fR()
function shall block until interrupted by a signal.
.P
File descriptors associated with regular files shall always select true
for ready to read, ready to write, and error conditions.
.P
On failure, the objects pointed to by the
.IR readfds ,
.IR writefds ,
and
.IR 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
.IR readfds ,
.IR writefds ,
and
.IR errorfds
arguments shall have all bits set to 0.
.P
File descriptor masks of type
.BR fd_set
can be initialized and tested with
\fIFD_CLR\fR(),
\fIFD_ISSET\fR(),
\fIFD_SET\fR(),
and
\fIFD_ZERO\fR().
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.
.P
\fIFD_CLR\fR(\fIfd\fR, \fIfdsetp\fR) shall remove the file descriptor
.IR fd
from the set pointed to by
.IR fdsetp .
If
.IR fd
is not a member of this set, there shall be no effect on the set, nor
will an error be returned.
.P
\fIFD_ISSET\fR(\fIfd\fR, \fIfdsetp\fR) shall evaluate to non-zero if
the file descriptor
.IR fd
is a member of the set pointed to by
.IR fdsetp ,
and shall evaluate to zero otherwise.
.P
\fIFD_SET\fR(\fIfd\fR, \fIfdsetp\fR) shall add the file descriptor
.IR fd
to the set pointed to by
.IR fdsetp .
If the file descriptor
.IR fd
is already in this set, there shall be no effect on the set, nor will
an error be returned.
.P
\fIFD_ZERO\fR(\fIfdsetp\fR) shall initialize the descriptor set pointed
to by
.IR fdsetp
to the null set. No error is returned if the set is not empty at the
time
\fIFD_ZERO\fR()
is invoked.
.P
The behavior of these macros is undefined if the
.IR fd
argument is less than 0 or greater than or equal to FD_SETSIZE, or if
.IR fd
is not a valid file descriptor, or if any of the arguments are
expressions with side-effects.
.P
If a thread gets canceled during a
\fIpselect\fR()
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
\fIpselect\fR()
call.
.SH "RETURN VALUE"
Upon successful completion, the
\fIpselect\fR()
and
\fIselect\fR()
functions shall return the total number of bits set in the bit masks.
Otherwise, \-1 shall be returned, and
.IR errno
shall be set to indicate the error.
.P
\fIFD_CLR\fR(),
\fIFD_SET\fR(),
and
\fIFD_ZERO\fR()
do not return a value.
\fIFD_ISSET\fR()
shall return a non-zero value if the bit for the file descriptor
.IR fd
is set in the file descriptor set pointed to by
.IR fdset ,
and 0 otherwise.
.SH ERRORS
Under the following conditions,
\fIpselect\fR()
and
\fIselect\fR()
shall fail and set
.IR errno
to:
.TP
.BR EBADF
One or more of the file descriptor sets specified a file descriptor
that is not a valid open file descriptor.
.TP
.BR EINTR
The function was interrupted while blocked waiting for any of the
selected descriptors to become ready and before the timeout interval
expired.
.RS 12 
.P
If SA_RESTART has been set for the interrupting signal, it is
implementation-defined whether the function restarts or returns with
.BR [EINTR] .
.RE
.TP
.BR EINVAL
An invalid timeout interval was specified.
.TP
.BR EINVAL
The
.IR nfds
argument is less than 0 or greater than FD_SETSIZE.
.TP
.BR EINVAL
One of the specified file descriptors refers to a STREAM or multiplexer
that is linked (directly or indirectly) downstream from a multiplexer.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
In earlier versions of the Single UNIX Specification, the
\fIselect\fR()
function was defined in the
.IR <sys/time.h> 
header. This is now changed to
.IR <sys/select.h> .
The rationale for this change was as follows: the introduction of the
\fIpselect\fR()
function included the
.IR <sys/select.h> 
header and the
.IR <sys/select.h> 
header defines all the related definitions for the
\fIpselect\fR()
and
\fIselect\fR()
functions. Backwards-compatibility to existing XSI implementations is
handled by allowing
.IR <sys/time.h> 
to include
.IR <sys/select.h> .
.P
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.
.sp
.RS 4
.nf

void cleanup(void *arg)
{
    sigset_t *ss = (sigset_t *) arg;
    pthread_sigmask(SIG_SETMASK, ss, NULL);
}
.P
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;
}
.fi
.P
.RE
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIaccept\fR\^(\|)",
.IR "\fIalarm\fR\^(\|)",
.IR "\fIconnect\fR\^(\|)",
.IR "\fIfcntl\fR\^(\|)",
.IR "\fIgetitimer\fR\^(\|)",
.IR "\fIpoll\fR\^(\|)",
.IR "\fIread\fR\^(\|)",
.IR "\fIrecvmsg\fR\^(\|)",
.IR "\fIsendmsg\fR\^(\|)",
.IR "\fIwrite\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_select.h>\fP",
.IR "\fB<sys_time.h>\fP"
.\"
.SH COPYRIGHT
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 .
.PP
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 .