man3/pthread_setcancelstate.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREAD_SETCANCELSTATE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 pthread_setcancelstate, pthread_setcanceltype \-
  29 set cancelability state and type
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <pthread.h>
  33 .PP
  34 .BI "int pthread_setcancelstate(int " state ", int *" oldstate );
  35 .BI "int pthread_setcanceltype(int " type ", int *" oldtype );
  36 .PP
  37 Compile and link with \fI\-pthread\fP.
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR pthread_setcancelstate ()
  42 sets the cancelability state of the calling thread to the value
  43 given in
  44 .IR state .
  45 The previous cancelability state of the thread is returned
  46 in the buffer pointed to by
  47 .IR oldstate .
  48 The
  49 .I state
  50 argument must have one of the following values:
  51 .TP
  52 .B PTHREAD_CANCEL_ENABLE
  53 The thread is cancelable.
  54 This is the default cancelability state in all new threads,
  55 including the initial thread.
  56 The thread's cancelability type determines when a cancelable thread
  57 will respond to a cancellation request.
  58 .TP
  59 .B PTHREAD_CANCEL_DISABLE
  60 The thread is not cancelable.
  61 If a cancellation request is received,
  62 it is blocked until cancelability is enabled.
  63 .PP
  64 The
  65 .BR pthread_setcanceltype ()
  66 sets the cancelability type of the calling thread to the value
  67 given in
  68 .IR type .
  69 The previous cancelability type of the thread is returned
  70 in the buffer pointed to by
  71 .IR oldtype .
  72 The
  73 .I type
  74 argument must have one of the following values:
  75 .TP
  76 .B PTHREAD_CANCEL_DEFERRED
  77 A cancellation request is deferred until the thread next calls
  78 a function that is a cancellation point (see
  79 .BR pthreads (7)).
  80 This is the default cancelability type in all new threads,
  81 including the initial thread.
  82 .IP
  83 Even with deferred cancellation, a
  84 cancellation point in an asynchronous signal handler may still
  85 be acted upon and the effect is as if it was an asynchronous
  86 cancellation.
  87 .TP
  88 .B PTHREAD_CANCEL_ASYNCHRONOUS
  89 The thread can be canceled at any time.
  90 (Typically,
  91 it will be canceled immediately upon receiving a cancellation request,
  92 but the system doesn't guarantee this.)
  93 .PP
  94 The set-and-get operation performed by each of these functions
  95 is atomic with respect to other threads in the process
  96 calling the same function.
  97 .SH RETURN VALUE
  98 On success, these functions return 0;
  99 on error, they return a nonzero error number.
 100 .SH ERRORS
 101 The
 102 .BR pthread_setcancelstate ()
 103 can fail with the following error:
 104 .TP
 105 .B EINVAL
 106 Invalid value for
 107 .IR state .
 108 .PP
 109 The
 110 .BR pthread_setcanceltype ()
 111 can fail with the following error:
 112 .TP
 113 .B EINVAL
 114 Invalid value for
 115 .IR type .
 116 .\" .SH VERSIONS
 117 .\" Available since glibc 2.0
 118 .SH ATTRIBUTES
 119 For an explanation of the terms used in this section, see
 120 .BR attributes (7).
 121 .ad l
 122 .nh
 123 .TS
 124 allbox;
 125 lbx lb lb
 126 l l l.
 127 Interface       Attribute       Value
 128 T{
 129 .BR pthread_setcancelstate (),
 130 .BR pthread_setcanceltype ()
 131 T}      Thread safety   T{
 132 MT-Safe
 133 T}
 134 T{
 135 .BR pthread_setcancelstate (),
 136 .BR pthread_setcanceltype ()
 137 T}      Async-cancel safety     T{
 138 AC-Safe
 139 T}
 140 .TE
 141 .hy
 142 .ad
 143 .sp 1
 144 .hy
 145 .SH CONFORMING TO
 146 POSIX.1-2001, POSIX.1-2008.
 147 .SH NOTES
 148 For details of what happens when a thread is canceled, see
 149 .BR pthread_cancel (3).
 150 .PP
 151 Briefly disabling cancelability is useful
 152 if a thread performs some critical action
 153 that must not be interrupted by a cancellation request.
 154 Beware of disabling cancelability for long periods,
 155 or around operations that may block for long periods,
 156 since that will render the thread unresponsive to cancellation requests.
 157 .SS Asynchronous cancelability
 158 Setting the cancelability type to
 159 .B PTHREAD_CANCEL_ASYNCHRONOUS
 160 is rarely useful.
 161 Since the thread could be canceled at
 162 .I any
 163 time, it cannot safely reserve resources (e.g., allocating memory with
 164 .BR malloc (3)),
 165 acquire mutexes, semaphores, or locks, and so on.
 166 Reserving resources is unsafe because the application has no way of
 167 knowing what the state of these resources is when the thread is canceled;
 168 that is, did cancellation occur before the resources were reserved,
 169 while they were reserved, or after they were released?
 170 Furthermore, some internal data structures
 171 (e.g., the linked list of free blocks managed by the
 172 .BR malloc (3)
 173 family of functions) may be left in an inconsistent state
 174 if cancellation occurs in the middle of the function call.
 175 Consequently, clean-up handlers cease to be useful.
 176 .PP
 177 Functions that can be safely asynchronously canceled are called
 178 .IR "async-cancel-safe functions" .
 179 POSIX.1-2001 and POSIX.1-2008 require only that
 180 .BR pthread_cancel (3),
 181 .BR pthread_setcancelstate (),
 182 and
 183 .BR pthread_setcanceltype ()
 184 be async-cancel-safe.
 185 In general, other library functions
 186 can't be safely called from an asynchronously cancelable thread.
 187 .PP
 188 One of the few circumstances in which asynchronous cancelability is useful
 189 is for cancellation of a thread that is in a pure compute-bound loop.
 190 .SS Portability notes
 191 The Linux threading implementations permit the
 192 .I oldstate
 193 argument of
 194 .BR pthread_setcancelstate ()
 195 to be NULL, in which case the information about the previous
 196 cancelability state is not returned to the caller.
 197 Many other implementations also permit a NULL
 198 .I oldstat
 199 argument,
 200 .\" It looks like at least Solaris, FreeBSD and Tru64 support this.
 201 but POSIX.1 does not specify this point,
 202 so portable applications should always specify a non-NULL value in
 203 .IR oldstate .
 204 A precisely analogous set of statements applies for the
 205 .I oldtype
 206 argument of
 207 .BR pthread_setcanceltype ().
 208 .SH EXAMPLES
 209 See
 210 .BR pthread_cancel (3).
 211 .SH SEE ALSO
 212 .BR pthread_cancel (3),
 213 .BR pthread_cleanup_push (3),
 214 .BR pthread_testcancel (3),
 215 .BR pthreads (7)