HPUX ptrace[2]
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 this capability 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
ptrace() provides a means by which a process can control the execution
of another process. 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)). When the traced process is in the stopped
state, the tracing process can examine and modify the "core image"
using ptrace(). Also, the tracing process can cause the traced
process 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:
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 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.
PT_RIUSER, PT_RDUSER
With these requests, the word at location addr in
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
ptrace(2) ptrace(2)
the address space of the traced process 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 PT_RIUSER
or request PT_RDUSER can be used with 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. This
request fails 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 tracing process
and its errno is set to EIO.
PT_WIUSER, PT_WDUSER
With these requests, the value given by the data
argument is written into the address space of the
traced process at location addr. Request
PT_WIUSER writes a word into I space, and request
PT_WDUSER writes a word in D space. Upon
successful completion, the value written into the
address space of the traced process is returned to
the tracing process. The addr2 argument is
ignored. These two requests fail if addr is not
the start address of a word, or if addr is a
location in a pure procedure space and either
another process is executing in that space or the
tracing process does not have write access for the
executable file corresponding to that space. Upon
failure a value of -1 is returned to the tracing
process and its errno is set to EIO.
PT_WUAREA With this request, a few entries in the traced
process' USER area can be written. data gives the
value that is to be written and addr is the
location of the entry. The addr2 argument is
ignored. The few entries that can be written are
dependent on the architecture of the system, but
include the user data registers, auxiliary data
registers, and status register (the set of
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
ptrace(2) ptrace(2)
registers, or bits in registers, that the user's
program could modify).
PT_CONTIN This request causes the traced process to resume
execution. If the data argument is 0, all pending
signals, including the one that caused the traced
process to stop, are canceled before it resumes
execution. If the data argument is a valid signal
number, the traced process 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. The addr2 argument
is ignored. Upon successful completion, the value
of data is returned to the tracing process. This
request fails if data is not 0 or a valid signal
number, in which case a value of -1 is returned to
the tracing process and its errno is set to EIO.
PT_EXIT This request causes the traced process to
terminate with the same consequences as exit().
The addr, data, and addr2 arguments are ignored.
PT_SINGLE This request causes a flag to be set so that an
interrupt occurs uponthe completion of one machine
instruction, and then executes the same steps as
listed above for request PT_CONTIN. If the
processor does not provide a trace bit, this
request returns an error. This effectively allows
single stepping of the traced process.
Whether or not the trace bit remains set after
this interrupt is a function of the hardware.
PT_ATTACH This request stops the process identified by pid
and allows the calling process to trace it.
Process pid does not have to be a child of the
calling process, but the effective user ID of the
calling process must match the real and saved uid
of process pid unless the effective user ID of the
tracing process is super-user. The calling
process can use the wait() system call to wait for
process pid to stop. The addr, data, and addr2
arguments are ignored.
PT_DETACH This request detaches the traced process pid and
allows it to continue its execution in the manner
of PT_CONTIN.
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
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
ptrace(2) ptrace(2)
image showing signal SIGTRAP.
ERRORS
In general, ptrace() fails if any of the following conditions are
encountered:
[EIO] request is an illegal number.
[EPERM] The specified process cannot be attached
for tracing.
[ESRCH] pid identifies a process to be traced
that does not exist or has not executed
a ptrace() with request PT_SETTRC.
DEPENDENCIES
Series 300/400
The following additional requests are available:
PT_RFPREGS With this request, the child's floating-point
accelerator register set is returned to the parent
process in addr. addr must be the address of a
buffer of at least 136 bytes. The first 128 bytes
contains the 16 double-precision floating-point
registers and the next 8 bytes contains the status
and control registers. The data argument is
ignored. This request fails if the child process
is not using the floating-point accelerator, in
which case a value of -1 is returned to the parent
process and the parent's errno is set to EIO.
This request also fails if addr is a bad address,
in which case a value of -1 is returned to the
parent process and the parent's errno is set to
EFAULT.
PT_WFPREGS With this request, the child's floating-point
accelerator register set is written from the
buffer pointed to by addr. addr must be the
address of a buffer of at least 136 bytes. The
first 128 bytes contains the new values for the 16
double-precision floating point registers and the
next 8 bytes contains the new values for the
status and control registers. The data argument
is ignored. This request fails if the child
process is not using the floating-point
accelerator, in which case a value of -1 is
returned to the parent process and the parent's
errno is set to EIO. This request also fails if
addr is a bad address, in which case a value of -1
is returned to the parent process and the parent's
errno is set to EFAULT.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
ptrace(2) ptrace(2)
Series 700/800
The request PT_WUAREA is not supported. Therefore, it returns -1,
sets errno to EIO and does not affect the USER area of the traced
process.
If the addr argument to a PT_CONTIN or PT_SINGLE request is not 1, the
Instruction Address Offset Queue (program counter) is loaded with the
values addr and addr+4 before execution resumes. Otherwise, execution
resumes from the point where it was interrupted.
If the addr argument to a PT_DETACH request is not 1, the Instruction
Address Offset Queue is loaded with the values addr and addr2.
Additional requests are available:
PT_RUREGS With this request, the word at location addr in
the save_state structure at the base of the per-
process kernel stack is returned to the tracing
process. addr must be word-aligned and less than
STACKSIZE*NBPG (see <sys/param.h> and
<machine/param.h>). The save_state structure
contains the registers and other information about
the process. The data and addr2 arguments are
ignored.
PT_WUREGS The save_state structure at the base of the per-
process kernel stack is written as it is read with
request PT_RUREGS. Only a few locations can be
written in this way: the general registers, most
floating-point registers, a few control registers,
and certain bits of the interruption processor
status word. The addr2 argument is ignored.
PT_RDTEXT, PT_RDDATA
These requests are identical to PT_RIUSER and
PT_RDUSER, except that the data argument specifies
the number of bytes to read and the addr2 argument
specifies where to store that data in the tracing
process.
PT_WRTEXT , PT_WRDATA
These requests are identical to PT_WIUSER and
PT_WDUSER except that the data argument specifies
the number of bytes to write and the addr2
argument specifies where to read that data in the
tracing process.
SEE ALSO
adb(1), exec(2), signal(2), wait(2).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
ptrace(2) ptrace(2)
STANDARDS CONFORMANCE
ptrace(): SVID2, XPG2
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992