Here is the poll() system call declaration:

#include <poll.h>

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

/*
 * Returns:
 *   Positive number  = number of ready file descriptors
 *   0                = timeout expired, nothing is ready
 *  -1                = error (check errno)
 */

The three arguments are:

Each element in the fds[] array is a struct pollfd. You fill in the fd and events fields before the call. After poll() returns, you read the revents field to know what actually happened.

struct pollfd {
    int   fd;       /* The file descriptor to watch */
    short events;   /* What events YOU want to watch (set before calling poll) */
    short revents;  /* What events ACTUALLY happened (filled in by kernel) */
};

Important: events and revents are bit masks. This means you can combine multiple event flags using the bitwise OR operator (|). The kernel also sets multiple bits in revents if multiple events occur at the same time.

These are the bit-mask constants you use in events and that the kernel sets in revents. Understanding these is critical for any I/O multiplexing code.

A great feature of poll() is that you can disable monitoring of one fd without rebuilding the whole array. Two ways to do this:

/* Temporarily stop watching fd 5 */
pollFd[2].events = 0;

/* Disable by negating the fd */
pollFd[2].fd = -pollFd[2].fd;

/* Re-enable later */
pollFd[2].fd = -pollFd[2].fd;

Some poll() constants are not visible by default. You must define feature test macros before including <poll.h> to unlock them.

/* To get POLLRDNORM, POLLRDBAND, POLLWRNORM, POLLWRBAND */
#define _XOPEN_SOURCE 600
#include <poll.h>

/* To get POLLRDHUP (Linux-specific, kernel >= 2.6.17) */
#define _GNU_SOURCE
#include <poll.h>

/* In practice, defining _GNU_SOURCE gives you everything */
#define _GNU_SOURCE
#include <poll.h>

This example shows the typical pattern for using poll(). We watch two file descriptors at the same time: standard input (fd 0) and the read end of a pipe (fd 3).

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <poll.h>
#include <unistd.h>
#include <string.h>

int main(void)
{
    int pipefd[2];
    char buf[256];

    /* Create a pipe */
    if (pipe(pipefd) == -1) {
        perror("pipe");
        exit(EXIT_FAILURE);
    }

    /* Write something into the pipe so we have something to read */
    write(pipefd[1], "hello from pipe", 15);

    /*
     * Set up the pollfd array.
     * We watch two fds:
     *   fds[0] = stdin  (fd 0) — watch for input
     *   fds[1] = pipefd[0]     — watch for input
     */
    struct pollfd fds[2];

    fds[0].fd     = STDIN_FILENO;   /* fd 0 */
    fds[0].events = POLLIN;         /* we want to know when data arrives */

    fds[1].fd     = pipefd[0];      /* read end of pipe */
    fds[1].events = POLLIN;

    printf("Calling poll()...\n");

    /* timeout = 5000 ms = 5 seconds */
    int ready = poll(fds, 2, 5000);

    if (ready == -1) {
        perror("poll");
        exit(EXIT_FAILURE);
    }

    if (ready == 0) {
        printf("Timeout: nothing became ready in 5 seconds\n");
        return 0;
    }

    printf("poll() returned %d ready fd(s)\n", ready);

    /* Check each fd */
    for (int i = 0; i < 2; i++) {

        if (fds[i].revents == 0)
            continue;   /* nothing happened on this fd */

        printf("fd %d: revents = 0x%x\n", fds[i].fd, fds[i].revents);

        if (fds[i].revents & POLLIN) {
            int n = read(fds[i].fd, buf, sizeof(buf) - 1);
            if (n > 0) {
                buf[n] = '\0';
                printf("  Read %d bytes: %s\n", n, buf);
            }
        }

        if (fds[i].revents & POLLERR)
            printf("  Error on fd %d\n", fds[i].fd);

        if (fds[i].revents & POLLHUP)
            printf("  Hangup on fd %d\n", fds[i].fd);
    }

    close(pipefd[0]);
    close(pipefd[1]);
    return 0;
}