1.\" $NetBSD: pthread_testcancel.3,v 1.3 2003/11/18 00:56:57 thorpej 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 fsync_range , 138.\".Fn getmsg , 139.\".Fn getpmsg , 140.\".Fn lockf , 141.\".Fn mq_receive , 142.\".Fn mq_send , 143.\".Fn mq_timedreceive , 144.\".Fn mq_timedsend , 145.Fn msgrcv , 146.Fn msgsnd , 147.Fn msync , 148.Fn nanosleep , 149.Fn open , 150.Fn pause , 151.Fn poll , 152.Fn pread , 153.Fn pselect , 154.Fn pthread_cond_timedwait , 155.Fn pthread_cond_wait , 156.Fn pthread_join , 157.Fn pthread_testcancel , 158.\".Fn putmsg , 159.\".Fn putpmsg , 160.Fn pwrite , 161.Fn read , 162.Fn readv , 163.Fn recv , 164.Fn recvfrom , 165.Fn recvmsg , 166.Fn select , 167.Fn sem_timedwait , 168.Fn sem_wait , 169.Fn send , 170.Fn sendmsg , 171.Fn sendto , 172.Fn sigpause , 173.Fn sigsuspend , 174.Fn sigtimedwait , 175.Fn sigwait , 176.Fn sigwaitinfo , 177.Fn sleep , 178.Fn system , 179.Fn tcdrain , 180.Fn usleep , 181.Fn wait , 182.Fn waitid , 183.Fn waitpid , 184.Fn write , 185and 186.Fn writev . 187.Sh RETURN VALUES 188If successful, the 189.Fn pthread_setcancelstate 190and 191.Fn pthread_setcanceltype 192functions will return zero. 193Otherwise, an error number shall be returned to 194indicate the error. 195.Pp 196The 197.Fn pthread_setcancelstate 198and 199.Fn pthread_setcanceltype 200functions are used to control the points at which a thread may be 201asynchronously canceled. 202For cancellation control to be usable in modular 203fashion, some rules must be followed. 204.Pp 205For purposes of this discussion, consider an object to be a generalization 206of a procedure. 207It is a set of procedures and global variables written as 208a unit and called by clients not known by the object. 209Objects may depend 210on other objects. 211.Pp 212First, cancelability should only be disabled on entry to an object, never 213explicitly enabled. 214On exit from an object, the cancelability state should 215always be restored to its value on entry to the object. 216.Pp 217This follows from a modularity argument: if the client of an object (or the 218client of an object that uses that object) has disabled cancelability, it is 219because the client doesn't want to have to worry about how to clean up if the 220thread is canceled while executing some sequence of actions. 221If an object 222is called in such a state and it enables cancelability and a cancellation 223request is pending for that thread, then the thread will be canceled, 224contrary to the wish of the client that disabled. 225.Pp 226Second, the cancelability type may be explicitly set to either 227.Em deferred 228or 229.Em asynchronous 230upon entry to an object. 231But as with the cancelability state, on exit from 232an object that cancelability type should always be restored to its value on 233entry to the object. 234.Pp 235Finally, only functions that are cancel-safe may be called from a thread that 236is asynchronously cancelable. 237.Sh ERRORS 238The function 239.Fn pthread_setcancelstate 240may fail with: 241.Bl -tag -width Er 242.It Bq Er EINVAL 243The specified state is not 244.Dv PTHREAD_CANCEL_ENABLE 245or 246.Dv PTHREAD_CANCEL_DISABLE . 247.El 248.Pp 249The function 250.Fn pthread_setcanceltype 251may fail with: 252.Bl -tag -width Er 253.It Bq Er EINVAL 254The specified state is not 255.Dv PTHREAD_CANCEL_DEFERRED 256or 257.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 258.El 259.Sh SEE ALSO 260.Xr pthread_cancel 3 261.Sh STANDARDS 262.Fn pthread_testcancel 263conforms to 264.St -p1003.1-96 . 265.Sh AUTHORS 266This man page was written by 267.An David Leonard Aq d@openbsd.org 268for the 269.Ox 270implementation of 271.Xr pthread_cancel 3 . 272