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

/* Exception (throw catch) mechanism, for GDB, the GNU debugger.

   Copyright (C) 1986-2016 Free Software Foundation, Inc.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#ifndef COMMON_EXCEPTIONS_H
#define COMMON_EXCEPTIONS_H

#include <setjmp.h>

/* 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.  */

enum return_reason
  {
    /* User interrupt.  */
    RETURN_QUIT = -2,
    /* Any other error.  */
    RETURN_ERROR
  };

#define RETURN_MASK(reason)	(1 << (int)(-reason))

typedef enum
{
  RETURN_MASK_QUIT = RETURN_MASK (RETURN_QUIT),
  RETURN_MASK_ERROR = RETURN_MASK (RETURN_ERROR),
  RETURN_MASK_ALL = (RETURN_MASK_QUIT | RETURN_MASK_ERROR)
} return_mask;

/* Describe all exceptions.  */

enum errors {
  GDB_NO_ERROR,

  /* Any generic error, the corresponding text is in
     exception.message.  */
  GENERIC_ERROR,

  /* Something requested was not found.  */
  NOT_FOUND_ERROR,

  /* Thread library lacks support necessary for finding thread local
     storage.  */
  TLS_NO_LIBRARY_SUPPORT_ERROR,

  /* Load module not found while attempting to find thread local storage.  */
  TLS_LOAD_MODULE_NOT_FOUND_ERROR,

  /* Thread local storage has not been allocated yet.  */
  TLS_NOT_ALLOCATED_YET_ERROR,

  /* Something else went wrong while attempting to find thread local
     storage.  The ``struct gdb_exception'' message field provides
     more detail.  */
  TLS_GENERIC_ERROR,

  /* Problem parsing an XML document.  */
  XML_PARSE_ERROR,

  /* Error accessing memory.  */
  MEMORY_ERROR,

  /* Value not available.  E.g., a register was not collected in a
     traceframe.  */
  NOT_AVAILABLE_ERROR,

  /* Value was optimized out.  Note: if the value was a register, this
     means the register was not saved in the frame.  */
  OPTIMIZED_OUT_ERROR,

  /* DW_OP_GNU_entry_value resolving failed.  */
  NO_ENTRY_VALUE_ERROR,

  /* Target throwing an error has been closed.  Current command should be
     aborted as the inferior state is no longer valid.  */
  TARGET_CLOSE_ERROR,

  /* An undefined command was executed.  */
  UNDEFINED_COMMAND_ERROR,

  /* Requested feature, method, mechanism, etc. is not supported.  */
  NOT_SUPPORTED_ERROR,

  /* The number of candidates generated during line completion has
     reached the user's specified limit.  This isn't an error, this exception
     is used to halt searching for more completions, but for consistency
     "_ERROR" is appended to the name.  */
  MAX_COMPLETIONS_REACHED_ERROR,

  /* Add more errors here.  */
  NR_ERRORS
};

struct gdb_exception
{
  enum return_reason reason;
  enum errors error;
  const char *message;
};

/* 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.  */
#define GDB_XCPT_SJMP 1

/* Make GDB exceptions use try/catch behind the scenes.  */
#define GDB_XCPT_TRY 2

/* Specify this mode to build with TRY/CATCH mapped directly to raw
   try/catch.  GDB won't work correctly, but building that way catches
   code tryin to break/continue out of the try block, along with
   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

/* Functions to drive the sjlj-based exceptions state machine.  Though
   declared here by necessity, these functions should be considered
   internal to the exceptions subsystem and not used other than via
   the TRY/CATCH (or TRY_SJLJ/CATCH_SJLJ) macros defined below.  */

extern jmp_buf *exceptions_state_mc_init (void);
extern int exceptions_state_mc_action_iter (void);
extern int exceptions_state_mc_action_iter_1 (void);
extern int exceptions_state_mc_catch (struct gdb_exception *, int);

/* Same, but for the C++ try/catch-based TRY/CATCH mechanism.  */

#if GDB_XCPT != GDB_XCPT_SJMP
extern void *exception_try_scope_entry (void);
extern void exception_try_scope_exit (void *saved_state);
extern void exception_rethrow (void);
#endif

