Nonlocal jumps
[C library]

This function pair allows you to return from a deep function call chain in one hit. More...

Functions
int	setjmp (jmp_buf env)
	Prepare for a non-local jump.
void	longjmp (jmp_buf env, int val)
	Execute a non-local jump.

---

Detailed Description

This function pair allows you to return from a deep function call chain in one hit.

This is useful when you have some sort of a parser where you descend deeper and deeper as you go along. If everything is fine, then you will return step by step. However, if you discover an error, then you will have to propagate that error up to the top level. This means that every function has to have code to do nothing else just pass the error up. You can save all that trouble by calling setjmp() at the top level and calling longjmp() if you detect the error. The call to longjmp() will unwind the stack, restore the state of the top-level function to the same state as when it called setjmp() and setjmp() will return to the top level function again.

When setjmp() returns to the caller the first time it returns 0. If it returns to the caller the second time (that is, because longjmp() was called) it is guaranteed that the return value is not 0. Therefore, the caller of setjmp can differentiate between the two kinds of returns.

The type of the object that contains the saved processor state is jmp_buf, which is an opaque type, which you can use to declare objects that can be passed to functions but can not be lvalues.

The state that was saved by setjmp() must be passed to longjmp() verbatim. The state goes out of scope if the function containing setjmp returns, even if it is stored in static storage. Calling longjmp() on such state may or may not cause an immediate system crash but will most definitely cause very hard to find bugs.

To use these functions you have to include setjmp.h.

---

Function Documentation

void longjmp	(	jmp_buf	env,
		int	val
	)

Execute a non-local jump.

The function restores the execution context that was saved by a setjmp() call earlier. When setjmp() returns again 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.

Parameters:

	env	The buffer in which the execution context was saved.
	val	The nonzero value that setjmp() will return when it returns again.

int setjmp

(

jmp_buf

env

)

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 again 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.

Parameters:

env

The buffer in which the execution context is to be saved.

Returns:

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().