The Tor Browser: xpcom/base/nsStackWalk.h@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     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/. */

     6 /* API for getting a stack trace of the C/C++ stack on the current thread */

     8 #ifndef nsStackWalk_h_

     9 #define nsStackWalk_h_

    11 /* WARNING: This file is intended to be included from C or C++ files. */

    13 #include "nscore.h"

    14 #include <stdint.h>

    16 #ifdef __cplusplus

    17 extern "C" {

    18 #endif

    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);

    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);

    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;

    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);

   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);

   121 #ifdef __cplusplus

   122 }

   123 #endif

   125 #endif /* !defined(nsStackWalk_h_) */

The Tor Browser / file revision