original/man3/pthread_cancel.3

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