PTRACE(2) COMMAND REFERENCE PTRACE(2)
NAME
ptrace - process trace
SYNOPSIS
#include <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. If I and D space are separated (e.g.
historically on a pdp-11), 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.
Printed 10/17/86 1
PTRACE(2) COMMAND REFERENCE 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.
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.
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.
10 A memory breakpoint is modified. Addr is the breakpoint
address. Data is a bit mask that is used to determine
what kind of memory breakpoint action to take. Bit 0
will force a breakpoint if addr is written, bit 1 will
force a breakpoint if addr is read, and bit 2 determines
which breakpoint register to use. (If bit 2 is set,
breakpoint register 1 (BPR1) is used; otherwise
breakpoint register 0 (BPR0) is used.) The breakpoint is
removed if neither bit 0 or bit 1 is set.
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.
Printed 10/17/86 2
PTRACE(2) COMMAND REFERENCE PTRACE(2)
DIAGNOSTICS
[ESRCH]
The specified process does not exist.
[EPERM]
The specified process cannot be traced.
[EIO]
Request is an invalid argument.
[EIO]
An I/O error occurred while performing the requested
action.
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
Ptrace is unique and arcane; it should be replaced with a
special file which 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.
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 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.
SEE ALSO
adb(1), sigvec(2), wait(2), execl(3c).
Printed 10/17/86 3
%%index%%
na:72,58;
sy:130,596;
de:726,2364;3234,2713;
di:6091,360;
rv:6451,250;
ca:6701,980;
se:7681,152;
%%index%%000000000130