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 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 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 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.

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 corresponding 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 floating 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 execution continues from where it stopped.

PT_KILL
The traced process terminates.

PT_STEP
Execution continues as in request PT_CONTINUE; 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 VAX-11 the T-bit is used and just one
instruction is executed.) This is part of the mechanism for
implementing breakpoints.

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 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.

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.