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_getrobust.3p (5628B)


  1. '\" et
  2. .TH PTHREAD_MUTEXATTR_GETROBUST "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_getrobust,
  12. pthread_mutexattr_setrobust
  13. \(em get and set the mutex robust attribute
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_mutexattr_getrobust(const pthread_mutexattr_t *restrict
  20. \fIattr\fP, int *restrict \fIrobust\fP);
  21. int pthread_mutexattr_setrobust(pthread_mutexattr_t *\fIattr\fP,
  22. int \fIrobust\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIpthread_mutexattr_getrobust\fR()
  27. and
  28. \fIpthread_mutexattr_setrobust\fR()
  29. functions, respectively, shall get and set the mutex
  30. .IR robust
  31. attribute. This attribute is set in the
  32. .IR robust
  33. parameter. Valid values for
  34. .IR robust
  35. include:
  36. .IP PTHREAD_MUTEX_STALLED 6
  37. .br
  38. No special actions are taken if the owner of the mutex is terminated
  39. while holding the mutex lock. This can lead to deadlocks if no other
  40. thread can unlock the mutex.
  41. .br
  42. This is the default value.
  43. .IP PTHREAD_MUTEX_ROBUST 6
  44. .br
  45. If the process containing the owning thread of a robust mutex
  46. terminates while holding the mutex lock, the next thread that acquires
  47. the mutex shall be notified about the termination by the return value
  48. .BR [EOWNERDEAD]
  49. from the locking function. If the owning thread of a robust mutex
  50. terminates while holding the mutex lock, the next thread that attempts
  51. to acquire the mutex may be notified about the termination by the
  52. return value
  53. .BR [EOWNERDEAD] .
  54. The notified thread can then attempt to make the state protected
  55. by the mutex consistent again, and if successful can mark the
  56. mutex state as consistent by calling
  57. \fIpthread_mutex_consistent\fR().
  58. After a subsequent successful call to
  59. \fIpthread_mutex_unlock\fR(),
  60. the mutex lock shall be released and can be used normally by other
  61. threads. If the mutex is unlocked without a call to
  62. \fIpthread_mutex_consistent\fR(),
  63. it shall be in a permanently unusable state and all attempts to lock
  64. the mutex shall fail with the error
  65. .BR [ENOTRECOVERABLE] .
  66. The only permissible operation on such a mutex is
  67. \fIpthread_mutex_destroy\fR().
  68. .P
  69. The behavior is undefined if the value specified by the
  70. .IR attr
  71. argument to
  72. \fIpthread_mutexattr_getrobust\fR()
  73. or
  74. \fIpthread_mutexattr_setrobust\fR()
  75. does not refer to an initialized mutex attributes object.
  76. .SH "RETURN VALUE"
  77. Upon successful completion, the
  78. \fIpthread_mutexattr_getrobust\fR()
  79. function shall return zero and store the value of the
  80. .IR robust
  81. attribute of
  82. .IR attr
  83. into the object referenced by the
  84. .IR robust
  85. parameter. Otherwise, an error value shall be returned to indicate the
  86. error. If successful, the
  87. \fIpthread_mutexattr_setrobust\fR()
  88. function shall return zero; otherwise, an error number shall be
  89. returned to indicate the error.
  90. .SH ERRORS
  91. The
  92. \fIpthread_mutexattr_setrobust\fR()
  93. function shall fail if:
  94. .TP
  95. .BR EINVAL
  96. The value of
  97. .IR robust
  98. is invalid.
  99. .P
  100. These functions shall not return an error code of
  101. .BR [EINTR] .
  102. .LP
  103. .IR "The following sections are informative."
  104. .SH EXAMPLES
  105. None.
  106. .SH "APPLICATION USAGE"
  107. The actions required to make the state protected by the mutex
  108. consistent again are solely dependent on the application. If it is not
  109. possible to make the state of a mutex consistent, robust mutexes can be
  110. used to notify this situation by calling
  111. \fIpthread_mutex_unlock\fR()
  112. without a prior call to
  113. \fIpthread_mutex_consistent\fR().
  114. .P
  115. If the state is declared inconsistent by calling
  116. \fIpthread_mutex_unlock\fR()
  117. without a prior call to
  118. \fIpthread_mutex_consistent\fR(),
  119. a possible approach could be to destroy the mutex and then reinitialize
  120. it. However, it should be noted that this is possible only in certain
  121. situations where the state protected by the mutex has to be
  122. reinitialized and coordination achieved with other threads blocked on
  123. the mutex, because otherwise a call to a locking function with a
  124. reference to a mutex object invalidated by a call to
  125. \fIpthread_mutex_destroy\fR()
  126. results in undefined behavior.
  127. .SH RATIONALE
  128. If an implementation detects that the value specified by the
  129. .IR attr
  130. argument to
  131. \fIpthread_mutexattr_getrobust\fR()
  132. or
  133. \fIpthread_mutexattr_setrobust\fR()
  134. does not refer to an initialized mutex attributes object, it is
  135. recommended that the function should fail and report an
  136. .BR [EINVAL]
  137. error.
  138. .SH "FUTURE DIRECTIONS"
  139. None.
  140. .SH "SEE ALSO"
  141. .IR "\fIpthread_mutex_consistent\fR\^(\|)",
  142. .IR "\fIpthread_mutex_destroy\fR\^(\|)",
  143. .IR "\fIpthread_mutex_lock\fR\^(\|)"
  144. .P
  145. The Base Definitions volume of POSIX.1\(hy2017,
  146. .IR "\fB<pthread.h>\fP"
  147. .\"
  148. .SH COPYRIGHT
  149. Portions of this text are reprinted and reproduced in electronic form
  150. from IEEE Std 1003.1-2017, Standard for Information Technology
  151. -- Portable Operating System Interface (POSIX), The Open Group Base
  152. Specifications Issue 7, 2018 Edition,
  153. Copyright (C) 2018 by the Institute of
  154. Electrical and Electronics Engineers, Inc and The Open Group.
  155. In the event of any discrepancy between this version and the original IEEE and
  156. The Open Group Standard, the original IEEE and The Open Group Standard
  157. is the referee document. The original Standard can be obtained online at
  158. http://www.opengroup.org/unix/online.html .
  159. .PP
  160. Any typographical or formatting errors that appear
  161. in this page are most likely
  162. to have been introduced during the conversion of the source files to
  163. man page format. To report such errors, see
  164. https://www.kernel.org/doc/man-pages/reporting_bugs.html .