PTRACE(2-SVR3) RISC/os Reference Manual PTRACE(2-SVR3)
NAME
ptrace - process trace
SYNOPSIS
#include <signal.h>
#include <sys/ptrace.h>
ptrace(request, pid, addr, data)
int request, pid, *addr, data;
DESCRIPTION
ptrace provides a means by which a process may control the
execution of another 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. A process
being traced behaves normally until it encounters some sig-
nal whether internally generated like "illegal instruction"
or externally generated like "interrupt". See sigset(2) or
signal(2) for the list.
Upon encountering a signal the traced process enters a
stopped state and its tracing process is notified via
wait(2). If the the traced process stops with a SIGTRAP the
process may have been stopped for a number of reasons. Two
status words addressable as registers in the traced
process's uarea qualify SIGTRAPs: TRAPCAUSE, which contains
the cause of the trap, and TRAPINFO, which contains extra
information concerning the trap.
When the traced process is in the stopped state, its core
image can be examined and modified using ptrace. If
desired, another ptrace request can then cause the traced
process either to terminate or to continue, possibly ignor-
ing the signal.
The value of the request argument determines the precise
action of the call:
0 This request is the only one that may be used by a
child process; it may declare that it is to be traced
by its parent. All other arguments are ignored. Pecu-
liar results will ensue if the parent does not expect
to trace the child.
1,2 The word in the traced process's address space at addr
is returned. If I and D space are separated (e.g. his-
torically on a pdp-11), request 1 indicates I space, 2
D space. addr must be 4-byte aligned. The traced pro-
cess must be stopped. The input data is ignored.
Printed 11/19/92 Page 1
PTRACE(2-SVR3) RISC/os Reference Manual PTRACE(2-SVR3)
3 The word of the system's per-process data area
corresponding to addr is returned. addr is a constant
defined in ptrace.h This space contains the registers
and other information about the process; the constants
correspond to fields in the user structure in the sys-
tem.
4,5 The given data is written at the word in the process's
address space corresponding to addr, which must be 4-
byte aligned. The old value at the address 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. The old value at the address is returned.
7 The data argument is taken as a signal number and the
traced process'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 exe-
cution 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 instruc-
tion, execution stops again. The signal number from
the stop is SIGTRAP. TRAPCAUSE will contain CAUSESIN-
GLE. This is part of the mechanism for implementing
breakpoints.
As indicated, these calls (except for request 0 and 5) 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.
If multiple processes are being traced, wait can be called
multiple times and will return the status for the next
stopped or terminated child or traced process.
To forestall possible fraud, ptrace inhibits the set-user-id
and set-group-id facilities on subsequent exec(2) calls. If
a traced process calls execve, it will stop before executing
the first instruction of the new image showing signal
Page 2 Printed 11/19/92
PTRACE(2-SVR3) RISC/os Reference Manual PTRACE(2-SVR3)
SIGTRAP. In this case TRAPCAUSE will contain CAUSEEXEC and
TRAPINFO will not contain anything interesting. If a traced
process execs again, the same thing will happen.
If a traced process forks, both parent and child will be
traced. Breakpoints from the parent will not be copied into
the child. At the time of the fork, the child will be
stopped with a SIGTRAP. The tracing process may then ter-
minate the trace if desired. TRAPCAUSE will contain
CAUSEFORK and TRAPINFO
will contain the pid of its parent.
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.
ERRORS
[EINVAL] The request code is invalid.
[EINVAL] The specified process does not exist.
[EINVAL] The given signal number is invalid.
[EFAULT] The specified address is out of bounds.
[EPERM] The specified process cannot be traced.
SEE ALSO
wait(2), sigset(2), signal(2), proc(4).
BUGS
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.
Printed 11/19/92 Page 3