man3/pthread_create.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_CREATE 3 2021-03-22 "Linux man-pages (unreleased)"
   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 .PP
  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 );
  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 .PP
  31 The new thread terminates in one of the following ways:
  32 .IP * 2
  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 *
  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 *
  47 It is canceled (see
  48 .BR pthread_cancel (3)).
  49 .IP *
  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.
  69 .PP
  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 .PP
  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 .PP
  85 The new thread inherits the calling thread's floating-point environment
  86 .RB ( fenv (3)).
  87 .PP
  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 .ad l
 140 .nh
 141 .TS
 142 allbox;
 143 lbx lb lb
 144 l l l.
 145 Interface       Attribute       Value
 146 T{
 147 .BR pthread_create ()
 148 T}      Thread safety   MT-Safe
 149 .TE
 150 .hy
 151 .ad
 152 .sp 1
 153 .SH STANDARDS
 154 POSIX.1-2001, POSIX.1-2008.
 155 .SH NOTES
 156 See
 157 .BR pthread_self (3)
 158 for further information on the thread ID returned in
 159 .I *thread
 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.
 167 .PP
 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)).
 187 .PP
 188 Under the NPTL threading implementation, if the
 189 .B RLIMIT_STACK
 190 soft resource limit
 191 .I at the time the program started
 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.
 200 If the
 201 .B RLIMIT_STACK
 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
 206 .TS
 207 allbox;
 208 lb lb
 209 l r.
 210 Architecture    Default stack size
 211 i386    2 MB
 212 IA-64   32 MB
 213 PowerPC 4 MB
 214 S/390   2 MB
 215 Sparc-32        2 MB
 216 Sparc-64        4 MB
 217 x86_64  2 MB
 218 .TE
 219 .RE
 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).
 226 .SH EXAMPLES
 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.
 230 .PP
 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:
 235 .PP
 236 .in +4n
 237 .EX
 238 .RB "$" " ulimit \-s"
 239 8192            # The stack size limit is 8 MB (0x800000 bytes)
 240 .RB "$" " ./a.out hola salut servus"
 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
 247 .EE
 248 .in
 249 .PP
 250 In the next run, the program explicitly sets a stack size of 1\ MB (using
 251 .BR pthread_attr_setstacksize (3))
 252 for the created threads:
 253 .PP
 254 .in +4n
 255 .EX
 256 .RB "$" " ./a.out \-s 0x100000 hola salut servus"
 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
 263 .EE
 264 .in
 265 .SS Program source
 266 \&
 267 .EX
 268 #include <pthread.h>
 269 #include <string.h>
 270 #include <stdio.h>
 271 #include <stdlib.h>
 272 #include <unistd.h>
 273 #include <errno.h>
 274 #include <ctype.h>
 275
 276 #define handle_error_en(en, msg) \e
 277         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 278
 279 #define handle_error(msg) \e
 280         do { perror(msg); exit(EXIT_FAILURE); } while (0)
 281
 282 struct thread_info {    /* Used as argument to thread_start() */
 283     pthread_t thread_id;        /* ID returned by pthread_create() */
 284     int       thread_num;       /* Application\-defined thread # */
 285     char     *argv_string;      /* From command\-line argument */
 286 };
 287
 288 /* Thread start function: display address near top of our stack,
 289    and return upper\-cased copy of argv_string. */
 290
 291 static void *
 292 thread_start(void *arg)
 293 {
 294     struct thread_info *tinfo = arg;
 295     char *uargv;
 296
 297     printf("Thread %d: top of stack near %p; argv_string=%s\en",
 298             tinfo\->thread_num, (void *) &tinfo, tinfo\->argv_string);
 299
 300     uargv = strdup(tinfo\->argv_string);
 301     if (uargv == NULL)
 302         handle_error("strdup");
 303
 304     for (char *p = uargv; *p != \(aq\e0\(aq; p++)
 305         *p = toupper(*p);
 306
 307     return uargv;
 308 }
 309
 310 int
 311 main(int argc, char *argv[])
 312 {
 313     int s, opt, num_threads;
 314     pthread_attr_t attr;
 315     ssize_t stack_size;
 316     void *res;
 317
 318     /* The "\-s" option specifies a stack size for our threads. */
 319
 320     stack_size = \-1;
 321     while ((opt = getopt(argc, argv, "s:")) != \-1) {
 322         switch (opt) {
 323         case \(aqs\(aq:
 324             stack_size = strtoul(optarg, NULL, 0);
 325             break;
 326
 327         default:
 328             fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en",
 329                     argv[0]);
 330             exit(EXIT_FAILURE);
 331         }
 332     }
 333
 334     num_threads = argc \- optind;
 335
 336     /* Initialize thread creation attributes. */
 337
 338     s = pthread_attr_init(&attr);
 339     if (s != 0)
 340         handle_error_en(s, "pthread_attr_init");
 341
 342     if (stack_size > 0) {
 343         s = pthread_attr_setstacksize(&attr, stack_size);
 344         if (s != 0)
 345             handle_error_en(s, "pthread_attr_setstacksize");
 346     }
 347
 348     /* Allocate memory for pthread_create() arguments. */
 349
 350     struct thread_info *tinfo = calloc(num_threads, sizeof(*tinfo));
 351     if (tinfo == NULL)
 352         handle_error("calloc");
 353
 354     /* Create one thread for each command\-line argument. */
 355
 356     for (int tnum = 0; tnum < num_threads; tnum++) {
 357         tinfo[tnum].thread_num = tnum + 1;
 358         tinfo[tnum].argv_string = argv[optind + tnum];
 359
 360         /* The pthread_create() call stores the thread ID into
 361            corresponding element of tinfo[]. */
 362
 363         s = pthread_create(&tinfo[tnum].thread_id, &attr,
 364                            &thread_start, &tinfo[tnum]);
 365         if (s != 0)
 366             handle_error_en(s, "pthread_create");
 367     }
 368
 369     /* Destroy the thread attributes object, since it is no
 370        longer needed. */
 371
 372     s = pthread_attr_destroy(&attr);
 373     if (s != 0)
 374         handle_error_en(s, "pthread_attr_destroy");
 375
 376     /* Now join with each thread, and display its returned value. */
 377
 378     for (int tnum = 0; tnum < num_threads; tnum++) {
 379         s = pthread_join(tinfo[tnum].thread_id, &res);
 380         if (s != 0)
 381             handle_error_en(s, "pthread_join");
 382
 383         printf("Joined with thread %d; returned value was %s\en",
 384                 tinfo[tnum].thread_num, (char *) res);
 385         free(res);      /* Free memory allocated by thread */
 386     }
 387
 388     free(tinfo);
 389     exit(EXIT_SUCCESS);
 390 }
 391 .EE
 392 .SH SEE ALSO
 393 .ad l
 394 .nh
 395 .BR getrlimit (2),
 396 .BR pthread_attr_init (3),
 397 .BR pthread_cancel (3),
 398 .BR pthread_detach (3),
 399 .BR pthread_equal (3),
 400 .BR pthread_exit (3),
 401 .BR pthread_getattr_np (3),
 402 .BR pthread_join (3),
 403 .BR pthread_self (3),
 404 .BR pthread_setattr_default_np (3),
 405 .BR pthreads (7)