NAME

select - synchronous I/O multiplexing

 SYNOPSIS

#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);

 DESCRIPTION

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 pseudo-terminal 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.

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 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 struct timeval that specifies a maximum interval to wait for the selection to complete. If the timeout argument points to an object of type struct timeval 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.

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.

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 file descriptors, the objects pointed to by the readfds, writefds, and errorfds arguments have all bits set to 0.

File descriptor masks of type fd_set can be initialised 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 descriptor set fdset.

FD_ZERO(&fdset)

Initialises 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, or if any of the arguments are expressions with side effects.

 RETURN VALUE

FD_CLR(), FD_SET() and FD_ZERO() return no value. FD_ISSET() 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.

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

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.

[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].

[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 multiplexer that is linked (directly or indirectly) downstream from a multiplexer.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

fcntl(), poll(), read(), write(), <sys/time.h>.