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 namespace OHOS { 24 namespace HiviewDFX { 25 static const int DEFAULT_MAX_FRAME_NUM = 256; 26 /** 27 * @brief Get a thread of backtrace string by specify tid 28 * 29 * @param out backtrace string(output parameter) 30 * @param tid the id of thread. 31 * notice: the value can not equal to tid of the caller thread, 32 * if you want to get stack of the caller thread, 33 * please use interface of "GetBacktrace" or "PrintBacktrace". 34 * @param skipFrameNum the number of frames to skip 35 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 36 * @param maxFrameNums the maximum number of frames to backtrace 37 * @param enableKernelStack if set to true, when failed to get user stack, try to get kernel stack. 38 * @return if succeed return true, otherwise return false 39 * @warning If enableKernelStack set to true, this interface requires that the caller process 40 * has ioctl system call permission, otherwise it may cause the calling process to crash. 41 */ 42 bool GetBacktraceStringByTid(std::string& out, int32_t tid, size_t skipFrameNum, bool fast, 43 size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM, bool enableKernelStack = true); 44 45 /** 46 * @brief Get a thread of backtrace string by specify tid enable mix 47 * 48 * @param out backtrace string(output parameter) 49 * @param tid the id of thread 50 * @param skipFrameNum the number of frames to skip 51 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 52 * @param maxFrameNums the maximum number of frames to backtrace 53 * @param enableKernelStack if set to true, when failed to get user stack, try to get kernel stack. 54 * @return if succeed return true, otherwise return false 55 * @warning If enableKernelStack set to true, this interface requires that the caller process 56 * has ioctl system call permission, otherwise it may cause the calling process to crash. 57 */ 58 bool GetBacktraceStringByTidWithMix(std::string& out, int32_t tid, size_t skipFrameNum, bool fast, 59 size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM, bool enableKernelStack = true); 60 61 /** 62 * @brief Print backtrace information to fd 63 * 64 * @param fd file descriptor 65 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 66 * @param maxFrameNums the maximum number of frames to backtrace 67 * @return if succeed return true, otherwise return false 68 */ 69 bool PrintBacktrace(int32_t fd = -1, bool fast = false, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 70 71 /** 72 * @brief Get backtrace string of the current thread 73 * 74 * @param out backtrace string(output parameter) 75 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 76 * @param maxFrameNums the maximum number of frames to backtrace 77 * @return if succeed return true, otherwise return false. 78 */ 79 bool GetBacktrace(std::string& out, bool fast = false, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 80 81 /** 82 * @brief Get backtrace string of the current thread 83 * 84 * @param out backtrace string(output parameter) 85 * @param skipFrameNum the number of frames to skip 86 * @param fast flag for using fp backtrace(true) or dwarf backtrace(false) 87 * @param maxFrameNums the maximum number of frames to backtrace 88 * @return if succeed return true, otherwise return false 89 */ 90 bool GetBacktrace(std::string& out, size_t skipFrameNum, bool fast = false, 91 size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 92 93 /** 94 * @brief Get formatted stacktrace string of current process 95 * 96 * This API is used to get formatted stacktrace string of current process 97 * 98 * @param maxFrameNums the maximum number of frames to backtrace 99 * @param enableKernelStack if set to true, when failed to get user stack, try to get kernel stack. 100 * @param includeThreadInfo if set to true, capture thread status information 101 * @return formatted stacktrace string 102 * @warning If enableKernelStack set to true, this interface requires that the caller process 103 * has ioctl system call permission, otherwise it may cause the calling process to crash. 104 */ 105 std::string GetProcessStacktrace(size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM, bool enableKernelStack = true, 106 bool includeThreadInfo = true); 107 108 extern "C" { 109 /** 110 * @brief Print backtrace information to fd 111 * 112 * @param fd file descriptor 113 * @param maxFrameNums the maximum number of frames to backtrace 114 * @return if succeed return true, otherwise return false 115 */ 116 bool PrintTrace(int32_t fd = -1, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 117 118 /** 119 * @brief Get backtrace of the current process 120 * 121 * @param skipFrameNum the number of frames to skip 122 * @param maxFrameNums the maximum number of frames to backtrace 123 * @return backtrace of the current process 124 */ 125 const char* GetTrace(size_t skipFrameNum = 0, size_t maxFrameNums = DEFAULT_MAX_FRAME_NUM); 126 } 127 } // namespace HiviewDFX 128 } // namespace OHOS 129 #endif 130