pthread_cancel.3t (2010 09)

p
pthread_cancel(3T) pthread_cancel(3T)
(Pthread Library)
NAME
pthread_cancel() - cancel execution of a thread
SYNOPSIS
#include <pthread.h>
int pthread_cancel(
pthread_t thread
);
PARAMETERS
thread Target thread to be canceled.
DESCRIPTION
pthread_cancel()
requests that thread (hereby referred to as target thread) be canceled. It allows a
thread to terminate the execution of any thread in the process in a controlled manner.
The target thread’s cancelability state and type determine when the cancellation takes effect. Cancella-
tion only occurs when the target thread’s cancelability state is
PTHREAD_CANCEL_ENABLE
. When the
target thread’s cancelability state is
PTHREAD_CANCEL_DISABLE
, cancellation requests against the
target thread are held pending and will be acted upon when cancellation is enabled.
When the cancelability type is
PTHREAD_CANCEL_ASYNCHRONOUS for the target thread , new or pend-
ing cancellation requests are acted upon at any time. When the target thread’s cancelability type is
PTHREAD_CANCEL_DEFERRED
, cancellation requests are held pending until the target thread reaches a
cancellation point (see below).
If the target thread’s cancelability state is disabled, the cancelability type does not matter. When cance-
lability is enabled, the cancelability type will take effect.
When the cancellation is acted on, the cancellation cleanup handlers for thread are called. The cancella-
tion cleanup handlers are called in the opposite order in which they were installed. When the last cancel-
lation cleanup handler returns, the thread-specific data destructor functions for thread are called. When
the last destructor function returns, thread shall be terminated.
The caller of
pthread_cancel()
will not wait for the target thread to be canceled.
Cancellation Points
Cancellation points are points inside of certain functions where a thread must act on any pending can-
cellation request when cancelability is enabled if the function would block.
RETURN VALUE
Upon successful completion,
pthread_cancel()
returns zero. Otherwise, an error number is
returned to indicate the error (the
errno variable is not set).
ERRORS
For each of the following conditions, if the condition is detected, the
pthread_cancel() function
returns the corresponding error number:
[ESRCH] No thread could be found corresponding to thread .
WARNINGS
Use of asynchronous cancelability while holding resources that need to be released may result in resource
loss. Applications must carefully follow static lexical scoping rules in their execution behavior. For
instance, the use of setjmp(), return, goto, etc., to leave user-defined cancellation scopes without doing
the necessary scope pop will result in undefined behavior.
AUTHOR
pthread_cancel() was derived from the IEEE POSIX P1003.1c standard.
SEE ALSO
pthread_exit(3T), pthread_join(3T), pthread_setcancelstate(3T), pthread_cleanup_pop(3T),
pthread_cond_wait(3T).
STANDARDS CONFORMANCE
pthread_cancel(): POSIX 1003.1c.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1