__tfork_thread(3) - OpenBSD manual pages

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);

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⟩ as CHILD_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.