書式
#include <sys/epoll.h>int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
説明
このシステムコールは、ファイルディスクリプタ epfd が参照する epoll(7) インスタンスに対する操作を行う。 対象のファイルディスクリプタ fd に対して、 操作 op の実行が要求される。op 引き数に指定できる有効な値は以下の通りである。
- EPOLL_CTL_ADD
- 対象のファイルディスクリプタ fd をファイルディスクリプタ epfd が参照する epoll インスタンスに登録し、イベント event を fd に結び付けられた内部ファイルに関連付ける。
- EPOLL_CTL_MOD
- イベント event を対象のファイルディスクリプタ fd に関連付けるように変更する。
- EPOLL_CTL_DEL
- 対象のファイルディスクリプタ fd を epfd が参照する epoll インスタンスから削除する。 event 引き数は無視されるので、NULL にすることもできる (但し、下記の「バグ」を参照)。
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"(Linux2.6.17以降)"
- ストリームソケットの他端が、コネクションの close 、 またはコネクションの書き込み側の shutdown を行った。 (このフラグを使うと、エッジトリガの監視を行う場合に、 通信のもう一端が閉じられたことを検知するコードを 非常に簡潔に書くことができる。)
- EPOLLPRI
- read(2) 操作が可能な緊急 (urgent) データがある。
- EPOLLERR
- 関連付けられたファイルディスクリプタにエラー条件が起こった。 epoll_wait(2) は常にこのイベントを待つので、 events に設定する必要はない。
- EPOLLHUP
- 関連付けられたファイルディスクリプタにハングアップが起こった。 epoll_wait(2) は常にこのイベントを待つので、 events に設定する必要はない。
- EPOLLET
- 関連付けられたファイルディスクリプタに エッジトリガ動作 (Edge Triggered behavior) を設定する。 epoll のデフォルトの動作は、レベルトリガ (Level Triggered) である。 エッジトリガとレベルトリガによるイベント分配機構 (event distribution architectures) についての詳細な情報は、 epoll(7) を参照すること。
- EPOLLONESHOT (Linux 2.6.2 以降)
- 関連付けられたファイルディスクリプタに 一撃動作 (One-Shot behavior) を設定する。 これはイベントが epoll_wait(2) によって引き出された後、 関連付けられたファイルディスクリプタが内部的に破棄され、 epoll インタフェースによってイベントが報告されなくなることを意味する。 新しいイベントマスクでファイルディスクリプタを再度有効にするためには、 epoll_ctl() に EPOLL_CTL_MOD を指定して呼び出さなければならない。 op 引き数に指定できる有効な値は、以下の通り:
返り値
成功した場合、 epoll_ctl() は 0 を返す。 エラーが起こった場合、 epoll_ctl() は -1 を返し、 errno を適切に設定する。エラー
- EBADF
- epfd か fd が有効なファイルディスクリプタでない。
- EEXIST
- op が EPOLL_CTL_ADD であり、かつ与えられたファイルディスクリプタ fd がこの epoll インスタンスに既に登録されている。
- EINVAL
- epfd が epoll ファイルディスクリプタでない。 または fd が epfd と同一である。 または要求された操作 op がこのインタフェースでサポートされていない。
- ENOENT
- op が EPOLL_CTL_MOD または EPOLL_CTL_DEL で、かつ fd がこの epoll インスタンスに登録されていない。
- ENOMEM
- 要求された op 制御操作を扱うのに十分なメモリがない。
- ENOSPC
- epoll インスタンスに新しいファイルディスクリプタを登録 (EPOLL_CTL_ADD) しようとした際に、 /proc/sys/fs/epoll/max_user_watches で決まる上限に達した。 詳細は epoll(7) を参照。
- EPERM
- 対象ファイル fd が epoll をサポートしていない。
バージョン
epoll_ctl() はカーネル 2.6 で追加された。準拠
epoll_ctl() は Linux 独自である。 ライブラリによるサポートは glibc バージョン 2.3.2 以降で提供されている。注意
epoll インタフェースは、 poll(2) に対応している全てのファイルディスクリプタに対応している。バグ
Linux 2.6.9 より前では、 EPOLL_CTL_DEL 操作の際、引き数 event に (たとえ無視される場合であっても) NULL でないポインタを渡す必要があった。 カーネル 2.6.9 以降では、 EPOLL_CTL_DEL を使う際に event に NULL を指定できるようになっている。 2.6.9 より前のカーネルへの移植性が必要なアプリケーションでは、 event に NULL でないポインタを指定すべきである。この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。