ptrace(2) ptrace(2)
NAME
ptrace - process trace
SYNOPSIS
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. The
child process behaves normally until it encounters a signal
(see signal(3) 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(3). 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. 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. Addresses are system dependent. The data
argument is ignored. This request will fail if
Page 1 (last mod. 1/14/87)
ptrace(2) ptrace(2)
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.
4, 5 With these requests, the value given by the data
argument is written into the address space of the
child at location addr. 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, or 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
certain bits of the Processor Status Word
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 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.
Note: the trace bit remains set after an interrupt.
Page 2 (last mod. 1/14/87)
ptrace(2) ptrace(2)
10 Read user register; pid = child process id; addr =
register number; data is ignored; returns value of
child's register.
11 Write user register; pid = child process id; addr =
register number; data = integer value to be written
into named register.
Note: For both requests 10 and 11, the register
numbers are as shown below for the 68000 family
(these numbers are system dependent).
Register Register # Register Register #
d0 0 a1 9
d1 1 a2 10
d2 2 a3 11
d3 3 a4 12
d4 4 a5 13
d5 5 a6 14
d6 6 SP 15
d7 7 PC 16
a0 8 PS 17
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.
GENERAL ERRORS
ptrace will in general fail if one or more of the following
are true:
request is an illegal number. [EIO]
pid identifies a child that does not exist or has not
executed a ptrace with request 0. [ESRCH]
NOTE
Request 11 completely supercedes request 6, and request 10
largely supercedes request 3 (request 3 can read any part of
the child's user area while request 10 can only read
register values of the child).
SEE ALSO
exec(2), wait(2), signal(3).
Page 3 (last mod. 1/14/87)