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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
#ifndef SENTRY_DATA_STRUCTURES_H
#define SENTRY_DATA_STRUCTURES_H
#include <cstddef>
#include <cstdint>
#ifdef __cplusplus
extern "C" {
#endif
/// Structure holding all stack frames in a certain thread. Use the call_stack_*
/// family of functions to interact with a call stack.
struct call_stack_t;
/// Carries information about the code module loaded into the process. The field
/// debug_identifier contains the UUID of this module. Use the code_module_*
/// family of functions to interact with a code module.
struct code_module_t;
/// Snapshot of the state of a process during its crash. This object is obtained
/// by processing Minidumps using the process_* family of functions. To interact
/// with ProcessStates use the process_state_* family of functions.
struct process_state_t;
/// Contains information from the stackdump, especially the frame's instruction
/// pointer. After being processed by a resolver, this struct also contains
/// source code locations and code offsets.
struct stack_frame_t;
/// Releases memory of a process state struct. Assumes ownership of the pointer.
void process_state_delete(process_state_t *state);
/// Returns a weak pointer to the list of threads in the minidump. Each thread
/// is represented by the call stack structure. The number of threads is
/// returned in the size_out parameter.
call_stack_t *const *process_state_threads(process_state_t *state,
size_t *size_out);
/// Returns the thread identifier of this callstack.
uint32_t call_stack_thread_id(const call_stack_t *stack);
/// Returns a weak pointer to the list of frames in a call stack. Each frame is
/// represented by the stack frame structure. The number of frames is returned
/// in the size_out parameter.
stack_frame_t *const *call_stack_frames(const call_stack_t *stack,
size_t *size_out);
/// Returns the program counter location as an absolute virtual address.
///
/// - For the innermost called frame in a stack, this will be an exact
/// program counter or instruction pointer value.
///
/// - For all other frames, this address is within the instruction that
/// caused execution to branch to this frame's callee (although it may
/// not point to the exact beginning of that instruction). This ensures
/// that, when we look up the source code location for this frame, we
/// get the source location of the call, not of the point at which
/// control will resume when the call returns, which may be on the next
/// line. (If the compiler knows the callee never returns, it may even
/// place the call instruction at the very end of the caller's machine
/// code, such that the "return address" (which will never be used)
/// immediately after the call instruction is in an entirely different
/// function, perhaps even from a different source file.)
///
/// On some architectures, the return address as saved on the stack or in
/// a register is fine for looking up the point of the call. On others, it
/// requires adjustment. ReturnAddress returns the address as saved by the
/// machine.
///
/// Use stack_frame_trust to obtain how trustworthy this instruction is.
uint64_t stack_frame_instruction(const stack_frame_t *frame);
/// Returns a weak pointer to the code module that hosts the instruction of the
/// stack framme. This function can return null for some frames.
const code_module_t *stack_frame_module(const stack_frame_t *frame);
/// Returns how well the instruction pointer derived during
/// stack walking is trusted. Since the stack walker can resort to
/// stack scanning, it can wind up with dubious frames.
/// In rough order of "trust metric".
int stack_frame_trust(const stack_frame_t *frame);
/// Returns the base address of this code module as it was loaded by the
/// process. (uint64_t)-1 on error.
uint64_t code_module_base_address(const code_module_t *module);
/// The size of the code module. 0 on error.
uint64_t code_module_size(const code_module_t *module);
/// Returns the path or file name that the code module was loaded from.
///
/// The return value is an owning pointer. Release memory with string_delete.
char *code_module_code_file(const code_module_t *module);
/// An identifying string used to discriminate between multiple versions and
/// builds of the same code module. This may contain a uuid, timestamp,
/// version number, or any combination of this or other information, in an
/// implementation-defined format.
///
/// The return value is an owning pointer. Release memory with string_delete.
char *code_module_code_identifier(const code_module_t *module);
/// Returns the filename containing debugging information of this code
/// module. If debugging information is stored in a file separate from the
/// code module itself (as is the case when .pdb or .dSYM files are used),
/// this will be different from code_file. If debugging information is
/// stored in the code module itself (possibly prior to stripping), this
/// will be the same as code_file.
///
/// The return value is an owning pointer. Release memory with string_delete.
char *code_module_debug_file(const code_module_t *module);
/// Returns a string identifying the specific version and build of the
/// associated debug file. This may be the same as code_identifier when
/// the debug_file and code_file are identical or when the same identifier
/// is used to identify distinct debug and code files.
///
/// It usually comprises the library's UUID and an age field. On Windows, the
/// age field is a generation counter, on all other platforms it is mostly
/// zero.
///
/// The return value is an owning pointer. Release memory with string_delete.
char *code_module_debug_identifier(const code_module_t *module);
#ifdef __cplusplus
}
#endif
#endif