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
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. Upon
27       successful completion, pthread_create() shall store the ID of the  cre‐
28       ated 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 alternate stack shall not be 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

RETURN VALUE

57       If  successful, the pthread_create() function shall return zero; other‐
58       wise, an error number shall be returned to indicate the error.
59

ERRORS

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

EXAMPLES

79       None.
80

APPLICATION USAGE

82       None.
83

RATIONALE

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

FUTURE DIRECTIONS

156       None.
157

SEE ALSO

159       fork(), pthread_exit(), pthread_join(), the Base Definitions volume  of
160       IEEE Std 1003.1-2001, <pthread.h>
161
163       Portions  of  this text are reprinted and reproduced in electronic form
164       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
165       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
166       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
167       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
168       event of any discrepancy between this version and the original IEEE and
169       The  Open Group Standard, the original IEEE and The Open Group Standard
170       is the referee document. The original Standard can be  obtained  online
171       at http://www.opengroup.org/unix/online.html .
172
173
174
175IEEE/The Open Group                  2003                   PTHREAD_CREATE(3P)
Impressum