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 non-zero
60 error number.
61
63 ESRCH No thread with the ID thread could be found.
64
66 POSIX.1-2001.
67
69 On Linux, cancellation is implemented using signals. Under the NPTL
70 threading implementation, the first real-time signal (i.e., signal 32)
71 is used for this purpose. On LinuxThreads, the second real-time signal
72 is used, if real-time signals are available, otherwise SIGUSR2 is used.
73
75 The program below creates a thread and then cancels it. The main
76 thread joins with the canceled thread to check that its exit status was
77 PTHREAD_CANCELED. The following shell session shows what happens when
78 we run the program:
79 $ ./a.out
81 thread_func(): started; cancellation disabled
82 main(): sending cancellation request
83 thread_func(): about to enable cancellation
84 main(): thread was canceled
85 Program source
87 #include <pthread.h>
89 #include <stdio.h>
90 #include <errno.h>
91 #include <stdlib.h>
92 #include <unistd.h>
93 #define handle_error_en(en, msg) \
95 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
96 static void *
98 thread_func(void *ignored_argument)
99 {
100 int s;
101 /* Disable cancellation for a while, so that we don't
103 immediately react to a cancellation request */
104 s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
106 if (s != 0)
107 handle_error_en(s, "pthread_setcancelstate");
108 printf("thread_func(): started; cancellation disabled\n");
110 sleep(5);
111 printf("thread_func(): about to enable cancellation\n");
112 s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
114 if (s != 0)
115 handle_error_en(s, "pthread_setcancelstate");
116 /* sleep() is a cancellation point */
118 sleep(1000); /* Should get canceled while we sleep */
120 /* Should never get here */
122 printf("thread_func(): not canceled!\n");
124 return NULL;
125 }
126 int
128 main(void)
129 {
130 pthread_t thr;
131 void *res;
132 int s;
133 /* Start a thread and then send it a cancellation request */
135 s = pthread_create(&thr, NULL, &thread_func, NULL);
137 if (s != 0)
138 handle_error_en(s, "pthread_create");
139 sleep(2); /* Give thread a chance to get started */
141 printf("main(): sending cancellation request\n");
143 s = pthread_cancel(thr);
144 if (s != 0)
145 handle_error_en(s, "pthread_cancel");
146 /* Join with thread to see what its exit status was */
148 s = pthread_join(thr, &res);
150 if (s != 0)
151 handle_error_en(s, "pthread_join");
152 if (res == PTHREAD_CANCELED)
154 printf("main(): thread was canceled\n");
155 else
156 printf("main(): thread wasn't canceled (shouldn't happen!)\n");
157 exit(EXIT_SUCCESS);
158 }
159
161 pthread_cleanup_push(3), pthread_create(3), pthread_exit(3),
162 pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3),
163 pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)
164
166 This page is part of release 3.22 of the Linux man-pages project. A
167 description of the project, and information about reporting bugs, can
168 be found at http://www.kernel.org/doc/man-pages/.
169Linux 2008-11-17 PTHREAD_CANCEL(3)