1PTHREAD_CANCEL(3) Linux Programmer's Manual PTHREAD_CANCEL(3)
2
6 pthread_cancel - send a cancellation request to a thread
7
9 #include <pthread.h>
10 int pthread_cancel(pthread_t thread);
12 Compile and link with -pthread.
14
16 The pthread_cancel() function sends a cancellation request to the
17 thread thread. Whether and when the target thread reacts to the can‐
18 cellation request depends on two attributes that are under the control
19 of that thread: its cancelability state and type.
20 A thread's cancelability state, determined by pthread_setcancel‐
22 state(3), can be enabled (the default for new threads) or disabled. If
23 a thread has disabled cancellation, then a cancellation request remains
24 queued until the thread enables cancellation. If a thread has enabled
25 cancellation, then its cancelability type determines when cancellation
26 occurs.
27 A thread's cancellation type, determined by pthread_setcanceltype(3),
29 may be either asynchronous or deferred (the default for new threads).
30 Asynchronous cancelability means that the thread can be canceled at any
31 time (usually immediately, but the system does not guarantee this).
32 Deferred cancelability means that cancellation will be delayed until
33 the thread next calls a function that is a cancellation point. A list
34 of functions that are or may be cancellation points is provided in
35 pthreads(7).
36 When a cancellation requested is acted on, the following steps occur
38 for thread (in this order):
39 1. Cancellation clean-up handlers are popped (in the reverse of the
41 order in which they were pushed) and called. (See
42 pthread_cleanup_push(3).)
43 2. Thread-specific data destructors are called, in an unspecified
45 order. (See pthread_key_create(3).)
46 3. The thread is terminated. (See pthread_exit(3).)
48 The above steps happen asynchronously with respect to the pthread_can‐
50 cel() call; the return status of pthread_cancel() merely informs the
51 caller whether the cancellation request was successfully queued.
52 After a canceled thread has terminated, a join with that thread using
54 pthread_join(3) obtains PTHREAD_CANCELED as the thread's exit status.
55 (Joining with a thread is the only way to know that cancellation has
56 completed.)
57
59 On success, pthread_cancel() returns 0; on error, it returns a nonzero
60 error number.
61
63 ESRCH No thread with the ID thread could be found.
64
66 For an explanation of the terms used in this section, see
67 attributes(7).
68 ┌─────────────────┬───────────────┬─────────┐
70 │Interface │ Attribute │ Value │
71 ├─────────────────┼───────────────┼─────────┤
72 │pthread_cancel() │ Thread safety │ MT-Safe │
73 └─────────────────┴───────────────┴─────────┘
74
76 POSIX.1-2001, POSIX.1-2008.
77
79 On Linux, cancellation is implemented using signals. Under the NPTL
80 threading implementation, the first real-time signal (i.e., signal 32)
81 is used for this purpose. On LinuxThreads, the second real-time signal
82 is used, if real-time signals are available, otherwise SIGUSR2 is used.
83
85 The program below creates a thread and then cancels it. The main
86 thread joins with the canceled thread to check that its exit status was
87 PTHREAD_CANCELED. The following shell session shows what happens when
88 we run the program:
89 $ ./a.out
91 thread_func(): started; cancellation disabled
92 main(): sending cancellation request
93 thread_func(): about to enable cancellation
94 main(): thread was canceled
95 Program source
97 #include <pthread.h>
99 #include <stdio.h>
100 #include <errno.h>
101 #include <stdlib.h>
102 #include <unistd.h>
103 #define handle_error_en(en, msg) \
105 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
106 static void *
108 thread_func(void *ignored_argument)
109 {
110 int s;
111 /* Disable cancellation for a while, so that we don't
113 immediately react to a cancellation request */
114 s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
116 if (s != 0)
117 handle_error_en(s, "pthread_setcancelstate");
118 printf("thread_func(): started; cancellation disabled\n");
120 sleep(5);
121 printf("thread_func(): about to enable cancellation\n");
122 s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
124 if (s != 0)
125 handle_error_en(s, "pthread_setcancelstate");
126 /* sleep() is a cancellation point */
128 sleep(1000); /* Should get canceled while we sleep */
130 /* Should never get here */
132 printf("thread_func(): not canceled!\n");
134 return NULL;
135 }
136 int
138 main(void)
139 {
140 pthread_t thr;
141 void *res;
142 int s;
143 /* Start a thread and then send it a cancellation request */
145 s = pthread_create(&thr, NULL, &thread_func, NULL);
147 if (s != 0)
148 handle_error_en(s, "pthread_create");
149 sleep(2); /* Give thread a chance to get started */
151 printf("main(): sending cancellation request\n");
153 s = pthread_cancel(thr);
154 if (s != 0)
155 handle_error_en(s, "pthread_cancel");
156 /* Join with thread to see what its exit status was */
158 s = pthread_join(thr, &res);
160 if (s != 0)
161 handle_error_en(s, "pthread_join");
162 if (res == PTHREAD_CANCELED)
164 printf("main(): thread was canceled\n");
165 else
166 printf("main(): thread wasn't canceled (shouldn't happen!)\n");
167 exit(EXIT_SUCCESS);
168 }
169
171 pthread_cleanup_push(3), pthread_create(3), pthread_exit(3),
172 pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3),
173 pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)
174
176 This page is part of release 4.16 of the Linux man-pages project. A
177 description of the project, information about reporting bugs, and the
178 latest version of this page, can be found at
179 https://www.kernel.org/doc/man-pages/.
180Linux 2017-09-15 PTHREAD_CANCEL(3)