Debian Codegraph @

upstream/debian-trixie/man3/pthread_cleanup_push.3

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