1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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
|
