xpcom/base/nsStackWalk.h

   1 /* vim: set shiftwidth=4 tabstop=8 autoindent cindent expandtab: */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is NS_WalkTheStack.
  16  *
  17  * The Initial Developer of the Original Code is the Mozilla Foundation.
  18  * Portions created by the Initial Developer are Copyright (C) 2007
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   L. David Baron <dbaron@dbaron.org>, Mozilla Corporation (original author)
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /* API for getting a stack trace of the C/C++ stack on the current thread */
  39
  40 #ifndef nsStackWalk_h_
  41 #define nsStackWalk_h_
  42
  43 /* WARNING: This file is intended to be included from C or C++ files. */
  44
  45 #include "nscore.h"
  46
  47 PR_BEGIN_EXTERN_C
  48
  49 typedef void
  50 (* NS_WalkStackCallback)(void *aPC, void *aClosure);
  51
  52 /**
  53  * Call aCallback for the C/C++ stack frames on the current thread, from
  54  * the caller of NS_StackWalk to main (or above).
  55  *
  56  * @param aCallback    Callback function, called once per frame.
  57  * @param aSkipFrames  Number of initial frames to skip.  0 means that
  58  *                     the first callback will be for the caller of
  59  *                     NS_StackWalk.
  60  * @param aClosure     Caller-supplied data passed through to aCallback.
  61  *
  62  * Returns NS_ERROR_NOT_IMPLEMENTED on platforms where it is
  63  * unimplemented.
  64  *
  65  * May skip some stack frames due to compiler optimizations or code
  66  * generation.
  67  */
  68 XPCOM_API(nsresult)
  69 NS_StackWalk(NS_WalkStackCallback aCallback, PRUint32 aSkipFrames,
  70              void *aClosure);
  71
  72 typedef struct {
  73     /*
  74      * The name of the shared library or executable containing an
  75      * address and the address's offset within that library, or empty
  76      * string and zero if unknown.
  77      */
  78     char library[256];
  79     unsigned long loffset;
  80     /*
  81      * The name of the file name and line number of the code
  82      * corresponding to the address, or empty string and zero if
  83      * unknown.
  84      */
  85     char filename[256];
  86     unsigned long lineno;
  87     /*
  88      * The name of the function containing an address and the address's
  89      * offset within that function, or empty string and zero if unknown.
  90      */
  91     char function[256];
  92     unsigned long foffset;
  93 } nsCodeAddressDetails;
  94
  95 /**
  96  * For a given pointer to code, fill in the pieces of information used
  97  * when printing a stack trace.
  98  *
  99  * @param aPC         The code address.
 100  * @param aDetails    A structure to be filled in with the result.
 101  */
 102 XPCOM_API(nsresult)
 103 NS_DescribeCodeAddress(void *aPC, nsCodeAddressDetails *aDetails);
 104
 105 /**
 106  * Format the information about a code address in a format suitable for
 107  * stack traces on the current platform.  When available, this string
 108  * should contain the function name, source file, and line number.  When
 109  * these are not available, library and offset should be reported, if
 110  * possible.
 111  *
 112  * @param aPC         The code address.
 113  * @param aDetails    The value filled in by NS_DescribeCodeAddress(aPC).
 114  * @param aBuffer     A string to be filled in with the description.
 115  *                    The string will always be null-terminated.
 116  * @param aBufferSize The size, in bytes, of aBuffer, including
 117  *                    room for the terminating null.  If the information
 118  *                    to be printed would be larger than aBuffer, it
 119  *                    will be truncated so that aBuffer[aBufferSize-1]
 120  *                    is the terminating null.
 121  */
 122 XPCOM_API(nsresult)
 123 NS_FormatCodeAddressDetails(void *aPC, const nsCodeAddressDetails *aDetails,
 124                             char *aBuffer, PRUint32 aBufferSize);
 125
 126 PR_END_EXTERN_C
 127
 128 #endif /* !defined(nsStackWalk_h_) */