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 2017-09-15 "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 .TP
  83 .B PTHREAD_CANCEL_ASYNCHRONOUS
  84 The thread can be canceled at any time.
  85 (Typically,
  86 it will be canceled immediately upon receiving a cancellation request,
  87 but the system doesn't guarantee this.)
  88 .PP
  89 The set-and-get operation performed by each of these functions
  90 is atomic with respect to other threads in the process
  91 calling the same function.
  92 .SH RETURN VALUE
  93 On success, these functions return 0;
  94 on error, they return a nonzero error number.
  95 .SH ERRORS
  96 The
  97 .BR pthread_setcancelstate ()
  98 can fail with the following error:
  99 .TP
 100 .B EINVAL
 101 Invalid value for
 102 .IR state .
 103 .PP
 104 The
 105 .BR pthread_setcanceltype ()
 106 can fail with the following error:
 107 .TP
 108 .B EINVAL
 109 Invalid value for
 110 .IR type .
 111 .\" .SH VERSIONS
 112 .\" Available since glibc 2.0
 113 .SH ATTRIBUTES
 114 For an explanation of the terms used in this section, see
 115 .BR attributes (7).
 116 .ad l
 117 .TS
 118 allbox;
 119 lb lb lb
 120 lw25 l l.
 121 Interface       Attribute       Value
 122 T{
 123 .BR pthread_setcancelstate (),
 124 .BR pthread_setcanceltype ()
 125 T}      Thread safety   T{
 126 MT-Safe
 127 T}
 128 T{
 129 .BR pthread_setcancelstate (),
 130 .BR pthread_setcanceltype ()
 131 T}      Async-cancel-safety     T{
 132 AC-Safe
 133 T}
 134 .TE
 135 .ad
 136 .hy
 137 .SH CONFORMING TO
 138 POSIX.1-2001, POSIX.1-2008.
 139 .SH NOTES
 140 For details of what happens when a thread is canceled, see
 141 .BR pthread_cancel (3).
 142 .PP
 143 Briefly disabling cancelability is useful
 144 if a thread performs some critical action
 145 that must not be interrupted by a cancellation request.
 146 Beware of disabling cancelability for long periods,
 147 or around operations that may block for long periods,
 148 since that will render the thread unresponsive to cancellation requests.
 149 .SS Asynchronous cancelability
 150 Setting the cancelability type to
 151 .B PTHREAD_CANCEL_ASYNCHRONOUS
 152 is rarely useful.
 153 Since the thread could be canceled at
 154 .I any
 155 time, it cannot safely reserve resources (e.g., allocating memory with
 156 .BR malloc (3)),
 157 acquire mutexes, semaphores, or locks, and so on.
 158 Reserving resources is unsafe because the application has no way of
 159 knowing what the state of these resources is when the thread is canceled;
 160 that is, did cancellation occur before the resources were reserved,
 161 while they were reserved, or after they were released?
 162 Furthermore, some internal data structures
 163 (e.g., the linked list of free blocks managed by the
 164 .BR malloc (3)
 165 family of functions) may be left in an inconsistent state
 166 if cancellation occurs in the middle of the function call.
 167 Consequently, clean-up handlers cease to be useful.
 168 .PP
 169 Functions that can be safely asynchronously canceled are called
 170 .IR "async-cancel-safe functions" .
 171 POSIX.1-2001 and POSIX.1-2008 require only that
 172 .BR pthread_cancel (3),
 173 .BR pthread_setcancelstate (),
 174 and
 175 .BR pthread_setcanceltype ()
 176 be async-cancel-safe.
 177 In general, other library functions
 178 can't be safely called from an asynchronously cancelable thread.
 179 .PP
 180 One of the few circumstances in which asynchronous cancelability is useful
 181 is for cancellation of a thread that is in a pure compute-bound loop.
 182 .SS Portability notes
 183 The Linux threading implementations permit the
 184 .I oldstate
 185 argument of
 186 .BR pthread_setcancelstate ()
 187 to be NULL, in which case the information about the previous
 188 cancelability state is not returned to the caller.
 189 Many other implementations also permit a NULL
 190 .I oldstat
 191 argument,
 192 .\" It looks like at least Solaris, FreeBSD and Tru64 support this.
 193 but POSIX.1 does not specify this point,
 194 so portable applications should always specify a non-NULL value in
 195 .IR oldstate .
 196 A precisely analogous set of statements applies for the
 197 .I oldtype
 198 argument of
 199 .BR pthread_setcanceltype ().
 200 .SH EXAMPLE
 201 See
 202 .BR pthread_cancel (3).
 203 .SH SEE ALSO
 204 .BR pthread_cancel (3),
 205 .BR pthread_cleanup_push (3),
 206 .BR pthread_testcancel (3),
 207 .BR pthreads (7)