PTRACE(2) PTRACE(2)
NAME
ptrace - process trace
SYNOPSIS
int ptrace (request, pid, addr, data);
int request, pid, addr, data;
For 88k systems:
#include <sys/types.h>
#include <sys/ptrace.h>
int 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. Its primary use
is for the implementation of breakpoint debugging [see
sdb(1)]. The child process behaves normally until it
encounters a signal [see signal(2) for the list], at which
time it enters a stopped state and its parent is notified
via wait(2). When the child is in the stopped state, its
parent can examine and modify its ``core image'' using
ptrace. Also, the parent can cause the child either to
terminate or continue, with the possibility of ignoring the
signal that caused it to stop.
The request argument determines the precise action to be
taken by ptrace and is one of the following:
0 This request must be issued by the child process
if it is to be traced by its parent. It turns on
the child's trace flag that stipulates that the
child should be left in a stopped state upon
receipt of a signal rather than the state
specified by func [see signal(2)]. The pid, addr,
and data arguments are ignored, and a return value
is not defined for this request. Peculiar results
will ensue if the parent does not expect to trace
the child.
Page 1 May 1989
PTRACE(2) PTRACE(2)
The remainder of the requests can only be used by the parent
process. For each, pid is the process ID of the child. The
child must be in a stopped state before these requests are
made.
1, 2 With these requests, the word at location addr in
the address space of the child is returned to the
parent process. If I and D space are separated,
request 1 returns a word from I space, and request
2 returns a word from D space. If I and D space
are not separated, either request 1 or request 2
may be used with equal results. The data argument
is ignored. These two requests will fail if addr
is not the start address of a word, in which case
a value of -1 is returned to the parent process
and the parent's errno is set to EIO.
3 With this request, the word at location addr in
the child's USER area in the system's address
space (see <sys/user.h>) is returned to the parent
process. The data argument is ignored. This
request will fail if addr is not the start address
of a word or is outside the USER area, in which
case a value of -1 is returned to the parent
process and the parent's errno is set to EIO.
For 88k systems:
With this request, information about the debuggee
stored in the kernel address space is made
available to the debugging process. This
information is referenced by addr which is
interpreted as a word offset into a synthetic
structure struct ptraceuser, defined in
<sys/ptrace.h>.
The request shall fail if addr is not a relative
word offset within struct ptraceuser, (i.e., if:
addr < 0
or
addr > sizeof(ptraceuser)
Page 2 May 1989
PTRACE(2) PTRACE(2)
or if addr is not a multiple of four). Upon failure, a
value of -1 is returned to the debugger process and the
debugger's errno is set to [EIO] .
4, 5 With these requests, the value given by the data
argument is written into the address space of the
child at location addr. If I and D space are
separated, request 4 writes a word into I space,
and request 5 writes a word into D space. If I
and D space are not separated, either request 4 or
request 5 may be used with equal results. Upon
successful completion, the value written into the
address space of the child is returned to the
parent. These two requests will fail if addr is
not the start address of a word. Upon failure a
value of -1 is returned to the parent process and
the parent's errno is set to EIO.
6 With this request, a few entries in the child's
USER area can be written. Data gives the value
that is to be written and addr is the location of
the entry. The few entries that can be written
are:
the general registers
the condition codes of the Processor Status
Word.
For 88k systems: With this request, information about
the debuggee stored in the kernel may be changed. This
is similar to request 3, but only the following entries
of the ptraceuser structure may be changed:
pt_r0 - pt_r31
General purpose registers.
pt_psr
Processor status register. Only the byte
order, carry, misaligned access, and
Page 3 May 1989
PTRACE(2) PTRACE(2)
serialize bits may be changed.
pt_fpsr
Floating point user status register.
pt_fpcr
Floating point user control register.
pt_sxip
Execution instruction pointer.
pt_snip
Next instruction pointer.
pt_sfip
Fetch instruction pointer.
pt_sigtbl
Signal table entries.
7 This request causes the child to resume execution.
If the data argument is 0, all pending signals
including the one that caused the child to stop
are canceled before it resumes execution. If the
data argument is a valid signal number, the child
resumes execution as if it had incurred that
signal, and any other pending signals are
canceled. The addr argument must be equal to 1
for this request. Upon successful completion, the
value of data is returned to the parent. This
request will fail if data is not 0 or a valid
signal number, in which case a value of -1 is
returned to the parent process and the parent's
errno is set to EIO.
8 This request causes the child to terminate with
the same consequences as exit(2).
9 This request sets the trace bit in the Processor
Status Word of the child and then executes the
Page 4 May 1989
PTRACE(2) PTRACE(2)
same steps as listed above for request 7. The
trace bit causes an interrupt upon completion of
one machine instruction. This effectively allows
single stepping of the child.
To forestall possible fraud, ptrace inhibits the set-user-id
facility on subsequent exec(2) calls. If a traced process
calls exec, it will stop before executing the first
instruction of the new image showing signal SIGTRAP.
DIAGNOSTICS
ptrace will in general fail if one or more of the following
are true:
[EIO] Request is an illegal number.
[ESRCH] Pid identifies a child that does not exist or
has not executed a ptrace with request 0.
For 88K systems only:
[EINVAL] Request is not supported by this system.
SEE ALSO
sdb(1), exec(2), signal(2), wait(2).
Page 5 May 1989