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