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

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

   Copyright (C) 1986-2019 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_COMMON_EXCEPTIONS_H
#define COMMON_COMMON_EXCEPTIONS_H

#include <setjmp.h>
#include <new>
#include <memory>

/* Reasons for calling throw_exceptions().  NOTE: all reason values
   must be different from zero.  enum value 0 is reserved for internal
   use as the return value from an initial setjmp().  */

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_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
{
  gdb_exception ()
    : reason ((enum return_reason) 0),
      error (GDB_NO_ERROR)
  {
  }

  gdb_exception (enum return_reason r, enum errors e)
    : reason (r),
      error (e)
  {
  }

  /* The copy constructor exists so that we can mark it "noexcept",
     which is a good practice for any sort of exception object.  */
  gdb_exception (const gdb_exception &other) noexcept
    : reason (other.reason),
      error (other.error),
      message (other.message)
  {
  }

  /* The assignment operator exists so that we can mark it "noexcept",
     which is a good practice for any sort of exception object.  */
  gdb_exception &operator= (const gdb_exception &other) noexcept
  {
    reason = other.reason;
    error = other.error;
    message = other.message;
    return *this;
  }

  /* Return the contents of the exception message, as a C string.  The
     string remains owned by the exception object.  */
  const char *what () const noexcept
  {
    return message->c_str ();
  }

  enum return_reason reason;
  enum errors error;
  std::shared_ptr<std::string> message;
};

/* 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);

/* For the C++ try/catch-based TRY/CATCH mechanism.  */

extern void exception_rethrow (void) ATTRIBUTE_NORETURN;

/* 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				\
  }

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

   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									\
      {									\
	do								\
	  {

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

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

/* 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
{
  explicit gdb_exception_RETURN_MASK_ALL (const gdb_exception &ex) noexcept
    : gdb_exception (ex)
  {
  }
};

struct gdb_exception_RETURN_MASK_ERROR : public gdb_exception_RETURN_MASK_ALL
{
  explicit gdb_exception_RETURN_MASK_ERROR (const gdb_exception &ex) noexcept
    : gdb_exception_RETURN_MASK_ALL (ex)
  {
  }
};

struct gdb_exception_RETURN_MASK_QUIT : public gdb_exception_RETURN_MASK_ALL
{
  explicit gdb_exception_RETURN_MASK_QUIT (const gdb_exception &ex) noexcept
    : gdb_exception_RETURN_MASK_ALL (ex)
  {
  }
};

/* An exception type that inherits from both std::bad_alloc and a gdb
   exception.  This is necessary because operator new can only throw
   std::bad_alloc, and OTOH, we want exceptions thrown due to memory
   allocation error to be caught by all the CATCH/RETURN_MASK_ALL
   spread around the codebase.  */

struct gdb_quit_bad_alloc
  : public gdb_exception_RETURN_MASK_QUIT,
    public std::bad_alloc
{
  explicit gdb_quit_bad_alloc (const gdb_exception &ex) noexcept
    : gdb_exception_RETURN_MASK_QUIT (ex),
      std::bad_alloc ()
  {
  }
};

/* *INDENT-ON* */

/* 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.  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_COMMON_EXCEPTIONS_H */
Commit	Line	Data
ff55e1b5 GB	1	/* Exception (throw catch) mechanism, for GDB, the GNU debugger.
ff55e1b5 GB	2
42a4f53d	3	Copyright (C) 1986-2019 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
1a5c2598 TT	20	#ifndef COMMON_COMMON_EXCEPTIONS_H
1a5c2598 TT	21	#define COMMON_COMMON_EXCEPTIONS_H
ff55e1b5	22
173981bc	23	#include <setjmp.h>
503b1c39	24	#include <new>
3d6e9d23	25	#include <memory>
ff55e1b5 GB	26
ff55e1b5 GB	27	/* Reasons for calling throw_exceptions(). NOTE: all reason values
65630365 PA	28	must be different from zero. enum value 0 is reserved for internal
65630365 PA	29	use as the return value from an initial setjmp(). */
ff55e1b5 GB	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
216f72a1	89	/* DW_OP_entry_value resolving failed. */
ff55e1b5 GB	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	{
3d6e9d23 TT	114	gdb_exception ()
	115	: reason ((enum return_reason) 0),
	116	error (GDB_NO_ERROR)
	117	{
	118	}
	119
	120	gdb_exception (enum return_reason r, enum errors e)
	121	: reason (r),
	122	error (e)
	123	{
	124	}
	125
	126	/* The copy constructor exists so that we can mark it "noexcept",
	127	which is a good practice for any sort of exception object. */
	128	gdb_exception (const gdb_exception &other) noexcept
	129	: reason (other.reason),
	130	error (other.error),
	131	message (other.message)
	132	{
	133	}
	134
	135	/* The assignment operator exists so that we can mark it "noexcept",
	136	which is a good practice for any sort of exception object. */
	137	gdb_exception &operator= (const gdb_exception &other) noexcept
	138	{
	139	reason = other.reason;
	140	error = other.error;
	141	message = other.message;
	142	return *this;
	143	}
	144
	145	/* Return the contents of the exception message, as a C string. The
	146	string remains owned by the exception object. */
	147	const char *what () const noexcept
	148	{
	149	return message->c_str ();
	150	}
	151
ff55e1b5 GB	152	enum return_reason reason;
ff55e1b5 GB	153	enum errors error;
3d6e9d23	154	std::shared_ptr<std::string> message;
ff55e1b5 GB	155	};
ff55e1b5 GB	156
89525768 PA	157	/* Functions to drive the sjlj-based exceptions state machine. Though
	158	declared here by necessity, these functions should be considered
	159	internal to the exceptions subsystem and not used other than via
	160	the TRY/CATCH (or TRY_SJLJ/CATCH_SJLJ) macros defined below. */
