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-4 shows poll error events.

Table 3-4 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) flag set, see note. 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.

Note - To conform with the IEEE operating system interface standard, POSIX, new applications should use the O_NONBLOCK flag. Its 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.

Asynchronous Input and Output

poll(2) enables a user to monitor multiple streams synchronously. poll(2) normally blocks until an event occurs on any of the polled file descriptors. In some applications, however, you want to process incoming data asynchronously. For example, an application can attempt to do some local processing and be interrupted when a pending event occurs. Some time-critical applications must not block, and must have immediate success or failure indication.

The I_SETSIG ioctl(2) (see streamio(7I)) is used to request that a SIGPOLL signal be sent to a user process when a specific event occurs. Table 3-5 lists events for I_SETSIG. These are similar to those described for poll(2).

Table 3-5 I_SETSIG ioctl(2) Events

S_INPUT, S_RDNORM, S_RDBAND, and S_HIPRI are set even if the message is of zero length. A user process can handle only high-priority messages by setting the arg to S_HIPRI.

signal Message

STREAMS enables modules and drivers to send a signal to user processes through a special signal message. If the signal specified by the module or driver is not SIGPOLL (see signal(3C)), the signal is sent to the process group associated with the stream. If the signal is SIGPOLL, the signal is only sent to processes that have registered for the signal by using the I_SETSIG ioctl(2).

Extended Signals

So that a process can obtain the band and event associated with SIGPOLL more readily, STREAMS supports extended signals. For the given events, a special code is defined in <sys/siginfo.h> that describes the reason SIGPOLL was generated. Table 3-6 describes the data available in the siginfo_t structure passed to the signal handler.

Table 3-6 Data in siginfo_t Structure