1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH PTHREAD_CREATE 3 2012-08-03 "Linux" "Linux Programmer's Manual"
28 pthread_create \- create a new thread
31 .B #include <pthread.h>
33 .BI "int pthread_create(pthread_t *" thread ", const pthread_attr_t *" attr ,
34 .BI " void *(*" start_routine ") (void *), void *" arg );
37 Compile and link with \fI\-pthread\fP.
41 function starts a new thread in the calling process.
42 The new thread starts execution by invoking
45 is passed as the sole argument of
48 The new thread terminates in one of the following ways:
52 specifying an exit status value that is available to another thread
53 in the same process that calls
58 This is equivalent to calling
60 with the value supplied in the
65 .BR pthread_cancel (3)).
67 Any of the threads in the process calls
69 or the main thread performs a return from
71 This causes the termination of all threads in the process.
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.
85 then the thread is created with default attributes.
87 Before returning, a successful call to
89 stores the ID of the new thread in the buffer pointed to by
91 this identifier is used to refer to the thread
92 in subsequent calls to other pthreads functions.
94 The new thread inherits a copy of the creating thread's signal mask
95 .RB ( pthread_sigmask (3)).
96 The set of pending signals for the new thread is empty
97 .RB ( sigpending (2)).
98 The new thread does not inherit the creating thread's
99 alternate signal stack
100 .RB ( sigaltstack (2)).
102 The new thread inherits the calling thread's floating-point environment
105 The initial value of the new thread's CPU-time clock is 0
107 .BR pthread_getcpuclockid (3)).
108 .\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2)
109 .SS Linux-specific details
110 The new thread inherits copies of the calling thread's capability sets
112 .BR capabilities (7))
113 and CPU affinity mask (see
114 .BR sched_setaffinity (2)).
117 .BR pthread_create ()
119 on error, it returns an error number, and the contents of
125 Insufficient resources to create another thread,
126 or a system-imposed limit on the number of threads was encountered.
127 The latter case may occur in two ways:
130 soft resource limit (set via
132 which limits the number of process for a real user ID,
134 or the kernel's system-wide limit on the number of threads,
135 .IR /proc/sys/kernel/threads-max ,
142 .\" FIXME . Test the following
144 No permission to set the scheduling policy and parameters specified in
151 for further information on the thread ID returned in
154 .BR pthread_create ().
155 Unless real-time scheduling policies are being employed,
157 .BR pthread_create (),
158 it is indeterminate which thread\(emthe caller or the new thread\(emwill
161 A thread may either be
165 If a thread is joinable, then another thread can call
167 to wait for the thread to terminate and fetch its exit status.
168 Only when a terminated joinable thread has been joined are
169 the last of its resources released back to the system.
170 When a detached thread terminates,
171 its resources are automatically released back to the system:
172 it is not possible to join with the thread in order to obtain
174 Making a thread detached is useful for some types of daemon threads
175 whose exit status the application does not need to care about.
176 By default, a new thread is created in a joinable state, unless
178 was set to create the thread in a detached state (using
179 .BR pthread_attr_setdetachstate (3)).
181 .\" FIXME . Perhaps some of the following detail should be in
182 .\" a future pthread_attr_setstacksize(3) page.
183 On Linux/x86-32, the default stack size for a new thread is 2 megabytes.
184 Under the NPTL threading implementation, if the
187 .IR "at the time the program started"
188 has any value other than "unlimited",
189 then it determines the default stack size of new threads.
191 .BR pthread_attr_setstacksize (3),
192 the stack size attribute can be explicitly set in the
194 argument used to create a thread,
195 in order to obtain a stack size other than the default.
197 In the obsolete LinuxThreads implementation,
198 each of the threads in a process has a different process ID.
199 This is in violation of the POSIX threads specification,
200 and is the source of many other nonconformances to the standard; see
203 The program below demonstrates the use of
204 .BR pthread_create (),
205 as well as a number of other functions in the pthreads API.
207 In the following run,
208 on a system providing the NPTL threading implementation,
209 the stack size defaults to the value given by the
210 "stack size" resource limit:
214 .RB "$" " ulimit \-s"
215 8192 # The stack size limit is 8 MB (0x800000 bytes)
216 .RB "$" " ./a.out hola salut servus"
217 Thread 1: top of stack near 0xb7dd03b8; argv_string=hola
218 Thread 2: top of stack near 0xb75cf3b8; argv_string=salut
219 Thread 3: top of stack near 0xb6dce3b8; argv_string=servus
220 Joined with thread 1; returned value was HOLA
221 Joined with thread 2; returned value was SALUT
222 Joined with thread 3; returned value was SERVUS
226 In the next run, the program explicitly sets a stack size of 1MB (using
227 .BR pthread_attr_setstacksize (3))
228 for the created threads:
232 .RB "$" " ./a.out \-s 0x100000 hola salut servus"
233 Thread 1: top of stack near 0xb7d723b8; argv_string=hola
234 Thread 2: top of stack near 0xb7c713b8; argv_string=salut
235 Thread 3: top of stack near 0xb7b703b8; argv_string=servus
236 Joined with thread 1; returned value was HOLA
237 Joined with thread 2; returned value was SALUT
238 Joined with thread 3; returned value was SERVUS
252 #define handle_error_en(en, msg) \\
253 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
255 #define handle_error(msg) \\
256 do { perror(msg); exit(EXIT_FAILURE); } while (0)
258 struct thread_info { /* Used as argument to thread_start() */
259 pthread_t thread_id; /* ID returned by pthread_create() */
260 int thread_num; /* Application\-defined thread # */
261 char *argv_string; /* From command\-line argument */
264 /* Thread start function: display address near top of our stack,
265 and return upper\-cased copy of argv_string */
268 thread_start(void *arg)
270 struct thread_info *tinfo = arg;
273 printf("Thread %d: top of stack near %p; argv_string=%s\\n",
274 tinfo\->thread_num, &p, tinfo\->argv_string);
276 uargv = strdup(tinfo\->argv_string);
278 handle_error("strdup");
280 for (p = uargv; *p != \(aq\\0\(aq; p++)
287 main(int argc, char *argv[])
289 int s, tnum, opt, num_threads;
290 struct thread_info *tinfo;
295 /* The "\-s" option specifies a stack size for our threads */
298 while ((opt = getopt(argc, argv, "s:")) != \-1) {
301 stack_size = strtoul(optarg, NULL, 0);
305 fprintf(stderr, "Usage: %s [\-s stack-size] arg...\\n",
311 num_threads = argc \- optind;
313 /* Initialize thread creation attributes */
315 s = pthread_attr_init(&attr);
317 handle_error_en(s, "pthread_attr_init");
319 if (stack_size > 0) {
320 s = pthread_attr_setstacksize(&attr, stack_size);
322 handle_error_en(s, "pthread_attr_setstacksize");
325 /* Allocate memory for pthread_create() arguments */
327 tinfo = calloc(num_threads, sizeof(struct thread_info));
329 handle_error("calloc");
331 /* Create one thread for each command\-line argument */
333 for (tnum = 0; tnum < num_threads; tnum++) {
334 tinfo[tnum].thread_num = tnum + 1;
335 tinfo[tnum].argv_string = argv[optind + tnum];
337 /* The pthread_create() call stores the thread ID into
338 corresponding element of tinfo[] */
340 s = pthread_create(&tinfo[tnum].thread_id, &attr,
341 &thread_start, &tinfo[tnum]);
343 handle_error_en(s, "pthread_create");
346 /* Destroy the thread attributes object, since it is no
349 s = pthread_attr_destroy(&attr);
351 handle_error_en(s, "pthread_attr_destroy");
353 /* Now join with each thread, and display its returned value */
355 for (tnum = 0; tnum < num_threads; tnum++) {
356 s = pthread_join(tinfo[tnum].thread_id, &res);
358 handle_error_en(s, "pthread_join");
360 printf("Joined with thread %d; returned value was %s\\n",
361 tinfo[tnum].thread_num, (char *) res);
362 free(res); /* Free memory allocated by thread */
373 .BR pthread_attr_init (3),
374 .BR pthread_cancel (3),
375 .BR pthread_detach (3),
376 .BR pthread_equal (3),
377 .BR pthread_exit (3),
378 .BR pthread_getattr_np (3),
379 .BR pthread_join (3),
380 .BR pthread_self (3),
383 This page is part of release 3.67 of the Linux
386 A description of the project,
387 information about reporting bugs,
388 and the latest version of this page,
390 \%http://www.kernel.org/doc/man\-pages/.