'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SETJMP 3UCB "Apr 7, 1993"
.SH NAME
setjmp, longjmp, _setjmp, _longjmp \- non-local goto
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ...
#include <setjmp.h>

\fBint\fR \fBsetjmp\fR(\fIenv\fR)
\fBjmp_buf\fR \fIenv\fR;
.fi

.LP
.nf
\fBvoid\fR \fBlongjmp\fR(\fIenv\fR, \fIval\fR)
\fBjmp_buf\fR \fIenv\fR;
\fBint\fR \fIval\fR;
.fi

.LP
.nf
\fBint\fR \fB_setjmp\fR(\fIenv\fR)
\fBjmp_buf\fR \fIenv\fR;
.fi

.LP
.nf
\fBvoid\fR \fB_longjmp\fR(\fIenv\fR, \fIval\fR)
\fBjmp_buf\fR \fIenv\fR;
\fBint\fR \fIval\fR;
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsetjmp()\fR and \fBlongjmp()\fR functions are useful for dealing with
errors and interrupts encountered in a low-level subroutine of a program.
.sp
.LP
The \fBsetjmp()\fR function saves its stack environment in \fIenv\fR for later
use by \fBlongjmp()\fR. A normal call to \fBsetjmp()\fR returns zero.
\fBsetjmp()\fR also saves the register environment.  If a \fBlongjmp()\fR call
will be made, the routine which called \fBsetjmp()\fR should not return until
after the \fBlongjmp()\fR has returned control (see below).
.sp
.LP
The \fBlongjmp()\fR function restores the environment saved by the last call of
\fBsetjmp()\fR, and then returns in such a way that execution continues as if
the call of \fBsetjmp()\fR had just returned the value \fIval\fR to the
function that invoked \fBsetjmp()\fR; however, if \fIval\fR were zero,
execution would continue as if the call of \fBsetjmp()\fR had returned one.
This ensures that a ``return'' from \fBsetjmp()\fR caused by a call to
\fBlongjmp()\fR can be distinguished from a regular return from \fBsetjmp()\fR.
The calling function must not itself have returned in the interim, otherwise
\fBlongjmp()\fR will be returning control to a possibly nonexistent
environment. All memory-bound data have values as of the time \fBlongjmp()\fR
was called.  The \fBCPU\fR and floating-point data registers are restored to
the values they had at the time that \fBsetjmp()\fR was called.  But, because
the \fBregister\fR storage class is only a hint to the C compiler, variables
declared as \fBregister\fR variables may not necessarily be assigned to machine
registers, so their values are unpredictable after a \fBlongjmp()\fR. This is
especially a problem for programmers trying to write machine-independent C
routines.
.sp
.LP
The \fBsetjmp()\fR and \fBlongjmp()\fR functions save and restore the signal
mask while \fB_setjmp()\fR and \fB_longjmp()\fR manipulate only the C stack and
registers.
.sp
.LP
None of these functions save or restore any floating-point status or control
registers.
.SH EXAMPLES
.LP
\fBExample 1 \fRExamples of \fBsetjmp()\fR and \fBlongjmp()\fR.
.sp
.LP
The following example uses both \fBsetjmp()\fR and \fBlongjmp()\fR to return
the flow of control to the appropriate instruction block:

.sp
.in +2
.nf
#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\en",SIGINT);
                break;
              case SIGALRM:
                printf("longjumped from alarm %d\en",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) ...\en");
          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);
        }
}
.fi
.in -2

.sp
.LP
When this example is compiled and executed, and the user sends an interrupt
signal, the output will be:

.sp
.in +2
.nf
longjumped from interrupt
.fi
.in -2

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

.sp
.in +2
.nf
longjumped from alarm
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBsigvec\fR(3UCB), \fBsetjmp\fR(3C), \fBsignal\fR(3C)
.SH NOTES
.sp
.LP
Use of these interfaces should be restricted to only applications written on
BSD platforms.  Use of these interfaces with any of the system libraries or in
multi-thread applications is unsupported.
.SH BUGS
.sp
.LP
The \fBsetjmp()\fR function does not save the current notion of whether the
process is executing on the signal stack.  The result is that a \fBlongjmp()\fR
to some place on the signal stack leaves the signal stack state incorrect.
.sp
.LP
On some systems \fBsetjmp()\fR also saves the register environment. Therefore,
all data that are bound to registers are restored to the values they had at the
time that \fBsetjmp()\fR was called. All memory-bound data have values as of
the time \fBlongjmp()\fR was called.  However, because the \fBregister\fR
storage class is only a hint to the C compiler, variables declared as
\fBregister\fR variables may not necessarily be assigned to machine registers,
so their values are unpredictable after a \fBlongjmp()\fR. When using compiler
options that specify automatic register allocation, the compiler will not
attempt to assign variables to registers in routines that call \fBsetjmp()\fR.
.sp
.LP
The \fBlongjmp()\fR function never causes \fBsetjmp()\fR to return 0, so
programmers should not depend on \fBlongjmp()\fR being able to cause
\fBsetjmp()\fR to return 0.