pthread_atfork Subroutine

Purpose

Registers fork handlers.

Library

Threads Library (libpthreads.a)

Syntax

#include <sys/types.h>
#include <unistd.h>

int pthread_atfork (prepare, parent, child)
void (*prepare)(void);
void (*parent)(void);
void (*child)(void);

Description

The pthread_atfork subroutine registers fork cleanup handlers. The prepare handler is called before the processing of the fork subroutine commences. The parent handler is called after the processing of the fork subroutine completes in the parent process. The child handler is called after the processing of the fork subroutine completes in the child process.

When the fork subroutine is called, only the calling thread is duplicated in the child process, but all synchronization variables are duplicated. The pthread_atfork subroutine provides a way to prevent state inconsistencies and resulting deadlocks. The expected usage is that the prepare handler acquires all mutexes, and the two other handlers release them in the parent and child processes.

The prepare handlers are called in LIFO (Last In First Out) order; whereas the parent and child handlers are called in FIFO (first-in first-out) order. Thereafter, the order of calls to the pthread_atfork subroutine is significant.

Note: The pthread.h header file must be the first included file of each source file using the threads library.

Parameters

Item Description
prepare Points to the pre-fork cleanup handler. If no pre-fork handling is desired, the value of this pointer should be set to NULL.
parent Points to the parent post-fork cleanup handler. If no parent post-fork handling is desired, the value of this pointer should be set to NULL.
child Points to the child post-fork cleanup handler. If no child post-fork handling is desired, the value of this pointer should be set to NULL.

Return Values

Upon successful completion, the pthread_atfork subroutine returns a value of zero. Otherwise, an error number is returned to indicate the error.

Error Codes

The pthread_atfork subroutine will fail if:

Item Description
ENOMEM Insufficient table space exists to record the fork handler addresses.

The pthread_atfork subroutine will not return an error code of EINTR.