4.3BSD - /usr/man/cat2/ptrace.0

PTRACE(2)                                                            PTRACE(2)


NAME
       ptrace - process trace

SYNOPSIS
       #include <sys/signal.h>
       #include <sys/ptrace.h>

       ptrace(request, pid, addr, data)
       int request, pid, *addr, data;

DESCRIPTION
       Ptrace  provides a means by which a parent process may control the exe‐
       cution of a child process, and examine and change its core image.   Its
       primary  use  is for the implementation of breakpoint debugging.  There
       are four arguments whose interpretation depends on a request  argument.
       Generally, pid is the process ID of the traced process, which must be a
       child (no more distant descendant) of the tracing process.   A  process
       being  traced  behaves normally until it encounters some signal whether
       internally generated like “illegal instruction” or externally generated
       like “interrupt”.  See sigvec(2) for the list.  Then the traced process
       enters a stopped state and its parent is notified  via  wait(2).   When
       the  child  is in the stopped state, its core image can be examined and
       modified using ptrace.  If desired, another  ptrace  request  can  then
       cause  the  child either to terminate or to continue, possibly ignoring
       the signal.

       The value of the request argument determines the precise action of  the
       call:

       PT_TRACE_ME
           This request is the only one used by the child process; it declares
           that the process is to be traced by  its  parent.   All  the  other
           arguments  are  ignored.  Peculiar results will ensue if the parent
           does not expect to trace the child.

       PT_READ_I, PT_READ_D
           The word in the child process’s address space at addr is  returned.
           If  I  and  D  space are separated (e.g. historically on a pdp-11),
           request PT_READ_I indicates I space, PT_READ_D D space.  Addr  must
           be  even  on  some machines.  The child must be stopped.  The input
           data is ignored.

       PT_READ_U
           The word of the system’s per-process  data  area  corresponding  to
           addr is returned.  Addr must be even on some machines and less than
           512.  This space contains the registers and other information about
           the  process;  its  layout corresponds to the user structure in the
           system.

       PT_WRITE_I, PT_WRITE_D
           The given data is written at the  word  in  the  process’s  address
           space  corresponding  to addr, which must be even on some machines.
           No useful value is returned.  If  I  and  D  space  are  separated,
           request PT_WRITE_I indicates I space, PT_WRITE_D D space.  Attempts
           to write in pure procedure fail if another process is executing the
           same file.

       PT_WRITE_U
           The  process’s  system  data is written, as it is read with request
           PT_READ_U.  Only a few locations can be written in  this  way:  the
           general  registers,  the  floating  point status and registers, and
           certain bits of the processor status word.

       PT_CONTINUE
           The data argument is taken as a signal number and the child’s  exe‐
           cution  continues  at location addr as if it had incurred that sig‐
           nal.  Normally the signal number will be either 0 to indicate  that
           the  signal  that  caused the stop should be ignored, or that value
           fetched out of the process’s image indicating which  signal  caused
           the  stop.  If addr is (int *)1 then execution continues from where
           it stopped.

       PT_KILL
           The traced process terminates.

       PT_STEP
           Execution continues as in request PT_CONTINUE; however, as soon  as
           possible  after  execution  of  at least one instruction, execution
           stops again.  The signal number from the stop is SIGTRAP.  (On  the
           VAX-11  the  T-bit  is  used and just one instruction is executed.)
           This is part of the mechanism for implementing breakpoints.

       As indicated, these calls (except for request PT_TRACE_ME) can be  used
       only  when  the  subject process has stopped.  The wait call is used to
       determine when a process stops; in such a case the “termination” status
       returned  by  wait  has the value 0177 to indicate stoppage rather than
       genuine termination.

       To forestall possible fraud, ptrace inhibits the set-user-id  and  set-
       group-id facilities on subsequent execve(2) calls.  If a traced process
       calls execve, it will stop before executing the  first  instruction  of
       the new image showing signal SIGTRAP.

       On  a  VAX-11,  “word”  also  means  a  32-bit  integer, but the “even”
       restriction does not apply.

RETURN VALUE
       A 0 value is returned if the call succeeds.  If the call fails  then  a
       -1  is  returned  and  the global variable errno is set to indicate the
       error.

ERRORS
       [EIO]          The request code is invalid.

       [ESRCH]        The specified process does not exist.

       [EIO]          The given signal number is invalid.

       [EIO]          The specified address is out of bounds.

       [EPERM]        The specified process cannot be traced.

SEE ALSO
       wait(2), sigvec(2), adb(1)

BUGS
       Ptrace is unique and arcane; it should be replaced with a special  file
       that  can  be opened and read and written.  The control functions could
       then be implemented with ioctl(2) calls on this file.   This  would  be
       simpler to understand and have much higher performance.

       The request PT_TRACE_ME call should be able to specify signals that are
       to be treated normally and not cause a stop.  In this way, for example,
       programs with simulated floating point (which use “illegal instruction”
       signals at a very high rate) could be efficiently debugged.

       The error indication, -1, is a legitimate function value;  errno,  (see
       intro(2)), can be used to disambiguate.

       It should be possible to stop a process on occurrence of a system call;
       in this way a completely controlled environment could be provided.


4th Berkeley Distribution        May 23, 1986                        PTRACE(2)