NAME¶
libunwind-ptrace -- ptrace() support in libunwind
SYNOPSIS¶
#include <libunwind-ptrace.h>
unw_accessors_t _UPT_accessors;
void *_UPT_create(pid_t);
void _UPT_destroy(void *);
int _UPT_find_proc_info(unw_addr_space_t, unw_word_t, unw_proc_info_t *, int,
void *);
void _UPT_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
int _UPT_get_dyn_info_list_addr(unw_addr_space_t, unw_word_t *, void *);
int _UPT_access_mem(unw_addr_space_t, unw_word_t, unw_word_t *, int, void *);
int _UPT_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *, int, void *);
int _UPT_access_fpreg(unw_addr_space_t, unw_regnum_t, unw_fpreg_t *, int, void
*);
int _UPT_get_proc_name(unw_addr_space_t, unw_word_t, char *, size_t, unw_word_t
*, void *);
int _UPT_resume(unw_addr_space_t, unw_cursor_t *, void *);
DESCRIPTION¶
The
ptrace(2) 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
ptrace(2). While it's not very difficult to do so
directly, libunwind 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, which is stands for ``unwind-via-ptrace''.
An application that wants to use the _UPT-facility first needs to create a new
libunwind address-space that represents the target process. This is done by
calling unw_create_addr_space(). In many cases, the application will simply
want to pass the address of _UPT_accessors as the first argument to this
routine. Doing so will ensure that libunwind 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(), _UPT_put_unwind_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,
all 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, and then starting the target
program (via
execve(2)), or by directly attaching to an already running
process (via PTRACE_ATTACH). 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 unw_init_remote().
The _UPT_resume() 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 process,
_UPT_destroy() needs to be called, passing it the void-pointer that was
returned by the corresponding call to _UPT_create(). This ensures that all
memory and other resources are freed up.
AVAILABILITY¶
Since
ptrace(2) works within a single machine only, the _UPT-facility by
definition is not available in libunwind-versions configured for
cross-unwinding.
THREAD SAFETY¶
The _UPT-facility 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 a _UPT-info structure at any given time, this facility is
thread-safe.
RETURN VALUE¶
_UPT_create() 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.
FILES¶
- libunwind-ptrace.h
-
Headerfile to include when using the interface defined by this
library.
- -lunwind-ptrace -lunwind-generic
-
Linker-switches to add when building a program that uses the functions
defined by this library.
SEE ALSO¶
execve(2),
libunwind(3),
ptrace(2)
AUTHOR¶
David Mosberger-Tang
Email:
dmosberger@gmail.com
WWW:
http://www.nongnu.org/libunwind/.
