man3/pthread_atfork.3

   1 '\" t
   2 .\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREAD_ATFORK 3 2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 pthread_atfork \- register fork handlers
  29 .SH SYNOPSIS
  30 .nf
  31 .B  #include <pthread.h>
  32 .PP
  33 .BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void),"
  34 .BI "                   void (*" child ")(void));"
  35 .fi
  36 .PP
  37 Link with \fI\-pthread\fP.
  38 .SH DESCRIPTION
  39 The
  40 .BR pthread_atfork ()
  41 function registers fork handlers that are to be executed when
  42 .BR fork (2)
  43 is called by this thread.
  44 The handlers are executed in the context of the thread that calls
  45 .BR fork (2).
  46 .PP
  47 Three kinds of handler can be registered:
  48 .IP * 3
  49 .IR prepare
  50 specifies a handler that is executed before
  51 .BR fork (2)
  52 processing starts.
  53 .IP *
  54 .I parent
  55 specifies a handler that is executed in the parent process after
  56 .BR fork (2)
  57 processing completes.
  58 .IP *
  59 .I child
  60 specifies a handler that is executed in the child process after
  61 .BR fork (2)
  62 processing completes.
  63 .PP
  64 Any of the three arguments may be NULL if no handler is needed
  65 in the corresponding phase of
  66 .BR fork (2)
  67 processing.
  68 .PP
  69 .SH RETURN VALUE
  70 On success,
  71 .BR pthread_atfork ()
  72 returns zero.
  73 On error, it returns an error number.
  74 .BR pthread_atfork ()
  75 may be called multiple times by a thread,
  76 to register multiple handlers for each phase.
  77 The handlers for each phase are called in a specified order: the
  78 .I prepare
  79 handlers are called in reverse order of registration; the
  80 .I parent
  81 and
  82 .I child
  83 handlers are called in the order of registration.
  84 .SH ERRORS
  85 .TP
  86 .B ENOMEM
  87 Could not allocate memory to record the form handler entry.
  88 .SH CONFORMING TO
  89 POSIX.1-2001, POSIX.1-2008.
  90 .SH NOTES
  91 When
  92 .BR fork (2)
  93 is called in a multithreaded process,
  94 only the calling thread is duplicated in the child process.
  95 The original intention of
  96 .BR pthread_atfork ()
  97 was to allow the calling thread to be returned to a consistent state.
  98 For example, at the time of the call to
  99 .BR fork (2),
 100 other threads may have locked mutexes that are visible in the
 101 user-space memory duplicated in the child.
 102 Such mutexes would never be unlocked,
 103 since the threads that placed the locks are not duplicated in the child.
 104 The intent of
 105 .BR pthread_atfork ()
 106 was to provide a mechanism whereby the application (or a library)
 107 could ensure that mutexes and other process and thread state would be
 108 restored to a consistent state.
 109 In practice, this task is generally too difficult to be practicable.
 110 .PP
 111 After a
 112 .BR fork (2)
 113 in a multithreaded process returns in the child,
 114 the child should call only async-signal-safe functions (see
 115 .BR signal-safety (7))
 116 until such time as it calls
 117 .BR execve (2)
 118 to execute a new program.
 119 .PP
 120 POSIX.1 specifies that
 121 .BR pthread_atfork ()
 122 shall not fail with the error
 123 .BR EINTR .
 124 .SH SEE ALSO
 125 .BR fork (2),
 126 .BR atexit (3),
 127 .BR pthreads (7)