generic/utilities/ascSignal.h

/*  ASCEND modelling environment
    Copyright (C) 1997 Benjamin Andrew Allan
    Copyright (C) 2006 Carnegie Mellon University

    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, 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.
*//**
    @file
    Signal handling protocol definitions for ASCEND.

    This file standardizes the handling of signals because some OS
    reset signals to SIG_DFL when a trap goes off while others
    process the signal but leave the trapping function in place.
    We want the second behavior and this gives it to us.

    This module implements limited support for managing signal handlers.
    This includes:
      - a standard signal handler - Asc_SignalTrap()
      - global jmp_buf's for use with Asc_SignalTrap()
      - functions for managing nested signal handlers
    
    The following signal types are currently supported:
      - SIGFPE  - floating point exception
      - SIGINT  - CTRL-C interactive attention request
      - SIGSEGV - segmentation fault
    
    A simple use of these facilities to trap floating point exceptions
    might be as follows:
    <pre>
       Asc_SignalInit();
       Asc_SignalHandlerPush(SIGFPE, Asc_SignalTrap);
       if (setjmp(g_fpe_env)==0) {
         y = sqrt(x);
       } else {
         y = sqrt(-x);
       }
       Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
       Asc_SignalDestroy();
    </pre>

    This example uses the built-in signal handler Asc_SignalTrap()
    and the global <code>jmp_buf</code> g_fpe_env.  After initializing
    the signal manager and registering the handler, <code>setjmp</code>
    is used to select normal and exception paths.  The <code>setjmp</code>
    returns 0 when initially called and the sqrt(x) is calculated.  If
    x is negative, a SIGFPE exception occurs and the handler is called.  It
    uses <code>lngjmp</code> and returns to the if statement, and now
    'setjmp' returns non-zero and the <code>else</code> clause is executed.
    Finally, the handler is removed and the signal manager cleaned up.<br><br>
    
    The stack mechanism also allows nested handlers to be registered.  It is
    important to note that nested handlers for the same signal type cannot
    both use Asc_SignalTrap() as the handler.  This is because different
    <code>jmp_buf</code> variables must be used and Asc_SignalTrap() uses
    the same global <code>jmp_buf</code> each time.  However, you can use
    custome <code>jmp_buf</code>'s and handlers:

    <pre>
       Asc_SignalInit();
       Asc_SignalHandlerPush(SIGFPE, Asc_SignalTrap);
       if (setjmp(g_fpe_env) == 0) {
           y = sqrt(x);
           Asc_SignalHandlerPush(SIGFPE, my_handler);
           if (setjmp(my_jmp_buf) == 0) {
               y = z/x;
           } else {
               Asc_Panic(1, NULL, "Div by zero error.");
           }
           Asc_SignHandlerPop(SIGFPE, my_handler);
       } else {
         y = sqrt(-x);
       }
       Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
       Asc_SignalDestroy();
    </pre>
    
    Here, exceptions in the sqrt(x) calculation are handled by the standard
    Asc_SignalTrap(), while the division is handled by my_handler.<br><br>
    
    Avoid mixing use of the signal manager with direct calls to signal().
    Once Asc_SignalInit() has been called, use of signal() directly is likely
    to be lost or to corrupt the managed handlers.<br><br>
    
    Another warning: setjmp is expensive if called inside a fast loop.

    Requires:
    #include "utilities/ascConfig.h"
*//*
    by Benjamin Andrew Allan, May 27, 1997
    Last in CVS: $Revision: 1.6 $ $Date: 1998/01/10 18:00:05 $ $Author: ballan $
*/

#ifndef ASC_ASCSIGNAL_H
#define ASC_ASCSIGNAL_H

#include <signal.h>
#include <setjmp.h>
#include "utilities/ascConfig.h"

#ifdef __WIN32__
#  include <process.h>
#else
#  include <unistd.h>
#endif

#ifdef __WIN32__
# define FPRESET _fpreset()
#else
# define FPRESET (void)0
#endif

typedef void SigHandlerFn(int);
/**< Signature of a signal handling function. */

#define MAX_TRAP_DEPTH 40L
/**< The maximum number of traps that can be nested. */

