backtrace.h revision f0c5872637a63e28e3cd314cfc915c07f76df9c6
1/* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17/* A stack unwinder. */ 18 19#ifndef _CORKSCREW_BACKTRACE_H 20#define _CORKSCREW_BACKTRACE_H 21 22#ifdef __cplusplus 23extern "C" { 24#endif 25 26#include <sys/types.h> 27#include <corkscrew/ptrace.h> 28#include <corkscrew/map_info.h> 29#include <corkscrew/symbol_table.h> 30 31/* 32 * Describes a single frame of a backtrace. 33 */ 34typedef struct { 35 uintptr_t absolute_pc; /* absolute PC offset */ 36 uintptr_t stack_top; /* top of stack for this frame */ 37 size_t stack_size; /* size of this stack frame */ 38} backtrace_frame_t; 39 40/* 41 * Describes the symbols associated with a backtrace frame. 42 */ 43typedef struct { 44 uintptr_t relative_pc; /* relative PC offset from the start of the library, 45 or the absolute PC if the library is unknown */ 46 char* map_name; /* executable or library name, or NULL if unknown */ 47 char* name; /* symbol name, or NULL if unknown */ 48 char* demangled_name; /* demangled symbol name, or NULL if unknown */ 49} backtrace_symbol_t; 50 51/* 52 * Unwinds the call stack for the current thread of execution. 53 * Populates the backtrace array with the program counters from the call stack. 54 * Returns the number of frames collected, or -1 if an error occurred. 55 */ 56ssize_t unwind_backtrace(backtrace_frame_t* backtrace, size_t ignore_depth, size_t max_depth); 57 58/* 59 * Unwinds the call stack for a thread within this process. 60 * Populates the backtrace array with the program counters from the call stack. 61 * Returns the number of frames collected, or -1 if an error occurred. 62 * 63 * The task is briefly suspended while the backtrace is being collected. 64 */ 65ssize_t unwind_backtrace_thread(pid_t tid, backtrace_frame_t* backtrace, 66 size_t ignore_depth, size_t max_depth); 67 68/* 69 * Unwinds the call stack of a task within a remote process using ptrace(). 70 * Populates the backtrace array with the program counters from the call stack. 71 * Returns the number of frames collected, or -1 if an error occurred. 72 */ 73ssize_t unwind_backtrace_ptrace(pid_t tid, const ptrace_context_t* context, 74 backtrace_frame_t* backtrace, size_t ignore_depth, size_t max_depth); 75 76/* 77 * Gets the symbols for each frame of a backtrace. 78 * The symbols array must be big enough to hold one symbol record per frame. 79 * The symbols must later be freed using free_backtrace_symbols. 80 */ 81void get_backtrace_symbols(const backtrace_frame_t* backtrace, size_t frames, 82 backtrace_symbol_t* backtrace_symbols); 83 84/* 85 * Gets the symbols for each frame of a backtrace from a remote process. 86 * The symbols array must be big enough to hold one symbol record per frame. 87 * The symbols must later be freed using free_backtrace_symbols. 88 */ 89void get_backtrace_symbols_ptrace(const ptrace_context_t* context, 90 const backtrace_frame_t* backtrace, size_t frames, 91 backtrace_symbol_t* backtrace_symbols); 92 93/* 94 * Frees the storage associated with backtrace symbols. 95 */ 96void free_backtrace_symbols(backtrace_symbol_t* backtrace_symbols, size_t frames); 97 98#ifdef __cplusplus 99} 100#endif 101 102#endif // _CORKSCREW_BACKTRACE_H 103