EPOLL_CTL(2) Linux Programmer's Manual POLL_CTL(2)

NAME

epoll_ctl - control interface for an epoll descriptor

SYNOPSIS

#include <sys/epoll.h>

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

描述

这个系统调用通过描述符epfd控制操作epoll实例.它要求operation op 是目标操作符, fd.
op 的有效参数有:
- EPOLL_CTL_ADD：登记目标文件描述符在epfd描述的epoll实例并且关联event到fd.
- EPOLL_CTL_MOD：改变文件描述符fd的event.
- EPOLL_CTL_DEL：从epoll实例中删除文件描述符.event参数被忽略，可以设置成NULL(但是会有下面的bug)
event参数描述关联文件描述符fd.struct epoll_event 定义如下:

    typedef union epoll_data {
        void        *ptr;
        int          fd;
        uint32_t     u32;
        uint64_t     u64;
    } epoll_data_t;

    struct epoll_event {
        uint32_t     events;      /* Epoll events */
        epoll_data_t data;        /* User data variable */
    };

events成员也是位域，有下面几种类型:
- EPOLLIN:关联的文件可读操作
- EPOLLOUT：关联文件可写操作
- EPOLLRDHUP (since Linux 2.6.17)：字节流套接字就相当于关闭连接，或半关闭写(这个标志在使用边缘触发监测shutdown时特别有用)
- EPOLLPRI：紧急事件可读操作
- EPOLLERR：fd有错误情况发生.epoll_wait(2) 总是等待这个事件,所有这个事件没有设置的不要
- EPOLLHUP:fd发生挂起事件，epoll_wait(2) 总是等待这个事件,所有这个事件没有设置的不要.注意在从一个管道读的时候，这个事件仅仅说明the peer closed its end of the channel.后面从这个管道读会返回0，(end of file)仅在所有管道中的未读数据被消耗后.
- EPOLLET：设置边沿触发,默认行为是水平触发.
- EPOLLONESHOT(since Linux 2.6.2)：设置one-shot.这意味着在一个事件pulled out后，epoll_wait(2)描述符关联的事件失效并且没有其他事件会被通知.必须调用call epoll_ctl() EPOLL_CTL_MOD 去再设置文件描述符的关联事件
- EPOLLWAKEUP (since Linux 3.5)：如果EPOLLONESHOT 和 EPOLLET 位被清除了并且进程有CAP_BLOCK_SUSPEND 能力,在进程等待或拥有期间确保系统不会暂停和睡眠，，The event is considered as being “processed” from the time when it is returned by a call to epoll_wait(2) until the next call to epoll_wait(2) on the same epoll(7) file descriptor, the closure of that file descriptor, the removal of the event file descriptor with EPOLL_CTL_DEL, or the clearing of EPOLLWAKEUP for the event file descriptor with EPOLL_CTL_MOD.See also BUGS.
返回值
- 成功返回0,失败返回-1，同时errno被设置
ERRORS
- EBADF epfd or fd is not a valid file descriptor.
- EEXIST op was EPOLL_CTL_ADD, and the supplied file descriptor fd is already registered with this epoll instance.
- EINVAL epfd is not an epoll file descriptor, or fd is the same as epfd,or the requested operation op is not supported by this interface.
- ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not registered with this epoll instance.
- ENOMEM There was insufficient memory to handle the requested op control operation.
- ENOSPC The limit imposed by /proc/sys/fs/epoll/max_user_watches was encountered while trying to register (EPOLL_CTL_ADD) a new file descriptor on an epoll instance. See epoll(7) for further details.
- EPERM The target file fd does not support epoll. This error can occur if fd refers to, for example, a regular file or a directory.
VERSIONS
- epoll_ctl() was added to the kernel in version 2.6.
CONFORMING TO
- epoll_ctl() is Linux-specific. Library support is provided in glibc starting with version 2.3.2.
NOTES
- The epoll interface supports all file descriptors that support poll(2).
BUGS
- In kernel versions before 2.6.9, the EPOLL_CTL_DEL operation required a non-null pointer in event, even though this argument is ignored. Since Linux 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL.
- Applications that need to be portable to kernels before 2.6.9 should specify a non-null pointer in event.
- If EPOLLWAKEUP is specified in flags, but the caller does not have the CAP_BLOCK_SUSPEND capability, then the EPOLLWAKEUP flag is silently ignored. This unfortunate behavior is necessary because no validity checks were performed on the flags argument in the original implementation, and the addition of the EPOLLWAKEUP with a check that caused the call to fail if the caller did not have the CAP_BLOCK_SUSPEND capability caused a breakage in at least one existing user-space application that happened to randomly (and uselessly) specify this bit.A robust application should therefore double check that it has the CAP_BLOCK_SUSPEND capability if attempting to use the EPOLLWAKEUP flag.

EPOLL_CTL(2) Linux Programmer's Manual POLL_CTL(2)

NAME

SYNOPSIS

描述

猜你喜欢