Controlling Epoll - BrainDump

The epoll_ctl() system call can be used to add file descriptors to and remove file descriptors from a given epoll context:

  #include <sys/epoll.h>

  int epoll_ctl (int epfd,
                int op,
                int fd,
                struct epoll_event *event);

The header <sys/epoll.h> defines theepoll_eventstructure as:

  struct epoll_event { 
         __u32 events; /* events */
         union {
                 void *ptr;
                 int fd;
                 __u32 u32;
                 __u64 u64;
         } data;
  };

A successful call toepoll_ctl()controls the epoll instance associated with the file descriptorepfd. The parameteropspecifies the operation to be taken against the file associated withfd. Theevent parameter further describes the behavior of the operation.

Here are valid values for theopparameter:

EPOLL_CTL_ADD

Add a monitor on the file associated with the file 
descriptorfdto theepoll instance associated with epfd, per the events defined inevent.

EPOLL_CTL_DEL

Remove a monitor on the file associated with the file descriptorfdfrom the epoll instance associated withepfd.

EPOLL_CTL_MOD

Modify an existing monitor offdwith the updated events specified byevent.

Theevents field in theepoll_eventstructure lists which events to monitor on the given file descriptor. Multiple events can be bitwise-ORed together. Here are valid values:

EPOLLERR

An error condition occurred on the file. This event is always monitored, even if it’s not specified.

EPOLLET

Enables edge-triggered behavior for the monitor of the file (see the upcoming section “Edge- Versus Level-Triggered Events”). The default behavior is level- triggered.

EPOLLHUP

A hangup occurred on the file. This event is always monitored, even if it’s not specified.

EPOLLIN

The file is available to be read from without blocking.

EPOLLONESHOT

After an event is generated and read, the file is automatically no longer monitored. A new event mask must be specified viaEPOLL_CTL_MODto reenable the watch.

EPOLLOUT

The file is available to be written to without blocking.

EPOLLPRI

There is urgent out-of-band data available to read.

Thedatafield inside theevent_pollstructure is for the user’s private use. The contents are returned to the user upon receipt of the requested event. The common practice is to setevent.data.fdtofd, which makes it easy to look up which file descriptor caused the event.

Upon success,epoll_ctl()returns0. On failure, the call returns-1, and setserrnoto one of the following values:

EBADF

epfdis not a valid epoll instance, orfdis not a valid file descriptor.

EEXIST

op wasEPOLL_CTL_ADD, butfdis already associated withepfd.

EINVAL

epfdis not an epoll instance,epfdis the same asfd, oropis invalid.

ENOENT

opwasEPOLL_CTL_MOD, orEPOLL_CTL_DEL, butfdis not associated withepfd.

ENOMEM

There was insufficient memory to process the request.

EPERM

fddoes not support epoll.

As an example, to add a new watch on the file associated withfdto the epoll instanceepfd, you would write:

  struct epoll_event event;
  int ret;

  event.data.fd = fd; /* return the fd to us later */
  event.events = EPOLLIN | EPOLLOUT;

  ret = epoll_ctl (epfd, EPOLL_CTL_ADD, fd, &event);
  if (ret)
          perror ("epoll_ctl");

To modify an existing event on the file associated withfdon the epoll instanceepfd, you would write:

  struct epoll_event event;
  int ret;

  event.data.fd = fd; /* return the fd to us later */
  event.events = EPOLLIN;

  ret = epoll_ctl (epfd, EPOLL_CTL_MOD, fd, &event);
  if (ret)
          perror ("epoll_ctl");

Conversely, to remove an existing event on the file associated withfdfrom the epoll instanceepfd, you would write:

  struct epoll_event event;
  int ret;

  ret = epoll_ctl (epfd, EPOLL_CTL_DEL, fd, &event);
  if (ret)
          perror ("epoll_ctl");

Note that theeventparameter can beNULLwhenopisEPOLL_CTL_DEL, as there is no event mask to provide. Kernel versions before 2.6.9, however, erroneously check for this parameter to be non-NULL. For portability to these older kernels, you should pass in a valid non-NULLpointer; it will not be touched. Kernel 2.6.9 fixed this bug.