xpcom/base/nsStackWalk.h

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