1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
2 .\" All rights reserved.
4 .\" This documentation was written by
5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
6 .\" from the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
36 .Nd create new thread of execution
42 .Fn thr_new "struct thr_param *param" "int param_size"
45 This function is intended for implementing threading.
46 Normal applications should call
53 system call creates a new kernel-scheduled thread of execution in the context
54 of the current process.
55 The newly created thread shares all attributes of the process with the
56 existing kernel-scheduled threads in the process, but has private processor
58 The machine context for the new thread is copied from the creating thread's
59 context, including coprocessor state.
60 FPU state and specific machine registers are excluded from the copy.
61 These are set according to ABI requirements and syscall parameters.
62 The FPU state for the new thread is reinitialized to clean.
66 structure supplies parameters affecting the thread creation.
67 The structure is defined in the
72 void (*start_func)(void *);
84 and contains the following fields:
85 .Bl -tag -width ".Va parent_tid"
87 Pointer to the thread entry function.
88 The kernel arranges for the new thread to start executing the function
89 upon the first return to userspace.
91 Opaque argument supplied to the entry function.
94 The stack must be allocated by the caller.
95 On some architectures, the ABI might require that the system put information
96 on the stack to ensure the execution environment for
102 The value of TLS base is loaded into the ABI-defined machine register
103 in the new thread context.
107 Address to store the new thread identifier, for the child's use.
109 Address to store the new thread identifier, for the parent's use.
115 are provided, with the intent that
117 is used by the new thread to get its thread identifier without
122 is used by the thread creator.
123 The latter is separate from
125 because the new thread might exit and free its thread data before the parent
126 has a chance to execute far enough to access it.
128 Thread creation flags.
131 member may specify the following flags:
132 .Bl -tag -width ".Dv THR_SYSTEM_SCOPE"
134 Create the new thread in the suspended state.
135 The flag is not currently implemented.
136 .It Dv THR_SYSTEM_SCOPE
137 Create the system scope thread.
138 The flag is not currently implemented.
141 Real-time scheduling priority for the new thread.
144 to inherit the priority from the
150 argument should be set to the size of the
154 After the first successful creation of an additional thread,
155 the process is marked by the kernel as multi-threaded.
158 flag is set in the process'
162 output), and several operations are executed in multi-threaded mode.
165 system call terminates all threads but the calling one on successful
170 will return zero, otherwise \-1 is returned, and
172 is set to indicate the error.
176 operation returns the following errors:
178 .\" When changing this list, consider updating share/man/man3/pthread_create.3,
179 .\" since that function can return any of these errors.
181 The memory pointed to by the
183 argument is not valid.
185 The memory pointed to by the
188 .Fa child_tid , parent_tid
191 arguments is not valid.
193 The specified stack base is invalid, or the kernel was unable to put required
194 initial data on the stack.
198 argument specifies a negative value, or the value is greater than the
201 size the kernel can interpret.
207 and specifies invalid scheduling parameters.
209 The specified TLS base is invalid.
211 The caller does not have permission to set the scheduling parameters or
214 Creation of the new thread would exceed the
219 Creation of the new thread would exceed the
220 .Dv kern.threads.max_threads_per_proc
224 There was not enough kernel memory to allocate the new thread structures.
240 system call is non-standard and is used by the