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