setjmp(3)              C LIBRARY FUNCTIONS              setjmp(3)



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

SYNOPSIS
     cc [ flag... ] file ... -lucb
     #include <setjmp.h>
     int setjmp(env)
     jmp_buf env;
     longjmp(env, val)
     jmp_buf env;
     int val;
     int _setjmp(env)
     jmp_buf env;
     _longjmp(env, val)
     jmp_buf env;
     int val;
     int sigsetjmp(env, savemask)
     sigjmp_buf env;
     int savemask;
     siglongjmp(env, val)
     sigjmp_buf env;
     int val;

DESCRIPTION
     setjmp and longjmp 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.   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  execu-
     tion  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, 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  try-
     ing  to  write  machine-independent  C routines.  setjmp and
     longjmp   save   and   restore   the   signal   mask    (see



             Last change: BSD Compatibility Package             1

setjmp(3)              C LIBRARY FUNCTIONS              setjmp(3)



     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 sub-
     sequent siglongjmp using the same env will restore the  sig-
     nal  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
          ...
               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(1), signal(3),  sigsetmask(3),  sigvec(3).   cc(1),  sig-
     nal(2), setjmp(3C) in the Programmer's Reference Manual.

BUGS
     setjmp does not save the current notion of whether the  pro-
     cess 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 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.




             Last change: BSD Compatibility Package             2