#define ASC_JMP_INFO
/**< Whether to store additional information before making a setjmp call */

#ifndef ASC_JMP_INFO
# define SETJMP set_jmp
# define LONGJMP longjmp
# define SIGNAL signal
typedef JMP_BUF jmp_buf
#else
# define SETJMP(ENV) (\
        CONSOLE_DEBUG("SETJMP at %s:%d (%s=%p)",__FILE__,__LINE__,#ENV,ENV.jmp)\
        ,ENV.filename = __FILE__, ENV.line = __LINE__, ENV.func = __FUNCTION__\
        ,ENV.varname = #ENV\
        , setjmp(ENV.jmp)\
    )
# define LONGJMP(ENV,VAL) (\
        CONSOLE_DEBUG("LONGJMP to %s:%d (%s) (%s=%p)",ENV.filename,ENV.line,ENV.func,ENV.varname,ENV.jmp)\
        , longjmp(ENV.jmp, VAL)\
    )
typedef struct{
    jmp_buf jmp;
    const char *filename;
    int line;
    const char *func;
    const char *varname;
} asc_jmp_buf;
#define JMP_BUF asc_jmp_buf
#define SIGNAL(SIG,HANDLER) (CONSOLE_DEBUG("SIGNAL(%d,%s)",SIG,#HANDLER),signal(SIG,HANDLER))
#endif


ASC_DLLSPEC(JMP_BUF) g_fpe_env;   /**< Standard signal jmp_buf - floating point error. */
ASC_DLLSPEC(JMP_BUF) g_seg_env;   /**< Standard signal jmp_buf - segmentation fault. */
ASC_DLLSPEC(JMP_BUF) g_int_env;   /**< Standard signal jmp_buf - interactive attention (<CTRL>C). */

#if 0
extern jmp_buf g_foreign_code_call_env;
/**<
    Not currently in use.  Should be when we get to a unified
    standard for signal handling.
    @todo Implement use of g_foreign_code_call_env?
*/
#endif

ASC_DLLSPEC(void ) Asc_SignalTrap(int sigval);
/**<
 *  Standard signal handler.
 *  This is the trap that should be used for most applications in
 *  ASCEND.  It prints a message then calls longjmp(GLOBAL, sigval)
 *  where GLOBAL is one of g_fpe_env, g_seg_env, or g_int_env.
 *  Because the jmp_buf is global, so you can't nest calls to
 *  setjmp where both use this trap function.<br><br>
 *
 *  Trivial Example:
 *  <pre>
 *     Asc_SignalHandlerPush(SIGFPE,Asc_SignalTrap);
 *     if (setjmp(g_fpe_env)==0) {
 *       y = sqrt(x);
 *     } else {
 *       y = sqrt(-x);
 *     }
 *     Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
 *
 *  For x < 0 the else is called because setjmp returns nonzero
 *  when the body of the 'if' signals range error.
 *  </pre>
 *  Remember always to use Asc_SignalHandlerPush() and
 *  Asc_SignalHandlerPop(). You can write an alternate function
 *  to use instead of AscSignalTrap() if need be.  The signals
 *  SIGFPE, SIGINT, SIGSEGV are understood.<br><br>
 *
 *  Note - this handler does not reinstall itself.  After an exception,
 *  you need to reinstall the handler (if desired) using
 *  Asc_SignalRecover().
 *
 *  @todo Should utilities/ascSignal.c:Asc_SignalTrap() reinstall itself
 *        after it catches an expection using Asc_SignalRecover()?
 *  @param sigval Holds the signal type code when called during
 *                an exception.
 */

ASC_DLLSPEC(int ) Asc_SignalInit(void);
/**<
 *  Initializes the signal manager.
 *  This should be called before using any of the signal handling
 *  functions in this module.  It initializes the internal stacks
 *  for mangaging signal handlers.  This function does not install
 *  any signal handlers (although any existing handlers are left
 *  in place).  Calling this function more than once will have no
 *  effect and an error code will be returned.<br><br>
 *
 *  @return Returns 0 if successful, 1 if memory could not be
 *          allocated, and 2 if an error occurred.
 */

