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

/* 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.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307, USA.  */

#include "defs.h"
#include "exceptions.h"
#include <setjmp.h>
#include "breakpoint.h"
#include "target.h"
#include "inferior.h"
#include "annotate.h"
#include "ui-out.h"
#include "gdb_assert.h"
#include "gdb_string.h"

const struct exception exception_none = { 0, NO_ERROR, NULL };

/* One should use catch_errors rather than manipulating these
   directly.  */
#if defined(HAVE_SIGSETJMP)
#define SIGJMP_BUF		sigjmp_buf
#define SIGSETJMP(buf)		sigsetjmp((buf), 1)
#define SIGLONGJMP(buf,val)	siglongjmp((buf), (val))
#else
#define SIGJMP_BUF		jmp_buf
#define SIGSETJMP(buf)		setjmp(buf)
#define SIGLONGJMP(buf,val)	longjmp((buf), (val))
#endif

/* Possible catcher states.  */
enum catcher_state {
  /* Initial state, a new catcher has just been created.  */
  CATCHER_CREATED,
  /* The catch code is running.  */
  CATCHER_RUNNING,
  CATCHER_RUNNING_1,
  /* The catch code threw an exception.  */
  CATCHER_ABORTING
};

/* Possible catcher actions.  */
enum catcher_action {
  CATCH_ITER,
  CATCH_ITER_1,
  CATCH_THROWING
};

struct catcher
{
  enum catcher_state state;
  /* Jump buffer pointing back at the exception handler.  */
  SIGJMP_BUF buf;
  /* Status buffer belonging to that exception handler.  */
  volatile struct exception *exception;
  /* Saved/current state.  */
  int mask;
  char *saved_error_pre_print;
  char *saved_quit_pre_print;
  struct ui_out *saved_uiout;
  struct cleanup *saved_cleanup_chain;
  /* Back link.  */
  struct catcher *prev;
};

/* Where to go for throw_exception().  */
static struct catcher *current_catcher;

static SIGJMP_BUF *
catcher_init (struct ui_out *func_uiout,
	      char *errstring,
	      volatile struct exception *exception,
	      return_mask mask)
{
  struct catcher *new_catcher = XZALLOC (struct catcher);

  /* Start with no exception, save it's address.  */
  exception->reason = 0;
  exception->error = NO_ERROR;
  exception->message = NULL;
  new_catcher->exception = exception;

  new_catcher->mask = mask;

  /* Override error/quit messages during FUNC. */
  new_catcher->saved_error_pre_print = error_pre_print;
  new_catcher->saved_quit_pre_print = quit_pre_print;
  if (mask & RETURN_MASK_ERROR)
    error_pre_print = errstring;
  if (mask & RETURN_MASK_QUIT)
    quit_pre_print = errstring;

  /* Override the global ``struct ui_out'' builder.  */
  new_catcher->saved_uiout = uiout;
  uiout = func_uiout;

  /* Prevent error/quit during FUNC from calling cleanups established
     prior to here. */
  new_catcher->saved_cleanup_chain = save_cleanups ();

  /* Push this new catcher on the top.  */
  new_catcher->prev = current_catcher;
  current_catcher = new_catcher;
  new_catcher->state = CATCHER_CREATED;

  return &new_catcher->buf;
}

static void
catcher_pop (void)
{
  struct catcher *old_catcher = current_catcher;
  current_catcher = old_catcher->prev;

  /* Restore the cleanup chain, the error/quit messages, and the uiout
     builder, to their original states. */

  restore_cleanups (old_catcher->saved_cleanup_chain);

  uiout = old_catcher->saved_uiout;

  quit_pre_print = old_catcher->saved_quit_pre_print;
  error_pre_print = old_catcher->saved_error_pre_print;

  xfree (old_catcher);
}

/* Catcher state machine.  Returns non-zero if the m/c should be run
   again, zero if it should abort.  */

