 |
Index for
Section 2 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
select(2)
NAME
select - Synchronous I/O multiplexing
SYNOPSIS
#include <sys/time.h>
int select(
int nfds,
fd_set *readfds,
fd_set *writefds,
fd_set *exceptfds,
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 );
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
select(): XSH4.2, XSH5.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
nfds Specifies the number of open objects that may be ready for reading
or writing or that have exceptions pending. The nfds parameter
cannot be greater than FD_SETSIZE.
readfds Points to an I/O descriptor set consisting of file descriptors of
objects opened for reading. When the readfds parameter is a null
pointer, the read I/O descriptor set is ignored by the select()
function.
writefds
Points to an I/O descriptor set consisting of file descriptors for
objects opened for writing. When the writefds parameter is a null
pointer, the write I/O descriptor set is ignored.
exceptfds
Points to an I/O descriptor set consisting of file descriptors for
objects opened for reading or writing that have an exception
pending. When the exceptfds parameter is a null pointer, the
exception I/O descriptor set is ignored.
timeout Points to a type timeval structure that specifies the maximum time
to wait for a response to a select() function. When the timeout
parameter has a nonzero value, the maximum time interval to wait
for the select() function to complete is specified by values stored
in space reserved by the type timeval structure pointed to by the
timeout parameter.
When the timeout parameter is a null pointer, the select() function
blocks indefinitely. To poll, the timeout parameter should be
specified as a nonzero value and point to a zero-valued timeval
structure.
The use of a timeout does not affect any pending timers set up by
alarm(), unalarm(), or settimer().
fd Specifies a file descriptor.
fdset Points to an I/O descriptor set.
DESCRIPTION
The select() function checks the status of objects identified by bit masks
called I/O descriptor sets. Each I/O descriptor set consists of an array of
bits whose relative position and state represent a file descriptor and the
status of its corresponding object. There is an I/O descriptor set for
reading, writing, and for pending exceptions. These I/O descriptor sets are
pointed to by the readfds, writefds, and exceptfds parameters,
respectively. The I/O descriptor sets provide a means of monitoring the
read, write, and exception status of objects represented by file
descriptors.
The status of nfds-1 file descriptors in each referenced I/O descriptor set
is checked when the select() function is called. The select() function
returns a modified I/O descriptor set, which has the following
characteristics: for any selected I/O descriptor set pointed to by the
readfds, writefds, or exceptfds parameters, if the state of any bit
corresponding with an active file descriptor is set on entry, when the
object represented by the set bit is ready for reading, writing, or its
exception condition has been satisfied, a corresponding bit position is
also set in the returned I/O descriptor set pointed to by the readfds,
writefds, or exceptfds parameters.
When it returns successfully, select() first replaces the original I/O
descriptor sets with the corresponding I/O descriptor sets (that have a set
bit for each file descriptor representing those objects that are ready for
the requested operation). Then, the function returns the total number of
ready objects represented by set bits in all the I/O descriptor sets.
Note: When objects are ready for the requested operation, the operation
will not block. This does not necessarily mean, however, that data is
available for the operation. See read(2) and write(2) for information on
when these calls would block.
After an I/O descriptor set is created, it may be modified with the
following macros:
FD_CLR(fd, &fdset)
Clears the I/O descriptor bit specified by file descriptor fd in the
I/O descriptor set addressed by fdset.
FD_ISSET(fd, &fdset)
Returns a nonzero value when the I/O descriptor bit for fd is included
in the I/O descriptor set addressed by fdset. Otherwise 0 (zero) is
returned.
FD_SET(fd, &fdset)
Includes the particular I/O descriptor bit specified by fd in the I/O
descriptor set addressed by fdset.
FD_ZERO(&fdset)
Initializes the I/O descriptor set addressed by fdset to a null value.
The behavior of these macros is undefined when parameter fd has a value
less than 0 (zero) or greater than or equal to FD_SETSIZE, which is
normally at least equal to the maximum number of file descriptors supported
by the system.
The select() function supports regular files, terminal and pseudo-terminal
devices, STREAMS-based files, FIFOs, and pipes. The behavior of the
select() function on file descriptors that refer to other types of files is
unspecified.
For sockets, a file descriptor for a socket that is listening for
connections indicates that it is ready for reading when connections are
available. A file descriptor for a socket that is connecting asynchronously
indicates that it is ready for writing after a connection is established.
NOTES
By default, this function supports up to 4K open file descriptors per
process. However, up to 64K open file descriptors per process is supported
if an application has enabled this capability by using the SSI_FD_NEWMAX
operation in a setsysinfo() call and the RLIMIT_NOFILE argument in a
setrlimit() call. For summary information on retrieving and setting limits
on the number of open file descriptors per process, see the description of
the open_max_hard and open_max_soft system attributes in sys_attrs_proc(5).
In addition to the requirement that limits greater than 4K must be enabled
by the setsysinfo() and setrlimit() calls, programmers must specify an
alternate value for FD_SETSIZE--one that does not exceed 64K--before they
include <sys/select.h> in a program to be compiled. If not set to be a
higher value in the program before compilation, FD_SETSIZE is set in the
<sys/select.h> header file to be 4K.
For a more in-depth discussion of this subject, refer to the section about
tuning open file limits in the System Configuration and Tuning manual.
RETURN VALUES
Upon successful completion, the select() function returns the number of
ready objects represented by corresponding file descriptor bits in the I/O
descriptor sets. When an error occurs, -1 is returned and errno is set to
indicate the error.
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 (zero).
When select() returns an error, including a process interrupt, the I/O
descriptor sets pointed to by the readfds, writefds, and exceptfds
parameters remain unmodified.
ERRORS
The select() function sets errno to the specified values for the following
conditions:
[EBADF] One or more of the I/O descriptor sets specified an invalid file
descriptor.
[EINTR] A signal was delivered before the time limit specified by the
timeout parameter expired and before any of the selected events
occurred.
[EINVAL]
The time limit specified by the timeout parameter is invalid.
The nfds parameter is less than 0, or greater than or equal to
FD_SETSIZE.
One of the specified file descriptors refers to a STREAM or
multiplexer that is linked (directly or indirectly) downstream from
a multiplexer.
[EAGAIN]
[Tru64 UNIX] Allocation of internal data structures failed. A
later call to the select() function may complete successfully.
SEE ALSO
Functions: accept(2), connect(2), getdtablesize(2), poll(2) read(2),
recv(2), send(2), setsysinfo(2), write(2)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|