From 24a0c1f26582a9563600a679928647d56d8b8148 Mon Sep 17 00:00:00 2001
From: Tommi Rantala <tt.rantala@gmail.com>
Date: Fri, 31 Aug 2012 13:39:38 +0300
Subject: [PATCH] Provide manual page for `unw_backtrace()'

---
 doc/Makefile.am       |  2 +
 doc/unw_backtrace.man | 86 +++++++++++++++++++++++++++++++++++++++++++
 doc/unw_backtrace.tex | 54 +++++++++++++++++++++++++++
 3 files changed, 142 insertions(+)
 create mode 100644 doc/unw_backtrace.man
 create mode 100644 doc/unw_backtrace.tex

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4730f9b7..25340667 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,7 @@
 # man pages that go into section 3:
 man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man	\
 	libunwind-ptrace.man libunwind-setjmp.man			\
+	unw_backtrace.man						\
 	unw_flush_cache.man						\
 	unw_get_accessors.man						\
 	unw_get_proc_info.man						\
@@ -26,6 +27,7 @@ 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			\
+	unw_backtrace.tex						\
 	unw_flush_cache.tex						\
 	unw_get_accessors.tex						\
 	unw_get_proc_info.tex						\
diff --git a/doc/unw_backtrace.man b/doc/unw_backtrace.man
new file mode 100644
index 00000000..5699bbfe
--- /dev/null
+++ b/doc/unw_backtrace.man
@@ -0,0 +1,86 @@
+'\" t
+.\" Manual page created with latex2man on Fri Aug 31 13:39:04 EEST 2012
+.\" NOTE: This file is generated, DO NOT EDIT.
+.de Vb
+.ft CW
+.nf
+..
+.de Ve
+.ft R
+
+.fi
+..
+.TH "UNW\\_BACKTRACE" "3" "31 August 2012" "Programming Library " "Programming Library "
+.SH NAME
+unw_backtrace
+\-\- return backtrace for the calling program 
+.PP
+.SH SYNOPSIS
+
+.PP
+#include <libunwind.h>
+.br
+.PP
+int
+unw_backtrace(void **buffer,
+int size);
+.br
+.PP
+#include <execinfo.h>
+.br
+.PP
+int
+backtrace(void **buffer,
+int size);
+.br
+.PP
+.SH DESCRIPTION
+
+.PP
+unw_backtrace()
+is a convenient routine for obtaining the backtrace for 
+the calling program. The routine fills up to size
+addresses in the array 
+pointed by buffer\&.
+The routine is only available for local unwinding. 
+.PP
+Note that many (but not all) systems provide practically identical function 
+called backtrace().
+The prototype for this function is usually obtained 
+by including the <execinfo.h>
+header file \-\- a prototype for 
+backtrace()
+is not provided by libunwind\&.
+libunwind
+weakly 
+aliases backtrace()
+to unw_backtrace(),
+so when a program 
+calling backtrace()
+is linked against libunwind,
+it may end up 
+calling unw_backtrace().
+.PP
+.SH RETURN VALUE
+
+.PP
+The routine returns the number of addresses stored in the array pointed by 
+buffer\&.
+The return value may be zero to indicate that no addresses were 
+stored. 
+.PP
+.SH SEE ALSO
+
+.PP
+libunwind(3),
+unw_step(3)
+.PP
+.SH AUTHOR
+
+.PP
+David Mosberger\-Tang
+.br
+Email: \fBdmosberger@gmail.com\fP
+.br
+WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
+.\" NOTE: This file is generated, DO NOT EDIT.
diff --git a/doc/unw_backtrace.tex b/doc/unw_backtrace.tex
new file mode 100644
index 00000000..c383eeb3
--- /dev/null
+++ b/doc/unw_backtrace.tex
@@ -0,0 +1,54 @@
+\documentclass{article}
+\usepackage[fancyhdr,pdf]{latex2man}
+
+\input{common.tex}
+
+\begin{document}
+
+\begin{Name}{3}{unw\_backtrace}{David Mosberger-Tang}{Programming Library}{unw\_backtrace}unw\_backtrace -- return backtrace for the calling program
+\end{Name}
+
+\section{Synopsis}
+
+\File{\#include $<$libunwind.h$>$}\\
+
+\Type{int} \Func{unw\_backtrace}(\Type{void~**}\Var{buffer}, \Type{int}~\Var{size});\\
+
+\File{\#include $<$execinfo.h$>$}\\
+
+\Type{int} \Func{backtrace}(\Type{void~**}\Var{buffer}, \Type{int}~\Var{size});\\
+
+\section{Description}
+
+\Func{unw\_backtrace}() is a convenient routine for obtaining the backtrace for
+the calling program. The routine fills up to \Var{size} addresses in the array
+pointed by \Var{buffer}. The routine is only available for local unwinding.
+
+Note that many (but not all) systems provide practically identical function
+called \Func{backtrace}(). The prototype for this function is usually obtained
+by including the \File{$<$execinfo.h$>$} header file -- a prototype for
+\Func{backtrace}() is not provided by \Prog{libunwind}. \Prog{libunwind} weakly
+aliases \Func{backtrace}() to \Func{unw\_backtrace}(), so when a program
+calling \Func{backtrace}() is linked against \Prog{libunwind}, it may end up
+calling \Func{unw\_backtrace}().
+
+\section{Return Value}
+
+The routine returns the number of addresses stored in the array pointed by
+\Var{buffer}. The return value may be zero to indicate that no addresses were
+stored.
+
+\section{See Also}
+
+\SeeAlso{libunwind(3)},
+\SeeAlso{unw\_step(3)}
+
+\section{Author}
+
+\noindent
+David Mosberger-Tang\\
+Email: \Email{dmosberger@gmail.com}\\
+WWW: \URL{http://www.nongnu.org/libunwind/}.
+\LatexManEnd
+
+\end{document}