/*	The backtrace SAM module provides a means for programs to generate
 *	backtraces, including symbolic information (function names etc).
 *
 *	It has been tested on Linux, using gcc and glibc, and works.  It should
 *	work on other UNIX-like systems with gcc and glibc, but has not been
 *	tested on such platforms.
 *
 *	Use of this SAM under Windows (or other systems without the HAS_EXECINFO
 *	flag defined at compile time) will not	fail, it will just produce a
 *	'backtrace' that contains a message stating	execinfo.h has not been
 *	included.
 *
 *	For further information regarding compiler flags and settings with this
 *	SAM, see the documentation below on make_backtrace(), as well as the
 *	online documentation for execinfo.h at:
 *
 *		http://www.gnu.org/manual/glibc-2.2.3/html_chapter/libc_33.html
 */

#ifndef DONE_BACKTRACE
#define DONE_BACKTRACE

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#ifdef HAS_EXECINFO
#include <execinfo.h>
#endif

#define BACKTRACE_BFSZ 1000		/* standard buffer size */
#undef  BACKTRACE_TESTING		/* define BACKTRACE_TESTING to include main() for testing */


/*	make_backtrace() produces a backtrace for the current thread, and puts it
 *	in the buffer 'backtrace_text', up to 'size' characters.
 *
 *	A sample backtrace, with symbolic information, is as follows:
 *
 *		./trace(make_backtrace+0x1d) [0x804874d]
 *		./trace(main+0x1d) [0x8048841]
 *		/lib/i686/libc.so.6(__libc_start_main+0x93) [0x4004d507]
 *		./trace(backtrace_symbols+0x35) [0x8048651]
 *
 *	make_backtrace() returns 1 if a backtrace is produced, or 0 otherwise.
 *
 *	NOTES:	-	make_backtrace() depends upon the execinfo.h header.  At
 *				compile time (on gcc), be sure to indicate the presence of
 *				this file with the -DHAS_EXECINFO flag.  If this flag is not
 *				present, no backtrace will be generated - instead, a line
 *				stating the absence of execinfo.h will be produced.
 *
 *			-	when compiling (with gcc), use the '-rdynamic' flag if you
 *				wish symbolic information to be generated (highly
 *				recommended).
 */
int make_backtrace(char *backtrace_text, size_t size);


#endif
