util_bug.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  1. /* Copyright (c) 2003-2004, Roger Dingledine
  2. * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
  3. * Copyright (c) 2007-2019, The Tor Project, Inc. */
  4. /* See LICENSE for licensing information */
  5. /**
  6. * \file util_bug.h
  7. *
  8. * \brief Macros to manage assertions, fatal and non-fatal.
  9. *
  10. * Guidelines: All the different kinds of assertion in this file are for
  11. * bug-checking only. Don't write code that can assert based on bad inputs.
  12. *
  13. * We provide two kinds of assertion here: "fatal" and "nonfatal". Use
  14. * nonfatal assertions for any bug you can reasonably recover from -- and
  15. * please, try to recover! Many severe bugs in Tor have been caused by using
  16. * a regular assertion when a nonfatal assertion would have been better.
  17. *
  18. * If you need to check a condition with a nonfatal assertion, AND recover
  19. * from that same condition, consider using the BUG() macro inside a
  20. * conditional. For example:
  21. *
  22. * <code>
  23. * // wrong -- use tor_assert_nonfatal() if you just want an assertion.
  24. * BUG(ptr == NULL);
  25. *
  26. * // okay, but needlessly verbose
  27. * tor_assert_nonfatal(ptr != NULL);
  28. * if (ptr == NULL) { ... }
  29. *
  30. * // this is how we do it:
  31. * if (BUG(ptr == NULL)) { ... }
  32. * </code>
  33. **/
  34. #ifndef TOR_UTIL_BUG_H
  35. #define TOR_UTIL_BUG_H
  36. #include "orconfig.h"
  37. #include "lib/cc/compat_compiler.h"
  38. #include "lib/log/log.h"
  39. #include "lib/testsupport/testsupport.h"
  40. /* Replace assert() with a variant that sends failures to the log before
  41. * calling assert() normally.
  42. */
  43. #ifdef NDEBUG
  44. /* Nobody should ever want to build with NDEBUG set. 99% of our asserts will
  45. * be outside the critical path anyway, so it's silly to disable bug-checking
  46. * throughout the entire program just because a few asserts are slowing you
  47. * down. Profile, optimize the critical path, and keep debugging on.
  48. *
  49. * And I'm not just saying that because some of our asserts check
  50. * security-critical properties.
  51. */
  52. #error "Sorry; we don't support building with NDEBUG."
  53. #endif /* defined(NDEBUG) */
  54. #if defined(TOR_UNIT_TESTS) && defined(__GNUC__)
  55. /* We define this GCC macro as a replacement for PREDICT_UNLIKELY() in this
  56. * header, so that in our unit test builds, we'll get compiler warnings about
  57. * stuff like tor_assert(n = 5).
  58. *
  59. * The key here is that (e) is wrapped in exactly one layer of parentheses,
  60. * and then passed right to a conditional. If you do anything else to the
  61. * expression here, or introduce any more parentheses, the compiler won't
  62. * help you.
  63. *
  64. * We only do this for the unit-test build case because it interferes with
  65. * the likely-branch labeling. Note below that in the other case, we define
  66. * these macros to just be synonyms for PREDICT_(UN)LIKELY.
  67. */
  68. #define ASSERT_PREDICT_UNLIKELY_(e) \
  69. ( { \
  70. int tor__assert_tmp_value__; \
  71. if (e) \
  72. tor__assert_tmp_value__ = 1; \
  73. else \
  74. tor__assert_tmp_value__ = 0; \
  75. tor__assert_tmp_value__; \
  76. } )
  77. #define ASSERT_PREDICT_LIKELY_(e) ASSERT_PREDICT_UNLIKELY_(e)
  78. #else
  79. #define ASSERT_PREDICT_UNLIKELY_(e) PREDICT_UNLIKELY(e)
  80. #define ASSERT_PREDICT_LIKELY_(e) PREDICT_LIKELY(e)
  81. #endif
  82. /* Sometimes we don't want to use assertions during branch coverage tests; it
  83. * leads to tons of unreached branches which in reality are only assertions we
  84. * didn't hit. */
  85. #if defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_TESTS)
  86. #define tor_assert(a) STMT_BEGIN \
  87. (void)(a); \
  88. STMT_END
  89. #else
  90. /** Like assert(3), but send assertion failures to the log as well as to
  91. * stderr. */
  92. #define tor_assert(expr) STMT_BEGIN \
  93. if (ASSERT_PREDICT_LIKELY_(expr)) { \
  94. } else { \
  95. tor_assertion_failed_(SHORT_FILE__, __LINE__, __func__, #expr); \
  96. tor_abort_(); \
  97. } STMT_END
  98. #endif /* defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_TESTS) */
  99. #define tor_assert_unreached() \
  100. STMT_BEGIN { \
  101. tor_assertion_failed_(SHORT_FILE__, __LINE__, __func__, \
  102. "line should be unreached"); \
  103. tor_abort_(); \
  104. } STMT_END
  105. /* Non-fatal bug assertions. The "unreached" variants mean "this line should
  106. * never be reached." The "once" variants mean "Don't log a warning more than
  107. * once".
  108. *
  109. * The 'BUG' macro checks a boolean condition and logs an error message if it
  110. * is true. Example usage:
  111. * if (BUG(x == NULL))
  112. * return -1;
  113. */
  114. #ifdef __COVERITY__
  115. #undef BUG
  116. // Coverity defines this in global headers; let's override it. This is a
  117. // magic coverity-only preprocessor thing.
  118. #nodef BUG(x) (x)
  119. #endif /* defined(__COVERITY__) */
  120. #if defined(__COVERITY__) || defined(__clang_analyzer__)
  121. // We're running with a static analysis tool: let's treat even nonfatal
  122. // assertion failures as something that we need to avoid.
  123. #define ALL_BUGS_ARE_FATAL
  124. #endif
  125. #ifdef ALL_BUGS_ARE_FATAL
  126. #define tor_assert_nonfatal_unreached() tor_assert(0)
  127. #define tor_assert_nonfatal(cond) tor_assert((cond))
  128. #define tor_assert_nonfatal_unreached_once() tor_assert(0)
  129. #define tor_assert_nonfatal_once(cond) tor_assert((cond))
  130. #define BUG(cond) \
  131. (ASSERT_PREDICT_UNLIKELY_(cond) ? \
  132. (tor_assertion_failed_(SHORT_FILE__,__LINE__,__func__,"!("#cond")"), \
  133. tor_abort_(), 1) \
  134. : 0)
  135. #elif defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_TESTS)
  136. #define tor_assert_nonfatal_unreached() STMT_NIL
  137. #define tor_assert_nonfatal(cond) ((void)(cond))
  138. #define tor_assert_nonfatal_unreached_once() STMT_NIL
  139. #define tor_assert_nonfatal_once(cond) ((void)(cond))
  140. #define BUG(cond) (ASSERT_PREDICT_UNLIKELY_(cond) ? 1 : 0)
  141. #else /* Normal case, !ALL_BUGS_ARE_FATAL, !DISABLE_ASSERTS_IN_UNIT_TESTS */
  142. #define tor_assert_nonfatal_unreached() STMT_BEGIN \
  143. tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, NULL, 0); \
  144. STMT_END
  145. #define tor_assert_nonfatal(cond) STMT_BEGIN \
  146. if (ASSERT_PREDICT_LIKELY_(cond)) { \
  147. } else { \
  148. tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, #cond, 0); \
  149. } \
  150. STMT_END
  151. #define tor_assert_nonfatal_unreached_once() STMT_BEGIN \
  152. static int warning_logged__ = 0; \
  153. if (!warning_logged__) { \
  154. warning_logged__ = 1; \
  155. tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, NULL, 1); \
  156. } \
  157. STMT_END
  158. #define tor_assert_nonfatal_once(cond) STMT_BEGIN \
  159. static int warning_logged__ = 0; \
  160. if (ASSERT_PREDICT_LIKELY_(cond)) { \
  161. } else if (!warning_logged__) { \
  162. warning_logged__ = 1; \
  163. tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, #cond, 1); \
  164. } \
  165. STMT_END
  166. #define BUG(cond) \
  167. (ASSERT_PREDICT_UNLIKELY_(cond) ? \
  168. (tor_bug_occurred_(SHORT_FILE__,__LINE__,__func__,"!("#cond")",0), 1) \
  169. : 0)
  170. #endif /* defined(ALL_BUGS_ARE_FATAL) || ... */
  171. #ifdef __GNUC__
  172. #define IF_BUG_ONCE__(cond,var) \
  173. if (( { \
  174. static int var = 0; \
  175. int bool_result = !!(cond); \
  176. if (bool_result && !var) { \
  177. var = 1; \
  178. tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, \
  179. "!("#cond")", 1); \
  180. } \
  181. bool_result; } ))
  182. #else /* !(defined(__GNUC__)) */
  183. #define IF_BUG_ONCE__(cond,var) \
  184. static int var = 0; \
  185. if ((cond) ? \
  186. (var ? 1 : \
  187. (var=1, \
  188. tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, \
  189. "!("#cond")", 1), \
  190. 1)) \
  191. : 0)
  192. #endif /* defined(__GNUC__) */
  193. #define IF_BUG_ONCE_VARNAME_(a) \
  194. warning_logged_on_ ## a ## __
  195. #define IF_BUG_ONCE_VARNAME__(a) \
  196. IF_BUG_ONCE_VARNAME_(a)
  197. /** This macro behaves as 'if (bug(x))', except that it only logs its
  198. * warning once, no matter how many times it triggers.
  199. */
  200. #define IF_BUG_ONCE(cond) \
  201. IF_BUG_ONCE__(ASSERT_PREDICT_UNLIKELY_(cond), \
  202. IF_BUG_ONCE_VARNAME__(__LINE__))
  203. /** Define this if you want Tor to crash when any problem comes up,
  204. * so you can get a coredump and track things down. */
  205. // #define tor_fragile_assert() tor_assert_unreached(0)
  206. #define tor_fragile_assert() tor_assert_nonfatal_unreached_once()
  207. void tor_assertion_failed_(const char *fname, unsigned int line,
  208. const char *func, const char *expr);
  209. void tor_bug_occurred_(const char *fname, unsigned int line,
  210. const char *func, const char *expr,
  211. int once);
  212. void tor_abort_(void) ATTR_NORETURN;
  213. #ifdef _WIN32
  214. #define SHORT_FILE__ (tor_fix_source_file(__FILE__))
  215. const char *tor_fix_source_file(const char *fname);
  216. #else
  217. #define SHORT_FILE__ (__FILE__)
  218. #define tor_fix_source_file(s) (s)
  219. #endif /* defined(_WIN32) */
  220. #ifdef TOR_UNIT_TESTS
  221. void tor_capture_bugs_(int n);
  222. void tor_end_capture_bugs_(void);
  223. const struct smartlist_t *tor_get_captured_bug_log_(void);
  224. void tor_set_failed_assertion_callback(void (*fn)(void));
  225. #endif /* defined(TOR_UNIT_TESTS) */
  226. #endif /* !defined(TOR_UTIL_BUG_H) */