unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

SETJMP(3V)                                                          SETJMP(3V)



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

SYNOPSIS
       #include <&lt;setjmp.h>&gt;
       int setjmp(env)
       jmp_buf env;
       void longjmp(env, val)
       jmp_buf env;
       int val;
       int _setjmp(env)
       jmp_buf env;
       void _longjmp(env, val)
       jmp_buf env;
       int val;
       int sigsetjmp(env, savemask)
       sigjmp_buf env;
       int savemask;
       void siglongjmp(env, val)
       sigjmp_buf env;
       int val;

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

       The macro 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 distin-
       guished 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, because the register stor-
       age class is only a hint to the C compiler, variables declared as  reg-
       ister  variables  may not necessarily be assigned to machine registers,
       so their values are unpredictable after a  longjmp().   This  is  espe-
       cially  a problem for programmers trying to write machine-independent C
       routines.

       setjmp() and longjmp() save and restore the signal  mask  (see  sigset-
       mask(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, in particular the MC68881 fpsr, fpcr, or fpiar, the
       Sun-3 FPA fpamode or fpastatus, and the Sun-4 %fsr.  See ieee_flags(3M)
       to save and restore floating-point status or control information.

SYSTEM V DESCRIPTION
       setjmp()  and longjmp() manipulate only the C stack and registers; they
       do not save or restore the signal mask.  _setjmp() behaves  identically
       to setjmp(), and _longjmp() behaves identically to longjmp().

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

              function declaration
              ...
                     jmp_buf   my_environment;
                     ...
                     if (setjmp(my_environment))  {
                            /* 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(1V),   sigsetmask(2),   sigvec(2),    ieee_flags(3M),    signal(3V),
       setjmp(3V)

BUGS
       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  Sun-2  and  Sun-3 systems setjmp() also saves the register environ-
       ment.  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  variables  may  not  necessarily  be
       assigned  to machine registers, so their values are unpredictable after
       a longjmp().  When using compiler options that specify automatic regis-
       ter  allocation  (see  cc(1V)), the compiler will not attempt to assign
       variables to registers in routines that call setjmp().



                                5 October 1989                      SETJMP(3V)