man3/pthread_cancel.3

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