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_timedwrlock.3p (4794B)

    

  1. '\" et
  2. .TH PTHREAD_RWLOCK_TIMEDWRLOCK "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_timedwrlock
  12. \(em lock a read-write lock for writing
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. #include <time.h>
  18. .P
  19. int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict \fIrwlock\fP,
  20.     const struct timespec *restrict \fIabstime\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_rwlock_timedwrlock\fR()
  25. function shall apply a write lock to the read-write lock referenced by
  26. .IR rwlock
  27. as in the
  28. \fIpthread_rwlock_wrlock\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_timedwrlock\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 the read-write lock. The results are undefined if this function
  60. is called with an uninitialized read-write lock.
  61. .SH "RETURN VALUE"
  62. The
  63. \fIpthread_rwlock_timedwrlock\fR()
  64. function shall return zero if the lock for writing on the read-write
  65. lock object referenced by
  66. .IR rwlock
  67. is acquired. Otherwise, an error number shall be returned to indicate
  68. the error.
  69. .SH ERRORS
  70. The
  71. \fIpthread_rwlock_timedwrlock\fR()
  72. function shall fail if:
  73. .TP
  74. .BR ETIMEDOUT
  75. The lock could not be acquired before the specified timeout expired.
  76. .P
  77. The
  78. \fIpthread_rwlock_timedwrlock\fR()
  79. function may fail if:
  80. .TP
  81. .BR EDEADLK
  82. A deadlock condition was detected or the calling thread already holds the
  83. .IR rwlock .
  84. .TP
  85. .BR EINVAL
  86. The
  87. .IR abstime
  88. nanosecond value is less than zero or greater than or equal to 1\|000
  89. million.
  90. .P
  91. This function shall not return an error code of
  92. .BR [EINTR] .
  93. .LP
  94. .IR "The following sections are informative."
  95. .SH EXAMPLES
  96. None.
  97. .SH "APPLICATION USAGE"
  98. Applications using this function may be subject to priority inversion,
  99. as discussed in the Base Definitions volume of POSIX.1\(hy2017,
  100. .IR "Section 3.291" ", " "Priority Inversion".
  101. .SH RATIONALE
  102. If an implementation detects that the value specified by the
  103. .IR rwlock
  104. argument to
  105. \fIpthread_rwlock_timedwrlock\fR()
  106. does not refer to an initialized read-write lock object, it is
  107. recommended that the function should fail and report an
  108. .BR [EINVAL] 
  109. error.
  110. .SH "FUTURE DIRECTIONS"
  111. None.
  112. .SH "SEE ALSO"
  113. .ad l
  114. .IR "\fIpthread_rwlock_destroy\fR\^(\|)",
  115. .IR "\fIpthread_rwlock_rdlock\fR\^(\|)",
  116. .IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)",
  117. .IR "\fIpthread_rwlock_trywrlock\fR\^(\|)",
  118. .IR "\fIpthread_rwlock_unlock\fR\^(\|)"
  119. .ad b
  120. .P
  121. The Base Definitions volume of POSIX.1\(hy2017,
  122. .IR "Section 3.291" ", " "Priority Inversion",
  123. .IR "Section 4.12" ", " "Memory Synchronization",
  124. .IR "\fB<pthread.h>\fP",
  125. .IR "\fB<time.h>\fP"
  126. .\"
  127. .SH COPYRIGHT
  128. Portions of this text are reprinted and reproduced in electronic form
  129. from IEEE Std 1003.1-2017, Standard for Information Technology
  130. -- Portable Operating System Interface (POSIX), The Open Group Base
  131. Specifications Issue 7, 2018 Edition,
  132. Copyright (C) 2018 by the Institute of
  133. Electrical and Electronics Engineers, Inc and The Open Group.
  134. In the event of any discrepancy between this version and the original IEEE and
  135. The Open Group Standard, the original IEEE and The Open Group Standard
  136. is the referee document. The original Standard can be obtained online at
  137. http://www.opengroup.org/unix/online.html .
  138. .PP
  139. Any typographical or formatting errors that appear
  140. in this page are most likely
  141. to have been introduced during the conversion of the source files to
  142. man page format. To report such errors, see
  143. https://www.kernel.org/doc/man-pages/reporting_bugs.html .