]>
Commit | Line | Data |
---|---|---|
9e528f3d MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
9e528f3d | 5 | .\" |
45186a5d | 6 | .TH PTHREAD_CANCEL 3 2021-03-22 "Linux man-pages (unreleased)" |
9e528f3d | 7 | .SH NAME |
1f08fc80 | 8 | pthread_cancel \- send a cancelation request to a thread |
5c0145d5 AC |
9 | .SH LIBRARY |
10 | POSIX threads library | |
8fc3b2cf | 11 | .RI ( libpthread ", " \-lpthread ) |
9e528f3d MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .B #include <pthread.h> | |
f90f031e | 15 | .PP |
653c3aed | 16 | .BI "int pthread_cancel(pthread_t " thread ); |
6030f2d8 | 17 | .fi |
9e528f3d MK |
18 | .SH DESCRIPTION |
19 | The | |
20 | .BR pthread_cancel () | |
1f08fc80 | 21 | function sends a cancelation request to the thread |
9e528f3d MK |
22 | .IR thread . |
23 | Whether and when the target thread | |
1f08fc80 | 24 | reacts to the cancelation request depends on |
9e528f3d | 25 | two attributes that are under the control of that thread: |
c6fa0841 MK |
26 | its cancelability |
27 | .I state | |
28 | and | |
29 | .IR type . | |
847e0d88 | 30 | .PP |
9e528f3d MK |
31 | A thread's cancelability state, determined by |
32 | .BR pthread_setcancelstate (3), | |
33 | can be | |
34 | .I enabled | |
653c3aed | 35 | (the default for new threads) or |
9e528f3d | 36 | .IR disabled . |
1f08fc80 SN |
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. | |
847e0d88 | 42 | .PP |
1f08fc80 | 43 | A thread's cancelation type, determined by |
9e528f3d MK |
44 | .BR pthread_setcanceltype (3), |
45 | may be either | |
1ae6b2c7 | 46 | .I asynchronous |
9e528f3d | 47 | or |
1ae6b2c7 | 48 | .I deferred |
653c3aed | 49 | (the default for new threads). |
9e528f3d MK |
50 | Asynchronous cancelability |
51 | means that the thread can be canceled at any time | |
52 | (usually immediately, but the system does not guarantee this). | |
1f08fc80 | 53 | Deferred cancelability means that cancelation will be delayed until |
9e528f3d | 54 | the thread next calls a function that is a |
1f08fc80 SN |
55 | .IR "cancelation point" . |
56 | A list of functions that are or may be cancelation points is provided in | |
d067764a | 57 | .BR pthreads (7). |
847e0d88 | 58 | .PP |
1f08fc80 | 59 | When a cancelation requested is acted on, the following steps occur for |
1ae6b2c7 | 60 | .I thread |
9e528f3d MK |
61 | (in this order): |
62 | .IP 1. 3 | |
63 | Cancellation 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 | .PP | |
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 () | |
1f08fc80 | 82 | merely informs the caller whether the cancelation request |
9e528f3d MK |
83 | was successfully queued. |
84 | .PP | |
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. | |
1f08fc80 | 91 | (Joining with a thread is the only way to know that cancelation |
653c3aed | 92 | has completed.) |
9e528f3d | 93 | .SH RETURN VALUE |
a113945f | 94 | On success, |
9e528f3d MK |
95 | .BR pthread_cancel () |
96 | returns 0; | |
c7094399 | 97 | on error, it returns a nonzero error number. |
9e528f3d MK |
98 | .SH ERRORS |
99 | .TP | |
100 | .B ESRCH | |
48718eb3 MK |
101 | No thread with the ID |
102 | .I thread | |
103 | could be found. | |
9e528f3d MK |
104 | .\" .SH VERSIONS |
105 | .\" Available since glibc 2.0 | |
ed6d44f8 ZL |
106 | .SH ATTRIBUTES |
107 | For an explanation of the terms used in this section, see | |
108 | .BR attributes (7). | |
c466875e MK |
109 | .ad l |
110 | .nh | |
ed6d44f8 ZL |
111 | .TS |
112 | allbox; | |
c466875e | 113 | lbx lb lb |
ed6d44f8 ZL |
114 | l l l. |
115 | Interface Attribute Value | |
116 | T{ | |
117 | .BR pthread_cancel () | |
118 | T} Thread safety MT-Safe | |
119 | .TE | |
c466875e MK |
120 | .hy |
121 | .ad | |
847e0d88 | 122 | .sp 1 |
3113c7f3 | 123 | .SH STANDARDS |
aa21680a | 124 | POSIX.1-2001, POSIX.1-2008. |
9e528f3d | 125 | .SH NOTES |
1f08fc80 | 126 | On Linux, cancelation is implemented using signals. |
9e528f3d MK |
127 | Under the NPTL threading implementation, |
128 | the first real-time signal (i.e., signal 32) is used for this purpose. | |
129 | On LinuxThreads, the second real-time signal is used, | |
130 | if real-time signals are available, otherwise | |
131 | .B SIGUSR2 | |
132 | is used. | |
a14af333 | 133 | .SH EXAMPLES |
9e528f3d MK |
134 | The program below creates a thread and then cancels it. |
135 | The main thread joins with the canceled thread to check | |
136 | that its exit status was | |
137 | .BR PTHREAD_CANCELED . | |
138 | The following shell session shows what happens when we run the program: | |
847e0d88 | 139 | .PP |
9e528f3d | 140 | .in +4n |
b8302363 | 141 | .EX |
9e528f3d | 142 | $ ./a.out |
1f08fc80 SN |
143 | thread_func(): started; cancelation disabled |
144 | main(): sending cancelation request | |
145 | thread_func(): about to enable cancelation | |
9e528f3d | 146 | main(): thread was canceled |
b8302363 | 147 | .EE |
9e528f3d MK |
148 | .in |
149 | .SS Program source | |
150 | \& | |
e7d0bb47 | 151 | .EX |
9e528f3d MK |
152 | #include <pthread.h> |
153 | #include <stdio.h> | |
154 | #include <errno.h> | |
155 | #include <stdlib.h> | |
156 | #include <unistd.h> | |
157 | ||
d1a71985 | 158 | #define handle_error_en(en, msg) \e |
9e528f3d MK |
159 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) |
160 | ||
161 | static void * | |
162 | thread_func(void *ignored_argument) | |
163 | { | |
164 | int s; | |
165 | ||
1f08fc80 SN |
166 | /* Disable cancelation for a while, so that we don\(aqt |
167 | immediately react to a cancelation request. */ | |
9e528f3d MK |
168 | |
169 | s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); | |
170 | if (s != 0) | |
171 | handle_error_en(s, "pthread_setcancelstate"); | |
172 | ||
1f08fc80 | 173 | printf("thread_func(): started; cancelation disabled\en"); |
9e528f3d | 174 | sleep(5); |
1f08fc80 | 175 | printf("thread_func(): about to enable cancelation\en"); |
9e528f3d MK |
176 | |
177 | s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); | |
178 | if (s != 0) | |
179 | handle_error_en(s, "pthread_setcancelstate"); | |
180 | ||
1f08fc80 | 181 | /* sleep() is a cancelation point. */ |
9e528f3d MK |
182 | |
183 | sleep(1000); /* Should get canceled while we sleep */ | |
184 | ||
46b20ca1 | 185 | /* Should never get here. */ |
9e528f3d | 186 | |
d1a71985 | 187 | printf("thread_func(): not canceled!\en"); |
9e528f3d MK |
188 | return NULL; |
189 | } | |
190 | ||
191 | int | |
192 | main(void) | |
193 | { | |
194 | pthread_t thr; | |
195 | void *res; | |
196 | int s; | |
197 | ||
1f08fc80 | 198 | /* Start a thread and then send it a cancelation request. */ |
9e528f3d MK |
199 | |
200 | s = pthread_create(&thr, NULL, &thread_func, NULL); | |
201 | if (s != 0) | |
202 | handle_error_en(s, "pthread_create"); | |
203 | ||
204 | sleep(2); /* Give thread a chance to get started */ | |
205 | ||
1f08fc80 | 206 | printf("main(): sending cancelation request\en"); |
9e528f3d MK |
207 | s = pthread_cancel(thr); |
208 | if (s != 0) | |
209 | handle_error_en(s, "pthread_cancel"); | |
210 | ||
46b20ca1 | 211 | /* Join with thread to see what its exit status was. */ |
9e528f3d MK |
212 | |
213 | s = pthread_join(thr, &res); | |
214 | if (s != 0) | |
215 | handle_error_en(s, "pthread_join"); | |
216 | ||
217 | if (res == PTHREAD_CANCELED) | |
d1a71985 | 218 | printf("main(): thread was canceled\en"); |
9e528f3d | 219 | else |
d1a71985 | 220 | printf("main(): thread wasn\(aqt canceled (shouldn\(aqt happen!)\en"); |
9e528f3d MK |
221 | exit(EXIT_SUCCESS); |
222 | } | |
e7d0bb47 | 223 | .EE |
9e528f3d | 224 | .SH SEE ALSO |
ca8a0bd2 MK |
225 | .ad l |
226 | .nh | |
9e528f3d MK |
227 | .BR pthread_cleanup_push (3), |
228 | .BR pthread_create (3), | |
229 | .BR pthread_exit (3), | |
230 | .BR pthread_join (3), | |
231 | .BR pthread_key_create (3), | |
232 | .BR pthread_setcancelstate (3), | |
233 | .BR pthread_setcanceltype (3), | |
234 | .BR pthread_testcancel (3), | |
235 | .BR pthreads (7) |