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, 2020
  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 .Bf -symbolic
  45 This function is intended for implementing threading.
  46 Normal applications should call
  47 .Xr pthread_create 3
  48 instead.
  49 .Ef
  50 .Pp
  51 The
  52 .Fn thr_new
  53 system call creates a new kernel-scheduled thread of execution in the context
  54 of the current process.
  55 The newly created thread shares all attributes of the process with the
  56 existing kernel-scheduled threads in the process, but has private processor
  57 execution state.
  58 The machine context for the new thread is copied from the creating thread's
  59 context, including coprocessor state.
  60 FPU state and specific machine registers are excluded from the copy.
  61 These are set according to ABI requirements and syscall parameters.
  62 The FPU state for the new thread is reinitialized to clean.
  63 .Pp
  64 The
  65 .Fa param
  66 structure supplies parameters affecting the thread creation.
  67 The structure is defined in the
  68 .In sys/thr.h
  69 header as follows
  70 .Bd -literal
  71 struct thr_param {
  72     void          (*start_func)(void *);
  73     void          *arg;
  74     char          *stack_base;
  75     size_t        stack_size;
  76     char          *tls_base;
  77     size_t        tls_size;
  78     long          *child_tid;
  79     long          *parent_tid;
  80     int           flags;
  81     struct rtprio *rtp;
  82 };
  83 .Ed
  84 and contains the following fields:
  85 .Bl -tag -width ".Va parent_tid"
  86 .It Va start_func
  87 Pointer to the thread entry function.
  88 The kernel arranges for the new thread to start executing the function
  89 upon the first return to userspace.
  90 .It Va arg
  91 Opaque argument supplied to the entry function.
  92 .It Va stack_base
  93 Stack base address.
  94 The stack must be allocated by the caller.
  95 On some architectures, the ABI might require that the system put information
  96 on the stack to ensure the execution environment for
  97 .Va start_func .
  98 .It Va stack_size
  99 Stack size.
 100 .It Va tls_base
 101 TLS base address.
 102 The value of TLS base is loaded into the ABI-defined machine register
 103 in the new thread context.
 104 .It Va tls_size
 105 TLS size.
 106 .It Va child_tid
 107 Address to store the new thread identifier, for the child's use.
 108 .It Va parent_tid
 109 Address to store the new thread identifier, for the parent's use.
 110 .Pp
 111 Both
 112 .Va child_tid
 113 and
 114 .Va parent_tid
 115 are provided, with the intent that
 116 .Va child_tid
 117 is used by the new thread to get its thread identifier without
 118 issuing the
 119 .Xr thr_self 2
 120 syscall, while
 121 .Va parent_tid
 122 is used by the thread creator.
 123 The latter is separate from
 124 .Va child_tid
 125 because the new thread might exit and free its thread data before the parent
 126 has a chance to execute far enough to access it.
 127 .It Va flags
 128 Thread creation flags.
 129 The
 130 .Va flags
 131 member may specify the following flags:
 132 .Bl -tag -width ".Dv THR_SYSTEM_SCOPE"
 133 .It Dv THR_SUSPENDED
 134 Create the new thread in the suspended state.
 135 The flag is not currently implemented.
 136 .It Dv THR_SYSTEM_SCOPE
 137 Create the system scope thread.
 138 The flag is not currently implemented.
 139 .El
 140 .It Va rtp
 141 Real-time scheduling priority for the new thread.
 142 May be
 143 .Dv NULL
 144 to inherit the priority from the
 145 creating thread.
 146 .El
 147 .Pp
 148 The
 149 .Fa param_size
 150 argument should be set to the size of the
 151 .Fa param
 152 structure.
 153 .Pp
 154 After the first successful creation of an additional thread,
 155 the process is marked by the kernel as multi-threaded.
 156 In particular, the
 157 .Dv P_HADTHREADS
 158 flag is set in the process'
 159 .Dv p_flag
 160 (visible in the
 161 .Xr ps 1
 162 output), and several operations are executed in multi-threaded mode.
 163 For instance, the
 164 .Xr execve 2
 165 system call terminates all threads but the calling one on successful
 166 execution.
 167 .Sh RETURN VALUES
 168 If successful,
 169 .Fn thr_new
 170 will return zero, otherwise \-1 is returned, and
 171 .Va errno
 172 is set to indicate the error.
 173 .Sh ERRORS
 174 The
 175 .Fn thr_new
 176 operation returns the following errors:
 177 .Bl -tag -width Er
 178 .\" When changing this list, consider updating share/man/man3/pthread_create.3,
 179 .\" since that function can return any of these errors.
 180 .It Bq Er EFAULT
 181 The memory pointed to by the
 182 .Fa param
 183 argument is not valid.
 184 .It Bq Er EFAULT
 185 The memory pointed to by the
 186 .Fa param
 187 structure
 188 .Fa child_tid , parent_tid
 189 or
 190 .Fa rtp
 191 arguments is not valid.
 192 .It Bq Er EFAULT
 193 The specified stack base is invalid, or the kernel was unable to put required
 194 initial data on the stack.
 195 .It Bq Er EINVAL
 196 The
 197 .Fa param_size
 198 argument specifies a negative value, or the value is greater than the
 199 largest
 200 .Fa struct param
 201 size the kernel can interpret.
 202 .It Bq Er EINVAL
 203 The
 204 .Fa rtp
 205 member is not
 206 .Dv NULL
 207 and specifies invalid scheduling parameters.
 208 .It Bq Er EINVAL
 209 The specified TLS base is invalid.
 210 .It Bq Er EPERM
 211 The caller does not have permission to set the scheduling parameters or
 212 scheduling policy.
 213 .It Bq Er EPROCLIM
 214 Creation of the new thread would exceed the
 215 .Dv RACCT_NTHR
 216 limit, see
 217 .Xr racct 2 .
 218 .It Bq Er EPROCLIM
 219 Creation of the new thread would exceed the
 220 .Dv kern.threads.max_threads_per_proc
 221 .Xr sysctl 2
 222 limit.
 223 .It Bq Er ENOMEM
 224 There was not enough kernel memory to allocate the new thread structures.
 225 .El
 226 .Sh SEE ALSO
 227 .Xr ps 1 ,
 228 .Xr _umtx_op 2 ,
 229 .Xr execve 2 ,
 230 .Xr racct 2 ,
 231 .Xr thr_exit 2 ,
 232 .Xr thr_kill 2 ,
 233 .Xr thr_kill2 2 ,
 234 .Xr thr_self 2 ,
 235 .Xr thr_set_name 2 ,
 236 .Xr pthread_create 3
 237 .Sh STANDARDS
 238 The
 239 .Fn thr_new
 240 system call is non-standard and is used by the
 241 .Lb libthr
 242 to implement
 243 .St -p1003.1-2001
 244 .Xr pthread 3
 245 functionality.
 246 .Sh HISTORY
 247 The
 248 .Fn thr_new
 249 system call first appeared in
 250 .Fx 5.2 .