Changeset View
Changeset View
Standalone View
Standalone View
head/lib/libc/sys/thr_new.2
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" This documentation was written by | |||||
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship | |||||
.\" from the FreeBSD Foundation. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd May 5, 2016 | |||||
.Dt THR_NEW 2 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm thr_new | |||||
.Nd create new thread of execution | |||||
.Sh LIBRARY | |||||
.Lb libc | |||||
.Sh SYNOPSIS | |||||
.In sys/thr.h | |||||
.Ft int | |||||
.Fn thr_new "struct thr_param *param" "int param_size" | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Fn thr_new | |||||
system call creates a new kernel-scheduled thread of execution in the context | |||||
of the current process. | |||||
The newly created thread shares all attributes of the process with the | |||||
existing kernel-scheduled threads in the process, but has private processor | |||||
execution state. | |||||
The machine context for the new thread is copied from the creating thread's | |||||
context, including coprocessor state. | |||||
FPU state and specific machine registers are excluded from the copy. | |||||
These are set according to ABI requirements and syscall parameters. | |||||
The FPU state for new thread is reinitialized to clean. | |||||
.Pp | |||||
The | |||||
.Fa param | |||||
structure supplies parameters affecting the thread creation. | |||||
The structure is defined in the | |||||
.In sys/thr.h | |||||
header as follows | |||||
.Bd -literal | |||||
struct thr_param { | |||||
void (*start_func)(void *); | |||||
void *arg; | |||||
char *stack_base; | |||||
size_t stack_size; | |||||
char *tls_base; | |||||
size_t tls_size; | |||||
long *child_tid; | |||||
long *parent_tid; | |||||
int flags; | |||||
struct rtprio *rtp; | |||||
}; | |||||
.Ed | |||||
and contains the following fields: | |||||
.Bl -tag -width ".Va parent_tid" | |||||
.It Va start_func | |||||
The pointer to the thread entry function. | |||||
Kernel arranges for the new thread to start executing the function | |||||
upon the first return to userspace. | |||||
.It Va arg | |||||
Opaque argument supplied to the entry function. | |||||
.It Va stack_base | |||||
Stack base address. | |||||
The stack must be allocated by the caller. | |||||
On some architectures, the ABI might require that system put information | |||||
on the stack to ensure the execution environment for | |||||
.Va start_func . | |||||
.It Va stack_size | |||||
Stack size. | |||||
.It Va tls_base | |||||
TLS base address. | |||||
The value of TLS base is loaded to the ABI-defined machine register | |||||
in the new thread context. | |||||
.It Va tls_size | |||||
TLS size. | |||||
.It Va child_tid | |||||
Address to store the new thread identifier, for the child's use. | |||||
.It Va parent_tid | |||||
Address to store the new thread identifier, for the parent's use. | |||||
.Pp | |||||
Both | |||||
.Va child_tid | |||||
and | |||||
.Va parent_tid | |||||
are provided, with the intent that | |||||
.Va child_tid | |||||
is used by the new thread to get its thread identifier without | |||||
issuing the | |||||
.Xr thr_self 2 | |||||
syscall, while | |||||
.Va parent_tid | |||||
is used by the thread creator. | |||||
The later is separate from the | |||||
.Va child_tid | |||||
because new thread might exit and free its thread data before parent | |||||
has a chance to execute far enough to access it. | |||||
.It Va flags | |||||
Thread creation flags. | |||||
The | |||||
.Va flags | |||||
member may specify the following flags: | |||||
.Bl -tag -width ".Dv THR_SYSTEM_SCOPE" | |||||
.It Dv THR_SUSPENDED | |||||
Create the new thread in the suspended state. | |||||
The flag is not currently implemented. | |||||
.It Dv THR_SYSTEM_SCOPE | |||||
Create the system scope thread. | |||||
The flag is not currently implemented. | |||||
.El | |||||
.It Va rtp | |||||
Real-time scheduling priority for the new thread. | |||||
May be NULL if thread should inherit the priority from the | |||||
creating thread. | |||||
.El | |||||
.Pp | |||||
The | |||||
.Fa param_size | |||||
argument should be set to the size of the | |||||
.Fa param | |||||
structure. | |||||
.Pp | |||||
After the first successful creation of an additional thread, | |||||
the process is marked by the kernel as multi-threaded. | |||||
In particular, the | |||||
.Dv P_HADTHREADS | |||||
flag is set in the process' | |||||
.Dv p_flag | |||||
(visible in the | |||||
.Xr ps 1 | |||||
output), and several operations are executed in multi-threaded mode. | |||||
For instance, the | |||||
.Xr execve 2 | |||||
system call terminates all threads but the calling one on successful | |||||
execution. | |||||
.Sh RETURN VALUES | |||||
If successful, | |||||
.Fn thr_new | |||||
will return zero, otherwise \-1 is returned, and | |||||
.Va errno | |||||
is set to indicate the error. | |||||
.Sh ERRORS | |||||
The | |||||
.Fn thr_new | |||||
operation returns the following errors: | |||||
.Bl -tag -width Er | |||||
.It Bq Er EFAULT | |||||
The memory pointed to by the | |||||
.Fa param | |||||
argument is not valid. | |||||
.It Bq Er EFAULT | |||||
The memory pointed to by the | |||||
.Fa param | |||||
structure | |||||
.Fa child_tid , parent_tid | |||||
or | |||||
.Fa rtp | |||||
arguments is not valid. | |||||
.It Bq Er EFAULT | |||||
Specified stack base is invalid, or the kernel was unable to put required | |||||
initial data on the stack. | |||||
.It Bq Er EINVAL | |||||
The | |||||
.Fa param_size | |||||
argument specifies negative value, or its value is greater than the | |||||
largest | |||||
.Fa struct param | |||||
size the kernel can interpret. | |||||
.It Bq Er EINVAL | |||||
The | |||||
.Fa rtp | |||||
member is not NULL, but specifies invalid scheduling parameters. | |||||
.It Bq Er EINVAL | |||||
The specified TLS base is invalid. | |||||
.It Bq Er EPROCLIM | |||||
Creation of the new thread would exceed the | |||||
.Dv RACCT_NTHR | |||||
limit, see | |||||
.Xr racct 2 . | |||||
.It Bq Er EPROCLIM | |||||
Creation of the new thread would exceed the | |||||
.Dv kern.threads.max_threads_per_proc | |||||
.Xr sysctl 2 | |||||
limit. | |||||
.It Bq Er ENOMEM | |||||
No kernel memory to allocate for the new thread structures. | |||||
.El | |||||
.Sh SEE ALSO | |||||
.Xr ps 1 , | |||||
.Xr execve 2 , | |||||
.Xr racct 2 , | |||||
.Xr thr_exit 2 , | |||||
.Xr thr_kill 2 , | |||||
.Xr thr_kill2 2 , | |||||
.Xr thr_self 2 , | |||||
.Xr thr_set_name 2 , | |||||
.Xr _umtx_op 2 | |||||
.Sh STANDARDS | |||||
The | |||||
.Fn thr_new | |||||
system call is non-standard and is used by the | |||||
.Lb libthr | |||||
to implement | |||||
.St -p1003.1-2001 | |||||
.Xr pthread(3) | |||||
functionality. |