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_destroy.3p (5947B)


  1. '\" et
  2. .TH PTHREAD_RWLOCK_DESTROY "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_destroy,
  12. pthread_rwlock_init
  13. \(em destroy and initialize a read-write lock object
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_rwlock_destroy(pthread_rwlock_t *\fIrwlock\fP);
  20. int pthread_rwlock_init(pthread_rwlock_t *restrict \fIrwlock\fP,
  21. const pthread_rwlockattr_t *restrict \fIattr\fP);
  22. pthread_rwlock_t \fIrwlock\fR = PTHREAD_RWLOCK_INITIALIZER;
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIpthread_rwlock_destroy\fR()
  27. function shall destroy the read-write lock object referenced by
  28. .IR rwlock
  29. and release any resources used by the lock. The effect of subsequent
  30. use of the lock is undefined until the lock is reinitialized by
  31. another call to
  32. \fIpthread_rwlock_init\fR().
  33. An implementation may cause
  34. \fIpthread_rwlock_destroy\fR()
  35. to set the object referenced by
  36. .IR rwlock
  37. to an invalid value. Results are undefined if
  38. \fIpthread_rwlock_destroy\fR()
  39. is called when any thread holds
  40. .IR rwlock .
  41. Attempting to destroy an uninitialized read-write lock results in
  42. undefined behavior.
  43. .P
  44. The
  45. \fIpthread_rwlock_init\fR()
  46. function shall allocate any resources required to use the read-write
  47. lock referenced by
  48. .IR rwlock
  49. and initializes the lock to an unlocked state with attributes
  50. referenced by
  51. .IR attr .
  52. If
  53. .IR attr
  54. is NULL, the default read-write lock attributes shall be used; the
  55. effect is the same as passing the address of a default read-write lock
  56. attributes object. Once initialized, the lock can be used any number of
  57. times without being reinitialized. Results are undefined if
  58. \fIpthread_rwlock_init\fR()
  59. is called specifying an already initialized read-write lock. Results
  60. are undefined if a read-write lock is used without first being
  61. initialized.
  62. .P
  63. If the
  64. \fIpthread_rwlock_init\fR()
  65. function fails,
  66. .IR rwlock
  67. shall not be initialized and the contents of
  68. .IR rwlock
  69. are undefined.
  70. .P
  71. See
  72. .IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings"
  73. for further requirements.
  74. .P
  75. In cases where default read-write lock attributes are appropriate, the
  76. macro PTHREAD_RWLOCK_INITIALIZER can be used to initialize read-write
  77. locks. The effect shall be equivalent to dynamic initialization by a
  78. call to
  79. \fIpthread_rwlock_init\fR()
  80. with the
  81. .IR attr
  82. parameter specified as NULL, except that no error checks are performed.
  83. .P
  84. The behavior is undefined if the value specified by the
  85. .IR attr
  86. argument to
  87. \fIpthread_rwlock_init\fR()
  88. does not refer to an initialized read-write lock attributes object.
  89. .SH "RETURN VALUE"
  90. If successful, the
  91. \fIpthread_rwlock_destroy\fR()
  92. and
  93. \fIpthread_rwlock_init\fR()
  94. functions shall return zero; otherwise, an error number shall be
  95. returned to indicate the error.
  96. .SH ERRORS
  97. The
  98. \fIpthread_rwlock_init\fR()
  99. function shall fail if:
  100. .TP
  101. .BR EAGAIN
  102. The system lacked the necessary resources (other than memory) to
  103. initialize another read-write lock.
  104. .TP
  105. .BR ENOMEM
  106. Insufficient memory exists to initialize the read-write lock.
  107. .TP
  108. .BR EPERM
  109. The caller does not have the privilege to perform the operation.
  110. .P
  111. These functions shall not return an error code of
  112. .BR [EINTR] .
  113. .LP
  114. .IR "The following sections are informative."
  115. .SH EXAMPLES
  116. None.
  117. .SH "APPLICATION USAGE"
  118. Applications using these and related read-write lock functions may be
  119. subject to priority inversion, as discussed in the Base Definitions volume of POSIX.1\(hy2017,
  120. .IR "Section 3.291" ", " "Priority Inversion".
  121. .SH RATIONALE
  122. If an implementation detects that the value specified by the
  123. .IR rwlock
  124. argument to
  125. \fIpthread_rwlock_destroy\fR()
  126. does not refer to an initialized read-write lock object, it is
  127. recommended that the function should fail and report an
  128. .BR [EINVAL]
  129. error.
  130. .P
  131. If an implementation detects that the value specified by the
  132. .IR attr
  133. argument to
  134. \fIpthread_rwlock_init\fR()
  135. does not refer to an initialized read-write lock attributes object,
  136. it is recommended that the function should fail and report an
  137. .BR [EINVAL]
  138. error.
  139. .P
  140. If an implementation detects that the value specified by the
  141. .IR rwlock
  142. argument to
  143. \fIpthread_rwlock_destroy\fR()
  144. or
  145. \fIpthread_rwlock_init\fR()
  146. refers to a locked read-write lock object, or detects that the value
  147. specified by the
  148. .IR rwlock
  149. argument to
  150. \fIpthread_rwlock_init\fR()
  151. refers to an already initialized read-write lock object, it is recommended
  152. that the function should fail and report an
  153. .BR [EBUSY]
  154. error.
  155. .SH "FUTURE DIRECTIONS"
  156. None.
  157. .SH "SEE ALSO"
  158. .ad l
  159. .IR "\fIpthread_rwlock_rdlock\fR\^(\|)",
  160. .IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)",
  161. .IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)",
  162. .IR "\fIpthread_rwlock_trywrlock\fR\^(\|)",
  163. .IR "\fIpthread_rwlock_unlock\fR\^(\|)"
  164. .ad b
  165. .P
  166. The Base Definitions volume of POSIX.1\(hy2017,
  167. .IR "Section 3.291" ", " "Priority Inversion",
  168. .IR "\fB<pthread.h>\fP"
  169. .\"
  170. .SH COPYRIGHT
  171. Portions of this text are reprinted and reproduced in electronic form
  172. from IEEE Std 1003.1-2017, Standard for Information Technology
  173. -- Portable Operating System Interface (POSIX), The Open Group Base
  174. Specifications Issue 7, 2018 Edition,
  175. Copyright (C) 2018 by the Institute of
  176. Electrical and Electronics Engineers, Inc and The Open Group.
  177. In the event of any discrepancy between this version and the original IEEE and
  178. The Open Group Standard, the original IEEE and The Open Group Standard
  179. is the referee document. The original Standard can be obtained online at
  180. http://www.opengroup.org/unix/online.html .
  181. .PP
  182. Any typographical or formatting errors that appear
  183. in this page are most likely
  184. to have been introduced during the conversion of the source files to
  185. man page format. To report such errors, see
  186. https://www.kernel.org/doc/man-pages/reporting_bugs.html .