util_bug.h 12.9 KB
Newer Older
1
2
/* Copyright (c) 2003-2004, Roger Dingledine
 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3
 * Copyright (c) 2007-2021, The Tor Project, Inc. */
4
5
6
7
/* See LICENSE for licensing information */

/**
 * \file util_bug.h
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 *
 * \brief Macros to manage assertions, fatal and non-fatal.
 *
 * Guidelines: All the different kinds of assertion in this file are for
 * bug-checking only. Don't write code that can assert based on bad inputs.
 *
 * We provide two kinds of assertion here: "fatal" and "nonfatal". Use
 * nonfatal assertions for any bug you can reasonably recover from -- and
 * please, try to recover!  Many severe bugs in Tor have been caused by using
 * a regular assertion when a nonfatal assertion would have been better.
 *
 * If you need to check a condition with a nonfatal assertion, AND recover
 * from that same condition, consider using the BUG() macro inside a
 * conditional.  For example:
 *
 * <code>
 *  // wrong -- use tor_assert_nonfatal() if you just want an assertion.
 *  BUG(ptr == NULL);
 *
 *  // okay, but needlessly verbose
 *  tor_assert_nonfatal(ptr != NULL);
 *  if (ptr == NULL) { ... }
 *
 *  // this is how we do it:
 *  if (BUG(ptr == NULL)) { ... }
 * </code>
34
35
36
37
38
39
 **/

#ifndef TOR_UTIL_BUG_H
#define TOR_UTIL_BUG_H

#include "orconfig.h"
40
#include "lib/cc/compat_compiler.h"
41
#include "lib/log/log.h"
42
#include "lib/testsupport/testsupport.h"
43
44
45
46
47
48
49
50
51
52
53
54
55
56

/* Replace assert() with a variant that sends failures to the log before
 * calling assert() normally.
 */
#ifdef NDEBUG
/* Nobody should ever want to build with NDEBUG set.  99% of our asserts will
 * be outside the critical path anyway, so it's silly to disable bug-checking
 * throughout the entire program just because a few asserts are slowing you
 * down.  Profile, optimize the critical path, and keep debugging on.
 *
 * And I'm not just saying that because some of our asserts check
 * security-critical properties.
 */
#error "Sorry; we don't support building with NDEBUG."
57
#endif /* defined(NDEBUG) */
58

59
60
61
62
63
64
65
66
67
#if defined(TOR_UNIT_TESTS) && defined(__GNUC__)
/* We define this GCC macro as a replacement for PREDICT_UNLIKELY() in this
 * header, so that in our unit test builds, we'll get compiler warnings about
 * stuff like tor_assert(n = 5).
 *
 * The key here is that (e) is wrapped in exactly one layer of parentheses,
 * and then passed right to a conditional.  If you do anything else to the
 * expression here, or introduce any more parentheses, the compiler won't
 * help you.
68
69
70
71
 *
 * We only do this for the unit-test build case because it interferes with
 * the likely-branch labeling.  Note below that in the other case, we define
 * these macros to just be synonyms for PREDICT_(UN)LIKELY.
72
73
 */
#define ASSERT_PREDICT_UNLIKELY_(e)             \
Nick Mathewson's avatar
Nick Mathewson committed
74
  ( {                                           \
75
76
77
78
79
80
    int tor__assert_tmp_value__;                \
    if (e)                                      \
      tor__assert_tmp_value__ = 1;              \
    else                                        \
      tor__assert_tmp_value__ = 0;              \
    tor__assert_tmp_value__;                    \
Nick Mathewson's avatar
Nick Mathewson committed
81
  } )
82
#define ASSERT_PREDICT_LIKELY_(e) ASSERT_PREDICT_UNLIKELY_(e)
Nick Mathewson's avatar
Nick Mathewson committed
83
#else /* !(defined(TOR_UNIT_TESTS) && defined(__GNUC__)) */
84
85
#define ASSERT_PREDICT_UNLIKELY_(e) PREDICT_UNLIKELY(e)
#define ASSERT_PREDICT_LIKELY_(e) PREDICT_LIKELY(e)
Nick Mathewson's avatar
Nick Mathewson committed
86
#endif /* defined(TOR_UNIT_TESTS) && defined(__GNUC__) */
87

88
89
90
91
92
93
94
/* Sometimes we don't want to use assertions during branch coverage tests; it
 * leads to tons of unreached branches which in reality are only assertions we
 * didn't hit. */
#if defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_TESTS)
#define tor_assert(a) STMT_BEGIN                                        \
  (void)(a);                                                            \
  STMT_END
95
96
97
98
#define tor_assertf(a, fmt, ...) STMT_BEGIN                             \
  (void)(a);                                                            \
  (void)(fmt);                                                          \
  STMT_END
99
#else /* !(defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_T...)) */
100
101
/** Like assert(3), but send assertion failures to the log as well as to
 * stderr. */
102
103
104
#define tor_assert(expr) tor_assertf(expr, NULL)

