2003-01-28 08:32:15 +01:00
\documentclass { article}
\usepackage [fancyhdr,pdf] { latex2man}
\input { common.tex}
\begin { document}
2003-03-31 21:57:09 +02:00
\begin { Name} { 3} { libunwind-ptrace} { David Mosberger-Tang} { Programming Library} { ptrace() support in libunwind} libunwind-ptrace -- ptrace() support in libunwind
2003-01-28 08:32:15 +01:00
\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~*} );\\
2003-02-27 10:58:57 +01:00
\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~*} );\\
2003-03-06 07:14:36 +01:00
\noindent
\Type { int} \Func { \_ UPT\_ resume} (\Type { unw\_ addr\_ space\_ t} , \Type { unw\_ cursor\_ t~*} , \Type { void~*} );\\
2003-01-28 08:32:15 +01:00
\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} ().
2003-03-06 07:14:36 +01:00
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} .
2003-01-28 08:32:15 +01:00
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}
