linuxthreads/man/pthread_atfork.man

   1 .TH PTHREAD_ATFORK 3 LinuxThreads
   2
   3 .SH NAME
   4 pthread_atfork \- register handlers to be called at fork(2) time
   5
   6 .SH SYNOPSIS
   7 #include <pthread.h>
   8
   9 int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void));
  10
  11 .SH DESCRIPTION
  12
  13 !pthread_atfork! registers handler functions to be called just before
  14 and just after a new process is created with !fork!(2). The |prepare|
  15 handler will be called from the parent process, just before the new
  16 process is created. The |parent| handler will be called from the parent
  17 process, just before !fork!(2) returns. The |child| handler will be
  18 called from the child process, just before !fork!(2) returns.
  19
  20 One or several of the three handlers |prepare|, |parent| and |child|
  21 can be given as !NULL!, meaning that no handler needs to be called at
  22 the corresponding point.
  23
  24 !pthread_atfork! can be called several times to install several sets
  25 of handlers. At !fork!(2) time, the |prepare| handlers are called in
  26 LIFO order (last added with !pthread_atfork!, first called before !fork!),
  27 while the |parent| and |child| handlers are called in FIFO order
  28 (first added, first called).
  29
  30 To understand the purpose of !pthread_atfork!, recall that !fork!(2)
  31 duplicates the whole memory space, including mutexes in their current
  32 locking state, but only the calling thread: other threads are not
  33 running in the child process. Thus, if a mutex is locked by a thread
  34 other than the thread calling !fork!, that mutex will remain locked
  35 forever in the child process, possibly blocking the execution of the
  36 child process. To avoid this, install handlers with !pthread_atfork!
  37 as follows: the |prepare| handler locks the global mutexes (in locking
  38 order), and the |parent| and |child| handlers unlock them (in
  39 reverse order). Alternatively, |prepare| and |parent| can be set to
  40 !NULL! and |child| to a function that calls !pthread_mutex_init! on
  41 the global mutexes.
  42
  43 .SH "RETURN VALUE"
  44
  45 !pthread_atfork! returns 0 on success and a non-zero error code on error.
  46
  47 .SH ERRORS
  48 .TP
  49 !ENOMEM!
  50 insufficient memory available to register the handlers.
  51
  52 .SH AUTHOR
  53 Xavier Leroy <Xavier.Leroy@inria.fr>
  54
  55 .SH "SEE ALSO"
  56 !fork!(2),
  57 !pthread_mutex_lock!(3),
  58 !pthread_mutex_unlock!(3).