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. */
27 /* Reasons for calling throw_exceptions(). NOTE: all reason values
28 must be less than zero. enum value 0 is reserved for internal use
29 as the return value from an initial setjmp(). The function
30 catch_exceptions() reserves values >= 0 as legal results from its
37 /* Any other error. */
41 #define RETURN_MASK(reason) (1 << (int)(-reason))
42 #define RETURN_MASK_QUIT RETURN_MASK (RETURN_QUIT)
43 #define RETURN_MASK_ERROR RETURN_MASK (RETURN_ERROR)
44 #define RETURN_MASK_ALL (RETURN_MASK_QUIT | RETURN_MASK_ERROR)
45 typedef int return_mask
;
47 /* Describe all exceptions. */
51 /* Any generic error, the corresponding text is in
55 /* Add more errors here. */
61 enum return_reason reason
;
66 /* A pre-defined non-exception. */
67 extern const struct exception exception_none
;
69 /* If E is an exception, print it's error message on the specified
70 stream. for _fprintf, prefix the message with PREFIX... */
71 extern void exception_print (struct ui_file
*file
, struct exception e
);
72 extern void exception_fprintf (struct ui_file
*file
, struct exception e
,
74 ...) ATTR_FORMAT (printf
, 3, 4);
76 /* Throw an exception (as described by "struct exception"). Will
77 execute a LONG JUMP to the inner most containing exception handler
78 established using catch_exceptions() (or similar).
80 Code normally throws an exception using error() et.al. For various
81 reaons, GDB also contains code that throws an exception directly.
82 For instance, the remote*.c targets contain CNTRL-C signal handlers
83 that propogate the QUIT event up the exception chain. ``This could
84 be a good thing or a dangerous thing.'' -- the Existential
87 extern NORETURN
void throw_exception (struct exception exception
) ATTR_NORETURN
;
88 extern NORETURN
void throw_verror (enum errors
, const char *fmt
,
89 va_list ap
) ATTR_NORETURN
;
90 extern NORETURN
void throw_vfatal (const char *fmt
, va_list ap
) ATTR_NORETURN
;
91 extern NORETURN
void throw_error (enum errors error
, const char *fmt
,
92 ...) ATTR_NORETURN
ATTR_FORMAT (printf
, 2, 3);
94 /* Instead of deprecated_throw_reason, code should use catch_exception
95 and throw_exception. */
96 extern NORETURN
void deprecated_throw_reason (enum return_reason reason
) ATTR_NORETURN
;
98 /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception
99 handler. If an exception (enum return_reason) is thrown using
100 throw_exception() than all cleanups installed since
101 catch_exceptions() was entered are invoked, the (-ve) exception
102 value is then returned by catch_exceptions. If FUNC() returns
103 normally (with a postive or zero return value) then that value is
104 returned by catch_exceptions(). It is an internal_error() for
105 FUNC() to return a negative value.
107 For the period of the FUNC() call: UIOUT is installed as the output
108 builder; ERRSTRING is installed as the error/quit message; and a
109 new cleanup_chain is established. The old values are restored
110 before catch_exceptions() returns.
112 The variant catch_exceptions_with_msg() is the same as
113 catch_exceptions() but adds the ability to return an allocated
114 copy of the gdb error message. This is used when a silent error is
115 issued and the caller wants to manually issue the error message.
117 FIXME; cagney/2001-08-13: The need to override the global UIOUT
118 builder variable should just go away.
120 This function superseeds catch_errors().
122 This function uses SETJMP() and LONGJUMP(). */
125 typedef int (catch_exceptions_ftype
) (struct ui_out
*ui_out
, void *args
);
126 extern int catch_exceptions (struct ui_out
*uiout
,
127 catch_exceptions_ftype
*func
, void *func_args
,
129 typedef void (catch_exception_ftype
) (struct ui_out
*ui_out
, void *args
);
130 extern int catch_exceptions_with_msg (struct ui_out
*uiout
,
131 catch_exceptions_ftype
*func
,
136 /* This function, in addition, suppresses the printing of the captured
137 error message. It's up to the client to print it. */
139 extern struct exception
catch_exception (struct ui_out
*uiout
,
140 catch_exception_ftype
*func
,
144 /* If CATCH_ERRORS_FTYPE throws an error, catch_errors() returns zero
145 otherwize the result from CATCH_ERRORS_FTYPE is returned. It is
146 probably useful for CATCH_ERRORS_FTYPE to always return a non-zero
147 value. It's unfortunate that, catch_errors() does not return an
148 indication of the exact exception that it caught - quit_flag might
151 This function is superseeded by catch_exceptions(). */
153 typedef int (catch_errors_ftype
) (void *);
154 extern int catch_errors (catch_errors_ftype
*, void *, char *, return_mask
);
156 /* Template to catch_errors() that wraps calls to command
159 typedef void (catch_command_errors_ftype
) (char *, int);
160 extern int catch_command_errors (catch_command_errors_ftype
*func
, char *command
, int from_tty
, return_mask
);