Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       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
              インスタンスに登録し、イベント  eventfd に結び付けられた内部ファイルに関連付け
              る。

       EPOLL_CTL_MOD
              イベント event を対象のファイルディスクリプター fd に関連付けるように変更する。

       EPOLL_CTL_DEL
              対象のファイルディスクリプター fdepfd が参照する  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
              引き数に指定できる有効な値は、以下の通り:

       EPOLLWAKEUP (Linux 3.5 以降)
              EPOLLONESHOTEPOLLET がクリアされており、 プロセスが CAP_BLOCK_SUSPEND  ケーパビ
              リティを持っている場合、   イベントが処理待ちか処理中かにかかわらず、必ずシステムが
              "suspend" や "hibernate" に入らないようにすること。 epoll_wait(2)  の呼び出しが返っ
              た時点から、  同じ epoll(7) ファイルディスクリプターに対して epoll_wait(2) が次に呼
              び出されるか、 そのファイルディスクリプターが閉じられるか、  イベントファイルディス
              クリプターが  EPOLL_CTL_DEL で削除されるか、 EPOLL_CTL_MOD でイベントファイルディス
              クリプターの EPOLLWAKEUP がクリアされるか、  のいずれかになるまで、イベントは「処理
              中」であるとみなされる。 「バグ」の節も参照のこと。

返り値

       成功した場合、  epoll_ctl()   は 0 を返す。 エラーが起こった場合、 epoll_ctl()  は -1 を返
       し、 errno を適切に設定する。

エラー

       EBADF  epfdfd が有効なファイルディスクリプターでない。

       EEXIST opEPOLL_CTL_ADD であり、かつ与えられたファイルディスクリプター fd がこの  epoll
              インスタンスに既に登録されている。

       EINVAL epfdepoll ファイルディスクリプターでない。 または fdepfd と同一である。 ま
              たは要求された操作 op がこのインターフェースでサポートされていない。

       ENOENT opEPOLL_CTL_MOD または EPOLL_CTL_DEL で、かつ fd がこの epoll  インスタンスに登
              録されていない。

       ENOMEM 要求された op 制御操作を扱うのに十分なメモリーがない。

       ENOSPC epoll  インスタンスに新しいファイルディスクリプターを登録 (EPOLL_CTL_ADD)  しようと
              した際に、   /proc/sys/fs/epoll/max_user_watches   で決まる上限に達した。    詳細は
              epoll(7)  を参照。

       EPERM  対象ファイル  fdepoll に対応していない。 このエラーは fd が例えば通常ファイルや
              ディレクトリを参照している場合にも起こり得る。

バージョン

       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 でないポインターを指定すべきであ
       る。

       flagsEPOLLWAKEUP が指定されたが、呼び出し元が CAP_BLOCK_SUSPEND ケーパビリティを持って
       いない場合、 EPOLLWAKEUP フラグは 黙って無視される。 元の実装では flags 引き数に対する正当
       性チェックが実行されていないため、   この残念な動作は必要である。   また、    呼び出し元が
       CAP_BLOCK_SUSPEND ケーパビリティを持っていなかった場合に呼び出しを失敗させるようにチェック
       を EPOLLWAKEUP  に追加すると、  少なくともひとつは動かなくなる既存のユーザー空間アプリケー
       ションがあった。  そのアプリケーションはたまたま (しかも意味もなく) このビットを指定してい
       た。 したがって、信頼性が求められるアプリケーションでは、 EPOLLWAKEUP フラグを使おうする場
       合には CAP_BLOCK_SUSPEND ケーパビリティを持っているかも確認するようにすべきである。

関連項目

       epoll_create(2), epoll_wait(2), poll(2), epoll(7)

この文書について

       この  man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。