Index for Section 3

Alphabetical listing for P

Bottom of page

pthread_atfork(3)
NAME
  pthread_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 standards
  as follows:

  IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS
  prepare
      Address of a routine that performs the fork preparation handling. This
      routine is called in the parent process before creating the child
      process.

  parent
      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).

  child
      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 during 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 associated 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 arguments
  to NULL.

NOTES
  It is not legal to call pthread_atfork from within a fork handler routine.
  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:

  0   Successful completion

  [ENOMEM]
      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

Index for Section 3

Alphabetical listing for P

Top of page