---
name: "libunwind-coredump"
section: "3"
platform: "linux"
package: "libunwind"
version: "1.8.3-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libunwind-coredump"
---

# libunwind-coredump(3)

## NAME

libunwind-coredump -- coredump() support in libunwind

## SYNOPSIS

\#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 \*);\

## 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.  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.

## THREAD SAFETY

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.

## RETURN VALUE

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

## FILES

- libunwind-coredump.h

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

- **-l**unwind-coredump **-l**unwind-generic

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

## SEE ALSO

libunwind(3libunwind)