ptrace() -- System Call (libc)

Trace process execution
#include <signal.h>
int ptrace(command, pid, location, value)
int command, pid, *location, value;

ptrace() 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  db,  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  commands  to  control  the  child.   pid 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  wait() 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  exec(),  the child  stops with  signal
SIGTRAP to enable the parent to plant breakpoints.  The set user id and set
group id modes are ineffective when a traced process performs an exec().

The following list describes  each available command. A command ignores any
arguments not mentioned.

0    This is  the only command 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 command argument is significant.

1,2  The int  at location  is the return  value.  Command 1  signifies that
     location is in the instruction space, whereas command 2 signifies data
     space.  Often these two spaces are equivalent.

3    The return value is the int  of the process description, as defined in
     sys/uproc.h. This  call may be used to obtain  values such as hardware
     register contents and segment allocation information.

4,5  Modify the  child process's memory by changing the  int at location to
     value.  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    Modify the  int at location  in the process description  area, as with
     command 3.  The permissible values for location are restricted to such
     things as hardware registers and bits of machine status registers that
     the user may safely change.

7    This command restarts the  stopped child process after it encounters a
     signal.  The process resumes  execution at location, or from where the
     process  was stopped  if location  is (int *)1.  value 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 command.  If value is zero, the effect
     of the signal is ignored.

8    Force the child process to exit.

9    Like command 7, except that  the child stops again with signal SIGTRAP
     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.

Files

<signal.h>
<sys/uproc.h>

See Also

db,
exec,
libc,
ptrace.h,
signal(),
wait()

Diagnostics

ptrace()  returns -1  if pid  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 errno should be
checked to distinguish a return value of -1 from an error return.

Notes

There is no way to specify which signals should not stop the process.

© 2012 by Stephen A. Ness