1PTHREAD_CREATE(3P) POSIX Programmer's Manual PTHREAD_CREATE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 pthread_create — thread creation
14
16 #include <pthread.h>
17 int pthread_create(pthread_t *restrict thread,
19 const pthread_attr_t *restrict attr,
20 void *(*start_routine)(void*), void *restrict arg);
21
23 The pthread_create() function shall create a new thread, with
24 attributes specified by attr, within a process. If attr is NULL, the
25 default attributes shall be used. If the attributes specified by attr
26 are modified later, the thread's attributes shall not be affected.
27 Upon successful completion, pthread_create() shall store the ID of the
28 created thread in the location referenced by thread.
29 The thread is created executing start_routine with arg as its sole
31 argument. If the start_routine returns, the effect shall be as if there
32 was an implicit call to pthread_exit() using the return value of
33 start_routine as the exit status. Note that the thread in which main()
34 was originally invoked differs from this. When it returns from main(),
35 the effect shall be as if there was an implicit call to exit() using
36 the return value of main() as the exit status.
37 The signal state of the new thread shall be initialized as follows:
39 * The signal mask shall be inherited from the creating thread.
41 * The set of signals pending for the new thread shall be empty.
43 The thread-local current locale and the alternate stack shall not be
45 inherited.
46 The floating-point environment shall be inherited from the creating
48 thread.
49 If pthread_create() fails, no new thread is created and the contents of
51 the location referenced by thread are undefined.
52 If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-
54 time clock accessible, and the initial value of this clock shall be set
55 to zero.
56 The behavior is undefined if the value specified by the attr argument
58 to pthread_create() does not refer to an initialized thread attributes
59 object.
60
62 If successful, the pthread_create() function shall return zero; other‐
63 wise, an error number shall be returned to indicate the error.
64
66 The pthread_create() function shall fail if:
67 EAGAIN The system lacked the necessary resources to create another
69 thread, or the system-imposed limit on the total number of
70 threads in a process {PTHREAD_THREADS_MAX} would be exceeded.
71 EPERM The caller does not have appropriate privileges to set the
73 required scheduling parameters or scheduling policy.
74 The pthread_create() function shall not return an error code of
76 [EINTR].
77 The following sections are informative.
79
81 None.
82
84 There is no requirement on the implementation that the ID of the cre‐
85 ated thread be available before the newly created thread starts execut‐
86 ing. The calling thread can obtain the ID of the created thread through
87 the return value of the pthread_create() function, and the newly cre‐
88 ated thread can obtain its ID by a call to pthread_self().
89
91 A suggested alternative to pthread_create() would be to define two sep‐
92 arate operations: create and start. Some applications would find such
93 behavior more natural. Ada, in particular, separates the ``creation''
94 of a task from its ``activation''.
95 Splitting the operation was rejected by the standard developers for
97 many reasons:
98 * The number of calls required to start a thread would increase from
100 one to two and thus place an additional burden on applications that
101 do not require the additional synchronization. The second call,
102 however, could be avoided by the additional complication of a
103 start-up state attribute.
104 * An extra state would be introduced: ``created but not started''.
106 This would require the standard to specify the behavior of the
107 thread operations when the target has not yet started executing.
108 * For those applications that require such behavior, it is possible
110 to simulate the two separate steps with the facilities that are
111 currently provided. The start_routine() can synchronize by waiting
112 on a condition variable that is signaled by the start operation.
113 An Ada implementor can choose to create the thread at either of two
115 points in the Ada program: when the task object is created, or when the
116 task is activated (generally at a ``begin''). If the first approach is
117 adopted, the start_routine() needs to wait on a condition variable to
118 receive the order to begin ``activation''. The second approach requires
119 no such condition variable or extra synchronization. In either
120 approach, a separate Ada task control block would need to be created
121 when the task object is created to hold rendezvous queues, and so on.
122 An extension of the preceding model would be to allow the state of the
124 thread to be modified between the create and start. This would allow
125 the thread attributes object to be eliminated. This has been rejected
126 because:
127 * All state in the thread attributes object has to be able to be set
129 for the thread. This would require the definition of functions to
130 modify thread attributes. There would be no reduction in the number
131 of function calls required to set up the thread. In fact, for an
132 application that creates all threads using identical attributes,
133 the number of function calls required to set up the threads would
134 be dramatically increased. Use of a thread attributes object per‐
135 mits the application to make one set of attribute setting function
136 calls. Otherwise, the set of attribute setting function calls
137 needs to be made for each thread creation.
138 * Depending on the implementation architecture, functions to set
140 thread state would require kernel calls, or for other implementa‐
141 tion reasons would not be able to be implemented as macros, thereby
142 increasing the cost of thread creation.
143 * The ability for applications to segregate threads by class would be
145 lost.
146 Another suggested alternative uses a model similar to that for process
148 creation, such as ``thread fork''. The fork semantics would provide
149 more flexibility and the ``create'' function can be implemented simply
150 by doing a thread fork followed immediately by a call to the desired
151 ``start routine'' for the thread. This alternative has these problems:
152 * For many implementations, the entire stack of the calling thread
154 would need to be duplicated, since in many architectures there is
155 no way to determine the size of the calling frame.
156 * Efficiency is reduced since at least some part of the stack has to
158 be copied, even though in most cases the thread never needs the
159 copied context, since it merely calls the desired start routine.
160 If an implementation detects that the value specified by the attr argu‐
162 ment to pthread_create() does not refer to an initialized thread
163 attributes object, it is recommended that the function should fail and
164 report an [EINVAL] error.
165
167 None.
168
170 fork(), pthread_exit(), pthread_join()
171 The Base Definitions volume of POSIX.1‐2008, Section 4.11, Memory Syn‐
173 chronization, <pthread.h>
174
176 Portions of this text are reprinted and reproduced in electronic form
177 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
178 -- Portable Operating System Interface (POSIX), The Open Group Base
179 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
180 cal and Electronics Engineers, Inc and The Open Group. (This is
181 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
182 event of any discrepancy between this version and the original IEEE and
183 The Open Group Standard, the original IEEE and The Open Group Standard
184 is the referee document. The original Standard can be obtained online
185 at http://www.unix.org/online.html .
186 Any typographical or formatting errors that appear in this page are
188 most likely to have been introduced during the conversion of the source
189 files to man page format. To report such errors, see https://www.ker‐
190 nel.org/doc/man-pages/reporting_bugs.html .
191IEEE/The Open Group 2013 PTHREAD_CREATE(3P)