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_rwlock_rdlock.3p (6330B)


  1. '\" et
  2. .TH PTHREAD_RWLOCK_RDLOCK "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_rwlock_rdlock,
  12. pthread_rwlock_tryrdlock
  13. \(em lock a read-write lock object for reading
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_rwlock_rdlock(pthread_rwlock_t *\fIrwlock\fP);
  20. int pthread_rwlock_tryrdlock(pthread_rwlock_t *\fIrwlock\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_rwlock_rdlock\fR()
  25. function shall apply a read lock to the read-write lock referenced by
  26. .IR rwlock .
  27. The calling thread acquires the read lock if a writer does not hold the
  28. lock and there are no writers blocked on the lock.
  29. .P
  30. If the Thread Execution Scheduling option is supported, and the threads
  31. involved in the lock are executing with the scheduling policies
  32. SCHED_FIFO or SCHED_RR, the calling thread shall
  33. not acquire the lock if a writer holds the lock or if writers of higher
  34. or equal priority are blocked on the lock; otherwise, the calling
  35. thread shall acquire the lock.
  36. .P
  37. If the Thread Execution Scheduling option is supported, and the
  38. threads involved in the lock are executing with the SCHED_SPORADIC
  39. scheduling policy, the calling thread shall not acquire the lock if a
  40. writer holds the lock or if writers of higher or equal priority are
  41. blocked on the lock; otherwise, the calling thread shall acquire the
  42. lock.
  43. .P
  44. If the Thread Execution Scheduling option is not supported, it is
  45. implementation-defined whether the calling thread acquires the lock
  46. when a writer does not hold the lock and there are writers blocked on
  47. the lock. If a writer holds the lock, the calling thread shall not
  48. acquire the read lock. If the read lock is not acquired, the calling
  49. thread shall block until it can acquire the lock. The calling thread
  50. may deadlock if at the time the call is made it holds a write lock.
  51. .P
  52. A thread may hold multiple concurrent read locks on
  53. .IR rwlock
  54. (that is, successfully call the
  55. \fIpthread_rwlock_rdlock\fR()
  56. function
  57. .IR n
  58. times). If so, the application shall ensure that the thread performs
  59. matching unlocks (that is, it calls the
  60. \fIpthread_rwlock_unlock\fR()
  61. function
  62. .IR n
  63. times).
  64. .P
  65. The maximum number of simultaneous read locks that an implementation
  66. guarantees can be applied to a read-write lock shall be
  67. implementation-defined. The
  68. \fIpthread_rwlock_rdlock\fR()
  69. function may fail if this maximum would be exceeded.
  70. .P
  71. The
  72. \fIpthread_rwlock_tryrdlock\fR()
  73. function shall apply a read lock as in the
  74. \fIpthread_rwlock_rdlock\fR()
  75. function, with the exception that the function shall fail if the
  76. equivalent
  77. \fIpthread_rwlock_rdlock\fR()
  78. call would have blocked the calling thread. In no case shall the
  79. \fIpthread_rwlock_tryrdlock\fR()
  80. function ever block; it always either acquires the lock or fails and
  81. returns immediately.
  82. .P
  83. Results are undefined if any of these functions are called with an
  84. uninitialized read-write lock.
  85. .P
  86. If a signal is delivered to a thread waiting for a read-write lock for
  87. reading, upon return from the signal handler the thread resumes waiting
  88. for the read-write lock for reading as if it was not interrupted.
  89. .SH "RETURN VALUE"
  90. If successful, the
  91. \fIpthread_rwlock_rdlock\fR()
  92. function shall return zero; otherwise, an error number shall be
  93. returned to indicate the error.
  94. .P
  95. The
  96. \fIpthread_rwlock_tryrdlock\fR()
  97. function shall return zero if the lock for reading on the read-write
  98. lock object referenced by
  99. .IR rwlock
  100. is acquired. Otherwise, an error number shall be returned to indicate
  101. the error.
  102. .SH ERRORS
  103. The
  104. \fIpthread_rwlock_tryrdlock\fR()
  105. function shall fail if:
  106. .TP
  107. .BR EBUSY
  108. The read-write lock could not be acquired for reading because a writer
  109. holds the lock or a writer with the appropriate priority was blocked on it.
  110. .P
  111. The
  112. \fIpthread_rwlock_rdlock\fR()
  113. and
  114. \fIpthread_rwlock_tryrdlock\fR()
  115. functions may fail if:
  116. .TP
  117. .BR EAGAIN
  118. The read lock could not be acquired because the maximum number of read
  119. locks for
  120. .IR rwlock
  121. has been exceeded.
  122. .P
  123. The
  124. \fIpthread_rwlock_rdlock\fR()
  125. function may fail if:
  126. .TP
  127. .BR EDEADLK
  128. A deadlock condition was detected or the current thread already owns
  129. the read-write lock for writing.
  130. .P
  131. These functions shall not return an error code of
  132. .BR [EINTR] .
  133. .LP
  134. .IR "The following sections are informative."
  135. .SH EXAMPLES
  136. None.
  137. .SH "APPLICATION USAGE"
  138. Applications using these functions may be subject to priority inversion,
  139. as discussed in the Base Definitions volume of POSIX.1\(hy2017,
  140. .IR "Section 3.291" ", " "Priority Inversion".
  141. .SH RATIONALE
  142. If an implementation detects that the value specified by the
  143. .IR rwlock
  144. argument to
  145. \fIpthread_rwlock_rdlock\fR()
  146. or
  147. \fIpthread_rwlock_tryrdlock\fR()
  148. does not refer to an initialized read-write lock object, it is
  149. recommended that the function should fail and report an
  150. .BR [EINVAL]
  151. error.
  152. .SH "FUTURE DIRECTIONS"
  153. None.
  154. .SH "SEE ALSO"
  155. .ad l
  156. .IR "\fIpthread_rwlock_destroy\fR\^(\|)",
  157. .IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)",
  158. .IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)",
  159. .IR "\fIpthread_rwlock_trywrlock\fR\^(\|)",
  160. .IR "\fIpthread_rwlock_unlock\fR\^(\|)"
  161. .ad b
  162. .P
  163. The Base Definitions volume of POSIX.1\(hy2017,
  164. .IR "Section 3.291" ", " "Priority Inversion",
  165. .IR "Section 4.12" ", " "Memory Synchronization",
  166. .IR "\fB<pthread.h>\fP"
  167. .\"
  168. .SH COPYRIGHT
  169. Portions of this text are reprinted and reproduced in electronic form
  170. from IEEE Std 1003.1-2017, Standard for Information Technology
  171. -- Portable Operating System Interface (POSIX), The Open Group Base
  172. Specifications Issue 7, 2018 Edition,
  173. Copyright (C) 2018 by the Institute of
  174. Electrical and Electronics Engineers, Inc and The Open Group.
  175. In the event of any discrepancy between this version and the original IEEE and
  176. The Open Group Standard, the original IEEE and The Open Group Standard
  177. is the referee document. The original Standard can be obtained online at
  178. http://www.opengroup.org/unix/online.html .
  179. .PP
  180. Any typographical or formatting errors that appear
  181. in this page are most likely
  182. to have been introduced during the conversion of the source files to
  183. man page format. To report such errors, see
  184. https://www.kernel.org/doc/man-pages/reporting_bugs.html .