int
catcher_state_machine (enum catcher_action action)
{
  switch (current_catcher->state)
    {
    case CATCHER_CREATED:
      switch (action)
	{
	case CATCH_ITER:
	  /* Allow the code to run the catcher.  */
	  current_catcher->state = CATCHER_RUNNING;
	  return 1;
	default:
	  internal_error (__FILE__, __LINE__, "bad state");
	}
    case CATCHER_RUNNING:
      switch (action)
	{
	case CATCH_ITER:
	  /* No error/quit has occured.  Just clean up.  */
	  catcher_pop ();
	  return 0;
	case CATCH_ITER_1:
	  current_catcher->state = CATCHER_RUNNING_1;
	  return 1;
	case CATCH_THROWING:
	  current_catcher->state = CATCHER_ABORTING;
	  /* See also throw_exception.  */
	  return 1;
	default:
	  internal_error (__FILE__, __LINE__, "bad switch");
	}
    case CATCHER_RUNNING_1:
      switch (action)
	{
	case CATCH_ITER:
	  /* The did a "break" from the inner while loop.  */
	  catcher_pop ();
	  return 0;
	case CATCH_ITER_1:
	  current_catcher->state = CATCHER_RUNNING;
	  return 0;
	case CATCH_THROWING:
	  current_catcher->state = CATCHER_ABORTING;
	  /* See also throw_exception.  */
	  return 1;
	default:
	  internal_error (__FILE__, __LINE__, "bad switch");
	}
    case CATCHER_ABORTING:
      switch (action)
	{
	case CATCH_ITER:
	  {
	    struct exception exception = *current_catcher->exception;
	    if (current_catcher->mask & RETURN_MASK (exception.reason))
	      {
		/* Exit normally if this catcher can handle this
		   exception.  The caller analyses the func return
		   values.  */
		catcher_pop ();
		return 0;
	      }
	    /* The caller didn't request that the event be caught,
	       relay the event to the next containing
	       catch_errors(). */
	    catcher_pop ();
	    throw_exception (exception);
	  }
	default:
	  internal_error (__FILE__, __LINE__, "bad state");
	}
    default:
      internal_error (__FILE__, __LINE__, "bad switch");
    }
}

/* Return EXCEPTION to the nearest containing catch_errors().  */

NORETURN void
throw_exception (struct exception exception)
{
  quit_flag = 0;
  immediate_quit = 0;

  /* Perhaps it would be cleaner to do this via the cleanup chain (not sure
     I can think of a reason why that is vital, though).  */
  bpstat_clear_actions (stop_bpstat);	/* Clear queued breakpoint commands */

  disable_current_display ();
  do_cleanups (ALL_CLEANUPS);
  if (target_can_async_p () && !target_executing)
    do_exec_cleanups (ALL_CLEANUPS);
  if (sync_execution)
    do_exec_error_cleanups (ALL_CLEANUPS);

  if (annotation_level > 1)
    switch (exception.reason)
      {
      case RETURN_QUIT:
	annotate_quit ();
	break;
      case RETURN_ERROR:
	/* Assume that these are all errors.  */
	annotate_error ();
	break;
      default:
	internal_error (__FILE__, __LINE__, "Bad switch.");
      }

  /* Jump to the containing catch_errors() call, communicating REASON
     to that call via setjmp's return value.  Note that REASON can't
     be zero, by definition in defs.h. */
  catcher_state_machine (CATCH_THROWING);
  *current_catcher->exception = exception;
  SIGLONGJMP (current_catcher->buf, exception.reason);
}

NORETURN void
throw_reason (enum return_reason reason)
{
  struct exception exception;
  memset (&exception, 0, sizeof exception);

  exception.reason = reason;
  switch (reason)
    {
    case RETURN_QUIT:
      break;
    case RETURN_ERROR:
      exception.error = GENERIC_ERROR;
      exception.message = error_last_message ();
      break;
    default:
      internal_error (__FILE__, __LINE__, "bad switch");
    }
  
  throw_exception (exception);
}

