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