Synchronous Input and Output

poll(2) provides a mechanism to identify the Streams over which a user can send or receive data. For each Stream of interest, users can specify one or more events about which they should be notified. The types of events that can be polled are POLLIN, POLLRDNORM, POLLRDBAND, POLLPRI, POLLOUT, POLLWRNORM, POLLWRBAND, detailed in Table 3-2.

Some of the events may not be applicable to all file types. For example, it is not expected that the POLLPRI event is generated when polling a non-STREAMS character device. POLLIN, POLLRDNORM, POLLRDBAND, and POLLPRI are set even if the message is of zero length.

poll(2) checks each file descriptor for the requested events and, on return, indicates which events have occurred for each file descriptor. If no event has occurred on any polled file descriptor, poll(2) blocks until a requested event or timeout occurs. poll(2) takes the following arguments:

• An array of file descriptors and events to be polled.

• The number of file descriptors to be polled.

• The number of milliseconds poll should wait for an event if no events are pending (-1 specifies wait forever).

Example 3-5 shows the use of poll(2). Two separate minor devices of the communications driver are opened, thereby establishing two separate Streams to the driver. The pollfd entry is initialized for each device. Each Stream is polled for incoming data. If data arrive on either Stream, data is read and then written back to the other Stream.

Example 3-5 Polling

#include <sys/stropts.h>
#include <fcntl.h>
#include <poll.h>

#define NPOLL 2						/* number of file descriptors to poll */
int
main()
{
 	struct pollfd pollfds[NPOLL];
 	char buf[1024];
 	int count, i;

		if ((pollfds[0].fd = open("/dev/ttya", O_RDWR|O_NONBLOCK)) < 0) {
 			perror("open failed for /dev/ttya");
 			exit(1);
 	}
 	if ((pollfds[1].fd = open("/dev/ttyb", O_RDWR|O_NONBLOCK)) < 0) {
 			perror("open failed for /dev/ttyb");
 			exit(2);
 	}

The variable pollfds is declared as an array of the pollfd structure, defined in <poll.h>, and has the format:

struct pollfd {
		int fd;             /* file descriptor */
		short events;       /* requested events */
		short revents;      /* returned events */
}

For each entry in the array, fd specifies the file descriptor to be polled and events is a bitmask that contains the bitwise inclusive OR of events to be polled on that file descriptor. On return, the revents bitmask indicates which of the requested events has occurred.

The example continues to process incoming data, as shown below:

pollfds[0].events = POLLIN;	/* set events to poll */
	pollfds[1].events = POLLIN;	/* for incoming data */
	while (1) {
		/* poll and use -1 timeout (infinite) */
		if (poll(pollfds, NPOLL, -1) < 0) {
			perror("poll failed");
			exit(3);
		}
		for (i = 0; i < NPOLL; i++) {
			switch (pollfds[i].revents) {
				default:						/* default error case */
					fprintf(stderr,"error event\n");
					exit(4);

				case 0:						/* no events */
					break;

				case POLLIN:
					/*echo incoming data on "other" Stream*/
					while ((count = read(pollfds[i].fd, buf, 1024)) > 0)
						/*
						 * write loses data if flow control
						 * prevents the transmit at this time
						 */
						if (write(pollfds[(i+1) % NPOLL].fd buf, count) != count)
							fprintf(stderr,"writer lost data");
						break;
					}
			}
		}
}

The user specifies the polled events by setting the events field of the pollfd structure to POLLIN. This request tells poll(2) to notify the user of any incoming data on each Stream. The bulk of the example is an infinite loop, where each iteration polls both Streams for incoming data.

The second argument of poll(2) specifies the number of entries in the pollfds array (2 in this example). The third argument indicates the number of milliseconds poll(2) waits for an event if none has occurred. On a system where millisecond accuracy is not available, timeout is rounded up to the nearest value available on that system. If the value of timeout is 0, poll(2) returns immediately. Here, timeout is set to -1, specifying that poll(2) blocks until a requested event occurs or until the call is interrupted.

If poll(2) succeeds, the program checks each entry in the pollfds array. If revents is set to 0, no event has occurred on that file descriptor. If revents is set to POLLIN, incoming data is available, so all available data is read from the polled minor device and written to the other minor device.

If revents is set to a value other than 0 or POLLIN, an error event must have occurred on that Stream because POLLIN was the only requested event. Table 3-3 shows poll error events.

These events cannot be polled for by the user but are reported in revents when they occur. They are only valid in the revents bitmask.

The example attempts to process incoming data as quickly as possible. However, when writing data to a Stream, write(2) can block if the Stream is exerting flow control. To prevent the process from blocking, the minor devices of the communications driver are opened with the O_NDELAY (or O_NONBLOCK; see note) flag set. write(2) cannot send all the data if flow control is on and O_NDELAY (O_NONBLOCK) is set. This can happen if the communications driver processes characters slower than the user transmits. If the Stream becomes full, the number of bytes write(2) sends is less than the requested count. For simplicity, the example ignores the data if the Stream becomes full, and a warning is printed to stderr.

To conform with the IEEE operating system interface standard, POSIX, new applications should use the O_NONBLOCK flag, whose behavior is the same as that of O_NDELAY unless otherwise noted.

This program continues until an error occurs on a Stream, or until the process is interrupted.