1.\" Copyright (c) 2016 The FreeBSD Foundation 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.It Dv THR_C_RUNTIME 137Indicate that the new thread is created by the C language runtime. 138It has architecture-specific meaning. 139.Pp 140On amd64, the flag requests that the specified 141.Fa tls_base 142was loaded into the 143.Va %fsbase 144register before calling a signal handler. 145.El 146.It Va rtp 147Real-time scheduling priority for the new thread. 148May be 149.Dv NULL 150to inherit the priority from the 151creating thread. 152.El 153.Pp 154The 155.Fa param_size 156argument should be set to the size of the 157.Fa param 158structure. 159.Pp 160After the first successful creation of an additional thread, 161the process is marked by the kernel as multi-threaded. 162In particular, the 163.Dv P_HADTHREADS 164flag is set in the process' 165.Dv p_flag 166(visible in the 167.Xr ps 1 168output), and several operations are executed in multi-threaded mode. 169For instance, the 170.Xr execve 2 171system call terminates all threads but the calling one on successful 172execution. 173.Sh RETURN VALUES 174If successful, 175.Fn thr_new 176will return zero, otherwise \-1 is returned, and 177.Va errno 178is set to indicate the error. 179.Sh ERRORS 180The 181.Fn thr_new 182operation returns the following errors: 183.Bl -tag -width Er 184.\" When changing this list, consider updating share/man/man3/pthread_create.3, 185.\" since that function can return any of these errors. 186.It Bq Er EFAULT 187The memory pointed to by the 188.Fa param 189argument is not valid. 190.It Bq Er EFAULT 191The memory pointed to by the 192.Fa param 193structure 194.Fa child_tid , parent_tid 195or 196.Fa rtp 197arguments is not valid. 198.It Bq Er EFAULT 199The specified stack base is invalid, or the kernel was unable to put required 200initial data on the stack. 201.It Bq Er EINVAL 202The 203.Fa param_size 204argument specifies a negative value, or the value is greater than the 205largest 206.Fa struct param 207size the kernel can interpret. 208.It Bq Er EINVAL 209The 210.Fa rtp 211member is not 212.Dv NULL 213and specifies invalid scheduling parameters. 214.It Bq Er EINVAL 215The specified TLS base is invalid. 216.It Bq Er EPERM 217The caller does not have permission to set the scheduling parameters or 218scheduling policy. 219.It Bq Er EPROCLIM 220Creation of the new thread would exceed the 221.Dv RACCT_NTHR 222limit, see 223.Xr rctl_get_racct 2 . 224.It Bq Er EPROCLIM 225Creation of the new thread would exceed the 226.Dv kern.threads.max_threads_per_proc 227.Xr sysctl 3 228limit. 229.It Bq Er ENOMEM 230There was not enough kernel memory to allocate the new thread structures. 231.El 232.Sh SEE ALSO 233.Xr ps 1 , 234.Xr _umtx_op 2 , 235.Xr execve 2 , 236.Xr rctl_get_racct 2 , 237.Xr thr_exit 2 , 238.Xr thr_kill 2 , 239.Xr thr_kill2 2 , 240.Xr thr_self 2 , 241.Xr thr_set_name 2 , 242.Xr pthread_create 3 243.Sh STANDARDS 244The 245.Fn thr_new 246system call is non-standard and is used by the 247.Lb libthr 248to implement 249.St -p1003.1-2001 250.Xr pthread 3 251functionality. 252.Sh HISTORY 253The 254.Fn thr_new 255system call first appeared in 256.Fx 5.2 . 257