/* Macro to wrap up standard try/catch behavior.

   The double loop lets us correctly handle code "break"ing out of the
   try catch block.  (It works as the "break" only exits the inner
   "while" loop, the outer for loop detects this handling it
   correctly.)  Of course "return" and "goto" are not so lucky.

   For instance:

   *INDENT-OFF*

   TRY
     {
     }
   CATCH (e, RETURN_MASK_ERROR)
     {
       switch (e.reason)
         {
           case RETURN_ERROR: ...
         }
     }
   END_CATCH

  Note that the SJLJ version of the macros are actually named
  TRY_SJLJ/CATCH_SJLJ in order to make it possible to call them even
  when TRY/CATCH are mapped to C++ try/catch.  The SJLJ variants are
  needed in some cases where gdb exceptions need to cross third-party
  library code compiled without exceptions support (e.g.,
  readline).  */

#define TRY_SJLJ \
     { \
       jmp_buf *buf = \
	 exceptions_state_mc_init (); \
       setjmp (*buf); \
     } \
     while (exceptions_state_mc_action_iter ()) \
       while (exceptions_state_mc_action_iter_1 ())

#define CATCH_SJLJ(EXCEPTION, MASK)				\
  {							\
    struct gdb_exception EXCEPTION;				\
    if (exceptions_state_mc_catch (&(EXCEPTION), MASK))

#define END_CATCH_SJLJ				\
  }

#if GDB_XCPT == GDB_XCPT_SJMP

/* If using SJLJ-based exceptions for all exceptions, then provide
   standard aliases.  */

#define TRY TRY_SJLJ
#define CATCH CATCH_SJLJ
#define END_CATCH END_CATCH_SJLJ

#endif /* GDB_XCPT_SJMP */

#if GDB_XCPT == GDB_XCPT_TRY || GDB_XCPT == GDB_XCPT_RAW_TRY

/* Prevent error/quit during TRY from calling cleanups established
   prior to here.  This pops out the scope in either case of normal
   exit or exception exit.  */
struct exception_try_scope
{
  exception_try_scope ()
  {
    saved_state = exception_try_scope_entry ();
  }
  ~exception_try_scope ()
  {
    exception_try_scope_exit (saved_state);
  }

  void *saved_state;
};

#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.  */
#define TRY								\
  try									\
    {									\
      exception_try_scope exception_try_scope_instance;			\
      do								\
	{

#define CATCH(EXCEPTION, MASK)						\
	} while (0);							\
    }								        \
  catch (struct gdb_exception ## _ ## MASK &EXCEPTION)

#define END_CATCH				\
  catch (...)					\
  {						\
    exception_rethrow ();			\
  }

#else

#define TRY try
#define CATCH(EXCEPTION, MASK) \
  catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
#define END_CATCH

#endif

/* The exception types client code may catch.  They're just shims
   around gdb_exception that add nothing but type info.  Which is used
   is selected depending on the MASK argument passed to CATCH.  */

struct gdb_exception_RETURN_MASK_ALL : public gdb_exception
{
};

struct gdb_exception_RETURN_MASK_ERROR : public gdb_exception_RETURN_MASK_ALL
{
};

struct gdb_exception_RETURN_MASK_QUIT : public gdb_exception_RETURN_MASK_ALL
{
};

#endif /* GDB_XCPT_TRY || GDB_XCPT_RAW_TRY */

/* *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".  */
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).  */
extern void throw_exception_sjlj (struct gdb_exception exception)
     ATTRIBUTE_NORETURN;

/* Convenience wrappers around throw_exception that throw GDB
   errors.  */
extern void throw_verror (enum errors, const char *fmt, va_list ap)
     ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0);
extern void throw_vquit (const char *fmt, va_list ap)
     ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0);
extern void throw_error (enum errors error, const char *fmt, ...)
     ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3);
extern void throw_quit (const char *fmt, ...)
     ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2);

/* A pre-defined non-exception.  */
extern const struct gdb_exception exception_none;

#endif /* COMMON_EXCEPTIONS_H */
Commit	Line	Data
ff55e1b5 GB	1	/* Exception (throw catch) mechanism, for GDB, the GNU debugger.
ff55e1b5 GB	2
618f726f	3	Copyright (C) 1986-2016 Free Software Foundation, Inc.
ff55e1b5 GB	4
	5	This file is part of GDB.
	6
	7	This program is free software; you can redistribute it and/or modify
	8	it under the terms of the GNU General Public License as published by
	9	the Free Software Foundation; either version 3 of the License, or
	10	(at your option) any later version.
	11
	12	This program is distributed in the hope that it will be useful,
	13	but WITHOUT ANY WARRANTY; without even the implied warranty of
	14	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	15	GNU General Public License for more details.
	16
	17	You should have received a copy of the GNU General Public License
	18	along with this program. If not, see <http://www.gnu.org/licenses/>. */
	19
	20	#ifndef COMMON_EXCEPTIONS_H
	21	#define COMMON_EXCEPTIONS_H
	22
173981bc	23	#include <setjmp.h>
ff55e1b5 GB	24
	25	/* Reasons for calling throw_exceptions(). NOTE: all reason values
	26	must be less than zero. enum value 0 is reserved for internal use
	27	as the return value from an initial setjmp(). The function
	28	catch_exceptions() reserves values >= 0 as legal results from its
	29	wrapped function. */
	30
	31	enum return_reason
	32	{
	33	/* User interrupt. */
	34	RETURN_QUIT = -2,
	35	/* Any other error. */
	36	RETURN_ERROR
	37	};
	38
	39	#define RETURN_MASK(reason) (1 << (int)(-reason))
	40
	41	typedef enum
	42	{
	43	RETURN_MASK_QUIT = RETURN_MASK (RETURN_QUIT),
	44	RETURN_MASK_ERROR = RETURN_MASK (RETURN_ERROR),
	45	RETURN_MASK_ALL = (RETURN_MASK_QUIT \| RETURN_MASK_ERROR)
	46	} return_mask;
	47
	48	/* Describe all exceptions. */
	49
	50	enum errors {
	51	GDB_NO_ERROR,
	52
	53	/* Any generic error, the corresponding text is in
	54	exception.message. */
	55	GENERIC_ERROR,
	56
	57	/* Something requested was not found. */
	58	NOT_FOUND_ERROR,
	59
	60	/* Thread library lacks support necessary for finding thread local
	61	storage. */
	62	TLS_NO_LIBRARY_SUPPORT_ERROR,
	63
	64	/* Load module not found while attempting to find thread local storage. */
	65	TLS_LOAD_MODULE_NOT_FOUND_ERROR,
	66
	67	/* Thread local storage has not been allocated yet. */
	68	TLS_NOT_ALLOCATED_YET_ERROR,
	69
	70	/* Something else went wrong while attempting to find thread local
	71	storage. The ``struct gdb_exception'' message field provides
	72	more detail. */
	73	TLS_GENERIC_ERROR,
	74
	75	/* Problem parsing an XML document. */
	76	XML_PARSE_ERROR,
	77
	78	/* Error accessing memory. */
	79	MEMORY_ERROR,
	80
	81	/* Value not available. E.g., a register was not collected in a
	82	traceframe. */
	83	NOT_AVAILABLE_ERROR,
	84
	85	/* Value was optimized out. Note: if the value was a register, this
	86	means the register was not saved in the frame. */
	87	OPTIMIZED_OUT_ERROR,
88
89	/* DW_OP_GNU_entry_value resolving failed. */
90	NO_ENTRY_VALUE_ERROR,
91
92	/* Target throwing an error has been closed. Current command should be
93	aborted as the inferior state is no longer valid. */
94	TARGET_CLOSE_ERROR,
95
96	/* An undefined command was executed. */
97	UNDEFINED_COMMAND_ERROR,
98
99	/* Requested feature, method, mechanism, etc. is not supported. */
100	NOT_SUPPORTED_ERROR,
101
ef0b411a GB	102	/* The number of candidates generated during line completion has
	103	reached the user's specified limit. This isn't an error, this exception
	104	is used to halt searching for more completions, but for consistency
	105	"_ERROR" is appended to the name. */
	106	MAX_COMPLETIONS_REACHED_ERROR,
	107
ff55e1b5 GB	108	/* Add more errors here. */
	109	NR_ERRORS
	110	};
	111
	112	struct gdb_exception
	113	{
	114	enum return_reason reason;
	115	enum errors error;
	116	const char *message;
	117	};
	118
