man3/pthread_atfork.3

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