mirror of https://github.com/mkerrisk/man-pages
104 lines
4.1 KiB
Plaintext
104 lines
4.1 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "PTHREAD_CANCEL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" pthread_cancel
|
||
|
.SH NAME
|
||
|
pthread_cancel \- cancel execution of a thread
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <pthread.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int pthread_cancel(pthread_t\fP \fIthread\fP\fB); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIpthread_cancel\fP() function shall request that \fIthread\fP
|
||
|
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
|
||
|
\fIthread\fP shall be called. When the last cancellation cleanup handler
|
||
|
returns, the thread-specific data destructor functions
|
||
|
shall be called for \fIthread\fP. When the last destructor function
|
||
|
returns, \fIthread\fP shall be terminated.
|
||
|
.LP
|
||
|
The cancellation processing in the target thread shall run asynchronously
|
||
|
with respect to the calling thread returning from
|
||
|
\fIpthread_cancel\fP().
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
If successful, the \fIpthread_cancel\fP() function shall return zero;
|
||
|
otherwise, an error number shall be returned to indicate
|
||
|
the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIpthread_cancel\fP() function may fail if:
|
||
|
.TP 7
|
||
|
.B ESRCH
|
||
|
No thread could be found corresponding to that specified by the given
|
||
|
thread ID.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fIpthread_cancel\fP() function shall not return an error code
|
||
|
of [EINTR].
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
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 \fIpthread_cancel\fP()
|
||
|
function, which would trigger the cancellation semantics.
|
||
|
.LP
|
||
|
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 \fIpthread_kill\fP(),
|
||
|
and the behavior of the delivered cancellation signal would be unlike
|
||
|
any previously existing defined signal.
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
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.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIpthread_exit\fP() , \fIpthread_cond_timedwait\fP() , \fIpthread_join\fP()
|
||
|
, \fIpthread_setcancelstate\fP() , the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|