epan/exceptions.h

   1 #ifndef __EXCEPTIONS_H__
   2 #define __EXCEPTIONS_H__
   3
   4 #ifndef XCEPT_H
   5 #include "except.h"
   6 #endif
   7
   8 /* Wireshark has only one exception group, to make these macros simple */
   9 #define XCEPT_GROUP_WIRESHARK 1
  10
  11 /* Wireshark's exceptions */
  12
  13 /**
  14     Index is out of range.
  15     An attempt was made to read past the end of a buffer.
  16     This generally means that the capture was done with a "slice"
  17     length or "snapshot" length less than the maximum packet size,
  18     and a link-layer packet was cut short by that, so not all of the
  19     data in the link-layer packet was available.
  20 **/
  21 #define BoundsError             1
  22
  23 /**
  24     Index is beyond reported length (not cap_len)
  25     An attempt was made to read past the logical end of a buffer. This
  26     differs from a BoundsError in that the parent protocol established a
  27     limit past which this dissector should not process in the buffer and that
  28     limit was execeeded.
  29     This generally means that the packet is invalid, i.e. whatever
  30     code constructed the packet and put it on the wire didn't put enough
  31     data into it.  It is therefore currently reported as a "Malformed
  32     packet".
  33     However, it also happens in some cases where the packet was fragmented
  34     and the fragments weren't reassembled.  We need to add another length
  35     field to a tvbuff, so that "length of the packet from the link layer"
  36     and "length of the packet were it fully reassembled" are different,
  37     and going past the first of those without going past the second would
  38     throw a different exception, which would be reported as an "Unreassembled
  39     packet" rather than a "Malformed packet".
  40 **/
  41 #define ReportedBoundsError     2
  42
  43 /**
  44     During dfilter parsing
  45 **/
  46 #define TypeError               3
  47
  48 /**
  49     A bug was detected in a dissector.
  50
  51     DO NOT throw this with THROW(); that means that no details about
  52     the dissector error will be reported.  (Instead, the message will
  53     blame you for not providing details.)
  54
  55     Instead, use the DISSECTOR_ASSERT(), etc. macros in epan/proto.h.
  56 **/
  57 #define DissectorError          4
  58
  59 /**
  60     Index is out of range.
  61     An attempt was made to read past the end of a buffer.
  62     This error is specific to SCSI data transfers where for some CDBs
  63     it is normal that the data PDU might be short.
  64     I.e. ReportLuns initially called with allocation_length=8, just enough
  65     to get the "size" of lun list back after which the initiator will
  66     reissue the command with an allocation_length that is big enough.
  67 **/
  68 #define ScsiBoundsError         5
  69
  70
  71 /* Usage:
  72  *
  73  * TRY {
  74  *      code;
  75  * }
  76  *
  77  * CATCH(exception) {
  78  *      code;
  79  * }
  80  *
  81  * CATCH2(exception1, exception2) {
  82  *      code;
  83  * }
  84  *
  85  * CATCH_ALL {
  86  *      code;
  87  * }
  88  *
  89  * FINALLY {
  90  *      code;
  91  * }
  92  *
  93  * ENDTRY;
  94  *
  95  * ********* Never use 'goto' or 'return' inside the TRY, CATCH, CATCH_ALL,
  96  * ********* or FINALLY blocks. Execution must proceed through ENDTRY before
  97  * ********* branching out.
  98  *
  99  * This is really something like:
 100  *
 101  * {
 102  *      caught = FALSE:
 103  *      x = setjmp();
 104  *      if (x == 0) {
 105  *              <TRY code>
 106  *      }
 107  *      if (!caught && x == 1) {
 108  *              caught = TRUE;
 109  *              <CATCH(1) code>
 110  *      }
 111  *      if (!caught && x == 2) {
 112  *              caught = TRUE;
 113  *              <CATCH(2) code>
 114  *      }
 115  *      if (!caught && (x == 3 || x == 4)) {
 116  *              caught = TRUE;
 117  *              <CATCH2(3,4) code>
 118  *      }
 119  *      if (!caught && x != 0) {
 120  *              caught = TRUE;
 121  *              <CATCH_ALL code>
 122  *      }
 123  *      <FINALLY code>
 124  *      if(!caught) {
 125  *              RETHROW(x)
 126  *      }
 127  * }<ENDTRY tag>
 128  *
 129  * All CATCH's must precede a CATCH_ALL.
 130  * FINALLY must occur after any CATCH or CATCH_ALL.
 131  * ENDTRY marks the end of the TRY code.
 132  * TRY and ENDTRY are the mandatory parts of a TRY block.
 133  * CATCH, CATCH_ALL, and FINALLY are all optional (although
 134  * you'll probably use at least one, otherwise why "TRY"?)
 135  *
 136  * GET_MESSAGE  returns string ptr to exception message
 137  *              when exception is thrown via THROW_MESSAGE()
 138  *
 139  * To throw/raise an exception.
 140  *
 141  * THROW(exception)
 142  * RETHROW                              rethrow the caught exception
 143  *
 144  * A cleanup callback is a function called in case an exception occurs
 145  * and is not caught. It should be used to free any dynamically-allocated data.
 146  * A pop or call_and_pop should occur at the same statement-nesting level
 147  * as the push.
 148  *
 149  * CLEANUP_CB_PUSH(func, data)
 150  * CLEANUP_CB_POP
 151  * CLEANUP_CB_CALL_AND_POP
 152  */
 153
 154 /* we do up to three passes through the bit of code after except_try_push(),
 155  * and except_state is used to keep track of where we are.
 156  */
 157 #define EXCEPT_CAUGHT   1 /* exception has been caught, no need to rethrow at
 158                            * END_TRY */
 159
 160 #define EXCEPT_RETHROWN 2 /* the exception was rethrown from a CATCH
 161                            * block. Don't reenter the CATCH blocks, but do
 162                            * execute FINALLY and rethrow at END_TRY */
 163
 164 #define EXCEPT_FINALLY  4 /* we've entered the FINALLY block - don't allow
 165                            * RETHROW, and don't reenter FINALLY if a
 166                            * different exception is thrown */
 167
 168 #define TRY \
 169 {\
 170         except_t *exc; \
 171         volatile int except_state = 0; \
 172         static const except_id_t catch_spec[] = { \
 173                 { XCEPT_GROUP_WIRESHARK, XCEPT_CODE_ANY } }; \
 174         except_try_push(catch_spec, 1, &exc); \
 175                                                        \
 176         if(except_state & EXCEPT_CAUGHT)               \
 177             except_state |= EXCEPT_RETHROWN;           \
 178         except_state &= ~EXCEPT_CAUGHT;                \
 179                                                        \
 180         if (except_state == 0 && exc == 0)             \
 181                 /* user's code goes here */
 182
 183 #define ENDTRY \
 184         /* rethrow the exception if necessary */ \
 185         if(!(except_state&EXCEPT_CAUGHT) && exc != 0)  \
 186             except_rethrow(exc);                 \
 187         except_try_pop();\
 188 }
 189
 190 /* the (except_state |= EXCEPT_CAUGHT) in the below is a way of setting
 191  * except_state before the user's code, without disrupting the user's code if
 192  * it's a one-liner.
 193  */
 194 #define CATCH(x) \
 195         if (except_state == 0 && exc != 0 && exc->except_id.except_code == (x) && \
 196             (except_state |= EXCEPT_CAUGHT))                                      \
 197                 /* user's code goes here */
 198
 199 #define CATCH2(x,y) \
 200         if (except_state == 0 && exc != 0 && \
 201             (exc->except_id.except_code == (x) || exc->except_id.except_code == (y)) && \
 202             (except_state|=EXCEPT_CAUGHT))                                             \
 203                 /* user's code goes here */
 204
 205 #define CATCH_ALL \
 206         if (except_state == 0 && exc != 0 && \
 207             (except_state|=EXCEPT_CAUGHT))                                             \
 208                 /* user's code goes here */
 209
 210
 211 #define FINALLY \
 212         if( !(except_state & EXCEPT_FINALLY) && (except_state|=EXCEPT_FINALLY)) \
 213                 /* user's code goes here */
 214
 215 #define THROW(x) \
 216         except_throw(XCEPT_GROUP_WIRESHARK, (x), NULL)
 217
 218 #define THROW_MESSAGE(x, y) \
 219         except_throw(XCEPT_GROUP_WIRESHARK, (x), (y))
 220
 221 #define GET_MESSAGE                     except_message(exc)
 222
 223 #define RETHROW                                     \
 224     {                                               \
 225         /* check we're in a catch block */          \
 226         g_assert(except_state == EXCEPT_CAUGHT);    \
 227         /* we can't use except_rethrow here, as that pops a catch block \
 228          * off the stack, and we don't want to do that, because we want to \
 229          * excecute the FINALLY {} block first.     \
 230          * except_throw doesn't provide an interface to rethrow an existing \
 231          * exception; however, longjmping back to except_try_push() has the \
 232          * desired effect.                          \
 233          *                                          \
 234          * Note also that THROW and RETHROW should provide much the same \
 235          * functionality in terms of which blocks to enter, so any messing \
 236          * about with except_state in here would indicate that THROW is \
 237          * doing the wrong thing.                   \
 238          */                                         \
 239         longjmp(except_ch.except_jmp,1);            \
 240     }
 241
 242 #define EXCEPT_CODE                     except_code(exc)
 243
 244 /* Register cleanup functions in case an exception is thrown and not caught.
 245  * From the Kazlib documentation, with modifications for use with the
 246  * Wireshark-specific macros:
 247  *
 248  * CLEANUP_PUSH(func, arg)
 249  *
 250  *  The call to CLEANUP_PUSH shall be matched with a call to
 251  *  CLEANUP_CALL_AND_POP or CLEANUP_POP which must occur in the same
 252  *  statement block at the same level of nesting. This requirement allows
 253  *  an implementation to provide a CLEANUP_PUSH macro which opens up a
 254  *  statement block and a CLEANUP_POP which closes the statement block.
 255  *  The space for the registered pointers can then be efficiently
 256  *  allocated from automatic storage.
 257  *
 258  *  The CLEANUP_PUSH macro registers a cleanup handler that will be
 259  *  called if an exception subsequently occurs before the matching
 260  *  CLEANUP_[CALL_AND_]POP is executed, and is not intercepted and
 261  *  handled by a try-catch region that is nested between the two.
 262  *
 263  *  The first argument to CLEANUP_PUSH is a pointer to the cleanup
 264  *  handler, a function that returns nothing and takes a single
 265  *  argument of type void*. The second argument is a void* value that
 266  *  is registered along with the handler.  This value is what is passed
 267  *  to the registered handler, should it be called.
 268  *
 269  *  Cleanup handlers are called in the reverse order of their nesting:
 270  *  inner handlers are called before outer handlers.
 271  *
 272  *  The program shall not leave the cleanup region between
 273  *  the call to the macro CLEANUP_PUSH and the matching call to
 274  *  CLEANUP_[CALL_AND_]POP by means other than throwing an exception,
 275  *  or calling CLEANUP_[CALL_AND_]POP.
 276  *
 277  *  Within the call to the cleanup handler, it is possible that new
 278  *  exceptions may happen.  Such exceptions must be handled before the
 279  *  cleanup handler terminates. If the call to the cleanup handler is
 280  *  terminated by an exception, the behavior is undefined. The exception
 281  *  which triggered the cleanup is not yet caught; thus the program
 282  *  would be effectively trying to replace an exception with one that
 283  *  isn't in a well-defined state.
 284  *
 285  *
 286  * CLEANUP_POP and CLEANUP_CALL_AND_POP
 287  *
 288  *  A call to the CLEANUP_POP or CLEANUP_CALL_AND_POP macro shall match
 289  *  each call to CLEANUP_PUSH which shall be in the same statement block
 290  *  at the same nesting level.  It shall match the most recent such a
 291  *  call that is not matched by a previous CLEANUP_[CALL_AND_]POP at
 292  *  the same level.
 293  *
 294  *  These macros causes the registered cleanup handler to be removed. If
 295  *  CLEANUP_CALL_AND_POP is called, the cleanup handler is called.
 296  *  In that case, the registered context pointer is passed to the cleanup
 297  *  handler. If CLEANUP_POP is called, the cleanup handler is not called.
 298  *
 299  *  The program shall not leave the region between the call to the
 300  *  macro CLEANUP_PUSH and the matching call to CLEANUP_[CALL_AND_]POP
 301  *  other than by throwing an exception, or by executing the
 302  *  CLEANUP_CALL_AND_POP.
 303  *
 304  */
 305
 306
 307 #define CLEANUP_PUSH(f,a)               except_cleanup_push((f),(a))
 308 #define CLEANUP_POP                     except_cleanup_pop(0)
 309 #define CLEANUP_CALL_AND_POP            except_cleanup_pop(1)
 310
 311 #endif /* __EXCEPTIONS_H__ */