libunwind-coredump - Man Page

#include <libunwind-coredump.h>

unw_accessors_t _UCD_accessors;

struct UCD_info *_UCD_create(char const *);
void _UCD_destroy(struct UCD_info *);

int _UCD_get_num_threads(struct UCD_info *);
void _UCD_select_thread(struct UCD_info *, int);
void _UCD_get_pid(struct UCD_info *);
void _UCD_get_cursig(struct UCD_info *);

int _UCD_find_proc_info(unw_addr_space_t, unw_word_t, unw_proc_info_t *, int, void *);
void _UCD_put_unwind_info(unw_addr_space_t, unw_proc_info_t *, void *);
int _UCD_get_dyn_info_list_addr(unw_addr_space_t, unw_word_t *, void *);
int _UCD_access_mem(unw_addr_space_t, unw_word_t, unw_word_t *, int, void *);
int _UCD_access_reg(unw_addr_space_t, unw_regnum_t, unw_word_t *, int, void *);
int _UCD_access_fpreg(unw_addr_space_t, unw_regnum_t, unw_fpreg_t *, int, void *);
int _UCD_get_proc_name(unw_addr_space_t, unw_word_t, char *, size_t, unw_word_t *, void *);
int _UCD_resume(unw_addr_space_t, unw_cursor_t *, void *);

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.  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 _UCD, which  stands for “unwind-via-coredump”.

An application that wants to use the coredump remote 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 _UCD_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 _UCD-facility. For this reason, the  individual callback routines (_UCD_find_proc_info(), _UCD_put_unwind_info(), etc.) are also available for direct  use. Of course, the addresses of these routines could also be picked  up from _UCD_accessors, but doing so would prevent static  initialization. Also, when using _UCD_accessors, 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 _UCD_create(), passing the name of the corefile.  The returned opaque pointer then needs to be  passed as the “argument” pointer (third argument) to  unw_init_remote().

When the application is done using libunwind on the corefile,  _UCD_destroy() needs to be called,  passing it the pointer that was returned by the corresponding call to  _UCD_create(). This ensures that all memory and other resources are freed up.

_UCD_get_num_threads()

Gets the number of threads in the corefile.

_UCD_get_pid()

Gets the process ID of the process associated with the corefile.

_UCD_get_cursig()

Gets the current signal begin received by the process associated with the  corefile (if any).

_UCD_select_thread()

Selects the current thread for unwinding.

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

_UCD_create() may return a null pointer if it fails  to create the UCD_info for any reason.

libunwind-coredump.h

Header file to include when using the  interface defined by this library.

-lunwind-coredump -lunwind-generic

Linker-switches to add when building a program that uses the  functions defined by this library.

libunwind(3libunwind)