HP-UX Reference (11i v2 07/12) - 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 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 target process and lwpid must be set to zero.
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: 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.
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.
HP-UX 11i Version 2: December 2007 Update − 1 − Hewlett-Packard Company 481