Commit | Line | Data |
---|---|---|
60250e8b AC |
1 | /* Exception (throw catch) mechanism, for GDB, the GNU debugger. |
2 | ||
28e7fd62 | 3 | Copyright (C) 1986-2013 Free Software Foundation, Inc. |
60250e8b AC |
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 | |
a9762ec7 | 9 | the Free Software Foundation; either version 3 of the License, or |
60250e8b AC |
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 | |
a9762ec7 | 18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
60250e8b AC |
19 | |
20 | #ifndef EXCEPTIONS_H | |
21 | #define EXCEPTIONS_H | |
22 | ||
e74e72b4 | 23 | #include "ui-out.h" |
6941d02a AC |
24 | #include <setjmp.h> |
25 | ||
2a78bfb5 | 26 | /* Reasons for calling throw_exceptions(). NOTE: all reason values |
60250e8b AC |
27 | must be less than zero. enum value 0 is reserved for internal use |
28 | as the return value from an initial setjmp(). The function | |
29 | catch_exceptions() reserves values >= 0 as legal results from its | |
30 | wrapped function. */ | |
31 | ||
32 | enum return_reason | |
33 | { | |
34 | /* User interrupt. */ | |
35 | RETURN_QUIT = -2, | |
36 | /* Any other error. */ | |
37 | RETURN_ERROR | |
38 | }; | |
39 | ||
40 | #define RETURN_MASK(reason) (1 << (int)(-reason)) | |
df302446 TT |
41 | |
42 | typedef enum | |
43 | { | |
44 | RETURN_MASK_QUIT = RETURN_MASK (RETURN_QUIT), | |
45 | RETURN_MASK_ERROR = RETURN_MASK (RETURN_ERROR), | |
46 | RETURN_MASK_ALL = (RETURN_MASK_QUIT | RETURN_MASK_ERROR) | |
47 | } return_mask; | |
60250e8b | 48 | |
2a78bfb5 AC |
49 | /* Describe all exceptions. */ |
50 | ||
51 | enum errors { | |
7b871fab | 52 | GDB_NO_ERROR, |
8af8e3bc | 53 | |
2a78bfb5 AC |
54 | /* Any generic error, the corresponding text is in |
55 | exception.message. */ | |
56 | GENERIC_ERROR, | |
8af8e3bc PA |
57 | |
58 | /* Something requested was not found. */ | |
05ff989b | 59 | NOT_FOUND_ERROR, |
93ad78a7 KB |
60 | |
61 | /* Thread library lacks support necessary for finding thread local | |
62 | storage. */ | |
63 | TLS_NO_LIBRARY_SUPPORT_ERROR, | |
64 | ||
65 | /* Load module not found while attempting to find thread local storage. */ | |
66 | TLS_LOAD_MODULE_NOT_FOUND_ERROR, | |
67 | ||
68 | /* Thread local storage has not been allocated yet. */ | |
69 | TLS_NOT_ALLOCATED_YET_ERROR, | |
70 | ||
71 | /* Something else went wrong while attempting to find thread local | |
71fff37b AC |
72 | storage. The ``struct gdb_exception'' message field provides |
73 | more detail. */ | |
93ad78a7 | 74 | TLS_GENERIC_ERROR, |
fd79ecee DJ |
75 | |
76 | /* Problem parsing an XML document. */ | |
77 | XML_PARSE_ERROR, | |
ccc57cf9 PA |
78 | |
79 | /* Error accessing memory. */ | |
80 | MEMORY_ERROR, | |
93ad78a7 | 81 | |
8af8e3bc PA |
82 | /* Value not available. E.g., a register was not collected in a |
83 | traceframe. */ | |
84 | NOT_AVAILABLE_ERROR, | |
85 | ||
710409a2 PA |
86 | /* Value was optimized out. Note: if the value was a register, this |
87 | means the register was not saved in the frame. */ | |
88 | OPTIMIZED_OUT_ERROR, | |
89 | ||
8e3b41a9 JK |
90 | /* DW_OP_GNU_entry_value resolving failed. */ |
91 | NO_ENTRY_VALUE_ERROR, | |
92 | ||
598d3636 JK |
93 | /* Target throwing an error has been closed. Current command should be |
94 | aborted as the inferior state is no longer valid. */ | |
95 | TARGET_CLOSE_ERROR, | |
96 | ||
2ea126fa JB |
97 | /* An undefined command was executed. */ |
98 | UNDEFINED_COMMAND_ERROR, | |
99 | ||
2a78bfb5 AC |
100 | /* Add more errors here. */ |
101 | NR_ERRORS | |
102 | }; | |
103 | ||
71fff37b | 104 | struct gdb_exception |
2a78bfb5 AC |
105 | { |
106 | enum return_reason reason; | |
107 | enum errors error; | |
b315da38 | 108 | const char *message; |
2a78bfb5 AC |
109 | }; |
110 | ||
c1043fc2 | 111 | /* A pre-defined non-exception. */ |
71fff37b | 112 | extern const struct gdb_exception exception_none; |
c1043fc2 | 113 | |
6941d02a AC |
114 | /* Wrap set/long jmp so that it's more portable (internal to |
115 | exceptions). */ | |
116 | ||
117 | #if defined(HAVE_SIGSETJMP) | |
118 | #define EXCEPTIONS_SIGJMP_BUF sigjmp_buf | |
119 | #define EXCEPTIONS_SIGSETJMP(buf) sigsetjmp((buf), 1) | |
120 | #define EXCEPTIONS_SIGLONGJMP(buf,val) siglongjmp((buf), (val)) | |
121 | #else | |
122 | #define EXCEPTIONS_SIGJMP_BUF jmp_buf | |
123 | #define EXCEPTIONS_SIGSETJMP(buf) setjmp(buf) | |
124 | #define EXCEPTIONS_SIGLONGJMP(buf,val) longjmp((buf), (val)) | |
125 | #endif | |
126 | ||
127 | /* Functions to drive the exceptions state m/c (internal to | |
128 | exceptions). */ | |
f9679975 | 129 | EXCEPTIONS_SIGJMP_BUF *exceptions_state_mc_init (volatile struct |
3e43a32a | 130 | gdb_exception *exception, |
6941d02a AC |
131 | return_mask mask); |
132 | int exceptions_state_mc_action_iter (void); | |
133 | int exceptions_state_mc_action_iter_1 (void); | |
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 | ||
71fff37b | 146 | volatile struct gdb_exception e; |
6941d02a AC |
147 | TRY_CATCH (e, RETURN_MASK_ERROR) |
148 | { | |
149 | } | |
150 | switch (e.reason) | |
151 | { | |
152 | case RETURN_ERROR: ... | |
153 | } | |
154 | ||
155 | */ | |
156 | ||
157 | #define TRY_CATCH(EXCEPTION,MASK) \ | |
8d19ca47 CV |
158 | { \ |
159 | EXCEPTIONS_SIGJMP_BUF *buf = \ | |
f9679975 | 160 | exceptions_state_mc_init (&(EXCEPTION), (MASK)); \ |
8d19ca47 CV |
161 | EXCEPTIONS_SIGSETJMP (*buf); \ |
162 | } \ | |
163 | while (exceptions_state_mc_action_iter ()) \ | |
164 | while (exceptions_state_mc_action_iter_1 ()) | |
6941d02a AC |
165 | |
166 | /* *INDENT-ON* */ | |
167 | ||
168 | ||
8a076db9 | 169 | /* If E is an exception, print it's error message on the specified |
0963b4bd | 170 | stream. For _fprintf, prefix the message with PREFIX... */ |
71fff37b AC |
171 | extern void exception_print (struct ui_file *file, struct gdb_exception e); |
172 | extern void exception_fprintf (struct ui_file *file, struct gdb_exception e, | |
9cbc821d | 173 | const char *prefix, |
a0b31db1 | 174 | ...) ATTRIBUTE_PRINTF (3, 4); |
8a076db9 | 175 | |
71fff37b | 176 | /* Throw an exception (as described by "struct gdb_exception"). Will |
2a78bfb5 AC |
177 | execute a LONG JUMP to the inner most containing exception handler |
178 | established using catch_exceptions() (or similar). | |
60250e8b AC |
179 | |
180 | Code normally throws an exception using error() et.al. For various | |
181 | reaons, GDB also contains code that throws an exception directly. | |
182 | For instance, the remote*.c targets contain CNTRL-C signal handlers | |
183 | that propogate the QUIT event up the exception chain. ``This could | |
2a78bfb5 AC |
184 | be a good thing or a dangerous thing.'' -- the Existential |
185 | Wombat. */ | |
186 | ||
3e43a32a MS |
187 | extern void throw_exception (struct gdb_exception exception) |
188 | ATTRIBUTE_NORETURN; | |
c25c4a8b JK |
189 | extern void throw_verror (enum errors, const char *fmt, va_list ap) |
190 | ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0); | |
191 | extern void throw_vfatal (const char *fmt, va_list ap) | |
192 | ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0); | |
193 | extern void throw_error (enum errors error, const char *fmt, ...) | |
194 | ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3); | |
60250e8b AC |
195 | |
196 | /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception | |
197 | handler. If an exception (enum return_reason) is thrown using | |
198 | throw_exception() than all cleanups installed since | |
199 | catch_exceptions() was entered are invoked, the (-ve) exception | |
200 | value is then returned by catch_exceptions. If FUNC() returns | |
787274f0 | 201 | normally (with a positive or zero return value) then that value is |
60250e8b AC |
202 | returned by catch_exceptions(). It is an internal_error() for |
203 | FUNC() to return a negative value. | |
204 | ||
205 | For the period of the FUNC() call: UIOUT is installed as the output | |
206 | builder; ERRSTRING is installed as the error/quit message; and a | |
207 | new cleanup_chain is established. The old values are restored | |
208 | before catch_exceptions() returns. | |
209 | ||
210 | The variant catch_exceptions_with_msg() is the same as | |
211 | catch_exceptions() but adds the ability to return an allocated | |
212 | copy of the gdb error message. This is used when a silent error is | |
213 | issued and the caller wants to manually issue the error message. | |
214 | ||
787274f0 DE |
215 | MASK specifies what to catch; it is normally set to |
216 | RETURN_MASK_ALL, if for no other reason than that the code which | |
217 | calls catch_errors might not be set up to deal with a quit which | |
218 | isn't caught. But if the code can deal with it, it generally | |
219 | should be RETURN_MASK_ERROR, unless for some reason it is more | |
220 | useful to abort only the portion of the operation inside the | |
221 | catch_errors. Note that quit should return to the command line | |
222 | fairly quickly, even if some further processing is being done. | |
223 | ||
60250e8b AC |
224 | FIXME; cagney/2001-08-13: The need to override the global UIOUT |
225 | builder variable should just go away. | |
226 | ||
787274f0 | 227 | This function supersedes catch_errors(). |
60250e8b AC |
228 | |
229 | This function uses SETJMP() and LONGJUMP(). */ | |
230 | ||
231 | struct ui_out; | |
232 | typedef int (catch_exceptions_ftype) (struct ui_out *ui_out, void *args); | |
233 | extern int catch_exceptions (struct ui_out *uiout, | |
234 | catch_exceptions_ftype *func, void *func_args, | |
1c3c7ee7 | 235 | return_mask mask); |
2a78bfb5 | 236 | typedef void (catch_exception_ftype) (struct ui_out *ui_out, void *args); |
60250e8b AC |
237 | extern int catch_exceptions_with_msg (struct ui_out *uiout, |
238 | catch_exceptions_ftype *func, | |
239 | void *func_args, | |
1c3c7ee7 | 240 | char **gdberrmsg, |
60250e8b | 241 | return_mask mask); |
8a076db9 | 242 | |
60250e8b | 243 | /* If CATCH_ERRORS_FTYPE throws an error, catch_errors() returns zero |
0963b4bd | 244 | otherwize the result from CATCH_ERRORS_FTYPE is returned. It is |
60250e8b | 245 | probably useful for CATCH_ERRORS_FTYPE to always return a non-zero |
0963b4bd | 246 | value. It's unfortunate that, catch_errors() does not return an |
60250e8b AC |
247 | indication of the exact exception that it caught - quit_flag might |
248 | help. | |
249 | ||
787274f0 | 250 | This function is superseded by catch_exceptions(). */ |
60250e8b AC |
251 | |
252 | typedef int (catch_errors_ftype) (void *); | |
253 | extern int catch_errors (catch_errors_ftype *, void *, char *, return_mask); | |
254 | ||
255 | /* Template to catch_errors() that wraps calls to command | |
0963b4bd | 256 | functions. */ |
60250e8b AC |
257 | |
258 | typedef void (catch_command_errors_ftype) (char *, int); | |
3e43a32a | 259 | extern int catch_command_errors (catch_command_errors_ftype *func, |
97f8dd09 | 260 | char *arg, int from_tty, return_mask); |
60250e8b | 261 | |
50dd9793 PA |
262 | /* Like catch_command_errors, but works with const command and args. */ |
263 | ||
264 | typedef void (catch_command_errors_const_ftype) (const char *, int); | |
265 | extern int catch_command_errors_const (catch_command_errors_const_ftype *func, | |
266 | const char *arg, int from_tty, return_mask); | |
267 | ||
60250e8b | 268 | #endif |