HP-UX Reference (11i v2 07/12) - 2 System Calls (vol 5)

p
ptrace(2) ptrace(2)
(PA-RISC 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 sig-
nal 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 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 request argument 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].
300 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: December 2007 Update