xref: /illumos-gate/usr/src/man/man3c/select.3c (revision 19141168d83c6b9692f40a6885b0c7258161ec6b)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\"
.Dd "Dec 28, 2016"
.Dt SELECT 3C
.Os
.Sh NAME
.Nm select ,
.Nm pselect ,
.Nm FD_SET ,
.Nm FD_CLR ,
.Nm FD_ISSET ,
.Nm FD_ZERO
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.In sys/time.h
.Ft int
.Fo select
.Fa "int nfds"
.Fa "fd_set *restrict readfds"
.Fa "fd_set *restrict writefds"
.Fa "fd_set *restrict errorfds"
.Fa "struct timeval *restrict timeout"
.Fc
.Ft int
.Fo pselect
.Fa "int nfds"
.Fa "fd_set *restrict readfds"
.Fa "fd_set *restrict writefds"
.Fa "fd_set *restrict errorfds"
.Fa "const struct timespec *restrict timeout"
.Fa "const sigset_t *restrict sigmask"
.Fc
.Ft void
.Fo FD_SET
.Fa "int fd"
.Fa "fd_set *fdset"
.Fc
.Ft void
.Fo FD_CLR
.Fa "int fd"
.Fa "fd_set *fdset"
.Fc
.Ft int
.Fo FD_ISSET
.Fa "int fd"
.Fa "fd_set *fd_set"
.Fc
.Ft void
.Fo FD_ZERO
.Fa "fd_set *fdset"
.Fc
.Sh DESCRIPTION
The
.Fn pselect
function examines the file descriptor sets whose addresses
are passed in the
.Fa readfds ,
.Fa writefds ,
and
.Fa errorfds
parameters to see if some of their descriptors are ready for reading,
are ready for writing, or have an exceptional condition pending,
respectively.
.Pp
The
.Fn select
function is equivalent to the
.Fn pselect
function, except as follows:
.Bl -bullet
.It
For the
.Fn select
function, the timeout period is given in seconds and
microseconds in an argument of type
.Vt struct timeval ,
whereas for the
.Fn pselect
function the timeout period is given in seconds and nanoseconds
in an argument of type
.Vt struct timespec
.It
The
.Fn select
function has no
.Fa sigmask
argument.
It behaves as
.Fn pselect
does when
.Fa sigmask
is a null pointer.
.It
Upon successful completion, the
.Fn select
function might modify the object pointed to by the
.Fa Itimeout
argument.
.El
.Pp
The
.Fn select
and
.Fn pselect
functions support regular files, terminal and pseudo-terminal devices,
STREAMS-based files, FIFOs, pipes, and sockets.
The behavior of
.Fn select
and
.Fn pselect
on file descriptors that refer to other types of file is unspecified.
.Pp
The
.Fa nfds
argument specifies the range of file descriptors to be tested.
The first
.Fa nfds
descriptors are checked in each set; that is, the
descriptors from zero through
.Dq Li nfds - 1
in the descriptor sets are examined.
.Pp
If the
.Fa readfds
argument is not a null pointer, it points to an object of
type
.Vt 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.
.Pp
If the
.Fa writefds
argument is not a null pointer, it points to an object of
type
.Vt 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.
.Pp
If the
.Fa errorfds
argument is not a null pointer, it points to an object of
type
.Vt 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.
.Pp
Upon successful completion, the objects pointed to by the
.Fa readfds ,
.Fa writefds ,
and
.Fa errorfds
arguments are modified to indicate which file descriptors are ready for reading,
ready for writing, or have an error condition pending, respectively, and return
the total number of ready descriptors in all the output sets.
For each file descriptor less than
.Fa nfds ,
the corresponding bit will be set on successful completion if it was set on
input and the associated condition is true for that file descriptor.
.Pp
If none of the selected descriptors are ready for the requested operation, the
.Fn select
or
.Fn pselect
function blocks until at least one of the
requested operations becomes ready, until the timeout occurs, or until
interrupted by a signal.
The
.Fa timeout
parameter controls how long the
.Fn select
or
.Fn pselect
function takes before timing out.
If the
.Fa 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 returns.
If the
.Fa timeout
parameter is a null pointer, then the call to
.Fn select
or
.Fn pselect
blocks indefinitely until at least one descriptor meets the
specified criteria.
To effect a poll, the
.Fa timeout
parameter should not be a null pointer, and should point to a zero-valued
.Vt timespec
structure.
.Pp
The use of a
.Fa timeout
does not affect any pending timers set up by
.Xr alarm 2 ,
.Xr ualarm 3C ,
or
.Xr setitimer 2 .
.Pp
If
.Fa sigmask
is not a null pointer, then the
.Fn pselect
function replaces the signal mask of the process by the set of signals pointed
to by
.Fa sigmask
before examining the descriptors, and restores the signal mask of
the process before returning.
.Pp
A descriptor is considered ready for reading when a call to an input function
with
.Dv 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 will be considered ready for reading.)
.Pp
A descriptor is considered ready for writing when a call to an output function
with
.Dv O_NONBLOCK
clear would not block, whether or not the function would
transfer data successfully.
.Pp
If a socket has a pending error, it is 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, if the operation is meaningless for a particular file
type,
.Fn select
or
.Fn pselect
indicates that the descriptor is ready for read or write operations and
indicates that the descriptor has no exceptional condition pending.
.Pp
If a descriptor refers to a socket, the implied input function is the
.Xr recvmsg 3XNET
function with parameters requesting normal and ancillary
data, such that the presence of either type causes the socket to be marked as
readable.
The presence of out-of-band data is checked if the socket option
.Dv SO_OOBINLINE
has been enabled, as out-of-band data is enqueued with
normal data.
If the socket is currently listening, then it is marked as readable if an
incoming connection request has been received, and a call to the accept function
completes without blocking.
.Pp
If a descriptor refers to a socket, the implied output function is the
.Xr sendmsg 3XNET
function supplying an amount of normal data equal to the
current value of the
.Dv 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 is marked as writable.
.Pp
A socket is considered to have an exceptional condition pending if a receive
operation with
.Dv O_NONBLOCK
clear for the open file description and with the
.Dv MSG_OOB
flag set would return out-of-band data without blocking.
(It is protocol-specific whether the
.Dv MSG_OOB
flag would be used to read out-of-band data.)
A socket will also be considered to have an exceptional condition pending if an
out-of-band data mark is present in the receive queue.
.Pp
A file descriptor for a socket that is listening for connections will indicate
that it is ready for reading, when connections are available.
A file descriptor for a socket that is connecting asynchronously will indicate
that it is ready for writing, when a connection has been established.
.Pp
Selecting true for reading on a socket descriptor upon which a
.Xr listen 3XNET
call has been performed indicates that a subsequent
.Xr accept 3XNET
call on that descriptor will not block.
.Pp
If the
.Fa timeout
argument is not a null pointer, it points to an object of type
.Vt struct timeval
that specifies a maximum interval to wait for the
selection to complete.
If the
.Fa timeout
argument points to an object of type
.Vt struct timeval
whose members are 0,
.Fn select
does not block.
If the
.Fa timeout
argument is a null pointer,
.Fn select
blocks until an event causes one of the masks to be returned with a valid
(non-zero) value.
If the time limit expires before any event occurs that would cause one of the
masks to be set to a non-zero value,
.Fn select
completes successfully and returns 0.
.Pp
If the
.Fa readfds ,
.Fa writefds ,
and
.Fa errorfds
arguments are all null pointers and the
.Fa timeout
argument is not a null pointer,
.Fn select
or
.Fn pselect
blocks for the time specified, or until interrupted by a
signal.
If the
.Fa readfds ,
.Fa writefds ,
and
.Fa errorfds
arguments are all null pointers and the
.Fa timeout
argument is a null pointer,
.Fn select
blocks until interrupted by a signal.
.Pp
File descriptors associated with regular files always select true for ready to
read, ready to write, and error conditions.
.Pp
On failure, the objects pointed to by the
.Fa readfds ,
.Fa writefds ,
and
.Fa errorfds
arguments are not 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
.Fa readfds ,
.Fa writefds ,
and
.Fa errorfds
arguments have all bits set to 0.
.Pp
File descriptor masks of type
.Vt fd_set
can be initialized and tested with the macros
.Fn FD_CLR ,
.Fn FD_ISSET ,
.Fn FD_SET ,
and
.Fn FD_ZERO .
.Bl -tag -width indent
.It Fn FD_CLR "fd" "&fdset"
Clears the bit for the file descriptor
.Fa fd
in the file descriptor set
.Fa fdset .
.It Fn FD_ISSET "fd" "&fdset"
Returns a non-zero value if the bit for the file descriptor
.Fa fd
is set in
the file descriptor set pointed to by
.Fa fdset ,
and 0 otherwise.
.It Fn FD_SET "fd" "&fdset"
Sets the bit for the file descriptor
.Fa fd
in the file descriptor set
.Fa fdset
.It Fn FD_ZERO "&fdset"
Initializes the file descriptor set \fIfdset\fR to have zero bits for all file
descriptors.
.El
.Pp
The behavior of these macros is undefined if the
.Fa fd
argument is less than 0 or greater than or equal to
.Dv FD_SETSIZE ,
or if
.Fa fd
is not a valid file descriptor, or if any of the arguments are expressions
with side effects.
.Sh RETURN VALUES
On successful completion,
.Fn select
and
.Fn pselect
return the total
number of bits set in the bit masks.
Otherwise,
.Sy -1
is returned and
.Dv errno
is set to indicate the error.
.Pp
The
.Fn FD_CLR ,
.Fn FD_SET ,
and
.Fn FD_ZERO ,
macros return no value.
The
.Fn FD_ISSET
macro returns a non-zero value if the bit for the file
descriptor
.Fa fd
is set in the file descriptor set pointed to by
.Fa fdset ,
and
.Sy 0
otherwise.
.Sh ERRORS
The
.Fn select
and
.Fn pselect
functions will fail if:
.Bl -tag -width indent
.It Er EBADF
One or more of the file descriptor sets specified a file descriptor that is not
a valid open file descriptor.
.It Er EINTR
The function was interrupted before any of the selected events occurred and
before the timeout interval expired.
.Pp
If
.Dv SA_RESTART
has been set for the interrupting signal, it is implementation-dependent whether
.Fn select
restarts or returns with
.Dv EINTR
.It Er EINVAL
An invalid timeout interval was specified.
.It Er EINVAL
The
.Fa nfds
argument is less than 0 or greater than
.Dv FD_SETSIZE .
.It Er EINVAL
One of the specified file descriptors refers to a STREAM or multiplexer that is
linked (directly or indirectly) downstream from a multiplexer.
.It Er EINVAL
A component of the pointed-to time limit is outside the acceptable range:
.Dv t_sec
must be between 0 and 10^8, inclusive.
.Dv t_usec
must be greater than or equal to 0, and less than 10^6.
.El
.Sh USAGE
The
.Xr poll 2
function is preferred over this function.
.Pp
The use of a timeout does not affect any pending timers set up by
.Xr alarm 2 ,
.Xr ualarm 3C ,
or
.Xr setitimer 2 .
.Pp
On successful completion, the object pointed to by the
.Fa timeout
argument may be modified.
.Sh INTERFACE STABILITY
.Sy Standard
.Sh MT Level
.Sy MT-Safe
.Sh SEE ALSO
.Xr alarm 2 ,
.Xr fcntl 2 ,
.Xr poll 2 ,
.Xr read 2 ,
.Xr setitimer 2 ,
.Xr write 2 ,
.Xr ualarm 3C ,
.Xr accept 3SOCKET ,
.Xr listen 3SOCKET ,
.Xr attributes 7 ,
.Xr standards 7