mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2025-02-16 18:21:41 +01:00
(Logical change 1.44)
This commit is contained in:
mostang.com!davidm
parent
3886794230
commit
64f2bf7735
2 changed files with 312 additions and 0 deletions
|
|
@ -0,0 +1,193 @@
|
|||
'\" t
|
||||
.\" Manual page created with latex2man on Mon Jan 27 23:19:42 PST 2003
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
.de Vb
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.TH "LIBUNWIND\-PTRACE" "3" "27 January 2003" "Programming Library " "Programming Library "
|
||||
.SH NAME
|
||||
|
||||
libunwind\-ptrace \-\- ptrace() support in libunwind
|
||||
.PP
|
||||
.SH SYNOPSIS
|
||||
|
||||
.PP
|
||||
#include <libunwind.h>
|
||||
.br
|
||||
.PP
|
||||
unw_accessors_t
|
||||
_UPT_accessors;
|
||||
.br
|
||||
.PP
|
||||
void *_UPT_create(pid_t);
|
||||
.br
|
||||
void
|
||||
_UPT_destroy(void *);
|
||||
.br
|
||||
.PP
|
||||
int
|
||||
_UPT_find_proc_info(unw_addr_space_t,
|
||||
unw_word_t,
|
||||
unw_proc_info_t *,
|
||||
int,
|
||||
void *);
|
||||
.br
|
||||
void
|
||||
_UPT_put_unwind_info(unw_addr_space_t,
|
||||
unw_proc_info_t *,
|
||||
void *);
|
||||
.br
|
||||
int
|
||||
_UPT_get_dyn_info_list_addr(unw_addr_space_t,
|
||||
unw_word_t *,
|
||||
void *);
|
||||
.br
|
||||
int
|
||||
_UPT_access_mem(unw_addr_space_t,
|
||||
unw_word_t,
|
||||
unw_word_t *,
|
||||
int,
|
||||
void *);
|
||||
.br
|
||||
int
|
||||
_UPT_access_reg(unw_addr_space_t,
|
||||
unw_regnum_t,
|
||||
unw_word_t *,
|
||||
int,
|
||||
void *);
|
||||
.br
|
||||
int
|
||||
_UPT_access_fpreg(unw_addr_space_t,
|
||||
unw_regnum_t,
|
||||
unw_fpreg_t *,
|
||||
int,
|
||||
void *);
|
||||
.br
|
||||
.PP
|
||||
.SH DESCRIPTION
|
||||
|
||||
.PP
|
||||
The ptrace(2)
|
||||
system\-call makes it possible for a process to
|
||||
gain access to the machine\-state and virtual memory of \fIanother\fP
|
||||
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\&''\&.
|
||||
.PP
|
||||
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,
|
||||
\fIall\fP
|
||||
the callback routines will be linked into the application, even if
|
||||
they are never actually called.
|
||||
.PP
|
||||
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().
|
||||
.PP
|
||||
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.
|
||||
.PP
|
||||
.SH AVAILABILITY
|
||||
|
||||
.PP
|
||||
Since ptrace(2)
|
||||
works within a single machine only, the
|
||||
_UPT\-facility
|
||||
by definition is not available in
|
||||
libunwind\-versions
|
||||
configured for cross\-unwinding.
|
||||
.PP
|
||||
.SH THREAD SAFETY
|
||||
|
||||
.PP
|
||||
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.
|
||||
.PP
|
||||
.SH RETURN VALUE
|
||||
|
||||
.PP
|
||||
_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.
|
||||
.PP
|
||||
.SH SEE ALSO
|
||||
|
||||
.PP
|
||||
execve(2),
|
||||
libunwind(3),
|
||||
ptrace(2)
|
||||
.PP
|
||||
.SH AUTHOR
|
||||
|
||||
.PP
|
||||
David Mosberger\-Tang
|
||||
.br
|
||||
Hewlett\-Packard Labs
|
||||
.br
|
||||
Palo\-Alto, CA 94304
|
||||
.br
|
||||
Email: \fBdavidm@hpl.hp.com\fP
|
||||
.br
|
||||
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
|
|
@ -0,0 +1,119 @@
|
|||
\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~*});\\
|
||||
|
||||
\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}().
|
||||
|
||||
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}
|
||||
Loading…
Add table
Reference in a new issue