GDB (xrefs)
common-exceptions.h
Go to the documentation of this file.
1 /* Exception (throw catch) mechanism, for GDB, the GNU debugger.
2 
3  Copyright (C) 1986-2015 Free Software Foundation, Inc.
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 
23 #include "gdb_setjmp.h"
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 
32  {
33  /* User interrupt. */
35  /* Any other error. */
37  };
38 
39 #define RETURN_MASK(reason) (1 << (int)(-reason))
40 
41 typedef enum
42 {
46 } return_mask;
47 
48 /* Describe all exceptions. */
49 
50 enum errors {
52 
53  /* Any generic error, the corresponding text is in
54  exception.message. */
56 
57  /* Something requested was not found. */
59 
60  /* Thread library lacks support necessary for finding thread local
61  storage. */
63 
64  /* Load module not found while attempting to find thread local storage. */
66 
67  /* Thread local storage has not been allocated yet. */
69 
70  /* Something else went wrong while attempting to find thread local
71  storage. The ``struct gdb_exception'' message field provides
72  more detail. */
74 
75  /* Problem parsing an XML document. */
77 
78  /* Error accessing memory. */
80 
81  /* Value not available. E.g., a register was not collected in a
82  traceframe. */
84 
85  /* Value was optimized out. Note: if the value was a register, this
86  means the register was not saved in the frame. */
88 
89  /* DW_OP_GNU_entry_value resolving failed. */
91 
92  /* Target throwing an error has been closed. Current command should be
93  aborted as the inferior state is no longer valid. */
95 
96  /* An undefined command was executed. */
98 
99  /* Requested feature, method, mechanism, etc. is not supported. */
101 
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. */
107 
108  /* Add more errors here. */
110 };
111 
113 {
115  enum errors error;
116  const char *message;
117 };
118 
119 /* Functions to drive the exceptions state machine. Though declared
120  here by necessity, these functions should be considered internal to
121  the exceptions subsystem and not used other than via the TRY/CATCH
122  macros defined below. */
123 
124 #ifndef __cplusplus
125 extern SIGJMP_BUF *exceptions_state_mc_init (void);
126 extern int exceptions_state_mc_action_iter (void);
127 extern int exceptions_state_mc_action_iter_1 (void);
128 extern int exceptions_state_mc_catch (struct gdb_exception *, int);
129 #else
130 extern void *exception_try_scope_entry (void);
131 extern void exception_try_scope_exit (void *saved_state);
132 extern void exception_rethrow (void);
133 #endif
134 
135 /* Macro to wrap up standard try/catch behavior.
136 
137  The double loop lets us correctly handle code "break"ing out of the
138  try catch block. (It works as the "break" only exits the inner
139  "while" loop, the outer for loop detects this handling it
140  correctly.) Of course "return" and "goto" are not so lucky.
141 
142  For instance:
143 
144  *INDENT-OFF*
145 
146  TRY
147  {
148  }
149  CATCH (e, RETURN_MASK_ERROR)
150  {
151  switch (e.reason)
152  {
153  case RETURN_ERROR: ...
154  }
155  }
156  END_CATCH
157 
158  */
159 
160 #ifndef __cplusplus
161 
162 #define TRY \
163  { \
164  SIGJMP_BUF *buf = \
165  exceptions_state_mc_init (); \
166  SIGSETJMP (*buf); \
167  } \
168  while (exceptions_state_mc_action_iter ()) \
169  while (exceptions_state_mc_action_iter_1 ())
170 
171 #define CATCH(EXCEPTION, MASK) \
172  { \
173  struct gdb_exception EXCEPTION; \
174  if (exceptions_state_mc_catch (&(EXCEPTION), MASK))
175 
176 #define END_CATCH \
177  }
178 
179 #else
180 
181 /* Prevent error/quit during TRY from calling cleanups established
182  prior to here. This pops out the scope in either case of normal
183  exit or exception exit. */
184 struct exception_try_scope
185 {
186  exception_try_scope ()
187  {
188  saved_state = exception_try_scope_entry ();
189  }
190  ~exception_try_scope ()
191  {
192  exception_try_scope_exit (saved_state);
193  }
194 
195  void *saved_state;
196 };
197 
198 /* We still need to wrap TRY/CATCH in C++ so that cleanups and C++
199  exceptions can coexist. The TRY blocked is wrapped in a
200  do/while(0) so that break/continue within the block works the same
201  as in C. */
202 #define TRY \
203  try \
204  { \
205  exception_try_scope exception_try_scope_instance; \
206  do \
207  {
208 
209 #define CATCH(EXCEPTION, MASK) \
210  } while (0); \
211  } \
212  catch (struct gdb_exception ## _ ## MASK &EXCEPTION)
213 
214 #define END_CATCH \
215  catch (...) \
216  { \
217  exception_rethrow (); \
218  }
219 
220 /* The exception types client code may catch. They're just shims
221  around gdb_exception that add nothing but type info. Which is used
222  is selected depending on the MASK argument passed to CATCH. */
223 
224 struct gdb_exception_RETURN_MASK_ALL : public gdb_exception
225 {
226 };
227 
228 struct gdb_exception_RETURN_MASK_ERROR : public gdb_exception_RETURN_MASK_ALL
229 {
230 };
231 
232 struct gdb_exception_RETURN_MASK_QUIT : public gdb_exception_RETURN_MASK_ALL
233 {
234 };
235 
236 #endif
237 
238 /* *INDENT-ON* */
239 
240 /* Hook to allow client-specific actions to be performed prior to
241  throwing an exception. This function must be provided by the
242  client, and will be called before any cleanups are run. */
243 
244 extern void prepare_to_throw_exception (void);
245 
246 /* Throw an exception (as described by "struct gdb_exception"). Will
247  execute a LONG JUMP to the inner most containing exception handler
248  established using catch_exceptions() (or similar).
249 
250  Code normally throws an exception using error() et.al. For various
251  reaons, GDB also contains code that throws an exception directly.
252  For instance, the remote*.c targets contain CNTRL-C signal handlers
253  that propogate the QUIT event up the exception chain. ``This could
254  be a good thing or a dangerous thing.'' -- the Existential
255  Wombat. */
256 
257 extern void throw_exception (struct gdb_exception exception)
258  ATTRIBUTE_NORETURN;
259 extern void throw_verror (enum errors, const char *fmt, va_list ap)
260  ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0);
261 extern void throw_vquit (const char *fmt, va_list ap)
262  ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0);
263 extern void throw_error (enum errors error, const char *fmt, ...)
264  ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3);
265 extern void throw_quit (const char *fmt, ...)
266  ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2);
267 
268 /* A pre-defined non-exception. */
269 extern const struct gdb_exception exception_none;
270 
271 #endif /* COMMON_EXCEPTIONS_H */
int exceptions_state_mc_catch(struct gdb_exception *, int)
return_reason
struct type ** const(pascal_builtin_types[])
#define RETURN_MASK(reason)
enum errors error
void void void void throw_quit(const char *fmt,...) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF(1
void void throw_vquit(const char *fmt, va_list ap) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF(1
#define SIGJMP_BUF
Definition: gdb_setjmp.h:29
void throw_exception(struct gdb_exception exception) ATTRIBUTE_NORETURN
void prepare_to_throw_exception(void)
Definition: exceptions.c:31
return_mask
int exceptions_state_mc_action_iter(void)
void throw_verror(enum errors, const char *fmt, va_list ap) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF(2
void void void throw_error(enum errors error, const char *fmt,...) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF(2
int exceptions_state_mc_action_iter_1(void)
SIGJMP_BUF * exceptions_state_mc_init(void)
static void ATTRIBUTE_PRINTF(6, 0)
Definition: cli-out.c:229
const char * message
enum return_reason reason