man(1) Manual page archive


     PTRACE(2)                                               PTRACE(2)

     NAME
          ptrace  -  process trace

     SYNOPSIS
          #include <signal.h>

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

     DESCRIPTION
          Ptrace provides a means by which a parent process may con-
          trol the execution of a child process, and examine and
          change its core image.  Its primary use is for the implemen-
          tation of breakpoint debugging.  There are four arguments
          whose interpretation depends on a request argument.  Gener-
          ally, 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 `inter-
          rupt.'  See signal(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:

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

          1,2 The word in the child process's address space at addr is
              returned.  If I and D space are separated, request 1
              indicates I space, 2 D space.  Addr must be even.  The
              child must be stopped.  The input data is ignored.

          3   The word of the system's per-process data area corre-
              sponding to addr is returned.  Addr must be even and
              less than 512.  This space contains the registers and
              other information about the process; its layout corre-
              sponds to the user structure in the system.

          4,5 The given data is written at the word in the process's
              address space corresponding to addr, which must be even.
              No useful value is returned.  If I and D space are

     PTRACE(2)                                               PTRACE(2)

              separated, request 4 indicates I space, 5 D space.
              Attempts to write in pure procedure fail if another pro-
              cess is executing the same file.

          6   The process's system data is written, as it is read with
              request 3.  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.

          7   The data argument is taken as a signal number and the
              child's execution continues at location addr as if it
              had incurred that signal.  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.

          8   The traced process terminates.

          9   Execution continues as in request 7; 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 PDP-11 the T-bit is used and just
              one instruction is executed; on the Interdata the stop
              does not take place until a store instruction is exe-
              cuted.)  This is part of the mechanism for implementing
              breakpoints.

          As indicated, these calls (except for request 0) 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
          facility on subsequent exec(2) calls.  If a traced process
          calls exec, it will stop before executing the first instruc-
          tion of the new image showing signal SIGTRAP.

          On the Interdata 8/32, `word' means a 32-bit word and `even'
          means 0 mod 4.

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

     DIAGNOSTICS
          The value -1 is returned if request is invalid, pid is not a
          traceable process, addr is out of bounds, or data specifies
          an illegal signal number.

     PTRACE(2)                                               PTRACE(2)

     BUGS
          On the Interdata 8/32, `as soon as possible' (request 7)
          means `as soon as a store instruction has been executed.'

          The request 0 call should be able to specify signals which
          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.

     ASSEMBLER
          (ptrace = 26.)
          (data in r0)
          sys ptrace; pid; addr; request
          (value in r0)