/* 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 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.

   Must not be called with immediate_quit in effect (bad things might
   happen, say we got a signal in the middle of a memcpy to quit_return).
   This is an OK restriction; with very few exceptions immediate_quit can
   be replaced by judicious use of QUIT.

   MASK specifies what to catch; it is normally set to
   RETURN_MASK_ALL, if for no other reason than that the code which
   calls catch_errors might not be set up to deal with a quit which
   isn't caught.  But if the code can deal with it, it generally
   should be RETURN_MASK_ERROR, unless for some reason it is more
   useful to abort only the portion of the operation inside the
   catch_errors.  Note that quit should return to the command line
   fairly quickly, even if some further processing is being done.  */

/* MAYBE: cagney/1999-11-05: catch_errors() in conjunction with
   error() et.al. could maintain a set of flags that indicate the the
   current state of each of the longjmp buffers.  This would give the
   longjmp code the chance to detect a longjmp botch (before it gets
   to longjmperror()).  Prior to 1999-11-05 this wasn't possible as
   code also randomly used a SET_TOP_LEVEL macro that directly
   initialize the longjmp buffers. */

/* MAYBE: cagney/1999-11-05: Should the catch_errors and cleanups code
   be consolidated into a single file instead of being distributed
   between utils.c and top.c? */

int
catch_exceptions (struct ui_out *uiout,
		  catch_exceptions_ftype *func,
		  void *func_args,
		  char *errstring,
		  return_mask mask)
{
  return catch_exceptions_with_msg (uiout, func, func_args, errstring,
				    NULL, mask);
}

struct exception
catch_exception (struct ui_out *uiout,
		 catch_exception_ftype *func,
		 void *func_args,
		 return_mask mask)
{
  volatile struct exception exception;
  SIGJMP_BUF *catch;
  catch = catcher_init (uiout, NULL, &exception, mask);
  for (SIGSETJMP ((*catch));
       catcher_state_machine (CATCH_ITER);)
    (*func) (uiout, func_args);
  return exception;
}

int
catch_exceptions_with_msg (struct ui_out *uiout,
		  	   catch_exceptions_ftype *func,
		  	   void *func_args,
		  	   char *errstring,
			   char **gdberrmsg,
		  	   return_mask mask)
{
  volatile struct exception exception;
  volatile int val = 0;
  SIGJMP_BUF *catch = catcher_init (uiout, errstring, &exception, mask);
  for (SIGSETJMP ((*catch)); catcher_state_machine (CATCH_ITER);)
    val = (*func) (uiout, func_args);
  gdb_assert (val >= 0);
  gdb_assert (exception.reason <= 0);
  if (exception.reason < 0)
    {
      /* If caller wants a copy of the low-level error message, make
	 one.  This is used in the case of a silent error whereby the
	 caller may optionally want to issue the message.  */
      if (gdberrmsg != NULL)
	*gdberrmsg = exception.message;
      return exception.reason;
    }
  return val;
}

int
catch_errors (catch_errors_ftype *func, void *func_args, char *errstring,
	      return_mask mask)
{
  volatile int val = 0;
  volatile struct exception exception;
  SIGJMP_BUF *catch = catcher_init (uiout, errstring, &exception, mask);
  /* This illustrates how it is possible to nest the mechanism and
     hence catch "break".  Of course this doesn't address the need to
     also catch "return".  */
  for (SIGSETJMP ((*catch)); catcher_state_machine (CATCH_ITER);)
    val = func (func_args);
  if (exception.reason != 0)
    return 0;
  return val;
}

struct captured_command_args
  {
    catch_command_errors_ftype *command;
    char *arg;
    int from_tty;
  };

static int
do_captured_command (void *data)
{
  struct captured_command_args *context = data;
  context->command (context->arg, context->from_tty);
  /* FIXME: cagney/1999-11-07: Technically this do_cleanups() call
     isn't needed.  Instead an assertion check could be made that
     simply confirmed that the called function correctly cleaned up
     after itself.  Unfortunately, old code (prior to 1999-11-04) in
     main.c was calling SET_TOP_LEVEL(), calling the command function,
     and then *always* calling do_cleanups().  For the moment we
     remain ``bug compatible'' with that old code..  */
  do_cleanups (ALL_CLEANUPS);
  return 1;
}

