lib/libpthread/pthread_cancel.3

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