1 /* 2 * Copyright (c) 2022-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef DFX_BACKTRACE_LOCAL_H 17 #define DFX_BACKTRACE_LOCAL_H 18 19 #include <cinttypes> 20 #include <string> 21 #include <vector> 22 23 #include "dfx_define.h" 24 #include "dfx_frame.h" 25 26 namespace OHOS { 27 namespace HiviewDFX { 28 29 /** 30 * @brief Get a thread of backtrace frames by specify tid 31 * 32 * @param frames backtrace frames(output parameter) 33 * @param tid the id of thread. 34 * notice: the value can not equal to tid of the caller thread, 35 * if you want to get stack of the caller thread, 36 * please use interface of "GetBacktrace" or "PrintBacktrace". 37 * @param skipFrameNum the number of frames to skip 38 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 39 * @param maxFrameNums the maximum number of frames to backtrace 40 * @return if succeed return true, otherwise return false 41 */ 42 bool GetBacktraceFramesByTid(std::vector<DfxFrame>& frames, int32_t tid, size_t skipFrameNum, bool fast, 43 size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 44 45 /** 46 * @brief Get a thread of backtrace string by specify tid 47 * 48 * @param out backtrace string(output parameter) 49 * @param tid the id of thread. 50 * notice: the value can not equal to tid of the caller thread, 51 * if you want to get stack of the caller thread, 52 * please use interface of "GetBacktrace" or "PrintBacktrace". 53 * @param skipFrameNum the number of frames to skip 54 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 55 * @param maxFrameNums the maximum number of frames to backtrace 56 * @param enableKernelStack if set to true, when failed to get user stack, try to get kernel stack. 57 * @return if succeed return true, otherwise return false 58 * @warning If enableKernelStack set to true, this interface requires that the caller process 59 * has ioctl system call permission, otherwise it may cause the calling process to crash. 60 */ 61 bool GetBacktraceStringByTid(std::string& out, int32_t tid, size_t skipFrameNum, bool fast, 62 size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM, bool enableKernelStack = true); 63 64 /** 65 * @brief Print backtrace information to fd 66 * 67 * @param fd file descriptor 68 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 69 * @param maxFrameNums the maximum number of frames to backtrace 70 * @return if succeed return true, otherwise return false 71 */ 72 bool PrintBacktrace(int32_t fd = -1, bool fast = false, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 73 74 /** 75 * @brief Get backtrace string of the current process 76 * 77 * @param out backtrace string(output parameter) 78 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 79 * @param maxFrameNums the maximum number of frames to backtrace 80 * @return if succeed return true, otherwise return false. 81 */ 82 bool GetBacktrace(std::string& out, bool fast = false, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 83 84 /** 85 * @brief Get backtrace string of the current process 86 * 87 * @param out backtrace string(output parameter) 88 * @param skipFrameNum the number of frames to skip 89 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 90 * @param maxFrameNums the maximum number of frames to backtrace 91 * @return if succeed return true, otherwise return false 92 */ 93 bool GetBacktrace(std::string& out, size_t skipFrameNum, bool fast = false, 94 size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 95 96 /** 97 * @brief Get formatted stacktrace string of current process 98 * 99 * This API is used to get formatted stacktrace string of current process 100 * 101 * @param maxFrameNums the maximum number of frames to backtrace 102 * @param enableKernelStack if set to true, when failed to get user stack, try to get kernel stack. 103 * @return formatted stacktrace string 104 * @warning If enableKernelStack set to true, this interface requires that the caller process 105 * has ioctl system call permission, otherwise it may cause the calling process to crash. 106 */ 107 std::string GetProcessStacktrace(size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM, bool enableKernelStack = true); 108 109 extern "C" { 110 /** 111 * @brief Print backtrace information to fd 112 * 113 * @param fd file descriptor 114 * @param maxFrameNums the maximum number of frames to backtrace 115 * @return if succeed return true, otherwise return false 116 */ 117 bool PrintTrace(int32_t fd = -1, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 118 119 /** 120 * @brief Get backtrace of the current process 121 * 122 * @param skipFrameNum the number of frames to skip 123 * @param maxFrameNums the maximum number of frames to backtrace 124 * @return backtrace of the current process 125 */ 126 const char* GetTrace(size_t skipFrameNum = 0, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 127 } 128 } // namespace HiviewDFX 129 } // namespace OHOS 130 #endif 131