HP-UX Reference (11i v3 07/02) - 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()
.
Requests
Most of the
ttrace() requests are to be used only by the tracing process. However, some requests (those
suffixed by _NOATTACH) can be used by any process provided that the effective user ID of the calling pro-
cess matches the real and saved uid of the target process. This is true unless the calling process has the
OWNER privilege.
ttrace() requests are divided in four groups: requests that target a process, requests that target a
specific thread within the process, requests that perform a series of requests on a process or thread, and
non-debug-related requests that target neither a process or a thread.
The request argument determines the action to be taken by ttrace() and is one of the following:
Process-Wide Requests
For all process-wide requests (those prefixed by TT_PROC_), pid is the process ID of the target process and
lwpid must be set to zero.
TT_PROC_SETTRC
This request must be issued by a child process if it is to be traced by its parent.
The addr2 argument specifies the action to be taken by the loader when the child process
does an exec(). If the value is TT_GEN_SHLIB_BPT
, the loader will communicate cer-
tain events to the debugger through an architected break instruction. The information
obtained through these events can be used by the debugger to identify all the load modules
in the program and their unwind information. If the debugger is not interested in these
events the value must be set to 0 (zero).
The pid, lwpid, and addr 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: It is critical for future backward compatibility that the TT_VERSION macro itself be
used and not its value.
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 tracing process has
the OWNER privilege.
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.
HP-UX 11i Version 3: February 2007 − 1 − Hewlett-Packard Company 497