draft/man2/epoll_ctl.2

   1 .\"  Copyright (C) 2003  Davide Libenzi
   2 .\"  Davide Libenzi <davidel@xmailserver.org>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   5 .\"  This program is free software; you can redistribute it and/or modify
   6 .\"  it under the terms of the GNU General Public License as published by
   7 .\"  the Free Software Foundation; either version 2 of the License, or
   8 .\"  (at your option) any later version.
   9 .\"
  10 .\"  This program is distributed in the hope that it will be useful,
  11 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"  GNU General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public
  16 .\" License along with this manual; if not, see
  17 .\" <http://www.gnu.org/licenses/>.
  18 .\" %%%LICENSE_END
  19 .\"
  20 .\"*******************************************************************
  21 .\"
  22 .\" This file was generated with po4a. Translate the source file.
  23 .\"
  24 .\"*******************************************************************
  25 .\"
  26 .\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO
  27 .\"         all rights reserved.
  28 .\" Translated 2004-06-15, Yuichi SATO <ysato444@yahoo.co.jp>
  29 .\" Updated & Modified 2004-12-29, Yuichi SATO
  30 .\" Updated & Modified 2005-04-20, Yuichi SATO
  31 .\" Updated & Modified 2005-09-06, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  32 .\" Updated 2006-07-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
  33 .\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.19
  34 .\"
  35 .TH EPOLL_CTL 2 2014\-12\-31 Linux "Linux Programmer's Manual"
  36 .SH 名前
  37 epoll_ctl \- epoll ディスクリプタのインタフェースを操作する
  38 .SH 書式
  39 \fB#include <sys/epoll.h>\fP
  40 .sp
  41 \fBint epoll_ctl(int \fP\fIepfd\fP\fB, int \fP\fIop\fP\fB, int \fP\fIfd\fP\fB, struct
  42 epoll_event *\fP\fIevent\fP\fB);\fP
  43 .SH 説明
  44 このシステムコールは、ファイルディスクリプタ \fIepfd\fP が参照する \fBepoll\fP(7)
  45 インスタンスに対する操作を行う。 対象のファイルディスクリプタ \fIfd\fP に対して、
  46 操作 \fIop\fP の実行が要求される。
  47
  48 \fIop\fP 引き数に指定できる有効な値は以下の通りである。
  49 .TP
  50 \fBEPOLL_CTL_ADD\fP
  51 対象のファイルディスクリプタ \fIfd\fP をファイルディスクリプタ \fIepfd\fP が参照する \fBepoll\fP インスタンスに登録し、イベント
  52 \fIevent\fP を \fIfd\fP に結び付けられた内部ファイルに関連付ける。
  53 .TP
  54 \fBEPOLL_CTL_MOD\fP
  55 イベント \fIevent\fP を対象のファイルディスクリプタ \fIfd\fP に関連付けるように変更する。
  56 .TP
  57 \fBEPOLL_CTL_DEL\fP
  58 対象のファイルディスクリプタ \fIfd\fP を \fIepfd\fP が参照する \fBepoll\fP インスタンスから削除する。 \fIevent\fP
  59 引き数は無視されるので、NULL にすることもできる (但し、下記の「バグ」を参照)。
  60 .PP
  61 \fIevent\fP 引き数は、ファイルディスクリプタ \fIfd\fP にリンクされたオブジェクトを表す。 \fIstruct epoll_event\fP
  62 は以下のように定義される。
  63 .sp
  64 .in +4n
  65 .nf
  66 typedef union epoll_data {
  67     void        *ptr;
  68     int          fd;
  69     uint32_t     u32;
  70     uint64_t     u64;
  71 } epoll_data_t;
  72
  73 struct epoll_event {
  74     uint32_t     events;      /* epoll イベント */
  75     epoll_data_t data;        /* ユーザデータ変数 */
  76 };
  77 .fi
  78 .in
  79
  80 \fIevents\fP メンバは、以下のような使用可能なイベントタイプを使って構成された ビットセットである。
  81 .TP
  82 \fBEPOLLIN\fP
  83 関連付けられたファイルに対して、 \fBread\fP(2)  操作が可能である。
  84 .TP
  85 \fBEPOLLOUT\fP
  86 関連付けられたファイルに対して、 \fBwrite\fP(2)  操作が可能である。
  87 .TP
  88 \fBEPOLLRDHUP"\fP(Linux\fB2.6.17\fP以降)"
  89 ストリームソケットの他端が、コネクションの close 、 またはコネクションの書き込み側の shutdown を行った。
  90 (このフラグを使うと、エッジトリガの監視を行う場合に、 通信のもう一端が閉じられたことを検知するコードを 非常に簡潔に書くことができる。)
  91 .TP
  92 \fBEPOLLPRI\fP
  93 \fBread\fP(2)  操作が可能な緊急 (urgent) データがある。
  94 .TP
  95 \fBEPOLLERR\fP
  96 関連付けられたファイルディスクリプタにエラー条件が起こった。 \fBepoll_wait\fP(2)  は常にこのイベントを待つので、 \fIevents\fP
  97 に設定する必要はない。
  98 .TP
  99 \fBEPOLLHUP\fP
 100 関連付けられたファイルディスクリプタにハングアップが起こった。 \fBepoll_wait\fP(2)  は常にこのイベントを待つので、 \fIevents\fP
 101 に設定する必要はない。
 102 .TP
 103 \fBEPOLLET\fP
 104 関連付けられたファイルディスクリプタに エッジトリガ動作 (Edge Triggered behavior) を設定する。 \fBepoll\fP
 105 のデフォルトの動作は、レベルトリガ (Level Triggered) である。 エッジトリガとレベルトリガによるイベント分配機構 (event
 106 distribution architectures) についての詳細な情報は、 \fBepoll\fP(7)  を参照すること。
 107 .TP
 108 \fBEPOLLONESHOT\fP (Linux 2.6.2 以降)
 109 関連付けられたファイルディスクリプタに 一撃動作 (One\-Shot behavior) を設定する。 これはイベントが
 110 \fBepoll_wait\fP(2)  によって引き出された後、 関連付けられたファイルディスクリプタが内部的に破棄され、 \fBepoll\fP
 111 インタフェースによってイベントが報告されなくなることを意味する。 新しいイベントマスクでファイルディスクリプタを再度有効にするためには、
 112 \fBepoll_ctl\fP()  に \fBEPOLL_CTL_MOD\fP を指定して呼び出さなければならない。 \fIop\fP
 113 引き数に指定できる有効な値は、以下の通り:
 114 .TP
 115 \fBEPOLLWAKEUP\fP (Linux 3.5 以降)
 116 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
 117 \fBEPOLLONESHOT\fP と \fBEPOLLET\fP がクリアされており、 プロセスが \fBCAP_BLOCK_SUSPEND\fP
 118 ケーパビリティを持っている場合、 イベントが処理待ちか処理中かにかかわらず、必ずシステムが "suspend" や "hibernate"
 119 に入らないようにすること。 \fBepoll_wait\fP(2) の呼び出しが返った時点から、 同じ \fBepoll\fP(7) ファイルディスクリプタに対して
 120 \fBepoll_wait\fP(2) が次に呼び出されるか、 そのファイルディスクリプタが閉じられるか、 イベントファイルディスクリプタが
 121 \fBEPOLL_CTL_DEL\fP で削除されるか、 \fBEPOLL_CTL_MOD\fP でイベントファイルディスクリプタの \fBEPOLLWAKEUP\fP
 122 がクリアされるか、 のいずれかになるまで、イベントは「処理中」であるとみなされる。 「バグ」の節も参照のこと。
 123 .SH 返り値
 124 成功した場合、 \fBepoll_ctl\fP()  は 0 を返す。 エラーが起こった場合、 \fBepoll_ctl\fP()  は \-1 を返し、
 125 \fIerrno\fP を適切に設定する。
 126 .SH エラー
 127 .TP
 128 \fBEBADF\fP
 129 \fIepfd\fP か \fIfd\fP が有効なファイルディスクリプタでない。
 130 .TP
 131 \fBEEXIST\fP
 132 \fIop\fP が \fBEPOLL_CTL_ADD\fP であり、かつ与えられたファイルディスクリプタ \fIfd\fP がこの epoll
 133 インスタンスに既に登録されている。
 134 .TP
 135 \fBEINVAL\fP
 136 \fIepfd\fP が \fBepoll\fP ファイルディスクリプタでない。 または \fIfd\fP が \fIepfd\fP と同一である。 または要求された操作
 137 \fIop\fP がこのインタフェースでサポートされていない。
 138 .TP
 139 \fBENOENT\fP
 140 \fIop\fP が \fBEPOLL_CTL_MOD\fP または \fBEPOLL_CTL_DEL\fP で、かつ \fIfd\fP がこの epoll
 141 インスタンスに登録されていない。
 142 .TP
 143 \fBENOMEM\fP
 144 要求された \fIop\fP 制御操作を扱うのに十分なメモリがない。
 145 .TP
 146 \fBENOSPC\fP
 147 epoll インスタンスに新しいファイルディスクリプタを登録 (\fBEPOLL_CTL_ADD\fP)  しようとした際に、
 148 \fI/proc/sys/fs/epoll/max_user_watches\fP で決まる上限に達した。 詳細は \fBepoll\fP(7)  を参照。
 149 .TP
 150 \fBEPERM\fP
 151 対象ファイル \fIfd\fP が \fBepoll\fP に対応していない。 このエラーは \fIfd\fP
 152 が例えば通常ファイルやディレクトリを参照している場合にも起こり得る。
 153 .SH バージョン
 154 .\" To be precise: kernel 2.5.44.
 155 .\" The interface should be finalized by Linux kernel 2.5.66.
 156 \fBepoll_ctl\fP()  はカーネル 2.6 で追加された。
 157 .SH 準拠
 158 \fBepoll_ctl\fP()  は Linux 独自である。
 159 ライブラリによるサポートは glibc バージョン 2.3.2 以降で提供されている。
 160 .SH 注意
 161 \fBepoll\fP インタフェースは、 \fBpoll\fP(2)  に対応している全てのファイルディスクリプタに対応している。
 162 .SH バグ
 163 Linux 2.6.9 より前では、 \fBEPOLL_CTL_DEL\fP 操作の際、引き数 \fIevent\fP に (たとえ無視される場合であっても)
 164 NULL でないポインタを渡す必要があった。 カーネル 2.6.9 以降では、 \fBEPOLL_CTL_DEL\fP を使う際に \fIevent\fP に
 165 NULL を指定できるようになっている。 2.6.9 より前のカーネルへの移植性が必要なアプリケーションでは、 \fIevent\fP に NULL
 166 でないポインタを指定すべきである。
 167
 168 .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
 169 .\" https://lwn.net/Articles/520198/
 170 \fIflags\fP に \fBEPOLLWAKEUP\fP が指定されたが、呼び出し元が \fBCAP_BLOCK_SUSPEND\fP
 171 ケーパビリティを持っていない場合、 \fBEPOLLWAKEUP\fP フラグは \fI黙って無視される\fP。 元の実装では \fIflags\fP
 172 引き数に対する正当性チェックが実行されていないため、 この残念な動作は必要である。 また、 呼び出し元が \fBCAP_BLOCK_SUSPEND\fP
 173 ケーパビリティを持っていなかった場合に呼び出しを失敗させるようにチェックを \fBEPOLLWAKEUP\fP に追加すると、
 174 少なくともひとつは動かなくなる既存のユーザー空間アプリケーションがあった。 そのアプリケーションはたまたま (しかも意味もなく)
 175 このビットを指定していた。 したがって、信頼性が求められるアプリケーションでは、 \fBEPOLLWAKEUP\fP フラグを使おうする場合には
 176 \fBCAP_BLOCK_SUSPEND\fP ケーパビリティを持っているかも確認するようにすべきである。
 177 .SH 関連項目
 178 \fBepoll_create\fP(2), \fBepoll_wait\fP(2), \fBpoll\fP(2), \fBepoll\fP(7)
 179 .SH この文書について
 180 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
 181 である。プロジェクトの説明とバグ報告に関する情報は
 182 http://www.kernel.org/doc/man\-pages/ に書かれている。