lib/libc_r/man/pthread_testcancel.3

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