2005-01-15 Andrew Cagney <cagney@gnu.org>

[deliverable/binutils-gdb.git] / gdb / exceptions.h

diff --git a/gdb/exceptions.h b/gdb/exceptions.h
index 5ebde6627941f6af536ab9feed49b0d147992c60..fddaf37ea1033017449c85356f7bbfdfaaf705a7 100644 (file)
--- a/gdb/exceptions.h
+++ b/gdb/exceptions.h
@@ -1,8 +1,8 @@
 /* Exception (throw catch) mechanism, for GDB, the GNU debugger.
 
    Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-   1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software
-   Foundation, Inc.
+   1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free
+   Software Foundation, Inc.
 
    This file is part of GDB.
 
@@ -24,7 +24,7 @@
 #ifndef EXCEPTIONS_H
 #define EXCEPTIONS_H
 
-/* Reasons for calling throw_exception().  NOTE: all reason values
+/* Reasons for calling throw_exceptions().  NOTE: all reason values
    must be less than zero.  enum value 0 is reserved for internal use
    as the return value from an initial setjmp().  The function
    catch_exceptions() reserves values >= 0 as legal results from its
@@ -44,17 +44,53 @@ enum return_reason
 #define RETURN_MASK_ALL                (RETURN_MASK_QUIT | RETURN_MASK_ERROR)
 typedef int return_mask;
 
-/* Throw an exception of type RETURN_REASON.  Will execute a LONG JUMP
-   to the inner most containing exception handler established using
-   catch_exceptions() (or the legacy catch_errors()).
+/* Describe all exceptions.  */
+
+enum errors {
+  NO_ERROR,
+  /* Any generic error, the corresponding text is in
+     exception.message.  */
+  GENERIC_ERROR,
+  NOT_FOUND_ERROR,
+  /* Add more errors here.  */
+  NR_ERRORS
+};
+
+struct exception
+{
+  enum return_reason reason;
+  enum errors error;
+  const char *message;
+};
+
+/* A pre-defined non-exception.  */
+extern const struct exception exception_none;
+
+/* If E is an exception, print it's error message on the specified
+   stream. for _fprintf, prefix the message with PREFIX...  */
+extern void exception_print (struct ui_file *file, struct exception e);
+extern void exception_fprintf (struct ui_file *file, struct exception e,
+                              const char *prefix,
+                              ...) ATTR_FORMAT (printf, 3, 4);
+
+/* Throw an exception (as described by "struct exception").  Will
+   execute a LONG JUMP to the inner most containing exception handler
+   established using catch_exceptions() (or similar).
 
    Code normally throws an exception using error() et.al.  For various
    reaons, GDB also contains code that throws an exception directly.
    For instance, the remote*.c targets contain CNTRL-C signal handlers
    that propogate the QUIT event up the exception chain.  ``This could
-   be a good thing or a dangerous thing.'' -- the Existential Wombat.  */
+   be a good thing or a dangerous thing.'' -- the Existential
+   Wombat.  */
 
-extern NORETURN void throw_exception (enum return_reason) ATTR_NORETURN;
+extern NORETURN void throw_exception (struct exception exception) ATTR_NORETURN;
+extern NORETURN void throw_reason (enum return_reason reason) ATTR_NORETURN;
+extern NORETURN void throw_verror (enum errors, const char *fmt,
+                                  va_list ap) ATTR_NORETURN;
+extern NORETURN void throw_vfatal (const char *fmt, va_list ap) ATTR_NORETURN;
+extern NORETURN void throw_error (enum errors error, const char *fmt,
+                                 ...) ATTR_NORETURN ATTR_FORMAT (printf, 2, 3);
 
 /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception
    handler.  If an exception (enum return_reason) is thrown using
@@ -86,13 +122,22 @@ struct ui_out;
 typedef int (catch_exceptions_ftype) (struct ui_out *ui_out, void *args);
 extern int catch_exceptions (struct ui_out *uiout,
                             catch_exceptions_ftype *func, void *func_args,
-                            char *errstring, return_mask mask);
+                            return_mask mask);
+typedef void (catch_exception_ftype) (struct ui_out *ui_out, void *args);
 extern int catch_exceptions_with_msg (struct ui_out *uiout,
                                      catch_exceptions_ftype *func, 
                                      void *func_args,
-                                     char *errstring, char **gdberrmsg,
+                                     char **gdberrmsg,
                                      return_mask mask);
 
+/* This function, in addition, suppresses the printing of the captured
+   error message.  It's up to the client to print it.  */
+
+extern struct exception catch_exception (struct ui_out *uiout,
+                                        catch_exception_ftype *func,
+                                        void *func_args,
+                                        return_mask mask);
+
 /* If CATCH_ERRORS_FTYPE throws an error, catch_errors() returns zero
    otherwize the result from CATCH_ERRORS_FTYPE is returned. It is
    probably useful for CATCH_ERRORS_FTYPE to always return a non-zero