PTRACE(2)               COMMAND REFERENCE               PTRACE(2)



NAME
     ptrace - process trace

SYNOPSIS
     #include <sys/signal.h>

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

DESCRIPTION
     Ptrace provides a means by which a parent process may
     control the execution of a child process, and examine and
     change its core image.  The child process must be started by
     using exect (see execl(3c)).

     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:

     0  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.

     1,2
        The word in the child process's address space at addr is
        returned.  Both requests operate the same; they are a
        vestige of systems (e.g., the pdp-11), on which there
        were separate I and D spaces.  Addr must be a multiple of
        the word size (i.e., 4 bytes).  The child must be
        stopped.  The input data is ignored.

     3  The word of the system's per-process data area
        corresponding to addr is returned.  Addr must be a
        multiple of the word size (4 bytes), and less than the
        size of the structure defined in /usr/include/sys/user.h.



Printed 5/12/88                                                 1

PTRACE(2)               COMMAND REFERENCE               PTRACE(2)



        This space contains the registers and other information
        about the process; its layout corresponds 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 a
        multiple of the word size (i.e., 4 bytes).  No useful
        value is returned.  Requests 4 and 5 operate identically.
        Attempts to write in pure procedure fail if another
        process 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.  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
     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.

DIAGNOSTICS
     [ESRCH]      The specified process does not exist.

     [EPERM]      The specified process cannot be traced.

     [EIO]        Request is an invalid argument.



Printed 5/12/88                                                 2

PTRACE(2)               COMMAND REFERENCE               PTRACE(2)



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.

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

SEE ALSO
     adb(1), sigvec(2), wait(2), and execl(3c).











































Printed 5/12/88                                                 3

%%index%%
na:288,74;
sy:362,964;
de:1326,2518;4204,2270;
di:6474,302;
rv:7136,294;
ca:7430,240;
se:7670,213;
%%index%%000000000132