Man Linux: Main Page and Category List

NAME

       pthread_cancel - cancel execution of a thread

SYNOPSIS

       #include <pthread.h>

       int pthread_cancel(pthread_t thread);

DESCRIPTION

       The  pthread_cancel()  function  shall request that thread be canceled.
       The target thread’s cancelability state and type  determines  when  the
       cancellation  takes  effect.  When  the  cancellation  is acted on, the
       cancellation cleanup handlers for thread shall be called. When the last
       cancellation   cleanup   handler   returns,  the  thread-specific  data
       destructor  functions  shall  be  called  for  thread.  When  the  last
       destructor function returns, thread shall be terminated.

       The   cancellation   processing   in   the   target  thread  shall  run
       asynchronously with  respect  to  the  calling  thread  returning  from
       pthread_cancel().

RETURN VALUE

       If   successful,  the  pthread_cancel()  function  shall  return  zero;
       otherwise, an error number shall be returned to indicate the error.

ERRORS

       The pthread_cancel() function may fail if:

       ESRCH  No thread could be found corresponding to that specified by  the
              given thread ID.

       The  pthread_cancel()  function  shall  not  return  an  error  code of
       [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       Two alternative functions were considered for sending the  cancellation
       notification to a thread. One would be to define a new SIGCANCEL signal
       that had the cancellation semantics when delivered; the  other  was  to
       define  the  new  pthread_cancel()  function,  which  would trigger the
       cancellation semantics.

       The advantage of a new signal was that so much of the delivery criteria
       were identical to that used when trying to deliver a signal that making
       cancellation notification a signal was seen as consistent. Indeed, many
       implementations  implement  cancellation using a special signal. On the
       other hand, there would be no signal functions that could be used  with
       this  signal  except  pthread_kill(), and the behavior of the delivered
       cancellation signal would be unlike  any  previously  existing  defined
       signal.

       The  benefits  of  a special function include the recognition that this
       signal would be defined because of the similar  delivery  criteria  and
       that  this  is  the only common behavior between a cancellation request
       and a signal. In addition, the cancellation delivery mechanism does not
       have  to  be  implemented  as  a  signal. There are also strong, if not
       stronger,  parallels  with  language  exception  mechanisms  than  with
       signals  that  are  potentially  obscured  if the delivery mechanism is
       visibly closer to signals.

       In the end, it was considered that as there were so many exceptions  to
       the  use  of the new signal with existing signals functions it would be
       misleading.  A  special  function  has  resolved  this  problem.   This
       function  was  carefully  defined  so that an implementation wishing to
       provide the cancellation functions on top of signals could do  so.  The
       special  function  also  means  that implementations are not obliged to
       implement cancellation with signals.

FUTURE DIRECTIONS

       None.

SEE ALSO

       pthread_exit(3),      pthread_cond_timedwait(3),       pthread_join(3),
       pthread_cleanup_pop(3),                        pthread_cleanup_push(3),
       pthread_setcancelstate(3),                    pthread_setcanceltype(3),
       pthread_testcancel(3),   the  Base  Definitions  volume  of   IEEE  Std
       1003.1-2001, <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .