From 089038df6bb46fd56825fc58c860f2c3b0e3aed7 Mon Sep 17 00:00:00 2001 From: Stephen Webb Date: Thu, 18 May 2023 11:06:12 -0400 Subject: [PATCH] Add manpage for libunwind-coredump Closes #487 --- doc/Makefile.am | 8 +- doc/libunwind-coredump.man | 224 +++++++++++++++++++++++++++++++++++++ doc/libunwind-coredump.tex | 149 ++++++++++++++++++++++++ 3 files changed, 379 insertions(+), 2 deletions(-) create mode 100644 doc/libunwind-coredump.man create mode 100644 doc/libunwind-coredump.tex diff --git a/doc/Makefile.am b/doc/Makefile.am index 2252978dc..476e939ee 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,8 @@ # man pages that go into section 3: man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man \ - libunwind-ptrace.man libunwind-setjmp.man \ + libunwind-coredump.man \ + libunwind-ptrace.man \ + libunwind-setjmp.man \ unw_apply_reg_state.man \ unw_backtrace.man \ unw_flush_cache.man \ @@ -32,7 +34,9 @@ man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man \ EXTRA_DIST = NOTES libunwind.trans \ libunwind.tex libunwind-dynamic.tex libunwind-ia64.tex \ - libunwind-ptrace.tex libunwind-setjmp.tex \ + libunwind-coredump.tex \ + libunwind-ptrace.tex \ + libunwind-setjmp.tex \ unw_apply_reg_state.tex \ unw_backtrace.tex \ unw_flush_cache.tex \ diff --git a/doc/libunwind-coredump.man b/doc/libunwind-coredump.man new file mode 100644 index 000000000..b6a3e6ca5 --- /dev/null +++ b/doc/libunwind-coredump.man @@ -0,0 +1,224 @@ +.\" *********************************** start of \input{common.tex} +.\" *********************************** end of \input{common.tex} +'\" t +.\" Manual page created with latex2man on Thu May 18 11:05:16 2023 +.\" NOTE: This file is generated, DO NOT EDIT. +.de Vb +.ft CW +.nf +.. +.de Ve +.ft R + +.fi +.. +.TH "LIBUNWIND\-COREDUMP" "3" "18 May 2023" "Programming Library " "Programming Library " +.SH NAME +libunwind\-coredump +\-\- coredump() support in libunwind +.PP +.SH SYNOPSIS + +.PP +#include +.br +.PP +unw_accessors_t +_UCD_accessors; +.br +.PP +void *_UCD_create(char const *); +.br +.PP +void +_UCD_destroy(struct UCD_info *); +.br +.PP +int +_UCD_get_num_threads(struct UCD_info *); +.br +.PP +void +_UCD_select_thread(struct UCD_info *, +int); +.br +.PP +void +_UCD_get_pid(struct UCD_info *); +.br +.PP +void +_UCD_get_cursig(struct UCD_info *); +.br +.PP +int +_UCD_find_proc_info(unw_addr_space_t, +unw_word_t, +unw_proc_info_t *, +int, +void *); +.br +.PP +void +_UCD_put_unwind_info(unw_addr_space_t, +unw_proc_info_t *, +void *); +.br +.PP +int +_UCD_get_dyn_info_list_addr(unw_addr_space_t, +unw_word_t *, +void *); +.br +.PP +int +_UCD_access_mem(unw_addr_space_t, +unw_word_t, +unw_word_t *, +int, +void *); +.br +.PP +int +_UCD_access_reg(unw_addr_space_t, +unw_regnum_t, +unw_word_t *, +int, +void *); +.br +.PP +int +_UCD_access_fpreg(unw_addr_space_t, +unw_regnum_t, +unw_fpreg_t *, +int, +void *); +.br +.PP +int +_UCD_get_proc_name(unw_addr_space_t, +unw_word_t, +char *, +size_t, +unw_word_t *, +void *); +.br +.PP +int +_UCD_resume(unw_addr_space_t, +unw_cursor_t *, +void *); +.br +.PP +.SH DESCRIPTION + +.PP +It is possible to generate a snapshot of a process state at a specific moment in +time and save it in a spcially\-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 name\-prefix of _UCD, +which is +stands for ``unwind\-via\-coredump\&''\&. +.PP +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, +\fIall\fP +the callback routines will be linked into the application, even if +they are never actually called. +.PP +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 void\-pointer then needs to be +passed as the ``argument\&'' pointer (third argument) to +unw_init_remote(). +.PP +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. +.PP +.TP +_UCD_get_num_threads() +Gets the number of threads in the corefile. +.PP +.TP +_UCD_get_pid() +Gets the process ID of the process associated with the corefile. +.PP +.TP +_UCD_get_cursig() +Gets the current signal begin received by the process associated with the +corefile (if any). +.PP +.TP +_UCD_select_thread() +Selects the current thread for unwinding. +.PP +.SH THREAD SAFETY + +.PP +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. +.PP +.SH RETURN VALUE + +.PP +_UCD_create() +may return a NULL +pointer if it fails +to create the UCD_info +for any reason. +.PP +.SH FILES + +.PP +.TP +libunwind\-coredump.h + Header file to include when using the +interface defined by this library. +.TP +\fB\-l\fPunwind\-coredump \fB\-l\fPunwind\-generic + Linker\-switches to add when building a program that uses the +functions defined by this library. +.PP +.SH SEE ALSO + +.PP +libunwind(3), +.PP +.\" NOTE: This file is generated, DO NOT EDIT. diff --git a/doc/libunwind-coredump.tex b/doc/libunwind-coredump.tex new file mode 100644 index 000000000..8893ca1a2 --- /dev/null +++ b/doc/libunwind-coredump.tex @@ -0,0 +1,149 @@ +\documentclass{article} +\usepackage[fancyhdr,pdf]{latex2man} + +\input{common.tex} + +\begin{document} + +\begin{Name}{3}{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{void~*}\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 spcially-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 name-prefix of \Func{\_UCD}, which is +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 void-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[\_UCD\_get\_num\_threads()] + Gets the number of threads in the corefile. + +\item[\_UCD\_get\_pid()] + Gets the process ID of the process associated with the corefile. + +\item[\_UCD\_get\_cursig()] + Gets the current signal begin received by the process associated with the + corefile (if any). + +\item[\_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 \Const{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(3)}, + +\LatexManEnd +\end{document}