Add xml_escape_text_append and use it

[deliverable/binutils-gdb.git] / gdb / common / common-exceptions.h

diff --git a/gdb/common/common-exceptions.h b/gdb/common/common-exceptions.h
index 6bf7e400adaa7b1bc8988e712435c2cd69458f60..15c85e28ab56d08fdbe8a8451177ce1872d8d2c7 100644 (file)
--- a/gdb/common/common-exceptions.h
+++ b/gdb/common/common-exceptions.h
@@ -1,6 +1,6 @@
 /* Exception (throw catch) mechanism, for GDB, the GNU debugger.
 
-   Copyright (C) 1986-2016 Free Software Foundation, Inc.
+   Copyright (C) 1986-2018 Free Software Foundation, Inc.
 
    This file is part of GDB.
 
@@ -24,10 +24,8 @@
 #include <new>
 
 /* Reasons for calling throw_exceptions().  NOTE: all reason values
-   must be less than zero.  enum value 0 is reserved for internal use
-   as the return value from an initial setjmp().  The function
-   catch_exceptions() reserves values >= 0 as legal results from its
-   wrapped function.  */
+   must be different from zero.  enum value 0 is reserved for internal
+   use as the return value from an initial setjmp().  */
 
 enum return_reason
   {
@@ -87,7 +85,7 @@ enum errors {
      means the register was not saved in the frame.  */
   OPTIMIZED_OUT_ERROR,
 
-  /* DW_OP_GNU_entry_value resolving failed.  */
+  /* DW_OP_entry_value resolving failed.  */
   NO_ENTRY_VALUE_ERROR,
 
   /* Target throwing an error has been closed.  Current command should be
@@ -119,8 +117,7 @@ struct gdb_exception
 
 /* The different exception mechanisms that TRY/CATCH can map to.  */
 
-/* Make GDB exceptions use setjmp/longjmp behind the scenes.  This is
-   the only mode supported when GDB is built as a C program.  */
+/* Make GDB exceptions use setjmp/longjmp behind the scenes.  */
 #define GDB_XCPT_SJMP 1
 
 /* Make GDB exceptions use try/catch behind the scenes.  */
@@ -132,11 +129,7 @@ struct gdb_exception
    spurious code between the TRY and the CATCH block.  */
 #define GDB_XCPT_RAW_TRY 3
 
-#ifdef __cplusplus
-# define GDB_XCPT GDB_XCPT_TRY
-#else
-# define GDB_XCPT GDB_XCPT_SJMP
-#endif
+#define GDB_XCPT GDB_XCPT_TRY
 
 /* Functions to drive the sjlj-based exceptions state machine.  Though
    declared here by necessity, these functions should be considered
@@ -236,25 +229,38 @@ struct exception_try_scope
 #if GDB_XCPT == GDB_XCPT_TRY
 
 /* We still need to wrap TRY/CATCH in C++ so that cleanups and C++
-   exceptions can coexist.  The TRY blocked is wrapped in a
-   do/while(0) so that break/continue within the block works the same
-   as in C.  */
+   exceptions can coexist.
+
+   The TRY blocked is wrapped in a do/while(0) so that break/continue
+   within the block works the same as in C.
+
+   END_CATCH makes sure that even if the CATCH block doesn't want to
+   catch the exception, we stop at every frame in the unwind chain to
+   run its cleanups, which may e.g., have pointers to stack variables
+   that are going to be destroyed.
+
+   There's an outer scope around the whole TRY/END_CATCH in order to
+   cause a compilation error if you forget to add the END_CATCH at the
+   end a TRY/CATCH construct.  */
+
 #define TRY                                                            \
-  try                                                                  \
-    {                                                                  \
-      exception_try_scope exception_try_scope_instance;                        \
-      do                                                               \
-       {
+  {                                                                    \
+    try                                                                        \
+      {                                                                        \
+       exception_try_scope exception_try_scope_instance;               \
+       do                                                              \
+         {
 
 #define CATCH(EXCEPTION, MASK)                                         \
-       } while (0);                                                    \
-    }                                                                  \
-  catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
+         } while (0);                                                  \
+       }                                                               \
+    catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
 
 #define END_CATCH                              \
-  catch (...)                                  \
-  {                                            \
-    exception_rethrow ();                      \
+    catch (...)                                        \
+      {                                                \
+       exception_rethrow ();                   \
+      }                                                \
   }
 
 #else
@@ -305,18 +311,16 @@ struct gdb_quit_bad_alloc
 
 /* *INDENT-ON* */
 
-/* Throw an exception (as described by "struct gdb_exception").  When
-   GDB is built as a C program, executes a LONG JUMP to the inner most
-   containing exception handler established using TRY/CATCH.  When
-   built as a C++ program, throws a C++ exception, using "throw".  */
+/* Throw an exception (as described by "struct gdb_exception"),
+   landing in the inner most containing exception handler established
+   using TRY/CATCH.  */
 extern void throw_exception (struct gdb_exception exception)
      ATTRIBUTE_NORETURN;
 
 /* Throw an exception by executing a LONG JUMP to the inner most
-   containing exception handler established using TRY_SJLJ.  Works the
-   same regardless of whether GDB is built as a C program or a C++
-   program.  Necessary in some cases where we need to throw GDB
-   exceptions across third-party library code (e.g., readline).  */
+   containing exception handler established using TRY_SJLJ.  Necessary
+   in some cases where we need to throw GDB exceptions across
+   third-party library code (e.g., readline).  */
 extern void throw_exception_sjlj (struct gdb_exception exception)
      ATTRIBUTE_NORETURN;