mirror of
https://github.com/isc-projects/bind9.git
synced 2026-03-01 04:50:50 -05:00
dfd56b84f5
This commit adds support for generating backtraces on Windows and refactors the isc_backtrace API to match the Linux/BSD API (without the isc_ prefix) * isc_backtrace_gettrace() was renamed to isc_backtrace(), the third argument was removed and the return type was changed to int * isc_backtrace_symbols() was added * isc_backtrace_symbols_fd() was added and used as appropriate
99 lines
3.1 KiB
C
99 lines
3.1 KiB
C
/*
|
|
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
|
|
*
|
|
* 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
|