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_once.3p (5320B)


  1. '\" et
  2. .TH PTHREAD_ONCE "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_once
  12. \(em dynamic package initialization
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_once(pthread_once_t *\fIonce_control\fP,
  19. void (*\fIinit_routine\fP)(void));
  20. pthread_once_t \fIonce_control\fP = PTHREAD_ONCE_INIT;
  21. .fi
  22. .SH DESCRIPTION
  23. The first call to
  24. \fIpthread_once\fR()
  25. by any thread in a process, with a given
  26. .IR once_control ,
  27. shall call the
  28. .IR init_routine
  29. with no arguments. Subsequent calls of
  30. \fIpthread_once\fR()
  31. with the same
  32. .IR once_control
  33. shall not call the
  34. .IR init_routine .
  35. On return from
  36. \fIpthread_once\fR(),
  37. .IR init_routine
  38. shall have completed. The
  39. .IR once_control
  40. parameter shall determine whether the associated initialization
  41. routine has been called.
  42. .P
  43. The
  44. \fIpthread_once\fR()
  45. function is not a cancellation point. However, if
  46. .IR init_routine
  47. is a cancellation point and is canceled, the effect on
  48. .IR once_control
  49. shall be as if
  50. \fIpthread_once\fR()
  51. was never called.
  52. .P
  53. If the call to
  54. .IR init_routine
  55. is terminated by a call to
  56. \fIlongjmp\fR(),
  57. \fI_longjmp\fR(),
  58. or
  59. \fIsiglongjmp\fR(),
  60. the behavior is undefined.
  61. .P
  62. The constant PTHREAD_ONCE_INIT is defined in the
  63. .IR <pthread.h>
  64. header.
  65. .P
  66. The behavior of
  67. \fIpthread_once\fR()
  68. is undefined if
  69. .IR once_control
  70. has automatic storage duration or is not initialized by
  71. PTHREAD_ONCE_INIT.
  72. .SH "RETURN VALUE"
  73. Upon successful completion,
  74. \fIpthread_once\fR()
  75. shall return zero; otherwise, an error number shall be returned to
  76. indicate the error.
  77. .SH ERRORS
  78. The
  79. \fIpthread_once\fR()
  80. function shall not return an error code of
  81. .BR [EINTR] .
  82. .LP
  83. .IR "The following sections are informative."
  84. .SH EXAMPLES
  85. None.
  86. .SH "APPLICATION USAGE"
  87. If
  88. .IR init_routine
  89. recursively calls
  90. \fIpthread_once\fR()
  91. with the same
  92. .IR once_control ,
  93. the recursive call will not call the specified
  94. .IR init_routine ,
  95. and thus the specified
  96. .IR init_routine
  97. will not complete, and thus the recursive call to
  98. \fIpthread_once\fR()
  99. will not return. Use of
  100. \fIlongjmp\fR(),
  101. \fI_longjmp\fR(),
  102. or
  103. \fIsiglongjmp\fR()
  104. within an
  105. .IR init_routine
  106. to jump to a point outside of
  107. .IR init_routine
  108. prevents
  109. .IR init_routine
  110. from returning.
  111. .SH RATIONALE
  112. Some C libraries are designed for dynamic initialization. That is, the
  113. global initialization for the library is performed when the first
  114. procedure in the library is called. In a single-threaded program, this
  115. is normally implemented using a static variable whose value is checked
  116. on entry to a routine, as follows:
  117. .sp
  118. .RS 4
  119. .nf
  120. static int random_is_initialized = 0;
  121. extern void initialize_random(void);
  122. .P
  123. int random_function()
  124. {
  125. if (random_is_initialized == 0) {
  126. initialize_random();
  127. random_is_initialized = 1;
  128. }
  129. ... /* Operations performed after initialization. */
  130. }
  131. .fi
  132. .P
  133. .RE
  134. .P
  135. To keep the same structure in a multi-threaded program, a new primitive
  136. is needed. Otherwise, library initialization has to be accomplished by
  137. an explicit call to a library-exported initialization function prior to
  138. any use of the library.
  139. .P
  140. For dynamic library initialization in a multi-threaded process, if an
  141. initialization flag is used the flag needs to be protected against
  142. modification by multiple threads simultaneously calling into the
  143. library. This can be done by using a mutex (initialized by assigning
  144. PTHREAD_MUTEX_INITIALIZER). However, the better solution is to use
  145. \fIpthread_once\fR()
  146. which is designed for exactly this purpose, as follows:
  147. .sp
  148. .RS 4
  149. .nf
  150. #include <pthread.h>
  151. static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT;
  152. extern void initialize_random(void);
  153. .P
  154. int random_function()
  155. {
  156. (void) pthread_once(&random_is_initialized, initialize_random);
  157. ... /* Operations performed after initialization. */
  158. }
  159. .fi
  160. .P
  161. .RE
  162. .P
  163. If an implementation detects that the value specified by the
  164. .IR once_control
  165. argument to
  166. \fIpthread_once\fR()
  167. does not refer to a
  168. .BR pthread_once_t
  169. object initialized by PTHREAD_ONCE_INIT, it is recommended that the
  170. function should fail and report an
  171. .BR [EINVAL]
  172. error.
  173. .SH "FUTURE DIRECTIONS"
  174. None.
  175. .SH "SEE ALSO"
  176. The Base Definitions volume of POSIX.1\(hy2017,
  177. .IR "\fB<pthread.h>\fP"
  178. .\"
  179. .SH COPYRIGHT
  180. Portions of this text are reprinted and reproduced in electronic form
  181. from IEEE Std 1003.1-2017, Standard for Information Technology
  182. -- Portable Operating System Interface (POSIX), The Open Group Base
  183. Specifications Issue 7, 2018 Edition,
  184. Copyright (C) 2018 by the Institute of
  185. Electrical and Electronics Engineers, Inc and The Open Group.
  186. In the event of any discrepancy between this version and the original IEEE and
  187. The Open Group Standard, the original IEEE and The Open Group Standard
  188. is the referee document. The original Standard can be obtained online at
  189. http://www.opengroup.org/unix/online.html .
  190. .PP
  191. Any typographical or formatting errors that appear
  192. in this page are most likely
  193. to have been introduced during the conversion of the source files to
  194. man page format. To report such errors, see
  195. https://www.kernel.org/doc/man-pages/reporting_bugs.html .