1LIBUNWIND-PTRACE(3) Programming Library LIBUNWIND-PTRACE(3)
2
6 libunwind-ptrace -- ptrace() support in libunwind
7
9 #include <libunwind-ptrace.h>
10 unw_accessors_t _UPT_accessors;
12 void *_UPT_create(pid_t);
14 void _UPT_destroy(void *);
15 int _UPT_find_proc_info(unw_addr_space_t, unw_word_t, unw_proc_info_t
17 *, int, void *);
18 void _UPT_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
19 int _UPT_get_dyn_info_list_addr(unw_addr_space_t, unw_word_t *, void
20 *);
21 int _UPT_access_mem(unw_addr_space_t, unw_word_t, unw_word_t *, int,
22 void *);
23 int _UPT_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *, int,
24 void *);
25 int _UPT_access_fpreg(unw_addr_space_t, unw_regnum_t, unw_fpreg_t *,
26 int, void *);
27 int _UPT_get_proc_name(unw_addr_space_t, unw_word_t, char *, size_t,
28 unw_word_t *, void *);
29 int _UPT_resume(unw_addr_space_t, unw_cursor_t *, void *);
30
32 The ptrace(2) system-call makes it possible for a process to gain
33 access to the machine-state and virtual memory of another process. With
34 the right set of call-back routines, it is therefore possible to hook
35 up libunwind to another process via ptrace(2). While it's not very
36 difficult to do so directly, libunwind further facilitates this task by
37 providing ready-to-use callbacks for this purpose. The routines and
38 variables implementing this facility use a name-prefix of _UPT, which
39 is stands for ``unwind-via-ptrace''.
40 An application that wants to use the _UPT-facility first needs to cre‐
42 ate a new libunwind address-space that represents the target process.
43 This is done by calling unw_create_addr_space(). In many cases, the
44 application will simply want to pass the address of _UPT_accessors as
45 the first argument to this routine. Doing so will ensure that libunwind
46 will be able to properly unwind the target process. However, in spe‐
47 cial circumstances, an application may prefer to use only portions of
48 the _UPT-facility. For this reason, the individual callback routines
49 (_UPT_find_proc_info(), _UPT_put_unwind_info(), etc.) are also avail‐
50 able for direct use. Of course, the addresses of these routines could
51 also be picked up from _UPT_accessors, but doing so would prevent
52 static initialization. Also, when using _UPT_accessors, all the call‐
53 back routines will be linked into the application, even if they are
54 never actually called.
55 Next, the application can turn on ptrace-mode on the target process,
57 either by forking a new process, invoking PTRACE_TRACEME, and then
58 starting the target program (via execve(2)), or by directly attaching
59 to an already running process (via PTRACE_ATTACH). Either way, once
60 the process-ID (pid) of the target process is known, a _UPT-info-struc‐
61 ture can be created by calling _UPT_create(), passing the pid of the
62 target process as the only argument. The returned void-pointer then
63 needs to be passed as the ``argument'' pointer (third argument) to
64 unw_init_remote().
65 The _UPT_resume() routine can be used to resume execution of the target
67 process. It simply invokes ptrace(2) with a command value of
68 PTRACE_CONT.
69 When the application is done using libunwind on the target process,
71 _UPT_destroy() needs to be called, passing it the void-pointer that was
72 returned by the corresponding call to _UPT_create(). This ensures that
73 all memory and other resources are freed up.
74
76 Since ptrace(2) works within a single machine only, the _UPT-facility
77 by definition is not available in libunwind-versions configured for
78 cross-unwinding.
79
81 The _UPT-facility assumes that a single _UPT-info structure is never
82 shared between threads. Because of this, no explicit locking is used.
83 As long as only one thread uses a _UPT-info structure at any given
84 time, this facility is thread-safe.
85
87 _UPT_create() may return a NULL pointer if it fails to create the
88 _UPT-info-structure for any reason. For the current implementation, the
89 only reason this call may fail is when the system is out of memory.
90
92 libunwind-ptrace.h
93 Headerfile to include when using the interface defined by this
94 library.
95 -lunwind-ptrace -lunwind-generic
97 Linker-switches to add when building a program that uses the
98 functions defined by this library.
99
101 execve(2), libunwind(3), ptrace(2)
102
104 David Mosberger-Tang
105 Email: dmosberger@gmail.com
106 WWW: http://www.nongnu.org/libunwind/.
107Programming Library 16 August 2007 LIBUNWIND-PTRACE(3)