ff55e1b5	161
173981bc	162	extern jmp_buf *exceptions_state_mc_init (void);
ff55e1b5 GB	163	extern int exceptions_state_mc_action_iter (void);
ff55e1b5 GB	164	extern int exceptions_state_mc_action_iter_1 (void);
492d29ea	165	extern int exceptions_state_mc_catch (struct gdb_exception *, int);
89525768	166
c5c10118	167	/* For the C++ try/catch-based TRY/CATCH mechanism. */
89525768	168
f7c6f423	169	extern void exception_rethrow (void) ATTRIBUTE_NORETURN;
ff55e1b5 GB	170
	171	/* Macro to wrap up standard try/catch behavior.
	172
	173	The double loop lets us correctly handle code "break"ing out of the
	174	try catch block. (It works as the "break" only exits the inner
	175	"while" loop, the outer for loop detects this handling it
	176	correctly.) Of course "return" and "goto" are not so lucky.
	177
	178	For instance:
	179
	180	INDENT-OFF
	181
492d29ea	182	TRY
ff55e1b5 GB	183	{
ff55e1b5 GB	184	}
492d29ea	185	CATCH (e, RETURN_MASK_ERROR)
ff55e1b5	186	{
492d29ea PA	187	switch (e.reason)
	188	{
	189	case RETURN_ERROR: ...
	190	}
ff55e1b5	191	}
492d29ea	192	END_CATCH
ff55e1b5	193
89525768 PA	194	Note that the SJLJ version of the macros are actually named
	195	TRY_SJLJ/CATCH_SJLJ in order to make it possible to call them even
	196	when TRY/CATCH are mapped to C++ try/catch. The SJLJ variants are
	197	needed in some cases where gdb exceptions need to cross third-party
	198	library code compiled without exceptions support (e.g.,
	199	readline). */
ff55e1b5	200
89525768	201	#define TRY_SJLJ \
ff55e1b5	202	{ \
173981bc	203	jmp_buf *buf = \
492d29ea	204	exceptions_state_mc_init (); \
173981bc	205	setjmp (*buf); \
ff55e1b5 GB	206	} \
	207	while (exceptions_state_mc_action_iter ()) \
	208	while (exceptions_state_mc_action_iter_1 ())
	209
89525768	210	#define CATCH_SJLJ(EXCEPTION, MASK) \
492d29ea PA	211	{ \
	212	struct gdb_exception EXCEPTION; \
	213	if (exceptions_state_mc_catch (&(EXCEPTION), MASK))
	214
89525768	215	#define END_CATCH_SJLJ \
492d29ea PA	216	}
492d29ea PA	217
72df25b2	218	/* We still need to wrap TRY/CATCH in C++ so that cleanups and C++
a87c1427 PA	219	exceptions can coexist.
	220
	221	The TRY blocked is wrapped in a do/while(0) so that break/continue
	222	within the block works the same as in C.
	223
	224	END_CATCH makes sure that even if the CATCH block doesn't want to
	225	catch the exception, we stop at every frame in the unwind chain to
	226	run its cleanups, which may e.g., have pointers to stack variables
	227	that are going to be destroyed.
	228
	229	There's an outer scope around the whole TRY/END_CATCH in order to
	230	cause a compilation error if you forget to add the END_CATCH at the
	231	end a TRY/CATCH construct. */
	232
