NAME
__tfork_thread
,
__tfork
—
create a new kernel thread in the
current process
SYNOPSIS
#include
<unistd.h>
struct __tfork { void *tf_tcb; /* TCB address for new thread */ pid_t *tf_tid; /* where to write child's TID */ void *tf_stack; /* stack address for new thread */ };
pid_t
__tfork_thread
(const
struct __tfork *params,
size_t psize,
void (*startfunc)(void
*), void
*startarg);
pid_t
__tfork
(const
struct __tfork *params,
size_t psize);
DESCRIPTION
The
__tfork_thread
()
function creates a new kernel thread in the current process. The new thread
starts by calling startfunc, passing
startarg as the only argument. If
startfunc returns, the thread will exit.
The params argument provides parameters used by the kernel during thread creation. The new thread's thread control block (TCB) address is set to tf_tcb. If tf_tid is not NULL, the new thread's PID is returned to the user at that address, with the guarantee that this is done before returning to userspace in either the current thread or the new thread. If tf_stack is not NULL, the new thread's stack is initialized to start at that address. On hppa and hppa64, that is the lowest address used; on other architectures that is the address after the highest address used.
The psize argument provides the size of the struct __tfork passed via the params argument.
The underlying system call used to create the thread
is
__tfork
().
Because the new thread returns without a stack frame, the syscall cannot be
directly used from C and is therefore not provided as a function. However,
the syscall may show up in the output of
kdump(1).
RETURN VALUES
Upon successful completion,
__tfork_thread
() returns in the current thread the
PID of new thread. The __tfork
() syscall itself, on
success, returns a value of 0 in the new thread and returns the PID of the
new thread to the current thread. Otherwise, a value of -1 is returned, no
thread is created, and the global variable errno is
set to indicate an error.
ERRORS
__tfork_thread
() and
__tfork
() will fail and no thread will be created
if:
- [
ENOMEM
] - Cannot allocate memory. The new process image required more memory than was allowed by the hardware or by system-imposed memory management constraints. A lack of swap space is normally temporary; however, a lack of core is not. Soft limits may be increased to their corresponding hard limits.
- [
EINVAL
] - Invalid argument. Some invalid argument was supplied.
- [
EAGAIN
] - Resource temporarily unavailable. The system-imposed limit on the total number of threads under execution would be exceeded. This limit is configuration-dependent.
- [
EAGAIN
] - Resource temporarily unavailable. The system-imposed limit
MAXUPRC
on the total number of threads under execution by a single user would be exceeded.MAXUPRC
is currently defined in ⟨sys/param.h⟩ asCHILD_MAX
, which is currently defined as 80 in ⟨sys/syslimits.h⟩. - [
ENOTSUP
] - The kern.rthreads sysctl was not enabled.
STANDARDS
The __tfork_thread
() function and
__tfork
() syscall are specific to
OpenBSD and should not be used in portable
applications.
HISTORY
The __tfork_thread
() function and
__tfork
() syscall appeared in
OpenBSD 5.1.