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