Debian Codegraph @

upstream/debian-unstable/man3/pthread_atfork.3

raw
1 .\" Copyright 2017, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_atfork 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_atfork \- register fork handlers
9 .SH LIBRARY
10 POSIX threads library
11 .RI ( libpthread ,\~ \-lpthread )
12 .SH SYNOPSIS
13 .nf
14 .B #include <pthread.h>
15 .P
16 .BI "int pthread_atfork(typeof(void (void)) *" prepare ,
17 .BI " typeof(void (void)) *" parent ,
18 .BI " typeof(void (void)) *" child );
19 .fi
20 .SH DESCRIPTION
21 The
22 .BR pthread_atfork ()
23 function registers fork handlers that are to be executed when
24 .BR fork (2)
25 is called by any thread in a process.
26 The handlers are executed in the context of the thread that calls
27 .BR fork (2).
28 .P
29 Three kinds of handler can be registered:
30 .IP \[bu] 3
31 .I prepare
32 specifies a handler that is executed in the parent process before
33 .BR fork (2)
34 processing starts.
35 .IP \[bu]
36 .I parent
37 specifies a handler that is executed in the parent process after
38 .BR fork (2)
39 processing completes.
40 .IP \[bu]
41 .I child
42 specifies a handler that is executed in the child process after
43 .BR fork (2)
44 processing completes.
45 .P
46 Any of the three arguments may be NULL if no handler is needed
47 in the corresponding phase of
48 .BR fork (2)
49 processing.
50 .SH RETURN VALUE
51 On success,
52 .BR pthread_atfork ()
53 returns zero.
54 On error, it returns an error number.
55 .BR pthread_atfork ()
56 may be called multiple times by a process
57 to register additional handlers.
58 The handlers for each phase are called in a specified order:
59 the
60 .I prepare
61 handlers are called in reverse order of registration;
62 the
63 .I parent
64 and
65 .I child
66 handlers are called in the order of registration.
67 .SH ERRORS
68 .TP
69 .B ENOMEM
70 Could not allocate memory to record the fork handler list entry.
71 .SH STANDARDS
72 POSIX.1-2008.
73 .SH HISTORY
74 POSIX.1-2001.
75 .SH NOTES
76 When
77 .BR fork (2)
78 is called in a multithreaded process,
79 only the calling thread is duplicated in the child process.
80 The original intention of
81 .BR pthread_atfork ()
82 was to allow the child process to be returned to a consistent state.
83 For example, at the time of the call to
84 .BR fork (2),
85 other threads may have locked mutexes that are visible in the
86 user-space memory duplicated in the child.
87 Such mutexes would never be unlocked,
88 since the threads that placed the locks are not duplicated in the child.
89 The intent of
90 .BR pthread_atfork ()
91 was to provide a mechanism whereby the application (or a library)
92 could ensure that mutexes and other process and thread state would be
93 restored to a consistent state.
94 In practice, this task is generally too difficult to be practicable.
95 .P
96 After a
97 .BR fork (2)
98 in a multithreaded process returns in the child,
99 the child should call only async-signal-safe functions (see
100 .BR signal\-safety (7))
101 until such time as it calls
102 .BR execve (2)
103 to execute a new program.
104 .P
105 POSIX.1 specifies that
106 .BR pthread_atfork ()
107 shall not fail with the error
108 .BR EINTR .
109 .SH SEE ALSO
110 .BR fork (2),
111 .BR atexit (3),
112 .BR pthreads (7)