]>
Commit | Line | Data |
---|---|---|
9e528f3d MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
9e528f3d MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
9e528f3d | 25 | .\" |
4b8c67d9 | 26 | .TH PTHREAD_CANCEL 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
9e528f3d MK |
27 | .SH NAME |
28 | pthread_cancel \- send a cancellation request to a thread | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <pthread.h> | |
f90f031e | 32 | .PP |
653c3aed | 33 | .BI "int pthread_cancel(pthread_t " thread ); |
68e4db0a | 34 | .PP |
9e528f3d | 35 | Compile and link with \fI\-pthread\fP. |
6030f2d8 | 36 | .fi |
9e528f3d MK |
37 | .SH DESCRIPTION |
38 | The | |
39 | .BR pthread_cancel () | |
40 | function sends a cancellation request to the thread | |
41 | .IR thread . | |
42 | Whether and when the target thread | |
43 | reacts to the cancellation request depends on | |
44 | two attributes that are under the control of that thread: | |
c6fa0841 MK |
45 | its cancelability |
46 | .I state | |
47 | and | |
48 | .IR type . | |
847e0d88 | 49 | .PP |
9e528f3d MK |
50 | A thread's cancelability state, determined by |
51 | .BR pthread_setcancelstate (3), | |
52 | can be | |
53 | .I enabled | |
653c3aed | 54 | (the default for new threads) or |
9e528f3d MK |
55 | .IR disabled . |
56 | If a thread has disabled cancellation, | |
57 | then a cancellation request remains queued until the thread | |
58 | enables cancellation. | |
59 | If a thread has enabled cancellation, | |
60 | then its cancelability type determines when cancellation occurs. | |
847e0d88 | 61 | .PP |
9e528f3d MK |
62 | A thread's cancellation type, determined by |
63 | .BR pthread_setcanceltype (3), | |
64 | may be either | |
65 | .IR asynchronous | |
66 | or | |
653c3aed MK |
67 | .IR deferred |
68 | (the default for new threads). | |
9e528f3d MK |
69 | Asynchronous cancelability |
70 | means that the thread can be canceled at any time | |
71 | (usually immediately, but the system does not guarantee this). | |
72 | Deferred cancelability means that cancellation will be delayed until | |
73 | the thread next calls a function that is a | |
74 | .IR "cancellation point" . | |
75 | A list of functions that are or may be cancellation points is provided in | |
d067764a | 76 | .BR pthreads (7). |
847e0d88 | 77 | .PP |
9e528f3d MK |
78 | When a cancellation requested is acted on, the following steps occur for |
79 | .IR thread | |
80 | (in this order): | |
81 | .IP 1. 3 | |
82 | Cancellation clean-up handlers are popped | |
83 | (in the reverse of the order in which they were pushed) and called. | |
84 | (See | |
85 | .BR pthread_cleanup_push (3).) | |
86 | .IP 2. | |
87 | Thread-specific data destructors are called, | |
88 | in an unspecified order. | |
89 | (See | |
90 | .BR pthread_key_create (3).) | |
91 | .IP 3. | |
92 | The thread is terminated. | |
93 | (See | |
94 | .BR pthread_exit (3).) | |
95 | .PP | |
96 | The above steps happen asynchronously with respect to the | |
97 | .BR pthread_cancel () | |
98 | call; | |
99 | the return status of | |
100 | .BR pthread_cancel () | |
101 | merely informs the caller whether the cancellation request | |
102 | was successfully queued. | |
103 | .PP | |
104 | After a canceled thread has terminated, | |
105 | a join with that thread using | |
106 | .BR pthread_join (3) | |
107 | obtains | |
108 | .B PTHREAD_CANCELED | |
109 | as the thread's exit status. | |
653c3aed MK |
110 | (Joining with a thread is the only way to know that cancellation |
111 | has completed.) | |
9e528f3d | 112 | .SH RETURN VALUE |
a113945f | 113 | On success, |
9e528f3d MK |
114 | .BR pthread_cancel () |
115 | returns 0; | |
c7094399 | 116 | on error, it returns a nonzero error number. |
9e528f3d MK |
117 | .SH ERRORS |
118 | .TP | |
119 | .B ESRCH | |
48718eb3 MK |
120 | No thread with the ID |
121 | .I thread | |
122 | could be found. | |
9e528f3d MK |
123 | .\" .SH VERSIONS |
124 | .\" Available since glibc 2.0 | |
ed6d44f8 ZL |
125 | .SH ATTRIBUTES |
126 | For an explanation of the terms used in this section, see | |
127 | .BR attributes (7). | |
128 | .TS | |
129 | allbox; | |
130 | lb lb lb | |
131 | l l l. | |
132 | Interface Attribute Value | |
133 | T{ | |
134 | .BR pthread_cancel () | |
135 | T} Thread safety MT-Safe | |
136 | .TE | |
847e0d88 | 137 | .sp 1 |
9e528f3d | 138 | .SH CONFORMING TO |
aa21680a | 139 | POSIX.1-2001, POSIX.1-2008. |
9e528f3d MK |
140 | .SH NOTES |
141 | On Linux, cancellation is implemented using signals. | |
142 | Under the NPTL threading implementation, | |
143 | the first real-time signal (i.e., signal 32) is used for this purpose. | |
144 | On LinuxThreads, the second real-time signal is used, | |
145 | if real-time signals are available, otherwise | |
146 | .B SIGUSR2 | |
147 | is used. | |
148 | .SH EXAMPLE | |
149 | The program below creates a thread and then cancels it. | |
150 | The main thread joins with the canceled thread to check | |
151 | that its exit status was | |
152 | .BR PTHREAD_CANCELED . | |
153 | The following shell session shows what happens when we run the program: | |
847e0d88 | 154 | .PP |
9e528f3d | 155 | .in +4n |
b8302363 | 156 | .EX |
9e528f3d MK |
157 | $ ./a.out |
158 | thread_func(): started; cancellation disabled | |
159 | main(): sending cancellation request | |
160 | thread_func(): about to enable cancellation | |
161 | main(): thread was canceled | |
b8302363 | 162 | .EE |
9e528f3d MK |
163 | .in |
164 | .SS Program source | |
165 | \& | |
e7d0bb47 | 166 | .EX |
9e528f3d MK |
167 | #include <pthread.h> |
168 | #include <stdio.h> | |
169 | #include <errno.h> | |
170 | #include <stdlib.h> | |
171 | #include <unistd.h> | |
172 | ||
173 | #define handle_error_en(en, msg) \\ | |
174 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) | |
175 | ||
176 | static void * | |
177 | thread_func(void *ignored_argument) | |
178 | { | |
179 | int s; | |
180 | ||
181 | /* Disable cancellation for a while, so that we don\(aqt | |
182 | immediately react to a cancellation request */ | |
183 | ||
184 | s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); | |
185 | if (s != 0) | |
186 | handle_error_en(s, "pthread_setcancelstate"); | |
187 | ||
188 | printf("thread_func(): started; cancellation disabled\\n"); | |
189 | sleep(5); | |
190 | printf("thread_func(): about to enable cancellation\\n"); | |
191 | ||
192 | s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); | |
193 | if (s != 0) | |
194 | handle_error_en(s, "pthread_setcancelstate"); | |
195 | ||
196 | /* sleep() is a cancellation point */ | |
197 | ||
198 | sleep(1000); /* Should get canceled while we sleep */ | |
199 | ||
200 | /* Should never get here */ | |
201 | ||
202 | printf("thread_func(): not canceled!\\n"); | |
203 | return NULL; | |
204 | } | |
205 | ||
206 | int | |
207 | main(void) | |
208 | { | |
209 | pthread_t thr; | |
210 | void *res; | |
211 | int s; | |
212 | ||
213 | /* Start a thread and then send it a cancellation request */ | |
214 | ||
215 | s = pthread_create(&thr, NULL, &thread_func, NULL); | |
216 | if (s != 0) | |
217 | handle_error_en(s, "pthread_create"); | |
218 | ||
219 | sleep(2); /* Give thread a chance to get started */ | |
220 | ||
221 | printf("main(): sending cancellation request\\n"); | |
222 | s = pthread_cancel(thr); | |
223 | if (s != 0) | |
224 | handle_error_en(s, "pthread_cancel"); | |
225 | ||
226 | /* Join with thread to see what its exit status was */ | |
227 | ||
228 | s = pthread_join(thr, &res); | |
229 | if (s != 0) | |
230 | handle_error_en(s, "pthread_join"); | |
231 | ||
232 | if (res == PTHREAD_CANCELED) | |
233 | printf("main(): thread was canceled\\n"); | |
234 | else | |
235 | printf("main(): thread wasn\(aqt canceled (shouldn\(aqt happen!)\\n"); | |
236 | exit(EXIT_SUCCESS); | |
237 | } | |
e7d0bb47 | 238 | .EE |
9e528f3d | 239 | .SH SEE ALSO |
ca8a0bd2 MK |
240 | .ad l |
241 | .nh | |
9e528f3d MK |
242 | .BR pthread_cleanup_push (3), |
243 | .BR pthread_create (3), | |
244 | .BR pthread_exit (3), | |
245 | .BR pthread_join (3), | |
246 | .BR pthread_key_create (3), | |
247 | .BR pthread_setcancelstate (3), | |
248 | .BR pthread_setcanceltype (3), | |
249 | .BR pthread_testcancel (3), | |
250 | .BR pthreads (7) |