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