int
catch_command_errors (catch_command_errors_ftype * command,
		      char *arg, int from_tty, return_mask mask)
{
  struct captured_command_args args;
  args.command = command;
  args.arg = arg;
  args.from_tty = from_tty;
  return catch_errors (do_captured_command, &args, "", mask);
}
Commit	Line	Data
60250e8b AC	1	/* Exception (throw catch) mechanism, for GDB, the GNU debugger.
	2
	3	Copyright 1986, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
	4	1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software
	5	Foundation, Inc.
	6
	7	This file is part of GDB.
	8
	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.
	13
	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.
	18
	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. */
	23
	24	#include "defs.h"
	25	#include "exceptions.h"
	26	#include <setjmp.h>
	27	#include "breakpoint.h"
	28	#include "target.h"
	29	#include "inferior.h"
	30	#include "annotate.h"
	31	#include "ui-out.h"
	32	#include "gdb_assert.h"
db5f402d	33	#include "gdb_string.h"
60250e8b	34
c1043fc2 AC	35	const struct exception exception_none = { 0, NO_ERROR, NULL };
c1043fc2 AC	36
60250e8b AC	37	/* One should use catch_errors rather than manipulating these
	38	directly. */
	39	#if defined(HAVE_SIGSETJMP)
	40	#define SIGJMP_BUF sigjmp_buf
	41	#define SIGSETJMP(buf) sigsetjmp((buf), 1)
	42	#define SIGLONGJMP(buf,val) siglongjmp((buf), (val))
	43	#else
	44	#define SIGJMP_BUF jmp_buf
	45	#define SIGSETJMP(buf) setjmp(buf)
	46	#define SIGLONGJMP(buf,val) longjmp((buf), (val))
	47	#endif
	48
db5f402d AC	49	/* Possible catcher states. */
	50	enum catcher_state {
	51	/* Initial state, a new catcher has just been created. */
	52	CATCHER_CREATED,
	53	/* The catch code is running. */
	54	CATCHER_RUNNING,
	55	CATCHER_RUNNING_1,
	56	/* The catch code threw an exception. */
	57	CATCHER_ABORTING
	58	};
	59
	60	/* Possible catcher actions. */
	61	enum catcher_action {
	62	CATCH_ITER,
	63	CATCH_ITER_1,
	64	CATCH_THROWING
	65	};
	66
	67	struct catcher
	68	{
	69	enum catcher_state state;
2a78bfb5	70	/* Jump buffer pointing back at the exception handler. */
db5f402d	71	SIGJMP_BUF buf;
2a78bfb5 AC	72	/* Status buffer belonging to that exception handler. */
2a78bfb5 AC	73	volatile struct exception *exception;
db5f402d AC	74	/* Saved/current state. */
	75	int mask;
	76	char *saved_error_pre_print;
	77	char *saved_quit_pre_print;
	78	struct ui_out *saved_uiout;
	79	struct cleanup *saved_cleanup_chain;
db5f402d AC	80	/* Back link. */
	81	struct catcher *prev;
	82	};
	83
