1pthread_create(3C) Standard C Library Functions pthread_create(3C)
2
6 pthread_create - create a thread
7
9 cc -mt [ flag... ] file... -lpthread [ library... ]
10 #include <pthread.h>
11 int pthread_create(pthread_t *restrict thread,
13 const pthread_attr_t *restrict attr,
14 void *(*start_routine)(void*), void *restrict arg);
15
18 The pthread_create() function is used to create a new thread, with
19 attributes specified by attr, within a process. If attr is NULL, the
20 default attributes are used. (See pthread_attr_init(3C)). If the
21 attributes specified by attr are modified later, the thread's
22 attributes are not affected. Upon successful completion, pthread_cre‐
23 ate() stores the ID of the created thread in the location referenced
24 by thread.
25 The thread is created executing start_routine with arg as its sole
28 argument. If the start_routine returns, the effect is as if there was
29 an implicit call to pthread_exit() using the return value of start_rou‐
30 tine as the exit status. Note that the thread in which main() was orig‐
31 inally invoked differs from this. When it returns from main(), the
32 effect is as if there was an implicit call to exit() using the return
33 value of main() as the exit status.
34 The signal state of the new thread is initialised as follows:
37 o The signal mask is inherited from the creating thread.
39 o The set of signals pending for the new thread is empty.
41 Default thread creation:
44 pthread_t tid;
46 void *start_func(void *), *arg;
47 pthread_create(&tid, NULL, start_func, arg);
49 This would have the same effect as:
53 pthread_attr_t attr;
55 pthread_attr_init(&attr); /* initialize attr with default */
57 /* attributes */
58 pthread_create(&tid, &attr, start_func, arg);
59 User-defined thread creation: To create a thread that is scheduled on a
63 system-wide basis, use:
64 pthread_attr_init(&attr); /* initialize attr with default */
66 /* attributes */
67 pthread_attr_setscope(&attr, PTHREAD_SCOPE_SYSTEM);
68 /* system-wide contention */
69 pthread_create(&tid, &attr, start_func, arg);
70 To customize the attributes for POSIX threads, see
74 pthread_attr_init(3C).
75 A new thread created with pthread_create() uses the stack specified by
78 the stackaddr attribute, and the stack continues for the number of
79 bytes specified by the stacksize attribute. By default, the stack size
80 is 1 megabyte for 32-bit processes and 2 megabyte for 64-bit processes
81 (see pthread_attr_setstacksize(3C)). If the default is used for both
82 the stackaddr and stacksize attributes, pthread_create() creates a
83 stack for the new thread with at least 1 megabyte for 32-bit processes
84 and 2 megabyte for 64-bit processes. (For customizing stack sizes, see
85 NOTES).
86 If pthread_create() fails, no new thread is created and the contents of
89 the location referenced by thread are undefined.
90
92 If successful, the pthread_create() function returns 0. Otherwise, an
93 error number is returned to indicate the error.
94
96 The pthread_create() function will fail if:
97 EAGAIN The system lacked the necessary resources to create another
99 thread, or the system-imposed limit on the total number of
100 threads in a process PTHREAD_THREADS_MAX would be exceeded.
101 EINVAL The value specified by attr is invalid.
104 EPERM The caller does not have appropriate permission to set the
107 required scheduling parameters or scheduling policy.
108
111 Example 1 Example of concurrency with multithreading
112 The following is an example of concurrency with multithreading. Since
115 POSIX threads and Solaris threads are fully compatible even within the
116 same process, this example uses pthread_create() if you execute a.out
117 0, or thr_create() if you execute a.out 1.
118 Five threads are created that simultaneously perform a time-consuming
122 function, sleep(10). If the execution of this process is timed, the
123 results will show that all five individual calls to sleep for ten-sec‐
124 onds completed in about ten seconds, even on a uniprocessor. If a sin‐
125 gle-threaded process calls sleep(10) five times, the execution time
126 will be about 50-seconds.
127 The command-line to time this process is:
131 POSIX threading /usr/bin/time a.out 0
134 Solaris threading /usr/bin/time a.out 1
137 /* cc thisfile.c -lthread -lpthread */
140 #define _REENTRANT /* basic 3-lines for threads */
141 #include <pthread.h>
142 #include <thread.h>
143 #define NUM_THREADS 5
145 #define SLEEP_TIME 10
146 void *sleeping(void *); /* thread routine */
148 int i;
149 thread_t tid[NUM_THREADS]; /* array of thread IDs */
150 int
152 main(int argc, char *argv[])
153 {
154 if (argc == 1) {
155 printf("use 0 as arg1 to use pthread_create()\n");
156 printf("or use 1 as arg1 to use thr_create()\n");
157 return (1);
158 }
159 switch (*argv[1]) {
161 case '0': /* POSIX */
162 for ( i = 0; i < NUM_THREADS; i++)
163 pthread_create(&tid[i], NULL, sleeping,
164 (void *)SLEEP_TIME);
165 for ( i = 0; i < NUM_THREADS; i++)
166 pthread_join(tid[i], NULL);
167 break;
168 case '1': /* Solaris */
170 for ( i = 0; i < NUM_THREADS; i++)
171 thr_create(NULL, 0, sleeping, (void *)SLEEP_TIME, 0,
172 &tid[i]);
173 while (thr_join(0, NULL, NULL) == 0)
174 ;
175 break;
176 } /* switch */
177 printf("main() reporting that all %d threads have
178 terminated\n", i);
179 return (0);
180 } /* main */
181 void *
183 sleeping(void *arg)
184 {
185 int sleep_time = (int)arg;
186 printf("thread %d sleeping %d seconds ...\n", thr_self(),
187 sleep_time);
188 sleep(sleep_time);
189 printf("\nthread %d awakening\n", thr_self());
190 return (NULL);
191 }
192 If main() had not waited for the completion of the other threads (using
196 pthread_join(3C) or thr_join(3C)), it would have continued to process
197 concurrently until it reached the end of its routine and the entire
198 process would have exited prematurely. See exit(2).
199
202 See attributes(5) for descriptions of the following attributes:
203 ┌─────────────────────────────┬─────────────────────────────┐
208 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
209 ├─────────────────────────────┼─────────────────────────────┤
210 │Interface Stability │Standard │
211 ├─────────────────────────────┼─────────────────────────────┤
212 │MT-Level │MT-Safe │
213 └─────────────────────────────┴─────────────────────────────┘
214
216 fork(2), pthread_attr_init(3C), pthread_cancel(3C), pthread_exit(3C),
217 pthread_join(3C), sysconf(3C), attributes(5), standards(5)
218
220 Multithreaded application threads execute independently of each other,
221 so their relative behavior is unpredictable. Therefore, it is possible
222 for the thread executing main() to finish before all other user appli‐
223 cation threads. The pthread_join(3C)function, on the other hand, must
224 specify the terminating thread (IDs) for which it will wait.
225 A user-specified stack size must be greater than the value
228 PTHREAD_STACK_MIN. A minimum stack size may not accommodate the stack
229 frame for the user thread function start_func. If a stack size is spec‐
230 ified, it must accommodate start_func requirements and the functions
231 that it may call in turn, in addition to the minimum requirement.
232 It is usually very difficult to determine the runtime stack require‐
235 ments for a thread. PTHREAD_STACK_MIN specifies how much stack storage
236 is required to execute a NULL start_func. The total runtime require‐
237 ments for stack storage are dependent on the storage required to do
238 runtime linking, the amount of storage required by library runtimes (as
239 printf()) that your thread calls. Since these storage parameters are
240 not known before the program runs, it is best to use default stacks. If
241 you know your runtime requirements or decide to use stacks that are
242 larger than the default, then it makes sense to specify your own
243 stacks.
244SunOS 5.11 23 Mar 2005 pthread_create(3C)