eec461d0 PA	119	/* The different exception mechanisms that TRY/CATCH can map to. */
	120
	121	/* Make GDB exceptions use setjmp/longjmp behind the scenes. This is
	122	the only mode supported when GDB is built as a C program. */
	123	#define GDB_XCPT_SJMP 1
	124
6290672f	125	/* Make GDB exceptions use try/catch behind the scenes. */
eec461d0 PA	126	#define GDB_XCPT_TRY 2
	127
	128	/* Specify this mode to build with TRY/CATCH mapped directly to raw
	129	try/catch. GDB won't work correctly, but building that way catches
	130	code tryin to break/continue out of the try block, along with
	131	spurious code between the TRY and the CATCH block. */
	132	#define GDB_XCPT_RAW_TRY 3
	133
6290672f PA	134	#ifdef __cplusplus
	135	# define GDB_XCPT GDB_XCPT_TRY
	136	#else
	137	# define GDB_XCPT GDB_XCPT_SJMP
	138	#endif
eec461d0	139
89525768 PA	140	/* Functions to drive the sjlj-based exceptions state machine. Though
	141	declared here by necessity, these functions should be considered
	142	internal to the exceptions subsystem and not used other than via
	143	the TRY/CATCH (or TRY_SJLJ/CATCH_SJLJ) macros defined below. */
ff55e1b5	144
173981bc	145	extern jmp_buf *exceptions_state_mc_init (void);
ff55e1b5 GB	146	extern int exceptions_state_mc_action_iter (void);
ff55e1b5 GB	147	extern int exceptions_state_mc_action_iter_1 (void);
492d29ea	148	extern int exceptions_state_mc_catch (struct gdb_exception *, int);
89525768 PA	149
	150	/* Same, but for the C++ try/catch-based TRY/CATCH mechanism. */
	151
	152	#if GDB_XCPT != GDB_XCPT_SJMP
72df25b2 PA	153	extern void *exception_try_scope_entry (void);
	154	extern void exception_try_scope_exit (void *saved_state);
	155	extern void exception_rethrow (void);
	156	#endif
ff55e1b5 GB	157
	158	/* Macro to wrap up standard try/catch behavior.
	159
	160	The double loop lets us correctly handle code "break"ing out of the
	161	try catch block. (It works as the "break" only exits the inner
	162	"while" loop, the outer for loop detects this handling it
	163	correctly.) Of course "return" and "goto" are not so lucky.
	164
	165	For instance:
	166
	167	INDENT-OFF
	168
492d29ea	169	TRY
ff55e1b5 GB	170	{
ff55e1b5 GB	171	}
492d29ea	172	CATCH (e, RETURN_MASK_ERROR)
ff55e1b5	173	{
492d29ea PA	174	switch (e.reason)
	175	{
	176	case RETURN_ERROR: ...
	177	}
ff55e1b5	178	}
492d29ea	179	END_CATCH
ff55e1b5	180
89525768 PA	181	Note that the SJLJ version of the macros are actually named
	182	TRY_SJLJ/CATCH_SJLJ in order to make it possible to call them even
	183	when TRY/CATCH are mapped to C++ try/catch. The SJLJ variants are
	184	needed in some cases where gdb exceptions need to cross third-party
	185	library code compiled without exceptions support (e.g.,
	186	readline). */
ff55e1b5	187
89525768	188	#define TRY_SJLJ \
ff55e1b5	189	{ \
173981bc	190	jmp_buf *buf = \
492d29ea	191	exceptions_state_mc_init (); \
173981bc	192	setjmp (*buf); \
ff55e1b5 GB	193	} \
	194	while (exceptions_state_mc_action_iter ()) \
	195	while (exceptions_state_mc_action_iter_1 ())
	196
89525768	197	#define CATCH_SJLJ(EXCEPTION, MASK) \
492d29ea PA	198	{ \
	199	struct gdb_exception EXCEPTION; \
	200	if (exceptions_state_mc_catch (&(EXCEPTION), MASK))
	201
89525768	202	#define END_CATCH_SJLJ \
492d29ea PA	203	}
492d29ea PA	204
89525768 PA	205	#if GDB_XCPT == GDB_XCPT_SJMP
	206
	207	/* If using SJLJ-based exceptions for all exceptions, then provide
	208	standard aliases. */
	209
	210	#define TRY TRY_SJLJ
	211	#define CATCH CATCH_SJLJ
	212	#define END_CATCH END_CATCH_SJLJ
	213
