名前

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