Debian Codegraph @

upstream/debian-unstable/man3/pthread_cancel.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_cancel 3 2025-09-21 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_cancel \- send a cancelation request to a thread
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_cancel(pthread_t " thread );
17 .fi
18 .SH DESCRIPTION
19 The
20 .BR pthread_cancel ()
21 function sends a cancelation request to the thread
22 .IR thread .
23 Whether and when the target thread
24 reacts to the cancelation request depends on
25 two attributes that are under the control of that thread:
26 its cancelability
27 .I state
28 and
29 .IR type .
30 .P
31 A thread's cancelability state, determined by
32 .BR pthread_setcancelstate (3),
33 can be
34 .I enabled
35 (the default for new threads) or
36 .IR disabled .
37 If a thread has disabled cancelation,
38 then a cancelation request remains queued until the thread
39 enables cancelation.
40 If a thread has enabled cancelation,
41 then its cancelability type determines when cancelation occurs.
42 .P
43 A thread's cancelation type, determined by
44 .BR pthread_setcanceltype (3),
45 may be either
46 .I asynchronous
47 or
48 .I deferred
49 (the default for new threads).
50 Asynchronous cancelability
51 means that the thread can be canceled at any time
52 (usually immediately, but the system does not guarantee this).
53 Deferred cancelability means that cancelation will be delayed until
54 the thread next calls a function that is a
55 .IR "cancelation point" .
56 A list of functions that are or may be cancelation points is provided in
57 .BR pthreads (7).
58 .P
59 When a cancelation request is acted on, the following steps occur for
60 .I thread
61 (in this order):
62 .IP (1) 5
63 Cancelation clean-up handlers are popped
64 (in the reverse of the order in which they were pushed) and called.
65 (See
66 .BR pthread_cleanup_push (3).)
67 .IP (2)
68 Thread-specific data destructors are called,
69 in an unspecified order.
70 (See
71 .BR pthread_key_create (3).)
72 .IP (3)
73 The thread is terminated.
74 (See
75 .BR pthread_exit (3).)
76 .P
77 The above steps happen asynchronously with respect to the
78 .BR pthread_cancel ()
79 call;
80 the return status of
81 .BR pthread_cancel ()
82 merely informs the caller whether the cancelation request
83 was successfully queued.
84 .P
85 After a canceled thread has terminated,
86 a join with that thread using
87 .BR pthread_join (3)
88 obtains
89 .B PTHREAD_CANCELED
90 as the thread's exit status.
91 (Joining with a thread is the only way to know that cancelation
92 has completed.)
93 .SH RETURN VALUE
94 On success,
95 .BR pthread_cancel ()
96 returns 0;
97 on error, it returns a nonzero error number.
98 .SH ERRORS
99 .TP
100 .B ESRCH
101 No thread with the ID
102 .I thread
103 could be found.
104 .SH ATTRIBUTES
105 For an explanation of the terms used in this section, see
106 .BR attributes (7).
107 .TS
108 allbox;
109 lbx lb lb
110 l l l.
111 Interface Attribute Value
112 T{
113 .na
114 .nh
115 .BR pthread_cancel ()
116 T} Thread safety MT-Safe
117 .TE
118 .SH VERSIONS
119 On Linux, cancelation is implemented using signals.
120 Under the NPTL threading implementation,
121 the first real-time signal (i.e., signal 32) is used for this purpose.
122 On LinuxThreads, the second real-time signal is used,
123 if real-time signals are available, otherwise
124 .B SIGUSR2
125 is used.
126 .SH STANDARDS
127 POSIX.1-2008.
128 .SH HISTORY
129 glibc 2.0
130 POSIX.1-2001.
131 .SH EXAMPLES
132 The program below creates a thread and then cancels it.
133 The main thread joins with the canceled thread to check
134 that its exit status was
135 .BR PTHREAD_CANCELED .
136 The following shell session shows what happens when we run the program:
137 .P
138 .in +4n
139 .EX
140 $ ./a.out
141 thread_func(): started; cancelation disabled
142 main(): sending cancelation request
143 thread_func(): about to enable cancelation
144 main(): thread was canceled
145 .EE
146 .in
147 .SS Program source
148 \&
149 .\" SRC BEGIN (pthread_cancel.c)
150 .EX
151 #include <err.h>
152 #include <pthread.h>
153 #include <stdio.h>
154 #include <stdlib.h>
155 #include <unistd.h>
156 \&
157 static void *
158 thread_func(void *ignored_argument)
159 {
160 int s;
161 \&
162 /* Disable cancelation for a while, so that we don\[aq]t
163 immediately react to a cancelation request. */
164 \&
165 s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
166 if (s != 0)
167 errc(EXIT_FAILURE, s, "pthread_setcancelstate");
168 \&
169 printf("%s(): started; cancelation disabled\[rs]n", __func__);
170 sleep(5);
171 printf("%s(): about to enable cancelation\[rs]n", __func__);
172 \&
173 s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
174 if (s != 0)
175 errc(EXIT_FAILURE, s, "pthread_setcancelstate");
176 \&
177 /* sleep() is a cancelation point. */
178 \&
179 sleep(1000); /* Should get canceled while we sleep */
180 \&
181 /* Should never get here. */
182 \&
183 printf("%s(): not canceled!\[rs]n", __func__);
184 return NULL;
185 }
186 \&
187 int
188 main(void)
189 {
190 pthread_t thr;
191 void *res;
192 int s;
193 \&
194 /* Start a thread and then send it a cancelation request. */
195 \&
196 s = pthread_create(&thr, NULL, &thread_func, NULL);
197 if (s != 0)
198 errc(EXIT_FAILURE, s, "pthread_create");
199 \&
200 sleep(2); /* Give thread a chance to get started */
201 \&
202 printf("%s(): sending cancelation request\[rs]n", __func__);
203 s = pthread_cancel(thr);
204 if (s != 0)
205 errc(EXIT_FAILURE, s, "pthread_cancel");
206 \&
207 /* Join with thread to see what its exit status was. */
208 \&
209 s = pthread_join(thr, &res);
210 if (s != 0)
211 errc(EXIT_FAILURE, s, "pthread_join");
212 \&
213 if (res == PTHREAD_CANCELED)
214 printf("%s(): thread was canceled\[rs]n", __func__);
215 else
216 printf("%s(): thread wasn\[aq]t canceled (shouldn\[aq]t happen!)\[rs]n",
217 __func__);
218 exit(EXIT_SUCCESS);
219 }
220 .EE
221 .\" SRC END
222 .SH SEE ALSO
223 .ad l
224 .nh
225 .BR pthread_cleanup_push (3),
226 .BR pthread_create (3),
227 .BR pthread_exit (3),
228 .BR pthread_join (3),
229 .BR pthread_key_create (3),
230 .BR pthread_setcancelstate (3),
231 .BR pthread_setcanceltype (3),
232 .BR pthread_testcancel (3),
233 .BR pthreads (7)