THREAD_STATE(3T)                     SysV                     THREAD_STATE(3T)



NAME
     thread_state: thread_get_state, thread_set_state - get or set the CPU
     state of the thread.

SYNOPSIS
     include <apollo/thread.h>

     kern_return_t thread_get_state(target_thread, flavor, old_state,
     old_state_size)
     thread_t target_thread;
     unsigned int flavor;
     void *old_state;
     unsigned int *old_state_size;

     kern_return_t thread_set_state(target_thread, flavor, new_state,
     new_state_size)
     thread_t target_thread;
     unsigned int flavor;
     void *new_state;
     unsigned int new_state_size;


DESCRIPTION
     The thread_state calls get or set the CPU state of the thread.  This
     information is inherently machine-dependent and requires complete
     knowledge of register usage of a particular machine.  This state must
     include a user stack pointer and a PC to begin execution.

     The arguments are as follows:

     target_thread
               The thread to get or set the state for.  This cannot be the
               current thread.

     flavor    The type of state that is to be copied out or in.  This is
               dependent on the type of machine that it is currently running
               on and must be one of A88K_IP_STATE, A88K_FP_STATE,
               M68K_IP_STATE, or M68K_FP_STATE.

     old_state A pointer to where to put the state information.  Current valid
               types are thread_state_data_t (for IP_STATE) and
               thread_fp_state_data_t (for FP_STATE).

     new_state A pointer to where to get the new state information.  Current
               valid types are thread_state_data_t (for IP_STATE) and
               thread_fp_state_data_t (for FP_STATE).

     old_state_size
               The size of the state structure

     new_state_size
               The size of the new state structure.

     Data Structures
     The data structures are defined as follows:

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

     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.  Upon successful
          completion, these calls return [KERN_SUCCESS]; otherwise, errno is
          set to indicate the error.

WARNING
     The Use of thread_set_state at any time other than creation of a thread
     may corrupt critical user state and/or stack state and is not
     recommended.

DIAGNOSTICS
     Upon successful completion, thread_get_state and thread_set_state return
     [KERN_SUCCESS]; otherwise, errno is set to indicate the error.

ERRORS
     thread_get_state or thread_set_state fail if:

     [KERN_INVALID_ARGUMENT]
               The thread specified can not be found or is the current thread
               or flavor is not valid for this machine or the specified size
               is wrong for this flavor.

     [KERN_PROTECTION_FAILURE]
               The process this thread is in does not have sufficient rights
               to get or set state in the target thread.

SEE ALSO
     thread_create(3T), thread_terminate(3T), thread_suspend(3T),
     thread_resume(3T), thread_abort(3T), thread_self(3T), thread_info(3T),
     thread_set_priority(3T), thread_handle_signals(3T), thread_inhibit(3T),
     thread_cleanup(3T), thread_startup(3T), threadp_init(3T),
     threadp_set(3T), threadp_get(3T).

     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.  Except as
     noted, they work exactly like the equivalent Mach call; they 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.