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