1pthread_cancel(3) Library Functions Manual pthread_cancel(3)
2
6 pthread_cancel - send a cancelation request to a thread
7
9 POSIX threads library (libpthread, -lpthread)
10
12 #include <pthread.h>
13 int pthread_cancel(pthread_t thread);
15
17 The pthread_cancel() function sends a cancelation request to the thread
18 thread. Whether and when the target thread reacts to the cancelation
19 request depends on two attributes that are under the control of that
20 thread: its cancelability state and type.
21 A thread's cancelability state, determined by pthread_setcancel‐
23 state(3), can be enabled (the default for new threads) or disabled. If
24 a thread has disabled cancelation, then a cancelation request remains
25 queued until the thread enables cancelation. If a thread has enabled
26 cancelation, then its cancelability type determines when cancelation
27 occurs.
28 A thread's cancelation type, determined by pthread_setcanceltype(3),
30 may be either asynchronous or deferred (the default for new threads).
31 Asynchronous cancelability means that the thread can be canceled at any
32 time (usually immediately, but the system does not guarantee this).
33 Deferred cancelability means that cancelation will be delayed until the
34 thread next calls a function that is a cancelation point. A list of
35 functions that are or may be cancelation points is provided in
36 pthreads(7).
37 When a cancelation requested is acted on, the following steps occur for
39 thread (in this order):
40 (1) Cancelation clean-up handlers are popped (in the reverse of the
42 order in which they were pushed) and called. (See
43 pthread_cleanup_push(3).)
44 (2) Thread-specific data destructors are called, in an unspecified or‐
46 der. (See pthread_key_create(3).)
47 (3) The thread is terminated. (See pthread_exit(3).)
49 The above steps happen asynchronously with respect to the pthread_can‐
51 cel() call; the return status of pthread_cancel() merely informs the
52 caller whether the cancelation request was successfully queued.
53 After a canceled thread has terminated, a join with that thread using
55 pthread_join(3) obtains PTHREAD_CANCELED as the thread's exit status.
56 (Joining with a thread is the only way to know that cancelation has
57 completed.)
58
60 On success, pthread_cancel() returns 0; on error, it returns a nonzero
61 error number.
62
64 ESRCH No thread with the ID thread could be found.
65
67 For an explanation of the terms used in this section, see at‐
68 tributes(7).
69 ┌────────────────────────────────────────────┬───────────────┬─────────┐
71 │Interface │ Attribute │ Value │
72 ├────────────────────────────────────────────┼───────────────┼─────────┤
73 │pthread_cancel() │ Thread safety │ MT-Safe │
74 └────────────────────────────────────────────┴───────────────┴─────────┘
75
77 On Linux, cancelation is implemented using signals. Under the NPTL
78 threading implementation, the first real-time signal (i.e., signal 32)
79 is used for this purpose. On LinuxThreads, the second real-time signal
80 is used, if real-time signals are available, otherwise SIGUSR2 is used.
81
83 POSIX.1-2008.
84
86 glibc 2.0 POSIX.1-2001.
87
89 The program below creates a thread and then cancels it. The main
90 thread joins with the canceled thread to check that its exit status was
91 PTHREAD_CANCELED. The following shell session shows what happens when
92 we run the program:
93 $ ./a.out
95 thread_func(): started; cancelation disabled
96 main(): sending cancelation request
97 thread_func(): about to enable cancelation
98 main(): thread was canceled
99 Program source
101 #include <errno.h>
103 #include <pthread.h>
104 #include <stdio.h>
105 #include <stdlib.h>
106 #include <unistd.h>
107 #define handle_error_en(en, msg) \
109 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
110 static void *
112 thread_func(void *ignored_argument)
113 {
114 int s;
115 /* Disable cancelation for a while, so that we don't
117 immediately react to a cancelation request. */
118 s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
120 if (s != 0)
121 handle_error_en(s, "pthread_setcancelstate");
122 printf("%s(): started; cancelation disabled\n", __func__);
124 sleep(5);
125 printf("%s(): about to enable cancelation\n", __func__);
126 s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
128 if (s != 0)
129 handle_error_en(s, "pthread_setcancelstate");
130 /* sleep() is a cancelation point. */
132 sleep(1000); /* Should get canceled while we sleep */
134 /* Should never get here. */
136 printf("%s(): not canceled!\n", __func__);
138 return NULL;
139 }
140 int
142 main(void)
143 {
144 pthread_t thr;
145 void *res;
146 int s;
147 /* Start a thread and then send it a cancelation request. */
149 s = pthread_create(&thr, NULL, &thread_func, NULL);
151 if (s != 0)
152 handle_error_en(s, "pthread_create");
153 sleep(2); /* Give thread a chance to get started */
155 printf("%s(): sending cancelation request\n", __func__);
157 s = pthread_cancel(thr);
158 if (s != 0)
159 handle_error_en(s, "pthread_cancel");
160 /* Join with thread to see what its exit status was. */
162 s = pthread_join(thr, &res);
164 if (s != 0)
165 handle_error_en(s, "pthread_join");
166 if (res == PTHREAD_CANCELED)
168 printf("%s(): thread was canceled\n", __func__);
169 else
170 printf("%s(): thread wasn't canceled (shouldn't happen!)\n",
171 __func__);
172 exit(EXIT_SUCCESS);
173 }
174
176 pthread_cleanup_push(3), pthread_create(3), pthread_exit(3),
177 pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3),
178 pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)
179Linux man-pages 6.04 2023-03-30 pthread_cancel(3)