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_setcancelstate.3p (5959B)


  1. '\" et
  2. .TH PTHREAD_SETCANCELSTATE "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_setcancelstate,
  12. pthread_setcanceltype,
  13. pthread_testcancel
  14. \(em set cancelability state
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <pthread.h>
  19. .P
  20. int pthread_setcancelstate(int \fIstate\fP, int *\fIoldstate\fP);
  21. int pthread_setcanceltype(int \fItype\fP, int *\fIoldtype\fP);
  22. void pthread_testcancel(void);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIpthread_setcancelstate\fR()
  27. function shall atomically both set the calling thread's cancelability
  28. state to the indicated
  29. .IR state
  30. and return the previous cancelability state at the location referenced
  31. by
  32. .IR oldstate .
  33. Legal values for
  34. .IR state
  35. are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.
  36. .P
  37. The
  38. \fIpthread_setcanceltype\fR()
  39. function shall atomically both set the calling thread's cancelability
  40. type to the indicated
  41. .IR type
  42. and return the previous cancelability type at the location referenced
  43. by
  44. .IR oldtype .
  45. Legal values for
  46. .IR type
  47. are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
  48. .P
  49. The cancelability state and type of any newly created threads,
  50. including the thread in which
  51. \fImain\fR()
  52. was first invoked, shall be PTHREAD_CANCEL_ENABLE and
  53. PTHREAD_CANCEL_DEFERRED respectively.
  54. .P
  55. The
  56. \fIpthread_testcancel\fR()
  57. function shall create a cancellation point in the calling thread. The
  58. \fIpthread_testcancel\fR()
  59. function shall have no effect if cancelability is disabled.
  60. .SH "RETURN VALUE"
  61. If successful, the
  62. \fIpthread_setcancelstate\fR()
  63. and
  64. \fIpthread_setcanceltype\fR()
  65. functions shall return zero; otherwise, an error number shall be
  66. returned to indicate the error.
  67. .SH ERRORS
  68. The
  69. \fIpthread_setcancelstate\fR()
  70. function may fail if:
  71. .TP
  72. .BR EINVAL
  73. The specified state is not PTHREAD_CANCEL_ENABLE or
  74. PTHREAD_CANCEL_DISABLE.
  75. .P
  76. The
  77. \fIpthread_setcanceltype\fR()
  78. function may fail if:
  79. .TP
  80. .BR EINVAL
  81. The specified type is not PTHREAD_CANCEL_DEFERRED or
  82. PTHREAD_CANCEL_ASYNCHRONOUS.
  83. .P
  84. These functions shall not return an error code of
  85. .BR [EINTR] .
  86. .LP
  87. .IR "The following sections are informative."
  88. .SH EXAMPLES
  89. None.
  90. .SH "APPLICATION USAGE"
  91. In order to write a signal handler for an asynchronous signal which
  92. can run safely in a cancellable thread,
  93. \fIpthread_setcancelstate\fR()
  94. must be used to disable cancellation for the duration of any calls
  95. that the signal handler makes which are cancellation points. However,
  96. the standard does not permit strictly conforming applications to call
  97. \fIpthread_setcancelstate\fR()
  98. from a signal handler since it is not currently required to be
  99. async-signal-safe. On implementations where
  100. \fIpthread_setcancelstate\fR()
  101. is not async-signal-safe, alternatives are to ensure either that the
  102. corresponding signals are blocked during execution of functions that
  103. are not async-cancel-safe or that cancellation is disabled during
  104. times when those signals could be delivered. Implementations are
  105. strongly encouraged to make
  106. \fIpthread_setcancelstate\fR()
  107. async-signal-safe.
  108. .SH RATIONALE
  109. The
  110. \fIpthread_setcancelstate\fR()
  111. and
  112. \fIpthread_setcanceltype\fR()
  113. functions control the points at which a thread may be
  114. asynchronously canceled. For cancellation control to be usable in
  115. modular fashion, some rules need to be followed.
  116. .P
  117. An object can be considered to be a generalization of a procedure. It
  118. is a set of procedures and global variables written as a unit and
  119. called by clients not known by the object. Objects may depend on other
  120. objects.
  121. .P
  122. First, cancelability should only be disabled on entry to an object,
  123. never explicitly enabled. On exit from an object, the
  124. cancelability state should always be restored to its value on entry to
  125. the object.
  126. .P
  127. This follows from a modularity argument: if the client of an object
  128. (or the client of an object that uses that object) has disabled
  129. cancelability, it is because the client does not want to be concerned
  130. about cleaning up if the thread is canceled while executing some
  131. sequence of actions. If an object is called in such a state and it
  132. enables cancelability and a cancellation request is pending for that
  133. thread, then the thread is canceled, contrary to the wish of the client
  134. that disabled.
  135. .P
  136. Second, the
  137. cancelability type may be explicitly set to either
  138. .IR deferred
  139. or
  140. .IR asynchronous
  141. upon entry to an object. But as with the cancelability state, on exit
  142. from an object the cancelability type should always be restored to its
  143. value on entry to the object.
  144. .P
  145. Finally, only functions that are cancel-safe
  146. may be called from a thread that is asynchronously cancelable.
  147. .SH "FUTURE DIRECTIONS"
  148. The
  149. \fIpthread_setcancelstate\fR()
  150. function may be added to the table of async-signal-safe functions in
  151. .IR "Section 2.4.3" ", " "Signal Actions".
  152. .SH "SEE ALSO"
  153. .IR "\fIpthread_cancel\fR\^(\|)"
  154. .P
  155. The Base Definitions volume of POSIX.1\(hy2017,
  156. .IR "\fB<pthread.h>\fP"
  157. .\"
  158. .SH COPYRIGHT
  159. Portions of this text are reprinted and reproduced in electronic form
  160. from IEEE Std 1003.1-2017, Standard for Information Technology
  161. -- Portable Operating System Interface (POSIX), The Open Group Base
  162. Specifications Issue 7, 2018 Edition,
  163. Copyright (C) 2018 by the Institute of
  164. Electrical and Electronics Engineers, Inc and The Open Group.
  165. In the event of any discrepancy between this version and the original IEEE and
  166. The Open Group Standard, the original IEEE and The Open Group Standard
  167. is the referee document. The original Standard can be obtained online at
  168. http://www.opengroup.org/unix/online.html .
  169. .PP
  170. Any typographical or formatting errors that appear
  171. in this page are most likely
  172. to have been introduced during the conversion of the source files to
  173. man page format. To report such errors, see
  174. https://www.kernel.org/doc/man-pages/reporting_bugs.html .