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_mutexattr_getprotocol.3p (6954B)


  1. '\" et
  2. .TH PTHREAD_MUTEXATTR_GETPROTOCOL "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_mutexattr_getprotocol,
  12. pthread_mutexattr_setprotocol
  13. \(em get and set the protocol attribute of the mutex attributes object
  14. (\fBREALTIME THREADS\fP)
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <pthread.h>
  19. .P
  20. int pthread_mutexattr_getprotocol(const pthread_mutexattr_t
  21. *restrict \fIattr\fP, int *restrict \fIprotocol\fP);
  22. int pthread_mutexattr_setprotocol(pthread_mutexattr_t *\fIattr\fP,
  23. int \fIprotocol\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIpthread_mutexattr_getprotocol\fR()
  28. and
  29. \fIpthread_mutexattr_setprotocol\fR()
  30. functions, respectively, shall get and set the protocol attribute of
  31. a mutex attributes object pointed to by
  32. .IR attr
  33. which was previously created by the function
  34. \fIpthread_mutexattr_init\fR().
  35. .P
  36. The
  37. .IR protocol
  38. attribute defines the protocol to be followed in utilizing mutexes.
  39. The value of
  40. .IR protocol
  41. may be one of:
  42. .P
  43. .nf
  44. PTHREAD_PRIO_INHERIT
  45. PTHREAD_PRIO_NONE
  46. PTHREAD_PRIO_PROTECT
  47. .fi
  48. .P
  49. which are defined in the
  50. .IR <pthread.h>
  51. header. The default value of the attribute shall be PTHREAD_PRIO_NONE.
  52. .P
  53. When a thread owns a mutex with the PTHREAD_PRIO_NONE
  54. .IR protocol
  55. attribute, its priority and scheduling shall not be affected by
  56. its mutex ownership.
  57. .P
  58. When a thread is blocking higher priority threads because of owning one
  59. or more robust mutexes with the PTHREAD_PRIO_INHERIT
  60. .IR protocol
  61. attribute, it shall execute at the higher of its priority or the priority
  62. of the highest priority thread waiting on any of the robust mutexes
  63. owned by this thread and initialized with this protocol.
  64. .P
  65. When a thread is blocking higher priority threads because of owning one
  66. or more non-robust mutexes with the PTHREAD_PRIO_INHERIT
  67. .IR protocol
  68. attribute, it shall execute at the higher of its priority or the priority
  69. of the highest priority thread waiting on any of the non-robust mutexes
  70. owned by this thread and initialized with this protocol.
  71. .P
  72. When a thread owns one or more robust mutexes initialized with the
  73. PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its
  74. priority or the highest of the priority ceilings of all the robust mutexes
  75. owned by this thread and initialized with this attribute, regardless of
  76. whether other threads are blocked on any of these robust mutexes or not.
  77. .P
  78. When a thread owns one or more non-robust mutexes initialized with the
  79. PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its
  80. priority or the highest of the priority ceilings of all the non-robust
  81. mutexes owned by this thread and initialized with this attribute,
  82. regardless of whether other threads are blocked on any of these non-robust
  83. mutexes or not.
  84. .P
  85. While a thread is holding a mutex which has been initialized with the
  86. PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it
  87. shall not be subject to being moved to the tail of the scheduling queue
  88. at its priority in the event that its original priority is changed,
  89. such as by a call to
  90. \fIsched_setparam\fR().
  91. Likewise, when a thread unlocks a mutex that has been initialized with
  92. the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes,
  93. it shall not be subject to being moved to the tail of the scheduling
  94. queue at its priority in the event that its original priority is
  95. changed.
  96. .P
  97. If a thread simultaneously owns several mutexes initialized with
  98. different protocols, it shall execute at the highest of the priorities
  99. that it would have obtained by each of these protocols.
  100. .P
  101. When a thread makes a call to
  102. \fIpthread_mutex_lock\fR(),
  103. the mutex was initialized with the protocol attribute having the value
  104. PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the
  105. mutex is owned by another thread, that owner thread shall inherit the
  106. priority level of the calling thread as long as it continues to own the
  107. mutex. The implementation shall update its execution priority to the
  108. maximum of its assigned priority and all its inherited priorities.
  109. Furthermore, if this owner thread itself becomes blocked on another
  110. mutex with the
  111. .IR protocol
  112. attribute having the value PTHREAD_PRIO_INHERIT, the same priority
  113. inheritance effect shall be propagated to this other owner thread,
  114. in a recursive manner.
  115. .P
  116. The behavior is undefined if the value specified by the
  117. .IR attr
  118. argument to
  119. \fIpthread_mutexattr_getprotocol\fR()
  120. or
  121. \fIpthread_mutexattr_setprotocol\fR()
  122. does not refer to an initialized mutex attributes object.
  123. .SH "RETURN VALUE"
  124. Upon successful completion, the
  125. \fIpthread_mutexattr_getprotocol\fR()
  126. and
  127. \fIpthread_mutexattr_setprotocol\fR()
  128. functions shall return zero; otherwise, an error number shall be
  129. returned to indicate the error.
  130. .SH ERRORS
  131. The
  132. \fIpthread_mutexattr_setprotocol\fR()
  133. function shall fail if:
  134. .TP
  135. .BR ENOTSUP
  136. The value specified by
  137. .IR protocol
  138. is an unsupported value.
  139. .P
  140. The
  141. \fIpthread_mutexattr_getprotocol\fR()
  142. and
  143. \fIpthread_mutexattr_setprotocol\fR()
  144. functions may fail if:
  145. .TP
  146. .BR EINVAL
  147. The value specified by
  148. .IR protocol
  149. is invalid.
  150. .TP
  151. .BR EPERM
  152. The caller does not have the privilege to perform the operation.
  153. .P
  154. These functions shall not return an error code of
  155. .BR [EINTR] .
  156. .LP
  157. .IR "The following sections are informative."
  158. .SH EXAMPLES
  159. None.
  160. .SH "APPLICATION USAGE"
  161. None.
  162. .SH RATIONALE
  163. If an implementation detects that the value specified by the
  164. .IR attr
  165. argument to
  166. \fIpthread_mutexattr_getprotocol\fR()
  167. or
  168. \fIpthread_mutexattr_setprotocol\fR()
  169. does not refer to an initialized mutex attributes object, it is
  170. recommended that the function should fail and report an
  171. .BR [EINVAL]
  172. error.
  173. .SH "FUTURE DIRECTIONS"
  174. None.
  175. .SH "SEE ALSO"
  176. .IR "\fIpthread_cond_destroy\fR\^(\|)",
  177. .IR "\fIpthread_create\fR\^(\|)",
  178. .IR "\fIpthread_mutex_destroy\fR\^(\|)"
  179. .P
  180. The Base Definitions volume of POSIX.1\(hy2017,
  181. .IR "\fB<pthread.h>\fP"
  182. .\"
  183. .SH COPYRIGHT
  184. Portions of this text are reprinted and reproduced in electronic form
  185. from IEEE Std 1003.1-2017, Standard for Information Technology
  186. -- Portable Operating System Interface (POSIX), The Open Group Base
  187. Specifications Issue 7, 2018 Edition,
  188. Copyright (C) 2018 by the Institute of
  189. Electrical and Electronics Engineers, Inc and The Open Group.
  190. In the event of any discrepancy between this version and the original IEEE and
  191. The Open Group Standard, the original IEEE and The Open Group Standard
  192. is the referee document. The original Standard can be obtained online at
  193. http://www.opengroup.org/unix/online.html .
  194. .PP
  195. Any typographical or formatting errors that appear
  196. in this page are most likely
  197. to have been introduced during the conversion of the source files to
  198. man page format. To report such errors, see
  199. https://www.kernel.org/doc/man-pages/reporting_bugs.html .