# pthread_cancel

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## 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 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.
    
           If an implementation detects use of a thread ID after the end of
           its lifetime, it is recommended that the function should fail and
           report an **[ESRCH]** error.
    


## FUTURE DIRECTIONS



           None.
    


* * *