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_mutex_timedlock.3p (6617B)


  1. '\" et
  2. .TH PTHREAD_MUTEX_TIMEDLOCK "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_mutex_timedlock
  12. \(em lock a mutex
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. #include <time.h>
  18. .P
  19. int pthread_mutex_timedlock(pthread_mutex_t *restrict \fImutex\fP,
  20. const struct timespec *restrict \fIabstime\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_mutex_timedlock\fR()
  25. function shall lock the mutex object referenced by
  26. .IR mutex .
  27. If the mutex is already locked, the calling thread shall block
  28. until the mutex becomes available as in the
  29. \fIpthread_mutex_lock\fR()
  30. function. If the mutex cannot be locked without waiting for another
  31. thread to unlock the mutex, this wait shall be terminated when the
  32. specified timeout expires.
  33. .P
  34. The timeout shall expire when the absolute time specified by
  35. .IR abstime
  36. passes, as measured by the clock on which timeouts are based (that is,
  37. when the value of that clock equals or exceeds
  38. .IR abstime ),
  39. or if the absolute time specified by
  40. .IR abstime
  41. has already been passed at the time of the call.
  42. .P
  43. The timeout shall be based on the CLOCK_REALTIME clock.
  44. The resolution of the timeout shall be the resolution of the clock on
  45. which it is based. The
  46. .BR timespec
  47. data type is defined in the
  48. .IR <time.h>
  49. header.
  50. .P
  51. Under no circumstance shall the function fail with a timeout if the
  52. mutex can be locked immediately. The validity of the
  53. .IR abstime
  54. parameter need not be checked if the mutex can be locked immediately.
  55. .P
  56. As a consequence of the priority inheritance rules (for mutexes
  57. initialized with the PRIO_INHERIT protocol), if a timed mutex wait is
  58. terminated
  59. because its timeout expires, the priority of the owner of the mutex
  60. shall be adjusted as necessary to reflect the fact that this thread is
  61. no longer among the threads waiting for the mutex.
  62. .P
  63. If
  64. .IR mutex
  65. is a robust mutex and the process containing the owning thread
  66. terminated while holding the mutex lock, a call to
  67. \fIpthread_mutex_timedlock\fR()
  68. shall return the error value
  69. .BR [EOWNERDEAD] .
  70. If
  71. .IR mutex
  72. is a robust mutex and the owning thread terminated while holding the
  73. mutex lock, a call to
  74. \fIpthread_mutex_timedlock\fR()
  75. may return the error value
  76. .BR [EOWNERDEAD]
  77. even if the process in which the owning thread resides has not
  78. terminated. In these cases, the mutex is locked by the thread but the
  79. state it protects is marked as inconsistent. The application should
  80. ensure that the state is made consistent for reuse and when that is
  81. complete call
  82. \fIpthread_mutex_consistent\fR().
  83. If the application is unable to recover the state, it should unlock the
  84. mutex without a prior call to
  85. \fIpthread_mutex_consistent\fR(),
  86. after which the mutex is marked permanently unusable.
  87. .P
  88. If
  89. .IR mutex
  90. does not refer to an initialized mutex object, the behavior is undefined.
  91. .SH "RETURN VALUE"
  92. If successful, the
  93. \fIpthread_mutex_timedlock\fR()
  94. function shall return zero; otherwise, an error number shall be
  95. returned to indicate the error.
  96. .SH ERRORS
  97. The
  98. \fIpthread_mutex_timedlock\fR()
  99. function shall fail if:
  100. .TP
  101. .BR EAGAIN
  102. The mutex could not be acquired because the maximum number of recursive
  103. locks for
  104. .IR mutex
  105. has been exceeded.
  106. .TP
  107. .BR EDEADLK
  108. The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current
  109. thread already owns the mutex.
  110. .TP
  111. .BR EINVAL
  112. The mutex was created with the protocol attribute having the value
  113. PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than
  114. the mutex' current priority ceiling.
  115. .TP
  116. .BR EINVAL
  117. The process or thread would have blocked, and the
  118. .IR abstime
  119. parameter specified a nanoseconds field value less than zero or greater
  120. than or equal to 1\|000 million.
  121. .TP
  122. .BR ENOTRECOVERABLE
  123. .br
  124. The state protected by the mutex is not recoverable.
  125. .TP
  126. .BR EOWNERDEAD
  127. .br
  128. The mutex is a robust mutex and the process containing the previous
  129. owning thread terminated while holding the mutex lock. The mutex lock
  130. shall be acquired by the calling thread and it is up to the new owner
  131. to make the state consistent.
  132. .TP
  133. .BR ETIMEDOUT
  134. The mutex could not be locked before the specified timeout expired.
  135. .P
  136. The
  137. \fIpthread_mutex_timedlock\fR()
  138. function may fail if:
  139. .TP
  140. .BR EDEADLK
  141. A deadlock condition was detected.
  142. .TP
  143. .BR EOWNERDEAD
  144. .br
  145. The mutex is a robust mutex and the previous owning thread terminated
  146. while holding the mutex lock. The mutex lock shall be acquired by the
  147. calling thread and it is up to the new owner to make the state consistent.
  148. .P
  149. This function shall not return an error code of
  150. .BR [EINTR] .
  151. .LP
  152. .IR "The following sections are informative."
  153. .SH EXAMPLES
  154. None.
  155. .SH "APPLICATION USAGE"
  156. Applications that have assumed that non-zero return values are errors
  157. will need updating for use with robust mutexes, since a valid return
  158. for a thread acquiring a mutex which is protecting a currently
  159. inconsistent state is
  160. .BR [EOWNERDEAD] .
  161. Applications that do not check the error returns, due to ruling out the
  162. possibility of such errors arising, should not use robust mutexes. If
  163. an application is supposed to work with normal and robust mutexes, it
  164. should check all return values for error conditions and if necessary
  165. take appropriate action.
  166. .SH RATIONALE
  167. Refer to
  168. .IR "\fIpthread_mutex_lock\fR\^(\|)".
  169. .SH "FUTURE DIRECTIONS"
  170. None.
  171. .SH "SEE ALSO"
  172. .IR "\fIpthread_mutex_destroy\fR\^(\|)",
  173. .IR "\fIpthread_mutex_lock\fR\^(\|)",
  174. .IR "\fItime\fR\^(\|)"
  175. .P
  176. The Base Definitions volume of POSIX.1\(hy2017,
  177. .IR "Section 4.12" ", " "Memory Synchronization",
  178. .IR "\fB<pthread.h>\fP",
  179. .IR "\fB<time.h>\fP"
  180. .\"
  181. .SH COPYRIGHT
  182. Portions of this text are reprinted and reproduced in electronic form
  183. from IEEE Std 1003.1-2017, Standard for Information Technology
  184. -- Portable Operating System Interface (POSIX), The Open Group Base
  185. Specifications Issue 7, 2018 Edition,
  186. Copyright (C) 2018 by the Institute of
  187. Electrical and Electronics Engineers, Inc and The Open Group.
  188. In the event of any discrepancy between this version and the original IEEE and
  189. The Open Group Standard, the original IEEE and The Open Group Standard
  190. is the referee document. The original Standard can be obtained online at
  191. http://www.opengroup.org/unix/online.html .
  192. .PP
  193. Any typographical or formatting errors that appear
  194. in this page are most likely
  195. to have been introduced during the conversion of the source files to
  196. man page format. To report such errors, see
  197. https://www.kernel.org/doc/man-pages/reporting_bugs.html .