poll() -- multiplex input and output

SYNOPSIS

#include <poll.h>

int poll(struct pollfd fds[], nfds_t nfds, int timeout);

The poll() function provides applications with a mechanism for multiplexing input and output over a set of file descriptors. For each member of the specified array, poll() examines the given file descriptor for the events specified in the events member. The poll() function identifies those file descriptors on which an application can read or write data, or on which certain events have occurred.

The fds array specified the file descriptors to be examined and the events of interest for each file descriptor. It is a pointer to an array with one member for each open file descriptor of interest. The array's members are pollfd structures within which the fd member specifies an open file descriptor, and the events and revents members are bitmasks constructed by ORing a combination of the following event flags:

POLLIN: Data other than high-priority data may be read without blocking.
POLLRDNORM: Normal data (priority band equals 0) may be read without blocking.
POLLRDBAND: Data from a non-zero priority band may be read without blocking.
POLLPRI: High-priority data may be received without blocking.
POLLOUT: Normal data (priority band equals 0) may be written without blocking
POLLWRNORM: Same as POLLOUT.
POLLWRBAND: Priority data (priority band greater than 0) may be written.
POLLERR: An error has occurred on the device. This flag is only valid in the revents bitmask; it is ignored in the events member.
POLLHUP: The device has been disconnected. This event and POLLOUT are mutually exclusive; a device can never be writable once a hangup has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually exclusive. This flag is only valid in the revents bitmask; it is ignored in the events member.
POLLNVAL: The value specified in the fd member is invalid. This flag is only valid in the revents bitmask; it is ignored in the events member.

If the value of the fd member is less than 0, the events member is ignored and the revents member of that entry is set to 0 on return from poll().

In each pollfd structure, poll() clears the revents member except that where the application requested a report on a condition by setting one of the bits of the events member as listed earlier, poll() sets the corresponding bit in revents if the requested condition is true. In addition, poll() sets the POLLHUP, POLLERR, and POLLNVAL flags in revents if any of these conditions are true, even if the application did not set the corresponding bit in the events member.

If none of the defined events has occurred on any of the selected file descriptors, poll() waits at least timeout milliseconds for an event to occur on any of the selected file descriptors. If the value of timeout is 0, poll() returns immediately. If the value of timeout is -1, poll() blocks until a requested event occurs or until the call is interrupted.

The poll() function is not affected by the O_NONBLOCK flag.

PARAMETERS

fds: Is an array describing the file descriptors and I/O operations to return status on. The revents member of each entry is updated on successful return.
nfds: Is the number of entries in fds.
timeout: Is the minimum number of milliseconds to wait for results. If this is 0, the call returns immediately. If it is -1, the call blocks indefinitely, returning only after results are available or the call is interrupted.

RETURN VALUES

On success, poll() returns a non-negative value. A positive value indicates the total number of file descriptors that have been selected (that is, file descriptor for which the revents member is non-zero). A value of 0 indicates that the call timed out and no file descriptors have been selected. Upon failure, poll() returns -1 and sets errno to one of the following values:

EAGAIN: The allocation of internal data structures failed but a subsequent request may succeed.
EBADF: One or more of the file descriptors is not a valid open file descriptor or does not support selection.
EINTR: A signal was caught during poll().
EINVAL: The nfds argument is greater than OPEN_MAX.

CONFORMANCE

UNIX 98, with exceptions

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

The POLLRDNORM, POLLRDBAND, and POLLWRBAND events only apply to STREAMS devices. Since the NuTCRACKER Platform does not support STREAMS, these flags are silently ignored.

The poll() function is implemented as a wrapper around the select() function. File descriptors passed to poll() requesting POLLIN events are placed in the read mask for select(); file descriptors requesting POLLOUT events are placed in the write mask; file descriptors requesting POLLPRI events are placed in the exception mask.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

poll()
multiplex input and output

Function