Setjmp/Longjmp

setjmp(3C) C Library Functions setjmp(3C)

NAME

setjmp, sigsetjmp, longjmp, siglongjmp - non-local goto

SYNOPSIS

#include < setjmp.h >

int setjmp(jmp_buf env);

int sigsetjmp(sigjmp_buf env, int savemask);

void longjmp(jmp_buf env, int val);

void siglongjmp(sigjmp_buf env, int val);

MT-LEVEL

Unsafe

DESCRIPTION

These functions are useful for dealing with errors and

interrupts encountered in a low-level subroutine of a pro-

gram.

setjmp() saves its stack environment in env for later use by

longjmp().

sigsetjmp() saves the calling process's registers and stack

environment (see sigaltstack(2)) in env for later use by

siglongjmp(). If savemask is non-zero, the calling

process's signal mask (see sigprocmask(2)) and scheduling

parameters (see priocntl(2)) are also saved.

longjmp() restores the environment saved by the last call of

setjmp() with the corresponding env argument. After

longjmp() is completed, program execution continues as if

the corresponding call of setjmp() had just returned the

value val. The caller of setjmp() must not have returned in

the interim. longjmp() cannot cause setjmp() to return the

value 0. If longjmp() is invoked with a second argument of

0, setjmp() will return 1. At the time of the second return

from setjmp(), all external and static variables have values

as of the time longjmp() is called (see example).

siglongjmp() restores the environment saved by the last call

of sigsetjmp() with the corresponding env argument. After

siglongjmp() is completed, program execution continues as if

the corresponding call of sigsetjmp() had just returned the

value val. siglongjmp() cannot cause sigsetjmp() to return

the value 0. If siglongjmp() is invoked with a second argu-

ment of 0, sigsetjmp() will return 1. At the time of the

second return from sigsetjmp(), all external and static

variables have values as of the time siglongjmp() is called.

If a signal-catching function interrupts sleep() and calls

siglongjmp() to restore an environment saved prior to the

sleep() call, the action associated with SIGALRM and time it

is scheduled to be generated are unspecified. It is also

unspecified whether the SIGALRM signal is blocked, unless

the process's signal mask is restored as part of the

environment.

The function siglongjmp() restores the saved signal mask if

and only if the env argument was initialized by a call to

the sigsetjmp() function with a non-zero savemask argument.

The values of register and automatic variables are unde-

fined. Register or automatic variables whose value must be

relied upon must be declared as volatile.

EXAMPLES

     #include < stdio.h >
     #include < stdlib.h >
     #include < setjmp.h >

     jmp_buf env;
     int i = 0;
     main ()
     {
         void exit();

         if(setjmp(env) != 0)
         {
            printf("value of i on 2nd return from setjmp: %d\n", i);
            exit(0);
         }
         printf("value of i on 1st return from setjmp: %d\n", i);
         i = 1;
         restore_env();
         /* NOTREACHED */
     }
     restore_env()
     {
         longjmp(env, 1);
         /* NOTREACHED */
     }

If the executable resulting from this C language code is run, the

output will be:

value of i on 1st return from setjmp:0

value of i on 2nd return from setjmp:1

RETURN VALUES

If longjmp() or siglongjmp() are invoked with a second argu-

ment of 0, setjmp() and sigsetjmp() , respectively, return

1. Otherwise, setjmp() and sigsetjmp() return 0.

SEE ALSO

getcontext(2), priocntl(2), sigaction(2), sigaltstack(2),

sigprocmask(2), signal(3C)

WARNINGS

If longjmp() or siglongjmp() are called even though env was

never primed by a call to setjmp() or sigsetjmp(), or when

the last such call was in a function that has since

returned, absolute chaos is guaranteed.

SunOS 5.4           Last change: 22 Jan 1993                    3