60250e8b	84	/* Where to go for throw_exception(). */
db5f402d AC	85	static struct catcher *current_catcher;
	86
	87	static SIGJMP_BUF *
	88	catcher_init (struct ui_out *func_uiout,
	89	char *errstring,
2a78bfb5	90	volatile struct exception *exception,
db5f402d AC	91	return_mask mask)
	92	{
	93	struct catcher *new_catcher = XZALLOC (struct catcher);
	94
2a78bfb5 AC	95	/* Start with no exception, save it's address. */
	96	exception->reason = 0;
	97	exception->error = NO_ERROR;
	98	exception->message = NULL;
	99	new_catcher->exception = exception;
	100
db5f402d AC	101	new_catcher->mask = mask;
	102
	103	/* Override error/quit messages during FUNC. */
	104	new_catcher->saved_error_pre_print = error_pre_print;
	105	new_catcher->saved_quit_pre_print = quit_pre_print;
	106	if (mask & RETURN_MASK_ERROR)
	107	error_pre_print = errstring;
	108	if (mask & RETURN_MASK_QUIT)
	109	quit_pre_print = errstring;
	110
	111	/* Override the global ``struct ui_out'' builder. */
	112	new_catcher->saved_uiout = uiout;
	113	uiout = func_uiout;
	114
	115	/* Prevent error/quit during FUNC from calling cleanups established
	116	prior to here. */
	117	new_catcher->saved_cleanup_chain = save_cleanups ();
	118
	119	/* Push this new catcher on the top. */
	120	new_catcher->prev = current_catcher;
	121	current_catcher = new_catcher;
	122	new_catcher->state = CATCHER_CREATED;
	123
	124	return &new_catcher->buf;
	125	}
	126
	127	static void
	128	catcher_pop (void)
	129	{
	130	struct catcher *old_catcher = current_catcher;
	131	current_catcher = old_catcher->prev;
	132
	133	/* Restore the cleanup chain, the error/quit messages, and the uiout
	134	builder, to their original states. */
	135
	136	restore_cleanups (old_catcher->saved_cleanup_chain);
	137
	138	uiout = old_catcher->saved_uiout;
	139
	140	quit_pre_print = old_catcher->saved_quit_pre_print;
	141	error_pre_print = old_catcher->saved_error_pre_print;
	142
	143	xfree (old_catcher);
	144	}
	145
	146	/* Catcher state machine. Returns non-zero if the m/c should be run
	147	again, zero if it should abort. */
	148
	149	int
	150	catcher_state_machine (enum catcher_action action)
	151	{
	152	switch (current_catcher->state)
	153	{
	154	case CATCHER_CREATED:
	155	switch (action)
	156	{
	157	case CATCH_ITER:
	158	/* Allow the code to run the catcher. */
	159	current_catcher->state = CATCHER_RUNNING;
	160	return 1;
	161	default:
	162	internal_error (__FILE__, __LINE__, "bad state");
	163	}
	164	case CATCHER_RUNNING:
165	switch (action)
166	{
167	case CATCH_ITER:
168	/* No error/quit has occured. Just clean up. */
169	catcher_pop ();
170	return 0;
171	case CATCH_ITER_1:
172	current_catcher->state = CATCHER_RUNNING_1;
173	return 1;
174	case CATCH_THROWING:
175	current_catcher->state = CATCHER_ABORTING;
176	/* See also throw_exception. */
177	return 1;
178	default:
179	internal_error (__FILE__, __LINE__, "bad switch");
180	}
181	case CATCHER_RUNNING_1:
182	switch (action)
183	{
184	case CATCH_ITER:
185	/* The did a "break" from the inner while loop. */
186	catcher_pop ();
187	return 0;
188	case CATCH_ITER_1:
189	current_catcher->state = CATCHER_RUNNING;
190	return 0;
191	case CATCH_THROWING:
192	current_catcher->state = CATCHER_ABORTING;
193	/* See also throw_exception. */
194	return 1;
195	default:
196	internal_error (__FILE__, __LINE__, "bad switch");
197	}
198	case CATCHER_ABORTING:
199	switch (action)
200	{
201	case CATCH_ITER:
202	{
2a78bfb5 AC	203	struct exception exception = *current_catcher->exception;
2a78bfb5 AC	204	if (current_catcher->mask & RETURN_MASK (exception.reason))
db5f402d AC	205	{
	206	/* Exit normally if this catcher can handle this
	207	exception. The caller analyses the func return
	208	values. */
	209	catcher_pop ();
	210	return 0;
	211	}
	212	/* The caller didn't request that the event be caught,
	213	relay the event to the next containing
	214	catch_errors(). */
	215	catcher_pop ();
2a78bfb5	216	throw_exception (exception);
db5f402d AC	217	}
	218	default:
	219	internal_error (__FILE__, __LINE__, "bad state");
	220	}
	221	default:
	222	internal_error (__FILE__, __LINE__, "bad switch");
	223	}
	224	}
