1.\" $OpenBSD: pthread_testcancel.3,v 1.17 2022/12/19 03:49:42 guenther Exp $ 2.\" 3.\" 4.\" David Leonard, 1999. Public Domain. 5.\" 6.Dd $Mdocdate: December 19 2022 $ 7.Dt PTHREAD_TESTCANCEL 3 8.Os 9.Sh NAME 10.Nm pthread_setcancelstate , 11.Nm pthread_setcanceltype , 12.Nm pthread_testcancel 13.Nd set cancelability state 14.Sh SYNOPSIS 15.In pthread.h 16.Ft int 17.Fn pthread_setcancelstate "int state" "int *oldstate" 18.Ft int 19.Fn pthread_setcanceltype "int type" "int *oldtype" 20.Ft void 21.Fn pthread_testcancel "void" 22.Sh DESCRIPTION 23The 24.Fn pthread_setcancelstate 25function atomically both sets the calling thread's cancelability state 26to the indicated 27.Fa state 28and, if 29.Fa oldstate 30is not 31.Dv NULL , 32returns the previous cancelability state at the location referenced by 33.Fa oldstate . 34Legal values for 35.Fa state 36are 37.Dv PTHREAD_CANCEL_ENABLE 38and 39.Dv PTHREAD_CANCEL_DISABLE . 40.Pp 41The 42.Fn pthread_setcanceltype 43function atomically both sets the calling thread's cancelability type 44to the indicated 45.Fa type 46and, if 47.Fa oldtype 48is not 49.Dv NULL , 50returns the previous cancelability type at the location referenced by 51.Fa oldtype . 52Legal values for 53.Fa type 54are 55.Dv PTHREAD_CANCEL_DEFERRED 56and 57.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 58.Pp 59The cancelability state and type of any newly created threads, including the 60thread in which 61.Fn main 62was first invoked, are 63.Dv PTHREAD_CANCEL_ENABLE 64and 65.Dv PTHREAD_CANCEL_DEFERRED 66respectively. 67.Pp 68The 69.Fn pthread_testcancel 70function creates a cancellation point in the calling thread. 71The 72.Fn pthread_testcancel 73function has no effect if cancelability is disabled. 74.Ss Cancelability States 75The cancelability state of a thread determines the action taken upon 76receipt of a cancellation request. 77The thread may control cancellation in a 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 102base interfaces: 103.Fn accept , 104.Fn close , 105.Fn connect , 106.Fn creat , 107.Fn fcntl "F_SETLKW" , 108.Fn fdatasync , 109.Fn fsync , 110.Fn lockf , 111.Fn msgrcv , 112.Fn msgsnd , 113.Fn msync , 114.Fn nanosleep , 115.Fn open , 116.Fn openat , 117.Fn pause , 118.Fn poll , 119.Fn pread , 120.Fn pselect , 121.Fn pthread_cond_timedwait , 122.Fn pthread_cond_wait , 123.Fn pthread_join , 124.Fn pthread_testcancel , 125.Fn pwrite , 126.Fn read , 127.Fn readv , 128.Fn recv , 129.Fn recvfrom , 130.Fn recvmsg , 131.Fn select , 132.Fn sem_timedwait , 133.Fn sem_wait , 134.Fn send , 135.Fn sendmsg , 136.Fn sendto , 137.Fn sigsuspend , 138.Fn sigwait , 139.Fn sleep , 140.Fn system , 141.Fn tcdrain , 142.Fn wait , 143.Fn waitid , 144.Fn waitpid , 145.Fn write , 146.Fn writev . 147.Pp 148In addition, 149cancellation points will occur when a thread is executing the following 150extension interfaces: 151.Fn accept4 , 152.Fn closefrom , 153.Fn ppoll , 154.Fn preadv , 155.Fn pwritev , 156.Fn recvmmsg , 157.Fn sendmmsg , 158.Fn wait3 , 159.Fn wait4 . 160.Sh RETURN VALUES 161If successful, the 162.Fn pthread_setcancelstate 163and 164.Fn pthread_setcanceltype 165functions will return zero. 166Otherwise, an error number shall be returned to indicate the error. 167.Pp 168The 169.Fn pthread_setcancelstate 170and 171.Fn pthread_setcanceltype 172functions are used to control the points at which a thread may be 173asynchronously cancelled. 174For cancellation control to be usable in modular 175fashion, some rules must be followed. 176.Pp 177For purposes of this discussion, consider an object to be a generalization 178of a procedure. 179It is a set of procedures and global variables written as 180a unit and called by clients not known by the object. 181Objects may depend on other objects. 182.Pp 183First, cancelability should only be disabled on entry to an object, never 184explicitly enabled. 185On exit from an object, the cancelability state should 186always be restored to its value on entry to the object. 187.Pp 188This follows from a modularity argument: if the client of an object (or the 189client of an object that uses that object) has disabled cancelability, it is 190because the client doesn't want to have to worry about how to clean up if the 191thread is cancelled while executing some sequence of actions. 192If an object 193is called in such a state and it enables cancelability and a cancellation 194request is pending for that thread, then the thread will be cancelled, 195contrary to the wish of the client that disabled. 196.Pp 197Second, the cancelability type may be explicitly set to either 198.Em deferred 199or 200.Em asynchronous 201upon entry to an object. 202But as with the cancelability state, on exit from 203an object that cancelability type should always be restored to its value on 204entry to the object. 205.Pp 206Finally, only functions that are cancel-safe may be called from a thread that 207is asynchronously cancelable. 208.Sh ERRORS 209The function 210.Fn pthread_setcancelstate 211may fail with: 212.Bl -tag -width Er 213.It Bq Er EINVAL 214The specified state is not 215.Dv PTHREAD_CANCEL_ENABLE 216or 217.Dv PTHREAD_CANCEL_DISABLE . 218.El 219.Pp 220The function 221.Fn pthread_setcanceltype 222may fail with: 223.Bl -tag -width Er 224.It Bq Er EINVAL 225The specified state is not 226.Dv PTHREAD_CANCEL_DEFERRED 227or 228.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 229.El 230.Sh SEE ALSO 231.Xr pthread_cancel 3 232.Sh STANDARDS 233.Fn pthread_testcancel 234conforms to 235.St -p1003.1-96 236