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