diff options
Diffstat (limited to 'man3p/pthread_cancel.3p')
| -rw-r--r-- | man3p/pthread_cancel.3p | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/man3p/pthread_cancel.3p b/man3p/pthread_cancel.3p new file mode 100644 index 000000000..6f4ca8484 --- /dev/null +++ b/man3p/pthread_cancel.3p @@ -0,0 +1,103 @@ +.\" 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 . |