select

Syntax

#include <time.h> #include <string.h> int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)

Description

This function waits for files to be ready for input or output, or to have exceptional condition pending, or for a timeout.

Each fd_set variable is a bitmap representation of a set of file descriptors, one bit for every descriptor. The following macros shall be used to deal with these sets (in the table below, p is a pointer to an fd_set object and n is a file descriptor):

FD_ZERO(p)

Initialize the set p to all zeros.

FD_SET(n, p)

Set member n in set p.

FD_CLR(n, p)

Clear member n in set p.

FD_ISSET(n, p)

Return the value of member n in set p.

FD_SETSIZE

The maximum number of descriptors supported by the system.

The nfds parameter is the number of bits to be examined in each of the fd_set sets: the function will only check file descriptors 0 through nfds - 1, even if some bits are set for descriptors beyond that.

On input, some of the bits of each one of the fd_set sets for which the function should wait, should be set using the FD_SET macro. select examines only those descriptors whose bits are set.

Any of readfds, writefds, and exceptfds can be a NULL pointer, if the caller is not interested in testing the corresponding conditions.

On output, if select returns a non-negative value, each non-NULL argument of the three sets will be replaced with a subset in which a bit is set for every descriptor that was found to be, respectively, ready for input, ready for output, and pending an exceptional condition. Note that if select returns -1, meaning a failure, the descriptor sets are unchanged, so you should always test the return value before looking at the bits in the returned sets.

The timeout value may be a NULL pointer (no timeout, i.e., wait forever), a pointer to a zero-value structure (poll mode, i.e., test once and exit immediately), or a pointer to a struct timeval variable (timeout: select will repeatedly test all the descriptors until some of them become ready, or the timeout expires).

struct timeval is defined as follows:

struct timeval { time_t tv_sec; long tv_usec; };

Return Value

On successfull return, select returns the number of files ready, or 0, if the timeout expired. The input sets are replaced with subsets that describe which files are ready for which operations. If select returns 0 (i.e., the timeout has expired), all the non-NULL sets have all their bits reset to zero.

On failure, select returns -1, sets errno to a suitable value, and leaves the descriptor sets unchanged.

Portability

ANSI/ISO C	No
POSIX	No

Example

struct timeval timeout; fd_set read_fds, write_fds; int i, select_result; timeout.tv_sec = 5; /* 5-second timeout */ timeout.tv_usec = 0; /* Display status of the 5 files open by default. */ for (i = 0; i < 5; i++) { FD_ZERO (&read_fds); FD_SET (i, &read_fds); select_result = select (i + 1, &read_fds, 0, 0, &timeout); if (select_result == -1) { fprintf(stderr, "%d: Failure for input", i); perror(""); } else fprintf(stderr, "%d: %s ready for input\n", i, select_result ? "" : "NOT"); FD_ZERO (&write_fds); FD_SET (i, &write_fds); select_result = select (i + 1, 0, &write_fds, 0, &timeout); if (select_result == -1) { fprintf(stderr, "%d: Failure for output", i); perror(""); } else fprintf(stderr, "%d: %s ready for output\n", i, select_result ? "" : "NOT"); }

Implementation Notes

The following notes describe some details pertinent to the DJGPP implementation of select:

• While select waits for the timeout to expire, it repeatedly calls the __dpmi_yield function (see section __dpmi_yield), so that any other programs that run at the same time (e.g., on Windows) get more CPU time.

• A file handle that belongs to a FILE object created by fopen or fdopen (see section fopen) for which feof or ferror return non-zero, will be reported in the exceptfds set; also, such a handle will be reported not input-ready if there are no pending buffered characters in the FILE object. This might be a feature or a bug, depending on your point of view; in particular, Unix implementations usually don't check buffered input. Portable programs should refrain from mixing select with buffered I/O.

• DOS doesn't support exceptional conditions, so file handles used for unbuffered I/O will never be marked in exceptfds.

• DOS always returns an output-ready indication for a file descriptor connected to a disk file. So use of writefds is only meaningful for character devices.

• The usual text-mode input from the keyboard and other character devices is line-buffered by DOS. This means that if you type one character, select will indicate that file handle 0 is ready for input, but a call to getc will still block until the Enter key is pressed. If you need to make sure that reading a single character won't block, you should read either with BIOS functions such as getkey (see section getkey) or with raw input DOS functions such as getch (see section getch), or switch the handle to binary mode with a call to setmode (see section setmode).