PTRACE(2) MachTen Programmer’s Manual PTRACE(2)

NAME
ptrace - process trace

SYNOPSIS
#include <sys/signal.h>
#include <sys/ptrace.h>

ptrace(request, pid, addr, data)
int request, pid, *addr, data;

DESCRIPTION
Ptrace provides a means by which a parent process may con-
trol the execution of a child process, and examine and
change its core image. Its primary use is for the imple-
mentation of breakpoint debugging. There are four argu-
ments 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 gener-
ated 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:

PT_TRACE_ME
This request is the only one used by the child pro-
cess; 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.

PT_READ_I, PT_READ_D
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 PT_READ_I indicates
I space, PT_READ_D D space. Addr must be even on some
machines. The child must be stopped. The input data
is ignored.

PT_READ_U
The word of the system’s per-process data area corre-
sponding to addr is returned. Addr must be even on
some machines 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.

PT_WRITE_I, PT_WRITE_D
The given data is written at the word in the process’s
address space corresponding to addr, which must be
even on some machines. No useful value is returned.
If I and D space are separated, request PT_WRITE_I
indicates I space, PT_WRITE_D D space. Attempts to
write in pure procedure fail if another process is
executing the same file.

PT_WRITE_U
The process’s system data is written, as it is read
with request PT_READ_U. Only a few locations can be
written in this way: the general registers, the float-
ing point status and registers, and certain bits of
the processor status word.

PT_CONTINUE
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 exe-
cution continues from where it stopped.

PT_KILL
The traced process terminates.

PT_STEP
Execution continues as in request PT_CONTINUE; how-
ever, as soon as possible after execution of at least
one instruction, execution stops again. The signal
number from the stop is SIGTRAP. (On the VAX-11 the
T-bit is used and just one instruction is executed.)
This is part of the mechanism for implementing break-
points.

As indicated, these calls (except for request PT_TRACE_ME)
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 gen-
uine 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.

On a VAX-11, "word" also means a 32-bit integer, but the
"even" restriction does not apply.

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
[EIO] The request code is invalid.

[ESRCH] The specified process does not exist.

[EIO] The given signal number is invalid.

[EIO] The specified address is out of bounds.

[EPERM] The specified process cannot be traced.