share/man/man3/pthread_testcancel.3

   1 .\" $FreeBSD$
   2 .Dd March 18, 2017
   3 .Dt PTHREAD_TESTCANCEL 3
   4 .Os
   5 .Sh NAME
   6 .Nm pthread_setcancelstate ,
   7 .Nm pthread_setcanceltype ,
   8 .Nm pthread_testcancel
   9 .Nd set cancelability state
  10 .Sh LIBRARY
  11 .Lb libpthread
  12 .Sh SYNOPSIS
  13 .In pthread.h
  14 .Ft int
  15 .Fn pthread_setcancelstate "int state" "int *oldstate"
  16 .Ft int
  17 .Fn pthread_setcanceltype "int type" "int *oldtype"
  18 .Ft void
  19 .Fn pthread_testcancel "void"
  20 .Sh DESCRIPTION
  21 The
  22 .Fn pthread_setcancelstate
  23 function atomically both sets the calling thread's cancelability state
  24 to the indicated
  25 .Fa state
  26 and, if
  27 .Fa oldstate
  28 is not
  29 .Dv NULL ,
  30 returns the previous cancelability state at the location referenced by
  31 .Fa oldstate .
  32 Legal values for
  33 .Fa state
  34 are
  35 .Dv PTHREAD_CANCEL_ENABLE
  36 and
  37 .Dv PTHREAD_CANCEL_DISABLE .
  38 .Pp
  39 The
  40 .Fn pthread_setcanceltype
  41 function atomically both sets the calling thread's cancelability type
  42 to the indicated
  43 .Fa type
  44 and, if
  45 .Fa oldtype
  46 is not
  47 .Dv NULL ,
  48 returns the previous cancelability type at the location referenced by
  49 .Fa oldtype .
  50 Legal values for
  51 .Fa type
  52 are
  53 .Dv PTHREAD_CANCEL_DEFERRED
  54 and
  55 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
  56 .Pp
  57 The cancelability state and type of any newly created threads, including the
  58 thread in which
  59 .Fn main
  60 was first invoked, are
  61 .Dv PTHREAD_CANCEL_ENABLE
  62 and
  63 .Dv PTHREAD_CANCEL_DEFERRED
  64 respectively.
  65 .Pp
  66 The
  67 .Fn pthread_testcancel
  68 function creates a cancellation point in the calling thread.
  69 The
  70 .Fn pthread_testcancel
  71 function has no effect if cancelability is disabled.
  72 .Pp
  73 .Ss Cancelability States
  74 The cancelability state of a thread determines the action taken upon
  75 receipt of a cancellation request.
  76 The thread may control cancellation in
  77 a number of ways.
  78 .Pp
  79 Each thread maintains its own
  80 .Dq cancelability state
  81 which may be encoded in two bits:
  82 .Bl -hang
  83 .It Em Cancelability Enable
  84 When cancelability is
  85 .Dv PTHREAD_CANCEL_DISABLE ,
  86 cancellation requests against the target thread are held pending.
  87 .It Em Cancelability Type
  88 When cancelability is enabled and the cancelability type is
  89 .Dv PTHREAD_CANCEL_ASYNCHRONOUS ,
  90 new or pending cancellation requests may be acted upon at any time.
  91 When cancelability is enabled and the cancelability type is
  92 .Dv PTHREAD_CANCEL_DEFERRED ,
  93 cancellation requests are held pending until a cancellation point (see
  94 below) is reached.
  95 If cancelability is disabled, the setting of the
  96 cancelability type has no immediate effect as all cancellation requests
  97 are held pending; however, once cancelability is enabled again the new
  98 type will be in effect.
  99 .El
 100 .Ss Cancellation Points
 101 Cancellation points will occur when a thread is executing the following
 102 functions:
 103 .Bl -tag -width "Fn pthread_cond_timedwait" -compact
 104 .It Fn accept
 105 .It Fn accept4
 106 .It Fn aio_suspend
 107 .It Fn connect
 108 .It Fn clock_nanosleep
 109 .It Fn close
 110 .It Fn creat
 111 .It Fn fcntl
 112 The
 113 .Fn fcntl
 114 function is a cancellation point if
 115 .Fa cmd
 116 is
 117 .Dv F_SETLKW .
 118 .It Fn fdatasync
 119 .It Fn fsync
 120 .It Fn kevent
 121 The
 122 .Fn kevent
 123 function is a cancellation point if it is potentially blocking,
 124 such as when the
 125 .Fa nevents
 126 argument is non-zero.
 127 .It Fn mq_receive
 128 .It Fn mq_send
 129 .It Fn mq_timedreceive
 130 .It Fn mq_timedsend
 131 .It Fn msync
 132 .It Fn nanosleep
 133 .It Fn open
 134 .It Fn openat
 135 .It Fn pause
 136 .It Fn poll
 137 .It Fn ppoll
 138 .It Fn pselect
 139 .It Fn pthread_cond_timedwait
 140 .It Fn pthread_cond_wait
 141 .It Fn pthread_join
 142 .It Fn pthread_testcancel
 143 .It Fn read
 144 .It Fn readv
 145 .It Fn recv
 146 .It Fn recvfrom
 147 .It Fn recvmsg
 148 .It Fn select
 149 .It Fn sem_timedwait
 150 .It Fn sem_clockwait_np
 151 .It Fn sem_wait
 152 .It Fn send
 153 .It Fn sendmsg
 154 .It Fn sendto
 155 .It Fn sigsuspend
 156 .It Fn sigtimedwait
 157 .It Fn sigwaitinfo
 158 .It Fn sigwait
 159 .It Fn sleep
 160 .It Fn system
 161 .It Fn tcdrain
 162 .It Fn usleep
 163 .It Fn wait
 164 .It Fn wait3
 165 .It Fn wait4
 166 .It Fn wait6
 167 .It Fn waitid
 168 .It Fn waitpid
 169 .It Fn write
 170 .It Fn writev
 171 .El
 172 .Sh NOTES
 173 The
 174 .Fn pthread_setcancelstate
 175 and
 176 .Fn pthread_setcanceltype
 177 functions are used to control the points at which a thread may be
 178 asynchronously canceled.
 179 For cancellation control to be usable in modular
 180 fashion, some rules must be followed.
 181 .Pp
 182 For purposes of this discussion, consider an object to be a generalization
 183 of a procedure.
 184 It is a set of procedures and global variables written as
 185 a unit and called by clients not known by the object.
 186 Objects may depend
 187 on other objects.
 188 .Pp
 189 First, cancelability should only be disabled on entry to an object, never
 190 explicitly enabled.
 191 On exit from an object, the cancelability state should
 192 always be restored to its value on entry to the object.
 193 .Pp
 194 This follows from a modularity argument: if the client of an object (or the
 195 client of an object that uses that object) has disabled cancelability, it is
 196 because the client does not want to have to worry about how to clean up if the
 197 thread is canceled while executing some sequence of actions.
 198 If an object
 199 is called in such a state and it enables cancelability and a cancellation
 200 request is pending for that thread, then the thread will be canceled,
 201 contrary to the wish of the client that disabled.
 202 .Pp
 203 Second, the cancelability type may be explicitly set to either
 204 .Em deferred
 205 or
 206 .Em asynchronous
 207 upon entry to an object.
 208 But as with the cancelability state, on exit from
 209 an object that cancelability type should always be restored to its value on
 210 entry to the object.
 211 .Pp
 212 Finally, only functions that are cancel-safe may be called from a thread that
 213 is asynchronously cancelable.
 214 .Sh RETURN VALUES
 215 If successful, the
 216 .Fn pthread_setcancelstate
 217 and
 218 .Fn pthread_setcanceltype
 219 functions will return zero.
 220 Otherwise, an error number shall be returned to
 221 indicate the error.
 222 .Sh ERRORS
 223 The function
 224 .Fn pthread_setcancelstate
 225 may fail with:
 226 .Bl -tag -width Er
 227 .It Bq Er EINVAL
 228 The specified state is not
 229 .Dv PTHREAD_CANCEL_ENABLE
 230 or
 231 .Dv PTHREAD_CANCEL_DISABLE .
 232 .El
 233 .Pp
 234 The function
 235 .Fn pthread_setcanceltype
 236 may fail with:
 237 .Bl -tag -width Er
 238 .It Bq Er EINVAL
 239 The specified state is not
 240 .Dv PTHREAD_CANCEL_DEFERRED
 241 or
 242 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
 243 .El
 244 .Sh SEE ALSO
 245 .Xr pthread_cancel 3
 246 .Sh STANDARDS
 247 The
 248 .Fn pthread_testcancel
 249 function conforms to
 250 .St -p1003.1-96 .
 251 The standard allows implementations to make many more functions
 252 cancellation points.
 253 .Sh AUTHORS
 254 This manual page was written by
 255 .An David Leonard Aq Mt d@openbsd.org
 256 for the
 257 .Ox
 258 implementation of
 259 .Xr pthread_cancel 3 .