PTRACE(S) XENIX System V PTRACE(S)
Name
ptrace - Traces a process.
Syntax
int ptrace (request, pid, addr, data);
int request, pid, data, addr;
Description
ptrace provides a means by which a parent process may
control the execution of a child process. Its primary use
is in the implementation of breakpoint debugging; see
adb(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 ``memory 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 addr argument is dependant on the underlying machine
type, specifically the process memory model. On systems
where the memory management mechanism provides a uniform and
linear address space to user processes, the argument is
declared as:
int *addr;
which is sufficient to address any location in the process'
memory. On machines where the user address space is
segmented (even if the particular program being traced has
only one segment allocated), the form of the addr argument
is:
struct saddr {
unsigned short sa_seg;
long sa_off;
} *addr;
which allows the caller to specify segment and offset in the
process address space.
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
Page 1 (printed 8/7/87)
PTRACE(S) XENIX System V PTRACE(S)
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 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.
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, 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
follow:
Page 2 (printed 8/7/87)
PTRACE(S) XENIX System V PTRACE(S)
-The general registers
-Any floating-point status registers
-Certain bits of the processor status
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.
In a linear address space memory model, the value
of addr must be (int *)1, or in a segmented
address space the segment part of addr must be
zero and the offset part of addr must be (int *)1.
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 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. This is part of
the mechanism for implementing breakpoints. The
exact implementation and behaviour is somewhat CPU
dependant.
As indicated, these calls (except for request 0) can be
used only when the subject process has stopped. The
wait system call is used to determine when a process
stops; in such a case the termination status returned
by wait has the value 0177 to indicate stoppage rather
than genuine termination.
To prevent security violations, 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.
Errors
ptrace will in general fail if one or more of the following
are true:
request is an illegal number. [EIO]
Page 3 (printed 8/7/87)
PTRACE(S) XENIX System V PTRACE(S)
pid identifies a child that does not exist or has not
executed a ptrace with request 0. [ESRCH]
Notes
The implementation and precise behaviour of this system call
is inherently tied to the specific CPU and process memory
model in use on a particular machine. Code using this call
is likely to not be portable across all implementations
without some change.
See Also
adb(CP), exec(S), signal(S), wait(S), machine(HW)
Page 4 (printed 8/7/87)