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