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
11

NAME

13       pthread_create — thread creation
14

SYNOPSIS

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

DESCRIPTION

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
30       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
38       The signal state of the new thread shall be initialized as follows:
39
40        *  The signal mask shall be inherited from the creating thread.
41
42        *  The set of signals pending for the new thread shall be empty.
43
44       The  thread-local  current  locale and the alternate stack shall not be
45       inherited.
46
47       The floating-point environment shall be  inherited  from  the  creating
48       thread.
49
50       If pthread_create() fails, no new thread is created and the contents of
51       the location referenced by thread are undefined.
52
53       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
57       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

RETURN VALUE

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

ERRORS

66       The pthread_create() function shall fail if:
67
68       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
72       EPERM  The  caller  does  not  have  appropriate  privileges to set the
73              required scheduling parameters or scheduling policy.
74
75       The pthread_create()  function  shall  not  return  an  error  code  of
76       [EINTR].
77
78       The following sections are informative.
79

EXAMPLES

81       None.
82

APPLICATION USAGE

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

RATIONALE

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
96       Splitting the operation was rejected by  the  standard  developers  for
97       many reasons:
98
99        *  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
105        *  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
109        *  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
114       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
123       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
128        *  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
139        *  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
144        *  The ability for applications to segregate threads by class would be
145           lost.
146
147       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
153        *  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
157        *  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
161       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

FUTURE DIRECTIONS

167       None.
168

SEE ALSO

170       fork(), pthread_exit(), pthread_join()
171
172       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
187       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 .
191
192
193
194IEEE/The Open Group                  2013                   PTHREAD_CREATE(3P)
Impressum