名前
epoll_ctl - epoll ディスクリプタのインタフェースを制御する
書式
#include <sys/epoll.h>
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event)
説明
対象ファイルディスクリプタ fd への操作 op の実行を要求し、 epoll ディスクリプタ epfd を制御する。 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 イベント */
epoll_data_t data; /* ユーザデータ変数 */
};
events メンバは、以下のような使用可能なイベントタイプを使って構成された ビットセットである。
EPOLLIN | |||||||||||||
関連付けられたファイルに対して、 read(2) 操作が可能である。 | |||||||||||||
EPOLLOUT | |||||||||||||
関連付けられたファイルに対して、 write(2) 操作が可能である。 | |||||||||||||
EPOLLRDHUP (カーネル 2.6.17 以降) | |||||||||||||
ストリームソケットの他端が、コネクションの close 、 またはコネクションの書き込み側の shutdown を行った。 (このフラグを使うと、エッジトリガの監視を行う場合に、 通信のもう一端が閉じられたことを検知するコードを 非常に簡潔に書くことができる。) | |||||||||||||
EPOLLPRI | |||||||||||||
read(2) 操作が可能な緊急 (urgent) データがある。 | |||||||||||||
EPOLLERR | |||||||||||||
関連付けられたファイルディスクリプタにエラー条件が起こった。 epoll_wait(2) は常にこのイベントを待つので、 events に設定する必要はない。 | |||||||||||||
EPOLLHUP | |||||||||||||
関連付けられたファイルディスクリプタにハングアップが起こった。 epoll_wait(2) は常にこのイベントを待つので、 events に設定する必要はない。 | |||||||||||||
EPOLLET | |||||||||||||
関連付けられたファイルディスクリプタに エッジトリガ動作 (Edge Triggered behaviour) を設定する。 epoll のデフォルトの動作は、レベルトリガ (Level Triggered) である。 エッジトリガとレベルトリガによるイベント分配機構 (event distribution architectures) についての詳細な情報は、 epoll(7) を参照すること。 | |||||||||||||
EPOLLONESHOT (カーネル 2.6.2 以降) | |||||||||||||
関連付けられたファイルディスクリプタに 一撃動作 (One-Shot behaviour) を設定する。 これはイベントが epoll_wait(2) によって引き出された後、 関連付けられたファイルディスクリプタが内部的に破棄され、 epoll インタフェースによってイベントが報告されなくなることを意味する。 新しいイベントマスクでファイルディスクリプタを再度有効にするためには、 epoll_ctl(2) に EPOLL_CTL_MOD を指定して呼び出さなければならない。 | |||||||||||||
epoll インタフェースは、 poll(2) をサポートする全てのファイルディスクリプタをサポートする。 op 引き数に指定できる有効な値は、以下の通り: | |||||||||||||
| |||||||||||||
返り値
成功した場合、 epoll_ctl(2) は 0 を返す。 エラーが起こった場合、 epoll_ctl(2) は -1 を返し、 errno を適切に設定する。
エラー
EBADF | epfd か fd が有効なファイルディスクリプタでない。 |
EEXIST | op が EPOLL_CTL_ADD であり、かつ与えられたファイルディスクリプタ fd が既に epfd に存在する。 |
EINVAL | epfd が epoll ファイルディスクリプタでない。 または fd が epfd と同一である。 または要求された操作 op がこのインタフェースでサポートされていない。 |
ENOENT | op が EPOLL_CTL_MOD または EPOLL_CTL_DEL であり、かつ fd が epfd に存在しない。 |
ENOMEM | 要求された op 制御操作を扱うのに十分なメモリがない。 |
EPERM | 対象ファイル fd が epoll をサポートしていない。 |
準拠
epoll_ctl(2) は Linux 独自であり、カーネル 2.5.44 で導入された。
バグ
2.6.9 より前のカーネルでは、 EPOLL_CTL_DEL 操作の際、引き数 event に (たとえ無視される場合であっても) NULL でないポインタを渡す必要があった。 カーネル 2.6.9 以降では、 EPOLL_CTL_DEL を使う際に event に NULL を指定できるようになっている。