/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss of reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

#error "Do not include this file! Use <setjmp.h> instead"

/****************************************************************************/
/*  This file is for documentation only, describing assembly routines.		*/
/****************************************************************************/

typedef	int jmp_buf[];

/** @addtogroup setjmp */
/** @{ */

/**
*	Prepare for a non-local jump.
*
*	The function saves the current execution context of the processor
*	to the object 'env' then it returns 0.
*	If later on a longjmp() is executed using the saved context,
*	the execution context is restired and this function will return
*	<i>again</i> but it is guaranteed that the return value is not 0.
*
*	@warning
*		If longjmp() is called with an execution context after the caller
*		of setjmp() that saved that context returned, then you will have a
*		spectacular system crash. It is your responsibility that no
*		execution context is used after it went out of scope.
*
*	@param	env		The buffer in which the execution context is to be saved.
*	@return			Zero when the function returns after saving the context
*					and a nonzero value, determined by longjmp() when the
*					function returns due to a call to longjmp().
*/

int	setjmp( jmp_buf env );

/**
*	Execute a non-local jump.
*
*	The function restores the execution context that was saved by a
*	setjmp() call earlier. When setjmp() returns <i>again</i> its return
*	value will be the value passed as the second argument of this function.
*	This value must not be 0. If 0 is passed to longjmp, it will be changed
*	to 1 to guarantee that setjmp() return 0 if and only if it returns the
*	first time.
*
*	Naturally, longjmp() does not return to its caller, as execution will
*	continue just after the setjmp() that saved the context.
*
*	@warning
*		If longjmp() is called with an execution context after the caller
*		of setjmp() that saved that context returned, then you will have a
*		spectacular system crash. It is your responsibility that no
*		execution context is used after it went out of scope.
*
*	@param	env		The buffer in which the execution context was saved.
*	@param	val		The nonzero value that setjmp() will return when it
*					returns again.
*/

void	longjmp( jmp_buf env, int val );

/** @} */

