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.Sh SYNOPSIS 14.In pthread.h 15.Ft int 16.Fn pthread_setcancelstate "int state" "int *oldstate" 17.Ft int 18.Fn pthread_setcanceltype "int type" "int *oldtype" 19.Ft void 20.Fn pthread_testcancel "void" 21.Sh DESCRIPTION 22The 23.Fn pthread_setcancelstate 24function atomically both sets the calling thread's cancelability state 25to the indicated 26.Fa state 27and, if 28.Fa oldstate 29is not 30.Dv NULL , 31returns the previous cancelability state at the location referenced by 32.Fa oldstate . 33Legal values for 34.Fa state 35are 36.Dv PTHREAD_CANCEL_ENABLE 37and 38.Dv PTHREAD_CANCEL_DISABLE . 39.Pp 40The 41.Fn pthread_setcanceltype 42function atomically both sets the calling thread's cancelability type 43to the indicated 44.Fa type 45and, if 46.Fa oldtype 47is not 48.Dv NULL , 49returns the previous cancelability type at the location referenced by 50.Fa oldtype . 51Legal values for 52.Fa type 53are 54.Dv PTHREAD_CANCEL_DEFERRED 55and 56.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 57.Pp 58The cancelability state and type of any newly created threads, including the 59thread in which 60.Fn main 61was first invoked, are 62.Dv PTHREAD_CANCEL_ENABLE 63and 64.Dv PTHREAD_CANCEL_DEFERRED 65respectively. 66.Pp 67The 68.Fn pthread_testcancel 69function creates a cancellation point in the calling thread. 70The 71.Fn pthread_testcancel 72function has no effect if cancelability is disabled. 73.Pp 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 78a number of ways. 79.Pp 80Each thread maintains its own 81.Dq cancelability state 82which may be encoded in two bits: 83.Bl -hang 84.It Em Cancelability Enable 85When cancelability is 86.Dv PTHREAD_CANCEL_DISABLE , 87cancellation requests against the target thread are held pending. 88.It Em Cancelability Type 89When cancelability is enabled and the cancelability type is 90.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 91new or pending cancellation requests may be acted upon at any time. 92When cancelability is enabled and the cancelability type is 93.Dv PTHREAD_CANCEL_DEFERRED , 94cancellation requests are held pending until a cancellation point (see 95below) is reached. 96If cancelability is disabled, the setting of the 97cancelability type has no immediate effect as all cancellation requests 98are held pending; however, once cancelability is enabled again the new 99type will be in effect. 100.El 101.Ss Cancellation Points 102Cancellation points will occur when a thread is executing the following 103functions: 104.Fn close , 105.Fn creat , 106.Fn fcntl , 107.Fn fsync , 108.Fn msync , 109.Fn nanosleep , 110.Fn open , 111.Fn pause , 112.Fn pthread_cond_timedwait , 113.Fn pthread_cond_wait , 114.Fn pthread_join , 115.Fn pthread_testcancel , 116.Fn read , 117.Fn sigwaitinfo , 118.Fn sigsuspend , 119.Fn sigwait , 120.Fn sleep , 121.Fn system , 122.Fn tcdrain , 123.Fn wait , 124.Fn waitpid , 125.Fn write . 126.Sh RETURN VALUES 127If successful, the 128.Fn pthread_setcancelstate 129and 130.Fn pthread_setcanceltype 131functions will return zero. 132Otherwise, an error number shall be returned to 133indicate the error. 134.Pp 135The 136.Fn pthread_setcancelstate 137and 138.Fn pthread_setcanceltype 139functions are used to control the points at which a thread may be 140asynchronously canceled. 141For cancellation control to be usable in modular 142fashion, some rules must be followed. 143.Pp 144For purposes of this discussion, consider an object to be a generalization 145of a procedure. 146It is a set of procedures and global variables written as 147a unit and called by clients not known by the object. 148Objects may depend 149on other objects. 150.Pp 151First, cancelability should only be disabled on entry to an object, never 152explicitly enabled. 153On exit from an object, the cancelability state should 154always be restored to its value on entry to the object. 155.Pp 156This follows from a modularity argument: if the client of an object (or the 157client of an object that uses that object) has disabled cancelability, it is 158because the client doesn't want to have to worry about how to clean up if the 159thread is canceled while executing some sequence of actions. 160If an object 161is called in such a state and it enables cancelability and a cancellation 162request is pending for that thread, then the thread will be canceled, 163contrary to the wish of the client that disabled. 164.Pp 165Second, the cancelability type may be explicitly set to either 166.Em deferred 167or 168.Em asynchronous 169upon entry to an object. 170But as with the cancelability state, on exit from 171an object that cancelability type should always be restored to its value on 172entry to the object. 173.Pp 174Finally, only functions that are cancel-safe may be called from a thread that 175is asynchronously cancelable. 176.Sh ERRORS 177The function 178.Fn pthread_setcancelstate 179may fail with: 180.Bl -tag -width Er 181.It Bq Er EINVAL 182The specified state is not 183.Dv PTHREAD_CANCEL_ENABLE 184or 185.Dv PTHREAD_CANCEL_DISABLE . 186.El 187.Pp 188The function 189.Fn pthread_setcanceltype 190may fail with: 191.Bl -tag -width Er 192.It Bq Er EINVAL 193The specified state is not 194.Dv PTHREAD_CANCEL_DEFERRED 195or 196.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 197.El 198.Sh SEE ALSO 199.Xr pthread_cancel 3 200.Sh STANDARDS 201The 202.Fn pthread_testcancel 203function conforms to 204.St -p1003.1-96 . 205.Sh AUTHORS 206This man page was written by 207.An David Leonard Aq d@openbsd.org 208for the 209.Ox 210implementation of 211.Xr pthread_cancel 3 . 212