Home arrow BrainDump arrow Page 2 - Linux Files and the Event Poll Interface

Controlling Epoll - BrainDump

In this second part of a seven-part series on Linux I/O file system calls, you will learn about the event poll interface. This article is excerpted from chapter four of the book Linux System Programming: Talking Directly to the Kernel and C Library, written by Robert Love (O'Reilly, 2007; ISBN: 0596009585). Copyright © 2007 O'Reilly Media, Inc. All rights reserved. Used with permission from the publisher. Available from booksellers or direct from O'Reilly Media.

TABLE OF CONTENTS:
  1. Linux Files and the Event Poll Interface
  2. Controlling Epoll
  3. Waiting for Events with Epoll
  4. Edge- Versus Level-Triggered Events
By: O'Reilly Media
Rating: starstarstarstarstar / 7
December 04, 2008

print this article
SEARCH DEV SHED

TOOLS YOU CAN USE

advertisement

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.



 
 
>>> More BrainDump Articles          >>> More By O'Reilly Media
 

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort
   

BRAINDUMP ARTICLES

- Apple Founder Steve Jobs Dies
- Steve Jobs` Era at Apple Ends
- Google's Chrome Developer Tool Updated
- Google's Chrome 6 Browser Brings Speed to th...
- New Open Source Update Fedora 13 is Released...
- Install Linux with Knoppix
- iPad Developers Flock To SDK 3.2
- Managing a Linux Wireless Access Point
- Maintaining a Linux Wireless Access Point
- Securing a Linux Wireless Access Point
- Configuring a Linux Wireless Access Point
- Building a Linux Wireless Access Point
- Migrating Oracle to PostgreSQL with Enterpri...
- Demystifying SELinux on Kernel 2.6
- Yahoo and Microsoft Create Ad Partnership

Developer Shed Affiliates

 


Dev Shed Tutorial Topics: