.TH PTHREAD_ATFORK 3 LinuxThreads

.SH NAME
pthread_atfork \- register handlers to be called at fork(2) time

.SH SYNOPSIS
.B #include <pthread.h>

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

.SH DESCRIPTION

\fBpthread_atfork\fP registers handler functions to be called just before
and just after a new process is created with \fBfork\fP(2). The \fIprepare\fP
handler will be called from the parent process, just before the new
process is created. The \fIparent\fP handler will be called from the parent
process, just before \fBfork\fP(2) returns. The \fIchild\fP handler will be
called from the child process, just before \fBfork\fP(2) returns.

One or several of the three handlers \fIprepare\fP, \fIparent\fP and \fIchild\fP
can be given as \fBNULL\fP, meaning that no handler needs to be called at
the corresponding point.

\fBpthread_atfork\fP can be called several times to install several sets
of handlers. At \fBfork\fP(2) time, the \fIprepare\fP handlers are called in
LIFO order (last added with \fBpthread_atfork\fP, first called before \fBfork\fP),
while the \fIparent\fP and \fIchild\fP handlers are called in FIFO order
(first added, first called).

To understand the purpose of \fBpthread_atfork\fP, recall that \fBfork\fP(2)
duplicates the whole memory space, including mutexes in their current
locking state, but only the calling thread: other threads are not
running in the child process.  The mutexes are not usable after the
\fBfork\fP and must be initialized with \fIpthread_mutex_init\fP in the child
process.  This is a limitation of the current implementation and might
or might not be present in future versions.

.SH "RETURN VALUE"

\fBpthread_atfork\fP returns 0 on success and a non-zero error code on error.

.SH ERRORS
.TP
\fBENOMEM\fP
insufficient memory available to register the handlers.

.SH AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>

.SH "SEE ALSO"
\fBfork\fP(2),
\fBpthread_mutex_lock\fP(3),
\fBpthread_mutex_unlock\fP(3).