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_timedrdlock.3p (4933B)

    

  1. '\" et
  2. .TH PTHREAD_RWLOCK_TIMEDRDLOCK "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_timedrdlock
  12. \(em lock a read-write lock for reading
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. #include <time.h>
  18. .P
  19. int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict \fIrwlock\fP,
  20.     const struct timespec *restrict \fIabstime\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_rwlock_timedrdlock\fR()
  25. function shall apply a read lock to the read-write lock referenced by
  26. .IR rwlock
  27. as in the
  28. \fIpthread_rwlock_rdlock\fR()
  29. function. However, if the lock cannot be acquired without waiting for
  30. other threads to unlock the lock, this wait shall be terminated when
  31. the specified timeout expires. The timeout shall expire when the
  32. absolute time specified by
  33. .IR abstime
  34. passes, as measured by the clock on which timeouts are based (that is,
  35. when the value of that clock equals or exceeds
  36. .IR abstime ),
  37. or if the absolute time specified by
  38. .IR abstime
  39. has already been passed at the time of the call.
  40. .P
  41. The timeout shall be based on the CLOCK_REALTIME clock.
  42. The resolution of the timeout shall be the resolution of the
  43. CLOCK_REALTIME clock. The
  44. .BR timespec
  45. data type is defined in the
  46. .IR <time.h> 
  47. header. Under no circumstances shall the function fail with a timeout
  48. if the lock can be acquired immediately. The validity of the
  49. .IR abstime
  50. parameter need not be checked if the lock can be immediately acquired.
  51. .P
  52. If a signal that causes a signal handler to be executed is delivered to
  53. a thread blocked on a read-write lock via a call to
  54. \fIpthread_rwlock_timedrdlock\fR(),
  55. upon return from the signal handler the thread shall resume waiting for
  56. the lock as if it was not interrupted.
  57. .P
  58. The calling thread may deadlock if at the time the call is made it
  59. holds a write lock on
  60. .IR rwlock .
  61. The results are undefined if this function is called with an
  62. uninitialized read-write lock.
  63. .SH "RETURN VALUE"
  64. The
  65. \fIpthread_rwlock_timedrdlock\fR()
  66. function shall return zero if the lock for reading on the read-write
  67. lock object referenced by
  68. .IR rwlock
  69. is acquired. Otherwise, an error number shall be returned to indicate
  70. the error.
  71. .SH ERRORS
  72. The
  73. \fIpthread_rwlock_timedrdlock\fR()
  74. function shall fail if:
  75. .TP
  76. .BR ETIMEDOUT
  77. The lock could not be acquired before the specified timeout expired.
  78. .P
  79. The
  80. \fIpthread_rwlock_timedrdlock\fR()
  81. function may fail if:
  82. .TP
  83. .BR EAGAIN
  84. The read lock could not be acquired because the maximum number of read
  85. locks for lock would be exceeded.
  86. .TP
  87. .BR EDEADLK
  88. A deadlock condition was detected or the calling thread already holds a
  89. write lock on
  90. .IR rwlock .
  91. .TP
  92. .BR EINVAL
  93. The
  94. .IR abstime
  95. nanosecond value is less than zero or greater than or equal to 1\|000
  96. million.
  97. .P
  98. This function shall not return an error code of
  99. .BR [EINTR] .
  100. .LP
  101. .IR "The following sections are informative."
  102. .SH EXAMPLES
  103. None.
  104. .SH "APPLICATION USAGE"
  105. Applications using this function may be subject to priority inversion,
  106. as discussed in the Base Definitions volume of POSIX.1\(hy2017,
  107. .IR "Section 3.291" ", " "Priority Inversion".
  108. .SH RATIONALE
  109. If an implementation detects that the value specified by the
  110. .IR rwlock
  111. argument to
  112. \fIpthread_rwlock_timedrdlock\fR()
  113. does not refer to an initialized read-write lock object, it is
  114. recommended that the function should fail and report an
  115. .BR [EINVAL] 
  116. error.
  117. .SH "FUTURE DIRECTIONS"
  118. None.
  119. .SH "SEE ALSO"
  120. .ad l
  121. .IR "\fIpthread_rwlock_destroy\fR\^(\|)",
  122. .IR "\fIpthread_rwlock_rdlock\fR\^(\|)",
  123. .IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)",
  124. .IR "\fIpthread_rwlock_trywrlock\fR\^(\|)",
  125. .IR "\fIpthread_rwlock_unlock\fR\^(\|)"
  126. .ad b
  127. .P
  128. The Base Definitions volume of POSIX.1\(hy2017,
  129. .IR "Section 3.291" ", " "Priority Inversion",
  130. .IR "Section 4.12" ", " "Memory Synchronization",
  131. .IR "\fB<pthread.h>\fP",
  132. .IR "\fB<time.h>\fP"
  133. .\"
  134. .SH COPYRIGHT
  135. Portions of this text are reprinted and reproduced in electronic form
  136. from IEEE Std 1003.1-2017, Standard for Information Technology
  137. -- Portable Operating System Interface (POSIX), The Open Group Base
  138. Specifications Issue 7, 2018 Edition,
  139. Copyright (C) 2018 by the Institute of
  140. Electrical and Electronics Engineers, Inc and The Open Group.
  141. In the event of any discrepancy between this version and the original IEEE and
  142. The Open Group Standard, the original IEEE and The Open Group Standard
  143. is the referee document. The original Standard can be obtained online at
  144. http://www.opengroup.org/unix/online.html .
  145. .PP
  146. Any typographical or formatting errors that appear
  147. in this page are most likely
  148. to have been introduced during the conversion of the source files to
  149. man page format. To report such errors, see
  150. https://www.kernel.org/doc/man-pages/reporting_bugs.html .