1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
3 .\" This documentation was written by
4 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
5 .\" from the FreeBSD Foundation.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nd create new thread of execution
41 .Fn thr_new "struct thr_param *param" "int param_size"
44 This function is intended for implementing threading.
45 Normal applications should call
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
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.
65 structure supplies parameters affecting the thread creation.
66 The structure is defined in the
71 void (*start_func)(void *);
83 and contains the following fields:
84 .Bl -tag -width ".Va parent_tid"
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.
90 Opaque argument supplied to the entry function.
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
101 The value of TLS base is loaded into the ABI-defined machine register
102 in the new thread context.
106 Address to store the new thread identifier, for the child's use.
108 Address to store the new thread identifier, for the parent's use.
114 are provided, with the intent that
116 is used by the new thread to get its thread identifier without
121 is used by the thread creator.
122 The latter is separate from
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.
127 Thread creation flags.
130 member may specify the following flags:
131 .Bl -tag -width ".Dv THR_SYSTEM_SCOPE"
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.
140 Real-time scheduling priority for the new thread.
143 to inherit the priority from the
149 argument should be set to the size of the
153 After the first successful creation of an additional thread,
154 the process is marked by the kernel as multi-threaded.
157 flag is set in the process'
161 output), and several operations are executed in multi-threaded mode.
164 system call terminates all threads but the calling one on successful
169 will return zero, otherwise \-1 is returned, and
171 is set to indicate the error.
175 operation returns the following errors:
177 .\" When changing this list, consider updating share/man/man3/pthread_create.3,
178 .\" since that function can return any of these errors.
180 The memory pointed to by the
182 argument is not valid.
184 The memory pointed to by the
187 .Fa child_tid , parent_tid
190 arguments is not valid.
192 The specified stack base is invalid, or the kernel was unable to put required
193 initial data on the stack.
197 argument specifies a negative value, or the value is greater than the
200 size the kernel can interpret.
206 and specifies invalid scheduling parameters.
208 The specified TLS base is invalid.
210 The caller does not have permission to set the scheduling parameters or
213 Creation of the new thread would exceed the
216 .Xr rctl_get_racct 2 .
218 Creation of the new thread would exceed the
219 .Dv kern.threads.max_threads_per_proc
223 There was not enough kernel memory to allocate the new thread structures.
229 .Xr rctl_get_racct 2 ,
239 system call is non-standard and is used by the
248 system call first appeared in