]>
Commit | Line | Data |
---|---|---|
058cd95f MK |
1 | .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
058cd95f | 5 | .\" |
4c1c5274 | 6 | .TH pthread_create 3 (date) "Linux man-pages (unreleased)" |
058cd95f MK |
7 | .SH NAME |
8 | pthread_create \- create a new thread | |
91707f82 AC |
9 | .SH LIBRARY |
10 | POSIX threads library | |
8fc3b2cf | 11 | .RI ( libpthread ", " \-lpthread ) |
058cd95f MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .B #include <pthread.h> | |
f90f031e | 15 | .PP |
71f5a50a AC |
16 | .BI "int pthread_create(pthread_t *restrict " thread , |
17 | .BI " const pthread_attr_t *restrict " attr , | |
18 | .BI " void *(*" start_routine ")(void *)," | |
19 | .BI " void *restrict " arg ); | |
058cd95f | 20 | .fi |
058cd95f MK |
21 | .SH DESCRIPTION |
22 | The | |
23 | .BR pthread_create () | |
2bb98c3f | 24 | function starts a new thread in the calling process. |
058cd95f MK |
25 | The new thread starts execution by invoking |
26 | .IR start_routine (); | |
1ae6b2c7 | 27 | .I arg |
058cd95f MK |
28 | is passed as the sole argument of |
29 | .IR start_routine (). | |
847e0d88 | 30 | .PP |
058cd95f | 31 | The new thread terminates in one of the following ways: |
22356d97 | 32 | .IP \(bu 3 |
058cd95f MK |
33 | It calls |
34 | .BR pthread_exit (3), | |
35 | specifying an exit status value that is available to another thread | |
36 | in the same process that calls | |
37 | .BR pthread_join (3). | |
22356d97 | 38 | .IP \(bu |
058cd95f MK |
39 | It returns from |
40 | .IR start_routine (). | |
41 | This is equivalent to calling | |
42 | .BR pthread_exit (3) | |
43 | with the value supplied in the | |
44 | .I return | |
45 | statement. | |
22356d97 | 46 | .IP \(bu |
058cd95f MK |
47 | It is canceled (see |
48 | .BR pthread_cancel (3)). | |
22356d97 | 49 | .IP \(bu |
058cd95f MK |
50 | Any of the threads in the process calls |
51 | .BR exit (3), | |
52 | or the main thread performs a return from | |
53 | .IR main (). | |
54 | This causes the termination of all threads in the process. | |
55 | .PP | |
56 | The | |
57 | .I attr | |
58 | argument points to a | |
59 | .I pthread_attr_t | |
60 | structure whose contents are used at thread creation time to | |
61 | determine attributes for the new thread; | |
62 | this structure is initialized using | |
63 | .BR pthread_attr_init (3) | |
64 | and related functions. | |
65 | If | |
66 | .I attr | |
67 | is NULL, | |
68 | then the thread is created with default attributes. | |
847e0d88 | 69 | .PP |
058cd95f MK |
70 | Before returning, a successful call to |
71 | .BR pthread_create () | |
72 | stores the ID of the new thread in the buffer pointed to by | |
73 | .IR thread ; | |
74 | this identifier is used to refer to the thread | |
75 | in subsequent calls to other pthreads functions. | |
847e0d88 | 76 | .PP |
058cd95f MK |
77 | The new thread inherits a copy of the creating thread's signal mask |
78 | .RB ( pthread_sigmask (3)). | |
c5571b61 | 79 | The set of pending signals for the new thread is empty |
058cd95f MK |
80 | .RB ( sigpending (2)). |
81 | The new thread does not inherit the creating thread's | |
82 | alternate signal stack | |
83 | .RB ( sigaltstack (2)). | |
847e0d88 | 84 | .PP |
058cd95f MK |
85 | The new thread inherits the calling thread's floating-point environment |
86 | .RB ( fenv (3)). | |
847e0d88 | 87 | .PP |
058cd95f MK |
88 | The initial value of the new thread's CPU-time clock is 0 |
89 | (see | |
90 | .BR pthread_getcpuclockid (3)). | |
0eb44391 | 91 | .\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2) |
058cd95f MK |
92 | .SS Linux-specific details |
93 | The new thread inherits copies of the calling thread's capability sets | |
94 | (see | |
95 | .BR capabilities (7)) | |
96 | and CPU affinity mask (see | |
97 | .BR sched_setaffinity (2)). | |
98 | .SH RETURN VALUE | |
99 | On success, | |
100 | .BR pthread_create () | |
101 | returns 0; | |
102 | on error, it returns an error number, and the contents of | |
1ae6b2c7 | 103 | .I *thread |
058cd95f MK |
104 | are undefined. |
105 | .SH ERRORS | |
106 | .TP | |
107 | .B EAGAIN | |
20cbd039 MK |
108 | Insufficient resources to create another thread. |
109 | .TP | |
110 | .B EAGAIN | |
111 | .\" NOTE! The following should match the description in fork(2) | |
112 | A system-imposed limit on the number of threads was encountered. | |
113 | There are a number of limits that may trigger this error: the | |
1ae6b2c7 | 114 | .B RLIMIT_NPROC |
058cd95f MK |
115 | soft resource limit (set via |
116 | .BR setrlimit (2)), | |
20cbd039 | 117 | which limits the number of processes and threads for a real user ID, |
058cd95f | 118 | was reached; |
03518b19 | 119 | the kernel's system-wide limit on the number of processes and threads, |
b49c2acb | 120 | .IR /proc/sys/kernel/threads\-max , |
20cbd039 MK |
121 | was reached (see |
122 | .BR proc (5)); | |
123 | or the maximum number of PIDs, | |
124 | .IR /proc/sys/kernel/pid_max , | |
125 | was reached (see | |
126 | .BR proc (5)). | |
058cd95f MK |
127 | .TP |
128 | .B EINVAL | |
129 | Invalid settings in | |
130 | .IR attr . | |
131 | .TP | |
132 | .\" FIXME . Test the following | |
133 | .B EPERM | |
134 | No permission to set the scheduling policy and parameters specified in | |
135 | .IR attr . | |
a7930e0d ZL |
136 | .SH ATTRIBUTES |
137 | For an explanation of the terms used in this section, see | |
138 | .BR attributes (7). | |
c466875e MK |
139 | .ad l |
140 | .nh | |
a7930e0d ZL |
141 | .TS |
142 | allbox; | |
c466875e | 143 | lbx lb lb |
a7930e0d ZL |
144 | l l l. |
145 | Interface Attribute Value | |
146 | T{ | |
147 | .BR pthread_create () | |
148 | T} Thread safety MT-Safe | |
149 | .TE | |
c466875e MK |
150 | .hy |
151 | .ad | |
847e0d88 | 152 | .sp 1 |
3113c7f3 | 153 | .SH STANDARDS |
be4f5cb1 | 154 | POSIX.1-2001, POSIX.1-2008. |
058cd95f MK |
155 | .SH NOTES |
156 | See | |
157 | .BR pthread_self (3) | |
158 | for further information on the thread ID returned in | |
1ae6b2c7 | 159 | .I *thread |
058cd95f MK |
160 | by |
161 | .BR pthread_create (). | |
162 | Unless real-time scheduling policies are being employed, | |
163 | after a call to | |
164 | .BR pthread_create (), | |
165 | it is indeterminate which thread\(emthe caller or the new thread\(emwill | |
166 | next execute. | |
847e0d88 | 167 | .PP |
058cd95f MK |
168 | A thread may either be |
169 | .I joinable | |
170 | or | |
171 | .IR detached . | |
172 | If a thread is joinable, then another thread can call | |
173 | .BR pthread_join (3) | |
174 | to wait for the thread to terminate and fetch its exit status. | |
175 | Only when a terminated joinable thread has been joined are | |
176 | the last of its resources released back to the system. | |
177 | When a detached thread terminates, | |
178 | its resources are automatically released back to the system: | |
179 | it is not possible to join with the thread in order to obtain | |
180 | its exit status. | |
181 | Making a thread detached is useful for some types of daemon threads | |
182 | whose exit status the application does not need to care about. | |
183 | By default, a new thread is created in a joinable state, unless | |
184 | .I attr | |
185 | was set to create the thread in a detached state (using | |
186 | .BR pthread_attr_setdetachstate (3)). | |
847e0d88 | 187 | .PP |
058cd95f | 188 | Under the NPTL threading implementation, if the |
1ae6b2c7 | 189 | .B RLIMIT_STACK |
058cd95f | 190 | soft resource limit |
1ae6b2c7 | 191 | .I at the time the program started |
058cd95f MK |
192 | has any value other than "unlimited", |
193 | then it determines the default stack size of new threads. | |
194 | Using | |
195 | .BR pthread_attr_setstacksize (3), | |
196 | the stack size attribute can be explicitly set in the | |
197 | .I attr | |
198 | argument used to create a thread, | |
199 | in order to obtain a stack size other than the default. | |
a706f0e0 | 200 | If the |
1ae6b2c7 | 201 | .B RLIMIT_STACK |
8efada99 MK |
202 | resource limit is set to "unlimited", |
203 | a per-architecture value is used for the stack size. | |
204 | Here is the value for a few architectures: | |
205 | .RS | |
af6e958b FB |
206 | .TS |
207 | allbox; | |
208 | lb lb | |
209 | l r. | |
210 | Architecture Default stack size | |
169d7283 MK |
211 | i386 2 MB |
212 | IA-64 32 MB | |
af6e958b FB |
213 | PowerPC 4 MB |
214 | S/390 2 MB | |
169d7283 MK |
215 | Sparc-32 2 MB |
216 | Sparc-64 4 MB | |
af6e958b FB |
217 | x86_64 2 MB |
218 | .TE | |
8efada99 | 219 | .RE |
22cb459d MK |
220 | .SH BUGS |
221 | In the obsolete LinuxThreads implementation, | |
222 | each of the threads in a process has a different process ID. | |
223 | This is in violation of the POSIX threads specification, | |
224 | and is the source of many other nonconformances to the standard; see | |
225 | .BR pthreads (7). | |
a14af333 | 226 | .SH EXAMPLES |
058cd95f MK |
227 | The program below demonstrates the use of |
228 | .BR pthread_create (), | |
229 | as well as a number of other functions in the pthreads API. | |
847e0d88 | 230 | .PP |
058cd95f MK |
231 | In the following run, |
232 | on a system providing the NPTL threading implementation, | |
233 | the stack size defaults to the value given by the | |
234 | "stack size" resource limit: | |
847e0d88 | 235 | .PP |
058cd95f | 236 | .in +4n |
b8302363 | 237 | .EX |
b43a3b30 | 238 | .RB "$" " ulimit \-s" |
d58522c0 | 239 | 8192 # The stack size limit is 8 MB (0x800000 bytes) |
b43a3b30 | 240 | .RB "$" " ./a.out hola salut servus" |
058cd95f MK |
241 | Thread 1: top of stack near 0xb7dd03b8; argv_string=hola |
242 | Thread 2: top of stack near 0xb75cf3b8; argv_string=salut | |
243 | Thread 3: top of stack near 0xb6dce3b8; argv_string=servus | |
244 | Joined with thread 1; returned value was HOLA | |
245 | Joined with thread 2; returned value was SALUT | |
246 | Joined with thread 3; returned value was SERVUS | |
b8302363 | 247 | .EE |
058cd95f | 248 | .in |
847e0d88 | 249 | .PP |
ee8655b5 | 250 | In the next run, the program explicitly sets a stack size of 1\ MB (using |
058cd95f MK |
251 | .BR pthread_attr_setstacksize (3)) |
252 | for the created threads: | |
847e0d88 | 253 | .PP |
058cd95f | 254 | .in +4n |
b8302363 | 255 | .EX |
b43a3b30 | 256 | .RB "$" " ./a.out \-s 0x100000 hola salut servus" |
058cd95f MK |
257 | Thread 1: top of stack near 0xb7d723b8; argv_string=hola |
258 | Thread 2: top of stack near 0xb7c713b8; argv_string=salut | |
259 | Thread 3: top of stack near 0xb7b703b8; argv_string=servus | |
260 | Joined with thread 1; returned value was HOLA | |
261 | Joined with thread 2; returned value was SALUT | |
262 | Joined with thread 3; returned value was SERVUS | |
b8302363 | 263 | .EE |
058cd95f | 264 | .in |
9c330504 | 265 | .SS Program source |
d84d0300 | 266 | \& |
b0b6ab4e | 267 | .\" SRC BEGIN (pthread_create.c) |
e7d0bb47 | 268 | .EX |
ad3868f0 AC |
269 | #include <ctype.h> |
270 | #include <errno.h> | |
058cd95f | 271 | #include <pthread.h> |
058cd95f MK |
272 | #include <stdio.h> |
273 | #include <stdlib.h> | |
ad3868f0 | 274 | #include <string.h> |
058cd95f | 275 | #include <unistd.h> |
058cd95f | 276 | |
d1a71985 | 277 | #define handle_error_en(en, msg) \e |
940c8ce2 | 278 | do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) |
058cd95f | 279 | |
d1a71985 | 280 | #define handle_error(msg) \e |
940c8ce2 | 281 | do { perror(msg); exit(EXIT_FAILURE); } while (0) |
058cd95f MK |
282 | |
283 | struct thread_info { /* Used as argument to thread_start() */ | |
188cf22e | 284 | pthread_t thread_id; /* ID returned by pthread_create() */ |
058cd95f MK |
285 | int thread_num; /* Application\-defined thread # */ |
286 | char *argv_string; /* From command\-line argument */ | |
287 | }; | |
288 | ||
289 | /* Thread start function: display address near top of our stack, | |
46b20ca1 | 290 | and return upper\-cased copy of argv_string. */ |
058cd95f MK |
291 | |
292 | static void * | |
293 | thread_start(void *arg) | |
294 | { | |
13f78d96 | 295 | struct thread_info *tinfo = arg; |
88893a77 | 296 | char *uargv; |
058cd95f | 297 | |
d1a71985 | 298 | printf("Thread %d: top of stack near %p; argv_string=%s\en", |
d917c31d | 299 | tinfo\->thread_num, (void *) &tinfo, tinfo\->argv_string); |
058cd95f MK |
300 | |
301 | uargv = strdup(tinfo\->argv_string); | |
302 | if (uargv == NULL) | |
940c8ce2 | 303 | handle_error("strdup"); |
058cd95f | 304 | |
88893a77 | 305 | for (char *p = uargv; *p != \(aq\e0\(aq; p++) |
058cd95f MK |
306 | *p = toupper(*p); |
307 | ||
308 | return uargv; | |
309 | } | |
310 | ||
311 | int | |
312 | main(int argc, char *argv[]) | |
313 | { | |
b42296e4 | 314 | int s, opt; |
0f6f10d5 | 315 | void *res; |
b42296e4 | 316 | size_t num_threads; |
0f6f10d5 AC |
317 | ssize_t stack_size; |
318 | pthread_attr_t attr; | |
319 | struct thread_info *tinfo; | |
058cd95f | 320 | |
46b20ca1 | 321 | /* The "\-s" option specifies a stack size for our threads. */ |
058cd95f MK |
322 | |
323 | stack_size = \-1; | |
324 | while ((opt = getopt(argc, argv, "s:")) != \-1) { | |
325 | switch (opt) { | |
ce5139ca | 326 | case \(aqs\(aq: |
058cd95f MK |
327 | stack_size = strtoul(optarg, NULL, 0); |
328 | break; | |
329 | ||
330 | default: | |
d064d41a | 331 | fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en", |
058cd95f MK |
332 | argv[0]); |
333 | exit(EXIT_FAILURE); | |
334 | } | |
335 | } | |
336 | ||
337 | num_threads = argc \- optind; | |
338 | ||
46b20ca1 | 339 | /* Initialize thread creation attributes. */ |
058cd95f MK |
340 | |
341 | s = pthread_attr_init(&attr); | |
342 | if (s != 0) | |
940c8ce2 | 343 | handle_error_en(s, "pthread_attr_init"); |
058cd95f MK |
344 | |
345 | if (stack_size > 0) { | |
346 | s = pthread_attr_setstacksize(&attr, stack_size); | |
347 | if (s != 0) | |
940c8ce2 | 348 | handle_error_en(s, "pthread_attr_setstacksize"); |
058cd95f MK |
349 | } |
350 | ||
46b20ca1 | 351 | /* Allocate memory for pthread_create() arguments. */ |
058cd95f | 352 | |
0f6f10d5 | 353 | tinfo = calloc(num_threads, sizeof(*tinfo)); |
058cd95f | 354 | if (tinfo == NULL) |
940c8ce2 | 355 | handle_error("calloc"); |
058cd95f | 356 | |
46b20ca1 | 357 | /* Create one thread for each command\-line argument. */ |
058cd95f | 358 | |
b42296e4 | 359 | for (size_t tnum = 0; tnum < num_threads; tnum++) { |
058cd95f MK |
360 | tinfo[tnum].thread_num = tnum + 1; |
361 | tinfo[tnum].argv_string = argv[optind + tnum]; | |
362 | ||
363 | /* The pthread_create() call stores the thread ID into | |
46b20ca1 | 364 | corresponding element of tinfo[]. */ |
058cd95f MK |
365 | |
366 | s = pthread_create(&tinfo[tnum].thread_id, &attr, | |
367 | &thread_start, &tinfo[tnum]); | |
368 | if (s != 0) | |
940c8ce2 | 369 | handle_error_en(s, "pthread_create"); |
058cd95f MK |
370 | } |
371 | ||
372 | /* Destroy the thread attributes object, since it is no | |
46b20ca1 | 373 | longer needed. */ |
058cd95f MK |
374 | |
375 | s = pthread_attr_destroy(&attr); | |
376 | if (s != 0) | |
940c8ce2 | 377 | handle_error_en(s, "pthread_attr_destroy"); |
058cd95f | 378 | |
46b20ca1 | 379 | /* Now join with each thread, and display its returned value. */ |
058cd95f | 380 | |
b42296e4 | 381 | for (size_t tnum = 0; tnum < num_threads; tnum++) { |
058cd95f MK |
382 | s = pthread_join(tinfo[tnum].thread_id, &res); |
383 | if (s != 0) | |
940c8ce2 | 384 | handle_error_en(s, "pthread_join"); |
058cd95f | 385 | |
d1a71985 | 386 | printf("Joined with thread %d; returned value was %s\en", |
d917c31d | 387 | tinfo[tnum].thread_num, (char *) res); |
058cd95f MK |
388 | free(res); /* Free memory allocated by thread */ |
389 | } | |
390 | ||
2bb98c3f | 391 | free(tinfo); |
058cd95f MK |
392 | exit(EXIT_SUCCESS); |
393 | } | |
e7d0bb47 | 394 | .EE |
b0b6ab4e | 395 | .\" SRC END |
058cd95f | 396 | .SH SEE ALSO |
ca8a0bd2 MK |
397 | .ad l |
398 | .nh | |
058cd95f MK |
399 | .BR getrlimit (2), |
400 | .BR pthread_attr_init (3), | |
401 | .BR pthread_cancel (3), | |
402 | .BR pthread_detach (3), | |
403 | .BR pthread_equal (3), | |
404 | .BR pthread_exit (3), | |
405 | .BR pthread_getattr_np (3), | |
406 | .BR pthread_join (3), | |
407 | .BR pthread_self (3), | |
c09bc825 | 408 | .BR pthread_setattr_default_np (3), |
058cd95f | 409 | .BR pthreads (7) |