ttrace.2 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

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 deﬁned 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 applica-

tion that uses this system call should not be expected to be portable across architectures or implementa-

tions.

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 notiﬁed via ttrace_wait()

Requests

Most of the

ttrace() requests are to be used only by the tracing process. However, some requests

(those sufﬁxed by _NOATTACH) can be used by any process provided that the effective user ID of the cal-

ling process 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

speciﬁc 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 preﬁxed 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 speciﬁes 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

certain events to the debugger through an architected break instruction. The informa-

tion 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 identiﬁed by pid. The process

pid does not have to be a child of the calling process, but the effective user ID of the cal-

ling process must match the real and saved uid of the process pid unless the tracing pro-

cess has the OWNER privilege.

When this call returns, the target process (all its threads) is stopped.

The addr argument speciﬁes 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

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (22 pages)

PAGE 1
ttrace(2) ttrace(2) NAME ttrace() - tracing facility for multithreaded processes SYNOPSIS #include 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.
PAGE 2
ttrace(2) ttrace(2) process(es) will be resumed and detached as if the debugger had performed a TT_PROC_DETACH request. The addr2 argument specifies the action to be taken by the loader when the target process does an exec(). If the value is TT_GEN_SHLIB_BPT, the loader will communicate certain events to the debugger through an architected break instruction.
PAGE 3
ttrace(2) ttrace(2) 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.
PAGE 4
ttrace(2) ttrace(2) 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 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.
PAGE 5
ttrace(2) ttrace(2) TTS_WASSUSPENDED TTS_WASSLEEPING TTS_WASRUNNING TTS_WAITEDFOR TTS_INSYSCALL TTS_IS32BIT TTS_ATEXIT = = = = = = = 0x0001 0x0002 0x0004 0x0008 0x0010 0x0020 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.
PAGE 6
ttrace(2) ttrace(2) } 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: typedef struct { lwpid_t } ttthread_data_t; tts_target_lwpid; tts_target_lwpid is the lwpid of the targeted lwp.
PAGE 7
ttrace(2) ttrace(2) 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 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.
PAGE 8
ttrace(2) ttrace(2) Note: These requests are not supported on PA-RISC versions of HP-UX. TT_PROC_GET_IBPT_REGS, 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 .
PAGE 9
ttrace(2) ttrace(2) TT_LWP_GET_STATE 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, 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 .
PAGE 10
ttrace(2) ttrace(2) __r4-__r7 R/W R/W __ret0-__ret3 __r8-__r11 R/W R/W __sp __r12 R/W R/W __tp __r13 R/W R/W __r14-__r31 R/W Reads as 0 See TT_LWP_RDRSEBS TT_LWP_WRRSEBS __r32-__r127 A tA and __f2-__f5 R/W R/W __f6-__f15 R/W Read as 0.0 __f16-__f31 R/W R/W __f32-__f127 R/W Read as 0.0 Writes may return [EINVAL] if the Hi FP registers were not live when the target thread stopped. __pr R/W R/W Writes to p6-p15 in a syscall context may be ignored.
PAGE 11
ttrace(2) ttrace(2) __ar32 R/W Reads as 0 __ar_unat __ar36 R/W R/W __ar_fpsr __ar40 R/W R/W __ar_pfs __ar64 R/W R __ar_lc __ar65 R/W R/W __ar_ec __ar66 R/W R/W __reason R R 0 == syscall context, non-zero == interruption context __ip R/W R/W Low-order 2-bits indicate slot number. __cfm R/W R/W Current Frame Marker corresponding to __ip __ed R/W Reads as 0 May not be set if not previously set.
PAGE 12
ttrace(2) ttrace(2) process specified by pid . The lwpid argument must be 0 (zero). The addr argument points to an array of up to TT_VEC_MAX tt_vec_ts, in the calling process’s address space. Each contains a request to be performed and the corresponding arguments.
PAGE 13
ttrace(2) ttrace(2) TT_VEC_LWP_RUREGS This request performs a series of TT_LWP_RUREGS requests on a single thread within the target process in a single call. The lwpid argument must specify a valid thread within the target process. The addr argument points to a location in the calling process’s address space containing an array of up to TT_VEC_MAX tt_reg_vecs, each containing the arguments for the request(s) to be performed.
PAGE 14
ttrace(2) ttrace(2) Events 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 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.
PAGE 15
ttrace(2) ttrace(2) ttstate_t structure. The path may subsequently be obtained using the TT_PROC_GET_PATHNAME request. TTEVT_SYSCALL_RETURN 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 return value and its error return in the ttstate_t structure.
PAGE 16
ttrace(2) [EACCES] [EACCES] ttrace(2) The pid argument to the TT_PROC_ATTACH or TT_PROC_ATTACH_NOSTOP is the pid of the invoker. The process identified by the pid argument to TT_PROC_ATTACH or TT_PROC_ATTACH_NOSTOP is exiting. [EACCES] The process is already being traced. [EAGAIN] Unable to attach to a process. This error can only be encountered when attaching to a process in the middle of an exec() syscall.
PAGE 17
ttrace(2) ttrace(2) [EPROTO] The debugger is attempting to modify wide registers after having modified narrow registers. [EPROTO] The debugger is attempting to first modify the text of a process in the middle of a vfork. Text modification is allowed during vfork as long as it was first modified before the vfork. [ESRCH] pid and/or lwpid identify a process or a thread to be traced that does not exist or has not executed a ttrace() with the TT_PROC_SETTRC request.
PAGE 18
ttrace(2) ttrace(2) return p; } (void) sprintf(buf, "EVENT_%#x", ev); return buf; } static void errexit(const char *p) { (void) fprintf(stderr, "%s: %s\n", p, strerror(errno)); if (ppid) { (void) kill(ppid, SIGINT); } exit (1); } static void dottrace(ttreq_t req, pid_t pid, lwpid_t lwpid, uint64_t addr2) { int rval; char *p; static _exp_t tab[] = { TT_PROC_SETTRC, TT_PROC_ATTACH, TT_PROC_ATTACH_NOSTOP, TT_PROC_DETACH, TT_PROC_CONTINUE, TT_PROC_SET_EVENT_MASK, TT_PROC_GET_FIRST_LWP_STATE, TT_PROC_GET_NEXT_
PAGE 19
ttrace(2) ttrace(2) SYS_wait, SYS_waitpid, SYS_waitid, SYS_time, SYS_brk, SYS_sigsuspend, SYS_sigprocmask, SYS_sigtimedwait, -1, "wait", "waitpid", "waitid", "time", "brk", "sigsuspend", "sigprocmask", "sigtimedwait", NULL, }; if (stp->tts_scno == SYS_siginhibit || stp->tts_scno == SYS_sigenable) { return; } if (evt == TTEVT_NONE) { evt = TTEVT_SYSCALL; } p = gen_name(tab, stp->tts_scno); if (p == NULL) { char buf[32]; (void) sprintf(buf, "syscall_%#x", stp->tts_scno); p = buf; } (void) printf("%s", p);
PAGE 20
ttrace(2) ttrace(2) stp->tts_u.tts_exit.tts_exitcode); break; case TTEVT_SIGNAL: (void) printf("%s %d\n", ev_name(stp->tts_event), stp->tts_u.tts_signal.tts_signo); break; default: (void) printf("%s\n", ev_name(stp->tts_event)); } } main(int argc, char **argv) { ttevent_t ev; ttstate_t st; pid_t pid; int pfd1[2]; int pfd2[2]; char c; --argc, ++argv; pid = atoi(*argv); ev.tte_events = TTEVT_SYSCALL|TTEVT_EXEC|TTEVT_EXIT; ev.
PAGE 21
ttrace(2) ttrace(2) (void) close(pfd1[1]); (void) close(pfd2[0]); (void) close(pfd2[1]); (void) execvp(*argv, argv); ppid = 0; errexit("exec"); } if (read(pfd2[0], (void *) &c, sizeof c) != sizeof c) { errexit("read"); } dottrace(TT_PROC_SET_EVENT_MASK, pid, 0, (uint64_t) &ev, sizeof ev, 0); /* tell the child to exec */ if (write(pfd1[1], (void *) &c, sizeof c) != sizeof c) { errexit("write"); } (void) close(pfd1[0]); (void) close(pfd1[1]); (void) close(pfd2[0]); (void) close(pfd2[1]); } dottrace(TT_PROC_
PAGE 22
(Notes) A (Notes) tA 22 Hewlett-Packard Company −1− HP-UX 11i Version 3: September 2010