1 /* Exception (throw catch) mechanism, for GDB, the GNU debugger.
3 Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
4 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free
5 Software Foundation, Inc.
7 This file is part of GDB.
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 59 Temple Place - Suite 330,
22 Boston, MA 02111-1307, USA. */
31 /* Reasons for calling throw_exceptions(). NOTE: all reason values
32 must be less than zero. enum value 0 is reserved for internal use
33 as the return value from an initial setjmp(). The function
34 catch_exceptions() reserves values >= 0 as legal results from its
41 /* Any other error. */
45 #define RETURN_MASK(reason) (1 << (int)(-reason))
46 #define RETURN_MASK_QUIT RETURN_MASK (RETURN_QUIT)
47 #define RETURN_MASK_ERROR RETURN_MASK (RETURN_ERROR)
48 #define RETURN_MASK_ALL (RETURN_MASK_QUIT | RETURN_MASK_ERROR)
49 typedef int return_mask;
51 /* Describe all exceptions. */
55 /* Any generic error, the corresponding text is in
59 /* Add more errors here. */
65 enum return_reason reason;
70 /* A pre-defined non-exception. */
71 extern const struct exception exception_none;
73 /* Wrap set/long jmp so that it's more portable (internal to
76 #if defined(HAVE_SIGSETJMP)
77 #define EXCEPTIONS_SIGJMP_BUF sigjmp_buf
78 #define EXCEPTIONS_SIGSETJMP(buf) sigsetjmp((buf), 1)
79 #define EXCEPTIONS_SIGLONGJMP(buf,val) siglongjmp((buf), (val))
81 #define EXCEPTIONS_SIGJMP_BUF jmp_buf
82 #define EXCEPTIONS_SIGSETJMP(buf) setjmp(buf)
83 #define EXCEPTIONS_SIGLONGJMP(buf,val) longjmp((buf), (val))
86 /* Functions to drive the exceptions state m/c (internal to
88 EXCEPTIONS_SIGJMP_BUF *exceptions_state_mc_init (struct ui_out *func_uiout,
89 volatile struct exception *
92 int exceptions_state_mc_action_iter (void);
93 int exceptions_state_mc_action_iter_1 (void);
95 /* Macro to wrap up standard try/catch behavior.
97 The double loop lets us correctly handle code "break"ing out of the
98 try catch block. (It works as the "break" only exits the inner
99 "while" loop, the outer for loop detects this handling it
100 correctly.) Of course "return" and "goto" are not so lucky.
106 volatile struct exception e;
107 TRY_CATCH (e, RETURN_MASK_ERROR)
112 case RETURN_ERROR: ...
117 #define TRY_CATCH(EXCEPTION,MASK) \
119 EXCEPTIONS_SIGJMP_BUF *buf = \
120 exceptions_state_mc_init (uiout, &(EXCEPTION), (MASK)); \
121 EXCEPTIONS_SIGSETJMP (*buf); \
123 while (exceptions_state_mc_action_iter ()) \
124 while (exceptions_state_mc_action_iter_1 ())
129 /* If E is an exception, print it's error message on the specified
130 stream. for _fprintf, prefix the message with PREFIX... */
131 extern void exception_print (struct ui_file *file, struct exception e);
132 extern void exception_fprintf (struct ui_file *file, struct exception e,
134 ...) ATTR_FORMAT (printf, 3, 4);
136 /* Throw an exception (as described by "struct exception"). Will
137 execute a LONG JUMP to the inner most containing exception handler
138 established using catch_exceptions() (or similar).
140 Code normally throws an exception using error() et.al. For various
141 reaons, GDB also contains code that throws an exception directly.
142 For instance, the remote*.c targets contain CNTRL-C signal handlers
143 that propogate the QUIT event up the exception chain. ``This could
144 be a good thing or a dangerous thing.'' -- the Existential
147 extern NORETURN void throw_exception (struct exception exception) ATTR_NORETURN;
148 extern NORETURN void throw_verror (enum errors, const char *fmt,
149 va_list ap) ATTR_NORETURN;
150 extern NORETURN void throw_vfatal (const char *fmt, va_list ap) ATTR_NORETURN;
151 extern NORETURN void throw_error (enum errors error, const char *fmt,
152 ...) ATTR_NORETURN ATTR_FORMAT (printf, 2, 3);
154 /* Instead of deprecated_throw_reason, code should use catch_exception
155 and throw_exception. */
156 extern NORETURN void deprecated_throw_reason (enum return_reason reason) ATTR_NORETURN;
158 /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception
159 handler. If an exception (enum return_reason) is thrown using
160 throw_exception() than all cleanups installed since
161 catch_exceptions() was entered are invoked, the (-ve) exception
162 value is then returned by catch_exceptions. If FUNC() returns
163 normally (with a postive or zero return value) then that value is
164 returned by catch_exceptions(). It is an internal_error() for
165 FUNC() to return a negative value.
167 For the period of the FUNC() call: UIOUT is installed as the output
168 builder; ERRSTRING is installed as the error/quit message; and a
169 new cleanup_chain is established. The old values are restored
170 before catch_exceptions() returns.
172 The variant catch_exceptions_with_msg() is the same as
173 catch_exceptions() but adds the ability to return an allocated
174 copy of the gdb error message. This is used when a silent error is
175 issued and the caller wants to manually issue the error message.
177 FIXME; cagney/2001-08-13: The need to override the global UIOUT
178 builder variable should just go away.
180 This function superseeds catch_errors().
182 This function uses SETJMP() and LONGJUMP(). */
185 typedef int (catch_exceptions_ftype) (struct ui_out *ui_out, void *args);
186 extern int catch_exceptions (struct ui_out *uiout,
187 catch_exceptions_ftype *func, void *func_args,
189 typedef void (catch_exception_ftype) (struct ui_out *ui_out, void *args);
190 extern int catch_exceptions_with_msg (struct ui_out *uiout,
191 catch_exceptions_ftype *func,
196 /* This function, in addition, suppresses the printing of the captured
197 error message. It's up to the client to print it. */
199 extern struct exception catch_exception (struct ui_out *uiout,
200 catch_exception_ftype *func,
204 /* If CATCH_ERRORS_FTYPE throws an error, catch_errors() returns zero
205 otherwize the result from CATCH_ERRORS_FTYPE is returned. It is
206 probably useful for CATCH_ERRORS_FTYPE to always return a non-zero
207 value. It's unfortunate that, catch_errors() does not return an
208 indication of the exact exception that it caught - quit_flag might
211 This function is superseeded by catch_exceptions(). */
213 typedef int (catch_errors_ftype) (void *);
214 extern int catch_errors (catch_errors_ftype *, void *, char *, return_mask);
216 /* Template to catch_errors() that wraps calls to command
219 typedef void (catch_command_errors_ftype) (char *, int);
220 extern int catch_command_errors (catch_command_errors_ftype *func, char *command, int from_tty, return_mask);