ASC_DLLSPEC(void ) Asc_SignalDestroy(void);
/**<
 *  Cleans up and destroys the stacks of signal handlers.
 *  It does not change the status of any registered signal handlers
 *  That is, any handlers registered when this function is called
 *  will still be registered.  It is important to call
 *  Asc_SignalHandlerPop() for each occurrence of Asc_SignalHandlerPush()
 *  before calling this function.  Otherwise, any signal handlers
 *  that were installed before Asc_SignalInit() was called will be lost.
 */

ASC_DLLSPEC(void ) Asc_SignalRecover(int force);
/**<
 *  Reinstalls the most recently pushed handler that has been
 *  installed for each supported signal type.  This should be called
 *  after every trapped exception and at any other time when the
 *  status of exception handlers may have become not well-defined.
 *  If no handler has been pushed for a given signal type, SIG_DFL is
 *  installed.  Note that the standard handler function Asc_SignalTrap()
 *  does not call this function.  If you use the standard handler and
 *  you want it reinstalled after an exception, be sure to call this
 *  function after the longjmp return.  This call is not particularly
 *  cheap if it does the reinstallation.<br><br>
 *
 *  This module tests on startup for whether the OS reverts to
 *  SIG_DFL when a trap function is called.  If it does NOT then
 *  this function will simply return unless force != 0. You don't
 *  want to call this function with force == 1 normally after a
 *  caught exception.  However, if you're not sure of the handler
 *  installation status and want to make sure the handlers are
 *  installed, call with force == 1.  Also, gdb or other
 *  debuggers which intercept and screw up signals may require
 *  applying force (manually) to ensure that the signals get
 *  reinstalled.
 *
 *  @param force If non-zero, the most recent handlers are
 *               reinstalled even if not required by the
 *               compiler/platform.
 */

ASC_DLLSPEC(int ) Asc_SignalHandlerPushDefault(int signum);
ASC_DLLSPEC(int ) Asc_SignalHandlerPush(int signum, SigHandlerFn *func);
/**<
 * Adds a handler to the stack of signal handlers for the given signal.
 * There is a maximum stack limit, so returns 1 if limit exceeded.
 * Returns -1 if stack of signal requested does not exist.
 * Pushing a NULL handler func does NOT change anything at all.
 * On a successful return, the handler has been installed and will
 * remain installed until a Asc_SignalHandlerPop() or another push.
 * The handler will remain installed as long as Asc_SignalRecover()
 * is used properly after every exception.
 *
 *  @param signum The signal type that func should handle.
 *  @param func   The signal handler to register for signum signal types.
 *  @return Returns 1 if the stack limit is exceeded, -1 if managing
 *          of signals for the specified signum is not supported or
 *          initialized, or 0 if the function completes successfully.
 *  @todo Shouldn't utilities/ascSignal.c:Asc_SignalHandlerPush() return
 *        an error code on a NULL func?  It seems too easy for someone to
 *        accidentally push a NULL without realizing it, and then later
 *        popping an unintended handler.
 */

ASC_DLLSPEC(int ) Asc_SignalHandlerPopDefault(int signum);
ASC_DLLSPEC(int ) Asc_SignalHandlerPop(int signum, SigHandlerFn *func);
/**<
 *  Removes the last-pushed handler from the stack for signum signal types.
 *  If the removed handler is the same as func, it is uninstalled and
 *  replaced with the handler now at the top of the stack.  If not, non-zero
 *  is returned and you need to call Asc_SignalRecover() to uninstall the
 *  current handler if desired.  Note that the top handler is popped off
 *  the stack whether it matches func or not.  Non-zero is also returned if
 *  the stack is empty.  A side effect is that all managed signal types will
 *  have the registered handlers reinstalled.
 *
 *  @param signum The signal type whose top-most handler should be replaced.
 *  @param func   The handler function that should be at the top of the
 *                stack (and currently installed) for signals of type signum.
 *  @return Returns non-zero if func is not the replaced handler or if
 *          the stack is empty, 0 if the function completed successfully.
 *  @todo Does it make more sense for utilities/ascSignal.c:Asc_SignalHanderPop()
 *        to fail completely if func is not the top-most handler?  It is not
 *        clear why the function should pop the top handler no matter what, but
 *        only call Asc_SignalRecover() if it matches func.
 */

