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

FreeBSD Manual Pages

  
 
  

home | help
setjmp(3C)		 Standard C Library Functions		    setjmp(3C)

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

SYNOPSIS
       #include	<setjmp.h>

       int setjmp(jmp_buf env);

       int sigsetjmp(sigjmp_buf	env, int savemask);

       void longjmp(jmp_buf env, int val);

       void siglongjmp(sigjmp_buf env, int val);

DESCRIPTION
       These  functions	are useful for dealing with errors  and	interrupts en-
       countered in a low-level	subroutine of a	program.

       The setjmp() function saves its stack environment in env	for later  use
       by longjmp().

       The  sigsetjmp()	 function  saves  the  calling process's registers and
       stack environment (see sigaltstack(2)) in  env for later	 use  by  sig-
       longjmp().  If  savemask	is non-zero, the calling process's signal mask
       (see sigprocmask(2)) and	scheduling parameters  (see  priocntl(2))  are
       also saved.

       The  longjmp() function restores	the environment	saved by the last call
       of setjmp() with	the corresponding env argument.	After  longjmp()  com-
       pletes,	program	 execution  continues  as if the corresponding call to
       setjmp()	had just returned the value val. The caller of	setjmp()  must
       not  have returned in the interim.  The longjmp() function cannot cause
       setjmp()	to return the value 0.	If longjmp() is	invoked	with a	second
       argument	of 0, setjmp() will return 1. At the time of the second	return
       from setjmp(), all external and static variables	have values as of  the
       time longjmp() is called	(see EXAMPLES).

       The  siglongjmp()  function  restores the environment saved by the last
       call of sigsetjmp() with	the corresponding  env	argument.  After  sig-
       longjmp()  completes, program execution continues as if the correspond-
       ing call	to sigsetjmp() had just	 returned  the	value  val.  The  sig-
       longjmp()  function cannot cause	sigsetjmp() to return the value	0.  If
       siglongjmp() is invoked with a second argument of 0,  sigsetjmp()  will
       return 1. At the	time of	the second return from sigsetjmp(), all	exter-
       nal and static variables	have values as of the  time  siglongjmp()  was
       called.

       If  a  signal-catching  function	 interrupts  sleep(3C)	and calls sig-
       longjmp() to restore an environment saved prior to  the	sleep()	 call,
       the  action associated with SIGALRM and time it is scheduled to be gen-
       erated are unspecified. It is also unspecified whether the SIGALRM sig-
       nal is blocked, unless the process's signal mask	is restored as part of
       the environment.

       The  siglongjmp() function restores the saved signal mask if  and  only
       if the  env argument was	initialized by a call to the sigsetjmp() func-
       tion with a non-zero  savemask argument.

       The values of register and automatic variables are undefined.  Register
       or automatic variables whose value must be relied upon must be declared
       as volatile.

RETURN VALUES
       If the return is	from a direct invocation, setjmp() and sigsetjmp() re-
       turn  0.	 If the	return is from a call to longjmp(), setjmp() returns a
       non-zero	 value.	 If  the  return  is  from  a  call  to	 siglongjmp(),
       sigsetjmp() returns a non-zero value.

       After  longjmp()	 is  completed,	 program execution continues as	if the
       corresponding invocation	of setjmp() had	just returned the value	speci-
       fied  by	val. The longjmp() function cannot cause setjmp() to return 0;
       if val is 0, setjmp() returns 1.

       After siglongjmp() is completed,	program	execution continues as if  the
       corresponding  invocation  of  sigsetjmp()  had just returned the value
       specified by val. The siglongjmp() function cannot cause	sigsetjmp() to
       return 0; if val	is 0, sigsetjmp() returns 1.

EXAMPLES
       Example 1: Example of setjmp() and longjmp() functions.

       The  following  example	uses both setjmp() and longjmp() to return the
       flow of control to the appropriate instruction block:

       #include	<stdio.h>
       #include	<setjmp.h>
       #include	<signal.h>
       #include	<unistd.h>
       jmp_buf env; static void	signal_handler();

       main()  {
	       int returned_from_longjump, processing =	1;
	       unsigned	int time_interval = 4;
	       if ((returned_from_longjump = setjmp(env)) != 0)
		   switch (returned_from_longjump)     {
		     case SIGINT:
		       printf("longjumped from interrupt %d\n",SIGINT);
		       break;
		     case SIGALRM:
		       printf("longjumped from alarm %d\n",SIGALRM);
		       break;
		   }
	       (void) signal(SIGINT, signal_handler);
	       (void) signal(SIGALRM, signal_handler);
	       alarm(time_interval);
	       while (processing)	 {
		 printf(" waiting for you to INTERRUPT (cntrl-C) ...\n");
		 sleep(1);
	       }       /* end while forever loop */
       }

       static void signal_handler(sig)
       int sig;	{
	       switch (sig)	{
		 case SIGINT:	...    /* process for interrupt	*/
				longjmp(env,sig);
				       /* break	never reached */
		 case SIGALRM:	...    /* process for alarm */
				longjmp(env,sig);
				      /* break never reached */
		 default:	exit(sig);
	       }
       }

       When this example is compiled and executed, and the user	sends  an  in-
       terrupt signal, the output will be:

       longjumped from interrupt

       Additionally,  every  4	seconds	the alarm will expire, signalling this
       process,	and the	output will be:

       longjumped from alarm

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Unsafe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       getcontext(2),  priocntl(2),  sigaction(2),  sigaltstack(2),   sigproc-
       mask(2),	signal(3C), attributes(5), standards(5)

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

SunOS 5.10			  14 Aug 2002			    setjmp(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ATTRIBUTES | SEE ALSO | WARNINGS

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

home | help