The Tor Browser / file comparison
comparison: xpcom/base/nsStackWalk.h
xpcom/base/nsStackWalk.h
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:074e2ae720c7 |
|---|---|
| 1 /* vim: set shiftwidth=4 tabstop=8 autoindent cindent expandtab: */ | |
| 2 /* This Source Code Form is subject to the terms of the Mozilla Public | |
| 3 * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ | |
| 5 | |
| 6 /* API for getting a stack trace of the C/C++ stack on the current thread */ | |
| 7 | |
| 8 #ifndef nsStackWalk_h_ | |
| 9 #define nsStackWalk_h_ | |
| 10 | |
| 11 /* WARNING: This file is intended to be included from C or C++ files. */ | |
| 12 | |
| 13 #include "nscore.h" | |
| 14 #include <stdint.h> | |
| 15 | |
| 16 #ifdef __cplusplus | |
| 17 extern "C" { | |
| 18 #endif | |
| 19 | |
| 20 // aSP will be the best approximation possible of what the stack pointer will be | |
| 21 // pointing to when the execution returns to executing that at that PC. | |
| 22 // If no approximation can be made it will be nullptr. | |
| 23 typedef void | |
| 24 (* NS_WalkStackCallback)(void *aPC, void *aSP, void *aClosure); | |
| 25 | |
| 26 /** | |
| 27 * Call aCallback for the C/C++ stack frames on the current thread, from | |
| 28 * the caller of NS_StackWalk to main (or above). | |
| 29 * | |
| 30 * @param aCallback Callback function, called once per frame. | |
| 31 * @param aSkipFrames Number of initial frames to skip. 0 means that | |
| 32 * the first callback will be for the caller of | |
| 33 * NS_StackWalk. | |
| 34 * @param aMaxFrames Maximum number of frames to trace. 0 means no limit. | |
| 35 * @param aClosure Caller-supplied data passed through to aCallback. | |
| 36 * @param aThread The thread for which the stack is to be retrieved. | |
| 37 * Passing null causes us to walk the stack of the | |
| 38 * current thread. On Windows, this is a thread HANDLE. | |
| 39 * It is currently not supported on any other platform. | |
| 40 * @param aPlatformData Platform specific data that can help in walking the | |
| 41 * stack, this should be nullptr unless you really know | |
| 42 * what you're doing! This needs to be a pointer to a | |
| 43 * CONTEXT on Windows and should not be passed on other | |
| 44 * platforms. | |
| 45 * | |
| 46 * Return values: | |
| 47 * - NS_ERROR_NOT_IMPLEMENTED. Occurs on platforms where it is unimplemented. | |
| 48 * | |
| 49 * - NS_ERROR_UNEXPECTED. Occurs when the stack indicates that the thread | |
| 50 * is in a very dangerous situation (e.g., holding sem_pool_lock in Mac OS X | |
| 51 * pthreads code). Callers should then bail out immediately. | |
| 52 * | |
| 53 * - NS_ERROR_FAILURE. Occurs when stack walking completely failed, i.e. | |
| 54 * aCallback was never called. | |
| 55 * | |
| 56 * - NS_OK. Occurs when stack walking succeeded, i.e. aCallback was called at | |
| 57 * least once (and there was no need to exit with NS_ERROR_UNEXPECTED). | |
| 58 * | |
| 59 * May skip some stack frames due to compiler optimizations or code | |
| 60 * generation. | |
| 61 */ | |
| 62 XPCOM_API(nsresult) | |
| 63 NS_StackWalk(NS_WalkStackCallback aCallback, uint32_t aSkipFrames, | |
| 64 uint32_t aMaxFrames, void *aClosure, uintptr_t aThread, | |
| 65 void *aPlatformData); | |
| 66 | |
| 67 typedef struct { | |
| 68 /* | |
| 69 * The name of the shared library or executable containing an | |
| 70 * address and the address's offset within that library, or empty | |
| 71 * string and zero if unknown. | |
| 72 */ | |
| 73 char library[256]; | |
| 74 ptrdiff_t loffset; | |
| 75 /* | |
| 76 * The name of the file name and line number of the code | |
| 77 * corresponding to the address, or empty string and zero if | |
| 78 * unknown. | |
| 79 */ | |
| 80 char filename[256]; | |
| 81 unsigned long lineno; | |
| 82 /* | |
| 83 * The name of the function containing an address and the address's | |
| 84 * offset within that function, or empty string and zero if unknown. | |
| 85 */ | |
| 86 char function[256]; | |
| 87 ptrdiff_t foffset; | |
| 88 } nsCodeAddressDetails; | |
| 89 | |
| 90 /** | |
| 91 * For a given pointer to code, fill in the pieces of information used | |
| 92 * when printing a stack trace. | |
| 93 * | |
| 94 * @param aPC The code address. | |
| 95 * @param aDetails A structure to be filled in with the result. | |
| 96 */ | |
| 97 XPCOM_API(nsresult) | |
| 98 NS_DescribeCodeAddress(void *aPC, nsCodeAddressDetails *aDetails); | |
| 99 | |
| 100 /** | |
| 101 * Format the information about a code address in a format suitable for | |
| 102 * stack traces on the current platform. When available, this string | |
| 103 * should contain the function name, source file, and line number. When | |
| 104 * these are not available, library and offset should be reported, if | |
| 105 * possible. | |
| 106 * | |
| 107 * @param aPC The code address. | |
| 108 * @param aDetails The value filled in by NS_DescribeCodeAddress(aPC). | |
| 109 * @param aBuffer A string to be filled in with the description. | |
| 110 * The string will always be null-terminated. | |
| 111 * @param aBufferSize The size, in bytes, of aBuffer, including | |
| 112 * room for the terminating null. If the information | |
| 113 * to be printed would be larger than aBuffer, it | |
| 114 * will be truncated so that aBuffer[aBufferSize-1] | |
| 115 * is the terminating null. | |
| 116 */ | |
| 117 XPCOM_API(nsresult) | |
| 118 NS_FormatCodeAddressDetails(void *aPC, const nsCodeAddressDetails *aDetails, | |
| 119 char *aBuffer, uint32_t aBufferSize); | |
| 120 | |
| 121 #ifdef __cplusplus | |
| 122 } | |
| 123 #endif | |
| 124 | |
| 125 #endif /* !defined(nsStackWalk_h_) */ |
