THREAD_CREATE(3T)                    BSD                     THREAD_CREATE(3T)



NAME
     thread_create - create a new thread

SYNOPSIS
     include <apollo/thread.h>
     kern_return_t thread_create(process_id, child_thread)
     pid_t process_id;
     thread_t *child_thread;

DESCRIPTION
     The thread_create call creates a new thread in the address space of the
     specified process.  All kernel state will be allocated, except for the
     CPU register state, then the new thread will be put in suspended state.

     The arguments are as follows:

     process_id
               The process in which to create the new thread.  The legal
               values for this argument are the pid of an existing process or
               0, meaning the current process.

     child_thread
               The id of the newly created thread will be placed in this
               output argument.


     Data Structures
     The basic data structures are defined as follows:

     thread_t
          The basic thread id.  This will be a black box value that will not
          be significant outside the thread system.  It will be guaranteed
          that no two active threads on a node will have the same thread id.

     pid_t
          The process id, as defined by POSIX.1 (IEEE P1003.1).

     kern_return_t
          An enumeration of the possible values a system call can return.  It
          indicates the success or failure of the call.  It will either be
          KERN_SUCCESS to indicate that the call succeeded, or some other
          value to describe the reason for the failure.

DIAGNOSTICS
     Upon successful completion, a new thread is created and thread_create
     returns [KERN_SUCCESS]; otherwise, errno is set to indicate the error.

ERRORS
     This function fails if:

     [KERN_INVALID_ARGUMENT]
               The process_id is not a valid process and not 0.

     [KERN_RESOURCE_SHORTAGE]
               Some kernel resource can not be allocated for the new thread.

     [KERN_PROTECTION_FAILURE]
               This process does not have sufficient rights to create a thread
               in the target process.

SEE ALSO

     thread_terminate(2P), thread_suspend(2P), thread_resume(2P),
     thread_abort(2P), thread_self(2P), thread_info(2P), thread_state(2P),
     thread_set_priority(2P), thread_handle_signals(2P), thread_inhibit(2P),
     thread_cleanup(2P), thread_startup(2P), threadp_init(2P),
     threadp_set(2P), threadp_get(2P).

     Section (3P) pthread calls (IEEE P1003.4a) calls
     Domain System Software Release Notes, Software Release 10.4

NOTES
     This call is part of the low level Domain/OS Pthread interface.  Most of
     these calls come directly from the Mach thread interface, with a few
     calls added to provide additional functionality.  Except as noted, they
     work exactly like the equivalent Mach call.  The calls work between
     processes (the thread id is unique for a node) if the calling process has
     the appropriate rights relative to the target process.

     This call is provided solely for compatibility with the Mach operating
     system. New applications should use the Pthread interface instead.