man/pthread_setcancelstate.3

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