Debian Codegraph @

upstream/debian-unstable/man3/pthread_cleanup_push.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_cleanup_push 3 2025-08-20 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_cleanup_push, pthread_cleanup_pop \- push and pop
9 thread cancelation clean-up handlers
10 .SH LIBRARY
11 POSIX threads library
12 .RI ( libpthread ,\~ \-lpthread )
13 .SH SYNOPSIS
14 .nf
15 .B #include <pthread.h>
16 .P
17 .BI "void pthread_cleanup_push(typeof(void (void *)) *" routine ", void *" arg );
18 .BI "void pthread_cleanup_pop(int " execute );
19 .fi
20 .SH DESCRIPTION
21 These functions manipulate the calling thread's stack of
22 thread-cancelation clean-up handlers.
23 A clean-up handler is a function that is automatically executed
24 when a thread is canceled (or in various other circumstances
25 described below);
26 it might, for example, unlock a mutex so that
27 it becomes available to other threads in the process.
28 .P
29 The
30 .BR pthread_cleanup_push ()
31 function pushes
32 .I routine
33 onto the top of the stack of clean-up handlers.
34 When
35 .I routine
36 is later invoked, it will be given
37 .I arg
38 as its argument.
39 .P
40 The
41 .BR pthread_cleanup_pop ()
42 function removes the routine at the top of the stack of clean-up handlers,
43 and optionally executes it if
44 .I execute
45 is nonzero.
46 .P
47 A cancelation clean-up handler is popped from the stack
48 and executed in the following circumstances:
49 .IP \[bu] 3
50 When a thread is canceled,
51 all of the stacked clean-up handlers are popped and executed in
52 the reverse of the order in which they were pushed onto the stack.
53 .IP \[bu]
54 When a thread terminates by calling
55 .BR pthread_exit (3),
56 all clean-up handlers are executed as described in the preceding point.
57 (Clean-up handlers are
58 .I not
59 called if the thread terminates by
60 performing a
61 .I return
62 from the thread start function.)
63 .IP \[bu]
64 When a thread calls
65 .BR pthread_cleanup_pop ()
66 with a nonzero
67 .I execute
68 argument, the top-most clean-up handler is popped and executed.
69 .P
70 POSIX.1 permits
71 .BR pthread_cleanup_push ()
72 and
73 .BR pthread_cleanup_pop ()
74 to be implemented as macros that expand to text
75 containing
76 .RB \[aq] { \[aq]
77 and
78 .RB \[aq] } \[aq],
79 respectively.
80 For this reason, the caller must ensure that calls to these
81 functions are paired within the same function,
82 and at the same lexical nesting level.
83 (In other words, a clean-up handler is established only
84 during the execution of a specified section of code.)
85 .P
86 Calling
87 .BR longjmp (3)
88 .RB ( siglongjmp (3))
89 produces undefined results if any call has been made to
90 .BR pthread_cleanup_push ()
91 or
92 .BR pthread_cleanup_pop ()
93 without the matching call of the pair since the jump buffer
94 was filled by
95 .BR setjmp (3)
96 .RB ( sigsetjmp (3)).
97 Likewise, calling
98 .BR longjmp (3)
99 .RB ( siglongjmp (3))
100 from inside a clean-up handler produces undefined results
101 unless the jump buffer was also filled by
102 .BR setjmp (3)
103 .RB ( sigsetjmp (3))
104 inside the handler.
105 .SH RETURN VALUE
106 These functions do not return a value.
107 .SH ERRORS
108 There are no errors.
109 .SH ATTRIBUTES
110 For an explanation of the terms used in this section, see
111 .BR attributes (7).
112 .TS
113 allbox;
114 lbx lb lb
115 l l l.
116 Interface Attribute Value
117 T{
118 .na
119 .nh
120 .BR pthread_cleanup_push (),
121 .BR pthread_cleanup_pop ()
122 T} Thread safety MT-Safe
123 .TE
124 .SH VERSIONS
125 On glibc, the
126 .BR pthread_cleanup_push ()
127 and
128 .BR pthread_cleanup_pop ()
129 functions
130 .I are
131 implemented as macros that expand to text
132 containing
133 .RB \[aq] { \[aq]
134 and
135 .RB \[aq] } \[aq],
136 respectively.
137 This means that variables declared within the scope of
138 paired calls to these functions will be visible within only that scope.
139 .P
140 POSIX.1
141 .\" The text was actually added in the 2004 TC2
142 says that the effect of using
143 .IR return ,
144 .IR break ,
145 .IR continue ,
146 or
147 .I goto
148 to prematurely leave a block bracketed
149 .BR pthread_cleanup_push ()
150 and
151 .BR pthread_cleanup_pop ()
152 is undefined.
153 Portable applications should avoid doing this.
154 .SH STANDARDS
155 POSIX.1-2008.
156 .SH HISTORY
157 POSIX.1-2001.
158 glibc 2.0.
159 .SH EXAMPLES
160 The program below provides a simple example of the use of the functions
161 described in this page.
162 The program creates a thread that executes a loop bracketed by
163 .BR pthread_cleanup_push ()
164 and
165 .BR pthread_cleanup_pop ().
166 This loop increments a global variable,
167 .IR cnt ,
168 once each second.
169 Depending on what command-line arguments are supplied,
170 the main thread sends the other thread a cancelation request,
171 or sets a global variable that causes the other thread
172 to exit its loop and terminate normally (by doing a
173 .IR return ).
174 .P
175 In the following shell session,
176 the main thread sends a cancelation request to the other thread:
177 .P
178 .in +4n
179 .EX
180 .RB $ " ./a.out" ;
181 New thread started
182 cnt = 0
183 cnt = 1
184 Canceling thread
185 Called clean\-up handler
186 Thread was canceled; cnt = 0
187 .EE
188 .in
189 .P
190 From the above, we see that the thread was canceled,
191 and that the cancelation clean-up handler was called
192 and it reset the value of the global variable
193 .I cnt
194 to 0.
195 .P
196 In the next run, the main program sets a
197 global variable that causes other thread to terminate normally:
198 .P
199 .in +4n
200 .EX
201 .RB $ " ./a.out x" ;
202 New thread started
203 cnt = 0
204 cnt = 1
205 Thread terminated normally; cnt = 2
206 .EE
207 .in
208 .P
209 From the above, we see that the clean-up handler was not executed (because
210 .I cleanup_pop_arg
211 was 0), and therefore the value of
212 .I cnt
213 was not reset.
214 .P
215 In the next run, the main program sets a global variable that
216 causes the other thread to terminate normally,
217 and supplies a nonzero value for
218 .IR cleanup_pop_arg :
219 .P
220 .in +4n
221 .EX
222 .RB $ " ./a.out x 1" ;
223 New thread started
224 cnt = 0
225 cnt = 1
226 Called clean\-up handler
227 Thread terminated normally; cnt = 0
228 .EE
229 .in
230 .P
231 In the above, we see that although the thread was not canceled,
232 the clean-up handler was executed, because the argument given to
233 .BR pthread_cleanup_pop ()
234 was nonzero.
235 .SS Program source
236 \&
237 .\" SRC BEGIN (pthread_cleanup_push.c)
238 .EX
239 #include <err.h>
240 #include <errno.h>
241 #include <pthread.h>
242 #include <stdio.h>
243 #include <stdlib.h>
244 #include <sys/types.h>
245 #include <unistd.h>
246 \&
247 static int done = 0;
248 static int cleanup_pop_arg = 0;
249 static int cnt = 0;
250 \&
251 static void
252 cleanup_handler(void *arg)
253 {
254 printf("Called clean\-up handler\[rs]n");
255 cnt = 0;
256 }
257 \&
258 static void *
259 thread_start(void *arg)
260 {
261 time_t curr;
262 \&
263 printf("New thread started\[rs]n");
264 \&
265 pthread_cleanup_push(cleanup_handler, NULL);
266 \&
267 curr = time(NULL);
268 \&
269 while (!done) {
270 pthread_testcancel(); /* A cancelation point */
271 if (curr < time(NULL)) {
272 curr = time(NULL);
273 printf("cnt = %d\[rs]n", cnt); /* A cancelation point */
274 cnt++;
275 }
276 }
277 \&
278 pthread_cleanup_pop(cleanup_pop_arg);
279 return NULL;
280 }
281 \&
282 int
283 main(int argc, char *argv[])
284 {
285 pthread_t thr;
286 int s;
287 void *res;
288 \&
289 s = pthread_create(&thr, NULL, thread_start, NULL);
290 if (s != 0)
291 errc(EXIT_FAILURE, s, "pthread_create");
292 \&
293 sleep(2); /* Allow new thread to run a while */
294 \&
295 if (argc > 1) {
296 if (argc > 2)
297 cleanup_pop_arg = atoi(argv[2]);
298 done = 1;
299 \&
300 } else {
301 printf("Canceling thread\[rs]n");
302 s = pthread_cancel(thr);
303 if (s != 0)
304 errc(EXIT_FAILURE, s, "pthread_cancel");
305 }
306 \&
307 s = pthread_join(thr, &res);
308 if (s != 0)
309 errc(EXIT_FAILURE, s, "pthread_join");
310 \&
311 if (res == PTHREAD_CANCELED)
312 printf("Thread was canceled; cnt = %d\[rs]n", cnt);
313 else
314 printf("Thread terminated normally; cnt = %d\[rs]n", cnt);
315 exit(EXIT_SUCCESS);
316 }
317 .EE
318 .\" SRC END
319 .SH SEE ALSO
320 .BR pthread_cancel (3),
321 .BR pthread_cleanup_push_defer_np (3),
322 .BR pthread_setcancelstate (3),
323 .BR pthread_testcancel (3),
324 .BR pthreads (7)