* defs.h (throw_exception): Rename return_to_top_level. Update

comments.
* utils.c (error_stream, internal_verror, quit): Ditto.
* top.c (throw_exception, catcher): Ditto.
* sparclet-rom.c (sparclet_load): Ditto.
* remote.c (interrupt_query, minitelnet): Ditto.
* remote-sds.c (interrupt_query): Ditto.
* remote-mips.c (mips_error, mips_kill): Ditto.
* ocd.c (interrupt_query): Ditto.
* monitor.c (monitor_interrupt_query): Ditto.
* m3-nat.c (suspend_all_threads, thread_resume_command): Ditto.
* target.h: Update comment.

* m3-nat.c, ocd.c, sparclet-rom.c: Update copyright.

gdb/ChangeLog

@@ -1,3 +1,20 @@
+2002-02-09  Andrew Cagney  <ac131313@redhat.com>
+
+	* defs.h (throw_exception): Rename return_to_top_level.  Update
+	comments.
+	* utils.c (error_stream, internal_verror, quit): Ditto.
+	* top.c (throw_exception, catcher): Ditto.
+	* sparclet-rom.c (sparclet_load): Ditto.
+	* remote.c (interrupt_query, minitelnet): Ditto.
+	* remote-sds.c (interrupt_query): Ditto.
+	* remote-mips.c (mips_error, mips_kill): Ditto.
+	* ocd.c (interrupt_query): Ditto.
+	* monitor.c (monitor_interrupt_query): Ditto.
+	* m3-nat.c (suspend_all_threads, thread_resume_command): Ditto.
+	* target.h: Update comment.
+	
+	* m3-nat.c, ocd.c, sparclet-rom.c: Update copyright.
+	
 2002-02-09  Andrew Cagney  <ac131313@redhat.com>
 
 	* gdbarch.sh (TARGET_LONG_DOUBLE_FORMAT): Default to

gdb/defs.h

