pthreads/pthread_cancel.3

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