setjmp or longjmp Subroutine

Purpose

Saves and restores the current execution context.

Library

Standard C Library (libc.a)

Syntax

#include <setjmp.h>
int setjmp (Context)
jmp_buf Context;

void longjmp ( Context, Value) jmp_buf Context; int Value;

int _setjmp (Context)
jmp_buf Context;

void _longjmp (Context, Value)
jmp_buf Context;
int Value;

Description

The setjmp subroutine and the longjmp subroutine are useful when handling errors and interrupts encountered in low-level subroutines of a program.

The setjmp subroutine saves the current stack context and signal mask in the buffer specified by the Context parameter.

The longjmp subroutine restores the stack context and signal mask that were saved by the setjmp subroutine in the corresponding Context buffer. After the longjmp subroutine runs, program execution continues as if the corresponding call to the setjmp subroutine had just returned the value of the Value parameter. The subroutine that called the setjmp subroutine must not have returned before the completion of the longjmp subroutine. The setjmp and longjmp subroutines save and restore the signal mask sigmask (2), while _setjmp and _longjmp manipulate only the stack context.

If a process is using the AT&T System V sigset interface, then the setjmp and longjmp subroutines do not save and restore the signal mask. In such a case, their actions are identical to those of the _setjmp and _longjmp subroutines.

Parameters

Item	Description
Context	Specifies an address for a jmp_buf structure.
Value	Indicates any integer value.

Return Values

The setjmp subroutine returns a value of 0, unless the return is from a call to the longjmp function, in which case setjmp returns a nonzero value.

The longjmp subroutine cannot return 0 to the previous context. The value 0 is reserved to indicate the actual return from the setjmp subroutine when first called by the program. The longjmp subroutine does not return from where it was called, but rather, program execution continues as if the corresponding call to setjmp was returned with a returned value of Value.

If the longjmp subroutine is passed a Value parameter of 0, then execution continues as if the corresponding call to the setjmp subroutine had returned a value of 1. All accessible data have values as of the time the longjmp subroutine is called.

Attention: If the longjmp subroutine is called with a Context parameter that was not previously set by the setjmp subroutine, or if the subroutine that made the corresponding call to the setjmp subroutine has already returned, then the results of the longjmp subroutine are undefined. If the longjmp subroutine detects such a condition, it calls the longjmperror routine. If longjmperror returns, the program is aborted. The default version of longjmperror prints the message: longjmp or siglongjmp used outside of saved context to standard error and returns. Users wishing to exit in another manner can write their own version of the longjmperror program.