1.\" $OpenBSD: pthread_testcancel.3,v 1.9 2002/05/01 08:03:30 mpech Exp $ 2.\" 3.Dd January 17, 1999 4.Dt PTHREAD_TESTCANCEL 3 5.Os 6.Sh NAME 7.Nm pthread_setcancelstate , 8.Nm pthread_setcanceltype , 9.Nm pthread_testcancel 10.Nd set cancelability state 11.Sh SYNOPSIS 12.Fd #include <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 a number of ways. 75.Pp 76Each thread maintains its own 77.Dq cancelability state 78which may be encoded in two bits: 79.Bl -hang 80.It Em Cancelability Enable 81When cancelability is 82.Dv PTHREAD_CANCEL_DISABLE , 83cancellation requests against the target thread are held pending. 84.It Em Cancelability Type 85When cancelability is enabled and the cancelability type is 86.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 87new or pending cancellation requests may be acted upon at any time. 88When cancelability is enabled and the cancelability type is 89.Dv PTHREAD_CANCEL_DEFERRED , 90cancellation requests are held pending until a cancellation point (see 91below) is reached. 92If cancelability is disabled, the setting of the 93cancelability type has no immediate effect as all cancellation requests 94are held pending; however, once cancelability is enabled again the new 95type will be in effect. 96.El 97.Ss Cancellation Points 98Cancellation points will occur when a thread is executing the following 99functions: 100.Fn close , 101.Fn creat , 102.Fn fcntl , 103.Fn fsync , 104.Fn msync , 105.Fn nanosleep , 106.Fn open , 107.Fn pause , 108.Fn pthread_cond_timedwait , 109.Fn pthread_cond_wait , 110.Fn pthread_join , 111.Fn pthread_testcancel , 112.Fn read , 113.Fn sigwaitinfo , 114.Fn sigsuspend , 115.Fn sigwait , 116.Fn sleep , 117.Fn system , 118.Fn tcdrain , 119.Fn wait , 120.Fn waitpid , 121.Fn write . 122.Sh RETURN VALUES 123If successful, the 124.Fn pthread_setcancelstate 125and 126.Fn pthread_setcanceltype 127functions will return zero. 128Otherwise, an error number shall be returned to indicate the error. 129.Pp 130The 131.Fn pthread_setcancelstate 132and 133.Fn pthread_setcanceltype 134functions are used to control the points at which a thread may be 135asynchronously cancelled. 136For cancellation control to be usable in modular 137fashion, some rules must be followed. 138.Pp 139For purposes of this discussion, consider an object to be a generalization 140of a procedure. It is a set of procedures and global variables written as 141a unit and called by clients not known by the object. 142Objects may depend on other objects. 143.Pp 144First, cancelability should only be disabled on entry to an object, never 145explicitly enabled. 146On exit from an object, the cancelability state should 147always be restored to its value on entry to the object. 148.Pp 149This follows from a modularity argument: if the client of an object (or the 150client of an object that uses that object) has disabled cancelability, it is 151because the client doesn't want to have to worry about how to clean up if the 152thread is cancelled while executing some sequence of actions. 153If an object 154is called in such a state and it enables cancelability and a cancellation 155request is pending for that thread, then the thread will be cancelled, 156contrary to the wish of the client that disabled. 157.Pp 158Second, the cancelability type may be explicitly set to either 159.Em deferred 160or 161.Em asynchronous 162upon entry to an object. 163But as with the cancelability state, on exit from 164an object that cancelability type should always be restored to its value on 165entry to the object. 166.Pp 167Finally, only functions that are cancel-safe may be called from a thread that 168is asynchronously cancelable. 169.Sh ERRORS 170The function 171.Fn pthread_setcancelstate 172may fail with: 173.Bl -tag -width Er 174.It Bq Er EINVAL 175The specified state is not 176.Dv PTHREAD_CANCEL_ENABLE 177or 178.Dv PTHREAD_CANCEL_DISABLE . 179.El 180.Pp 181The function 182.Fn pthread_setcanceltype 183may fail with: 184.Bl -tag -width Er 185.It Bq Er EINVAL 186The specified state is not 187.Dv PTHREAD_CANCEL_DEFERRED 188or 189.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 190.El 191.Sh SEE ALSO 192.Xr pthread_cancel 3 193.Sh STANDARDS 194.Fn pthread_testcancel 195conforms to 196.St -p1003.1-96 197