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