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