.TH "setjmp" 3avr "Fri Jan 1 2021" "Version 2.0.0" "avr-libc" \" -*- nroff -*-
.ad l
.nh
.SH NAME
setjmp \- <setjmp\&.h>: Non-local goto
.SH SYNOPSIS
.br
.PP
.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\&.