1 files changed, 101 insertions, 0 deletions
diff --git a/lib/isc/include/isc/backtrace.h b/lib/isc/include/isc/backtrace.h
new file mode 100644
index 0000000..f818c3b
--- /dev/null
+++ b/lib/isc/include/isc/backtrace.h
@@ -0,0 +1,101 @@
+/*
+ * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+ *
+ * SPDX-License-Identifier: MPL-2.0
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * See the COPYRIGHT file distributed with this work for additional
+ * information regarding copyright ownership.
+ */
+
+/*! \file isc/backtrace.h
+ * \brief provide a back trace of the running process to help debug problems.
+ *
+ * This module tries to get a back trace of the process using some platform
+ * dependent way when available.  It also manages an internal symbol table
+ * that maps function addresses used in the process to their textual symbols.
+ * This module is expected to be used to help debug when some fatal error
+ * happens.
+ *
+ * IMPORTANT NOTE: since the (major) intended use case of this module is
+ * dumping a back trace on a fatal error, normally followed by self termination,
+ * functions defined in this module generally doesn't employ assertion checks
+ * (if it did, a program bug could cause infinite recursive calls to a
+ * backtrace function).
+ */
+
+#pragma once
+
+/***
+ ***	Imports
+ ***/
+#include <isc/types.h>
+
+/***
+ *** Functions
+ ***/
+
+ISC_LANG_BEGINDECLS
+int
+isc_backtrace(void **addrs, int maxaddrs);
+/*%<
+ * Get a back trace of the running process above this function itself.  On
+ * success, addrs[i] will store the address of the call point of the i-th
+ * stack frame (addrs[0] is the caller of this function).  *nframes will store
+ * the total number of frames.
+ *
+ * Requires (note that these are not ensured by assertion checks, see above):
+ *
+ *\li	'addrs' is a valid array containing at least 'maxaddrs' void * entries.
+ *
+ *\li	'nframes' must be non NULL.
+ *
+ * Returns:
+ *
+ *\li	#ISC_R_SUCCESS
+ *\li	#ISC_R_FAILURE
+ *\li	#ISC_R_NOTFOUND
+ *\li	#ISC_R_NOTIMPLEMENTED
+ */
+
+char **
+isc_backtrace_symbols(void *const *buffer, int size);
+/*
+ * isc_backtrace_symbols() attempts to transform a call stack obtained by
+ * backtrace() into an array of human-readable strings using dladdr().  The
+ * array of strings returned has size elements.  It is allocated using
+ * malloc() and should be released using free().  There is no need to free
+ * the individual strings in the array.
+ *
+ * Notes:
+ *
+ *\li	On Windows, this is shim implementation using SymFromAddr()
+ *\li	On systems with backtrace_symbols(), it's just a thin wrapper
+ *\li	Otherwise, it returns NULL
+ *\li	See platform NOTES for backtrace_symbols
+ *
+ * Returns:
+ *
+ *\li	On success, backtrace_symbols() returns a pointer to the array
+ *\li	On error, NULL is returned.
+ */
+
+void
+isc_backtrace_symbols_fd(void *const *buffer, int size, int fd);
+/*
+ * isc_backtrace_symbols_fd() performs the same operation as
+ * isc_backtrace_symbols(), but the resulting strings are immediately written to
+ * the file descriptor fd, and are not returned.  isc_backtrace_symbols_fd()
+ * does not call malloc(3), and so can be employed in situations where the
+ * latter function might fail.
+ *
+ * Notes:
+ *
+ *\li	See isc_backtrace_symbols() notes
+ *\li	See platform NOTES for backtrace_symbols_fd for caveats
+ */
+
+ISC_LANG_ENDDECLS