pthread_cancel(3)pthread_cancel(3)NAMEpthread_cancel - Allows a thread to request a thread to terminate exe‐
cution
SYNOPSIS
#include <pthread.h>
int pthread_cancel(
pthread_t thread );
LIBRARY
DECthreads POSIX 1003.1c Library (libpthread.so)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
IEEE Std 1003.1c-1995, POSIX System Application Program Interface
PARAMETERS
Thread that receives a cancellation request.
DESCRIPTION
This routine sends a cancellation request to the specified target
thread. A cancellation request is a mechanism by which a calling thread
requests the target thread to terminate as quickly as possible. Issuing
a cancellation request does not guarantee that the target thread will
receive or handle the request.
When the cancellation request is acted on, all active cleanup handler
routines for the target thread are called. When the last cleanup han‐
dler returns, the thread-specific data destructor routines are called
for each thread-specific data key with a destructor and for which the
target thread has a non-NULL value. Finally, the target thread is ter‐
minated.
Note that cancellation of the target thread runs asynchronously with
respect to the calling thread's returning from pthread_cancel(3). The
target thread's cancelability state and type determine when or if the
cancellation takes place, as follows: The target thread can delay can‐
cellation during critical operations by setting its cancelability state
to PTHREAD_CANCEL_DISABLE. Because of communication delays, the call‐
ing thread can only rely on the fact that a cancellation request will
eventually become pending in the target thread (provided that the tar‐
get thread does not terminate beforehand). The calling thread has no
guarantee that a pending cancellation request will be delivered because
delivery is controlled by the target thread.
When a cancellation request is delivered to a thread, termination pro‐
cessing is similar to that for pthread_exit(3). For more information
about thread termination, see the discussion of thread termination in
pthread_create(3).
This routine is preferred in implementing an Ada abort statement and
any other language- or software-defined construct for requesting thread
cancellation.
The results of this routine are unpredictable, if the value specified
in thread refers to a thread that does not currently exist.
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error. Possible return values are as follows:
Successful completion. The specified thread is invalid. The thread
argument does not specify an existing thread.
ERRORS
None
SEE ALSO
Functions: pthread_cleanup_pop(3), pthread_cleanup_push(3),
pthread_create(3), pthread_exit(3), pthread_join(3), pthread_setcancel‐
state(3), pthread_setcanceltype(3), pthread_testcancel(3)
Manuals: Guide to DECthreads and Programmer's Guide
pthread_cancel(3)