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 21The 22.Fn pthread_setcancelstate 23function atomically both sets the calling thread's cancelability state 24to the indicated 25.Fa state 26and, if 27.Fa oldstate 28is not 29.Dv NULL , 30returns the previous cancelability state at the location referenced by 31.Fa oldstate . 32Legal values for 33.Fa state 34are 35.Dv PTHREAD_CANCEL_ENABLE 36and 37.Dv PTHREAD_CANCEL_DISABLE . 38.Pp 39The 40.Fn pthread_setcanceltype 41function atomically both sets the calling thread's cancelability type 42to the indicated 43.Fa type 44and, if 45.Fa oldtype 46is not 47.Dv NULL , 48returns the previous cancelability type at the location referenced by 49.Fa oldtype . 50Legal values for 51.Fa type 52are 53.Dv PTHREAD_CANCEL_DEFERRED 54and 55.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 56.Pp 57The cancelability state and type of any newly created threads, including the 58thread in which 59.Fn main 60was first invoked, are 61.Dv PTHREAD_CANCEL_ENABLE 62and 63.Dv PTHREAD_CANCEL_DEFERRED 64respectively. 65.Pp 66The 67.Fn pthread_testcancel 68function creates a cancellation point in the calling thread. 69The 70.Fn pthread_testcancel 71function has no effect if cancelability is disabled. 72.Pp 73.Ss Cancelability States 74The cancelability state of a thread determines the action taken upon 75receipt of a cancellation request. 76The thread may control cancellation in 77a number of ways. 78.Pp 79Each thread maintains its own 80.Dq cancelability state 81which may be encoded in two bits: 82.Bl -hang 83.It Em Cancelability Enable 84When cancelability is 85.Dv PTHREAD_CANCEL_DISABLE , 86cancellation requests against the target thread are held pending. 87.It Em Cancelability Type 88When cancelability is enabled and the cancelability type is 89.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 90new or pending cancellation requests may be acted upon at any time. 91When cancelability is enabled and the cancelability type is 92.Dv PTHREAD_CANCEL_DEFERRED , 93cancellation requests are held pending until a cancellation point (see 94below) is reached. 95If cancelability is disabled, the setting of the 96cancelability type has no immediate effect as all cancellation requests 97are held pending; however, once cancelability is enabled again the new 98type will be in effect. 99.El 100.Ss Cancellation Points 101Cancellation points will occur when a thread is executing the following 102functions: 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 112The 113.Fn fcntl 114function is a cancellation point if 115.Fa cmd 116is 117.Dv F_SETLKW . 118.It Fn fdatasync 119.It Fn fsync 120.It Fn kevent 121The 122.Fn kevent 123function is a cancellation point if it is potentially blocking, 124such as when the 125.Fa nevents 126argument 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 173The 174.Fn pthread_setcancelstate 175and 176.Fn pthread_setcanceltype 177functions are used to control the points at which a thread may be 178asynchronously canceled. 179For cancellation control to be usable in modular 180fashion, some rules must be followed. 181.Pp 182For purposes of this discussion, consider an object to be a generalization 183of a procedure. 184It is a set of procedures and global variables written as 185a unit and called by clients not known by the object. 186Objects may depend 187on other objects. 188.Pp 189First, cancelability should only be disabled on entry to an object, never 190explicitly enabled. 191On exit from an object, the cancelability state should 192always be restored to its value on entry to the object. 193.Pp 194This follows from a modularity argument: if the client of an object (or the 195client of an object that uses that object) has disabled cancelability, it is 196because the client does not want to have to worry about how to clean up if the 197thread is canceled while executing some sequence of actions. 198If an object 199is called in such a state and it enables cancelability and a cancellation 200request is pending for that thread, then the thread will be canceled, 201contrary to the wish of the client that disabled. 202.Pp 203Second, the cancelability type may be explicitly set to either 204.Em deferred 205or 206.Em asynchronous 207upon entry to an object. 208But as with the cancelability state, on exit from 209an object that cancelability type should always be restored to its value on 210entry to the object. 211.Pp 212Finally, only functions that are cancel-safe may be called from a thread that 213is asynchronously cancelable. 214.Sh RETURN VALUES 215If successful, the 216.Fn pthread_setcancelstate 217and 218.Fn pthread_setcanceltype 219functions will return zero. 220Otherwise, an error number shall be returned to 221indicate the error. 222.Sh ERRORS 223The function 224.Fn pthread_setcancelstate 225may fail with: 226.Bl -tag -width Er 227.It Bq Er EINVAL 228The specified state is not 229.Dv PTHREAD_CANCEL_ENABLE 230or 231.Dv PTHREAD_CANCEL_DISABLE . 232.El 233.Pp 234The function 235.Fn pthread_setcanceltype 236may fail with: 237.Bl -tag -width Er 238.It Bq Er EINVAL 239The specified state is not 240.Dv PTHREAD_CANCEL_DEFERRED 241or 242.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 243.El 244.Sh SEE ALSO 245.Xr pthread_cancel 3 246.Sh STANDARDS 247The 248.Fn pthread_testcancel 249function conforms to 250.St -p1003.1-96 . 251The standard allows implementations to make many more functions 252cancellation points. 253.Sh AUTHORS 254This manual page was written by 255.An David Leonard Aq Mt d@openbsd.org 256for the 257.Ox 258implementation of 259.Xr pthread_cancel 3 . 260