setjmp(3C-ucb)          (BSD Compatibility Package)          setjmp(3C-ucb)

NAME
     setjmp, longjmp, setjmp, longjmp - non-local goto

SYNOPSIS
     /usr/ucb/cc [flag ...] file ... -lucb

     #include <setjmp.h>

     int setjmp(jmpbuf env);

     longjmp(jmpbuf env, int val);

     int setjmp(jmpbuf env);

     longjmp(jmpbuf env, int val);

DESCRIPTION
     setjmp and longjmp are useful for dealing with errors and interrupts
     encountered in a low-level subroutine of a program.

     setjmp saves its stack environment in env for later use by longjmp. A
     normal call to setjmp returns zero. setjmp also saves the register
     environment. If a longjmp call will be made, the routine which called
     setjmp should not return until after the longjmp has returned control
     (see below).

     longjmp restores the environment saved by the last call of setjmp, and
     then returns in such a way that execution continues as if the call of
     setjmp had just returned the value val to the function that invoked
     setjmp; however, if val were zero, execution would continue as if the
     call of setjmp had returned one. This ensures that a return from
     setjmp caused by a call to longjmp can be distinguished from a regular
     return from setjmp. The calling function must not itself have returned
     in the interim, otherwise longjmp will be returning control to a pos-
     sibly non-existent environment. All memory-bound data have values as
     of the time longjmp was called. The CPU and floating-point data regis-
     ters are restored to the values they had at the time that setjmp was
     called. But, because the register storage class is only a hint to the
     C compiler, variables declared as register variables may not neces-
     sarily be assigned to machine registers, so their values are
     unpredictable after a longjmp. This is especially a problem for pro-
     grammers trying to write machine-independent C routines.













Page 1                       Reliant UNIX 5.44                Printed 11/98

setjmp(3C-ucb)          (BSD Compatibility Package)          setjmp(3C-ucb)

     The longjmp() and setjmp() functions are identical to longjmp() and
     setjmp(), respectively, with the additional restriction that
     longjmp() and setjmp() do not manipulate the signal mask.

     If longjmp() is called even though env was never initialized by a
     call to setjmp(), or when the last such call was in a function that
     has since returned, the results are undefined.

     None of these functions save or restore any floating-point status or
     control registers.

EXAMPLE
     The following code fragment indicates the flow of control of the
     setjmp and longjmp combination:

          function declaration
          ...
                jmpbuf myenvironment;
                ...
                if (setjmp(myenvironment))  {
                  /* register variables have unpredictable values */
                     code after the return from longjmp
                     ...
                } else {
                  /* do not modify register vars in this leg of code */
                     this is the return from setjmp
                       ...
                }

APPLICATION USAGE
     If longjmp() is executed and the environment in which setjmp() was
     executed no longer exists, errors can occur. The conditions under
     which the environment of the setjmp() no longer exists include exit-
     ing the function that contains the setjmp() call, and exiting an
     inner block with temporary storage. This condition might not be
     detectable, in which case the longjmp() occurs and, if the environ-
     ment no longer exists, the contents of the temporary storage of an
     inner block are unpredictable. This condition might also cause unex-
     pected process termination. If the function has returned, the results
     are undefined.

     Passing longjmp() a pointer to a buffer not created by setjmp(), pass-
     ing longjmp() a pointer to a buffer not created by setjmp(), passing
     siglongjmp() a pointer to a buffer not created by sigsetjmp() or pass-
     ing any of these three functions a buffer that has been modified by
     the user can cause all the problems listed above, and more.

     The longjmp() and setjmp() functions are included to support pro-
     grams written to historical system interfaces. New applications should
     use siglongjmp() and sigsetjmp() respectively.




Page 2                       Reliant UNIX 5.44                Printed 11/98

setjmp(3C-ucb)          (BSD Compatibility Package)          setjmp(3C-ucb)

NOTES
     setjmp does not save the current notion of whether the process is exe-
     cuting on the signal stack. The result is that a longjmp to some place
     on the signal stack leaves the signal stack state incorrect.

     On some systems setjmp also saves the register environment. Therefore,
     all data that are bound to registers are restored to the values they
     had at the time that setjmp was called. All memory-bound data have
     values as of the time longjmp was called. However, because the regis-
     ter storage class is only a hint to the C compiler, variables declared
     as register variables may not necessarily be assigned to machine
     registers, so their values are unpredictable after a longjmp. When
     using compiler options that specify automatic register allocation [see
     cc(1)], the compiler will not attempt to assign variables to registers
     in routines that call setjmp.

     longjmp never causes setjmp to return zero.

SEE ALSO
     cc(1), signal(2), sigsetmask(3), sigvec(3), signal(3-ucb), setjmp(3C),
     setjmp(5).

































Page 3                       Reliant UNIX 5.44                Printed 11/98