share/man/man3c/thrd_create.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd "Jan 13, 2015"
  15 .Dt THRD_CREATE 3C
  16 .Os
  17 .Sh NAME
  18 .Nm thrd_create
  19 .Nd create a thread
  20 .Sh SYNOPSIS
  21 .In threads.h
  22 .Vt "typedef int (*thrd_start_t)(void *);"
  23 .Ft int
  24 .Fo thrd_create
  25 .Fa "thrd_t *thrdp"
  26 .Fa "thrd_start_t func"
  27 .Fa "void *arg"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fn thrd_create
  32 function creates a new thread of execution inside of the current
  33 process and stores its identifier in
  34 .Fa thrdp .
  35 Each thread operates concurrently within the process.
  36 .Pp
  37 When a thread is created, it begins its execution at the function
  38 .Fa func
  39 with the argument
  40 .Fa arg .
  41 A created thread has access to all global data within a process;
  42 however, it has its own private stack.
  43 Currently 32-bit processes have a default stack of 1 megabyte, while 64-bit
  44 systems have a default stack size of 2 megabytes.
  45 In addition, newly created threads inherit the signal mask of the thread which
  46 created them; however, they do not inherit any pending signals.
  47 .Pp
  48 Once created, a thread will continue to execute until either, it returns
  49 from its initial function, the thread explicitly calls
  50 .Xr thrd_exit 3C ,
  51 or the process itself terminates, such as with a call to
  52 .Xr exit 2 .
  53 When the initial function returns, it behaves as though a call to
  54 .Xr thrd_exit 3C
  55 was made, and, if the thread has not been detached with a call to
  56 .Xr thrd_detach 3C ,
  57 the exit status remains available and the corresponding thread ID will
  58 not be reused until a process calls
  59 .Xr thrd_join 3C .
  60 This is similar to how a parent must call
  61 .Xr wait 3C ,
  62 to clean up a child process that has terminated.
  63 .Pp
  64 For a richer interface interface with more control over aspects of the
  65 newly created thread, such as stack size, stack placement, and the like,
  66 see
  67 .Xr thr_create 3C
  68 and
  69 .Xr pthread_create 3C .
  70 .Sh RETURN VALUES
  71 Upon successful completion, the
  72 .Fn thrd_create
  73 function returns
  74 .Sy thrd_success .
  75 If insufficient memory was available, then
  76 .Sy thrd_nomem
  77 is returned.
  78 Otherwise,
  79 .Sy thrd_error
  80 is returned, indicating that a non-memory related error.
  81 .Sh INTERFACE STABILITY
  82 .Sy Standard
  83 .Sh MT-LEVEL
  84 .Sy MT-Safe
  85 .Sh SEE ALSO
  86 .Xr pthread_create 3C ,
  87 .Xr thr_create 3C ,
  88 .Xr thrd_detach 3C ,
  89 .Xr thrd_join 3C ,
  90 .Xr attributes 5 ,
  91 .Xr threads 5