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.
Cancellation 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 pending 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 cancelability is enabled, the cancelability type
will take effect.
When the cancellation is acted on, the
cancellation cleanup handlers for
thread
are called.
The cancellation cleanup handlers are called in the opposite order in which
they were installed.
When the last cancellation 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 cancellation 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.
STANDARDS CONFORMANCE
pthread_cancel(): POSIX 1003.1c.
