select(2) select(2)
NAME [Toc] [Back]
select, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - synchronous I/O
multiplexing
SYNOPSIS [Toc] [Back]
#include <sys/time.h>
int select(int nfds, fd_set *readfds, fd_set *writefds,
fd_set *errorfds, struct timeval *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);
For Backward Compatibility Only: (_XOPEN_SOURCE_EXTENDED not defined)
#include <time.h>
int select(size_t nfds, int *readfds, int *writefds,
int *exceptds, const struct timeval *timeout);
DESCRIPTION [Toc] [Back]
The select() function indicates which of the specified file
descriptors is ready for reading, ready for writing, or has an error
condition pending. If the specified condition is false for all of the
specified file descriptors, select() blocks, up to the specified
timeout interval, until the specified condition is true for at least
one of the specified file descriptors.
The select() function supports regular files, terminal and pseudoterminal
devices, STREAMS-based files, FIFOs and pipes. The behaviour
of select() on file descriptors that refer to other types of file is
unspecified.
The nfds argument specifies the range of file descriptors to be
tested. The select() function tests file descriptors in the range of
0 to nfds -1. File descriptor f is represented by the bit 1<<f in the
masks. More formally, a file descriptor is represented by:
fds[(f / BITS_PER_INT)] & (1 << (f % BITS_PER_INT))
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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
select(2) select(2)
If the writefds 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 write, and on output indicates which file
descriptors are ready to write.
If the errorfds 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 error conditions pending, and on output indicates which
file descriptors have error conditions pending.
On successful completion, the objects pointed to by the readfds,
writefds, and errorfds arguments are modified to indicate which file
descriptors are ready for reading, ready for writing, or have an error
condition pending, respectively. For each file descriptor less than
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.
If the timeout argument is not a null pointer, it points to an object
of type structtimeval that specifies a maximum interval to wait for
the selection to complete. If the timeout argument points to an
object of type structtimeval whose members are 0, select() does not
block. If the timeout argument is a null pointer, 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,
select() completes successfully and returns 0.
Implementations may place limitations on the maximum timeout interval
supported. On all implementations, the maximum timeout interval
supported will be at least 31 days. If the timeout argument specifies
a timeout interval greater than the implementation- dependent maximum
value, the maximum value will 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 will be rounded up to the next supported value.
If the readfds, writefds, and errorfds arguments are all null pointers
and the timeout argument is not a null pointer, select() blocks for
the time specified, or until interrupted by a signal. If the readfds,
writefds, and errorfds arguments are all null pointers and the timeout
argument is a null pointer, select() blocks until interrupted by a
signal.
File descriptors associated with regular files 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 are not modified. If the timeout interval expires
without the specified condition being true for any of the specified
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
select(2) select(2)
file descriptors, the objects pointed to by the readfds, writefds, and
errorfds arguments have all bits set to 0.
Ttys and sockets are ready for reading or writing, respectively, if a
read() or write() would not block for one or more of the following
reasons:
+ input data is available.
+ output data can be accepted.
+ an error condition exists, such as a broken pipe, no carrier,
or a lost connection.
TCP sockets select true on reads only for normal data. They do not
select true on reads if out-of-band data ("urgent" data) arrives.
TCP sockets select true on exceptions for out-of-band data.
AF_CCITT sockets select true on reads for normal and out-of-band data
and information, including supervisory frames.
Pipes are ready for reading if there is any data in the pipe, or if
there are no writers left for the pipe. Pipes are ready for writing
if there is room for more data in the pipe AND there are one or more
readers for the pipe, OR there are no readers left for the pipe.
select() returns the same results for a pipe whether a file descriptor
associated with the read-only end or the write-only end of the pipe is
used, since both file descriptors refer to the same underlying pipe.
So a select() of a read-only file descriptor that is associated with a
pipe can return ready to write, even though that particular file
descriptor cannot be written to.
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 behaviour
is undefined.
FD_CLR(fd, &fdset) Clears the bit for the file
descriptor fd in the file
descriptor set fdset.
FD_ISSET(fd, &fdset) Returns 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.
FD_SET(fd, &fdset) Sets the bit for the file
descriptor fd in the file
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
select(2) select(2)
descriptor set fdset.
FD_ZERO(&fdset) Initializes the file descriptor set
fdset to have zero bits for all
file descriptors. The behaviour of
these macros is undefined if the fd
argument is less than 0 or greater
than or equal to FD_SETSIZE.
The use of a timeout does not affect any pending timers set up by
alarm(), ualarm(), or setitimer().
On successful completion, the object pointed to by the timeout
argument may be modified.
The FD_SETSIZE is used in the definition of fd_set structure. It is
set to a value of 2048 to accommodate 2048 file descriptors. Any user
code that uses FD_SETSIZE or the structure fd_set should redefine
FD_SETSIZE to a smaller value (greater than or equal to the number of
open files the process will have) in order to save space. Similarly,
any user code that wants to test more than 2048 file descriptors
should redefine FD_SETSIZE to the required higher value.
The user can also allocate the space for fd_set structure dynamically,
depending upon the number of file descriptors to be tested. The
following code segment illustrates the basic concepts.
int num_of_fds,s;
struct fd_set *f;
/*
* Set num_of_fds to the required value.
* User can set it to the maximum possible value the kernel is
* configured for, by using sysconf(_SC_OPEN_MAX).
* Note that, if you are not using these many files, you are
* wasting too much space.
*/
num_of_fds = sysconf(_SC_OPEN_MAX);
s = sizeof(long);
/*
* howmany is a macro defined in sys/types.h
*/
f = (struct fd_set *)malloc(s*howmany(num_of_fds, s*8);
/*
* Use f wherever struct fd_set * is used.
* It can be used to test num_of_fds file descriptors.
*/
RETURN VALUE [Toc] [Back]
FD_CLR(), FD_SET(), and FD_ZERO() return no value. FD_ISSET()
returns a non-zero value if the bit for the file descriptor fd is set
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
select(2) select(2)
in the file descriptor set pointed to by fdset, and 0 otherwise.
On successful completion, select() returns the total number of bits
set in the bit masks. Otherwise, -1 is returned, and errno is set to
indicate the error.
ERRORS [Toc] [Back]
Under the following conditions, select() fails and sets errno to:
[EBADF] One or more of the file descriptor sets specified
a file descriptor that is not a valid open file
descriptor. This could happen either if the file
descriptor sets are not initialized or nfds
argument is greater than FD_SETSIZE.
[EINTR] The select() 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
implementation-dependent whether select() restarts
or returns with [EINTR].
[EFAULT] One or more of the pointers was invalid. The
reliable detection of this error is implementation
dependent.
[EINVAL] An invalid timeout interval was specified. Valid
values for number of microseconds should be a
non-negative integer less than 1,000,000 and, for
number of seconds, should be a non-negative
integer.
[EINVAL] The nfds argument is less than 0, or is greater
than or equal to the value of MAXFUPLIM, which
specifies the absolute maximum number of files a
process can have open at one time. If the
resource limit RLIMIT_NOFILE for a process is less
than or equal to 2048, MAXFUPLIM is considered to
be 2048.
[EINVAL] One of the specified file descriptors refers to a
STREAM or multiplexer that is linked (directly or
indirectly) downstream from a multiplexer.
EXAMPLES [Toc] [Back]
The following call to select() checks if any of 4 terminals are ready
for reading. select() times out after 5 seconds if no terminals are
ready for reading. Note that the code for opening the terminals or
reading from the terminals is not shown in this example. Also, note
that this example must be modified if the calling process has more
than 32 file descriptors open. Following this first example is an
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
select(2) select(2)
example of select with more than 32 file descriptors.
#define MASK(f) (1 << (f))
#define NTTYS 4
int tty[NTTYS];
int ttymask[NTTYS];
int readmask = 0;
int readfds;
int nfound, i;
struct timeval timeout;
/* First open each terminal for reading and put the
* file descriptors into array tty[NTTYS]. The code
* for opening the terminals is not shown here.
*/
for (i=0; i < NTTYS; i++) {
ttymask[i] = MASK(tty[i]);
readmask |= ttymask[i];
}
timeout.tv_sec = 5;
timeout.tv_usec = 0;
readfds = readmask;
/* select on NTTYS+3 file descriptors if stdin, stdout
* and stderr are also open
*/
if ((nfound = select (NTTYS+3, &readfds, 0, 0, &timeout)) == -1)
perror ("select failed");
else if (nfound == 0)
printf ("select timed out \n");
else for (i=0; i < NTTYS; i++)
if (ttymask[i] & readfds)
/* Read from tty[i]. The code for reading
* is not shown here.
*/
else printf ("tty[%d] is not ready for reading \n",i);
The following example is the same as the previous example, except that
it works for more than 32 open files. Definitions for howmany,
fd_set, and NFDBITS are in <sys/types.h>.
#include <sys/param.h>
#include <sys/types.h>
#include <sys/time.h>
#define MASK(f) (1 << (f))
#define NTTYS NOFILE - 3
#define NWORDS howmany(FD_SETSIZE, NFDBITS)
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
select(2) select(2)
int tty[NTTYS];
int ttymask[NTTYS];
struct fd_set readmask, readfds;
int nfound, i, j, k;
struct timeval timeout;
/* First open each terminal for reading and put the
* file descriptors into array tty[NTTYS]. The code
* for opening the terminals is not shown here.
*/
for (k=0; k < NWORDS; k++)
readmask.fds_bits[k] = 0;
for (i=0, k=0; i < NTTYS && k < NWORDS; k++)
for (j=0; j < NFDBITS && i < NTTYS; j++, i++) {
ttymask[i] = MASK(tty[i]);
readmask.fds_bits[k] |= ttymask[i];
}
timeout.tv_sec = 5;
timeout.tv_usec = 0;
for (k=0; k < NWORDS; k++)
readfds.fds_bits[k] = readmask.fds_bits[k];
/* select on NTTYS+3 file descriptors if stdin, stdout
* and stderr are also open
*/
if ((nfound = select (NTTYS+3, &readfds, 0, 0, &timeout)) == -1)
perror ("select failed");
else if (nfound == 0)
printf ("select timed out \n");
else for (i=0, k=0; i < NTTYS && k < NWORDS; k++)
for (j=0; j < NFDBITS && i < NTTYS; j++, i++)
if (ttymask[i] & readfds.fds_bits[k])
/* Read from tty[i]. The code for reading
* is not shown here.
*/
else printf ("tty[%d] is not ready for reading \n",i);
WARNINGS [Toc] [Back]
Check all references to signal(5) for appropriateness on systems that
support sigvector(). sigvector() can affect the behavior described on
this manpage.
The file descriptor masks are always modified on return, even if the
call returns as the result of a timeout.
DEPENDENCIES [Toc] [Back]
select() supports the following devices and file types:
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
select(2) select(2)
+ pipes
+ fifo special files (named pipes)
+ all serial devices
+ All ITEs (internal terminal emulators) and HP-HIL input
devices
+ lan(7) special files
+ pty(7) special files
+ sockets
AUTHOR [Toc] [Back]
select() was developed by HP and the University of California,
Berkeley.
SEE ALSO [Toc] [Back]
fcntl(2), read(2), write(2), poll(2), thread_safety(5).
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003 [ Back ] |
