HP-UX Reference (11i v1 00/12) - 2 System Calls (vol 5)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man2/!!!intro.2
________________________________________________________________
___ ___
p
ptrace(2) ptrace(2)
NAME
ptrace() - process trace
SYNOPSIS
#include <sys/ptrace.h>
int ptrace(
int request,
pid_t pid,
int addr,
int data,
int addr2
);
Remarks
Much of the functionality of ptrace() is highly dependent on the underlying hardware. An application
that uses this system call should not be expected to be portable across architectures or implementations.
DESCRIPTION
The ptrace() system call provides a means by which a process can control the execution of another pro-
cess. Its primary use is for the implementation of breakpoint debugging (see adb(1)). The traced process
behaves normally until it encounters a signal (see signal(2) for the list), at which time it enters a stopped
state and the tracing process is notified via
wait() (see wait(2)).
A traced process may also enter the stopped state without encountering a signal. This can happen if the
traced process stops in response to specific events that it encounters during the course of its execution. To
make this happen, the tracing process has to set specific event flags in the context of the traced process.
This mechanism will be described later in greater detail.
When the traced process is in the stopped state, the tracing process can use ptrace() to examine and
modify the "core image". Also, the tracing process can cause the traced process to either terminate or con-
tinue, with the possibility of ignoring the signal that caused it to stop.
To forestall possible fraud,
ptrace() inhibits the set-user-ID facility on subsequent exec*() calls. If a
traced process calls exec*(), it stops before executing the first instruction of the new image, showing sig-
nal SIGTRAP.
The request argument determines the precise action to be taken by ptrace(). It is one of the values
described in the rest of this section.
The following request is used by the child process that will be traced.
PT_SETTRC This request must be issued by a child process if it is to be traced by its parent. It
turns on the child’s trace flag, which stipulates that the child should be left in a
stopped state upon receipt of a signal rather than the state specified by func (see sig-
nal(2)). The pid, addr, data, and addr2 arguments are ignored, and a return value is
not defined for this request. Peculiar results occur if the parent does not expect to
trace the child.
The remainder of the requests can only be used by the tracing process. For each, pid is the process ID of
the process being traced, which must be in a stopped state before these requests are made. The responsibil-
ity of ensuring that the traced process is in a stopped state before a request is issued, lies with the tracing
process.
PT_RDUSER
PT_RIUSER
With these requests, the word at location addr in the address space of the traced pro-
cess is returned to the tracing process. If instruction (I) and data (D) space are
separated, request PT_RIUSER returns a word from I space, and request
PT_RDUSER returns a word from D space. If I and D space are not separated, either
request produces equivalent results. The data and addr2 arguments are ignored.
These two requests fail if addr is not the start address of a word, in which case a value
of −1 is returned to the tracing process and its errno is set to [EIO].
PT_RUAREA With this request, the word at location addr in the user area of the traced process in
the system’s address space (see <sys/user.h> ) is returned to the tracing process.
Addresses in this area are system dependent, but start at zero. The limit can be
derived from <sys/user.h> . The data and addr2 arguments are ignored.
Section 2−−234 − 1 − HP-UX Release 11i: December 2000
___
___