Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIBUNW...REDUMP(3libunwind)  Programming Library   LIBUNW...REDUMP(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
       moment in time and save it in a specially-formatted file	called a core-
       dump.  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-core-
       dump''.

       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_ac-
       cessors	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 cre-
       ate 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_re-
       mote().

       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	 core-
	      file.

       _UCD_get_cursig()
	       Gets  the  current signal begin received	by the process associ-
	      ated 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.

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

SEE ALSO
       libunwind(3libunwind)

Programming Library		29 August 2023	   LIBUNW...REDUMP(3libunwind)

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+14.3.quarterly>

home | help