libunwind/doc/libunwind-coredump.tex

\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}

\input{common.tex}

\begin{document}

\begin{Name}{3libunwind}{libunwind-coredump}{}{Programming Library}{coredump analysis support in libunwind}libunwind-coredump -- coredump() support in libunwind
\end{Name}

\section{Synopsis}

\File{\#include $<$libunwind-coredump.h$>$}\\

\noindent
\Type{unw\_accessors\_t} \Var{\_UCD\_accessors};\\

\Type{struct~UCD\_info~*}\Func{\_UCD\_create}(\Type{char const~*});\\
\noindent
\Type{void}~\Func{\_UCD\_destroy}(\Type{struct UCD\_info~*});\\

\noindent
\Type{int} \Func{\_UCD\_get\_num\_threads}(\Type{struct UCD\_info~*});\\
\noindent
\Type{void} \Func{\_UCD\_select\_thread}(\Type{struct UCD\_info~*}, \Type{int});\\
\noindent
\Type{void} \Func{\_UCD\_get\_pid}(\Type{struct UCD\_info~*});\\
\noindent
\Type{void} \Func{\_UCD\_get\_cursig}(\Type{struct UCD\_info~*});\\

\noindent
\Type{int} \Func{\_UCD\_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{\_UCD\_put\_unwind\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_proc\_info\_t~*}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UCD\_get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UCD\_access\_mem}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UCD\_access\_reg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UCD\_access\_fpreg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UCD\_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{\_UCD\_resume}(\Type{unw\_addr\_space\_t}, \Type{unw\_cursor\_t~*}, \Type{void~*});\\

\section{Description}

It is possible to generate a snapshot of a process state at a specific moment in
time and save it in a specially-formatted file called a coredump.
This often happens automatically when a process encounters an unrecoverable
error and the OS itself captures the state of the process when the error
occurred.
\Prog{libunwind} provides a library that can be used as part of a lightweight
tool to generate some useful information as to why the process abnormally
terminated (such as a stack trace of al threads of execution).
The routines and variables
implementing this facility use a prefix of \Func{\_UCD}, which
stands for ``unwind-via-coredump''.

An application that wants to use the coredump remote 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{\_UCD\_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{\_UCD}-facility.  For this reason, the
individual callback routines (\Func{\_UCD\_find\_proc\_info}(),
\Func{\_UCD\_put\_unwind\_info}(), etc.)  are also available for direct
use.  Of course, the addresses of these routines could also be picked
up from \Var{\_UCD\_accessors}, but doing so would prevent static
initialization.  Also, when using \Var{\_UCD\_accessors}, \emph{all}
the callback routines will be linked into the application, even if
they are never actually called.

Next, the application needs to load the corefile for analysis and create an
(opaque) UCD\_info structure by calling \Func{\_UCD_create}(),
passing the name of the corefile.
The returned opaque 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 corefile,
\Func{\_UCD\_destroy}() needs to be called,
passing it the pointer that was returned by the corresponding call to
\Func{\_UCD\_create}().
This ensures that all memory and other resources are freed up.

\begin{description}[style=nextline]

    \item[\Func{\_UCD\_get\_num\_threads}()]
    Gets the number of threads in the corefile.

\item[\Func{\_UCD\_get\_pid}()]
    Gets the process ID of the process associated with the corefile.

\item[\Func{\_UCD\_get\_cursig}()]
    Gets the current signal begin received by the process associated with the
    corefile (if any).

\item[\Func{\_UCD\_select\_thread}()]
    Selects the current thread for unwinding.

\end{description}

\section{Thread Safety}

The coredump remote assumes that a single \Prog{\_UCD\_info}
structure is never shared between threads.
Because of this,
no explicit locking is used.
As long as only one thread uses a \Prog{\_UCD\_info} structure at any given time,
this facility is thread-safe.

\section{Return Value}

\Func{\_UCD\_create}() may return a null pointer if it fails
to create the \Prog{UCD\_info} for any reason.

\section{Files}

\begin{Description}
\item[\File{libunwind-coredump.h}] Header file to include when using the
  interface defined by this library.
\item[\Opt{-l}\File{unwind-coredump} \Opt{-l}\File{unwind-generic}]
    Linker-switches to add when building a program that uses the
    functions defined by this library.
\end{Description}

\section{See Also}

\SeeAlso{libunwind}(3libunwind)

\LatexManEnd
\end{document}