m2-internship/libunwind-eh_elf
1
0
Fork 0
mirror of https://github.com/tobast/libunwind-eh_elf.git synced 2025-02-18 11:01:41 +01:00
Code Issues Releases Activity

Fix some typos.

Browse source 
(Logical change 1.139)
This commit is contained in:
mostang.com!davidm 2003-12-10 07:14:38 +00:00
parent e70096e64b
commit 4ea1dd7fe5
1 changed files with 36 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
doc/libunwind.tex
View file

@ -82,23 +82,23 @@ some sort of error has occurred.
While it is not possible to directly move the unwind cursor in the While it is not possible to directly move the unwind cursor in the
``down'' direction (towards newer stack frames), this effect can be ``down'' direction (towards newer stack frames), this effect can be
achieved by making copyies of an unwind cursor. For example, a achieved by making copies of an unwind cursor. For example, a program
program that sometimes has to move ``down'' by one stack frame could that sometimes has to move ``down'' by one stack frame could maintain
maintain two cursor variables: ``\Var{curr}'' and ``\Var{prev}''. The two cursor variables: ``\Var{curr}'' and ``\Var{prev}''. The former
former would be used as the current cursor and \Var{prev} would be would be used as the current cursor and \Var{prev} would be maintained
maintained as the ``previous frame'' cursor by copying the contents of as the ``previous frame'' cursor by copying the contents of \Var{curr}
\Var{curr} to \Var{prev} right before calling \Func{unw\_step}(). to \Var{prev} right before calling \Func{unw\_step}(). With this
With this approach, the program could move one step ``down'' simply by approach, the program could move one step ``down'' simply by copying
copying back \Var{prev} to \Var{curr} whenever that is necessary. In back \Var{prev} to \Var{curr} whenever that is necessary. In the most
the mosts extreme case, a program could maintain a separate cursor for extreme case, a program could maintain a separate cursor for each call
each call frame and that way it could move up and down the call frame frame and that way it could move up and down the callframe-chain at
chain at will. will.
Given an unwind cursor, it is possible to read and write the CPU Given an unwind cursor, it is possible to read and write the CPU
registers that were preserved for the current stack frame identified registers that were preserved for the current stack frame (as
by the cursor. \Prog{Libunwind} provides several routines for this identified by the cursor). \Prog{Libunwind} provides several routines
purpose: \Func{unw\_get\_reg}() reads an integer (general) register, for this purpose: \Func{unw\_get\_reg}() reads an integer (general)
\Func{unw\_get\_fpreg}() reads a floating-point register, register, \Func{unw\_get\_fpreg}() reads a floating-point register,
\Func{unw\_set\_reg}() writes an integer register, and \Func{unw\_set\_reg}() writes an integer register, and
\Func{unw\_set\_fpreg}() writes a floating-point register. Note that, \Func{unw\_set\_fpreg}() writes a floating-point register. Note that,
by definition, only the \emph{preserved} machine state can be accessed by definition, only the \emph{preserved} machine state can be accessed
@ -131,16 +131,19 @@ special implementation can be selected which may run much faster than
the generic implementation which supports both kinds of unwinding. To the generic implementation which supports both kinds of unwinding. To
select this optimized version, simply define the macro select this optimized version, simply define the macro
\Const{UNW\_LOCAL\_ONLY} before including the headerfile \Const{UNW\_LOCAL\_ONLY} before including the headerfile
\File{$<$libunwind.h$>$}. If is perfectly OK for a single program to \File{$<$libunwind.h$>$}. It is perfectly OK for a single program to
employ both local-only and generic unwinding. That is, whether or not employ both local-only and generic unwinding. That is, whether or not
\Const{UNW\_LOCAL\_ONLY} is defined is a choice that each source-file \Const{UNW\_LOCAL\_ONLY} is defined is a choice that each source-file
(compilation-unit) can make on its own. Independent of the setting(s) (compilation-unit) can make on its own. Independent of the setting(s)
of \Const{UNW\_LOCAL\_ONLY}, you'll always link the same library into of \Const{UNW\_LOCAL\_ONLY}, you'll always link the same library into
the program (normally \Opt{-l}\File{unwind}). the program (normally \Opt{-l}\File{unwind}). Furthermore, the
portion of \Prog{libunwind} that manages unwind-info for dynamically
generated code is not affected by the setting of
\Const{UNW\_LOCAL\_ONLY}.
If we put all of the above together, here is how we could use If we put all of the above together, here is how we could use
\Prog{libunwind} write function \Func{show\_backtrace}() which prints \Prog{libunwind} to write a function ``\Func{show\_backtrace}()''
a classic stack trace: which prints a classic stack trace:
\begin{verbatim} \begin{verbatim}
#define UNW_LOCAL_ONLY #define UNW_LOCAL_ONLY
@ -155,7 +158,7 @@ void show_backtrace (void) {
while (unw_step(&cursor) > 0) { while (unw_step(&cursor) > 0) {
unw_get_reg(&cursor, UNW_REG_IP, &ip); unw_get_reg(&cursor, UNW_REG_IP, &ip);
unw_get_reg(&cursor, UNW_REG_SP, &sp); unw_get_reg(&cursor, UNW_REG_SP, &sp);
printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp); printf ("ip = %%lx, sp = %%lx\n", (long) ip, (long) sp);
} }
} }
\end{verbatim} \end{verbatim}
@ -171,7 +174,7 @@ used by debuggers and instruction-set simulators, for example.
Before you can unwind a remote process, you need to create a new Before you can unwind a remote process, you need to create a new
address-space object for that process. This is achieved with the address-space object for that process. This is achieved with the
\Func{unw\_create\_addr\_space} routine. The routine takes two \Func{unw\_create\_addr\_space}() routine. The routine takes two
arguments: a pointer to a set of \emph{accessor} routines and an arguments: a pointer to a set of \emph{accessor} routines and an
integer that specifies the byte-order of the target process. The integer that specifies the byte-order of the target process. The
accessor routines provide \Func{libunwind} with the means to accessor routines provide \Func{libunwind} with the means to
@ -184,13 +187,13 @@ to \Func{unw\_init\_remote}(). This routine is very similar to
\Func{unw\_init\_local}(), except that it takes an address-space \Func{unw\_init\_local}(), except that it takes an address-space
object and an opaque pointer as arguments. The routine uses these object and an opaque pointer as arguments. The routine uses these
arguments to fetch the initial machine state. \Prog{Libunwind} never arguments to fetch the initial machine state. \Prog{Libunwind} never
uses the opaque pointer on its own, but instead justs passes it on to uses the opaque pointer on its own, but instead just passes it on to
the accessor (callback) routines. Typically, this pointer is used to the accessor (callback) routines. Typically, this pointer is used to
select, e.g., the thread within a process that is to be unwound. select, e.g., the thread within a process that is to be unwound.
Once a cursor has been initialized with \Func{unw\_init\_remote}(), Once a cursor has been initialized with \Func{unw\_init\_remote}(),
unwinding works exactly like in the local case. That is, you can use unwinding works exactly like in the local case. That is, you can use
\Func{unw\_step} to move ``up'' in the call-chain, read and write \Func{unw\_step}() to move ``up'' in the call-chain, read and write
registers, or resume execution at a particular stack frame by calling registers, or resume execution at a particular stack frame by calling
\Func{unw\_resume}. \Func{unw\_resume}.
@ -209,7 +212,7 @@ call it \emph{native} unwinding. If they differ, we call it
\emph{cross-platform} unwinding. \emph{cross-platform} unwinding.
The principle behind supporting native, cross-platform, and The principle behind supporting native, cross-platform, and
multi-platform unwinding are very simple: for native unwinding, a multi-platform unwinding is very simple: for native unwinding, a
program includes \File{$<$libunwind.h$>$} and uses the linker switch program includes \File{$<$libunwind.h$>$} and uses the linker switch
\Opt{-l}\File{unwind}. For cross-platform unwinding, a program \Opt{-l}\File{unwind}. For cross-platform unwinding, a program
includes \File{$<$libunwind-}\Var{PLAT}\File{.h$>$} and uses the linker includes \File{$<$libunwind-}\Var{PLAT}\File{.h$>$} and uses the linker
@ -251,7 +254,7 @@ signal-safe). For remote-unwinding, \emph{none} of the
\section{Unwinding Through Dynamically Generated Code} \section{Unwinding Through Dynamically Generated Code}
\Func{Libunwind} provides the routines \Func{\_U\_dyn\_register}() and \Func{Libunwind} provides the routines \Func{\_U\_dyn\_register}() and
\Func{\_U\_dyn\_cancel} to register/cancel the information required to \Func{\_U\_dyn\_cancel}() to register/cancel the information required to
unwind through code that has been generated at runtime (e.g., by a unwind through code that has been generated at runtime (e.g., by a
just-in-time (JIT) compiler). It is important to register the just-in-time (JIT) compiler). It is important to register the
information for \emph{all} dynamically generated code because information for \emph{all} dynamically generated code because
@ -266,6 +269,9 @@ data-structure encapsulating the dynamic unwind info has been designed
to facilitate sharing, such that similar procedures can share much of to facilitate sharing, such that similar procedures can share much of
the underlying information. the underlying information.
For more information on the \Prog{libunwind} support for dynamically
generated code, see \SeeAlso{libunwind-dynamic(3)}.
\section{Caching of Unwind Info} \section{Caching of Unwind Info}
@ -296,7 +302,7 @@ local unwinding only.
\item[\File{libunwind.h}] Headerfile to include for native (same \item[\File{libunwind.h}] Headerfile to include for native (same
platform) unwinding. platform) unwinding.
\item[\File{libunwind-}\Var{PLAT}\File{.h}] Headerfile to include when \item[\File{libunwind-}\Var{PLAT}\File{.h}] Headerfile to include when
unwind target runs on platform \Var{PLAT}. For example, to unwind the unwind target runs on platform \Var{PLAT}. For example, to unwind
an IA-64 program, the header file \File{libunwind-ia64.h} should be an IA-64 program, the header file \File{libunwind-ia64.h} should be
included. included.
\item[\Opt{-l}\File{unwind}] Linker-switch to add when building a \item[\Opt{-l}\File{unwind}] Linker-switch to add when building a
@ -311,6 +317,7 @@ local unwinding only.
\section{See Also} \section{See Also}
\SeeAlso{libunwind-dynamic(3)},
\SeeAlso{libunwind-ia64(3)}, \SeeAlso{libunwind-ia64(3)},
\SeeAlso{libunwind-ptrace(3)}, \SeeAlso{libunwind-ptrace(3)},
\SeeAlso{libunwind-setjmp(3)}, \SeeAlso{libunwind-setjmp(3)},
@ -332,7 +339,9 @@ local unwinding only.
\SeeAlso{unw\_set\_caching\_policy(3)}, \SeeAlso{unw\_set\_caching\_policy(3)},
\SeeAlso{unw\_set\_fpreg(3)}, \SeeAlso{unw\_set\_fpreg(3)},
\SeeAlso{unw\_set\_reg(3)}, \SeeAlso{unw\_set\_reg(3)},
\SeeAlso{unw\_step(3)} \SeeAlso{unw\_step(3)},
\SeeAlso{\_U\_dyn\_register(3)},
\SeeAlso{\_U\_dyn\_cancel(3)}
\section{Author} \section{Author}