epan/exceptions.h

   1 /* exceptions.h
   2  * Wireshark's exceptions.
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation; either version 2
  11  * of the License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  21  */
  22
  23 #ifndef __EXCEPTIONS_H__
  24 #define __EXCEPTIONS_H__
  25
  26 #include "except.h"
  27
  28 /* Wireshark has only one exception group, to make these macros simple */
  29 #define XCEPT_GROUP_WIRESHARK 1
  30
  31 /**
  32     Index is out of range.
  33     An attempt was made to read past the end of a buffer.
  34     This generally means that the capture was done with a "slice"
  35     length or "snapshot" length less than the maximum packet size,
  36     and a link-layer packet was cut short by that, so not all of the
  37     data in the link-layer packet was available.
  38 **/
  39 #define BoundsError             1
  40
  41 /**
  42     Index is beyond reported length (not cap_len)
  43     An attempt was made to read past the logical end of a buffer. This
  44     differs from a BoundsError in that the parent protocol established a
  45     limit past which this dissector should not process in the buffer and that
  46     limit was exceeded.
  47     This generally means that the packet is invalid, i.e. whatever
  48     code constructed the packet and put it on the wire didn't put enough
  49     data into it.  It is therefore currently reported as a "Malformed
  50     packet".
  51 **/
  52 #define ReportedBoundsError     2
  53
  54 /**
  55     Index is beyond fragment length but not reported length.
  56     This means that the packet wasn't reassembled.
  57 **/
  58 #define FragmentBoundsError     3
  59
  60 /**
  61     During dfilter parsing
  62 **/
  63 #define TypeError               4
  64
  65 /**
  66     A bug was detected in a dissector.
  67
  68     DO NOT throw this with THROW(); that means that no details about
  69     the dissector error will be reported.  (Instead, the message will
  70     blame you for not providing details.)
  71
  72     Instead, use the DISSECTOR_ASSERT(), etc. macros in epan/proto.h.
  73 **/
  74 #define DissectorError          5
  75
  76 /**
  77     Index is out of range.
  78     An attempt was made to read past the end of a buffer.
  79     This error is specific to SCSI data transfers where for some CDBs
  80     it is normal that the data PDU might be short.
  81     I.e. ReportLuns initially called with allocation_length=8, just enough
  82     to get the "size" of lun list back after which the initiator will
  83     reissue the command with an allocation_length that is big enough.
  84 **/
  85 #define ScsiBoundsError         6
  86
  87 /**
  88     Running out of memory.
  89     A dissector tried to allocate memory but that failed.
  90 **/
  91 #define OutOfMemoryError        7
  92
  93 /**
  94     The reassembly state machine was passed a bad fragment offset,
  95     or other similar issues. We used to use DissectorError in these
  96     cases, but they're not necessarily the dissector's fault - if the packet
  97     contains a bad fragment offset, the dissector shouldn't have to figure
  98     that out by itself since that's what the reassembly machine is for.
  99 **/
 100 #define ReassemblyError         8
 101
 102 /*
 103  * Catch errors that, if you're calling a subdissector and catching
 104  * exceptions from the subdissector, and possibly dissecting more
 105  * stuff after the subdissector returns or fails, mean it makes
 106  * sense to continue dissecting:
 107  *
 108  * BoundsError indicates a configuration problem (the capture was
 109  * set up to throw away data, and it did); there's no point in
 110  * trying to dissect any more data, as there's no more data to dissect.
 111  *
 112  * FragmentBoundsError indicates a configuration problem (reassembly
 113  * wasn't enabled or couldn't be done); there's no point in trying
 114  * to dissect any more data, as there's no more data to dissect.
 115  *
 116  * OutOfMemoryError indicates what its name suggests; there's no point
 117  * in trying to dissect any more data, as you're probably not going to
 118  * have any more memory to use when dissecting them.
 119  *
 120  * Other errors indicate that there's some sort of problem with
 121  * the packet; you should continue dissecting data, as it might
 122  * be OK, and, even if it's not, you should report its problem
 123  * separately.
 124  */
 125 #define CATCH_NONFATAL_ERRORS \
 126         CATCH3(ReportedBoundsError, ScsiBoundsError, ReassemblyError)
 127
 128 /*
 129  * Catch all bounds-checking errors.
 130  */
 131 #define CATCH_BOUNDS_ERRORS \
 132         CATCH4(BoundsError, FragmentBoundsError, ReportedBoundsError, \
 133                ScsiBoundsError)
 134
 135 /*
 136  * Catch all bounds-checking errors, and catch dissector bugs.
 137  * Should only be used at the top level, so that dissector bugs
 138  * go all the way to the top level and get reported immediately.
 139  */
 140 #define CATCH_BOUNDS_AND_DISSECTOR_ERRORS \
 141         CATCH6(BoundsError, FragmentBoundsError, ReportedBoundsError, \
 142                ScsiBoundsError, DissectorError, ReassemblyError)
 143
 144 /* Usage:
 145  *
 146  * TRY {
 147  *      code;
 148  * }
 149  *
 150  * CATCH(exception) {
 151  *      code;
 152  * }
 153  *
 154  * CATCH2(exception1, exception2) {
 155  *      code;
 156  * }
 157  *
 158  * CATCH3(exception1, exception2, exception3) {
 159  *      code;
 160  * }
 161  *
 162  * CATCH4(exception1, exception2, exception3, exception4) {
 163  *      code;
 164  * }
 165  *
 166  * CATCH5(exception1, exception2, exception3, exception4, exception5) {
 167  *      code;
 168  * }
 169  *
 170  * CATCH6(exception1, exception2, exception3, exception4, exception5, exception6) {
 171  *      code;
 172  * }
 173  *
 174  * CATCH_NONFATAL_ERRORS {
 175  *      code;
 176  * }
 177  *
 178  * CATCH_BOUNDS_ERRORS {
 179  *      code;
 180  * }
 181  *
 182  * CATCH_BOUNDS_AND_DISSECTOR_ERRORS {
 183  *      code;
 184  * }
 185  *
 186  * CATCH_ALL {
 187  *      code;
 188  * }
 189  *
 190  * FINALLY {
 191  *      code;
 192  * }
 193  *
 194  * ENDTRY;
 195  *
 196  * ********* Never use 'goto' or 'return' inside the TRY, CATCH*, or
 197  * ********* FINALLY blocks. Execution must proceed through ENDTRY before
 198  * ********* branching out.
 199  *
 200  * This is really something like:
 201  *
 202  * {
 203  *      caught = FALSE:
 204  *      x = setjmp();
 205  *      if (x == 0) {
 206  *              <TRY code>
 207  *      }
 208  *      if (!caught && x == 1) {
 209  *              caught = TRUE;
 210  *              <CATCH(1) code>
 211  *      }
 212  *      if (!caught && x == 2) {
 213  *              caught = TRUE;
 214  *              <CATCH(2) code>
 215  *      }
 216  *      if (!caught && (x == 3 || x == 4)) {
 217  *              caught = TRUE;
 218  *              <CATCH2(3,4) code>
 219  *      }
 220  *      if (!caught && (x == 5 || x == 6 || x == 7)) {
 221  *              caught = TRUE;
 222  *              <CATCH3(5,6,7) code>
 223  *      }
 224  *      if (!caught && x != 0) {
 225  *              caught = TRUE;
 226  *              <CATCH_ALL code>
 227  *      }
 228  *      <FINALLY code>
 229  *      if(!caught) {
 230  *              RETHROW(x)
 231  *      }
 232  * }<ENDTRY tag>
 233  *
 234  * All CATCH's must precede a CATCH_ALL.
 235  * FINALLY must occur after any CATCH or CATCH_ALL.
 236  * ENDTRY marks the end of the TRY code.
 237  * TRY and ENDTRY are the mandatory parts of a TRY block.
 238  * CATCH, CATCH_ALL, and FINALLY are all optional (although
 239  * you'll probably use at least one, otherwise why "TRY"?)
 240  *
 241  * GET_MESSAGE  returns string ptr to exception message
 242  *              when exception is thrown via THROW_MESSAGE()
 243  *
 244  * To throw/raise an exception.
 245  *
 246  * THROW(exception)
 247  * RETHROW                              rethrow the caught exception
 248  *
 249  * A cleanup callback is a function called in case an exception occurs
 250  * and is not caught. It should be used to free any dynamically-allocated data.
 251  * A pop or call_and_pop should occur at the same statement-nesting level
 252  * as the push.
 253  *
 254  * CLEANUP_CB_PUSH(func, data)
 255  * CLEANUP_CB_POP
 256  * CLEANUP_CB_CALL_AND_POP
 257  */
 258
 259 /* we do up to three passes through the bit of code after except_try_push(),
 260  * and except_state is used to keep track of where we are.
 261  */
 262 #define EXCEPT_CAUGHT   1 /* exception has been caught, no need to rethrow at
 263                            * ENDTRY */
 264
 265 #define EXCEPT_RETHROWN 2 /* the exception was rethrown from a CATCH
 266                            * block. Don't reenter the CATCH blocks, but do
 267                            * execute FINALLY and rethrow at ENDTRY */
 268
 269 #define EXCEPT_FINALLY  4 /* we've entered the FINALLY block - don't allow
 270                            * RETHROW, and don't reenter FINALLY if a
 271                            * different exception is thrown */
 272
 273 #define TRY \
 274 {\
 275         except_t *exc; \
 276         volatile int except_state = 0; \
 277         static const except_id_t catch_spec[] = { \
 278                 { XCEPT_GROUP_WIRESHARK, XCEPT_CODE_ANY } }; \
 279         except_try_push(catch_spec, 1, &exc); \
 280                                                        \
 281         if(except_state & EXCEPT_CAUGHT)               \
 282             except_state |= EXCEPT_RETHROWN;           \
 283         except_state &= ~EXCEPT_CAUGHT;                \
 284                                                        \
 285         if (except_state == 0 && exc == 0)             \
 286                 /* user's code goes here */
 287
 288 #define ENDTRY \
 289         /* rethrow the exception if necessary */ \
 290         if(!(except_state&EXCEPT_CAUGHT) && exc != 0)  \
 291             except_rethrow(exc);                 \
 292         except_try_pop();\
 293 }
 294
 295 /* the (except_state |= EXCEPT_CAUGHT) in the below is a way of setting
 296  * except_state before the user's code, without disrupting the user's code if
 297  * it's a one-liner.
 298  */
 299 #define CATCH(x) \
 300         if (except_state == 0 && exc != 0 && \
 301             exc->except_id.except_code == (x) && \
 302             (except_state |= EXCEPT_CAUGHT)) \
 303                 /* user's code goes here */
 304
 305 #define CATCH2(x,y) \
 306         if (except_state == 0 && exc != 0 && \
 307             (exc->except_id.except_code == (x) || \
 308              exc->except_id.except_code == (y)) && \
 309             (except_state|=EXCEPT_CAUGHT)) \
 310                 /* user's code goes here */
 311
 312 #define CATCH3(x,y,z) \
 313         if (except_state == 0 && exc != 0 && \
 314             (exc->except_id.except_code == (x) || \
 315              exc->except_id.except_code == (y) || \
 316              exc->except_id.except_code == (z)) && \
 317             (except_state|=EXCEPT_CAUGHT)) \
 318                 /* user's code goes here */
 319
 320 #define CATCH4(w,x,y,z) \
 321         if (except_state == 0 && exc != 0 && \
 322             (exc->except_id.except_code == (w) || \
 323              exc->except_id.except_code == (x) || \
 324              exc->except_id.except_code == (y) || \
 325              exc->except_id.except_code == (z)) && \
 326             (except_state|=EXCEPT_CAUGHT)) \
 327                 /* user's code goes here */
 328
 329 #define CATCH5(v,w,x,y,z) \
 330         if (except_state == 0 && exc != 0 && \
 331             (exc->except_id.except_code == (v) || \
 332              exc->except_id.except_code == (w) || \
 333              exc->except_id.except_code == (x) || \
 334              exc->except_id.except_code == (y) || \
 335              exc->except_id.except_code == (z)) && \
 336             (except_state|=EXCEPT_CAUGHT)) \
 337                 /* user's code goes here */
 338
 339 #define CATCH6(u,v,w,x,y,z) \
 340         if (except_state == 0 && exc != 0 && \
 341             (exc->except_id.except_code == (u) || \
 342              exc->except_id.except_code == (v) || \
 343              exc->except_id.except_code == (w) || \
 344              exc->except_id.except_code == (x) || \
 345              exc->except_id.except_code == (y) || \
 346              exc->except_id.except_code == (z)) && \
 347             (except_state|=EXCEPT_CAUGHT)) \
 348                 /* user's code goes here */
 349
 350 #define CATCH_ALL \
 351         if (except_state == 0 && exc != 0 && \
 352             (except_state|=EXCEPT_CAUGHT)) \
 353                 /* user's code goes here */
 354
 355 #define FINALLY \
 356         if( !(except_state & EXCEPT_FINALLY) && (except_state|=EXCEPT_FINALLY)) \
 357                 /* user's code goes here */
 358
 359 #define THROW(x) \
 360         except_throw(XCEPT_GROUP_WIRESHARK, (x), NULL)
 361
 362 #define THROW_ON(cond, x) G_STMT_START { \
 363         if ((cond)) \
 364                 except_throw(XCEPT_GROUP_WIRESHARK, (x), NULL); \
 365 } G_STMT_END
 366
 367 #define THROW_MESSAGE(x, y) \
 368         except_throw(XCEPT_GROUP_WIRESHARK, (x), (y))
 369
 370 #define THROW_MESSAGE_ON(cond, x, y) G_STMT_START { \
 371         if ((cond)) \
 372                 except_throw(XCEPT_GROUP_WIRESHARK, (x), (y)); \
 373 } G_STMT_END
 374
 375 /* Throws a formatted message, its memory is cleared after catching it. */
 376 #define THROW_FORMATTED(x, ...) \
 377         except_throwf(XCEPT_GROUP_WIRESHARK, (x), __VA_ARGS__)
 378
 379 #define GET_MESSAGE                     except_message(exc)
 380
 381 #define RETHROW                                     \
 382     {                                               \
 383         /* check we're in a catch block */          \
 384         g_assert(except_state == EXCEPT_CAUGHT);    \
 385         /* we can't use except_rethrow here, as that pops a catch block \
 386          * off the stack, and we don't want to do that, because we want to \
 387          * excecute the FINALLY {} block first.     \
 388          * except_throw doesn't provide an interface to rethrow an existing \
 389          * exception; however, longjmping back to except_try_push() has the \
 390          * desired effect.                          \
 391          *                                          \
 392          * Note also that THROW and RETHROW should provide much the same \
 393          * functionality in terms of which blocks to enter, so any messing \
 394          * about with except_state in here would indicate that THROW is \
 395          * doing the wrong thing.                   \
 396          */                                         \
 397         longjmp(except_ch.except_jmp,1);            \
 398     }
 399
 400 #define EXCEPT_CODE                     except_code(exc)
 401
 402 /* Register cleanup functions in case an exception is thrown and not caught.
 403  * From the Kazlib documentation, with modifications for use with the
 404  * Wireshark-specific macros:
 405  *
 406  * CLEANUP_PUSH(func, arg)
 407  *
 408  *  The call to CLEANUP_PUSH shall be matched with a call to
 409  *  CLEANUP_CALL_AND_POP or CLEANUP_POP which must occur in the same
 410  *  statement block at the same level of nesting. This requirement allows
 411  *  an implementation to provide a CLEANUP_PUSH macro which opens up a
 412  *  statement block and a CLEANUP_POP which closes the statement block.
 413  *  The space for the registered pointers can then be efficiently
 414  *  allocated from automatic storage.
 415  *
 416  *  The CLEANUP_PUSH macro registers a cleanup handler that will be
 417  *  called if an exception subsequently occurs before the matching
 418  *  CLEANUP_[CALL_AND_]POP is executed, and is not intercepted and
 419  *  handled by a try-catch region that is nested between the two.
 420  *
 421  *  The first argument to CLEANUP_PUSH is a pointer to the cleanup
 422  *  handler, a function that returns nothing and takes a single
 423  *  argument of type void*. The second argument is a void* value that
 424  *  is registered along with the handler.  This value is what is passed
 425  *  to the registered handler, should it be called.
 426  *
 427  *  Cleanup handlers are called in the reverse order of their nesting:
 428  *  inner handlers are called before outer handlers.
 429  *
 430  *  The program shall not leave the cleanup region between
 431  *  the call to the macro CLEANUP_PUSH and the matching call to
 432  *  CLEANUP_[CALL_AND_]POP by means other than throwing an exception,
 433  *  or calling CLEANUP_[CALL_AND_]POP.
 434  *
 435  *  Within the call to the cleanup handler, it is possible that new
 436  *  exceptions may happen.  Such exceptions must be handled before the
 437  *  cleanup handler terminates. If the call to the cleanup handler is
 438  *  terminated by an exception, the behavior is undefined. The exception
 439  *  which triggered the cleanup is not yet caught; thus the program
 440  *  would be effectively trying to replace an exception with one that
 441  *  isn't in a well-defined state.
 442  *
 443  *
 444  * CLEANUP_POP and CLEANUP_CALL_AND_POP
 445  *
 446  *  A call to the CLEANUP_POP or CLEANUP_CALL_AND_POP macro shall match
 447  *  each call to CLEANUP_PUSH which shall be in the same statement block
 448  *  at the same nesting level.  It shall match the most recent such a
 449  *  call that is not matched by a previous CLEANUP_[CALL_AND_]POP at
 450  *  the same level.
 451  *
 452  *  These macros causes the registered cleanup handler to be removed. If
 453  *  CLEANUP_CALL_AND_POP is called, the cleanup handler is called.
 454  *  In that case, the registered context pointer is passed to the cleanup
 455  *  handler. If CLEANUP_POP is called, the cleanup handler is not called.
 456  *
 457  *  The program shall not leave the region between the call to the
 458  *  macro CLEANUP_PUSH and the matching call to CLEANUP_[CALL_AND_]POP
 459  *  other than by throwing an exception, or by executing the
 460  *  CLEANUP_CALL_AND_POP.
 461  *
 462  */
 463
 464
 465 #define CLEANUP_PUSH(f,a)               except_cleanup_push((f),(a))
 466 #define CLEANUP_POP                     except_cleanup_pop(0)
 467 #define CLEANUP_CALL_AND_POP            except_cleanup_pop(1)
 468
 469 /* Variants to allow nesting of except_cleanup_push w/o "shadowing" variables */
 470 #define CLEANUP_PUSH_PFX(pfx,f,a)       except_cleanup_push_pfx(pfx,(f),(a))
 471 #define CLEANUP_POP_PFX(pfx)            except_cleanup_pop_pfx(pfx,0)
 472 #define CLEANUP_CALL_AND_POP_PFX(pfx)   except_cleanup_pop_pfx(pfx,1)
 473
 474
 475
 476 #endif /* __EXCEPTIONS_H__ */