2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
3 .\" NOTE: This file is generated, DO NOT EDIT.
13 .TH "LIBUNWIND\-PTRACE" "3" "16 August 2007" "Programming Library " "Programming Library "
16 \-\- ptrace() support in libunwind
21 #include <libunwind\-ptrace.h>
28 void *_UPT_create(pid_t);
35 _UPT_find_proc_info(unw_addr_space_t,
42 _UPT_put_unwind_info(unw_addr_space_t,
47 _UPT_get_dyn_info_list_addr(unw_addr_space_t,
52 _UPT_access_mem(unw_addr_space_t,
59 _UPT_access_reg(unw_addr_space_t,
66 _UPT_access_fpreg(unw_addr_space_t,
73 _UPT_get_proc_name(unw_addr_space_t,
81 _UPT_resume(unw_addr_space_t,
90 system\-call makes it possible for a process to
91 gain access to the machine\-state and virtual memory of \fIanother\fP
92 process. With the right set of call\-back routines, it is therefore
93 possible to hook up libunwind
94 to another process via
96 While it\&'s not very difficult to do so directly,
98 further facilitates this task by providing
99 ready\-to\-use callbacks for this purpose. The routines and variables
100 implementing this facility use a name\-prefix of _UPT,
102 stands for ``unwind\-via\-ptrace\&''\&.
104 An application that wants to use the _UPT\-facility
106 to create a new libunwind
107 address\-space that represents the
108 target process. This is done by calling
109 unw_create_addr_space().
110 In many cases, the application
111 will simply want to pass the address of _UPT_accessors
113 first argument to this routine. Doing so will ensure that
115 will be able to properly unwind the target process.
116 However, in special circumstances, an application may prefer to use
117 only portions of the _UPT\-facility.
119 individual callback routines (_UPT_find_proc_info(),
120 _UPT_put_unwind_info(),
121 etc.) are also available for direct
122 use. Of course, the addresses of these routines could also be picked
123 up from _UPT_accessors,
124 but doing so would prevent static
125 initialization. Also, when using _UPT_accessors,
127 the callback routines will be linked into the application, even if
128 they are never actually called.
130 Next, the application can turn on ptrace\-mode on the target process,
131 either by forking a new process, invoking PTRACE_TRACEME,
133 then starting the target program (via execve(2)),
135 directly attaching to an already running process (via
137 Either way, once the process\-ID (pid) of the
138 target process is known, a _UPT\-info\-structure
140 by calling _UPT_create(),
141 passing the pid of the target process
142 as the only argument. The returned void\-pointer then needs to be
143 passed as the ``argument\&'' pointer (third argument) to
147 routine can be used to resume execution of
148 the target process. It simply invokes ptrace(2)
150 value of PTRACE_CONT\&.
152 When the application is done using libunwind
154 process, _UPT_destroy()
155 needs to be called, passing it the
156 void\-pointer that was returned by the corresponding call to
158 This ensures that all memory and other
159 resources are freed up.
165 works within a single machine only, the
167 by definition is not available in
169 configured for cross\-unwinding.
175 assumes that a single _UPT\-info
176 structure is never shared between threads. Because of this, no
177 explicit locking is used. As long as only one thread uses
179 structure at any given time, this facility
188 to create the _UPT\-info\-structure
189 for any reason. For the
190 current implementation, the only reason this call may fail is when the
191 system is out of memory.
198 Headerfile to include when using the
199 interface defined by this library.
201 \fB\-l\fPunwind\-ptrace \fB\-l\fPunwind\-generic
202 Linker\-switches to add when building a program that uses the
203 functions defined by this library.
215 David Mosberger\-Tang
217 Email: \fBdmosberger@gmail.com\fP
219 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
220 .\" NOTE: This file is generated, DO NOT EDIT.