1PTHREAD_CREATE(3P)         POSIX Programmer's Manual        PTHREAD_CREATE(3P)
2
3
4

PROLOG

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

NAME

12       pthread_create — thread creation
13

SYNOPSIS

15       #include <pthread.h>
16
17       int pthread_create(pthread_t *restrict thread,
18           const pthread_attr_t *restrict attr,
19           void *(*start_routine)(void*), void *restrict arg);
20

DESCRIPTION

22       The  pthread_create()  function  shall  create  a  new   thread,   with
23       attributes  specified  by  attr, within a process. If attr is NULL, the
24       default attributes shall be used. If the attributes specified  by  attr
25       are  modified  later,  the  thread's  attributes shall not be affected.
26       Upon successful completion, pthread_create() shall store the ID of  the
27       created thread in the location referenced by thread.
28
29       The  thread  is  created  executing  start_routine with arg as its sole
30       argument. If the start_routine returns, the effect shall be as if there
31       was  an  implicit  call  to  pthread_exit()  using  the return value of
32       start_routine as the exit status. Note that the thread in which  main()
33       was  originally invoked differs from this. When it returns from main(),
34       the effect shall be as if there was an implicit call  to  exit()  using
35       the return value of main() as the exit status.
36
37       The signal state of the new thread shall be initialized as follows:
38
39        *  The signal mask shall be inherited from the creating thread.
40
41        *  The set of signals pending for the new thread shall be empty.
42
43       The  thread-local  current  locale and the alternate stack shall not be
44       inherited.
45
46       The floating-point environment shall be  inherited  from  the  creating
47       thread.
48
49       If pthread_create() fails, no new thread is created and the contents of
50       the location referenced by thread are undefined.
51
52       If _POSIX_THREAD_CPUTIME is defined, the new thread shall have  a  CPU-
53       time clock accessible, and the initial value of this clock shall be set
54       to zero.
55
56       The behavior is undefined if the value specified by the  attr  argument
57       to  pthread_create() does not refer to an initialized thread attributes
58       object.
59

RETURN VALUE

61       If successful, the pthread_create() function shall return zero;  other‐
62       wise, an error number shall be returned to indicate the error.
63

ERRORS

65       The pthread_create() function shall fail if:
66
67       EAGAIN The  system  lacked  the  necessary  resources to create another
68              thread, or the system-imposed  limit  on  the  total  number  of
69              threads in a process {PTHREAD_THREADS_MAX} would be exceeded.
70
71       EPERM  The  caller  does  not  have  appropriate  privileges to set the
72              required scheduling parameters or scheduling policy.
73
74       The pthread_create()  function  shall  not  return  an  error  code  of
75       [EINTR].
76
77       The following sections are informative.
78

EXAMPLES

80       None.
81

APPLICATION USAGE

83       There  is  no requirement on the implementation that the ID of the cre‐
84       ated thread be available before the newly created thread starts execut‐
85       ing. The calling thread can obtain the ID of the created thread through
86       the thread argument of the pthread_create()  function,  and  the  newly
87       created thread can obtain its ID by a call to pthread_self().
88

RATIONALE

90       A suggested alternative to pthread_create() would be to define two sep‐
91       arate operations: create and start. Some applications would  find  such
92       behavior  more  natural. Ada, in particular, separates the ``creation''
93       of a task from its ``activation''.
94
95       Splitting the operation was rejected by  the  standard  developers  for
96       many reasons:
97
98        *  The  number of calls required to start a thread would increase from
99           one to two and thus place an additional burden on applications that
100           do  not  require  the  additional synchronization. The second call,
101           however, could be avoided  by  the  additional  complication  of  a
102           start-up state attribute.
103
104        *  An  extra  state  would be introduced: ``created but not started''.
105           This would require the standard to  specify  the  behavior  of  the
106           thread operations when the target has not yet started executing.
107
108        *  For  those  applications that require such behavior, it is possible
109           to simulate the two separate steps with  the  facilities  that  are
110           currently  provided. The start_routine() can synchronize by waiting
111           on a condition variable that is signaled by the start operation.
112
113       An Ada implementor can choose to create the thread  at  either  of  two
114       points in the Ada program: when the task object is created, or when the
115       task is activated (generally at a ``begin''). If the first approach  is
116       adopted,  the  start_routine() needs to wait on a condition variable to
117       receive the order to begin ``activation''. The second approach requires
118       no   such  condition  variable  or  extra  synchronization.  In  either
119       approach, a separate Ada task control block would need  to  be  created
120       when the task object is created to hold rendezvous queues, and so on.
121
122       An  extension of the preceding model would be to allow the state of the
123       thread to be modified between the create and start.  This  would  allow
124       the  thread  attributes object to be eliminated. This has been rejected
125       because:
126
127        *  All state in the thread attributes object has to be able to be  set
128           for  the  thread. This would require the definition of functions to
129           modify thread attributes. There would be no reduction in the number
130           of  function  calls  required to set up the thread. In fact, for an
131           application that creates all threads  using  identical  attributes,
132           the  number  of function calls required to set up the threads would
133           be dramatically increased. Use of a thread attributes  object  per‐
134           mits  the application to make one set of attribute setting function
135           calls.  Otherwise, the set  of  attribute  setting  function  calls
136           needs to be made for each thread creation.
137
138        *  Depending  on  the  implementation  architecture,  functions to set
139           thread state would require kernel calls, or for  other  implementa‐
140           tion reasons would not be able to be implemented as macros, thereby
141           increasing the cost of thread creation.
142
143        *  The ability for applications to segregate threads by class would be
144           lost.
145
146       Another  suggested alternative uses a model similar to that for process
147       creation, such as ``thread fork''. The  fork  semantics  would  provide
148       more  flexibility and the ``create'' function can be implemented simply
149       by doing a thread fork followed immediately by a call  to  the  desired
150       ``start routine'' for the thread. This alternative has these problems:
151
152        *  For  many  implementations,  the entire stack of the calling thread
153           would need to be duplicated, since in many architectures  there  is
154           no way to determine the size of the calling frame.
155
156        *  Efficiency  is reduced since at least some part of the stack has to
157           be copied, even though in most cases the  thread  never  needs  the
158           copied context, since it merely calls the desired start routine.
159
160       If an implementation detects that the value specified by the attr argu‐
161       ment to pthread_create()  does  not  refer  to  an  initialized  thread
162       attributes  object, it is recommended that the function should fail and
163       report an [EINVAL] error.
164

FUTURE DIRECTIONS

166       None.
167

SEE ALSO

169       fork(), pthread_exit(), pthread_join()
170
171       The Base Definitions volume of POSIX.1‐2017, Section 4.12, Memory  Syn‐
172       chronization, <pthread.h>
173
175       Portions  of  this text are reprinted and reproduced in electronic form
176       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
177       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
178       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
179       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
180       event of any discrepancy between this version and the original IEEE and
181       The  Open Group Standard, the original IEEE and The Open Group Standard
182       is the referee document. The original Standard can be  obtained  online
183       at http://www.opengroup.org/unix/online.html .
184
185       Any  typographical  or  formatting  errors that appear in this page are
186       most likely to have been introduced during the conversion of the source
187       files  to  man page format. To report such errors, see https://www.ker
188       nel.org/doc/man-pages/reporting_bugs.html .
189
190
191
192IEEE/The Open Group                  2017                   PTHREAD_CREATE(3P)
Impressum