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 thread ID */ 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 thread ID is returned to the user at that address, with the guarantee that this is done before returning to userspace in either the calling 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 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 calling thread the
thread ID of new thread. The __tfork
() syscall
itself, on success, returns a value of 0 in the new thread and returns the
thread ID of the new thread to the calling 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>
.
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.