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