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

p
ptrace(2) ptrace(2)
(PA-RISC Only; TO BE OBSOLETED)
PT_SINGLE
This request causes a flag to be set so that an interrupt occurs upon the completion of
one machine instruction. It then executes the same way as listed for request
PT_CONTIN, effectively allowing the single-stepping of the traced process. If the
processor does not provide a trace bit, this request returns an error.
Whether or not the trace bit remains set after this interrupt is a function of the
hardware.
PT_ATTACH This request stops the process specified by the pid argument and allows the calling
process to trace it. The process 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 user ID of
process pid unless the tracing process has the
OWNER privilege. 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 specified by the pid argument and allows it
to continue its execution in the manner of
PT_CONTIN.
If the addr argument is not 1, the Instruction Address Offset Queue (program
counter) is loaded with the values from the addr and addr2 arguments.
PT_CONTIN1 This request causes the traced process to resume execution with all its pending signals
intact. If the data argument is 0, the signal that caused the traced process to stop is
canceled before the traced process resumes execution. If the data argument is a valid
signal number, the traced process resumes execution as if it had received that signal.
The addr argument must be equal to 1 for this request and the addr2 argument is
ignored. Upon successful completion, the value of data is returned to the tracing pro-
cess.
This request fails if data is not 0 or a valid signal number and a value of
-1 is
returned to the tracing process and
errno is set to [EIO].
PT_SINGLE1 This request causes a flag to be set so that an interrupt occurs upon the completion of
one machine instruction. It then executes the same steps as listed above for request
PT_CONTIN1 and provides the single stepping of the traced process. If the processor
does not provide a trace bit, this request returns an error.
Whether or not the trace bit remains set after this interrupt is a function of the
hardware.
As noted earlier, a tracing process can set event flags in the context of the traced process to make it
respond to specific events during its execution. These events are:
PTRACE_SIGNAL This event flag indicates that when processing signals, the traced process needs
to examine signal mask bits set in its context by the tracing process. See the
ptrace_event structure description under PT_SET_EVENT_MASK
for further
details.
If the signal being processed has its signal mask bit set, signal processing contin-
ues as though the process was not traced. The traced process is not stopped and
the tracing process is not notified of the signal. If the signal mask bit is not set
for the signal being processed, the traced process is stopped and the tracing pro-
cess is notified via a
wait() call (see wait(2)).
Note that the SIGKILL signal is an exception to this rule in that it can never be
unmasked; it behaves as though its mask bit were always set, whether or not it
is actually set. Consequently, a SIGKILL signal cannot be used to stop a traced
process.
In this respect, a SIGTRAP signal is also special in that it is specifically used to
stop traced processes. A SIGTRAP signal should therefore never be masked.
Setting a mask bit for SIGTRAP will result in unexpected system behavior.
PTRACE_FORK This event flag indicates that the traced process needs to take special action
when it invokes the fork() call. When set, both the parent and child processes
stop (the child after marking itself as the traced process and adopting its
parent’s debugger). Both processes log the fact that they stopped in response to
a PTRACE_FORK event. Further, the child’s pid argument value is logged in
the parent’s context and the parent’s pid argument value is logged in the child’s
302 Hewlett-Packard Company − 3 − HP-UX 11i Version 2: December 2007 Update