60250e8b	225
2a78bfb5	226	/* Return EXCEPTION to the nearest containing catch_errors(). */
60250e8b AC	227
60250e8b AC	228	NORETURN void
2a78bfb5	229	throw_exception (struct exception exception)
60250e8b AC	230	{
	231	quit_flag = 0;
	232	immediate_quit = 0;
	233
	234	/* Perhaps it would be cleaner to do this via the cleanup chain (not sure
	235	I can think of a reason why that is vital, though). */
	236	bpstat_clear_actions (stop_bpstat); /* Clear queued breakpoint commands */
	237
	238	disable_current_display ();
	239	do_cleanups (ALL_CLEANUPS);
	240	if (target_can_async_p () && !target_executing)
	241	do_exec_cleanups (ALL_CLEANUPS);
	242	if (sync_execution)
	243	do_exec_error_cleanups (ALL_CLEANUPS);
	244
	245	if (annotation_level > 1)
2a78bfb5	246	switch (exception.reason)
60250e8b AC	247	{
	248	case RETURN_QUIT:
	249	annotate_quit ();
	250	break;
	251	case RETURN_ERROR:
2a78bfb5	252	/* Assume that these are all errors. */
60250e8b AC	253	annotate_error ();
60250e8b AC	254	break;
2a78bfb5 AC	255	default:
2a78bfb5 AC	256	internal_error (__FILE__, __LINE__, "Bad switch.");
60250e8b AC	257	}
	258
	259	/* Jump to the containing catch_errors() call, communicating REASON
	260	to that call via setjmp's return value. Note that REASON can't
	261	be zero, by definition in defs.h. */
db5f402d	262	catcher_state_machine (CATCH_THROWING);
2a78bfb5 AC	263	*current_catcher->exception = exception;
	264	SIGLONGJMP (current_catcher->buf, exception.reason);
	265	}
	266
	267	NORETURN void
	268	throw_reason (enum return_reason reason)
	269	{
	270	struct exception exception;
	271	memset (&exception, 0, sizeof exception);
	272
	273	exception.reason = reason;
	274	switch (reason)
	275	{
	276	case RETURN_QUIT:
	277	break;
	278	case RETURN_ERROR:
	279	exception.error = GENERIC_ERROR;
	280	exception.message = error_last_message ();
	281	break;
	282	default:
	283	internal_error (__FILE__, __LINE__, "bad switch");
	284	}
	285
	286	throw_exception (exception);
60250e8b AC	287	}
	288
	289	/* Call FUNC() with args FUNC_UIOUT and FUNC_ARGS, catching any
	290	errors. Set FUNC_CAUGHT to an ``enum return_reason'' if the
	291	function is aborted (using throw_exception() or zero if the
	292	function returns normally. Set FUNC_VAL to the value returned by
	293	the function or 0 if the function was aborted.
	294
	295	Must not be called with immediate_quit in effect (bad things might
	296	happen, say we got a signal in the middle of a memcpy to quit_return).
	297	This is an OK restriction; with very few exceptions immediate_quit can
	298	be replaced by judicious use of QUIT.
	299
	300	MASK specifies what to catch; it is normally set to
	301	RETURN_MASK_ALL, if for no other reason than that the code which
	302	calls catch_errors might not be set up to deal with a quit which
	303	isn't caught. But if the code can deal with it, it generally
	304	should be RETURN_MASK_ERROR, unless for some reason it is more
	305	useful to abort only the portion of the operation inside the
	306	catch_errors. Note that quit should return to the command line
	307	fairly quickly, even if some further processing is being done. */
	308
	309	/* MAYBE: cagney/1999-11-05: catch_errors() in conjunction with
	310	error() et.al. could maintain a set of flags that indicate the the
	311	current state of each of the longjmp buffers. This would give the
	312	longjmp code the chance to detect a longjmp botch (before it gets
	313	to longjmperror()). Prior to 1999-11-05 this wasn't possible as
	314	code also randomly used a SET_TOP_LEVEL macro that directly
	315	initialize the longjmp buffers. */
	316
	317	/* MAYBE: cagney/1999-11-05: Should the catch_errors and cleanups code
	318	be consolidated into a single file instead of being distributed
	319	between utils.c and top.c? */
	320
