PWB1/usr/man/man2/ptrace.2

.th PTRACE II 5/31/77
.sh NAME
ptrace  \*-  process trace
.sh SYNOPSIS
.nf
(ptrace = 26.)
(data in r0)
.ft B
sys	ptrace; pid; addr; request
.ft R
.br
(value in r0)
.ft B
.s3
ptrace(request, pid, addr, data);
.ft R
.fi
.sh DESCRIPTION
.it 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,
but it should be adaptable for simulation of non-UNIX environments.
There are four arguments whose interpretation
depends on a
.it request
argument.
Generally,
.it 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
.it signal\^\c
(II) for the list.
Then the traced process enters a stopped state
and its parent is notified via
.it wait(II).
When the child is in the stopped state,
its core image can be examined and modified
using
.it ptrace.
If desired, another
.it ptrace
request can then cause the child either to terminate
or to continue, possibly ignoring the signal.
.s3
The value of the
.it request
argument determines the precise
action of the call:
.s3
.lp +4 4
0	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.
.s3
.lp +4 4
1,2	The
word in the child process's address space
at
.it addr
is returned (in r0).
Request 1 indicates the instruction space,
2 indicates the data space.
.it addr
must be even.
The child must be stopped.
The input
.it data
is ignored.
.s3
.lp +4 4
3	The word
of the system's per-process data area corresponding to
.it addr
is returned.
.it Addr
must be even and in the data area.
This space contains the registers and other information about
the process;
its layout corresponds to the
.it user
structure in the system.
.s3
.lp +4 4
4,5	The
given
.it data
is written at the word in the process's address space corresponding to
.it addr,
which must be even.
No useful value is returned.
Request 4 specifies instruction space, 5 specifies
data space.
Attempts to write in pure procedure result in termination of the
child, instead of going through or causing an error for the parent.
.s3
.lp +4 4
6	The process's system data is written,
as it is read with request 3.
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.
.s3
.lp +4 4
7	The
.it data
argument is taken as a signal number
and the child's execution continues
as if it had incurred that signal.
Normally the signal number will be
either 0 to indicate that the signal which caused the stop
should be ignored,
or that value fetched out of the
process's image indicating which signal caused
the stop.
.s3
.lp +4 4
8	The traced process terminates.
.s3
.i0
As indicated,
these calls
(except for request 0)
can be used only when the subject process has stopped.
The
.it wait
call is used to determine
when a process stops;
in such a case the ``termination'' status
returned by
.it wait
has the value 0177 to indicate stoppage rather
than genuine termination.
.s3
To forestall possible fraud,
.it ptrace
inhibits the set-user-id facility
on subsequent
.it exec(II)
calls.
.sh "SEE ALSO"
wait(II), signal(II), cdb(I)
.sh DIAGNOSTICS
From assembler, the c-bit (error bit) is set on errors;
from C, \-1 is returned and
.it errno
has the error code.
.sh BUGS
The request 0 call should be able to specify
signals which 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.
.s3
Also, it should be possible to stop a process on occurrence of a system
call;
in this way a completely controlled environment could
be provided.