FD_SET(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

NAME

select, FD_SET, FD_CLR, FD_ISSET, FD_ZERO- 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_SET(int fd, fd_set *fdset);
void FD_CLR(int fd, fd_set *fdset);
int FD_ISSET(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 behavior 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 readfs 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 writefs 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 readfs , writefs , 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.

If the readfs , writefs , 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 readfs , writefs , 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 readfs , writefs , 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 readfs , writefs , and errorfds arguments have all bits set to 0.

A file descriptor for a socket that is listening for connections will indicate that it is ready for reading, when connections are available. A file descriptor for a socket that is connecting asynchronously will indicate that it is ready for writing, when a connection has been established.

Selecting true for reading on a socket descriptor upon which a listen(3SOCKET) call has been performed indicates that a subsequent accept(3SOCKET) call on that descriptor will not block.

File descriptor masks of type fd_set can be initialized and tested with the macros FD_CLR() , FD_ISSET() , FD_SET() , and FD_ZERO() .

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 )

Initializes the file descriptor set fdset to have zero bits for all file descriptors.

The behavior of these macros is undefined if the fd argument is less than 0 or greater than or equal to FD_SETSIZE.

RETURN VALUES

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

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

The select() function will fail if:

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 or equal to 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.

EINVAL

A component of the pointed-to time limit is outside the acceptable range: t_sec must be between 0 and 10⁸ , inclusive. t_usec must be greater than or equal to 0 , and less than 10⁶ .

USAGE

The poll(2) function is preferred over this function. It must be used when the number of file descriptors exceeds FD_SETSIZE .

The use of a timeout does not affect any pending timers set up by alarm(2) , ualarm(3C) or setitimer(2) .

On successful completion, the object pointed to by the timeout argument may be modified.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

SEE ALSO

alarm(2) , fcntl(2) , poll(2) , read(2) , setitimer(2) , write(2) , accept(3SOCKET) , listen(3SOCKET) , ualarm(3C) , attributes(5)

NOTES

The default value for FD_SETSIZE (currently 1024) is larger than the default limit on the number of open files. To accommodate 32-bit applications that wish to use a larger number of open files with select() , it is possible to increase this size at compile time by providing a larger definition of FD_SETSIZE before the inclusion of <sys/types.h> . The maximum supported size for FD_SETSIZE is 65536. The default value is already 65536 for 64-bit applications.

SunOS 5.8  Last Revised 22 Apr 1998

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES