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