lib/libc/sys/thr_new.2

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