1PTHREAD_CANCEL(3)          Linux Programmer's Manual         PTHREAD_CANCEL(3)
2
3
4

NAME

6       pthread_cancel - send a cancellation request to a thread
7

SYNOPSIS

9       #include <pthread.h>
10
11       int pthread_cancel(pthread_t thread);
12
13       Compile and link with -pthread.
14

DESCRIPTION

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
21       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
28       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
37       When a cancellation requested is acted on, the  following  steps  occur
38       for thread (in this order):
39
40       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
44       2. Thread-specific  data  destructors  are  called,  in  an unspecified
45          order.  (See pthread_key_create(3).)
46
47       3. The thread is terminated.  (See pthread_exit(3).)
48
49       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
53       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

RETURN VALUE

59       On  success, pthread_cancel() returns 0; on error, it returns a nonzero
60       error number.
61

ERRORS

63       ESRCH  No thread with the ID thread could be found.
64

ATTRIBUTES

66       For  an  explanation  of  the  terms  used   in   this   section,   see
67       attributes(7).
68
69       ┌─────────────────┬───────────────┬─────────┐
70Interface        Attribute     Value   
71       ├─────────────────┼───────────────┼─────────┤
72pthread_cancel() │ Thread safety │ MT-Safe │
73       └─────────────────┴───────────────┴─────────┘
74

CONFORMING TO

76       POSIX.1-2001, POSIX.1-2008.
77

NOTES

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

EXAMPLE

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
90           $ ./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
96   Program source
97
98       #include <pthread.h>
99       #include <stdio.h>
100       #include <errno.h>
101       #include <stdlib.h>
102       #include <unistd.h>
103
104       #define handle_error_en(en, msg) \
105               do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
106
107       static void *
108       thread_func(void *ignored_argument)
109       {
110           int s;
111
112           /* Disable cancellation for a while, so that we don't
113              immediately react to a cancellation request */
114
115           s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
116           if (s != 0)
117               handle_error_en(s, "pthread_setcancelstate");
118
119           printf("thread_func(): started; cancellation disabled\n");
120           sleep(5);
121           printf("thread_func(): about to enable cancellation\n");
122
123           s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
124           if (s != 0)
125               handle_error_en(s, "pthread_setcancelstate");
126
127           /* sleep() is a cancellation point */
128
129           sleep(1000);        /* Should get canceled while we sleep */
130
131           /* Should never get here */
132
133           printf("thread_func(): not canceled!\n");
134           return NULL;
135       }
136
137       int
138       main(void)
139       {
140           pthread_t thr;
141           void *res;
142           int s;
143
144           /* Start a thread and then send it a cancellation request */
145
146           s = pthread_create(&thr, NULL, &thread_func, NULL);
147           if (s != 0)
148               handle_error_en(s, "pthread_create");
149
150           sleep(2);           /* Give thread a chance to get started */
151
152           printf("main(): sending cancellation request\n");
153           s = pthread_cancel(thr);
154           if (s != 0)
155               handle_error_en(s, "pthread_cancel");
156
157           /* Join with thread to see what its exit status was */
158
159           s = pthread_join(thr, &res);
160           if (s != 0)
161               handle_error_en(s, "pthread_join");
162
163           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

SEE ALSO

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

COLOPHON

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/.
180
181
182
183Linux                             2017-09-15                 PTHREAD_CANCEL(3)
Impressum