PTRACE(2) GENIX Programmer's 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.
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 sig-
nal that may be 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
parent can examine and modify the child's core image 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. The
request turns on the child's state flag, which stipulates the
child should be left in a stopped state upon receipt of a signal
instead of the state specified by func. No return value is
defined for this request. All the other arguments are ignored.
Peculiar results will ensue if the parent does not expect to
trace the child.
The remainder of the requests can only be issued by the parent pro-
cess. The child must be in a stopped state before these requests
are made.
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 items are ignored.
3 The word of the system's per-process data area corresponding to
addr or the register that matches the values in reg.h or fpu.h
is returned. Addr must be less than 2048, or one of the reg.h
or fpu.h values. This space contains the registers and other
information about the process; its layout corresponds to the
user structure in the system.
Printed 11/16/83 1
PTRACE(2) GENIX Programmer's Manual PTRACE(2)
4,5 The given data is written at the word in the process's address
space corresponding to addr, which must be even, or the register
that matches the reg.h or fpu.h offset. 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
registers, the floating point status and registers, and certain
bits of the processor status word. However, when addr is 0, 1,
2, or less than zero, a register is addressed, the register
being the value that matches the reg.h or fpu.h values for
register indexing.
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 possi-
ble after execution of at least one instruction, execution stops
again. The signal number from the stop is SIGTRAP. (On the
NS16000, PDP-11, and VAX-11 the T-bit is used and just one
instruction is executed; on the Interdata 8/32 the stop does not
take place until a store instruction is executed.) This is part
of the mechanism for implementing breakpoints.
The following two requests apply only to the NS16000.
10 An MMU breakpoint is set at location addr. Data indicates which
of the two breakpoint registers is to be set (0 or 1). High
order bits in addr specify the type of breakpoint (read, write,
or combinations thereof) as specified in the MMU data sheet,
except that the AS bit is forced to 1 and the VP bit is forced
to 0 (so that supervisor or physical breakpoints cannot be set).
An addr value of 0 clears the breakpoint.
11 Set the breakpoint counter register for MMU breakpoint number 0
to addr.
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.
Printed 11/16/83 2
PTRACE(2) GENIX Programmer's Manual PTRACE(2)
To forestall possible fraud, ptrace inhibits the set-user-id facil-
ity 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. On the NS16000 and VAX-11, `word' also means a 32-bit
integer, but the `even' restriction does not apply.
FILES
/usr/include/sys/reg.h values for register requests
/usr/include/sys/fpu.h
SEE ALSO
wait(2), signal(2), ddt(1)
DIAGNOSTICS
The value -1 is returned if request is invalid, pid is not a trace-
able process, addr is out of bounds, or data specifies an illegal
signal number.
BUGS
Ptrace is unique and arcane; it should be replaced with a special
file that can be opened and read and written. The control functions
could then be implemented with ioctl(2) calls on this file. This
would be simpler to understand and have much higher performance.
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 instruc-
tion' 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 resolve any ambiguity.
It should be possible to stop a process on occurrence of a system
call; in this way a completely controlled environment could be pro-
vided.
Printed 11/16/83 3