original/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 2014-05-13 "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
  34 .BI "int pthread_setcancelstate(int " state ", int *" oldstate );
  35 .BI "int pthread_setcanceltype(int " type ", int *" oldtype );
  36 .sp
  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 .SS Multithreading (see pthreads(7))
 115 The
 116 .BR pthread_setcancelstate ()
 117 and
 118 .BR pthread_setcanceltype ()
 119 functions are thread-safe.
 120 .SH CONFORMING TO
 121 POSIX.1-2001.
 122 .SH NOTES
 123 For details of what happens when a thread is canceled, see
 124 .BR pthread_cancel (3).
 125
 126 Briefly disabling cancelability is useful
 127 if a thread performs some critical action
 128 that must not be interrupted by a cancellation request.
 129 Beware of disabling cancelability for long periods,
 130 or around operations that may block for long periods,
 131 since that will render the thread unresponsive to cancellation requests.
 132 .SS Asynchronous cancelability
 133 Setting the cancelability type to
 134 .B PTHREAD_CANCEL_ASYNCHRONOUS
 135 is rarely useful.
 136 Since the thread could be canceled at
 137 .I any
 138 time, it cannot safely reserve resources (e.g., allocating memory with
 139 .BR malloc (3)),
 140 acquire mutexes, semaphores, or locks, and so on.
 141 Reserving resources is unsafe because the application has no way of
 142 knowing what the state of these resources is when the thread is canceled;
 143 that is, did cancellation occur before the resources were reserved,
 144 while they were reserved, or after they were released?
 145 Furthermore, some internal data structures
 146 (e.g., the linked list of free blocks managed by the
 147 .BR malloc (3)
 148 family of functions) may be left in an inconsistent state
 149 if cancellation occurs in the middle of the function call.
 150 Consequently, clean-up handlers cease to be useful.
 151
 152 Functions that can be safely asynchronously canceled are called
 153 .IR "async-cancel-safe functions" .
 154 POSIX.1-2001 requires only that
 155 .BR pthread_cancel (3),
 156 .BR pthread_setcancelstate (),
 157 and
 158 .BR pthread_setcanceltype ()
 159 be async-cancel-safe.
 160 In general, other library functions
 161 can't be safely called from an asynchronously cancelable thread.
 162
 163 One of the few circumstances in which asynchronous cancelability is useful
 164 is for cancellation of a thread that is in a pure compute-bound loop.
 165 .SS Portability notes
 166 The Linux threading implementations permit the
 167 .I oldstate
 168 argument of
 169 .BR pthread_setcancelstate ()
 170 to be NULL, in which case the information about the previous
 171 cancelability state is not returned to the caller.
 172 Many other implementations also permit a NULL
 173 .I oldstat
 174 argument,
 175 .\" It looks like at least Solaris, FreeBSD and Tru64 support this.
 176 but POSIX.1-2001 does not specify this point,
 177 so portable applications should always specify a non-NULL value in
 178 .IR oldstate .
 179 A precisely analogous set of statements applies for the
 180 .I oldtype
 181 argument of
 182 .BR pthread_setcanceltype ().
 183 .SH EXAMPLE
 184 See
 185 .BR pthread_cancel (3).
 186 .SH SEE ALSO
 187 .BR pthread_cancel (3),
 188 .BR pthread_cleanup_push (3),
 189 .BR pthread_testcancel (3),
 190 .BR pthreads (7)
 191 .SH COLOPHON
 192 This page is part of release 3.79 of the Linux
 193 .I man-pages
 194 project.
 195 A description of the project,
 196 information about reporting bugs,
 197 and the latest version of this page,
 198 can be found at
 199 \%http://www.kernel.org/doc/man\-pages/.