You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
120 lines
3.0 KiB
Groff
120 lines
3.0 KiB
Groff
15 years ago
|
.TH "<setjmp.h>: Non-local goto" 3 "4 Dec 2008" "Version 1.6.4" "avr-libc" \" -*- nroff -*-
|
||
|
|
.ad l
|
||
|
|
.nh
|
||
|
|
.SH NAME
|
||
|
|
<setjmp.h>: Non-local goto \-
|
||
|
|
.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
|
||
|
|
|
||
|
|
.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 "Function Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "void longjmp (jmp_buf __jmpb, int __ret)"
|
||
|
|
.PP
|
||
|
|
Non-local jump to a saved stack context.
|
||
|
|
.PP
|
||
|
|
.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
|
||
|
|
.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
|
||
|
|
|