Author : Paulus Gandung Prakosa (syn1988@sdf.lonestar.org)

Controlling Epoll

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 the epoll_event structure as :

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

A successful call to epoll_ctl() controls the epoll instance associated with the file descriptor epfd. The parameter op specifies the operation to be taken against the file associated with fd. The event parameter further describes the behavior of the operation.

Here are valid values for the op parameter :

EPOLL_CTL_ADD
• Add a monitor of the file associated with file descriptor fd to the epoll instance associated with epfd, per the events defined in event.

EPOLL_CTL_DEL
• Remove a monitor on the file associated with the file descriptor fd from the epoll instance associated with epfd.

EPOLL_CTL_MOD
• Modify an existing monitor of fd with the updated events specified by event.

The events field in the epoll_event structure 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. 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 via EPOLL_CTL_MOD to 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.

The data field inside the event_poll structure is for user's private use. The contents are returned to the user upon receipt of the requested event. The common practice is to set event.data.fd to fd, which makes it easy to look up which file descriptor caued the event.

Upon success, epoll_ctl() returns 0. On failure, the call returns -1, and sets global variable errno to one of the following values :

EBADF
• epfd is not epoll instance, or fd is not a valid file descriptor.

EEXIST
• op was EPOLL_CTL_ADD, but fd is already associated with epfd.

EINVAL
• epfd is not an epoll instance, epfd is the same as fd, or op is invalid.

ENOENT
• op was EPOLL_CTL_MOD, or EPOLL_CTL_DEL, but fd is not associated with epfd.

ENOMEM
• There was insufficient memory to process the request.

EPERM
• fd does not support epoll