1.\" $NetBSD: pthread_testcancel.3,v 1.4 2008/04/30 13:10:52 martin Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 14.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 17.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/lib/libpthread/man/pthread_testcancel.3,v 1.9 2002/09/16 19:29:29 mini Exp $ 26.Dd January 30, 2003 27.Dt PTHREAD_TESTCANCEL 3 28.Os 29.Sh NAME 30.Nm pthread_setcancelstate , 31.Nm pthread_setcanceltype , 32.Nm pthread_testcancel 33.Nd set cancelability state 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_setcancelstate "int state" "int *oldstate" 40.Ft int 41.Fn pthread_setcanceltype "int type" "int *oldtype" 42.Ft void 43.Fn pthread_testcancel "void" 44.Sh DESCRIPTION 45The 46.Fn pthread_setcancelstate 47function atomically both sets the calling thread's cancelability state 48to the indicated 49.Fa state 50and, if 51.Fa oldstate 52is not 53.Dv NULL , 54returns the previous cancelability state at the location referenced by 55.Fa oldstate . 56Legal values for 57.Fa state 58are 59.Dv PTHREAD_CANCEL_ENABLE 60and 61.Dv PTHREAD_CANCEL_DISABLE . 62.Pp 63The 64.Fn pthread_setcanceltype 65function atomically both sets the calling thread's cancelability type 66to the indicated 67.Fa type 68and, if 69.Fa oldtype 70is not 71.Dv NULL , 72returns the previous cancelability type at the location referenced by 73.Fa oldtype . 74Legal values for 75.Fa type 76are 77.Dv PTHREAD_CANCEL_DEFERRED 78and 79.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 80.Pp 81The cancelability state and type of any newly created threads, including the 82thread in which 83.Fn main 84was first invoked, are 85.Dv PTHREAD_CANCEL_ENABLE 86and 87.Dv PTHREAD_CANCEL_DEFERRED 88respectively. 89.Pp 90The 91.Fn pthread_testcancel 92function creates a cancellation point in the calling thread. 93The 94.Fn pthread_testcancel 95function has no effect if cancelability is disabled. 96.Ss Cancelability States 97The cancelability state of a thread determines the action taken upon 98receipt of a cancellation request. 99The thread may control cancellation in 100a number of ways. 101.Pp 102Each thread maintains its own 103.Dq cancelability state 104which may be encoded in two bits: 105.Bl -hang 106.It Em Cancelability Enable 107When cancelability is 108.Dv PTHREAD_CANCEL_DISABLE , 109cancellation requests against the target thread are held pending. 110.It Em Cancelability Type 111When cancelability is enabled and the cancelability type is 112.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 113new or pending cancellation requests may be acted upon at any time. 114When cancelability is enabled and the cancelability type is 115.Dv PTHREAD_CANCEL_DEFERRED , 116cancellation requests are held pending until a cancellation point (see 117below) is reached. 118If cancelability is disabled, the setting of the 119cancelability type has no immediate effect as all cancellation requests 120are held pending; however, once cancelability is enabled again the new 121type will be in effect. 122.El 123.Ss Cancellation Points 124Cancellation points will occur when a thread is executing the following 125functions: 126.Fn accept , 127.\".Fn aio_suspend , 128.\".Fn clock_nanosleep , 129.Fn close , 130.Fn connect , 131.Fn creat , 132.Fn fcntl , 133.Fn fsync , 134.Fn fsync_range , 135.\".Fn getmsg , 136.\".Fn getpmsg , 137.\".Fn lockf , 138.\".Fn mq_receive , 139.\".Fn mq_send , 140.\".Fn mq_timedreceive , 141.\".Fn mq_timedsend , 142.Fn msgrcv , 143.Fn msgsnd , 144.Fn msync , 145.Fn nanosleep , 146.Fn open , 147.Fn pause , 148.Fn poll , 149.Fn pread , 150.Fn pselect , 151.Fn pthread_cond_timedwait , 152.Fn pthread_cond_wait , 153.Fn pthread_join , 154.Fn pthread_testcancel , 155.\".Fn putmsg , 156.\".Fn putpmsg , 157.Fn pwrite , 158.Fn read , 159.Fn readv , 160.Fn recv , 161.Fn recvfrom , 162.Fn recvmsg , 163.Fn select , 164.Fn sem_timedwait , 165.Fn sem_wait , 166.Fn send , 167.Fn sendmsg , 168.Fn sendto , 169.Fn sigpause , 170.Fn sigsuspend , 171.Fn sigtimedwait , 172.Fn sigwait , 173.Fn sigwaitinfo , 174.Fn sleep , 175.Fn system , 176.Fn tcdrain , 177.Fn usleep , 178.Fn wait , 179.Fn waitid , 180.Fn waitpid , 181.Fn write , 182and 183.Fn writev . 184.Sh RETURN VALUES 185If successful, the 186.Fn pthread_setcancelstate 187and 188.Fn pthread_setcanceltype 189functions will return zero. 190Otherwise, an error number shall be returned to 191indicate the error. 192.Pp 193The 194.Fn pthread_setcancelstate 195and 196.Fn pthread_setcanceltype 197functions are used to control the points at which a thread may be 198asynchronously canceled. 199For cancellation control to be usable in modular 200fashion, some rules must be followed. 201.Pp 202For purposes of this discussion, consider an object to be a generalization 203of a procedure. 204It is a set of procedures and global variables written as 205a unit and called by clients not known by the object. 206Objects may depend 207on other objects. 208.Pp 209First, cancelability should only be disabled on entry to an object, never 210explicitly enabled. 211On exit from an object, the cancelability state should 212always be restored to its value on entry to the object. 213.Pp 214This follows from a modularity argument: if the client of an object (or the 215client of an object that uses that object) has disabled cancelability, it is 216because the client doesn't want to have to worry about how to clean up if the 217thread is canceled while executing some sequence of actions. 218If an object 219is called in such a state and it enables cancelability and a cancellation 220request is pending for that thread, then the thread will be canceled, 221contrary to the wish of the client that disabled. 222.Pp 223Second, the cancelability type may be explicitly set to either 224.Em deferred 225or 226.Em asynchronous 227upon entry to an object. 228But as with the cancelability state, on exit from 229an object that cancelability type should always be restored to its value on 230entry to the object. 231.Pp 232Finally, only functions that are cancel-safe may be called from a thread that 233is asynchronously cancelable. 234.Sh ERRORS 235The function 236.Fn pthread_setcancelstate 237may fail with: 238.Bl -tag -width Er 239.It Bq Er EINVAL 240The specified state is not 241.Dv PTHREAD_CANCEL_ENABLE 242or 243.Dv PTHREAD_CANCEL_DISABLE . 244.El 245.Pp 246The function 247.Fn pthread_setcanceltype 248may fail with: 249.Bl -tag -width Er 250.It Bq Er EINVAL 251The specified state is not 252.Dv PTHREAD_CANCEL_DEFERRED 253or 254.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 255.El 256.Sh SEE ALSO 257.Xr pthread_cancel 3 258.Sh STANDARDS 259.Fn pthread_testcancel 260conforms to 261.St -p1003.1-96 . 262.Sh AUTHORS 263This man page was written by 264.An David Leonard Aq d@openbsd.org 265for the 266.Ox 267implementation of 268.Xr pthread_cancel 3 . 269