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