LIBUNWI...OREDUMP(3libunwind) Programming Library LIBUNWI...OREDUMP(3libunwind) 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 mo- ment 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 argu- ment 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_acces- sors, but doing so would prevent static initialization. Also, when using _UCD_accessors, all the callback routines will be linked into the applica- tion, 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_de- stroy() 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 li- brary. -lunwind-coredump -lunwind-generic Linker-switches to add when building a program that uses the func- tions defined by this library. SEE ALSO libunwind(3libunwind) Programming Library 29 August 2023 LIBUNWI...OREDUMP(3libunwind)
NAME | SYNOPSIS | DESCRIPTION | THREAD SAFETY | RETURN VALUE | FILES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=libunwind-coredump&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>