@@ -1082,7 +1082,7 @@ extern NORETURN void internal_error (const char *file, int line,
 
 extern NORETURN void nomem (long) ATTR_NORETURN;
 
-/* Reasons for calling return_to_top_level.  NOTE: all reason values
+/* Reasons for calling throw_exception().  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
@@ -1105,25 +1105,20 @@ enum return_reason
 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()).
+   to the inner most containing exception handler established using
+   catch_exceptions() (or the legacy catch_errors()).
 
-   Useful when a section of code that caught an exception finds it
-   needs to repropagate that exception up the call chain.
+   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.  */
 
-   The name return_to_top_level() dates back to a time when GDB had
-   only one exception handler installed at the top level.  This really
-   did return to the top level.  The name should probably be changed.
-
-   NOTE: Some sections of code are using error_begin() in conjunction
-   with return_to_top_level() to throw the initial exception.  That
-   code should, instead, use either error() or error_string().  */
-
-extern NORETURN void return_to_top_level (enum return_reason) ATTR_NORETURN;
+extern NORETURN void throw_exception (enum return_reason) ATTR_NORETURN;
 
 /* Call FUNC(UIOUT, FUNC_ARGS) but wrapped within an exception
    handler.  If an exception (enum return_reason) is thrown using
-   return_to_top_level() than all cleanups installed since
+   throw_exception() than all cleanups installed since
    catch_exceptions() was entered are invoked, the (-ve) exception
    value is then returned by catch_exceptions.  If FUNC() returns
    normally (with a postive or zero return value) then that value is

gdb/m3-nat.c

@@ -1,8 +1,8 @@
 /* Interface GDB to Mach 3.0 operating systems.
    (Most) Mach 3.0 related routines live in this file.
 
-   Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001
-   Free Software Foundation, Inc.
+   Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
+   2002 Free Software Foundation, Inc.
 
    This file is part of GDB.
 
@@ -2939,7 +2939,7 @@ suspend_all_threads (int from_tty)
     {
       warning ("Could not suspend inferior threads.");
       m3_kill_inferior ();
-      return_to_top_level (RETURN_ERROR);
+      throw_exception (RETURN_ERROR);
     }
 
   for (index = 0; index < thread_count; index++)
@@ -3108,7 +3108,7 @@ thread_resume_command (char *args, int from_tty)
     {
       if (current_thread)
 	current_thread = saved_thread;
-      return_to_top_level (RETURN_ERROR);
+      throw_exception (RETURN_ERROR);
     }
 
   ret = thread_info (current_thread,

gdb/monitor.c

@@ -1036,7 +1036,7 @@ monitor_interrupt_query (void)
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();

gdb/ocd.c

@@ -1,6 +1,7 @@
 /* Target communications support for Macraigor Systems' On-Chip Debugging
-   Copyright 1996, 1997, 1998, 1999, 2000, 2001
-   Free Software Foundation, Inc.
+
+   Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software
+   Foundation, Inc.
 
    This file is part of GDB.
 
@@ -446,7 +447,7 @@ interrupt_query (void)
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();

gdb/remote-mips.c

@@ -497,7 +497,7 @@ mips_error (char *string,...)
   printf_unfiltered ("Ending remote MIPS debugging.\n");
   target_mourn_inferior ();
 
-  return_to_top_level (RETURN_ERROR);
+  throw_exception (RETURN_ERROR);
 }
 
 /* putc_readable - print a character, displaying non-printable chars in
@@ -2186,7 +2186,7 @@ Give up (and stop debugging it)? "))
 	  printf_unfiltered ("Ending remote MIPS debugging.\n");
 	  target_mourn_inferior ();
 
-	  return_to_top_level (RETURN_QUIT);
+	  throw_exception (RETURN_QUIT);
 	}
 
       target_terminal_inferior ();

gdb/remote-sds.c

@@ -405,7 +405,7 @@ interrupt_query (void)
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();

gdb/remote.c

@@ -2877,7 +2877,7 @@ interrupt_query (void)
 Give up (and stop debugging it)? "))
     {
       target_mourn_inferior ();
-      return_to_top_level (RETURN_QUIT);
+      throw_exception (RETURN_QUIT);
     }
 
   target_terminal_inferior ();
@@ -5717,7 +5717,7 @@ minitelnet (void)
 	      if (query ("Interrupt GDB? "))
 		{
 		  printf_filtered ("Interrupted by user.\n");
-		  return_to_top_level (RETURN_QUIT);
+		  throw_exception (RETURN_QUIT);
 		}
 	      quit_count = 0;
 	    }

gdb/sparclet-rom.c

@@ -1,6 +1,7 @@
 /* Remote target glue for the SPARC Sparclet ROM monitor.
-   Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001
-   Free Software Foundation, Inc.
+
+   Copyright 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free
+   Software Foundation, Inc.
 
    This file is part of GDB.
 
@@ -204,7 +205,7 @@ sparclet_load (struct serial *desc, char *file, int hashmark)
   pop_target ();
   push_remote_target (monitor_get_dev_name (), 1);
 
-  return_to_top_level (RETURN_QUIT);
+  throw_exception (RETURN_QUIT);
 }
 
 /* Define the monitor command strings. Since these are passed directly

gdb/target.h

@@ -438,10 +438,10 @@ extern void target_detach (char *, int);
     (*current_target.to_resume) (ptid, step, siggnal);			\
   } while (0)
 
-/* Wait for process pid to do something.  PTID = -1 to wait for any pid
-   to do something.  Return pid of child, or -1 in case of error;
+/* Wait for process pid to do something.  PTID = -1 to wait for any
+   pid to do something.  Return pid of child, or -1 in case of error;
    store status through argument pointer STATUS.  Note that it is
-   *not* OK to return_to_top_level out of target_wait without popping
+   _NOT_ OK to throw_exception() out of target_wait() without popping
    the debugging target from the stack; GDB isn't prepared to get back
    to the prompt with a debugging target but without the frame cache,
    stop_pc, etc., set up.  */

gdb/top.c

@@ -196,7 +196,7 @@ void (*init_ui_hook) (char *argv0);
 int (*ui_loop_hook) (int);
 
 /* Called instead of command_loop at top level.  Can be invoked via
-   return_to_top_level.  */
+   throw_exception().  */
 
 void (*command_loop_hook) (void);
 
@@ -298,13 +298,13 @@ NORETURN void (*error_hook) (void) ATTR_NORETURN;
 #define SIGLONGJMP(buf,val)	longjmp((buf), (val))
 #endif
 
-/* Where to go for return_to_top_level.  */
+/* Where to go for throw_exception().  */
 static SIGJMP_BUF *catch_return;
 
 /* Return for reason REASON to the nearest containing catch_errors().  */
 
 NORETURN void
-return_to_top_level (enum return_reason reason)
+throw_exception (enum return_reason reason)
 {
   quit_flag = 0;
   immediate_quit = 0;
@@ -340,7 +340,7 @@ return_to_top_level (enum return_reason reason)
 
 /* Call FUNC() with args FUNC_UIOUT and FUNC_ARGS, catching any
    errors.  Set FUNC_CAUGHT to an ``enum return_reason'' if the
-   function is aborted (using return_to_top_level() or zero if the
+   function is aborted (using throw_exception() or zero if the
    function returns normally.  Set FUNC_VAL to the value returned by
    the function or 0 if the function was aborted.
 
@@ -458,7 +458,7 @@ catcher (catch_exceptions_ftype *func,
   /* The caller didn't request that the event be caught, relay the
      event to the next containing catch_errors(). */
 
-  return_to_top_level (caught);
+  throw_exception (caught);
 }
 
 int

gdb/utils.c

@@ -645,7 +645,7 @@ error_stream (struct ui_file *stream)
   ui_file_put (stream, do_write, gdb_stderr);
   fprintf_filtered (gdb_stderr, "\n");
 
-  return_to_top_level (RETURN_ERROR);
+  throw_exception (RETURN_ERROR);
 }
 
 /* Get the last error message issued by gdb */
@@ -728,7 +728,7 @@ Create a core file containing the current state of GDB? ");
     }
 
   dejavu = 0;
-  return_to_top_level (RETURN_ERROR);
+  throw_exception (RETURN_ERROR);
 }
 
 NORETURN void
@@ -850,7 +850,7 @@ quit (void)
     fprintf_unfiltered (gdb_stderr,
 	       "Quit (expect signal SIGINT when the program is resumed)\n");
 #endif
-  return_to_top_level (RETURN_QUIT);
+  throw_exception (RETURN_QUIT);
 }
 
 /* Control C comes here */