citadel/ecrash.h

   1 /**
   2  * \file eCrash.h
   3  * @author David Frascone
   4  *
   5  *  eCrash types and prototypes.
   6  *
   7  * vim: ts=4
   8  */
   9
  10 #ifndef _ECRASH_H_
  11 #define _ECRASH_H_
  12
  13 #include <stdio.h>
  14 #include <signal.h>
  15
  16 typedef void (*sighandler_t)(int);
  17
  18 typedef long BOOL;
  19
  20 #define MAX_LINE_LEN 256
  21
  22 #ifndef TRUE
  23 #define TRUE 1
  24 #define FALSE 0
  25 #define BOOL int
  26 #endif
  27
  28 #define ECRASH_DEFAULT_STACK_DEPTH 10
  29 #define ECRASH_DEFAULT_BACKTRACE_SIGNAL SIGUSR2
  30 #define ECRASH_DEFAULT_THREAD_WAIT_TIME 10
  31 #define ECRASH_MAX_NUM_SIGNALS 30
  32
  33 /** \struct eCrashSymbol
  34  *  \brief Function Name / Address pair
  35  *
  36  *  This is used in conjunction with eCrashSymbolTable to
  37  *  provide an alternative to backtrace_symbols.
  38  */
  39 typedef struct {
  40         char          *function;
  41         void          *address;
  42 } eCrashSymbol;
  43 /** \struct eCrashSymbolTable
  44  *  \brief Symbol table used to avoid backtrace_symbols()
  45  *
  46  *  This structure is used to provide a alternative to
  47  *  backtrace_symbols which is not async signal safe.
  48  *
  49  *  The symbol table should be sorted by address (it will
  50  *  be either binary or linearly searched)
  51  */
  52 typedef struct {
  53         int           numSymbols;
  54         eCrashSymbol *symbols;
  55 } eCrashSymbolTable;
  56
  57
  58
  59 #define ECRASH_DEBUG_ENABLE  /* undef to turn off debug */
  60
  61 #ifdef ECRASH_DEBUG_ENABLE
  62 # define ECRASH_DEBUG_VERY_VERBOSE 1
  63 # define ECRASH_DEBUG_VERBOSE      2
  64 # define ECRASH_DEBUG_INFO         3
  65 # define ECRASH_DEBUG_WARN         4
  66 # define ECRASH_DEBUG_ERROR        5
  67 # define ECRASH_DEBUG_OFF          6
  68 # define ECRASH_DEBUG_DEFAULT     (ECRASH_DEBUG_ERROR)
  69 # define DPRINTF(level, fmt...) \
  70                 if (level >= gbl_params.debugLevel) { printf(fmt); fflush(stdout); }
  71 #else /* ECRASH_DEBUG_ENABLE */
  72 # define DPRINTF(level, fmt...)
  73 #endif /* ECRASH_DEBUG_ENABLE */
  74
  75
  76 /** \struct eCrashParameters
  77  *  \brief eCrash Initialization Parameters
  78  *
  79  *  This structure contains all the global initialization functions
  80  *  for eCrash.
  81  *
  82  *  @see eCrash_Init
  83  */
  84 typedef struct {
  85
  86
  87         /*  OUTPUT OPTIONS */
  88                 /** Filename to output to, or NULL */
  89         char *filename;
  90                 /** FILE * to output to or NULL */
  91         FILE *filep;
  92                 /** fd to output to or -1 */
  93         int     fd;
  94
  95         int debugLevel;
  96
  97                 /** If true, all registered threads will
  98                  *   be dumped
  99          */
 100         BOOL dumpAllThreads;
 101
 102                 /** How far to backtrace each stack */
 103         unsigned int maxStackDepth;
 104
 105                 /** Default signal to use to tell a thread to drop it's
 106                  *  stack.
 107                  */
 108         int defaultBacktraceSignal;
 109
 110                 /** How long to wait for a threads
 111                  *  dump
 112                  */
 113         unsigned int threadWaitTime;
 114
 115                 /** If this is non-zero, the dangerous function, backtrace_symbols
 116                   * will be used.  That function does a malloc(), so is not async
 117                   * signal safe, and could cause deadlocks.
 118                   */
 119         BOOL useBacktraceSymbols;
 120
 121                 /** To avoid the issues with backtrace_symbols (see comments above)
 122                   * the caller can supply it's own symbol table, containing function
 123                   * names and start addresses.  This table can be created using
 124                   * a script, or a static table.
 125                   *
 126                   * If this variable is not null, it will be used, instead of
 127                   * backtrace_symbols, reguardless of the setting
 128                   * of useBacktraceSymbols.
 129                   */
 130         eCrashSymbolTable *symbolTable;
 131
 132                 /** Array of crash signals to catch,
 133                  *  ending in 0  I would have left it a [] array, but I
 134                  *  do a static copy, so I needed a set size.
 135          */
 136         int signals[ECRASH_MAX_NUM_SIGNALS];
 137
 138 } eCrashParameters;
 139
 140 /*!
 141  * Initialize eCrash.
 142  *
 143  * This function must be called before calling any other eCrash
 144  * functions.  It sets up the global behavior of the system.
 145  *
 146  * @param params Our input parameters.  The passed in structure will be copied.
 147  *
 148  * @return Zero on success.
 149  */
 150 int eCrash_Init(eCrashParameters *params);
 151 /*!
 152  * UnInitialize eCrash.
 153  *
 154  * This function may be called to de-activate eCrash, release the
 155  * signal handlers, and free any memory allocated by eCrash.
 156  *
 157  * @return Zero on success.
 158  */
 159 int eCrash_Uninit( void );
 160
 161 /*!
 162  * Register a thread for backtracing on crash.
 163  *
 164  * This function must be called by any thread wanting it's stack
 165  * dumped in the event of a crash.  The thread my specify what
 166  * signal should be used, or the default, SIGUSR1 will be used.
 167  *
 168  * @param name String used to refer to us in crash dumps
 169  * @param signo Signal to use to generate dump (default: SIGUSR1)
 170  *
 171  * @return Zero on success.
 172  */
 173 int eCrash_RegisterThread(char *name, int signo);
 174
 175 /*!
 176  * Un-register a thread for stack dumps.
 177  *
 178  * This function may be called to un-register any previously
 179  * registered thread.
 180  *
 181  * @return Zero on success.
 182  */
 183 int eCrash_UnregisterThread( void );
 184
 185 #endif /* _E_CRASH_H_ */