.\"   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) 2000 WAKABAYASHI, Takeyasu
.\"         all rights reserved.
.\" Translated on Fri Jan 14 16:50:24 JST 2000
.\"         by WAKABAYASHI, Takeyasu <twakaba@eco.toyama-u.ac.jp>
.\" Updated and modified Sun Feb  2 01:39:34 JST 2003
.\"         by Suzuki Takashi.
.\"
.\"WORD:    install    登録
.\"
.TH PTHREAD_ATFORK 3 LinuxThreads

.SH "名前"
pthread_atfork \- fork(2) の際に呼び出されるハンドラを登録する

.SH "書式"
.BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void), void (*" child ")(void));"

.\" .SH DESCRIPTION
.SH 説明

.B "pthread_atfork"
は
.BR "fork" (2)
によって新しいプロセスが生成される際、その直前と直後に呼び出される
ハンドラ関数を登録する。
.I "prepare"
ハンドラは、新しいプロセスが生成される直前に親プロセスから
呼び出される。
.I "parent"
ハンドラは、
.BR "fork" (2)
がリターンする直前に親プロセスから呼び出される。
.I "child"
ハンドラは
.BR "fork" (2)
が返る直前に子プロセスから呼び出される。

.IR "prepare" ,
.I "parent"
および
.I "child"
の三つのハンドラのうちの一つまたは複数に
.BR "NULL"
を与えることができるが、これは対応する時点でいかなるハンドラをも
呼び出す必要がないことを意味する。

.B "pthread_atfork"
は複数のハンドラの組合せを登録するために複数回
呼び出すことが可能である。
.BR "fork" (2)
の時点で複数の
.I "prepare"
ハンドラは LIFO 順で呼び出される(
.BR "pthread_atfork"
で最後に加えられたものが
.BR "fork" 
の前に最初に呼び出される)。
他方、
.I "parent"
と
.I "child"
は FIFO 順で呼び出される
(最初に加えられたものが最初に呼び出される)。

.BR "pthread_atfork"
の目的を理解するために、
.BR "fork" (2)
は、現在ロック状態にある mutex も含めて、呼び出したスレッドのみの
メモリ空間全体を複製することを思い出そう。つまり、他のスレッドは
子プロセスでは実行されていないのである。従って、
.BR "fork"
を呼び出したスレッド以外のスレッドによって mutex がロックされている
のならば、その mutex は子プロセスの中で永遠にロックされたままであり、
子プロセスの実行をブロックする可能性がある。
これを避けるためには、
.B "pthread_atfork"
で次のようなハンドラを登録すれば良いだろう:
.I "prepare"
ハンドラが大域的な mutex を(ロックする際の順序で)ロックし、
.I "parent"
と
.I "child"
がそれらを(逆の順に)アンロックする。
または、
.I "prepare"
と
.I "parent"
を
.B "NULL"
に設定し、
.I "child"
を大域的な mutex に対して
.B "pthread_mutex_init"
を呼び出す関数に設定しても良いだろう。

.SH 返り値

.B "pthread_atfork"
は成功すれば 0 を返し、エラーがあれば非ゼロのエラーコードを返す。

.SH "エラー"
.TP
.B "ENOMEM"
ハンドラを登録するのにメモリが足りない。

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

.SH "関連項目"
.BR "fork" (2),
.BR "pthread_mutex_lock" (3),
.BR "pthread_mutex_unlock" (3).

[訳注] glibc-linuxthreads の最新のドキュメントは Texinfo形式で提供されている。
以下は glibc-linuxthreads-2.3.1 の Texinfo ファイルからの引用である。

.B "pthread_atfork"
の目的を理解するために、
.B "fork"
が現在ロック状態にある mutex も含めたメモリ空間全体を、
しかし呼び出しスレッドだけを複製することを思い出してほしい。
つまり、他のスレッドは子プロセスでは実行されない。
mutex は
.B "fork"
の後は使うことができず、子プロセスで
.B "pthread_mutex_init"
を使って初期化されなければならない。
これは現在の実装の制限で、将来のバージョンでも存在するかもしれないし、
存在しないかもしれない。

これを避けるためには、
.B "pthread_atfork"
で次のようなハンドラを登録すればよい:
.I "prepare"
ハンドラで mutex を (ロックする際の順序で) ロックし、
.I "parent"
ハンドラで mutex をロック解除する。
.I "child"
ハンドラでは
.B "pthread_mutex_init"
を使用して mutex を初期化しなければならない。
条件変数などの他の同期オブジェクトについても同様である。

グローバル mutex を fork の前にロックすると、
他のスレッドはすべて、それらのグローバル mutex で保護される
コードのクリティカル領域から締め出される。したがって
.B "fork"
が親プロセスのアドレス空間のスナップショットを取ると、
そのスナップショットは有効で安定したデータをコピーする。
子プロセスで同期オブジェクトを初期化することで
親プロセスのスレッドサブシステムに由来するものが適切に清められることが保証される。
例えば、 mutex は獲得を待つスレッドの待ちキューを引き継ぐが、
この待ちキューは子プロセスでは意味を持たない。
mutex を初期化することでこのことに対処する。