Add manpage for libunwind-coredump

Closes #487

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						\

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 <libunwind\-coredump.h>
+.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.

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}