Debian Codegraph @

upstream/debian-unstable/man3/pthread_cleanup_push_defer_np.3

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH pthread_cleanup_push_defer_np 3 2025-05-17 "Linux man-pages 6.18"
6 .SH NAME
7 pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- push and pop
8 thread cancelation clean-up handlers while saving cancelability type
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 "void pthread_cleanup_push_defer_np(typeof(void (void *)) *" routine ,
17 .BI " void *" arg );
18 .BI "void pthread_cleanup_pop_restore_np(int " execute );
19 .fi
20 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR pthread_cleanup_push_defer_np (),
27 .BR pthread_cleanup_pop_defer_np ():
28 .nf
29 _GNU_SOURCE
30 .fi
31 .SH DESCRIPTION
32 These functions are the same as
33 .BR pthread_cleanup_push (3)
34 and
35 .BR pthread_cleanup_pop (3),
36 except for the differences noted on this page.
37 .P
38 Like
39 .BR pthread_cleanup_push (3),
40 .BR pthread_cleanup_push_defer_np ()
41 pushes
42 .I routine
43 onto the thread's stack of cancelation clean-up handlers.
44 In addition, it also saves the thread's current cancelability type,
45 and sets the cancelability type to "deferred" (see
46 .BR pthread_setcanceltype (3));
47 this ensures that cancelation clean-up will occur
48 even if the thread's cancelability type was "asynchronous"
49 before the call.
50 .P
51 Like
52 .BR pthread_cleanup_pop (3),
53 .BR pthread_cleanup_pop_restore_np ()
54 pops the top-most clean-up handler from the thread's
55 stack of cancelation clean-up handlers.
56 In addition, it restores the thread's cancelability
57 type to its value at the time of the matching
58 .BR pthread_cleanup_push_defer_np ().
59 .P
60 The caller must ensure that calls to these
61 functions are paired within the same function,
62 and at the same lexical nesting level.
63 Other restrictions apply, as described in
64 .BR pthread_cleanup_push (3).
65 .P
66 This sequence of calls:
67 .P
68 .in +4n
69 .EX
70 pthread_cleanup_push_defer_np(routine, arg);
71 pthread_cleanup_pop_restore_np(execute);
72 .EE
73 .in
74 .P
75 is equivalent to (but shorter and more efficient than):
76 .P
77 .\" As far as I can see, LinuxThreads reverses the two substeps
78 .\" in the push and pop below.
79 .in +4n
80 .EX
81 int oldtype;
82 \&
83 pthread_cleanup_push(routine, arg);
84 pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
85 \&...
86 pthread_setcanceltype(oldtype, NULL);
87 pthread_cleanup_pop(execute);
88 .EE
89 .in
90 .SH STANDARDS
91 GNU;
92 hence the suffix "_np" (nonportable) in the names.
93 .SH HISTORY
94 glibc 2.0
95 .SH SEE ALSO
96 .BR pthread_cancel (3),
97 .BR pthread_cleanup_push (3),
98 .BR pthread_setcancelstate (3),
99 .BR pthread_testcancel (3),
100 .BR pthreads (7)