epoll_ctl - epoll
ディスクリプタのインタフェースを操作する
#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
でないポインタを指定すべきである。
関連項目¶
epoll_create(2),
epoll_wait(2),
poll(2),
epoll(7)
この文書について¶
この man ページは Linux
man-pages
プロジェクトのリリース
3.41 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man-pages/
に書かれている。