ppttrraaccee() -- System Call (libc)

Trace process execution
#iinncclluuddee <ssiiggnnaall.hh>
iinntt ppttrraaccee(_c_o_m_m_a_n_d, _p_i_d, _l_o_c_a_t_i_o_n, _v_a_l_u_e)
iinntt _c_o_m_m_a_n_d, _p_i_d, *_l_o_c_a_t_i_o_n, _v_a_l_u_e;

ppttrraaccee() provides a parent process with primitives to monitor and alter the
execution of  a child  process.  These primitives  typically are used  by a
debugger  such as  ddbb,  which needs  to  examine and  change memory,  plant
breakpoints, and single-step the child process being debugged.

Once a  child process indicates it  wishes to be traced,  its parent issues
various  _c_o_m_m_a_n_ds  to  control  the  child.   _p_i_d identifies  the  affected
process.  The parent may issue a  command only when the child process is in
a  stopped state,  which  occurs when  the  child encounters  a signal.   A
special return value of 0177 from  wwaaiitt() informs the parent that the child
has entered the  stopped state.  The parent may then  examine or change the
child process memory space or restart the process at any point.

When  the child  process  issues an  eexxeecc(),  the child  stops with  signal
SSIIGGTTRRAAPP to enable the parent to plant breakpoints.  The set user id and set
group id modes are ineffective when a traced process performs an eexxeecc().

The following list describes  each available _c_o_m_m_a_n_d. A _c_o_m_m_a_n_d ignores any
arguments not mentioned.

00    This is  the only _c_o_m_m_a_n_d the  child process may issue.   It tells the
     system  that the  child wishes  to be traced.   Parent and  child must
     agree that  tracing should occur to achieve  the desired effect.  Only
     the _c_o_m_m_a_n_d argument is significant.

11,22  The iinntt  at _l_o_c_a_t_i_o_n  is the return  value.  Command 1  signifies that
     _l_o_c_a_t_i_o_n is in the instruction space, whereas command 2 signifies _d_a_t_a
     space.  Often these two spaces are equivalent.

33    The return value is the iinntt  of the process description, as defined in
     ssyyss/uupprroocc.hh. This  call may be used to obtain  values such as hardware
     register contents and segment allocation information.

44,55  Modify the  child process's memory by changing the  iinntt at _l_o_c_a_t_i_o_n to
     _v_a_l_u_e.  Command 4  means instruction  space and  command 5  means data
     space.   Shared segments  may be  written only  if no  other executing
     process is using them.

66    Modify the  iinntt at _l_o_c_a_t_i_o_n  in the process description  area, as with
     command 3.  The permissible values for _l_o_c_a_t_i_o_n are restricted to such
     things as hardware registers and bits of machine status registers that
     the user may safely change.

77    This command restarts the  stopped child process after it encounters a
     signal.  The process resumes  execution at _l_o_c_a_t_i_o_n, or from where the
     process  was stopped  if _l_o_c_a_t_i_o_n  is (iinntt *)11.  _v_a_l_u_e gives  a signal
     number that the process receives as it restarts.  This is normally the
     number of the signal that caused the process to stop, fetched from the
     process description area by a 33 command.  If _v_a_l_u_e is zero, the effect
     of the signal is ignored.

88    Force the child process to exit.

99    Like command 77, except that  the child stops again with signal SSIIGGTTRRAAPP
     as  soon   as  practicable  after  the  execution   of  at  least  one
     instruction.   The  actual  hardware  method  used to  implement  this
     command  varies  from machine  to  machine,  explaining the  imprecise
     nature of its definition.  This call may provide part of the basis for
     breakpoints.

_F_i_l_e_s
<ssiiggnnaall.hh>
<ssyyss/uupprroocc.hh>

_S_e_e _A_l_s_o
ddbb, eexxeecc, lliibbcc, ppttrraaccee.hh, ssiiggnnaall(), wwaaiitt()

_D_i_a_g_n_o_s_t_i_c_s
ppttrraaccee()  returns -1  if _p_i_d  is not  the process id  of an  eligible child
process  or if  some other  argument  is invalid  or out  of bounds.   Some
commands may return an arbitrary data  value, in which case eerrrrnnoo should be
checked to distinguish a return value of -1 from an error return.

_N_o_t_e_s
There is no way to specify which signals should not stop the process.
