ptrace(2)
NAME
ptrace - process trace
SYNOPSIS
#include <sys/types.h>
#include <sys/signal.h>
#include <sys/ptrace.h>
int ptrace(int request, pid_t pid, long addr, long data)
DESCRIPTION
Note: This manual page has no relation to Minix. Someone who knows
ptrace() has to check, or rewrite, this page. (kjb)
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 sigaction(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.
SEE ALSO
wait(2), sigaction(2), mdb(1).
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.
The request PT_TRACE_ME call should be able to specify signals that 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.