72df25b2	233	#define TRY \
a87c1427 PA	234	{ \
	235	try \
	236	{ \
a87c1427 PA	237	do \
a87c1427 PA	238	{
72df25b2 PA	239
72df25b2 PA	240	#define CATCH(EXCEPTION, MASK) \
a87c1427 PA	241	} while (0); \
	242	} \
	243	catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
72df25b2 PA	244
72df25b2 PA	245	#define END_CATCH \
a87c1427 PA	246	catch (...) \
	247	{ \
	248	exception_rethrow (); \
	249	} \
72df25b2	250	}
eec461d0	251
72df25b2 PA	252	/* The exception types client code may catch. They're just shims
	253	around gdb_exception that add nothing but type info. Which is used
	254	is selected depending on the MASK argument passed to CATCH. */
	255
	256	struct gdb_exception_RETURN_MASK_ALL : public gdb_exception
	257	{
3d6e9d23 TT	258	explicit gdb_exception_RETURN_MASK_ALL (const gdb_exception &ex) noexcept
	259	: gdb_exception (ex)
	260	{
	261	}
72df25b2 PA	262	};
	263
	264	struct gdb_exception_RETURN_MASK_ERROR : public gdb_exception_RETURN_MASK_ALL
	265	{
3d6e9d23 TT	266	explicit gdb_exception_RETURN_MASK_ERROR (const gdb_exception &ex) noexcept
	267	: gdb_exception_RETURN_MASK_ALL (ex)
	268	{
	269	}
72df25b2 PA	270	};
	271
	272	struct gdb_exception_RETURN_MASK_QUIT : public gdb_exception_RETURN_MASK_ALL
	273	{
3d6e9d23 TT	274	explicit gdb_exception_RETURN_MASK_QUIT (const gdb_exception &ex) noexcept
	275	: gdb_exception_RETURN_MASK_ALL (ex)
	276	{
	277	}
72df25b2 PA	278	};
72df25b2 PA	279
503b1c39 PA	280	/* An exception type that inherits from both std::bad_alloc and a gdb
	281	exception. This is necessary because operator new can only throw
	282	std::bad_alloc, and OTOH, we want exceptions thrown due to memory
	283	allocation error to be caught by all the CATCH/RETURN_MASK_ALL
	284	spread around the codebase. */
	285
	286	struct gdb_quit_bad_alloc
	287	: public gdb_exception_RETURN_MASK_QUIT,
	288	public std::bad_alloc
	289	{
3d6e9d23 TT	290	explicit gdb_quit_bad_alloc (const gdb_exception &ex) noexcept
	291	: gdb_exception_RETURN_MASK_QUIT (ex),
	292	std::bad_alloc ()
503b1c39	293	{
503b1c39 PA	294	}
	295	};
	296
ff55e1b5 GB	297	/* INDENT-ON */
ff55e1b5 GB	298
ddb6d633 PA	299	/* Throw an exception (as described by "struct gdb_exception"),
	300	landing in the inner most containing exception handler established
	301	using TRY/CATCH. */
ff55e1b5 GB	302	extern void throw_exception (struct gdb_exception exception)
ff55e1b5 GB	303	ATTRIBUTE_NORETURN;
89525768 PA	304
89525768 PA	305	/* Throw an exception by executing a LONG JUMP to the inner most
ddb6d633 PA	306	containing exception handler established using TRY_SJLJ. Necessary
	307	in some cases where we need to throw GDB exceptions across
	308	third-party library code (e.g., readline). */
89525768 PA	309	extern void throw_exception_sjlj (struct gdb_exception exception)
	310	ATTRIBUTE_NORETURN;
	311
	312	/* Convenience wrappers around throw_exception that throw GDB
	313	errors. */
ff55e1b5 GB	314	extern void throw_verror (enum errors, const char *fmt, va_list ap)
	315	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0);
	316	extern void throw_vquit (const char *fmt, va_list ap)
	317	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0);
	318	extern void throw_error (enum errors error, const char *fmt, ...)
	319	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3);
	320	extern void throw_quit (const char *fmt, ...)
	321	ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2);
	322
ad6aff7d PA	323	/* A pre-defined non-exception. */
	324	extern const struct gdb_exception exception_none;
	325
1a5c2598	326	#endif /* COMMON_COMMON_EXCEPTIONS_H */