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_create.3p (8493B)


  1. '\" et
  2. .TH PTHREAD_CREATE "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_create
  12. \(em thread creation
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_create(pthread_t *restrict \fIthread\fP,
  19. const pthread_attr_t *restrict \fIattr\fP,
  20. void *(*\fIstart_routine\fP)(void*), void *restrict \fIarg\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_create\fR()
  25. function shall create a new thread, with attributes specified by
  26. .IR attr ,
  27. within a process. If
  28. .IR attr
  29. is NULL, the default attributes shall be used. If the attributes
  30. specified by
  31. .IR attr
  32. are modified later, the thread's attributes shall not be affected.
  33. Upon successful completion,
  34. \fIpthread_create\fR()
  35. shall store the ID of the created thread in the location referenced by
  36. .IR thread .
  37. .P
  38. The thread is created executing
  39. .IR start_routine
  40. with
  41. .IR arg
  42. as its sole argument. If the
  43. .IR start_routine
  44. returns, the effect shall be as if there was an implicit call to
  45. \fIpthread_exit\fR()
  46. using the return value of
  47. .IR start_routine
  48. as the exit status. Note that the thread in which
  49. \fImain\fR()
  50. was originally invoked differs from this. When it returns from
  51. \fImain\fR(),
  52. the effect shall be as if there was an implicit call to
  53. \fIexit\fR()
  54. using the return value of
  55. \fImain\fR()
  56. as the exit status.
  57. .P
  58. The signal state of the new thread shall be initialized as follows:
  59. .IP " *" 4
  60. The signal mask shall be inherited from the creating thread.
  61. .IP " *" 4
  62. The set of signals pending for the new thread shall be empty.
  63. .P
  64. The thread-local current locale
  65. and the alternate stack
  66. shall not be inherited.
  67. .P
  68. The floating-point environment shall be inherited from the creating
  69. thread.
  70. .P
  71. If
  72. \fIpthread_create\fR()
  73. fails, no new thread is created and the contents of the location
  74. referenced by
  75. .IR thread
  76. are undefined.
  77. .P
  78. If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a
  79. CPU-time clock accessible, and the initial value of this clock shall
  80. be set to zero.
  81. .P
  82. The behavior is undefined if the value specified by the
  83. .IR attr
  84. argument to
  85. \fIpthread_create\fR()
  86. does not refer to an initialized thread attributes object.
  87. .SH "RETURN VALUE"
  88. If successful, the
  89. \fIpthread_create\fR()
  90. function shall return zero; otherwise, an error number shall be
  91. returned to indicate the error.
  92. .SH ERRORS
  93. The
  94. \fIpthread_create\fR()
  95. function shall fail if:
  96. .TP
  97. .BR EAGAIN
  98. The system lacked the necessary resources to create another thread, or
  99. the system-imposed limit on the total number of threads in a process
  100. {PTHREAD_THREADS_MAX}
  101. would be exceeded.
  102. .TP
  103. .BR EPERM
  104. The caller does not have appropriate privileges to set the required
  105. scheduling parameters or scheduling policy.
  106. .P
  107. The
  108. \fIpthread_create\fR()
  109. function shall not return an error code of
  110. .BR [EINTR] .
  111. .LP
  112. .IR "The following sections are informative."
  113. .SH EXAMPLES
  114. None.
  115. .SH "APPLICATION USAGE"
  116. There is no requirement on the implementation that the ID of the
  117. created thread be available before the newly created thread starts
  118. executing. The calling thread can obtain the ID of the created thread
  119. through the
  120. .IR thread
  121. argument of the
  122. \fIpthread_create\fR()
  123. function, and the newly created thread can obtain its ID by a call to
  124. \fIpthread_self\fR().
  125. .SH RATIONALE
  126. A suggested alternative to
  127. \fIpthread_create\fR()
  128. would be to define two separate operations: create and start. Some
  129. applications would find such behavior more natural. Ada, in
  130. particular, separates the ``creation'' of a task from its
  131. ``activation''.
  132. .P
  133. Splitting the operation was rejected by the standard developers for
  134. many reasons:
  135. .IP " *" 4
  136. The number of calls required to start a thread would increase from one
  137. to two and thus place an additional burden on applications that do not
  138. require the additional synchronization. The second call, however,
  139. could be avoided by the additional complication of a start-up state
  140. attribute.
  141. .IP " *" 4
  142. An extra state would be introduced: ``created but not started''. This
  143. would require the standard to specify the behavior of the thread
  144. operations when the target has not yet started executing.
  145. .IP " *" 4
  146. For those applications that require such behavior, it is possible to
  147. simulate the two separate steps with the facilities that are currently
  148. provided. The
  149. \fIstart_routine\fR()
  150. can synchronize by waiting on a condition variable that is signaled by
  151. the start operation.
  152. .P
  153. An Ada implementor can choose to create the thread at either of two
  154. points in the Ada program: when the task object is created, or when
  155. the task is activated (generally at a ``begin''). If the first
  156. approach is adopted, the
  157. \fIstart_routine\fR()
  158. needs to wait on a condition variable to receive the order to begin
  159. ``activation''. The second approach requires no such condition
  160. variable or extra synchronization. In either approach, a separate Ada
  161. task control block would need to be created when the task object is
  162. created to hold rendezvous queues, and so on.
  163. .P
  164. An extension of the preceding model would be to allow the state of the
  165. thread to be modified between the create and start. This would allow
  166. the thread attributes object to be eliminated. This has been rejected
  167. because:
  168. .IP " *" 4
  169. All state in the thread attributes object has to be able to be set for
  170. the thread. This would require the definition of functions to modify
  171. thread attributes. There would be no reduction in the number of
  172. function calls required to set up the thread. In fact, for an
  173. application that creates all threads using identical attributes, the
  174. number of function calls required to set up the threads would be
  175. dramatically increased. Use of a thread attributes object permits the
  176. application to make one set of attribute setting function calls.
  177. Otherwise, the set of attribute setting function calls needs to be made
  178. for each thread creation.
  179. .IP " *" 4
  180. Depending on the implementation architecture, functions to set thread
  181. state would require kernel calls, or for other implementation reasons
  182. would not be able to be implemented as macros, thereby increasing the
  183. cost of thread creation.
  184. .IP " *" 4
  185. The ability for applications to segregate threads by class would be
  186. lost.
  187. .P
  188. Another suggested alternative uses a model similar to that for process
  189. creation, such as ``thread fork''. The fork semantics would provide
  190. more flexibility and the ``create'' function can be implemented simply
  191. by doing a thread fork followed immediately by a call to the desired
  192. ``start routine'' for the thread. This alternative has these
  193. problems:
  194. .IP " *" 4
  195. For many implementations, the entire stack of the calling thread would
  196. need to be duplicated, since in many architectures there is no way to
  197. determine the size of the calling frame.
  198. .IP " *" 4
  199. Efficiency is reduced since at least some part of the stack has to be
  200. copied, even though in most cases the thread never needs the copied
  201. context, since it merely calls the desired start routine.
  202. .P
  203. If an implementation detects that the value specified by the
  204. .IR attr
  205. argument to
  206. \fIpthread_create\fR()
  207. does not refer to an initialized thread attributes object, it is
  208. recommended that the function should fail and report an
  209. .BR [EINVAL]
  210. error.
  211. .SH "FUTURE DIRECTIONS"
  212. None.
  213. .SH "SEE ALSO"
  214. .IR "\fIfork\fR\^(\|)",
  215. .IR "\fIpthread_exit\fR\^(\|)",
  216. .IR "\fIpthread_join\fR\^(\|)"
  217. .P
  218. The Base Definitions volume of POSIX.1\(hy2017,
  219. .IR "Section 4.12" ", " "Memory Synchronization",
  220. .IR "\fB<pthread.h>\fP"
  221. .\"
  222. .SH COPYRIGHT
  223. Portions of this text are reprinted and reproduced in electronic form
  224. from IEEE Std 1003.1-2017, Standard for Information Technology
  225. -- Portable Operating System Interface (POSIX), The Open Group Base
  226. Specifications Issue 7, 2018 Edition,
  227. Copyright (C) 2018 by the Institute of
  228. Electrical and Electronics Engineers, Inc and The Open Group.
  229. In the event of any discrepancy between this version and the original IEEE and
  230. The Open Group Standard, the original IEEE and The Open Group Standard
  231. is the referee document. The original Standard can be obtained online at
  232. http://www.opengroup.org/unix/online.html .
  233. .PP
  234. Any typographical or formatting errors that appear
  235. in this page are most likely
  236. to have been introduced during the conversion of the source files to
  237. man page format. To report such errors, see
  238. https://www.kernel.org/doc/man-pages/reporting_bugs.html .