ptrace - process trace
ptrace(request, pid, addr, data)
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 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 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
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 sepa-
rated, 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 loca-
tions 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 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
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.
wait(2), signal(2), adb(1)
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.
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
It should be possible to stop a process on occurrence of a system call; in this way a com-
pletely controlled environment could be provided.
(ptrace = 26.)
(data in r0)
sys ptrace; pid; addr; request
(value in r0)