/sys$common/syshlp/HELPLIB.HLB  —  CRTL  poll
    Provides users with a mechanism for multiplexing input/output
    over a set of file descriptors that reference open streams.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <poll.h>

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

1  –  Argument

 filedes

    Points to an array of pollfd structures, one for each file
    descriptor of interest. Each pollfd structure includes the
    following members:

       int fd - The file descriptor
       int events - The requested conditions
       int revents - The reported conditions

 nfds

    The number of pollfd structures in the filedes array.

 timeout

    The maximum length of time (in milliseconds) to wait for at least
    one of the specified events to occur.

2  –  Description

    The poll function provides users with a mechanism for
    multiplexing input/output over a set of file descriptors that
    reference open streams. For each member of the array pointed
    to by filedes, poll examines the given file descriptor for the
    event(s) specified in events. The poll function identifies those
    streams on which an application can send or receive messages, or
    on which certain events have occurred.

    The filedes parameter specifies the file descriptor to be
    examined and the events of interest for each file descriptor.
    It is a pointer to an array of pollfd structures. The fd member
    of each pollfd structure specifies an open file descriptor. The
    poll function uses the events member to determine what conditions
    to report for this file descriptor. If one or more of these
    conditions is true, the poll function sets the associated revents
    member.

    The events and revents members of each pollfd structure are
    bitmasks. The calling process sets the events bitmask, and poll
    sets the revents bitmasks. These bitmasks contain inclusive
    ORed combinations of condition options. The following condition
    options are defined:

       POLLERR - An error has occurred on the file descriptor. This
       option is only valid in the revents bitmask; it is not used in
       the events member.

       For STREAMS devices, if an error occurs on the file descriptor
       and the device is also disconnected, poll returns POLLERR;
       POLLERR takes precedence over POLLHUP.

       POLLHUP - The device has been disconnected. This event
       is mutually exclusive with POLLOUT; a stream can never be
       writable if a hangup occurred. However, this event and POLLIN,
       POLLRDNORM, POLLRDBAND or POLLPRI are not mutually exclusive.
       This option is only valid in the revents bitmask; it is
       ignored in the events member.

       POLLIN - Data other than high-priority data may be read
       without blocking. This option is set in revents even if the
       message is of zero length. In revents, this option is mutually
       exclusive with POLLPRI.

       POLLNVAL - The value specified for fd is invalid. This option
       is only valid in the revents member; it is ignored in the
       events member.

       POLLOUT - Normal (priority band equals 0) data may be written
       without blocking.

       POLLPRI - High-priority data may be received without blocking.
       This option is set in revents even if the message is of zero
       length. In revents, this option is mutually exclusive with
       POLLIN.

       POLLRDBAND - Data from a nonzero priority band may be read
       without blocking. This option is set in revents even if the
       message is of zero length.

       POLLRDNORM - Normal data (priority band equals 0) may be read
       without blocking. This option is set in revents even if the
       message is of zero length.

       POLLWRBAND - Priority data (priority band greater than 0)
       may be written. This event only examines bands that have been
       written to at least once.

       POLLWRNORM - Same as POLLOUT.

    The poll function ignores any pollfd structure whose fd member
    is less than 0 (zero). If the fd member of all pollfd structures
    is less than 0, the poll function will return 0 and have no other
    results.

    The conditions indicated by POLLNORM and POLLOUT are true if and
    only if at least one byte of data can be read or written without
    blocking. There are two exceptions: regular files, which always
    poll true for POLLNORM and POLLOUT, and pipes, when the rules
    for the operation specify to return zero in order to indicate
    end-of-file.

    The condition options POLLERR, POLLHUP, and POLLNVAL are always
    set in revents if the conditions they indicate are true for the
    specified file descriptor, whether or not these options are set
    in events.

    For each call to the poll function, the set of reportable
    conditions for each file descriptor consists of those conditions
    that are always reported, together with any further conditions
    for which options are set in events. If any reportable condition
    is true for any file descriptor, the poll function will return
    with options set in revents for each true condition for that file
    descriptor.

    If no reportable condition is true for any of the file
    descriptors, the poll function waits up to timeout milliseconds
    for a reportable condition to become true. If, in that time
    interval, a reportable condition becomes true for any of the file
    descriptors, poll reports the condition in the file descriptor's
    associated revents member and returns. If no reportable condition
    becomes true, poll returns without setting any revents bitmasks.

    If the timeout parameter is a value of -1, the poll function does
    not return until at least one specified event has occurred. If
    the value of the timeout parameter is 0 (zero), the poll function
    does not wait for an event to occur but returns immediately, even
    if no specified event has occurred.

    The behavior of the poll function is not affected by whether
    the O_NONBLOCK option is set on any of the specified file
    descriptors.

    The poll function supports regular files, terminal and pseudo-
    terminal devices, STREAMS-based files, FIFOs, and pipes. The
    behavior of poll on elements of file descriptors that refer to
    other types of files is unspecified.

    For sockets, a file descriptor for a socket that is listening for
    connections indicates it is ready for reading after connections
    are available. A file descriptor for a socket that is connecting
    asynchronously indicates it is ready for writing after a
    connection is established.

3  –  Return Values

    n                  Upon successful completion, a nonnegative
                       value is returned, indicating the number of
                       file descriptors for which poll has set the
                       revents bitmask.
    0                  poll has timed out and has not set any of the
                       revents bitmasks.
    -1                 An error occurred. errno is set to indicate
                       the error:

                       o  EAGAIN - Allocation of internal data
                          structures failed. A later call to the
                          poll function might complete successfully.

                       o  EINTR - A signal was intercepted during the
                          poll function, and the signal handler was
                          installed with an indication that functions
                          are not to be restarted.

                       o  EINVAL - The nfds parameter is greater than
                          OPEN_MAX, or one of the fd members refers
                          to a stream or multiplexer that is linked
                          (directly or indirectly) downstream from a
                          multiplexer.
Close Help