


      PTRACE(2)                   (UNIX 5.0)                  PTRACE(2)



      NAME
           ptrace - process trace

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

      DESCRIPTION
           Ptrace allows a parent process to control the execution of
           its child process.  Its primary use is the implementation of
           breakpoint debugging.

           The child process behaves normally until it encounters a
           signal documented in signal(2), at which time it enters a
           stopped state and its parent is notified via wait(2).  While
           the child is in the stopped state, its parent can examine
           and modify it, and/or terminate or continue, by means of
           ptrace.

           request determines the precise action of ptrace:

                0    must be issued by the child process, to set its
                     own trace flag, that indicates it should be left
                     in a stopped state upon receipt of a signal rather
                     than the state specified by func, so that it may
                     be traced by its parent.  see signal(2) for func
                     info.  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.

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

                1, 2 With these requests, the word at location addr in
                     the address space of the child is returned to the
                     parent process.  If I and D space are separated,
                     request 1 returns a word from I space, and request
                     2 returns a word from D space.  If I and D space
                     are not separated, either request 1 or request 2
                     may be used with equal results.  The data argument
                     is ignored.  These two requests will fail if addr
                     is not the start address of a word, in which case
                     a value of -1 is returned to the parent process
                     and the parent's errno is set to EIO.

                3    With this request, the word at location addr in
                     the child's process control block in the system's
                     address space (see <sys/user.h>) is returned to
                     the parent process.  Addresses in this area range



      Page 1                                         (73 A2 02MTA REV1)






      PTRACE(2)                   (UNIX 5.0)                  PTRACE(2)



                     from 0 to 1024 on the PDP-11s and 0 to 2048 on the
                     3B20S and VAX.  The data argument is ignored.
                     This request will fail if addr is not the start
                     address of a word or is outside the USER area, in
                     which case a value of -1 is returned to the parent
                     process and the parent's errno is set to EIO.

                4, 5 With these requests, the value given by the data
                     argument is written into the address space of the
                     child at location addr.  If I and D space are
                     separated, request 4 writes a word into I space,
                     and request 5 writes a word into D space.  If I
                     and D space are not separated, either request 4 or
                     request 5 may be used with equal results.  Upon
                     successful completion, the value written into the
                     address space of the child is returned to the
                     parent.  These two requests will fail if addr is a
                     location in a pure procedure space and another
                     process is executing in that space, or addr is not
                     the start address of a word.  Upon failure a value
                     of -1 is returned to the parent process and the
                     parent's errno is set to EIO.

                6    With this request, a few entries in the child's
                     process control block can be written.  Data gives
                     the value that is to be written and addr is the
                     location of the entry.  The few entries that can
                     be written are the general registers, the program
                     counter, and the trapsword.

                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 signals 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.  This request
                     will fail if data is not 0 or a valid signal
                     number, in which case a value of -1 is returned to
                     the parent process and the parent's errno is set
                     to EIO.

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

           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
           instruction of the new image showing signal SIGTRAP.



      Page 2                                         (73 A2 02MTA REV1)






      PTRACE(2)                   (UNIX 5.0)                  PTRACE(2)



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

                Request is an illegal number.  [EIO]

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

      SEE ALSO
           exec(2), signal(2), wait(2).












































      Page 3                                         (73 A2 02MTA REV1)