eec461d0 PA	214	#endif /* GDB_XCPT_SJMP */
	215
	216	#if GDB_XCPT == GDB_XCPT_TRY \|\| GDB_XCPT == GDB_XCPT_RAW_TRY
72df25b2 PA	217
	218	/* Prevent error/quit during TRY from calling cleanups established
	219	prior to here. This pops out the scope in either case of normal
	220	exit or exception exit. */
	221	struct exception_try_scope
	222	{
	223	exception_try_scope ()
	224	{
	225	saved_state = exception_try_scope_entry ();
	226	}
	227	~exception_try_scope ()
	228	{
	229	exception_try_scope_exit (saved_state);
	230	}
	231
	232	void *saved_state;
	233	};
	234
eec461d0	235	#if GDB_XCPT == GDB_XCPT_TRY
9c6595ab	236
72df25b2 PA	237	/* We still need to wrap TRY/CATCH in C++ so that cleanups and C++
	238	exceptions can coexist. The TRY blocked is wrapped in a
	239	do/while(0) so that break/continue within the block works the same
	240	as in C. */
	241	#define TRY \
	242	try \
	243	{ \
	244	exception_try_scope exception_try_scope_instance; \
	245	do \
	246	{
	247
	248	#define CATCH(EXCEPTION, MASK) \
	249	} while (0); \
	250	} \
	251	catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
	252
	253	#define END_CATCH \
	254	catch (...) \
	255	{ \
	256	exception_rethrow (); \
	257	}
eec461d0	258
9c6595ab PA	259	#else
	260
	261	#define TRY try
	262	#define CATCH(EXCEPTION, MASK) \
	263	catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
	264	#define END_CATCH
	265
	266	#endif
72df25b2 PA	267
	268	/* The exception types client code may catch. They're just shims
	269	around gdb_exception that add nothing but type info. Which is used
	270	is selected depending on the MASK argument passed to CATCH. */
	271
	272	struct gdb_exception_RETURN_MASK_ALL : public gdb_exception
	273	{
	274	};
	275
	276	struct gdb_exception_RETURN_MASK_ERROR : public gdb_exception_RETURN_MASK_ALL
	277	{
	278	};
	279
	280	struct gdb_exception_RETURN_MASK_QUIT : public gdb_exception_RETURN_MASK_ALL
	281	{
	282	};
	283
eec461d0	284	#endif /* GDB_XCPT_TRY \|\| GDB_XCPT_RAW_TRY */
72df25b2	285
ff55e1b5 GB	286	/* INDENT-ON */
ff55e1b5 GB	287
89525768 PA	288	/* Throw an exception (as described by "struct gdb_exception"). When
	289	GDB is built as a C program, executes a LONG JUMP to the inner most
	290	containing exception handler established using TRY/CATCH. When
	291	built as a C++ program, throws a C++ exception, using "throw". */
ff55e1b5 GB	292	extern void throw_exception (struct gdb_exception exception)
ff55e1b5 GB	293	ATTRIBUTE_NORETURN;
89525768 PA	294
	295	/* Throw an exception by executing a LONG JUMP to the inner most
	296	containing exception handler established using TRY_SJLJ. Works the
	297	same regardless of whether GDB is built as a C program or a C++
	298	program. Necessary in some cases where we need to throw GDB
	299	exceptions across third-party library code (e.g., readline). */
	300	extern void throw_exception_sjlj (struct gdb_exception exception)
	301	ATTRIBUTE_NORETURN;
	302
	303	/* Convenience wrappers around throw_exception that throw GDB
	304	errors. */
ff55e1b5 GB	305	extern void throw_verror (enum errors, const char *fmt, va_list ap)
	306	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0);
	307	extern void throw_vquit (const char *fmt, va_list ap)
	308	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0);
	309	extern void throw_error (enum errors error, const char *fmt, ...)
	310	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3);
	311	extern void throw_quit (const char *fmt, ...)
	312	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2);
	313
ad6aff7d PA	314	/* A pre-defined non-exception. */
	315	extern const struct gdb_exception exception_none;
	316
ff55e1b5	317	#endif /* COMMON_EXCEPTIONS_H */