HP-UX Reference (11i v1 05/09) - 2 System Calls (vol 5)

t
ttrace(2) ttrace(2)
NAME
ttrace - tracing facility for multithreaded processes
SYNOPSIS
#include <sys/ttrace.h>
int ttrace (ttreq_t request, pid_t pid, lwpid_t lwpid,
uint64_t addr, uint64_t data, uint64_t addr2);
Remarks
While the posix API is defined and will not change, the present underlying system calls are not guaranteed
to be compatible with future versions.
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
The ttrace() 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 and event driven debugging; see adb(1) and
dde(1).
ttrace() is designed to function for both single and multithreaded traced processes. The traced
process behaves normally until one of its threads encounters a signal (see signal(2) for the list), or an event
(these are discussed in detail in the EVENTS section below) at which time the thread enters a stopped
state and the tracing process is notified via
ttrace_wait()
.
The request argument determines the action to be taken by
ttrace() and is one of the following:
TT_PROC_SETTRC
This request must be issued by a child process if it is to be traced by its parent.
For this request, the pid, lwpid, addr, and addr2 arguments must be set to 0 (zero) and
data must be set to TT_VERSION . Peculiar results occur if the parent does not expect to
trace the child.
Note that it is critical for future backward compatibility that the
TT_VERSION macro
itself be used and not its value.
All other requests are to be used only by the tracing process. They are divided in two groups: requests that
target a process and requests that target a specific thread within the process. For all process-wide requests
(those prefixed by
TT_PROC_), pid is the process ID of the traced process and lwpid must be set to zero.
The process-wide requests are:
TT_PROC_ATTACH
This request allows the calling process to trace the process identified by pid. The 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 the process pid unless the effective user ID of
the tracing process is super-user.
When this call returns, the target process (all its threads) is stopped.
The addr argument specifies the action to be taken if the debugger exits without having
detached the target process. If the value is
TT_KILL_ON_EXIT, the attached process(es)
will be killed. If the value is TT_DETACH_ON_EXIT, the attached process(es) will be
resumed and detached as if the debugger had performed a TT_PROC_DETACH request.
The lwpid and addr2 arguments must be set to zero and data must be TT_VERSION (see
TT_PROC_SETTRC above).
TT_PROC_DETACH
This request detaches the traced process and allows it to continue executing. It behaves
identically to TT_PROC_CONTINUE except that the process is no longer being traced after
the call returns.
For this request, the lwpid, addr, data and addr2 arguments must be set to zero.
TT_PROC_RDTEXT
TT_PROC_RDDATA
These requests allow reading from the target process text (TT_PROC_RDTEXT) or data
space (TT_PROC_RDDATA).
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 2−−435