NAME

select − Synchronous I/O multiplexing

SYNOPSIS

#include<sys/types.h> #include<sys/time.h> int select(
int nfds,
fd_set ∗readfds,
fd_set ∗writefds,
fd_set ∗exceptfds,
struct timeval ∗timeout) ; FD_SET(
int fd,
fd_set ∗fdset ); FD_CLR(
int fd,
fd_set ∗fdset ); FD_ISSET(
int fd,
fd_set ∗fdset ); FD_ZERO(
fd_set ∗fdset );

PARAMETERS

nfdsSpecifies 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. 

readfdsPoints 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. 

writefdsPoints 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. 

exceptfdsPoints 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. 

timeoutPoints to a type timeval structure that specifies the 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. 

fdSpecifies a file descriptor. 

fdsetPoints 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 theselect() 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, and 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. 

On return, the select() function 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. The total number of ready objects represented by set bits in all the I/O descriptor sets is returned by the select() function. 

After an I/O descriptor set is created, it may be modified with the following macros:

FD_ZERO(&fdset)
Initializes the I/O descriptor set addressed by fdset to a null value. 

FD_SET(fd, &fdset)
Includes the particular I/O descriptor bit specified by fd in the I/O descriptor set addressed by fdset. 

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. 

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. 

NOTES

Although the getdtablesize() function is intended to allow users to write programs independently of the kernel limit on the number of open files, the dimensioning of a sufficiently large bit field for select()  remains a problem.  The default size FD_SETSIZE (currently 256) is larger than the current kernel limit on the permitted number of open files.  To accommodate programs that specify more open files with the select() function, it is possible to specify an alternate value for FD_SETSIZE before including the sys/types.h header file. 

FD_SETSIZE is set to the current kernel limit on the permitted number of open files.  To accommodate programs that need to specify alternate fd_set sizes, it is possible to specify an alternative value for FD_SETSIZE before including the sys/types.h header file. 

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.  When the time limit specified by values pointed to by the timeout parameter expires, this function returns the value 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

If the select() function fails, errno may be set to one of the following values:

[EBADF]One of the I/O descriptor sets you specified is invalid. 

[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.  One of its components is negative or too large. 

[EAGAIN]Allocation of internal data structures failed.  A later call to the select() function may complete successfully. 

RELATED INFORMATION

Functions: accept(2), connect(2), send(2), getdtablesize(2), poll(2) read(2), recv(2), write(2)