.\"   Copyright (C) 1996-1999 Free Software Foundation, Inc.
.\"
.\"   Permission is granted to make and distribute verbatim copies of
.\" this manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\"   Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\"   Permission is granted to copy and distribute translations of this
.\" manual into another language, under the above conditions for modified
.\" versions, except that this permission notice may be stated in a
.\" translation approved by the Foundation.
.\"
.\" Copyright (C) 1996 Xavier Leroy.
.\"
.\" Japanese Version Copyright (C) 2002-2003 Suzuki Takashi
.\"         all rights reserved.
.\" Translated Tue Dec 31 20:02:27 JST 2002
.\"         by Suzuki Takashi.
.\"
.\"WORD:    handling of signals シグナルハンドリング
.\"WORD:    signal mask         シグナルマスク
.\"WORD:    calling thread      呼び出しスレッド
.\"WORD:    signal action       シグナルアクション
.\"WORD:    signal handler      シグナルハンドラ
.\"
.\"
.TH PTHREAD_SIGNAL 3 LinuxThreads


.SH "名前"
pthread_sigmask, pthread_kill, sigwait \- スレッド内でのシグナルハンドリング

.SH "書式"
.B #include <pthread.h>
.br
.B #include <signal.h>

.BI "int pthread_sigmask(int " how ", const sigset_t *" newmask ", sigset_t *" oldmask ");"

.BI "int pthread_kill(pthread_t " thread ", int " signo ");"

.BI "int sigwait(const sigset_t *" set ", int *" sig ");"

.SH "説明"

.B "pthread_sigmask"
は呼び出しスレッドのシグナルマスクを
引数
.I "how"
および
.I "newmask"
で指定されるように変更する。
.I "oldmask"
が
.B "NULL"
でないときには、直前のシグナルマスクが
.I "oldmask"
で指し示される領域に格納される。

引数
.I "how"
および
.I "newmask"
の意味は
.BR "sigprocmask" (2)
の引数の意味と同じである。
.I "how"
が
.B "SIG_SETMASK"
のときには、
シグナルマスクが
.I "newmask"
に設定される。
.I "how"
が
.B "SIG_BLOCK"
のときには、
.I "newmask"
で指定されるシグナルが現時点のシグナルマスクに追加される。
.I "how"
が
.BR "SIG_UNBLOCK"
のときには、
.I "newmask"
で指定されるシグナルが現時点のシグナルマスクから取り除かれる。

シグナルマスクはスレッドごとに設定されることを思い出してほしい。
しかし
.BR "sigaction" (2)
で設定される
シグナルアクションとシグナルハンドラは、
すべてのスレッドで共通である。

.B "pthread_kill"
はシグナル番号
.I "signo"
のシグナルを
スレッド
.IR "thread"
に送信する。
シグナルは
.BR "kill" (2)
に書かれているように配送されハンドルされる。

.B "sigwait"
は
.I "set"
で指定されるシグナルのうちいずれか 1 つが呼び出しスレッドに
配送されるまで呼び出しスレッドの実行を停止する。
そして受信したシグナルの数を
.I "sig"
で指し示される領域に格納して返る。
.I "set"
で指定されるシグナルは
.B "sigwait"
に入るときにブロックされていなければならず、無視されてはならない。
配送されたシグナルに対するシグナルハンドラが登録されていても、
ハンドラ関数は呼び出され
.I "ない"
。

.SH "取り消し"

.B "sigwait"
は取り消しポイントである。

.SH "返り値"

成功すると、0 が返る。
失敗の場合、非 0 のエラーコードが返る。

.SH "エラー"

関数
.B "pthread_sigmask"
はエラーのとき、次のようなエラーコードを返す:
.RS
.TP
.B "EINVAL"
.I "how"
が
.B "SIG_SETMASK"
および
.B "SIG_BLOCK"
、
.B "SIG_UNBLOCK"
のいずれでもない。

.TP
.B "EFAULT"
.I "newmask"
または
.I "oldmask"
が無効なアドレスを指している。
.RE

関数
.B "pthread_kill"
はエラーのとき、次のようなエラーコードを返す:
.RS
.TP
.B "EINVAL"
.I "signo"
は有効なシグナル番号でない。

.TP
.B "ESRCH"
スレッド
.I "thread"
は存在しない (例えば、そのスレッドはすでに終了している) 。
.RE

関数
.B "sigwait"
がエラーを返すことはない。

.SH "著者"
Xavier Leroy <Xavier.Leroy@inria.fr>

.SH "関連項目"
.BR "sigprocmask" (2),
.BR "kill" (2),
.BR "sigaction" (2),
.BR "sigsuspend" (2).

.SH "注意"

.B "sigwait"
が確実に機能するように、
配送を待つシグナルは、呼び出しスレッドだけでなく
すべてのスレッドでブロックされていなければならない。
そうでない場合、POSIX のシグナル配送機構は
シグナルを受信するスレッドが
.B "sigwait"
を呼び出しているスレッドとなることを保証しない。
これを実現する最もよい方法は、
どのスレッドを生成するよりも前にそれらのシグナルをブロックし、
プログラム中では
.B "sigwait"
を呼び出す以外、ブロックを解除しないことである。

.SH "バグ"

LinuxThreads のシグナルハンドリングは POSIX 標準とは大きく異なっている。
POSIX 標準によると、「非同期の」 (外部の) シグナルは
プロセス全体 (すべてのスレッドの集まり) に対して発行され、
その後特定の 1 つのスレッドに配送される。
実際にシグナルを受信するスレッドは
その時点でシグナルをブロックしていないスレッドのいずれかとなる。

LinuxThreads では、
それぞれのスレッドが実際には固有の PID をもつカーネルプロセスであるため、
外部のシグナルは特定の 1 つのスレッドに直接配送される。
例えば、もし別のスレッドが
.B "sigwait"
を使ってそのシグナルをブロックしても、
そのスレッドが再開されることはない。

.B "sigwait"
の LinuxThreads の実装では、
.B "sigwait"
は待ちの期間中、
.I "set"
に含まれるシグナルに対応するダミーのシグナルハンドラを登録する。
シグナルハンドラはすべてのスレッドで共通であるため、
他のスレッドはこれらのシグナルに対して独自のシグナルハンドラを登録してはならない。
あるいはその代わりに、すべてのスレッドが
これらのシグナルをブロックしなければならない
(このことはとにかく推奨されている -- 注意のセクションを参照のこと) 。