share/man/man3/pthread_testcancel.3

   1 .\" $FreeBSD$
   2 .Dd February 17, 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 close
 109 .It Fn creat
 110 .It Fn fcntl
 111 The
 112 .Fn fcntl
 113 function is a cancellation point if
 114 .Fa cmd
 115 is
 116 .Dv F_SETLKW .
 117 .It Fn fdatasync
 118 .It Fn fsync
 119 .It Fn kevent
 120 The
 121 .Fn kevent
 122 function is a cancellation point if it is potentially blocking,
 123 such as when the
 124 .Fa nevents
 125 argument is non-zero.
 126 .It Fn mq_receive
 127 .It Fn mq_send
 128 .It Fn mq_timedreceive
 129 .It Fn mq_timedsend
 130 .It Fn msync
 131 .It Fn nanosleep
 132 .It Fn open
 133 .It Fn openat
 134 .It Fn pause
 135 .It Fn poll
 136 .It Fn ppoll
 137 .It Fn pselect
 138 .It Fn pthread_cond_timedwait
 139 .It Fn pthread_cond_wait
 140 .It Fn pthread_join
 141 .It Fn pthread_testcancel
 142 .It Fn read
 143 .It Fn readv
 144 .It Fn recv
 145 .It Fn recvfrom
 146 .It Fn recvmsg
 147 .It Fn select
 148 .It Fn sem_timedwait
 149 .It Fn sem_clockwait_np
 150 .It Fn sem_wait
 151 .It Fn send
 152 .It Fn sendmsg
 153 .It Fn sendto
 154 .It Fn sigsuspend
 155 .It Fn sigtimedwait
 156 .It Fn sigwaitinfo
 157 .It Fn sigwait
 158 .It Fn sleep
 159 .It Fn system
 160 .It Fn tcdrain
 161 .It Fn usleep
 162 .It Fn wait
 163 .It Fn wait3
 164 .It Fn wait4
 165 .It Fn wait6
 166 .It Fn waitid
 167 .It Fn waitpid
 168 .It Fn write
 169 .It Fn writev
 170 .El
 171 .Sh NOTES
 172 The
 173 .Fn pthread_setcancelstate
 174 and
 175 .Fn pthread_setcanceltype
 176 functions are used to control the points at which a thread may be
 177 asynchronously canceled.
 178 For cancellation control to be usable in modular
 179 fashion, some rules must be followed.
 180 .Pp
 181 For purposes of this discussion, consider an object to be a generalization
 182 of a procedure.
 183 It is a set of procedures and global variables written as
 184 a unit and called by clients not known by the object.
 185 Objects may depend
 186 on other objects.
 187 .Pp
 188 First, cancelability should only be disabled on entry to an object, never
 189 explicitly enabled.
 190 On exit from an object, the cancelability state should
 191 always be restored to its value on entry to the object.
 192 .Pp
 193 This follows from a modularity argument: if the client of an object (or the
 194 client of an object that uses that object) has disabled cancelability, it is
 195 because the client does not want to have to worry about how to clean up if the
 196 thread is canceled while executing some sequence of actions.
 197 If an object
 198 is called in such a state and it enables cancelability and a cancellation
 199 request is pending for that thread, then the thread will be canceled,
 200 contrary to the wish of the client that disabled.
 201 .Pp
 202 Second, the cancelability type may be explicitly set to either
 203 .Em deferred
 204 or
 205 .Em asynchronous
 206 upon entry to an object.
 207 But as with the cancelability state, on exit from
 208 an object that cancelability type should always be restored to its value on
 209 entry to the object.
 210 .Pp
 211 Finally, only functions that are cancel-safe may be called from a thread that
 212 is asynchronously cancelable.
 213 .Sh RETURN VALUES
 214 If successful, the
 215 .Fn pthread_setcancelstate
 216 and
 217 .Fn pthread_setcanceltype
 218 functions will return zero.
 219 Otherwise, an error number shall be returned to
 220 indicate the error.
 221 .Sh ERRORS
 222 The function
 223 .Fn pthread_setcancelstate
 224 may fail with:
 225 .Bl -tag -width Er
 226 .It Bq Er EINVAL
 227 The specified state is not
 228 .Dv PTHREAD_CANCEL_ENABLE
 229 or
 230 .Dv PTHREAD_CANCEL_DISABLE .
 231 .El
 232 .Pp
 233 The function
 234 .Fn pthread_setcanceltype
 235 may fail with:
 236 .Bl -tag -width Er
 237 .It Bq Er EINVAL
 238 The specified state is not
 239 .Dv PTHREAD_CANCEL_DEFERRED
 240 or
 241 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
 242 .El
 243 .Sh SEE ALSO
 244 .Xr pthread_cancel 3
 245 .Sh STANDARDS
 246 The
 247 .Fn pthread_testcancel
 248 function conforms to
 249 .St -p1003.1-96 .
 250 The standard allows implementations to make many more functions
 251 cancellation points.
 252 .Sh AUTHORS
 253 This manual page was written by
 254 .An David Leonard Aq Mt d@openbsd.org
 255 for the
 256 .Ox
 257 implementation of
 258 .Xr pthread_cancel 3 .