poll() -- System Call (libc)

Query several I/O devices
#include <poll.h>
int poll(fds, nfds, timeout)
struct pollfd fds[]; unsigned long nfds; int timeout;

The COHERENT system  call poll() polls one or more  file streams for one or
more polling conditions.   fds gives the address of an  array of structs of
type pollfd, which has the following structure:

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

Field fd gives the file descriptor for a file stream, as returned by a call
to open(),  or creat(). Fields  events and revents  give, respectively, the
polling conditions  that interest you,  and those that  have occurred.  The
legal conditions, as defined in header file poll.h, are as follows:

POLLIN  Input, or  a non-priority  or file-descriptor  passing  message, is
        available for reading.  In revents, this  bit is mutually exclusive
        with POLLPRI.

POLLPRI
        A priority message is available for  reading.  In revents, this bit
        is mutually exclusive with POLLIN.

POLLOUT
        Output may be performed; the output queue is not full.

POLLERR
        An error message has arrived.  This  field is used only in revents,
        and is ignored in events.

POLLHUP
        A hangup has occurred.  This field  is used only in revents, and is
        ignored in events.

POLLNVAL
        The specified fd value does not belong to an open I/O stream.  This
        field is used only in revents, and is ignored in events.

nfds gives the number of entries in fds.

For each array element fds[i],   poll()   examines   the  file   descriptor
fds[i].fd for the events specified by bits set in fds[i].events, and places
the resulting status into fds[i].revents.   If the  fd value  is  less than
zero, revents for that entry is  set to zero.  Event flags POLLIN, POLLPRI,
and POLLOUT are set in revents  only if the same bits are set in events and
the  corresponding  condition holds.   Event  flags  POLLHUP, POLLERR,  and
POLLNVAL are  always set in  revents if the  corresponding condition holds,
regardless of the contents of events.

If none of the defined events for any of the file descriptors has occurred,
poll() waits  for timeout milliseconds.   Because the system  clock runs at
100 hertz,  the value used for  timeout is the next  higher multiple of ten
milliseconds.  If timeout  is zero, poll() returns immediately.  If timeout
is -1, poll() blocks until a  requested event occurs or a signal interrupts
the call.

poll() returns the number of file descriptors for which revents is nonzero.
It  returns zero  if it  timed out  with no matching  events.  If  the call
failed, it returns -1 and sets errno to an appropriate value.

Example

For an example of using poll() to read a serial port, see the Lexicon entry
for ioctl(). The following example uses poll() to sleep for a fraction of a
second.

#include <poll.h>
#include <sys/v_types.h>
#include <sys/times.h>

main()
{
    struct pollfd fds;
    int timeout;
    struct tms tmp;
    int before; /* time in millisec before poll() */
    int after; /* time in millisec after poll() */

    timeout = 270; /* sleep time is timeout * 10 millisec */

    fds.fd = -1; /* no file needed for sleeping */

    before = times(&tmp); /* Get time before poll */

    /* sleep not less than 0.270 sec */
    poll(&fds, 1, timeout);

    after = times(&tmp); /* Get time after poll */

    printf("%d\n", (after - before) * 1000 / CLK_TCK);
}

See Also

libc,
poll.h

© 2012 by Stephen A. Ness