名前

       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.65 の一部 である。プロジェクトの説明とバグ報告
       に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。