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