share/man/man3/pthread_cancel.3

   1 .\" $FreeBSD$
   2 .Dd January 17, 1999
   3 .Dt PTHREAD_CANCEL 3
   4 .Os
   5 .Sh NAME
   6 .Nm pthread_cancel
   7 .Nd cancel execution of a thread
   8 .Sh LIBRARY
   9 .Lb libc_r
  10 .Lb libpthread
  11 .Lb libthr
  12 .Sh SYNOPSIS
  13 .In pthread.h
  14 .Ft int
  15 .Fn pthread_cancel "pthread_t thread"
  16 .Sh DESCRIPTION
  17 The
  18 .Fn pthread_cancel
  19 function requests that
  20 .Fa thread
  21 be canceled.
  22 The target thread's cancelability state and type determines
  23 when the cancellation takes effect.
  24 When the cancellation is acted on,
  25 the cancellation cleanup handlers for
  26 .Fa thread
  27 are called.
  28 When the last cancellation cleanup handler returns,
  29 the thread-specific data destructor functions will be called for
  30 .Fa thread .
  31 When the last destructor function returns,
  32 .Fa thread
  33 will be terminated.
  34 .Pp
  35 The cancellation processing in the target thread runs asynchronously with
  36 respect to the calling thread returning from
  37 .Fn pthread_cancel .
  38 .Pp
  39 A status of
  40 .Dv PTHREAD_CANCELED
  41 is made available to any threads joining with the target.
  42 The symbolic
  43 constant
  44 .Dv PTHREAD_CANCELED
  45 expands to a constant expression of type
  46 .Ft "(void *)" ,
  47 whose value matches no pointer to an object in memory nor the value
  48 .Dv NULL .
  49 .Sh RETURN VALUES
  50 If successful, the
  51 .Fn pthread_cancel
  52 functions will return zero.
  53 Otherwise an error number will be returned to
  54 indicate the error.
  55 .Sh ERRORS
  56 The
  57 .Fn pthread_cancel
  58 function will fail if:
  59 .Bl -tag -width Er
  60 .It Bq Er ESRCH
  61 No thread could be found corresponding to that specified by the given
  62 thread ID.
  63 .El
  64 .Sh SEE ALSO
  65 .Xr pthread_cleanup_pop 3 ,
  66 .Xr pthread_cleanup_push 3 ,
  67 .Xr pthread_exit 3 ,
  68 .Xr pthread_join 3 ,
  69 .Xr pthread_setcancelstate 3 ,
  70 .Xr pthread_setcanceltype 3 ,
  71 .Xr pthread_testcancel 3
  72 .Sh STANDARDS
  73 The
  74 .Fn pthread_cancel
  75 function conforms to
  76 .St -p1003.1-96 .
  77 .Sh AUTHORS
  78 This manual page was written by
  79 .An David Leonard Aq d@openbsd.org
  80 for the
  81 .Ox
  82 implementation of
  83 .Fn pthread_cancel .