108 lines
2.3 KiB
Plaintext
108 lines
2.3 KiB
Plaintext
'\"macro stdmacro
|
|
.\"
|
|
.\" ----------------
|
|
.TH pthread_atfork 3P
|
|
.\"
|
|
.\" ----------------
|
|
.SH NAME
|
|
pthread_atfork \- register fork() handlers
|
|
.\"
|
|
.\" ----------------
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.nf
|
|
.ft 3
|
|
#include <pthread.h>
|
|
.HP
|
|
.ft 3
|
|
int pthread_atfork(void (\(**prepare)(void), void (\(**parent)(void),
|
|
.br
|
|
void (\(**child)(void));
|
|
.ft 1
|
|
.fi
|
|
.Op
|
|
.\"
|
|
.\" ----------------
|
|
.SH DESCRIPTION
|
|
The
|
|
.IR pthread_atfork ()
|
|
function registers three functions which are invoked when any thread calls
|
|
.IR fork ().
|
|
If
|
|
.I prepare
|
|
is not
|
|
.B NULL
|
|
it must be a function that will be called prior to the actual
|
|
.IR fork ()
|
|
in the parent context.
|
|
Similarly,
|
|
.I parent
|
|
and
|
|
.IR child ,
|
|
if not
|
|
.BR NULL ,
|
|
will be called after
|
|
.IR fork ()
|
|
in the contexts of the parent and child respectively.
|
|
Multiple calls to
|
|
.IR pthread_atfork ()
|
|
are possible;
|
|
.I prepare
|
|
handlers are run in the opposite order to which they were registered and
|
|
.I parent
|
|
and
|
|
.I child
|
|
handlers in the order they were registered.
|
|
.\"
|
|
.PP
|
|
When
|
|
.IR fork ()
|
|
is called from a threaded application a new process is created
|
|
with a single thread (the caller);
|
|
other threads which may be running in the parent do not exist in the
|
|
child.
|
|
A side effect of this behavior is that locks which protect data
|
|
in the process may be held in the child by threads which no longer exist.
|
|
If the single surviving thread were to encounter these locks it would
|
|
wait indefinitely.
|
|
.\"
|
|
.PP
|
|
Using
|
|
.IR fork ()
|
|
handlers an application may protect its own data by synchronizing its
|
|
state with respect to
|
|
.IR fork ().
|
|
Typically this means adding a
|
|
.I prepare
|
|
handler to acquire a lock and
|
|
.I parent
|
|
and
|
|
.I child
|
|
handlers to unlock it again, ensuring that the child may use the lock
|
|
(and associated data) as usual.
|
|
.\"
|
|
.PP
|
|
Although an application may protect its own data in this way, libraries
|
|
it uses may not.
|
|
Therefore the child process should restrict itself to its own code
|
|
and to system calls.
|
|
This restriction is less onerous than it appears since
|
|
the most common reason for using
|
|
.IR fork ()
|
|
in a threaded application is in order to start a new process with
|
|
.IR exec ().
|
|
.\"
|
|
.\" ----------------
|
|
.SH DIAGNOSTICS
|
|
On success
|
|
.IR pthread_atfork ()
|
|
returns zero; otherwise an error number is returned:
|
|
.\"
|
|
.TP 15
|
|
.B [ENOMEM]
|
|
Memory cannot be allocated to record the handlers.
|
|
.\"
|
|
.\" ----------------
|
|
.SH "SEE ALSO"
|
|
fork(2), exec(2).
|