Debian Codegraph @

upstream/debian-unstable/man3/pthread_create.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH pthread_create 3 2026-02-10 "Linux man-pages 6.18"
7 .SH NAME
8 pthread_create \- create a new thread
9 .SH LIBRARY
10 POSIX threads library
11 .RI ( libpthread ,\~ \-lpthread )
12 .SH SYNOPSIS
13 .nf
14 .B #include <pthread.h>
15 .P
16 .BI "int pthread_create(pthread_t *restrict " thread ,
17 .BI " const pthread_attr_t *_Nullable restrict " attr ,
18 .BI " typeof(void *(void *_Nullable)) *" start_routine ,
19 .BI " void *_Nullable restrict " arg );
20 .fi
21 .SH DESCRIPTION
22 The
23 .BR pthread_create ()
24 function starts a new thread in the calling process.
25 The new thread starts execution by invoking
26 .IR start_routine ();
27 .I arg
28 is passed as the sole argument of
29 .IR start_routine ().
30 .P
31 The new thread terminates in one of the following ways:
32 .IP \[bu] 3
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).
38 .IP \[bu]
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.
46 .IP \[bu]
47 It is canceled (see
48 .BR pthread_cancel (3)).
49 .IP \[bu]
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 .P
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.
69 .P
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.
76 .P
77 The new thread inherits a copy of the creating thread's signal mask
78 .RB ( pthread_sigmask (3)).
79 The set of pending signals for the new thread is empty
80 .RB ( sigpending (2)).
81 The new thread does not inherit the creating thread's
82 alternate signal stack
83 .RB ( sigaltstack (2)).
84 .P
85 The new thread inherits the calling thread's floating-point environment
86 .RB ( fenv (3)).
87 .P
88 The initial value of the new thread's CPU-time clock is 0
89 (see
90 .BR pthread_getcpuclockid (3)).
91 .\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2)
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
103 .I *thread
104 are undefined.
105 .SH ERRORS
106 .TP
107 .B EAGAIN
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
114 .B RLIMIT_NPROC
115 soft resource limit (set via
116 .BR setrlimit (2)),
117 which limits the number of processes and threads for a real user ID,
118 was reached;
119 the kernel's system-wide limit on the number of processes and threads,
120 .IR /proc/sys/kernel/threads\-max ,
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)).
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 .
136 .SH ATTRIBUTES
137 For an explanation of the terms used in this section, see
138 .BR attributes (7).
139 .TS
140 allbox;
141 lbx lb lb
142 l l l.
143 Interface Attribute Value
144 T{
145 .na
146 .nh
147 .BR pthread_create ()
148 T} Thread safety MT-Safe
149 .TE
150 .SH STANDARDS
151 POSIX.1-2008.
152 .SH HISTORY
153 POSIX.1-2001.
154 .SH NOTES
155 See
156 .BR pthread_self (3)
157 for further information on the thread ID returned in
158 .I *thread
159 by
160 .BR pthread_create ().
161 Unless real-time scheduling policies are being employed,
162 after a call to
163 .BR pthread_create (),
164 it is indeterminate which thread\[em]the caller or the new thread\[em]will
165 next execute.
166 .P
167 A thread may either be
168 .I joinable
169 or
170 .IR detached .
171 If a thread is joinable, then another thread can call
172 .BR pthread_join (3)
173 to wait for the thread to terminate and fetch its exit status.
174 Only when a terminated joinable thread has been joined are
175 the last of its resources released back to the system.
176 When a detached thread terminates,
177 its resources are automatically released back to the system:
178 it is not possible to join with the thread in order to obtain
179 its exit status.
180 Making a thread detached is useful for some types of daemon threads
181 whose exit status the application does not need to care about.
182 By default, a new thread is created in a joinable state, unless
183 .I attr
184 was set to create the thread in a detached state (using
185 .BR pthread_attr_setdetachstate (3)).
186 .P
187 Under the NPTL threading implementation, if the
188 .B RLIMIT_STACK
189 soft resource limit
190 .I at the time the program started
191 has any value other than "unlimited",
192 then it determines the default stack size of new threads.
193 Using
194 .BR pthread_attr_setstacksize (3),
195 the stack size attribute can be explicitly set in the
196 .I attr
197 argument used to create a thread,
198 in order to obtain a stack size other than the default.
199 If the
200 .B RLIMIT_STACK
201 resource limit is set to "unlimited",
202 a per-architecture value is used for the stack size:
203 2 MB on most architectures;
204 4 MB on POWER and Sparc-64.
205 .SH BUGS
206 In the obsolete LinuxThreads implementation,
207 each of the threads in a process has a different process ID.
208 This is in violation of the POSIX threads specification,
209 and is the source of many other nonconformances to the standard;
210 see
211 .BR pthreads (7).
212 .SH EXAMPLES
213 The program below demonstrates the use of
214 .BR pthread_create (),
215 as well as a number of other functions in the pthreads API.
216 .P
217 In the following run,
218 on a system providing the NPTL threading implementation,
219 the stack size defaults to the value given by the
220 "stack size" resource limit:
221 .P
222 .in +4n
223 .EX
224 .RB "$" " ulimit \-s"
225 8192 # The stack size limit is 8 MB (0x800000 bytes)
226 .RB "$" " ./a.out hola salut servus"
227 Thread 1: top of stack near 0xb7dd03b8; argv_string=hola
228 Thread 2: top of stack near 0xb75cf3b8; argv_string=salut
229 Thread 3: top of stack near 0xb6dce3b8; argv_string=servus
230 Joined with thread 1; returned value was HOLA
231 Joined with thread 2; returned value was SALUT
232 Joined with thread 3; returned value was SERVUS
233 .EE
234 .in
235 .P
236 In the next run, the program explicitly sets a stack size of 1\ MB (using
237 .BR pthread_attr_setstacksize (3))
238 for the created threads:
239 .P
240 .in +4n
241 .EX
242 .RB "$" " ./a.out \-s 0x100000 hola salut servus"
243 Thread 1: top of stack near 0xb7d723b8; argv_string=hola
244 Thread 2: top of stack near 0xb7c713b8; argv_string=salut
245 Thread 3: top of stack near 0xb7b703b8; argv_string=servus
246 Joined with thread 1; returned value was HOLA
247 Joined with thread 2; returned value was SALUT
248 Joined with thread 3; returned value was SERVUS
249 .EE
250 .in
251 .SS Program source
252 \&
253 .\" SRC BEGIN (pthread_create.c)
254 .EX
255 #include <ctype.h>
256 #include <err.h>
257 #include <pthread.h>
258 #include <stdio.h>
259 #include <stdlib.h>
260 #include <string.h>
261 #include <sys/types.h>
262 #include <unistd.h>
263 \&
264 struct thread_info { /* Used as argument to thread_start() */
265 pthread_t thread_id; /* ID returned by pthread_create() */
266 int thread_num; /* Application\-defined thread # */
267 char *argv_string; /* From command\-line argument */
268 };
269 \&
270 /* Thread start function: display address near top of our stack,
271 and return upper\-cased copy of argv_string. */
272 \&
273 static void *
274 thread_start(void *arg)
275 {
276 struct thread_info *tinfo = arg;
277 char *uargv;
278 \&
279 printf("Thread %d: top of stack near %p; argv_string=%s\[rs]n",
280 tinfo\->thread_num, (void *) &tinfo, tinfo\->argv_string);
281 \&
282 uargv = strdup(tinfo\->argv_string);
283 if (uargv == NULL)
284 err(EXIT_FAILURE, "strdup");
285 \&
286 for (char *p = uargv; *p != \[aq]\[rs]0\[aq]; p++)
287 *p = toupper(*p);
288 \&
289 return uargv;
290 }
291 \&
292 int
293 main(int argc, char *argv[])
294 {
295 int s, opt;
296 void *res;
297 size_t num_threads;
298 ssize_t stack_size;
299 pthread_attr_t attr;
300 struct thread_info *tinfo;
301 \&
302 /* The "\-s" option specifies a stack size for our threads. */
303 \&
304 stack_size = \-1;
305 while ((opt = getopt(argc, argv, "s:")) != \-1) {
306 switch (opt) {
307 case \[aq]s\[aq]:
308 stack_size = strtoul(optarg, NULL, 0);
309 break;
310 \&
311 default:
312 fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\[rs]n",
313 argv[0]);
314 exit(EXIT_FAILURE);
315 }
316 }
317 \&
318 num_threads = argc \- optind;
319 \&
320 /* Initialize thread creation attributes. */
321 \&
322 s = pthread_attr_init(&attr);
323 if (s != 0)
324 errc(EXIT_FAILURE, s, "pthread_attr_init");
325 \&
326 if (stack_size > 0) {
327 s = pthread_attr_setstacksize(&attr, stack_size);
328 if (s != 0)
329 errc(EXIT_FAILURE, s, "pthread_attr_setstacksize");
330 }
331 \&
332 /* Allocate memory for pthread_create() arguments. */
333 \&
334 tinfo = calloc(num_threads, sizeof(*tinfo));
335 if (tinfo == NULL)
336 err(EXIT_FAILURE, "calloc");
337 \&
338 /* Create one thread for each command\-line argument. */
339 \&
340 for (size_t tnum = 0; tnum < num_threads; tnum++) {
341 tinfo[tnum].thread_num = tnum + 1;
342 tinfo[tnum].argv_string = argv[optind + tnum];
343 \&
344 /* The pthread_create() call stores the thread ID into
345 corresponding element of tinfo[]. */
346 \&
347 s = pthread_create(&tinfo[tnum].thread_id, &attr,
348 &thread_start, &tinfo[tnum]);
349 if (s != 0)
350 errc(EXIT_FAILURE, s, "pthread_create");
351 }
352 \&
353 /* Destroy the thread attributes object, since it is no
354 longer needed. */
355 \&
356 s = pthread_attr_destroy(&attr);
357 if (s != 0)
358 errc(EXIT_FAILURE, s, "pthread_attr_destroy");
359 \&
360 /* Now join with each thread, and display its returned value. */
361 \&
362 for (size_t tnum = 0; tnum < num_threads; tnum++) {
363 s = pthread_join(tinfo[tnum].thread_id, &res);
364 if (s != 0)
365 errc(EXIT_FAILURE, s, "pthread_join");
366 \&
367 printf("Joined with thread %d; returned value was %s\[rs]n",
368 tinfo[tnum].thread_num, (char *) res);
369 free(res); /* Free memory allocated by thread */
370 }
371 \&
372 free(tinfo);
373 exit(EXIT_SUCCESS);
374 }
375 .EE
376 .\" SRC END
377 .SH SEE ALSO
378 .ad l
379 .nh
380 .BR getrlimit (2),
381 .BR pthread_attr_init (3),
382 .BR pthread_cancel (3),
383 .BR pthread_detach (3),
384 .BR pthread_equal (3),
385 .BR pthread_exit (3),
386 .BR pthread_getattr_np (3),
387 .BR pthread_join (3),
388 .BR pthread_self (3),
389 .BR pthread_setattr_default_np (3),
390 .BR pthreads (7)