HP-UX Reference (11i v2 04/09) - 2 System Calls (vol 5)

p
ptrace(2) ptrace(2)
(PA Only; TO BE OBSOLETED)
NAME
ptrace() - process trace
SYNOPSIS
#include <sys/ptrace.h>
long ptrace(
int request,
pid_t pid,
long addr,
long data,
long addr2
);
Remarks
ptrace() is not available on Itanium(R)-based systems. Its use is discouraged because it is targeted for
removal from HP-UX. Please use ttrace (2) instead.
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 a breakpoint debugging mechanism (see adb (1)) and
involves a tracing and a traced process. 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
signal SIGTRAP.
The request argument determines the precise action to be taken by
ptrace().
The following request argument 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
signal (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 request arguemnt values 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 responsibility 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 The word specified by the address in the addr argument in the address space of the
traced process is returned to the tracing process. If the 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
errno is set to [EIO].
HP-UX 11i Version 2: September 2004 − 1 − Hewlett-Packard Company Section 2−−265