mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2024-11-16 13:18:12 +01:00
126 lines
5.3 KiB
TeX
126 lines
5.3 KiB
TeX
\documentclass{article}
|
|
\usepackage[fancyhdr,pdf]{latex2man}
|
|
|
|
\input{common.tex}
|
|
|
|
\begin{document}
|
|
|
|
\begin{Name}{3}{libunwind-ptrace}{David Mosberger-Tang}{Programming Library}{ptrace() support in libunwind}libunwind-ptrace -- ptrace() support in libunwind
|
|
\end{Name}
|
|
|
|
\section{Synopsis}
|
|
|
|
\File{\#include $<$libunwind.h$>$}\\
|
|
|
|
\noindent
|
|
\Type{unw\_accessors\_t} \Var{_UPT\_accessors};\\
|
|
|
|
\Type{void~*}\Func{\_UPT\_create}(\Type{pid\_t});\\
|
|
\noindent
|
|
\Type{void} \Func{\_UPT\_destroy}(\Type{void~*});\\
|
|
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_find\_proc\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_proc\_info\_t~*}, \Type{int}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{void} \Func{\_UPT\_put\_unwind\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_proc\_info\_t~*}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_access\_mem}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_access\_reg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_access\_fpreg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*}, \Type{int}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_get\_proc\_name}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{char~*}, \Type{size\_t}, \Type{unw_word_t~*}, \Type{void~*});\\
|
|
\noindent
|
|
\Type{int} \Func{\_UPT\_resume}(\Type{unw\_addr\_space\_t}, \Type{unw\_cursor\_t~*}, \Type{void~*});\\
|
|
|
|
\section{Description}
|
|
|
|
The \Func{ptrace}(2) system-call makes it possible for a process to
|
|
gain access to the machine-state and virtual memory of \emph{another}
|
|
process. With the right set of call-back routines, it is therefore
|
|
possible to hook up \Prog{libunwind} to another process via
|
|
\Func{ptrace}(2). While it's not very difficult to do so directly,
|
|
\Prog{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 \Func{\_UPT}, which is
|
|
stands for ``unwind-via-ptrace''.
|
|
|
|
An application that wants to use the \Func{\_UPT}-facility first needs
|
|
to create a new \Prog{libunwind} address-space that represents the
|
|
target process. This is done by calling
|
|
\Func{unw\_create\_addr\_space}(). In many cases, the application
|
|
will simply want to pass the address of \Var{\_UPT\_accessors} as the
|
|
first argument to this routine. Doing so will ensure that
|
|
\Prog{libunwind} will be able to properly unwind the target process.
|
|
However, in special circumstances, an application may prefer to use
|
|
only portions of the \Prog{\_UPT}-facility. For this reason, the
|
|
individual callback routines (\Func{\_UPT\_find\_proc\_info}(),
|
|
\Func{\_UPT\_put\_unwind\_info}(), etc.) are also available for direct
|
|
use. Of course, the addresses of these routines could also be picked
|
|
up from \Var{\_UPT\_accessors}, but doing so would prevent static
|
|
initialization. Also, when using \Var{\_UPT\_accessors}, \emph{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 \Const{PTRACE\_TRACEME}, and
|
|
then starting the target program (via \Func{execve}(2)), or by
|
|
directly attaching to an already running process (via
|
|
\Const{PTRACE\_ATTACH}). Either way, once the process-ID (pid) of the
|
|
target process is known, a \Prog{\_UPT}-info-structure can be created
|
|
by calling \Func{\_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
|
|
\Func{unw\_init\_remote}().
|
|
|
|
The \Func{\_UPT\_resume}() routine can be used to resume execution of
|
|
the target process. It simply invokes \Func{ptrace}(2) with a command
|
|
value of \Const{PTRACE\_CONT}.
|
|
|
|
When the application is done using \Prog{libunwind} on the target
|
|
process, \Func{\_UPT\_destroy}() needs to be called, passing it the
|
|
void-pointer that was returned by the corresponding call to
|
|
\Func{\_UPT\_create}(). This ensures that all memory and other
|
|
resources are freed up.
|
|
|
|
\section{Availability}
|
|
|
|
Since \Func{ptrace}(2) works within a single machine only, the
|
|
\Prog{\_UPT}-facility by definition is not available in
|
|
\Prog{libunwind}-versions configured for cross-unwinding.
|
|
|
|
\section{Thread Safety}
|
|
|
|
The \Prog{\_UPT}-facility assumes that a single \Prog{\_UPT}-info
|
|
structure is never shared between threads. Because of this, no
|
|
explicit locking is used. As long as only one thread uses
|
|
a \Prog{\_UPT}-info structure at any given time, this facility
|
|
is thread-safe.
|
|
|
|
\section{Return Value}
|
|
|
|
\Func{\_UPT\_create}() may return a \Const{NULL} pointer if it fails
|
|
to create the \Prog{\_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.
|
|
|
|
\section{See Also}
|
|
|
|
execve(2),
|
|
\SeeAlso{libunwind(3)},
|
|
ptrace(2)
|
|
|
|
\section{Author}
|
|
|
|
\noindent
|
|
David Mosberger-Tang\\
|
|
Hewlett-Packard Labs\\
|
|
Palo-Alto, CA 94304\\
|
|
Email: \Email{davidm@hpl.hp.com}\\
|
|
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
|
|
\LatexManEnd
|
|
|
|
\end{document}
|