lib/libc/sys/thr_new.2

   1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by
   5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   6 .\" from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 5, 2016
  32 .Dt THR_NEW 2
  33 .Os
  34 .Sh NAME
  35 .Nm thr_new
  36 .Nd create new thread of execution
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/thr.h
  41 .Ft int
  42 .Fn thr_new "struct thr_param *param" "int param_size"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn thr_new
  46 system call creates a new kernel-scheduled thread of execution in the context
  47 of the current process.
  48 The newly created thread shares all attributes of the process with the
  49 existing kernel-scheduled threads in the process, but has private processor
  50 execution state.
  51 The machine context for the new thread is copied from the creating thread's
  52 context, including coprocessor state.
  53 FPU state and specific machine registers are excluded from the copy.
  54 These are set according to ABI requirements and syscall parameters.
  55 The FPU state for the new thread is reinitialized to clean.
  56 .Pp
  57 The
  58 .Fa param
  59 structure supplies parameters affecting the thread creation.
  60 The structure is defined in the
  61 .In sys/thr.h
  62 header as follows
  63 .Bd -literal
  64 struct thr_param {
  65     void          (*start_func)(void *);
  66     void          *arg;
  67     char          *stack_base;
  68     size_t        stack_size;
  69     char          *tls_base;
  70     size_t        tls_size;
  71     long          *child_tid;
  72     long          *parent_tid;
  73     int           flags;
  74     struct rtprio *rtp;
  75 };
  76 .Ed
  77 and contains the following fields:
  78 .Bl -tag -width ".Va parent_tid"
  79 .It Va start_func
  80 Pointer to the thread entry function.
  81 The kernel arranges for the new thread to start executing the function
  82 upon the first return to userspace.
  83 .It Va arg
  84 Opaque argument supplied to the entry function.
  85 .It Va stack_base
  86 Stack base address.
  87 The stack must be allocated by the caller.
  88 On some architectures, the ABI might require that the system put information
  89 on the stack to ensure the execution environment for
  90 .Va start_func .
  91 .It Va stack_size
  92 Stack size.
  93 .It Va tls_base
  94 TLS base address.
  95 The value of TLS base is loaded into the ABI-defined machine register
  96 in the new thread context.
  97 .It Va tls_size
  98 TLS size.
  99 .It Va child_tid
 100 Address to store the new thread identifier, for the child's use.
 101 .It Va parent_tid
 102 Address to store the new thread identifier, for the parent's use.
 103 .Pp
 104 Both
 105 .Va child_tid
 106 and
 107 .Va parent_tid
 108 are provided, with the intent that
 109 .Va child_tid
 110 is used by the new thread to get its thread identifier without
 111 issuing the
 112 .Xr thr_self 2
 113 syscall, while
 114 .Va parent_tid
 115 is used by the thread creator.
 116 The latter is separate from
 117 .Va child_tid
 118 because the new thread might exit and free its thread data before the parent
 119 has a chance to execute far enough to access it.
 120 .It Va flags
 121 Thread creation flags.
 122 The
 123 .Va flags
 124 member may specify the following flags:
 125 .Bl -tag -width ".Dv THR_SYSTEM_SCOPE"
 126 .It Dv THR_SUSPENDED
 127 Create the new thread in the suspended state.
 128 The flag is not currently implemented.
 129 .It Dv THR_SYSTEM_SCOPE
 130 Create the system scope thread.
 131 The flag is not currently implemented.
 132 .El
 133 .It Va rtp
 134 Real-time scheduling priority for the new thread.
 135 May be
 136 .Dv NULL
 137 to inherit the priority from the
 138 creating thread.
 139 .El
 140 .Pp
 141 The
 142 .Fa param_size
 143 argument should be set to the size of the
 144 .Fa param
 145 structure.
 146 .Pp
 147 After the first successful creation of an additional thread,
 148 the process is marked by the kernel as multi-threaded.
 149 In particular, the
 150 .Dv P_HADTHREADS
 151 flag is set in the process'
 152 .Dv p_flag
 153 (visible in the
 154 .Xr ps 1
 155 output), and several operations are executed in multi-threaded mode.
 156 For instance, the
 157 .Xr execve 2
 158 system call terminates all threads but the calling one on successful
 159 execution.
 160 .Sh RETURN VALUES
 161 If successful,
 162 .Fn thr_new
 163 will return zero, otherwise \-1 is returned, and
 164 .Va errno
 165 is set to indicate the error.
 166 .Sh ERRORS
 167 The
 168 .Fn thr_new
 169 operation returns the following errors:
 170 .Bl -tag -width Er
 171 .It Bq Er EFAULT
 172 The memory pointed to by the
 173 .Fa param
 174 argument is not valid.
 175 .It Bq Er EFAULT
 176 The memory pointed to by the
 177 .Fa param
 178 structure
 179 .Fa child_tid , parent_tid
 180 or
 181 .Fa rtp
 182 arguments is not valid.
 183 .It Bq Er EFAULT
 184 Specified stack base is invalid, or the kernel was unable to put required
 185 initial data on the stack.
 186 .It Bq Er EINVAL
 187 The
 188 .Fa param_size
 189 argument specifies a negative value, or the value is greater than the
 190 largest
 191 .Fa struct param
 192 size the kernel can interpret.
 193 .It Bq Er EINVAL
 194 The
 195 .Fa rtp
 196 member is not
 197 .Dv NULL
 198 and specifies invalid scheduling parameters.
 199 .It Bq Er EINVAL
 200 The specified TLS base is invalid.
 201 .It Bq Er EPROCLIM
 202 Creation of the new thread would exceed the
 203 .Dv RACCT_NTHR
 204 limit, see
 205 .Xr racct 2 .
 206 .It Bq Er EPROCLIM
 207 Creation of the new thread would exceed the
 208 .Dv kern.threads.max_threads_per_proc
 209 .Xr sysctl 2
 210 limit.
 211 .It Bq Er ENOMEM
 212 No kernel memory to allocate for the new thread structures.
 213 .El
 214 .Sh SEE ALSO
 215 .Xr ps 1 ,
 216 .Xr execve 2 ,
 217 .Xr racct 2 ,
 218 .Xr thr_exit 2 ,
 219 .Xr thr_kill 2 ,
 220 .Xr thr_kill2 2 ,
 221 .Xr thr_self 2 ,
 222 .Xr thr_set_name 2 ,
 223 .Xr _umtx_op 2
 224 .Sh STANDARDS
 225 The
 226 .Fn thr_new
 227 system call is non-standard and is used by the
 228 .Lb libthr
 229 to implement
 230 .St -p1003.1-2001
 231 .Xr pthread 3
 232 functionality.