PTRACE(2)                DOMAIN/IX SYS5                 PTRACE(2)



NAME
     ptrace - process trace

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


DESCRIPTION
     Ptrace provides a way for a parent process to control execu-
     tion of a child process.  It is mainly used in breakpoint
     debugging.  The child process behaves normally until it
     encounters a signal (see signal(2) for the list), at which
     time it enters a stopped state and its parent is notified
     via wait(2).  When the child is in the stopped state, its
     parent can:

     ⊕  examine and modify the child's "core image" using ptrace

     ⊕  terminate the child

     ⊕  continue (restart) the child, optionally telling the
        child to ignore the signal that caused it to stop.

REQUESTS
     The request argument is an integer in the range 0-9.

     Note:     Where two numbers are associated with a request
               (an artifact of implementations with separate
               instruction and data space), either number may be
               used.

     Request zero can only be used in the child.

     Non-zero requests can only be used by the parent.  For each
     non-zero request, pid is the process ID of the child.  The
     child must be in a stopped state before these requests are
     made.

     0    Child trace flag.  This is the only request that can be
          issued by the child. It stipulates that the child
          should be left in a stopped state upon receipt of a
          signal rather than the state specified by any func;
          argument associated with a signal(2) call in the child.
          The pid, addr, and data arguments are ignored, and a
          return value is not defined for this request.  Peculiar
          results will ensue if the parent does not expect to
          trace the child.

     1, 2 return the word at location addr in the address space



Printed 12/4/86                                          PTRACE-1

PTRACE(2)                DOMAIN/IX SYS5                 PTRACE(2)



          of the child.  On DOMAIN Systems, either request 1 or
          request 2 may be used with identical results.  If addr
          is not the start address of a word, a value of -1 is
          returned to the parent process and the parent's errno
          is set to EIO.

     3    return the word at location addr in the child's USER
          area in the system's address space (see <sys/user.h>)
          to the parent process.  On DOMAIN Systems, addresses in
          this area range from 0 to 2048, and the data argument
          is ignored.  If addr is not the start address of a word
          or is outside the USER area, a value of -1 is returned
          to the parent process and the parent's errno is set to
          EIO.

     4, 5 write the value given by the data argument into the
          address space of the child at location addr.  Upon suc-
          cessful completion, the value written into the address
          space of the child is returned to the parent.  If addr
          is a location in a pure procedure space and another
          process is executing in that space, or if addr is not
          the start address of a word, these requests will fail,
          a value of -1 will be returned to the parent process,
          and the parent's errno will be set to EIO.

     6    write one of the following entries, where data gives
          the value that is to be written and addr is the loca-
          tion of the entry, in the child's USER area:

               M68xxx processor registers (A0-A7, D0-D7).

               The condition codes (bits 0-7) of the Processor
               Status Word

     7    This request causes the child to resume execution.  If
          the data argument is 0, all pending signals including
          the one that caused the child to stop are canceled
          before it resumes execution.  If the data argument is a
          valid signal number, the child resumes execution as if
          it had incurred that signal, and any other pending sig-
          nals are canceled.  The addr argument must be equal to
          1 for this request.  Upon successful completion, the
          value of data is returned to the parent.  If data is
          not 0 or a valid signal number, this request will fail,
          a value of -1 will be returned to the parent process,
          and the parent's errno will be set to EIO.

     8    This request causes the child to terminate with the
          same consequences as exit(2).




PTRACE-2                                          Printed 12/4/86

PTRACE(2)                DOMAIN/IX SYS5                 PTRACE(2)



     9    This request sets the trace bit in the Processor Status
          Word of the child (bit 15 on M68xxx processors) and
          then executes the same steps as listed above for
          request 7.  The trace bit causes an interrupt upon com-
          pletion of one machine instruction. This effectively
          allows single stepping of the child.  The trace bit is
          turned off after interrupt.

     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.

GENERAL ERRORS
     Ptrace will in general fail if one or more of the following
     are true:

     [EIO]     Request is an illegal number.

     [ESRCH]   Pid identifies a child that does not exist or has
               not executed a ptrace with request 0.

RELATED INFORMATION
     exec(2), signal(2), wait(2)





























Printed 12/4/86                                          PTRACE-3