Manual Reference Pages - LIBUNWIND-PTRACE (3)
-- ptrace() support in libunwind
system-call makes it possible for a process to
gain access to the machine-state and virtual memory of another
process. With the right set of call-back routines, it is therefore
possible to hook up libunwind
to another process via
While its not very difficult to do so directly,
further facilitates this task by providing
ready-to-use callbacks for this purpose. The routines and variables
implementing this facility use a name-prefix of _UPT,
stands for unwind-via-ptrace.
An application that wants to use the _UPT-facility
to create a new libunwind
address-space that represents the
target process. This is done by calling
In many cases, the application
will simply want to pass the address of _UPT_accessors
first argument to this routine. Doing so will ensure that
will be able to properly unwind the target process.
However, in special circumstances, an application may prefer to use
only portions of the _UPT-facility.
For this reason, the
individual callback routines (_UPT_find_proc_info(),
etc.) are also available for direct
use. Of course, the addresses of these routines could also be picked
up from _UPT_accessors,
but doing so would prevent static
initialization. Also, when using _UPT_accessors,
the callback routines will be linked into the application, even if
they are never actually called.
Next, the application can turn on ptrace-mode on the target process,
either by forking a new process, invoking PTRACE_TRACEME,
then starting the target program (via execve(2)),
directly attaching to an already running process (via
Either way, once the process-ID (pid) of the
target process is known, a _UPT-info-structure
can be created
by calling _UPT_create(),
passing the pid of the target process
as the only argument. The returned void-pointer then needs to be
passed as the argument pointer (third argument) to
routine can be used to resume execution of
the target process. It simply invokes ptrace(2)
with a command
value of PTRACE_CONT.
When the application is done using libunwind
on the target
needs to be called, passing it the
void-pointer that was returned by the corresponding call to
This ensures that all memory and other
resources are freed up.
works within a single machine only, the
by definition is not available in
configured for cross-unwinding.
assumes that a single _UPT-info
structure is never shared between threads. Because of this, no
explicit locking is used. As long as only one thread uses
structure at any given time, this facility
may return a NULL
pointer if it fails
to create the _UPT-info-structure
for any reason. For the
current implementation, the only reason this call may fail is when the
system is out of memory.
Headerfile to include when using the
interface defined by this library.
Linker-switches to add when building a program that uses the
functions defined by this library.
|Programming Library ||LIBUNWIND-PTRACE (3) ||16 August 2007 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.