PTRACE(2)							System Calls Manual							 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 control the execution 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  argu-
       ment.   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  exter-
       nally  generated  like `interrupt.'  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 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.  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 corresponding 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 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 even.   No  useful  value	is
	   returned.  If I and D space are separated, request 4 indicates I space, 5 D space.  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  reg-
	   isters, 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 executed.)  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 instruction 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.

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, pro-
       grams 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)

																	 PTRACE(2)