60250e8b AC	321	int
	322	catch_exceptions (struct ui_out *uiout,
	323	catch_exceptions_ftype *func,
	324	void *func_args,
	325	char *errstring,
	326	return_mask mask)
	327	{
db5f402d AC	328	return catch_exceptions_with_msg (uiout, func, func_args, errstring,
db5f402d AC	329	NULL, mask);
60250e8b AC	330	}
60250e8b AC	331
2a78bfb5 AC	332	struct exception
	333	catch_exception (struct ui_out *uiout,
	334	catch_exception_ftype *func,
	335	void *func_args,
	336	return_mask mask)
	337	{
	338	volatile struct exception exception;
	339	SIGJMP_BUF *catch;
	340	catch = catcher_init (uiout, NULL, &exception, mask);
	341	for (SIGSETJMP ((*catch));
	342	catcher_state_machine (CATCH_ITER);)
	343	(*func) (uiout, func_args);
	344	return exception;
	345	}
	346
60250e8b AC	347	int
	348	catch_exceptions_with_msg (struct ui_out *uiout,
	349	catch_exceptions_ftype *func,
	350	void *func_args,
	351	char *errstring,
	352	char **gdberrmsg,
	353	return_mask mask)
	354	{
2a78bfb5 AC	355	volatile struct exception exception;
	356	volatile int val = 0;
	357	SIGJMP_BUF *catch = catcher_init (uiout, errstring, &exception, mask);
	358	for (SIGSETJMP ((*catch)); catcher_state_machine (CATCH_ITER);)
db5f402d	359	val = (*func) (uiout, func_args);
60250e8b	360	gdb_assert (val >= 0);
2a78bfb5 AC	361	gdb_assert (exception.reason <= 0);
	362	if (exception.reason < 0)
	363	{
	364	/* If caller wants a copy of the low-level error message, make
	365	one. This is used in the case of a silent error whereby the
	366	caller may optionally want to issue the message. */
	367	if (gdberrmsg != NULL)
	368	*gdberrmsg = exception.message;
	369	return exception.reason;
	370	}
60250e8b AC	371	return val;
	372	}
	373
60250e8b AC	374	int
	375	catch_errors (catch_errors_ftype func, void func_args, char *errstring,
	376	return_mask mask)
	377	{
2a78bfb5 AC	378	volatile int val = 0;
	379	volatile struct exception exception;
	380	SIGJMP_BUF *catch = catcher_init (uiout, errstring, &exception, mask);
db5f402d AC	381	/* This illustrates how it is possible to nest the mechanism and
	382	hence catch "break". Of course this doesn't address the need to
	383	also catch "return". */
2a78bfb5 AC	384	for (SIGSETJMP ((*catch)); catcher_state_machine (CATCH_ITER);)
	385	val = func (func_args);
	386	if (exception.reason != 0)
60250e8b AC	387	return 0;
	388	return val;
	389	}
	390
	391	struct captured_command_args
	392	{
	393	catch_command_errors_ftype *command;
	394	char *arg;
	395	int from_tty;
	396	};
	397
	398	static int
	399	do_captured_command (void *data)
	400	{
	401	struct captured_command_args *context = data;
	402	context->command (context->arg, context->from_tty);
	403	/* FIXME: cagney/1999-11-07: Technically this do_cleanups() call
	404	isn't needed. Instead an assertion check could be made that
	405	simply confirmed that the called function correctly cleaned up
	406	after itself. Unfortunately, old code (prior to 1999-11-04) in
	407	main.c was calling SET_TOP_LEVEL(), calling the command function,
	408	and then always calling do_cleanups(). For the moment we
	409	remain ``bug compatible'' with that old code.. */
	410	do_cleanups (ALL_CLEANUPS);
	411	return 1;
	412	}
	413
	414	int
	415	catch_command_errors (catch_command_errors_ftype * command,
	416	char *arg, int from_tty, return_mask mask)
	417	{
	418	struct captured_command_args args;
	419	args.command = command;
	420	args.arg = arg;
	421	args.from_tty = from_tty;
	422	return catch_errors (do_captured_command, &args, "", mask);
	423	}