NAME
pthread_cancel —
cancel execution of a
thread
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_cancel(
pthread_t
thread);
DESCRIPTION
The
pthread_cancel() function requests that
thread be canceled. The target thread's cancelability
state and type determines whether and when the target thread reacts to the
cancellation request.
- The cancelability state of a thread is
determined by the
pthread_setcancelstate(3)
function. The state can be either:
PTHREAD_CANCEL_ENABLE
: the
cancelability type determines when the actual cancellation occurs.
This is the default.
PTHREAD_CANCEL_DISABLE
: the
request from pthread_cancel() remains queued until
the cancellation is enabled by the thread.
- The cancellation type of a thread is
determined by the
pthread_setcanceltype(3)
function. The type can be either:
PTHREAD_CANCEL_DEFERRED
: the
cancellation will be delayed until the thread calls a function that is
a cancellation point. This is the default. The available cancellation
points are listed in
pthread_setcanceltype(3).
PTHREAD_CANCEL_ASYNCHRONOUS
:
the thread can be canceled at any time.
When the thread reacts to the cancellation request, the following occur:
- The cancellation cleanup handlers for the thread are
called; see
pthread_cleanup_push(3).
- When the last cancellation cleanup handler returns, the
thread-specific data destructor functions will be called for the
thread.
- When the last destructor function returns, the thread will
be terminated; see
pthread_exit(3).
The cancellation processing in the target thread runs asynchronously with
respect to the calling thread returning from
pthread_cancel().
A status of
PTHREAD_CANCELED
is made available to any
threads joining with the target. The symbolic constant
PTHREAD_CANCELED
expands to a constant expression of
type
(void *), whose value matches no pointer to an
object in memory nor the value
NULL
.
RETURN VALUES
If successful, the
pthread_cancel() functions will return
zero. Otherwise an error number will 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.
SEE ALSO
pthread_cleanup_pop(3),
pthread_join(3),
pthread_testcancel(3)
STANDARDS
The function conforms to
IEEE Std 1003.1-2001
(“POSIX.1”).