PTRACE(2) PTRACE(2)
NAME
ptrace - process trace
SYNOPSIS
#include <signal.h>
#include <ptrace.h>
ptrace (request, pid, addr, data)
int request, pid, *addr, data;
DESCRIPTION
Ptrace provides a way for a process to control the execution
of another process and to examine and change that process's
core image. Ptrace is used primarily to implement
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 signal, whether internally
generated (for example, "illegal instruction")) or
externally generated (for example, "interrupt"). See
signal(2) for the list.
When the traced process encounters a signal, it enters a
stopped state. The process tracing it is notified by
wait(2). If the the traced process stops with a SIGTRAP,
the process might have stopped for many reasons. Two status
words, which are 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 about the trap.
When the traced process is in the stopped state, its core
image can be examined and modified using ptrace. Another
ptrace request can cause the traced process 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 that can be used by a child
process. Request 0 can declare that the child process
is to be traced by its parent. All other arguments are
ignored. Peculiar results happen when 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 (for
example, historically on a PDP-11), Request 1 specifies
I space and Request 2 specifies D space. Addr must be
4-byte aligned. The traced process must be stopped.
Page 1 (last mod. 8/20/87)
PTRACE(2) PTRACE(2)
The input data is ignored.
3 The word of the system's per-process data area that
corresponds 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 system's user structure.
4,5 The specified data is written at the word in the
process's address space corresponds to addr. Addr must
be 4-byte aligned. Upon successful completion, the
value written into the address space of the child is
returned to the parent. If I and D space are separated,
Request 4 specifies I space and Request 5 specifies D
space. Attempts to write in pure procedure fail when
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 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. The signal number can
be 0, indicating the signal that caused the stop should
be ignored, or the signal can be the value fetched from
the process's image, indicating what signal caused the
stop. If addr is (int *)1, execution continues from
where it stopped.
8 The traced process terminates. The addr argument is
ignored and the data argument is the signal specified in
Request 7.
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. TRAPCAUSE contains CAUSESINGLE. This part
of ptrace is used to implement breakpoints. The addr
and data arguments are defined in Request 7.
Requests 20-29 have not been fully defined or implemented.
20 This request is the same as Request 0, except it is
executed by the tracing process and the pid field is
non-zero. That pid's process pid stops execution. On a
signal, it becomes a traced process that returns control
to the tracing process rather than to the parent. The
tracing process must have the same user-id (uid) as the
Page 2 (last mod. 8/20/87)
PTRACE(2) PTRACE(2)
traced process.
21,22
These requests return MAXREG general registers or
MAXFREG floating registers, respectively. Their values
are copied to the locations starting at the address in
the tracing process specified by the addr argument.
24,25
These requests are the same as Requests 20 and 21,
except that they write the registers instead of reading
them.
26 This request specifies a watchpoint in the data or stack
segment of the traced process. If any byte address
(starting at the addr argument and continuing for the
number of bytes specified by the data argument) is
accessed in an instruction, the traced process stops
execution with a SIGTRAP. TRAPCAUSE contains
CAUSEWATCH; TRAPINFO contains the address causing the
trap. Ptrace returns a wid (watchpoint identifier).
MAXWIDS specifies the maximum number of watchpoints per
process.
27 This request's data argument specifies a wid to delete.
28 This request turns off tracing for the traced process
that has the specified pid.
29 This request returns an open file descriptor for the
file attached to pid. This is useful for accessing the
symbol table of an execed process.
These calls (except for Requests 0 and 20) can be used only
when the subject process has terminated. The wait call
determines when a process terminates. Then, the
"termination" status returned by wait has the value 0177 to
show stoppage rather than termination. If multiple
processes are being traced, wait can be called multiple
times and returns the status for the next stopped child,
terminated child, or traced process.
To prevent fraud, ptrace inhibits the set-user-id and set-
group-id facilities on later execve(2) calls. If a traced
process calls execve, the process terminates before
executing the first instruction of the new image showing
signal SIGTRAP. TRAPCAUSE contains CAUSEEXEC; TRAPINFO does
not contain anything interesting. If a traced process execs
again, the same thing happens.
If a traced process forks, both parent and child are traced,
and the breakpoints from the parent are copied into the
Page 3 (last mod. 8/20/87)
PTRACE(2) PTRACE(2)
child. At the time of the fork, the child stops with a
SIGTRAP. The tracing process can end the trace, if desired.
TRAPCAUSE contains CAUSEFORK; TRAPINFO contains the its
parent's pid.
RETURN VALUE
If the call succeeds, a 0 value is returned. 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), sigvec(2).
BUGS
Ptrace is unique and arcane; it should be replaced with a
special file that can be opened, read, and written. The
control functions could be implemented with ioctl(2) calls
on this file. This would be easier to understand and have
much higher performance.
The Request 0 call should specify signals that are to be
treated normally and should not cause a termination. Then,
programs with simulated floating point (which use "illegal
instruction" signals at a high rate) could be efficiently
debugged.
The error indication -1 is a legitimate function value
errno. See intro(2) 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.
ORIGIN
MIPS Computer Systems
Page 4 (last mod. 8/20/87)