Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SETJMP(3V)							    SETJMP(3V)

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

SYNOPSIS
       #include	<setjmp.h>
       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  in-
       voked  setjmp();	however, if val	were zero, execution would continue as
       if the call of setjmp() had returned one.  This ensures	that  a	 ``re-
       turn'' from setjmp() caused by a	call to	longjmp() can be distinguished
       from a regular return from setjmp().  The calling function must not it-
       self  have returned in the interim, otherwise longjmp() will be return-
       ing 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 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 ex-
       ecuting	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 as-
       signed 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	 vari-
       ables to	registers in routines that call	setjmp().

				5 October 1989			    SETJMP(3V)

NAME | SYNOPSIS | DESCRIPTION | SYSTEM V DESCRIPTION | EXAMPLE | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=setjmp&sektion=3v&manpath=SunOS+4.1.3>

home | help