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