PTRACE(S) UNIX System V PTRACE(S)
Name
ptrace - process trace
Syntax
int ptrace (request, pid, addr, data);
int request, pid, data;
Description
The ptrace system call 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(CP)). The child process behaves normally
until it encounters a signal (see signal(S) for the list),
at which time it enters a stopped state and its parent is
notified via wait(S). 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 data type of the
argument addr depends upon the particular request given to
ptrace.
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(S)). 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.
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.
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 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.
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 a
location in a pure procedure space and another
process is executing in that space. 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 all registers.
On the 80386, the ptrace system call can be used
to modify the debug registers.
The 80386 debug registers are used to specify an
address to monitor in a user process. Any access
to this location by the user process will deliver
a SIGTRAP (see signal(S)) to the user process and
possibly restart the parent process.
The 80386 debug registers can be accessed by using
the 3 or 6 options of the ptrace system call to
read or write a traced-process's u-area. The file
<sys/debugreg.h> should be included in the parent
process that wants to control the debug registers.
This header file defines bit masks that describe
the debug-registers in the u_debugreg[] array in
the u-area.
The debug registers numbered
u.u_debugreg[DR_FIRSTADDR] (%dr0) to
u.u_debugreg[DR_LASTADDR] (%dr3) contain process
addresses which will be monitored according to the
instructions provided in u.u_debugreg[DR_CONTROL]
(%dr7). Only the DR_LOCAL_ENABLE_MASK and the
various read/write and length bits in
u.u_debugreg[DR_CONTROL] can be set. Setting
DR_LOCAL_SLOWDOWN to slow down processing is also
highly recommended. The setting of all other bits
is undefined and should be set to zero to ensure
compatibility with future Intel processors.
In the process being debugged, these registers are
automatically loaded before entering user-mode
(privilege level 3) and cleared before entering
the system for any reason. In UNIX System V
Release 3.0, if the location specified by a
debug-register is accessed during a system call,
core-dump, or interrupt service, no trap will
ensue.
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(S).
9 This request sets the trace bit in the Processor
Status Word of the child and then executes the
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(S) calls. If a traced process
calls exec, it will stop before executing the first
instruction of the new image showing signal SIGTRAP.
General Errors
The ptrace system call will in general fail if the child
process is running under i286emul(CP) or one or more of the
following is 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.
See Also
sdb(CP), exec(S), signal(S), wait(S)
Standards Conformance
ptrace is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
and The X/Open Portability Guide II of January 1987.
(printed 6/20/89)