pthread_atfork(3)pthread_atfork(3)NAMEpthread_atfork - Declares fork handler routines to be called when the
calling thread's process forks a child process
SYNOPSIS
#include <pthread.h>
int pthread_atfork(
void (*prepare)(void),
void (*parent)(void),
void (*child)(void) );
LIBRARY
Standard C Library (libc.so, libc.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
Address of a routine that performs the fork preparation handling. This
routine is called in the parent process before creating the child
process. Address of a routine that performs the fork parent handling.
This routine is called in the parent process after creating the child
process and before returning to the caller of fork(2). Address of a
routine that performs the fork child handling. This routine is called
in the child process before returning to the caller of fork(2).
DESCRIPTION
This routine allows a main program or library to control resources dur‐
ing a fork(2) operation by declaring fork handler routines, as follows:
The fork handler routine specified in the prepare argument is called
before fork(2) executes. The fork handler routine specified in the
parent argument is called after fork(2) executes within the parent
process. The fork handler routine specified in the child argument is
called in the new child process after fork(2) executes.
Your program (or library) can use fork handlers to ensure that program
context in the child process is consistent and meaningful. After fork()
executes, only the calling thread exists in the child process, and the
state of all memory in the parent process is replicated in the child
process, including the states of any mutexes, condition variables, and
so on.
For example, in the new child process there might exist locked mutexes
that are copies of mutexes that were locked in the parent process by
threads that do not exist in the child process. Therefore, any associ‐
ated program state might be inconsistent in the child process.
The program can avoid this problem by calling pthread_atfork to provide
routines that acquire and release resources that are critical to the
child process. For example, the prepare handler should lock all mutexes
that you want to be usable in the child process. The parent handler
just unlocks those mutexes. The child handler will also unlock them
all--and might also create threads or reset any program state for the
child process.
If no fork handling is desired, you can set any of this routine's argu‐
ments to NULL.
NOTES
It is not legal to call pthread_atfork from within a fork handler rou‐
tine. Doing so could cause a deadlock.
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error. Possible return values are as follows:
Successful completion Insufficient table space exists to record the
fork handler routines' addresses.
ERRORS
None
EXAMPLES
For example, if your library uses a mutex my_mutex, you might provide
pthread_atfork handler routines coded as follows:
void my_prepare(void)
{
pthread_mutex_lock(&my_mutex);
}
void my_parent(void)
{
pthread_mutex_unlock(&my_mutex);
}
void my_child(void)
{
pthread_mutex_unlock(&my_mutex);
/* Reinitialize state that doesn't apply...like heap owned */
/* by other threads */
}
{
.
.
.
pthread_atfork(my_prepare, my_parent, my_child);
.
.
fork();
}
SEE ALSO
Functions: pthread_create(3)
Manuals: Guide to DECthreads, Programmer's Guide
pthread_atfork(3)