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.Ss Cancelability States 73The cancelability state of a thread determines the action taken upon 74receipt of a cancellation request. 75The thread may control cancellation in 76a number of ways. 77.Pp 78Each thread maintains its own 79.Dq cancelability state 80which may be encoded in two bits: 81.Bl -hang 82.It Em Cancelability Enable 83When cancelability is 84.Dv PTHREAD_CANCEL_DISABLE , 85cancellation requests against the target thread are held pending. 86.It Em Cancelability Type 87When cancelability is enabled and the cancelability type is 88.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 89new or pending cancellation requests may be acted upon at any time. 90When cancelability is enabled and the cancelability type is 91.Dv PTHREAD_CANCEL_DEFERRED , 92cancellation requests are held pending until a cancellation point (see 93below) is reached. 94If cancelability is disabled, the setting of the 95cancelability type has no immediate effect as all cancellation requests 96are held pending; however, once cancelability is enabled again the new 97type will be in effect. 98.El 99.Ss Cancellation Points 100Cancellation points will occur when a thread is executing the following 101functions: 102.Bl -tag -width "Fn pthread_cond_timedwait" -compact 103.It Fn accept 104.It Fn accept4 105.It Fn aio_suspend 106.It Fn connect 107.It Fn clock_nanosleep 108.It Fn close 109.It Fn creat 110.It Fn fcntl 111The 112.Fn fcntl 113function is a cancellation point if 114.Fa cmd 115is 116.Dv F_SETLKW . 117.It Fn fdatasync 118.It Fn fsync 119.It Fn kevent 120The 121.Fn kevent 122function is a cancellation point if it is potentially blocking, 123such as when the 124.Fa nevents 125argument 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 172The 173.Fn pthread_setcancelstate 174and 175.Fn pthread_setcanceltype 176functions are used to control the points at which a thread may be 177asynchronously canceled. 178For cancellation control to be usable in modular 179fashion, some rules must be followed. 180.Pp 181For purposes of this discussion, consider an object to be a generalization 182of a procedure. 183It is a set of procedures and global variables written as 184a unit and called by clients not known by the object. 185Objects may depend 186on other objects. 187.Pp 188First, cancelability should only be disabled on entry to an object, never 189explicitly enabled. 190On exit from an object, the cancelability state should 191always be restored to its value on entry to the object. 192.Pp 193This follows from a modularity argument: if the client of an object (or the 194client of an object that uses that object) has disabled cancelability, it is 195because the client does not want to have to worry about how to clean up if the 196thread is canceled while executing some sequence of actions. 197If an object 198is called in such a state and it enables cancelability and a cancellation 199request is pending for that thread, then the thread will be canceled, 200contrary to the wish of the client that disabled. 201.Pp 202Second, the cancelability type may be explicitly set to either 203.Em deferred 204or 205.Em asynchronous 206upon entry to an object. 207But as with the cancelability state, on exit from 208an object that cancelability type should always be restored to its value on 209entry to the object. 210.Pp 211Finally, only functions that are cancel-safe may be called from a thread that 212is asynchronously cancelable. 213.Sh RETURN VALUES 214If successful, the 215.Fn pthread_setcancelstate 216and 217.Fn pthread_setcanceltype 218functions will return zero. 219Otherwise, an error number shall be returned to 220indicate the error. 221.Sh ERRORS 222The function 223.Fn pthread_setcancelstate 224may fail with: 225.Bl -tag -width Er 226.It Bq Er EINVAL 227The specified state is not 228.Dv PTHREAD_CANCEL_ENABLE 229or 230.Dv PTHREAD_CANCEL_DISABLE . 231.El 232.Pp 233The function 234.Fn pthread_setcanceltype 235may fail with: 236.Bl -tag -width Er 237.It Bq Er EINVAL 238The specified state is not 239.Dv PTHREAD_CANCEL_DEFERRED 240or 241.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 242.El 243.Sh SEE ALSO 244.Xr pthread_cancel 3 245.Sh STANDARDS 246The 247.Fn pthread_testcancel 248function conforms to 249.St -p1003.1-96 . 250The standard allows implementations to make many more functions 251cancellation points. 252.Sh AUTHORS 253This manual page was written by 254.An David Leonard Aq Mt d@openbsd.org 255for the 256.Ox 257implementation of 258.Xr pthread_cancel 3 . 259