unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

__TFORK_THREAD(3)        BSD Library Functions Manual        __TFORK_THREAD(3)

NAME
     __tfork_thread, __tfork -- create a new kernel thread in the current
     process

SYNOPSIS
     #include <&lt;unistd.h>&gt;

     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 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 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-depen-
                        dent.

     [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>.

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.

BSD                            January 15, 2015                            BSD