SELECT(2) BSD Programmer's Manual SELECT(2)NAME
pselect select - synchronous I/O multiplexing
SYNOPSIS
#include <sys/types.h>
#include <sys/time.h>
#include <sys/select.h>
#include <signal.h>
int
pselect(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
const struct timespec *timeout, const sigset_t *sigmask);
int
select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
const struct timeval *timeout);
fd_set *
FD_ALLOC(int n);
void
FD_CLR(int fd, fd_set *fdset);
void
FD_COPY(fd_set *from_fdset, fd_set *to_fdset);
int
FD_ISSET(int fd, fd_set *fdset);
void
FD_NCOPY(int n, fd_set *from_fdset, fd_set *to_fdset);
void
FD_NZERO(int n, fd_set *fdset);
fd_set *
FD_REALLOC(fd_set *fdset, int oldn, int newn);
void
FD_SET(int fd, fd_set *fdset);
void
FD_ZERO(fd_set *fdset);
DESCRIPTION
The pselect() and select() functions examine the I/O descriptor sets
whose addresses are passed in readfds, writefds, and exceptfds to see if
some of their descriptors are ready for reading, are ready for writing,
or have an exceptional condition pending, respectively. The two func-
tions are identical except for the type and format of the timeout value,
and the additional sigmask parameter supplied to the pselect() call. The
first nfds descriptors are checked in each set; i.e., the descriptors
from 0 through nfds-1 in the descriptor sets are examined.
The pselect() and select() functions replace the given descriptor sets
with subsets consisting of those descriptors that are ready for the re-
quested operation, and return the total number of ready descriptors in
the sets.
If timeout is a non-NULL pointer, it specifies a maximum interval to wait
for the selection to complete. If timeout is a NULL pointer, the select
blocks indefinitely. To poll the descriptors, the timeout argument
should be non-NULL, pointing to a zero-valued timespec or timeval struc-
ture. If the sigmask parameter to pselect() is not NULL, it points to a
signal mask that replaces the previous signal mask for the process for
the duration of the call, and the previous mask is restored upon return;
see sigprocmask(3). This is normally used so that signals can be blocked
while preparing for a call to pselect(), and atomically unblocking the
signals while selecting.
Any of readfds, writefds, and exceptfds may be given as NULL pointers if
no descriptors are of interest.
The descriptor sets are stored as bit fields in arrays of integers.
The following macros are provided for, setting, clearing and testing en-
tries in the descriptor sets:
FD_SET(int fd, fd_set *fdset);
Sets the descriptor fd in the descriptor set fdset.
FD_CLR(int fd, fd_set *fdset);
Unsets the descriptor fd in the descriptor set fdset.
FD_ISSET(int fd, fd_set *fdset);
Returns non-zero if fd is a member of the descriptor set fdset, ze-
ro otherwise.
Descriptor sets adequate to handle FD_SETSIZE descriptors may be declared
with the fd_set type defined in <sys/select.h>. FD_SETSIZE is a constant
defined by the header file <sys/select.h>, and is currently set to 256.
The following macros are provided for manipulating such descriptor sets:
FD_COPY(fd_set *from_fdset, fd_set *to_fdset);
Copies the descriptor set from_fdset to the descriptor set
to_fdset.
FD_ZERO(fd_set *fdset);
Initializes the descriptor set fdset to the empty set.
The behavior of the FD_COPY() and FD_ZERO() macros is undefined if a de-
scriptor value is greater than or equal to FD_SETSIZE.
As a process may have more file descriptors than the value of FD_SETSIZE,
the following additional macros are provided for creating and manipulat-
ing such descriptor sets:
FD_ALLOC(int n);
Allocate a descriptor set sufficient for n descriptors. A pointer
to the descriptor set is returned, or NULL if the allocation
failed. The allocated descriptor set is initialized to the empty
set. The allocated descriptor set may be deallocated with the
free() function when it is no longer needed.
FD_REALLOC(fd_set *fdset, int oldn, int newn);
Increase the size of a descriptor set previously allocated to be
sufficient for oldn descriptors to be sufficient for newn descrip-
tors. A pointer to the descriptor set is returned, or NULL if the
allocation failed. The newly allocated portion of the descriptor
set is initialized to the empty set. The allocated descriptor set
may be deallocated with the free() function when it is no longer
needed.
FD_NCOPY(int n, fd_set *from_fdset, fd_set *to_fdset);
Copies the descriptor set from_fdset, allocated to be sufficient
for n descriptors, to the descriptor set to_fdset.
FD_NZERO(int n, fd_set *fdset);
Initializes the descriptor set fdset, allocated to be sufficient
for n descriptors, to the empty set.
RETURN VALUES
The pselect() and select() functions return the number of ready descrip-
tors that are contained in the descriptor sets, or -1 if an error oc-
curred. If the time limit expires, the functions return 0. If the func-
tions return with an error, including one due to an interrupted call, the
descriptor sets will be unmodified.
ERRORS
An error return from pselect() or select() indicates:
[EBADF] One of the descriptor sets specified an invalid descriptor.
[EFAULT] One of the parameters points outside the allocated address
space.
[EINTR] A signal was delivered before the time limit expired and
before any of the selected events occurred.
[EINVAL] The specified time limit is invalid. One of its components
is negative or too large.
The macros FD_ALLOC() and FD_REALLOC() may fail and set errno for any of
the errors specified for the library function malloc(3).
SEE ALSOaccept(2), connect(2), gettimeofday(2), read(2), recv(2), send(2),
write(2), free(3)sigprocmask(3)STANDARDS
The select function call appeared in 4.2BSD. The pselect function ap-
peared in BSD/OS 4.0, based on draft 6.6 of the POSIX networking stan-
dard, to become IEEE Std 1003.12. Both functions are expected to conform
to that standard.
4.2 Berkeley Distribution March 25, 1994 3
