ttrace(2) ttrace(2)
NAME [Toc] [Back]
ttrace - tracing facility for multithreaded processes
SYNOPSIS [Toc] [Back]
#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 [Toc] [Back]
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 [Toc] [Back]
The ttrace() system call provides a means by which a process can
control the execution of another process. 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 [Toc] [Back]
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
process matches the real and saved uid of the target process. This is
true unless the effective user ID of the calling process is superuser.
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
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
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
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 [Toc] [Back]
TT_PROC_RDDATA
TT_PROC_RDTEXT_NOATTACH
TT_PROC_RDDATA_NOATTACH
These requests allow reading from the target process
text (TT_PROC_RDTEXT and TT_PROC_RDTEXT_NOATTACH) or
data space (TT_PROC_RDDATA and
TT_PROC_RDDATA_NOATTACH).
The addr argument specifies the offset to be read from.
The data argument specifies the number of bytes to read
and the addr2 argument specifies where to store that
data in the tracing process.
The lwpid argument must be set to zero.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
TT_PROC_WRTEXT [Toc] [Back]
TT_PROC_WRDATA These requests allow writing into the target process
text (TT_PROC_WRTEXT) and data spaces (TT_PROC_WRDATA).
The addr argument specifies the offset to be written
to. The data argument specifies the number of bytes to
write.a The addr2 argument specifies where to get the
data in the tracing process.
The lwpid argument must be set to zero.
TT_PROC_STOP This request causes the traced process (all its
threads) to stop. If a thread was already stopped by
the debugger prior to this call, its state is not
modified.
The lwpid, addr, data and addr2 arguments must be set
to zero.
TT_PROC_CONTINUE [Toc] [Back]
This request causes the entire traced process to resume
execution. All threads that had been stopped directly
(request) or indirectly (event) by the debugger are
resumed with all their pending signals intact.
The data, addr and addr2 arguments must be set to zero.
TT_PROC_GET_PATHNAME [Toc] [Back]
This request is used by the calling process to access
the path name of the executable file provided as a path
or file argument to exec(). The request reads data
bytes of data of the pathname string from the traced
process' context into the data buffer in user space
pointed to by addr.
In the typical case, data is equal to the value of the
ttexec_data_t.tts_len member of the ttstate_t structure
returned via the TT_LWP_GET_STATE or other ttrace
requests returning a Lightweight Process (LWP or lwp)
state. The length of the path does not include a
terminating null character. The data is available
during the entire life of the process.
The lwpid and addr2 arguments must be set to zero.
TT_PROC_GET_EVENT_MASK [Toc] [Back]
This request returns the process-wide event flags and
signal mask values.
The data argument specifies the number of bytes to be
read from the context of the traced process into the
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
ttevent_t data structure in user space pointed to by
addr.
The lwpid and addr2 arguments must be set to zero.
The ttevent_t data structure is as follows:
typedef struct {
sigset_t tte_signals;
ttevents_t tte_events;
tteopt_t tte_opts;
} ttevent_t;
The options provided in tte_opts control the behavior
of child processes produced by fork() and are as
follows:
TTEO_NONE = 0x0000
TTEO_NOSTRCCHLD = 0x0001
TTEO_PROC_INHERIT = 0x0002
TTEO_LWP_INHERIT = 0x0004
TTEO_NORM_SIGTRAP = 0x0008
If TTEO_NOSTRCCHLD is set, the child process resulting
from a fork() will not be traced. This makes it
possible for a debugger to debug another debugger. The
TTEO_PROC_INHERIT and TTEO_LWP_INHERIT options allow
events to be inherited by child processes and threads
respectively. Refer to the EVENTS section below.
If TTEO_NORM_SIGTRAP is set, the SIGTRAP signal behaves
normally. That is, it is getting delivered (the default
behavior is to drop these signals).
TT_PROC_SET_EVENT_MASK [Toc] [Back]
This request allows the tracing process to establish
events and signals the traced process will respond to.
Refer to the EVENTS section for a description of these
events.
The addr argument is a pointer to a ttevent_t structure
to be copied into the target process. The data
argument specifies the number of bytes to be
transferred.
The lwpid and addr2 arguments must be set to zero.
TT_PROC_GET_SIGMASK [Toc] [Back]
This request returns the process-wide signal mask value
for the target process that was set using
TT_PROC_SET_SIGMASK.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
The data argument specifies the number of bytes to be
read from the context of the traced process into the
ttmask_t data structure in user space pointed by addr.
The lwpid and addr2 arguments must be set to zero.
The ttmask_t data structure is as follows:
typedef struct {
sigset_t ttm_signals;
ttmopt_t ttm_opts;
} ttmask_t;
The options provided in ttm_opts control the behavior
of signal masks on child processes produced by fork()
and are as follows:
TTMO_NONE = 0x0000
TTMO_PROC_INHERIT = 0x0001
TTMO_LWP_INHERIT = 0x0002
The TTMO_PROC_INHERIT and TT_LWP_INHERIT option allow
signal masks to be inherited by child processes and
threads respectively.
TT_PROC_SET_SIGMASK [Toc] [Back]
This request allows the tracing process to change the
signal mask on the target process.
The addr argument is a pointer to a ttmask_t structure
to be copied into the target process. The data
argument specifies the number of bytes to be
transferred.
The lwpid and addr2 arguments must be set to zero.
The resulting signal mask on the traced process will be
a union of the current signal mask on the target
process and the set pointed by the ttm_signals field in
the ttmask_t structure. Setting the ttm_signals to an
empty set results in clearing the signal mask that was
previously set using this request.
TT_PROC_GET_FIRST_LWP_STATE [Toc] [Back]
This request returns the ttstate_t structure associated
with the first thread on the stopped list. It resets
the list pointer to the first entry in the list. The
TT_PROC_GET_NEXT_LWP_STATE request (see below) provides
the means to examine the state of other stopped
threads.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
The data argument specifies the number bytes to be read
from the context of the traced process into the
ttstate_t data structure in the user space pointed to
by addr. The lwpid and addr2 arguments must be zero.
The ttstate_t structure provides the debugger with the
means to query the system for the state of a thread. It
is established when a thread enters the debugger
stopped state and, except for the TTS_WAITEDFOR bit, is
invariant until the thread is resumed. Its layout is as
follows:
typedef struct {
pid_t tts_pid;
lwpid_t tts_lwpid;
uint64_t tts_user_tid;
ttevents_t tts_event;
ttsf_t tts_flags;
int tts_scno;
int tts_scnargs;
uint64_t tts_scarg[SCALL_MAXARGS];
union {
ttexec_data_t tts_exec;
ttfork_data_t tts_fork;
ttprefork_data_t tts_prefork;
ttsignal_data_t tts_signal;
ttthread_data_t tts_thread;
ttsyscall_data_t tts_syscall;
ttexit_data_t tts_exit;
ttbpt_data_t tts_bpt_sstep;
char tts_fill[128];
} tts_u;
} ttstate_t;
tts_pid is the process ID.
tts_lwpid is the lwpid of the stopped thread.
tts_user_tid is the thread's user ID.
tts_event is the event that caused the stop (TTEVT_NONE
if the thread stopped because of a ttrace command).
The tts_flags provide information about the state of
the thread before it was stopped. The information
specifies whether or not the thread has been waited for
by ttrace_wait(), whether or not it is processing a
system call, whether it is a 32-bit or a 64-bit process
and whether the thread is in the exit() system call.
The values are as follows:
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
TTS_WASSUSPENDED = 0x0001
TTS_WASSLEEPING = 0x0002
TTS_WASRUNNING = 0x0004
TTS_WAITEDFOR = 0x0008
TTS_INSYSCALL = 0x0010
TTS_IS32BIT = 0x0020
TTS_ATEXIT = 0x0040
The following three arguments provide information
regarding the system call being executed when the
thread was stopped. This information is valid only if
the TTS_INSYSCALL bit is set in tts_flags.
tts_scno is the system call number.
tts_scnargs is the number of arguments of the system
call.
tts_scarg is the argument list of the system call.
The data associated with a TTEVT_EXEC event is as
follows:
typedef struct {
int tts_pathlen;
} ttexec_data_t;
tts_pathlen is the length of the pathname of the exec()
system call.
The data associated with a TTEVT_FORK, TTEVT_VFORK or
TTEVT_FORK_FAIL event is as follows:
typedef struct {
pid_t tts_fpid;
lwpid_t tts_flwpid;
int tts_isparent;
int tts_errno;
} ttfork_data_t;
tts_fpid is the process ID of the other side of the
fork. This field is set to zero for the
TTEVT_FORK_FAIL event.
tts_flwpid is the thread ID of the other side of the
fork. This field is set to zero for the
TTEVT_FORK_FAIL event.
tts_isparent is zero for the child event and one for
the parent.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
tts_errno is set to error code indicating the reason
for error in TTEVT_FORK_FAIL event. This field is set
to zero for the TTEVT_FORK and TTEVT_VFORK events.
The data associated with a TTEVT_PREFORK event is as
follows:
typedef enum {
TTS_FORK,
TTS_VFORK
} ttpf_t;
typedef struct {
pid_t tts_fpid;
lwpid_t tts_flwpid;
ttpf_t tts_type;
} ttprefork_data_t;
tts_fpid is the process ID of the other side of the
fork.
tts_flwpid is the thread ID of the other side of the
fork.
tts_type is the type of fork.
The data associated with a TTEVT_SIGNAL event is as
follows:
typedef struct {
int tts_signo;
ttsigf_t tts_sigflags;
uint64_t tts_sigaction;
siginfo_t tts_siginfo;
} ttsignal_data_t;
tts_signal is the signal number.
tts_sigflags is TTSF_USERSIGINFO if a siginfo was
delivered with the signal, 0 otherwise.
tts_sigaction is the disposition of the signal.
tts_siginfo is the siginfo, if applicable.
The data associated with a TTEVT_LWP_CREATE,
TTEVT_LWP_TERMINATE or TTEVT_LWP_ABORT_SYSCALL event is
as follows:
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
typedef struct {
lwpid_t tts_target_lwpid;
} ttthread_data_t;
tts_target_lwpid is the lwpid of the targeted lwp.
The data associated with a TTEVT_SYSCALL event is as
follows:
typedef struct {
int64_t tts_rval[2];
int tts_errno;
} ttsyscall_data_t;
The tts_rval fields are the return value(s) of the
system call.
tts_errno is the error status if the system call
failed.
The data associated with a TTEVT_LWP_EXIT event is as
follows:
typedef struct {
int tts_exitcode;
} ttexit_data_t;
tts_exitcode is the exit code of the process.
The data associated with a TTEVT_BPT_SSTEP event is as
follows:
On PA-RISC:
typedef struct {
int tts_isbpt;
} ttbpt_data_t;
tts_isbpt is set to zero if it is a single-step and to
one if the event is a breakpoint (including singlestepping
into a breakpoint).
On Itanium(R)-based system:
typedef enum {
TTBPT_SSTEP = 0, /* Single stepping */
TTBPT_BPT, /* Breakpoint */
TTBPT_TBRANCH /* Taken Branch */
} ttbpt_type_t;
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
typedef struct {
ttbpt_type_t tts_isbpt;
} ttbpt_data_t;
TT_PROC_GET_NEXT_LWP_STATE [Toc] [Back]
This request is identical to
TT_PROC_GET_FIRST_LWP_STATE except that it returns the
state for the next thread on the stopped list. As
events cause threads to stop, they are added to this
list. This provides a way for the tracing process to
examine the state of all the stopped threads in the
target process. Both these requests return either a 1
(one) if valid data is returned or 0 (zero) otherwise.
Valid data is returned if the status is that there was
a stopped thread for which to return.
TT_PROC_GET_MPROTECT [Toc] [Back]
This request allows the debugger to obtain protection
information for a page in the address space of the code
being debugged. The addr argument specifies the
address for which the protection is to be obtained.
The addr2 argument specifies the address of an integer
in which the protection data will be copied.
For this request, the lwpid and data arguments must be
set to zero.
TT_PROC_SET_MPROTECT [Toc] [Back]
This requests allows the debugger to modify the
protection of the address space of the code being
debugged. The addr argument specifies the start
address. The data argument specifies the extent (in
bytes) of the space to be modified. The addr2 argument
contains the new protection. Note that protection
changes affect whole pages (see mprotect(2) for more
information).
For this request, the lwpid argument must be set to
zero.
TT_PROC_SET_SCBM [Toc] [Back]
This request allows the debugger to pass a bitmap to
the kernel indicating which system calls should cause a
debugger stop.
The addr argument must be set to TTSCBM_SELECT or
TTSCBM_UNSELECT to indicate whether the bitmap
represents a positive (meaning that the calls in the
bitmap will result in a stop) or a negative (meaning
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
that all calls except those in the bit map will result
in a stop) list.
The data argument is the size of the bitmap, in bytes.
A size of zero indicates that the current bitmap, if
any, should be cleared.
The addr2 argument is the user address where the bitmap
is located. If data is zero, this value must be zero
too.
The lwpid argument must be zero.
TT_PROC_EXIT This request causes the traced process to terminate.
It has the same consequence as exit() being invoked by
one of the process threads. The lwpid, addr, data and
addr2 arguments must be zero.
TT_PROC_CORE This request causes the traced process to generate a
core file without modifying the process's state. If
addr is zero, the core file is created in the target
process's current working directory and is named
core.pid; where, pid is the process ID of the target
process. If addr is non-zero, it is the address of a
buffer containing the path of the core file to be
created. Up to MAXPATHLEN bytes will be read from the
buffer. If the path is not absolute (not starting with
a slash), it is relative to the target process's
current working directory. In both cases, the
directory must exist and, if present, the file must be
a regular file. In all cases, the debugger's
credentials are used and standard permission checking
applies. The lwpid, data and addr2 arguments must be
zero.
TT_PROC_GET_NUM_IBPT_REGS [Toc] [Back]
TT_PROC_GET_NUM_DBPT_REGS
These requests return the number of physical hardware
instruction or data breakpoint registers that are
available for use.
TT_PROC_SET_IBPT_REGS [Toc] [Back]
TT_PROC_SET_DBPT_REGS
These requests write process-wide breakpoint values
into breakpoint registers. data bytes from addr2 will
be written to the instruction or data breakpoint
register(s) named by addr. For Itanium-based system,
addr must be an even number less than the value
returned by TT_PROC_GET_NUM_IBPT_REGS or
TT_PROC_GET_NUM_DBPT_REGS respectively. data must be
16 bytes. The request will set a value into the pair
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
of instruction or data breakpoint registers addr and
addr+1.
Note: The available breakpoint registers must be shared
between process-wide breakpoints and per-thread
breakpoints. If a breakpoint register is currently
being used as a per-thread breakpoint in any thread
within the target process, it may not be used for a
process-wide breakpoint.
Note: This does not limit the number of break
instructions that may be present in the program text.
Note: These requests are not supported on PA-RISC
versions of HP-UX.
TT_PROC_GET_IBPT_REGS [Toc] [Back]
TT_PROC_GET_DBPT_REGS
These requests read process-wide breakpoint values from
breakpoint registers. data bytes are copied from the
instruction or data breakpoint register(s) specified by
addr to addr2 in debugger memory. data must be 16
bytes. The request will get the value of the pair of
instruction or data breakpoint registers addr and
addr+1.
Note: These requests are not supported on PA-RISC
versions of HP-UX.
TT_PROC_GET_ARGS [Toc] [Back]
This request returns a pointer to the argument list
passed to the initial thread of the process at
execve(2) time. (i.e. argc, argv, envp) If the target
process has not overwritten these arguments, this
address can be used to retrieve the full argument and
environment list.
Note: This request is not supported on PA-RISC versions
of HP-UX.
Other Requests [Toc] [Back]
All other requests, except non debug-related requests below, are
targeted to a specific thread in the target process. Also, all other
requests require both the pid of the target process and an lwpid
specifying a valid thread in the target process. These requests are
prefixed by TT_LWP_ and are as follows:
TT_LWP_STOP [Toc] [Back]
This request causes the thread identified by lwpid to stop
executing. If the thread is already stopped by the debugger, or
by an event, an error is returned.
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
The addr, data and addr2 arguments must be zero.
TT_LWP_CONTINUE [Toc] [Back]
This request causes the thread identified by lwpid to resume
execution or, rather, to return to the state it was in prior to
being stopped by the debugger. If the thread had not previously
been stopped by the debugger, an error is returned.
If addr is not TT_NOPC, that value is loaded in the program
counter before execution is resumed. Unexpected behavior will
result if this value is not within the same function since only
the PC, not the context, is being modified.
If data is non-zero, it is expected to be a valid signal number
and the thread will continue as if it had received this signal.
The addr2 argument must be zero.
TT_LWP_SINGLE [Toc] [Back]
This request causes the stopped thread identified by lwpid to
resume execution for one machine instruction. It causes a flag
to be set so that an interrupt occurs upon the completion of one
machine instruction, and then executes the same steps as listed
above for the TT_LWP_CONTINUE request.
TT_LWP_TBRANCH [Toc] [Back]
This request causes the stopped thread identified by lwpid to
resume execution until a taken branch instruction is executed.
It causes a flag to be set so that an interrupt occurs upon
completion of the next taken branch instruction, and then
executes the same steps as listed above for the TT_LWP_CONTINUE
request.
Note: This request is not supported on PA-RISC versions of HP-UX.
TT_LWP_GET_EVENT_MASK [Toc] [Back]
This request is the same as TT_PROC_GET_EVENT_MASK except for the
thread identified by lwpid.
TT_LWP_SET_EVENT_MASK [Toc] [Back]
This request is the same as TT_PROC_SET_EVENT_MASK except for the
thread identified by lwpid.
TT_LWP_GET_SIGMASK [Toc] [Back]
This request is the same as TT_PROC_GET_SIGMASK except for the
thread identified by lwpid.
TT_LWP_SET_SIGMASK [Toc] [Back]
This request is the same as TT_PROC_SET_SIGMASK except for the
thread identified by lwpid.
Hewlett-Packard Company - 13 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
TT_LWP_GET_STATE [Toc] [Back]
This calls returns the state of the thread identified by lwpid.
If the thread was not previously stopped by the debugger or
waiting to be continued after an event, an error is returned.
TT_LWP_SET_IBPT_REGS [Toc] [Back]
TT_LWP_SET_DBPT_REGS
These requests write per-thread breakpoint values into breakpoint
registers. data bytes from addr2 will be written to the
instruction or data breakpoint register(s) named by addr. For
Itanium-based, addr must be an even number less than the value
returned by TT_PROC_GET_NUM_IBPT_REGS or
TT_PROC_GET_NUM_DBPT_REGS respectively. data must be 16 bytes.
The request will set a value into the pair of instruction or data
breakpoint registers addr and addr+1. These values will be
enabled only when the specified thread is running. They are
identical to TT_PROC_SET_IBPT_REGS and TT_PROC_SET_DBPT_REGS
respectively in other respects.
Note: The available breakpoint registers must be shared between
process-wide breakpoints and per-thread breakpoints. If a
breakpoint register is currently being used as a process-wide
breakpoint within the target process, it may not be used for a
per-thread breakpoint in any thread of the target process.
Note: These requests are not supported on PA-RISC versions of
HP-UX.
TT_LWP_GET_IBPT_REGS [Toc] [Back]
TT_LWP_GET_DBPT_REGS
These requests read per-thread breakpoint values from breakpoint
registers. They are identical to TT_PROC_GET_IBPT_REGS and
TT_PROC_GET_DBPT_REGS respectively in other respects.
Note: These requests are not supported on PA-RISC versions of
HP-UX.
TT_LWP_RDRSEBS [Toc] [Back]
TT_LWP_WRRSEBS
TT_LWP_RDRSEBS_NOATTACH
These requests allow the calling process to access stacked
general register values that have not yet been written to the RSE
backing store. data bytes that would have been spilled at addr
on the user's RSE backing store, had the RSE been flushed, are
copied to or from addr2 in the the calling process. The addr
argument must be 8-byte-aligned and conform to ar.bspstore _ addr
< ar.bsp. data must be a multiple of 8 bytes, and addr+data must
also conform to ar.bspstore _ addr+data < ar.bsp. As a special
case, to retrieve the final NaT collection, addr == ar.bsp |
0x1f8 and data == 8 is also accepted.
Hewlett-Packard Company - 14 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
Note: This facility should be used only to modify values of
registers that were dirty when the thread was stopped. Do not
use this facility if the values of ar.bsp or ar.bspstore have
been modified.
Note: These requests are not supported on PA-RISC versions of
HP-UX.
Non-debug-related Request [Toc] [Back]
There is currently only one non debug-related request:
TT_NDR_GET_FLEV [Toc] [Back]
This call returns the feature level of the operating system and
has been introduced to help debugger developers make their tools
more portable from one version to another. 11.0 systems can be
identified by the fact that this call will return an error.
Later releases will return the TT_FEATURE_LEVEL value the
operating system was compiled with (see ttrace.h). The release
levels for systems newer than 11.0 are:
Level 5: internal change
Level 6: add DETACH_ON_EXIT attach option.
Level 7: add TTEVT_BPT_SSTEP event.
Level 8: add TT_PROC_SET_IBPT, TT_PROC_SET_DBPT,
TT_PROC_GET_IBPT, TT_PROC_GET_DBPT,
TT_PROC_GET_NUM_IBPT_REGS, TT_PROC_GET_NUM_DBPT_REGS,
TT_PROC_GET_ARGS, TT_LWP_SET_IBPT, TT_LWP_SET_DBPT,
TT_LWP_GET_IBPT, TT_LWP_GET_DBPT, TT_LWP_RDRSEBS,
TT_LWP_WRRSEBS, TT_LWP_TBRANCH requests.
Level 9: add TT_PROC_GET_SIGMASK, TT_PROC_SET_SIGMASK,
TT_LWP_GET_SIGMASK, TT_LWP_SET_SIGMASK requests.
Level 10: add TTEVT_PREFORK, TTEVT_FORK_FAIL events.
Level 11: allow the TT_PROC_CORE request to generate user
specified core file names.
Level 12: add _NOATTACH requests.
Security Restrictions [Toc] [Back]
For security reasons, ttrace() inhibits the set-user-ID facility on
subsequent exec() calls.
Events [Toc] [Back]
As noted earlier, a tracing process can set event flags in the context
of a traced process, or its individual threads, to cause the threads
to respond to specific events during their execution. When an event
Hewlett-Packard Company - 15 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
flag is set in the context of the process, all threads in the process
respond to the event. When set in the context of a thread, only the
specific thread will respond to the event.
Important [Toc] [Back]
If an event is requested by the process, the event mask of the thread
is not examined. For the event mask of the thread to be significant,
the process event must be be unset. Similarly, if an event option is
enabled in the process, the option for the thread is not considered.
Event masks may be inherited across fork() using the tte_opts options
in the ttevent_t structure. If TTEO_PROC_INHERIT is set, the child
process inherits the event mask of its parent. If TTEO_LWP_INHERIT is
set, the lwp inherits the event mask of the lwp that invoked fork().
If the latter is set, the lwp created by lwp_create() also inherits
the event mask of the creating thread.
These events are:
TTEVT_SIGNAL This event flag indicates that the traced thread
needs to examine signal mask bits when processing
signals. This means that, by default, threads stop
when receiving a signal. If the signal being
processed has its mask bit set, signal processing
continues as though the process were not traced: the
traced thread is not stopped, and the tracing
process is not notified of the signal. On the other
hand, if the signal mask bit is not set for the
signal being processed, the traced thread is stopped
and the tracing process is notified via
ttrace_wait().
Note that the SIGKILL signal can never be unmasked.
It behaves as though its mask bit were always set.
This means that a SIGKILL signal cannot be used to
stop a traced thread. The SIGTRAP signal is also
special in that it is used to stop traced threads
when they respond to a trap, such as a breakpoint or
a single step. Consequently, masking SIGTRAP, even
though allowed, will result in unexpected behavior
in these conditions.
TTEVT_FORK This event flag indicates that the traced thread
needs to take special action when it invokes fork().
When set, both the parent thread and the initial
thread in the child process stop (after the child
process is marked as a traced process and adopts its
parent's debugger). Both threads log the fact that
they stopped in response to a TTEVT_FORK event. The
parent thread provides the pid of the child process
in the appropriate portion of the ttstate_t
structure. The initial thread of the child process
Hewlett-Packard Company - 16 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
provides the pid of the parent in the same location.
See the ttstate_t structure description for further
details.
TTEVT_VFORK This event flag indicates that the traced thread
needs to take special action when it invokes
vfork(). The behavior is identical to that of
TTEVT_FORK but it is important to note that the
caveats with respect to vfork(), continue to apply
here. In particular, it needs to be remembered that
when the child process stops, its parent is asleep,
and that the child borrows the parent's address
space until a call to exec() or an exit (either by a
call to exit() or abnormally) takes place.
Continuing the parent process before the above steps
take place results in an error.
TTEVT_PREFORK This event flag indicates that the traced thread
needs to notify the debugger, during a fork() or
vfork() operation, just after the child process ID
and thread ID is known and before the child process
is created and set to run. The parent thread is
stopped and it provides the pid of the child process
and lwpid of the child's initial thread.
Note: Upon continuation from this event, the traced
thread does not guarantee that the child process
with an earlier returned pid and lwpid can be
created since the fork() or vfork() operation might
fail.
TTEVT_FORK_FAIL This event flag indicates that the traced thread
needs to notify the debugger upon the failure of a
fork() or vfork() operation. The traced parent
thread is stopped and returns the error code for
fork failure.
TTEVT_EXEC This event flag indicates that a traced thread needs
to notify the debugger upon completion of loading
the new executable file, in the exec() system call.
The length of the pathname string (not including a
null terminating character) is returned in the
ttstate_t structure. The path may subsequently be
obtained using the TT_PROC_GET_PATHNAME request.
TTEVT_SYSCALL_RETURN [Toc] [Back]
This event flag indicates that the traced process
will notify the debugger upon return of all system
calls. The traced process will also provide the
following information: the system call number, its
number of arguments and all its arguments, its
Hewlett-Packard Company - 17 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
return value and its error return in the ttstate_t
structure. If the system call is a fork(), vfork()
or exec() and if, respectively, the TTEVT_FORK,
TTEVT_VFORK or TTEVT_EXEC event is set, only the
notification associated with these events is
performed. See the TT_PROC_SET_SCBM request.
TTEVT_SYSCALL_ENTRY [Toc] [Back]
This event flag requests notification of system call
entry points. By default, all system calls stop at
this event if it is selected. The information
provided is the same as for TTEVT_SYSCALL_RETURN
events but the return value and error are always
zero.
TTEVT_SYSCALL_RESTART [Toc] [Back]
Identical to TTEVT_SYSCALL_ENTRY but for system call
restarts.
TTEVT_EXIT This event flag indicates that the traced process
needs to notify the debugger action when it invokes
exit(). When set, the traced thread stops while
still potentially multithreaded.
TTEVT_LWP_CREATE This event flag indicates that the debugger wants to
be notified when the lwp_create() system call is
invoked to create a thread. When set, the calling
thread stops and provides the debugger with the
lwpid of the newly created thread.
TTEVT_LWP_EXIT This event flag indicates that the debugger wants to
be notified when a thread is exiting via the
lwp_exit() system call. The thread stops upon entry
to the system call.
TTEVT_LWP_TERMINATE [Toc] [Back]
This event flag indicates that the debugger wants to
be notified when a caller thread invokes the
lwp_terminate() call on a target thread. When set,
the calling thread stops upon entering the system
call and provides the lwpid of the thread to be
terminated in the ttstate_t structure.
TTEVT_LWP_ABORT_SYSCALL [Toc] [Back]
This event flag indicates that the debugger is to be
notified when the lwp_abort_syscall() system call is
invoked. The lwpid of the target thread is provided
in the ttstate_t structure.
TTEVT_BPT_SSTEP This event flag tells the kernel to perform eventbased
single-stepping and breakpoint notification.
Hewlett-Packard Company - 18 - HP-UX 11i Version 2: August 2003
ttrace(2) ttrace(2)
If this event is requested, SIGTRAP loses all
special meaning. It is highly recommended that
debuggers use this event instead of the old signalbased
method as it will allow breakpoints and
single-steps to take place regardless of the signals
the thread is blocking. Unlike the signal-ba
|
