draft/man2/signalfd.2

   1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" starting from a version by 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 .TH SIGNALFD 2 2009\-01\-13 Linux "Linux Programmer's Manual"
  26 .SH 名前
  27 signalfd \- シグナル受け付け用のファイルディスクリプタを生成する
  28 .SH 書式
  29 \fB#include <sys/signalfd.h>\fP
  30 .sp
  31 \fBint signalfd(int \fP\fIfd\fP\fB, const sigset_t *\fP\fImask\fP\fB, int \fP\fIflags\fP\fB);\fP
  32 .SH 説明
  33 \fBsignalfd\fP()  は、呼び出し元宛てのシグナルを受け付けるために使用されるファイル ディスクリプタを生成する。 この方法はシグナルハンドラや
  34 \fBsigwaitinfo\fP(2)  を用いる方法の代わりとなるものであり、このファイルディスクリプタを \fBselect\fP(2),
  35 \fBpoll\fP(2), \fBepoll\fP(7)  で監視できるという利点がある。
  36
  37 \fImask\fP 引き数には、呼び出し元がこのファイルディスクリプタ経由で受け付けたい シグナル集合を指定する。この引き数で指定するシグナル集合の内容は、
  38 \fBsigsetops\fP(3)  で説明されているマクロを使って初期化することができる。 通常、ファイルディスクリプタ経由で受信するシグナル集合は、
  39 そのシグナルがデフォルトの配送方法に基いて処理されるのを防ぐために、 \fBsigprocmask\fP(2)  を使ってブロックしておくべきである。
  40 シグナル \fBSIGKILL\fP と \fBSIGSTOP\fP を signalfd ファイルディスクリプタ経由で受信することはできない。 これらのシグナルが
  41 \fImask\fP で指定された場合には黙って無視される。
  42
  43 \fIfd\fP 引き数が \-1 の場合、 \fBsignalfd\fP()  は新しいファイルディスクリプタを生成し、 \fImask\fP
  44 で指定されたシグナル集合をそのファイルディスクリプタに関連付ける。 \fIfd\fP 引き数が \-1 以外の場合、 \fIfd\fP には有効な既存の
  45 signalfd ファイルディスクリプタを指定しなければならず、 そのディスクリプタに関連付けられているシグナル集合は \fImask\fP
  46 を使って置き換えられる。
  47
  48 Linux 2.6.27 以降では、 以下の値のいくつかをビット単位の論理和 (OR) で指定することで、 \fBsignalfd\fP()
  49 の振舞いを変更することができる。
  50 .TP  14
  51 \fBSFD_NONBLOCK\fP
  52 新しく生成されるオープンファイル記述 (open file description) の \fBO_NONBLOCK\fP
  53 ファイルステータスフラグをセットする。 このフラグを使うことで、 \fBO_NONBLOCK\fP をセットするために \fBfcntl\fP(2)
  54 を追加で呼び出す必要がなくなる。
  55 .TP
  56 \fBSFD_CLOEXEC\fP
  57 新しいファイルディスクリプタに対して close\-on\-exec (\fBFD_CLOEXEC\fP)  フラグをセットする。
  58 このフラグが役に立つ理由については、 \fBopen\fP(2)  の \fBO_CLOEXEC\fP フラグの説明を参照のこと。
  59 .PP
  60 バージョン 2.6.26 以前の Linux では、 \fIflags\fP 引き数は未使用であり、0 を指定しなければならない。
  61
  62 \fBsignalfd\fP()  が返すファイルディスクリプタは以下の操作をサポートしている。
  63 .TP
  64 \fBread\fP(2)
  65 \fImask\fP に指定されているシグナルのうち一つ以上がそのプロセスに対して 処理待ち (pending) であれば、それらのシグナルの情報が
  66 \fBread\fP(2)  に渡されたバッファを使って、 \fIsignalfd_siginfo\fP 構造体に格納されて返される。 \fBread\fP(2)
  67 は、バッファに格納可能な範囲でできるだけ多くの処理待ちのシグナルに ついての情報を返す。 バッファは最低でも \fIsizeof(struct
  68 signalfd_siginfo)\fP バイトの大きさがなければならない。 \fBread\fP(2)  の返り値は読み出されたトータルのバイト数である。
  69 .IP
  70 \fBread\fP(2)  が行われた結果、シグナルは消費され、 これらのシグナルはそのプロセスに対しては処理待ちではなくなる
  71 (つまり、シグナルハンドラで捕捉されることもなく、 \fBsigwaitinfo\fP(2)  を使って受け取ることもできなくなる)。
  72 .IP
  73 \fImask\fP に指定されているシグナルがそのプロセスに対して一つも処理待ちでなければ、 \fBread\fP(2)  は、 \fImask\fP
  74 で指定されたシグナルのうちいずれか一つがそのプロセスに対して発生するまで 停止 (block) する、もしくはファイルディスクリプタが非停止
  75 (nonblocking)  に設定されている場合はエラー \fBEAGAIN\fP で失敗する。
  76 .TP
  77 \fBpoll\fP(2), \fBselect\fP(2) (と同様の操作)
  78 \fImask\fP に指定されたシグナルのうち一つ以上がそのプロセスに対して処理待ちであれば、 ファイルディスクリプタは読み出し可能となる
  79 (\fBselect\fP(2)  の \fIreadfds\fP 引き数や \fBpoll\fP(2)  の \fBPOLLIN\fP フラグ)。
  80 .IP
  81 signalfd ファイルディスクリプタは、これ以外のファイルディスクリプタ 多重 API である \fBpselect\fP(2),
  82 \fBppoll\fP(2), \fBepoll\fP(7)  もサポートしている。
  83 .TP
  84 \fBclose\fP(2)
  85 ファイルディスクリプタがそれ以降は必要なくなった際には、クローズすべきである。 同じ signalfd
  86 オブジェクトに関連付けられたファイルディスクリプタが全て クローズされると、そのオブジェクト用の資源がカーネルにより解放される。
  87 .SS "signalfd_siginfo 構造体"
  88 signalfd ファイルディスクリプタからの \fBread\fP(2)  で返される \fIsignalfd_siginfo\fP
  89 構造体のフォーマットは以下の通りである。
  90 .in +4n
  91 .nf
  92
  93 .\" ssi_trapno is unused on most arches
  94 .\" FIXME Since Linux 2.6.37 there is 'uint16_t ssi_addr_lsb'
  95 .\" which is not yet documented
  96 struct signalfd_siginfo {
  97 struct signalfd_siginfo {
  98     uint32_t ssi_signo;   /* シグナル番号 */
  99     int32_t  ssi_errno;   /* エラー番号 (未使用) */
 100     int32_t  ssi_code;    /* シグナルコード */
 101     uint32_t ssi_pid;     /* 送信元の PID */
 102     uint32_t ssi_uid;     /* 送信元の実 UID */
 103     int32_t  ssi_fd;      /* ファイルディスクリプタ (SIGIO) */
 104     uint32_t ssi_tid;     /* カーネルタイマ ID (POSIX タイマ)
 105     uint32_t ssi_band;    /* Band イベント (SIGIO) */
 106     uint32_t ssi_overrun; /* POSIX タイマのオーバーラン回数 */
 107     uint32_t ssi_trapno;  /* シグナルの原因となったトラップ番号 */
 108     int32_t  ssi_status;  /* 終了ステータスかシグナル (SIGCHLD) */
 109     int32_t  ssi_int;     /* sigqueue(3) から送られた整数 */
 110     uint64_t ssi_ptr;     /* sigqueue(3) から送られたポインタ */
 111     uint64_t ssi_utime;   /* 消費したユーザ CPU 時間 (SIGCHLD) */
 112     uint64_t ssi_stime;   /* 消費したシステム CPU 時間 (SIGCHLD) */
 113     uint64_t ssi_addr;    /* シグナルを生成したアドレス
 114                              (ハードウェアが生成したシグナルの場合) */
 115     uint8_t  pad[\fIX\fP];      /* pad の大きさは 128 バイト
 116                              (将来のフィールド追加用の場所の確保) */
 117 };
 118
 119 .fi
 120 .in
 121 \fIsignalfd_siginfo\fP 構造体の各フィールドは、 \fIsiginfo_t\fP 構造体の同じような名前のフィールドと同様である。
 122 \fIsiginfo_t\fP 構造体については \fBsigaction\fP(2)  に説明がある。 返された \fIsignalfd_siginfo\fP
 123 構造体の全てのフィールドがあるシグナルに対して有効なわけではない。 どのフィールドが有効かは、 \fIssi_code\fP
 124 フィールドで返される値から判定することができる。 このフィールドは \fIsiginfo_t\fP の \fIsi_code\fP フィールドと同様である。詳細は
 125 \fBsigaction\fP(2)  を参照。
 126 .SS "fork(2) での扱い"
 127 \fBfork\fP(2)  が行われると、子プロセスは signalfd ファイルディスクリプタのコピーを 継承する。
 128 子プロセスでこのファイルディスクリプタから \fBread\fP(2)  を行うと、子プロセスに対するキューに入っているシグナルに関する 情報が返される。
 129 .SS "execve(2) での扱い"
 130 他のファイルディスクリプタと全く同様に、 signalfd ファイルディスクリプタも \fBexecve\fP(2)
 131 の前後でオープンされたままとなる。但し、そのファイルディスクリプタに close\-on\-exec のマーク (\fBfcntl\fP(2)  参照)
 132 が付いている場合はクローズされる。 \fBexecve\fP(2)  の前に読み出し可能となっていた全てのシグナルは新しく起動されたプログラム
 133 でも引き続き読み出し可能である (これは伝統的なシグナルの扱いと同じであり、 処理待ちのブロックされたシグナルは \fBexecve\fP(2)
 134 の前後で処理待ちのままとなる)。
 135 .SS スレッドでの扱い
 136 マルチスレッドプログラムにおける signalfd ファイルディスクリプタの扱いは シグナルの標準的な扱いと全く同じである。
 137 言い換えると、あるスレッドが signalfd ファイルディスクリプタから 読み出しを行うと、そのスレッド自身宛てのシグナルとプロセス (すなわち
 138 スレッドグループ全体) 宛てのシグナルが読み出される。 (スレッドは同じプロセスの他のスレッド宛てのシグナルを読み出すことはできない。)
 139 .SH 返り値
 140 成功すると、 \fBsignalfd\fP()  は signalfd ファイルディスクリプタを返す。 返されるファイルディスクリプタは、 \fIfd\fP が
 141 \-1 の場合は新規のファイルディスクリプタであり、 \fIfd\fP が有効な signalfd ファイルディスクリプタだった場合は \fIfd\fP 自身である。
 142 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
 143 .SH エラー
 144 .TP
 145 \fBEBADF\fP
 146 ファイルディスクリプタ \fIfd\fP が有効なファイルディスクリプタでない。
 147 .TP
 148 \fBEINVAL\fP
 149 .\" or, the
 150 .\" .I sizemask
 151 .\" argument is not equal to
 152 .\" .IR sizeof(sigset_t) ;
 153 \fIfd\fP が有効な signalfd ファイルディスクリプタではない。
 154 .TP
 155 \fBEINVAL\fP
 156 \fIflags\fP が無効である。もしくは、Linux 2.6.26 以前の場合には \fIflags\fP が 0 以外である。
 157 .TP
 158 \fBEMFILE\fP
 159 オープン済みのファイルディスクリプタの数がプロセスあたりの上限に 達していた。
 160 .TP
 161 \fBENFILE\fP
 162 オープン済みのファイル総数がシステム全体の上限に達していた。
 163 .TP
 164 \fBENODEV\fP
 165 (カーネル内の) 無名 inode デバイスをマウントできなかった。
 166 .TP
 167 \fBENOMEM\fP
 168 新しい signalfd ファイルディスクリプタを生成するのに十分なメモリがなかった。
 169 .SH バージョン
 170 .\" signalfd() is in glibc 2.7, but reportedly does not build
 171 \fBsignalfd\fP()  はカーネル 2.6.22 以降の Linux で利用可能である。 正しく動作する glibc 側のサポートはバージョン
 172 2.8 以降で提供されている。 \fBsignalfd4\fP()  システムコール (「注意」参照) は カーネル 2.6.27 以降の Linux
 173 で利用可能である。
 174 .SH 準拠
 175 \fBsignalfd\fP()  と \fBsignalfd4\fP()  は Linux 固有である。
 176 .SH 注意
 177 実際の Linux のシステムコールでは \fIsize_t sizemask\fP という引き数が追加で必要である。この引き数で \fImask\fP
 178 のサイズを指定する。 glibc の \fBsignalfd\fP()  ラッパー関数にはこの引き数は含まれず、
 179 ラッパー関数が必要な値を計算して内部で呼び出すシステムコールに提供する。
 180
 181 一つのプロセスは複数の signalfd ファイルディスクリプタを生成することができる。
 182 これにより、異なるファイルディスクリプタで異なるシグナルを受け取ることが できる (この機能は \fBselect\fP(2), \fBpoll\fP(2),
 183 \fBepoll\fP(7)  を使ってファイルディスクリプタを監視する場合に有用かもしれない。
 184 異なるシグナルが到着すると、異なるファイルディスクリプタが利用可能に なるからだ)。 一つのシグナルが二つ以上のファイルディスクリプタの \fImask\fP
 185 に含まれている場合、そのシグナルの発生はそのシグナルを \fImask\fP に含むファイルディスクリプタのうちいずれか一つから読み出すことができる。
 186 .SS "下層にある Linux のシステムコール"
 187 下層にある Linux システムコールは二種類あり、 \fBsignalfd\fP()  と、もっと新しい \fBsignalfd4\fP()  である。
 188 \fBsignalfd\fP()  は \fIflags\fP 引き数を実装していない。 \fBsignalfd4\fP()  では上記の値の \fIflags\fP
 189 が実装されている。 glibc 2.9 以降では、 \fBsignalfd\fP()  のラッパー関数は、 \fBsignalfd4\fP()
 190 が利用可能であれば、これを使用する。
 191 .SH バグ
 192 .\" The fix also was put into 2.6.24.5
 193 カーネル 2.6.25 より前では、 \fBsigqueue\fP(3)  により送信されたシグナルと一緒に渡されるデータでは、フィールド
 194 \fIssi_ptr\fP と \fIssi_int\fP は設定されない。
 195 .SH 例
 196 下記のプログラムは、シグナル \fBSIGINT\fP と \fBSIGQUIT\fP を signalfd ファイルディスクリプタ経由で受信する。 シグナル
 197 \fBSIGQUIT\fP 受信後にプログラムは終了する。 以下に示すシェルセッションにこのプログラムの使い方を示す。
 198 .in +4n
 199 .nf
 200
 201 $\fB ./signalfd_demo\fP
 202 \fB^C\fP                   # Control\-C generates SIGINT
 203 Got SIGINT
 204 \fB^C\fP
 205 Got SIGINT
 206 \fB^\e\fP                    # Control\-\e generates SIGQUIT
 207 Got SIGQUIT
 208 $
 209 .fi
 210 .in
 211 .SS プログラムのソース
 212 \&
 213 .nf
 214 #include <sys/signalfd.h>
 215 #include <signal.h>
 216 #include <unistd.h>
 217 #include <stdlib.h>
 218 #include <stdio.h>
 219
 220 #define handle_error(msg) \e
 221     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 222
 223 int
 224 main(int argc, char *argv[])
 225 {
 226     sigset_t mask;
 227     int sfd;
 228     struct signalfd_siginfo fdsi;
 229     ssize_t s;
 230
 231     sigemptyset(&mask);
 232     sigaddset(&mask, SIGINT);
 233     sigaddset(&mask, SIGQUIT);
 234
 235     /* Block signals so that they aren\(aqt handled
 236        according to their default dispositions */
 237
 238     if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1)
 239         handle_error("sigprocmask");
 240
 241     sfd = signalfd(\-1, &mask, 0);
 242     if (sfd == \-1)
 243         handle_error("signalfd");
 244
 245     for (;;) {
 246         s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));
 247         if (s != sizeof(struct signalfd_siginfo))
 248             handle_error("read");
 249
 250         if (fdsi.ssi_signo == SIGINT) {
 251             printf("Got SIGINT\en");
 252         } else if (fdsi.ssi_signo == SIGQUIT) {
 253             printf("Got SIGQUIT\en");
 254             exit(EXIT_SUCCESS);
 255         } else {
 256             printf("Read unexpected signal\en");
 257         }
 258     }
 259 }
 260 .fi
 261 .SH 関連項目
 262 \fBeventfd\fP(2), \fBpoll\fP(2), \fBread\fP(2), \fBselect\fP(2), \fBsigaction\fP(2),
 263 \fBsigprocmask\fP(2), \fBsigwaitinfo\fP(2), \fBtimerfd_create\fP(2), \fBsigsetops\fP(3),
 264 \fBsigwait\fP(3), \fBepoll\fP(7), \fBsignal\fP(7)
 265 .SH この文書について
 266 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 267 である。プロジェクトの説明とバグ報告に関する情報は
 268 http://www.kernel.org/doc/man\-pages/ に書かれている。