logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_cancel.3p (4610B)

    

  1. '\" et
  2. .TH PTHREAD_CANCEL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_cancel
  12. \(em cancel execution of a thread
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_cancel(pthread_t \fIthread\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpthread_cancel\fR()
  23. function shall request that
  24. .IR thread
  25. be canceled. The target thread's cancelability state and type
  26. determines when the cancellation takes effect. When the cancellation
  27. is acted on, the cancellation cleanup handlers for
  28. .IR thread
  29. shall be called. When the last cancellation cleanup handler returns,
  30. the thread-specific data destructor functions shall be called for
  31. .IR thread .
  32. When the last destructor function returns,
  33. .IR thread
  34. shall be terminated.
  35. .P
  36. The cancellation processing in the target thread shall run
  37. asynchronously with respect to the calling thread returning from
  38. \fIpthread_cancel\fR().
  39. .SH "RETURN VALUE"
  40. If successful, the
  41. \fIpthread_cancel\fR()
  42. function shall return zero; otherwise, an error number shall be
  43. returned to indicate the error.
  44. .SH ERRORS
  45. The
  46. \fIpthread_cancel\fR()
  47. function shall not return an error code of
  48. .BR [EINTR] .
  49. .LP
  50. .IR "The following sections are informative."
  51. .SH EXAMPLES
  52. None.
  53. .SH "APPLICATION USAGE"
  54. None.
  55. .SH RATIONALE
  56. Two alternative functions were considered for sending the cancellation
  57. notification to a thread. One would be to define a new SIGCANCEL
  58. signal that had the cancellation semantics when delivered; the other was
  59. to define the new
  60. \fIpthread_cancel\fR()
  61. function, which would trigger the cancellation semantics.
  62. .P
  63. The advantage of a new signal was that so much of the delivery criteria
  64. were identical to that used when trying to deliver a signal that making
  65. cancellation notification a signal was seen as consistent. Indeed, many
  66. implementations implement cancellation using a special signal. On the
  67. other hand, there would be no signal functions that could be used with
  68. this signal except
  69. \fIpthread_kill\fR(),
  70. and the behavior of the delivered cancellation signal would be unlike
  71. any previously existing defined signal.
  72. .P
  73. The benefits of a special function include the recognition that this
  74. signal would be defined because of the similar delivery criteria and
  75. that this is the only common behavior between a cancellation request and
  76. a signal. In addition, the cancellation delivery mechanism does not
  77. have to be implemented as a signal. There are also strong, if not
  78. stronger, parallels with language exception mechanisms than with
  79. signals that are potentially obscured if the delivery mechanism is
  80. visibly closer to signals.
  81. .P
  82. In the end, it was considered that as there were so many exceptions to
  83. the use of the new signal with existing signals functions it
  84. would be misleading. A special function has resolved this problem.
  85. This function was carefully defined so that an implementation wishing
  86. to provide the cancellation functions on top of signals could do so.
  87. The special function also means that implementations are not obliged
  88. to implement cancellation with signals.
  89. .P
  90. If an implementation detects use of a thread ID after the end of its
  91. lifetime, it is recommended that the function should fail and report an
  92. .BR [ESRCH] 
  93. error.
  94. .SH "FUTURE DIRECTIONS"
  95. None.
  96. .SH "SEE ALSO"
  97. .ad l
  98. .IR "\fIpthread_exit\fR\^(\|)",
  99. .IR "\fIpthread_cond_timedwait\fR\^(\|)",
  100. .IR "\fIpthread_join\fR\^(\|)",
  101. .IR "\fIpthread_setcancelstate\fR\^(\|)"
  102. .ad b
  103. .P
  104. The Base Definitions volume of POSIX.1\(hy2017,
  105. .IR "\fB<pthread.h>\fP"
  106. .\"
  107. .SH COPYRIGHT
  108. Portions of this text are reprinted and reproduced in electronic form
  109. from IEEE Std 1003.1-2017, Standard for Information Technology
  110. -- Portable Operating System Interface (POSIX), The Open Group Base
  111. Specifications Issue 7, 2018 Edition,
  112. Copyright (C) 2018 by the Institute of
  113. Electrical and Electronics Engineers, Inc and The Open Group.
  114. In the event of any discrepancy between this version and the original IEEE and
  115. The Open Group Standard, the original IEEE and The Open Group Standard
  116. is the referee document. The original Standard can be obtained online at
  117. http://www.opengroup.org/unix/online.html .
  118. .PP
  119. Any typographical or formatting errors that appear
  120. in this page are most likely
  121. to have been introduced during the conversion of the source files to
  122. man page format. To report such errors, see
  123. https://www.kernel.org/doc/man-pages/reporting_bugs.html .