/** Output the contents of the specified stack. For debugging. */
ASC_DLLSPEC(void) Asc_SignalPrintStack(int signum);

/** Return the length of the specified stack. For debugging. */
ASC_DLLSPEC(int) Asc_SignalStackLength(int signum);

/** For debugging.
    @return handler at top of specified stack, or NULL if stack is empty.
*/
ASC_DLLSPEC(SigHandlerFn *) Asc_SignalStackTop(int signum);

#endif  /* ASC_ASCSIGNAL_H */

1	johnpye	526	/* ASCEND modelling environment
2			Copyright (C) 1997 Benjamin Andrew Allan
3			Copyright (C) 2006 Carnegie Mellon University
4	jds	54
5	johnpye	526	This program is free software; you can redistribute it and/or modify
6			it under the terms of the GNU General Public License as published by
7			the Free Software Foundation; either version 2, or (at your option)
8			any later version.
9
10			This program is distributed in the hope that it will be useful,
11			but WITHOUT ANY WARRANTY; without even the implied warranty of
12			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13			GNU General Public License for more details.
14
15			You should have received a copy of the GNU General Public License
16			along with this program; if not, write to the Free Software
17			Foundation, Inc., 59 Temple Place - Suite 330,
18			Boston, MA 02111-1307, USA.
19			//*
20			@file
21			Signal handling protocol definitions for ASCEND.
22
23			This file standardizes the handling of signals because some OS
24			reset signals to SIG_DFL when a trap goes off while others
25			process the signal but leave the trapping function in place.
26			We want the second behavior and this gives it to us.
27
28			This module implements limited support for managing signal handlers.
29			This includes:
30			- a standard signal handler - Asc_SignalTrap()
31			- global jmp_buf's for use with Asc_SignalTrap()
32			- functions for managing nested signal handlers
33
34			The following signal types are currently supported:
35			- SIGFPE - floating point exception
36			- SIGINT - CTRL-C interactive attention request
37			- SIGSEGV - segmentation fault
38
39			A simple use of these facilities to trap floating point exceptions
40			might be as follows:
41			<pre>
42			Asc_SignalInit();
43			Asc_SignalHandlerPush(SIGFPE, Asc_SignalTrap);
44			if (setjmp(g_fpe_env)==0) {
45			y = sqrt(x);
46			} else {
47			y = sqrt(-x);
48			}
49			Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
50			Asc_SignalDestroy();
51			</pre>
52	jds	54
53	johnpye	968	This example uses the built-in signal handler Asc_SignalTrap()
54			and the global <code>jmp_buf</code> g_fpe_env. After initializing
55			the signal manager and registering the handler, <code>setjmp</code>
56			is used to select normal and exception paths. The <code>setjmp</code>
57			returns 0 when initially called and the sqrt(x) is calculated. If
58			x is negative, a SIGFPE exception occurs and the handler is called. It
59			uses <code>lngjmp</code> and returns to the if statement, and now
60			'setjmp' returns non-zero and the <code>else</code> clause is executed.
61			Finally, the handler is removed and the signal manager cleaned up.<br><br>
62
63			The stack mechanism also allows nested handlers to be registered. It is
64			important to note that nested handlers for the same signal type cannot
65			both use Asc_SignalTrap() as the handler. This is because different
66			<code>jmp_buf</code> variables must be used and Asc_SignalTrap() uses
67			the same global <code>jmp_buf</code> each time. However, you can use
68			custome <code>jmp_buf</code>'s and handlers:
69
70			<pre>
71			Asc_SignalInit();
72			Asc_SignalHandlerPush(SIGFPE, Asc_SignalTrap);
73			if (setjmp(g_fpe_env) == 0) {
74			y = sqrt(x);
75			Asc_SignalHandlerPush(SIGFPE, my_handler);
76			if (setjmp(my_jmp_buf) == 0) {
77			y = z/x;
78			} else {
79			Asc_Panic(1, NULL, "Div by zero error.");
80			}
81			Asc_SignHandlerPop(SIGFPE, my_handler);
82			} else {
83			y = sqrt(-x);
84			}
85			Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
86			Asc_SignalDestroy();
87			</pre>
88
89			Here, exceptions in the sqrt(x) calculation are handled by the standard
90			Asc_SignalTrap(), while the division is handled by my_handler.<br><br>
91
92			Avoid mixing use of the signal manager with direct calls to signal().
93			Once Asc_SignalInit() has been called, use of signal() directly is likely
94			to be lost or to corrupt the managed handlers.<br><br>
95
96			Another warning: setjmp is expensive if called inside a fast loop.
97
98	johnpye	526	Requires:
99			#include "utilities/ascConfig.h"
100			//
101	johnpye	953	by Benjamin Andrew Allan, May 27, 1997
102			Last in CVS: $Revision: 1.6 $ $Date: 1998/01/10 18:00:05 $ $Author: ballan $
103	johnpye	526	*/
104
105	johnpye	67	#ifndef ASC_ASCSIGNAL_H
106			#define ASC_ASCSIGNAL_H
107	jds	54
108	aw0a	1	#include <signal.h>
109			#include <setjmp.h>
110	johnpye	669	#include "utilities/ascConfig.h"
111
112	aw0a	1	#ifdef __WIN32__
113	jds	102	# include <process.h>
114	jds	101	#else
115	jds	102	# include <unistd.h>
116	aw0a	1	#endif
117
118	johnpye	968	#ifdef __WIN32__
119			# define FPRESET _fpreset()
120			#else
121			# define FPRESET (void)0
122			#endif
123
124	johnpye	953	typedef void SigHandlerFn(int);
125	jds	59	/*< Signature of a signal handling function. /
126	jds	54
127	aw0a	1	#define MAX_TRAP_DEPTH 40L
128	jds	59	/*< The maximum number of traps that can be nested. /
129	aw0a	1
130	johnpye	997	#define ASC_JMP_INFO
131			/*< Whether to store additional information before making a setjmp call /
132	aw0a	1
133	johnpye	997	#ifndef ASC_JMP_INFO
134			# define SETJMP set_jmp
135			# define LONGJMP longjmp
136	johnpye	1002	# define SIGNAL signal
137	johnpye	997	typedef JMP_BUF jmp_buf
138			#else
139	johnpye	1002	# define SETJMP(ENV) (\
140			CONSOLE_DEBUG("SETJMP at %s:%d (%s=%p)",__FILE__,__LINE__,#ENV,ENV.jmp)\
141			,ENV.filename = __FILE__, ENV.line = __LINE__, ENV.func = __FUNCTION__\
142			,ENV.varname = #ENV\
143			, setjmp(ENV.jmp)\
144			)
145			# define LONGJMP(ENV,VAL) (\
146			CONSOLE_DEBUG("LONGJMP to %s:%d (%s) (%s=%p)",ENV.filename,ENV.line,ENV.func,ENV.varname,ENV.jmp)\
147			, longjmp(ENV.jmp, VAL)\
148			)
149	johnpye	997	typedef struct{
150			jmp_buf jmp;
151			const char *filename;
152			int line;
153			const char *func;
154	johnpye	1002	const char *varname;
155	johnpye	997	} asc_jmp_buf;
156			#define JMP_BUF asc_jmp_buf
157	johnpye	1002	#define SIGNAL(SIG,HANDLER) (CONSOLE_DEBUG("SIGNAL(%d,%s)",SIG,#HANDLER),signal(SIG,HANDLER))
158	johnpye	997	#endif
159
160
161
162			ASC_DLLSPEC(JMP_BUF) g_fpe_env; /*< Standard signal jmp_buf - floating point error. /
163			ASC_DLLSPEC(JMP_BUF) g_seg_env; /*< Standard signal jmp_buf - segmentation fault. /
164			ASC_DLLSPEC(JMP_BUF) g_int_env; /*< Standard signal jmp_buf - interactive attention (<CTRL>C). /
165
166			#if 0
167	aw0a	1	extern jmp_buf g_foreign_code_call_env;
168	jds	54	/**<
169	johnpye	953	Not currently in use. Should be when we get to a unified
170			standard for signal handling.
171			@todo Implement use of g_foreign_code_call_env?
172			*/
173	johnpye	997	#endif
174	aw0a	1
175	johnpye	522	ASC_DLLSPEC(void ) Asc_SignalTrap(int sigval);
176	jds	54	/**<
177	jds	59	* Standard signal handler.
178	jds	54	* This is the trap that should be used for most applications in
179	jds	59	* ASCEND. It prints a message then calls longjmp(GLOBAL, sigval)
180			* where GLOBAL is one of g_fpe_env, g_seg_env, or g_int_env.
181			* Because the jmp_buf is global, so you can't nest calls to
182			* setjmp where both use this trap function.<br><br>
183	aw0a	1	*
184	jds	54	* Trivial Example:
185			* <pre>
186			* Asc_SignalHandlerPush(SIGFPE,Asc_SignalTrap);
187			* if (setjmp(g_fpe_env)==0) {
188			* y = sqrt(x);
189			* } else {
190			* y = sqrt(-x);
191			* }
192			* Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
193	jds	59	*
194	aw0a	1	* For x < 0 the else is called because setjmp returns nonzero
195			* when the body of the 'if' signals range error.
196	jds	54	* </pre>
197	johnpye	485	* Remember always to use Asc_SignalHandlerPush() and
198			* Asc_SignalHandlerPop(). You can write an alternate function
199	jds	59	* to use instead of AscSignalTrap() if need be. The signals
200	jds	54	* SIGFPE, SIGINT, SIGSEGV are understood.<br><br>
201	aw0a	1	*
202	jds	59	* Note - this handler does not reinstall itself. After an exception,
203			* you need to reinstall the handler (if desired) using
204			* Asc_SignalRecover().
205			*
206			* @todo Should utilities/ascSignal.c:Asc_SignalTrap() reinstall itself
207			* after it catches an expection using Asc_SignalRecover()?
208			* @param sigval Holds the signal type code when called during
209			* an exception.
210	aw0a	1	*/
211
212	johnpye	593	ASC_DLLSPEC(int ) Asc_SignalInit(void);
213	johnpye	485	/**<
214	jds	59	* Initializes the signal manager.
215	johnpye	485	* This should be called before using any of the signal handling
216	jds	59	* functions in this module. It initializes the internal stacks
217			* for mangaging signal handlers. This function does not install
218			* any signal handlers (although any existing handlers are left
219			* in place). Calling this function more than once will have no
220			* effect and an error code will be returned.<br><br>
221			*
222			* @return Returns 0 if successful, 1 if memory could not be
223			* allocated, and 2 if an error occurred.
224	aw0a	1	*/
225
226	johnpye	593	ASC_DLLSPEC(void ) Asc_SignalDestroy(void);
227	jds	59	/**<
228			* Cleans up and destroys the stacks of signal handlers.
229			* It does not change the status of any registered signal handlers
230			* That is, any handlers registered when this function is called
231			* will still be registered. It is important to call
232			* Asc_SignalHandlerPop() for each occurrence of Asc_SignalHandlerPush()
233			* before calling this function. Otherwise, any signal handlers
234			* that were installed before Asc_SignalInit() was called will be lost.
235	aw0a	1	*/
236
237	johnpye	522	ASC_DLLSPEC(void ) Asc_SignalRecover(int force);
238	jds	59	/**<
239			* Reinstalls the most recently pushed handler that has been
240			* installed for each supported signal type. This should be called
241			* after every trapped exception and at any other time when the
242			* status of exception handlers may have become not well-defined.
243			* If no handler has been pushed for a given signal type, SIG_DFL is
244	johnpye	485	* installed. Note that the standard handler function Asc_SignalTrap()
245			* does not call this function. If you use the standard handler and
246			* you want it reinstalled after an exception, be sure to call this
247			* function after the longjmp return. This call is not particularly
248	jds	59	* cheap if it does the reinstallation.<br><br>
249	aw0a	1	*
250	jds	59	* This module tests on startup for whether the OS reverts to
251			* SIG_DFL when a trap function is called. If it does NOT then
252			* this function will simply return unless force != 0. You don't
253			* want to call this function with force == 1 normally after a
254			* caught exception. However, if you're not sure of the handler
255	johnpye	485	* installation status and want to make sure the handlers are
256	jds	59	* installed, call with force == 1. Also, gdb or other
257			* debuggers which intercept and screw up signals may require
258			* applying force (manually) to ensure that the signals get
259			* reinstalled.
260			*
261	johnpye	485	* @param force If non-zero, the most recent handlers are
262	jds	59	* reinstalled even if not required by the
263			* compiler/platform.
264	aw0a	1	*/
265
266	johnpye	968	ASC_DLLSPEC(int ) Asc_SignalHandlerPushDefault(int signum);
267	johnpye	953	ASC_DLLSPEC(int ) Asc_SignalHandlerPush(int signum, SigHandlerFn *func);
268	jds	54	/**<
269	aw0a	1	* Adds a handler to the stack of signal handlers for the given signal.
270			* There is a maximum stack limit, so returns 1 if limit exceeded.
271			* Returns -1 if stack of signal requested does not exist.
272	jds	54	* Pushing a NULL handler func does NOT change anything at all.
273	aw0a	1	* On a successful return, the handler has been installed and will
274	jds	59	* remain installed until a Asc_SignalHandlerPop() or another push.
275			* The handler will remain installed as long as Asc_SignalRecover()
276			* is used properly after every exception.
277			*
278			* @param signum The signal type that func should handle.
279			* @param func The signal handler to register for signum signal types.
280			* @return Returns 1 if the stack limit is exceeded, -1 if managing
281			* of signals for the specified signum is not supported or
282			* initialized, or 0 if the function completes successfully.
283			* @todo Shouldn't utilities/ascSignal.c:Asc_SignalHandlerPush() return
284			* an error code on a NULL func? It seems too easy for someone to
285	johnpye	485	* accidentally push a NULL without realizing it, and then later
286	jds	59	* popping an unintended handler.
287	aw0a	1	*/
288
289	johnpye	968	ASC_DLLSPEC(int ) Asc_SignalHandlerPopDefault(int signum);
290	johnpye	953	ASC_DLLSPEC(int ) Asc_SignalHandlerPop(int signum, SigHandlerFn *func);
291	jds	54	/**<
292	jds	59	* Removes the last-pushed handler from the stack for signum signal types.
293	johnpye	485	* If the removed handler is the same as func, it is uninstalled and
294	jds	59	* replaced with the handler now at the top of the stack. If not, non-zero
295			* is returned and you need to call Asc_SignalRecover() to uninstall the
296	johnpye	485	* current handler if desired. Note that the top handler is popped off
297			* the stack whether it matches func or not. Non-zero is also returned if
298			* the stack is empty. A side effect is that all managed signal types will
299	jds	59	* have the registered handlers reinstalled.
300			*
301			* @param signum The signal type whose top-most handler should be replaced.
302			* @param func The handler function that should be at the top of the
303			* stack (and currently installed) for signals of type signum.
304			* @return Returns non-zero if func is not the replaced handler or if
305			* the stack is empty, 0 if the function completed successfully.
306			* @todo Does it make more sense for utilities/ascSignal.c:Asc_SignalHanderPop()
307	johnpye	485	* to fail completely if func is not the top-most handler? It is not
308			* clear why the function should pop the top handler no matter what, but
309	jds	59	* only call Asc_SignalRecover() if it matches func.
310	aw0a	1	*/
311
312	johnpye	1003	/** Output the contents of the specified stack. For debugging. */
313	johnpye	1002	ASC_DLLSPEC(void) Asc_SignalPrintStack(int signum);
314
315	johnpye	1003	/** Return the length of the specified stack. For debugging. */
316	johnpye	1002	ASC_DLLSPEC(int) Asc_SignalStackLength(int signum);
317
318	johnpye	1003	/** For debugging.
319			@return handler at top of specified stack, or NULL if stack is empty.
320			*/
321			ASC_DLLSPEC(SigHandlerFn *) Asc_SignalStackTop(int signum);
322
323	johnpye	67	#endif /* ASC_ASCSIGNAL_H */
324	jds	54