src/util/error.h

   1 /** Error handling and debugging stuff
   2  * @file
   3  *
   4  * Here you will found a chunk of functions useful for error states --- from
   5  * reporting of various problems to generic error tests/workarounds to some
   6  * tools to be used when you got into an error state already. Some of the
   7  * functions are also useful for debugging. */
   8
   9 #ifndef EL__UTIL_ERROR_H
  10 #define EL__UTIL_ERROR_H
  11
  12 /* This errfile thing is needed, as we don't have var-arg macros in standart,
  13  * only as gcc extension :(. */
  14 extern int errline;
  15 extern const unsigned char *errfile;
  16
  17 /** @c DBG(format_string) is used for printing of debugging information. It
  18  * should not be used anywhere in the official codebase (although it is often
  19  * lying there commented out, as it may get handy). */
  20 #undef DBG
  21 #define DBG errfile = __FILE__, errline = __LINE__, elinks_debug
  22 void elinks_debug(unsigned char *fmt, ...);
  23
  24 /** @c WDBG(format_string) is used for printing of debugging information, akin
  25  * to DBG(). However, it sleep(1)s, therefore being useful when it is going
  26  * to be overdrawn or so. It should not be used anywhere in the official
  27  * codebase (although it is often lying there commented out, as it may get
  28  * handy). */
  29 #undef WDBG
  30 #define WDBG errfile = __FILE__, errline = __LINE__, elinks_wdebug
  31 void elinks_wdebug(unsigned char *fmt, ...);
  32
  33 /** @c ERROR(format_string) is used to report non-fatal unexpected errors during
  34  * the ELinks run. It tries to (not that agressively) draw user's attention to
  35  * the error, but never dumps core or so. Note that this should be used only in
  36  * cases of non-severe internal inconsistences etc, never as an indication of
  37  * user error (bad parameter, config file error etc.). We have usrerror() for
  38  * this kind of stuff, and there's nothing naughty about using that. */
  39 #undef ERROR
  40 #define ERROR errfile = __FILE__, errline = __LINE__, elinks_error
  41 void elinks_error(unsigned char *fmt, ...);
  42
  43 /** @c INTERNAL(format_string) is used to report fatal errors during the ELinks
  44  * run. It tries to draw user's attention to the error and dumps core if ELinks
  45  * is running in the CONFIG_DEBUG mode. */
  46 #undef INTERNAL
  47 #define INTERNAL errfile = __FILE__, errline = __LINE__, elinks_internal
  48 void elinks_internal(unsigned char *fmt, ...);
  49
  50
  51 /** @c usrerror(format_string) is used to report user errors during a peaceful
  52  * ELinks run. It does not belong to the family above - it doesn't print code
  53  * location, beep nor sleep, it just wraps around fprintf(stderr, "...\n");. */
  54 void usrerror(unsigned char *fmt, ...);
  55
  56
  57 #ifdef HAVE_VARIADIC_MACROS
  58 #ifdef CONFIG_DEBUG
  59 /** The @c LOG_*() macros can be used to log to a file, however, by default log
  60  * messages are written to stderr. Set the following environment variables
  61  * to configure the log behavior:
  62  *
  63  * <dl>
  64  * <dt>ELINKS_LOG       <dd>The path to the log file, it is opened for appending
  65  * <dt>ELINKS_MSG       <dd>A comma separated list containing "error", "warn",
  66  *                          "info" and/or "debug" which can be used to limit
  67  *                          what messages to emit to the log.
  68  * <dt>ELINKS_FILES     <dd>A comma separated list of which files names to
  69  *                          emit log messages from.
  70  * </dl>
  71  */
  72 void
  73 elinks_log(unsigned char *msg, unsigned char *file, int line,
  74            unsigned char *fmt, ...);
  75
  76 #undef LOG_ERR
  77 #define LOG_ERR(args...) \
  78         elinks_log("error", __FILE__, __LINE__, args)
  79
  80 #undef LOG_WARN
  81 #define LOG_WARN(args...) \
  82         elinks_log("warn", __FILE__, __LINE__, args)
  83
  84 #undef LOG_INFO
  85 #define LOG_INFO(args...) \
  86         elinks_log("info", __FILE__, __LINE__, args)
  87
  88 #undef LOG_DBG
  89 #define LOG_DBG(args...) \
  90         elinks_log("debug", __FILE__, __LINE__, args)
  91
  92 #endif
  93 #endif
  94
  95
  96
  97 /** This is our smart assert(). It is basically equivalent to if (x) INTERNAL(),
  98  * but it generates a uniform message and mainly does not do the test if we are
  99  * supposed to be lightning fast. Use it, use it a lot! And never forget the
 100  * recovery path, see below ::if_assert_failed. */
 101
 102 #undef assert
 103 #ifdef CONFIG_FASTMEM
 104 #define assert(x) /* We don't do anything in CONFIG_FASTMEM mode. */
 105 #else
 106 #define assert(x) \
 107 do { if (!assert_failed && (assert_failed = !(x))) { \
 108         INTERNAL("assertion " #x " failed!"); \
 109 } } while (0)
 110 #endif
 111
 112
 113 /** This is extended assert() version, it can print additional user-specified
 114  * message. Quite useful not only to detect that _something_ is wrong, but also
 115  * _how_ wrong is it ;-). Note that the format string must always be a regular
 116  * string, not a variable reference. Also, be careful _what_ will you attempt
 117  * to print, or you could easily get just a SIGSEGV instead of the assertion
 118  * failed message. */
 119
 120 #undef assertm
 121 #ifdef HAVE_VARIADIC_MACROS
 122 #ifdef CONFIG_FASTMEM
 123 #define assertm(x,m...) /* We don't do anything in CONFIG_FASTMEM mode. */
 124 #else
 125 #define assertm(x,m...) \
 126 do { if (!assert_failed && (assert_failed = !(x))) { \
 127         INTERNAL("assertion " #x " failed: " m); \
 128 } } while (0)
 129 #endif
 130 #else /* HAVE_VARIADIC_MACROS */
 131 #ifdef CONFIG_FASTMEM
 132 #define assertm elinks_assertm
 133 #else
 134 #define assertm errfile = __FILE__, errline = __LINE__, elinks_assertm
 135 #endif
 136 /* This is not nice at all, and does not really work that nice as macros do
 137  * But it is good to try to do at least _some_ assertm()ing even when the
 138  * variadic macros are not supported. */
 139 /* XXX: assertm() usage could generate warnings (we assume that the assert()ed
 140  * expression is int (and that's completely fine, I do *NOT* want to see any
 141  * stinking assert((int) pointer) ! ;-)), so CONFIG_DEBUG (-Werror) and
 142  * !HAVE_VARIADIC_MACROS won't play well together. Hrm. --pasky */
 143 #ifdef CONFIG_FASTMEM
 144 static inline
 145 #endif
 146 void elinks_assertm(int x, unsigned char *fmt, ...)
 147 #ifdef CONFIG_FASTMEM
 148 {
 149         /* We don't do anything in CONFIG_FASTMEM mode. Let's hope that the compiler
 150          * will at least optimize out the @x computation. */
 151 }
 152 #else
 153         ;
 154 #endif
 155 #endif /* HAVE_VARIADIC_MACROS */
 156
 157
 158 /** Whether an assertion has failed and the failure has not yet been handled.
 159  * To make recovery path possible (assertion failed may not mean end of the
 160  * world, the execution goes on if we're outside of CONFIG_DEBUG and CONFIG_FASTMEM),
 161  * @c assert_failed is set to true if the last assert() failed, otherwise it's
 162  * zero. Note that you must never change assert_failed value, sorry guys.
 163  *
 164  * You should never test @c assert_failed directly anyway. Use ::if_assert_failed
 165  * instead, it will attempt to hint compiler to optimize out the recovery path
 166  * if we're CONFIG_FASTMEM. So it should go like:
 167  *
 168  * @code
 169  * assertm(1 == 1, "The world's gonna blow up!");
 170  * if_assert_failed { schedule_time_machine(); return; }
 171  * @endcode
 172  *
 173  * In-depth explanation: this restriction is here because in the CONFIG_FASTMEM mode,
 174  * @c assert_failed is initially initialized to zero and then not ever touched
 175  * anymore. So if you change it to non-zero failure, your all further recovery
 176  * paths will get hit (and since developers usually don't test CONFIG_FASTMEM mode
 177  * extensively...). So better don't mess with it, even if you would do that
 178  * with awareness of this fact. We don't want to iterate over tens of spots all
 179  * over the code when we change one detail regarding CONFIG_FASTMEM operation.
 180  *
 181  * This is not that actual after introduction of ::if_assert_failed, but it's
 182  * a safe recommendation anyway, so... ;-) */
 183 extern int assert_failed;
 184
 185 #undef if_assert_failed
 186 #ifdef CONFIG_FASTMEM
 187 #define if_assert_failed if (0) /* This should be optimalized away. */
 188 #else
 189 #define if_assert_failed if (assert_failed && !(assert_failed = 0))
 190 #endif
 191
 192
 193
 194 /** This will print some fancy message, version string and possibly do
 195  * something else useful. Then, it will dump core. */
 196 #ifdef CONFIG_DEBUG
 197 void force_dump(void);
 198 #endif
 199
 200
 201 /** This function does nothing, except making compiler not to optimize certains
 202  * spots of code --- this is useful when that particular optimization is buggy.
 203  * So we are just workarounding buggy compilers.
 204  *
 205  * This function should be always used only in context of compiler version
 206  * specific macros. */
 207 void do_not_optimize_here(void *x);
 208
 209 #if defined(__GNUC__) && __GNUC__ == 2 && __GNUC_MINOR__ <= 7
 210 #define do_not_optimize_here_gcc_2_7(x) do_not_optimize_here(x)
 211 #else
 212 #define do_not_optimize_here_gcc_2_7(x)
 213 #endif
 214
 215 #if defined(__GNUC__) && __GNUC__ == 3
 216 #define do_not_optimize_here_gcc_3_x(x) do_not_optimize_here(x)
 217 #else
 218 #define do_not_optimize_here_gcc_3_x(x)
 219 #endif
 220
 221 #if defined(__GNUC__) && __GNUC__ == 3 && __GNUC_MINOR__ == 3
 222 #define do_not_optimize_here_gcc_3_3(x) do_not_optimize_here(x)
 223 #else
 224 #define do_not_optimize_here_gcc_3_3(x)
 225 #endif
 226
 227
 228 /** This function dumps backtrace (or whatever similar it founds on the stack)
 229  * nicely formatted and with symbols resolved to @a f. When @a trouble is set,
 230  * it tells it to be extremely careful and not use dynamic memory allocation
 231  * functions etc (useful in SIGSEGV handler etc).
 232  *
 233  * Note that this function just calls system-specific backend provided by the
 234  * libc, so it is available only on some systems. CONFIG_BACKTRACE is defined
 235  * if it is available on yours. */
 236 #ifdef CONFIG_BACKTRACE
 237 #include <stdio.h>
 238 void dump_backtrace(FILE *f, int trouble);
 239 #endif
 240
 241 /** This is needed for providing info about features when dumping core */
 242 extern unsigned char full_static_version[1024];
 243
 244 #endif