longjmp - Non-local jump

Definition	#include <setjmp.h> void longjmp(jmp_buf env, int value); longjmp can only be used in association with the setjmp function. This is because a longjmp call causes the program to branch to a position previously “marked” with setjmp. In contrast to goto jumps, which are only admissible within the same function (i.e. locally), longjmp and setjmp enable the transfer of control from any given function to some other active function (non-local jump). setjmp stores the current program status (address in the C runtime stack, program counter, register contents) in a variable of type jmp_buf (defined in <setjmp.h>). longjmp restores the program status stored by setjmp, and the program is then continued with the statement immediately following the setjmp call.
Parameters	jmp_buf env Field in which setjmp has stored its values. The type jmp_buf is defined in <setjmp.h>. int value Integer interpreted as the return value of the setjmp call when program execution is resumed. If value is equal to 0, setjmp returns a value of 1; 0 would imply that control was transferred "normally" at the position after the setjmp call, i.e. that no branch was made with longjmp (see setjmp for further information).
Notes	The behavior is undefined if longjmp is called with an env argument that was not previously given a value by means of a setjmp call. The function containing the setjmp call with the env variable must still be active when longjmp is activated with the same variable, i.e. this function should not have been terminated in the meantime (e.g. with exit or return). Non-local jumps are useful in the handling of interrupts (see signal). For example, if error handling or interrupt handling is carried out in routines on a low level (i.e. when a number of previously called functions are still active), longjmp and setjmp can be used to circumvent normal processing of still active functions and immediately branch to a function on a higher level. A longjmp call from an interrupt or error handling routine flushes the entries in the runtime stack up to the position marked by setjmp. In other words, functions that were active thus far on a lower level are now no longer active, and the program is continued on a higher level. When program execution is resumed, the variables have the same values they would have received following a goto call: Global variables have the values that they had at the time of the longjmp call. Register variables and other local variables are undefined, i.e. they should be checked and re-initialized, if required.
Example	Text I/O in an interactive text editor represents a typical use for longjmp and setjmp. When the program is interrupted during input or output as a result of an externally originating signal (e.g. when the K2 key is pressed after "please acknowledge" or in response to an input prompt), text I/O is terminated. Otherwise, the text editor continues with I/O operations. The following program shows how this can be implemented with setjmp and longjmp (only illustrates signal handling - not an editor!): #include <stdio.h> #include <setjmp.h> #include <signal.h> FILE *fp; jmp_buf env; void intr(int sig) { printf("\n ***** You don't want the text? ****** \n"); longjmp(env,0); } int main(void) { int c; char reply; setjmp(env); signal(SIGINT,intr); printf("Text output? (y?n):\n"); scanf("%1s",&reply); /* Interruption possible with K2 */ if(reply == 'y') { fp = fopen("text","r"); /* File text must exist */ while((c=getc(fp)) != EOF) putc((char)c,stdout); /* Interruption of text output possible ̧ /* with K2 after "please acknowledge" */ } else printf("No text output\n"); return 0; }
See also	setjmp, signal