setjmp(3)          UNIX System V(BSD Compatibility Package)           setjmp(3)


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

SYNOPSIS
      cc [ flag. . . ] file . . . -lucb

      #include <setjmp.h>

      int setjmp(env)
      jmpbuf env;

      longjmp(env, val)
      jmpbuf env;
      int val;

      int setjmp(env)
      jmpbuf env;

      longjmp(env, val)
      jmpbuf env;
      int val;

      int sigsetjmp(env, savemask)
      sigjmpbuf env;
      int savemask;

      siglongjmp(env, val)
      sigjmpbuf 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 possibly
      non-existent environment.  All memory-bound data have values as of the
      time longjmp was called.  The CPU and floating-point data registers are
      restored to the values they had at the time that setjmp was called.  But,


10/89                                                                    Page 1

setjmp(3)          UNIX System V(BSD Compatibility Package)           setjmp(3)


      because the register 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.
      This is especially a problem for programmers trying to write machine-
      independent C routines.

      setjmp and longjmp save and restore the signal mask (see sigsetmask(2)),
      while setjmp and longjmp manipulate only the C stack and registers.  If
      the savemask flag to sigsetjmp is non-zero, the signal mask is saved, and
      a subsequent siglongjmp using the same env will restore the signal mask.
      If the savemask flag is zero, the signal mask is not saved, and a
      subsequent siglongjmp using the same env will not restore the signal
      mask.  In all other ways, setjmp and sigsetjmp function in the same way
      that setjmp does, and longjmp and siglongjmp function in the same way
      that longjmp does.

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

SEE ALSO
      cc(1), signal(3), sigsetmask(3), sigvec(3)

      cc(1), signal(2), setjmp(3C) in the Programmer's Reference Manual

NOTES
      setjmp does not save the current notion of whether the process is
      executing 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 register storage
      class is only a hint to the C compiler, variables declared as register


Page 2                                                                    10/89

setjmp(3)          UNIX System V(BSD Compatibility Package)           setjmp(3)


      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(1V)), the compiler
      will not attempt to assign variables to registers in routines that call
      setjmp.

      longjmp never causes setjmp to return zero, so programmers should not
      depend on longjmp being able to cause setjmp to return zero.














































10/89                                                                    Page 3