#define tor_assertf(expr, fmt, ...) STMT_BEGIN                          \
105
106
  if (ASSERT_PREDICT_LIKELY_(expr)) {                                   \
  } else {                                                              \
107
108
    tor_assertion_failed_(SHORT_FILE__, __LINE__, __func__, #expr,      \
                          fmt, ##__VA_ARGS__);                          \
109
    tor_abort_();                                                        \
110
  } STMT_END
111
#endif /* defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_TESTS) */
112

Nick Mathewson's avatar
Nick Mathewson committed
113
114
115
#define tor_assert_unreached()                                  \
  STMT_BEGIN {                                                  \
    tor_assertion_failed_(SHORT_FILE__, __LINE__, __func__,     \
116
                          "line should be unreached", NULL);    \
117
    tor_abort_();                                               \
Nick Mathewson's avatar
Nick Mathewson committed
118
  } STMT_END
119
120
121
122

/* Non-fatal bug assertions. The "unreached" variants mean "this line should
 * never be reached." The "once" variants mean "Don't log a warning more than
 * once".
123
124
125
126
127
 *
 * The 'BUG' macro checks a boolean condition and logs an error message if it
 * is true.  Example usage:
 *   if (BUG(x == NULL))
 *     return -1;
128
129
 */

130
131
132
133
#ifdef __COVERITY__
#undef BUG
// Coverity defines this in global headers; let's override it.  This is a
// magic coverity-only preprocessor thing.
134
#ifndef COCCI
135
#nodef BUG(x) (x)
136
#endif
137
#endif /* defined(__COVERITY__) */
138
139
140
141
142
143
144

#if defined(__COVERITY__) || defined(__clang_analyzer__)
// We're running with a static analysis tool: let's treat even nonfatal
// assertion failures as something that we need to avoid.
#define ALL_BUGS_ARE_FATAL
#endif

145
146
/** Define ALL_BUGS_ARE_FATAL if you want Tor to crash when any problem comes
 * up, so you can get a coredump and track things down. */
147
148
149
#ifdef ALL_BUGS_ARE_FATAL
#define tor_assert_nonfatal_unreached() tor_assert(0)
#define tor_assert_nonfatal(cond) tor_assert((cond))
150
151
#define tor_assertf_nonfatal(cond, fmt, ...)    \
  tor_assertf(cond, fmt, ##__VA_ARGS__)
152
153
#define tor_assert_nonfatal_unreached_once() tor_assert(0)
#define tor_assert_nonfatal_once(cond) tor_assert((cond))
154
#define BUG(cond)                                                       \
155
  (ASSERT_PREDICT_UNLIKELY_(cond) ?                                     \
156
   (tor_assertion_failed_(SHORT_FILE__,__LINE__,__func__,"!("#cond")",NULL), \
157
    tor_abort_(), 1)                                                    \
158
   : 0)
159
160
161
#ifndef COCCI
#define IF_BUG_ONCE(cond) if (BUG(cond))
#endif
162
163
164
#elif defined(TOR_UNIT_TESTS) && defined(DISABLE_ASSERTS_IN_UNIT_TESTS)
#define tor_assert_nonfatal_unreached() STMT_NIL
#define tor_assert_nonfatal(cond) ((void)(cond))
rl1987's avatar
rl1987 committed
165
166
167
168
#define tor_assertf_nonfatal(cond, fmt, ...) STMT_BEGIN                 \
  (void)cond;                                                           \
  (void)fmt;                                                            \
  STMT_END
169
170
#define tor_assert_nonfatal_unreached_once() STMT_NIL
#define tor_assert_nonfatal_once(cond) ((void)(cond))
171
#define BUG(cond) (ASSERT_PREDICT_UNLIKELY_(cond) ? 1 : 0)
172
173
174
#ifndef COCCI
#define IF_BUG_ONCE(cond) if (BUG(cond))
#endif
175
176
#else /* Normal case, !ALL_BUGS_ARE_FATAL, !DISABLE_ASSERTS_IN_UNIT_TESTS */
#define tor_assert_nonfatal_unreached() STMT_BEGIN                      \
rl1987's avatar
rl1987 committed
177
  tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, NULL, 0, NULL);   \
178
179
  STMT_END
#define tor_assert_nonfatal(cond) STMT_BEGIN                            \
180
181
  if (ASSERT_PREDICT_LIKELY_(cond)) {                                   \
  } else {                                                              \
rl1987's avatar
rl1987 committed
182
183
184
185
186
187
188
189
    tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, #cond, 0, NULL);\
  }                                                                     \
  STMT_END
#define tor_assertf_nonfatal(cond, fmt, ...) STMT_BEGIN                 \
  if (ASSERT_PREDICT_UNLIKELY_(cond)) {                                 \
  } else {                                                              \
    tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, #cond, 0,        \
                      fmt, ##__VA_ARGS__);                               \
190
191
192
193
194
195
  }                                                                     \
  STMT_END
#define tor_assert_nonfatal_unreached_once() STMT_BEGIN                 \
  static int warning_logged__ = 0;                                      \
  if (!warning_logged__) {                                              \
    warning_logged__ = 1;                                               \
rl1987's avatar
rl1987 committed
196
    tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, NULL, 1, NULL); \
197
198
199
200
  }                                                                     \
  STMT_END
#define tor_assert_nonfatal_once(cond) STMT_BEGIN                       \
  static int warning_logged__ = 0;                                      \
201
202
  if (ASSERT_PREDICT_LIKELY_(cond)) {                                   \
  } else if (!warning_logged__) {                                       \
203
    warning_logged__ = 1;                                               \
rl1987's avatar
rl1987 committed
204
    tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__, #cond, 1, NULL);\
205
206
  }                                                                     \
  STMT_END
207
#define BUG(cond)                                                       \
208
  (ASSERT_PREDICT_UNLIKELY_(cond) ?                                     \
209
  (tor_bug_occurred_(SHORT_FILE__,__LINE__,__func__,"!("#cond")",0,NULL),1) \
210
   : 0)
211

212
#ifndef COCCI
213
214
#ifdef __GNUC__
#define IF_BUG_ONCE__(cond,var)                                         \
215
  if (( {                                                               \
216
      static int var = 0;                                               \
217
218
      int bool_result = !!(cond);                                       \
      if (bool_result && !var) {                                        \
219
        var = 1;                                                        \
220
        tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__,             \
221
                          ("!("#cond")"), 1, NULL);                     \
222
      }                                                                 \
223
      bool_result; } ))
224
#else /* !defined(__GNUC__) */
225
226
#define IF_BUG_ONCE__(cond,var)                                         \
  static int var = 0;                                                   \
227
  if ((cond) ?                                                          \
228
229
      (var ? 1 :                                                        \
       (var=1,                                                          \
230
        tor_bug_occurred_(SHORT_FILE__, __LINE__, __func__,             \
231
                          ("!("#cond")"), 1, NULL),                     \
232
233
        1))                                                             \
      : 0)
234
#endif /* defined(__GNUC__) */
Nick Mathewson's avatar
Nick Mathewson committed
235
#endif /* !defined(COCCI) */
236

237
238
239
240
241
#define IF_BUG_ONCE_VARNAME_(a)               \
  warning_logged_on_ ## a ## __
#define IF_BUG_ONCE_VARNAME__(a)              \
  IF_BUG_ONCE_VARNAME_(a)

242
/** This macro behaves as 'if (BUG(x))', except that it only logs its
243
244
245
246
 * warning once, no matter how many times it triggers.
 */

#define IF_BUG_ONCE(cond)                                       \
247
  IF_BUG_ONCE__(ASSERT_PREDICT_UNLIKELY_(cond),                 \
248
249
                IF_BUG_ONCE_VARNAME__(__LINE__))

250
251
#endif /* defined(ALL_BUGS_ARE_FATAL) || ... */

252
253
254
255
256
257
258
259
260
/**
 * Use this macro after a nonfatal assertion, and before a case statement
 * where you would want to fall through.
 */
#ifdef ALL_BUGS_ARE_FATAL
#define FALLTHROUGH_UNLESS_ALL_BUGS_ARE_FATAL \
  abort()
#else
#define FALLTHROUGH_UNLESS_ALL_BUGS_ARE_FATAL FALLTHROUGH
261
#endif /* defined(ALL_BUGS_ARE_FATAL) */
262

263
264
265
266
267
268
269
/** In older code, we used tor_fragile_assert() to mark optional failure
 * points. At these points, we could make some debug builds fail.
 * (But release builds would continue.)
 *
 * To get the same behaviour in recent tor versions, define
 * ALL_BUGS_ARE_FATAL, and use any non-fatal assertion or *BUG() macro.
 */
270
#define tor_fragile_assert() tor_assert_nonfatal_unreached_once()
271
272

void tor_assertion_failed_(const char *fname, unsigned int line,
273
                           const char *func, const char *expr,
274
275
                           const char *fmt, ...)
    CHECK_PRINTF(5,6);
276
277
void tor_bug_occurred_(const char *fname, unsigned int line,
                       const char *func, const char *expr,
278
279
                       int once, const char *fmt, ...)
  CHECK_PRINTF(6,7);
280

281
282
void tor_abort_(void) ATTR_NORETURN;

283
284
285
286
287
288
289
290
#ifdef _WIN32
#define SHORT_FILE__ (tor_fix_source_file(__FILE__))
const char *tor_fix_source_file(const char *fname);
#else
#define SHORT_FILE__ (__FILE__)
#define tor_fix_source_file(s) (s)
#endif /* defined(_WIN32) */

291
292
293
294
#ifdef TOR_UNIT_TESTS
void tor_capture_bugs_(int n);
void tor_end_capture_bugs_(void);
const struct smartlist_t *tor_get_captured_bug_log_(void);
295
void tor_set_failed_assertion_callback(void (*fn)(void));
296
#endif /* defined(TOR_UNIT_TESTS) */
297

298
#endif /* !defined(TOR_UTIL_BUG_H) */