.TH "<setjmp.h>: Non-local goto" 3 "24 Jun 2019" "Version 2.0.0" "avr-libc" \" -*- nroff -*-
.ad l
.nh
.SH NAME
<setjmp.h>: Non-local goto \- 
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBsetjmp\fP (jmp_buf __jmpb)"
.br
.ti -1c
.RI "void \fBlongjmp\fP (jmp_buf __jmpb, int __ret) __ATTR_NORETURN__"
.br
.in -1c
.SH "Detailed Description"
.PP 
While the C language has the dreaded \fCgoto\fP statement, it can only be used to jump to a label in the same (local) function. In order to jump directly to another (non-local) function, the C library provides the \fBsetjmp()\fP and \fBlongjmp()\fP functions. \fBsetjmp()\fP and \fBlongjmp()\fP are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program.
.PP
\fBNote:\fP
.RS 4
\fBsetjmp()\fP and \fBlongjmp()\fP make programs hard to understand and maintain. If possible, an alternative should be used.
.PP
\fBlongjmp()\fP can destroy changes made to global register variables (see \fBHow to permanently bind a variable to a register?\fP).
.RE
.PP
For a very detailed discussion of \fBsetjmp()\fP/longjmp(), see Chapter 7 of \fIAdvanced Programming in the UNIX Environment\fP, by W. Richard Stevens.
.PP
Example:
.PP
.PP
.nf
    #include <setjmp.h>

    jmp_buf env;

    int main (void)
    {
        if (setjmp (env))
        {
            ... handle error ...
        }

        while (1)
        {
           ... main processing loop which calls foo() some where ...
        }
    }

    ...

    void foo (void)
    {
        ... blah, blah, blah ...

        if (err)
        {
            longjmp (env, 1);
        }
    }
.fi
.PP
 
.SH "Function Documentation"
.PP 
.SS "void longjmp (jmp_buf __jmpb, int __ret)"
.PP
Non-local jump to a saved stack context. .PP
.nf
 #include <setjmp.h>
.fi
.PP
.PP
\fBlongjmp()\fP restores the environment saved by the last call of \fBsetjmp()\fP with the corresponding \fI__jmpb\fP argument. After \fBlongjmp()\fP is completed, program execution continues as if the corresponding call of \fBsetjmp()\fP had just returned the value \fI__ret\fP.
.PP
\fBNote:\fP
.RS 4
\fBlongjmp()\fP cannot cause 0 to be returned. If \fBlongjmp()\fP is invoked with a second argument of 0, 1 will be returned instead.
.RE
.PP
\fBParameters:\fP
.RS 4
\fI__jmpb\fP Information saved by a previous call to \fBsetjmp()\fP. 
.br
\fI__ret\fP Value to return to the caller of \fBsetjmp()\fP.
.RE
.PP
\fBReturns:\fP
.RS 4
This function never returns. 
.RE
.PP

.SS "int setjmp (jmp_buf __jmpb)"
.PP
Save stack context for non-local goto. .PP
.nf
 #include <setjmp.h>
.fi
.PP
.PP
\fBsetjmp()\fP saves the stack context/environment in \fI__jmpb\fP for later use by \fBlongjmp()\fP. The stack context will be invalidated if the function which called \fBsetjmp()\fP returns.
.PP
\fBParameters:\fP
.RS 4
\fI__jmpb\fP Variable of type \fCjmp_buf\fP which holds the stack information such that the environment can be restored.
.RE
.PP
\fBReturns:\fP
.RS 4
\fBsetjmp()\fP returns 0 if returning directly, and non-zero when returning from \fBlongjmp()\fP using the saved context. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for avr-libc from the source code.