Debian Codegraph @

upstream/fedora-44/man3/pthread_cleanup_push_defer_np.3

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