select
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, respec-
tively.
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, ter-
minal 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
ready for writing, or have an error condition pending, respectively,
and shall return the total number of ready descriptors in all the out-
put sets. For each file descriptor less than nfds, the corresponding
bit shall be set on 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 opera-
tion, 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 inter-
val 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(), ualarm(), 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 inter-
val 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 imple-
mentation 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 process by the set of signals pointed to
by sigmask before examining the descriptors, and shall restore the sig-
nal mask of the process 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 descrip-
tor 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 excep-
tional 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 meaning-
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 cur-
rent 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 con-
nection 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 descrip-
tion and with the MSG_OOB flag set would return out-of-band data with-
out 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 proto-
col-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 inter-
rupted 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 sig-
nal.
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 spec-
ified 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.
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 before any of the selected events
occurred and before the timeout interval expired.
If SA_RESTART has been set for the interrupting signal, it is implemen-
tation-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 mul-
tiplexer that is linked (directly or indirectly) downstream from
a multiplexer.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
None.
RATIONALE
In previous 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 defini-
tions for the pselect() and select() functions. Backwards-compatibility
to existing XSI implementations is handled by allowing <sys/time.h> to
include <sys/select.h>.
FUTURE DIRECTIONS
None.
SEE ALSO
accept() , alarm() , connect() , fcntl() , poll() , read() , recvmsg()
, sendmsg() , setitimer() , ualarm() , write() , the Base Definitions
volume of IEEE Std 1003.1-2001, <sys/select.h>, <sys/time.h>
IEEE/The Open Group 2003 PSELECT(P)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2012
Hurricane Electric.
All Rights Reserved.