sigsetjmp(3)sigsetjmp(3)NAME
sigsetjmp, siglongjmp - Save and restores the current execution context
SYNOPSIS
#include <setjmp.h>
int sigsetjmp(
sigjmp_buf environment,
int savemask ); void siglongjmp(
sigjmp_buf environment,
int value );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
siglongjmp(), sigsetjmp(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies an address for a sigjmp_buf structure. Specifies whether the
current signal mask should be saved. If this parameter contains a 0
(zero) value, sigsetjmp() does not save the signal mask. Otherwise, the
function saves the signal mask. Specifies the value you want written
to the execution context as the return value of the sigsetjmp() func‐
tion. If you specify 0 (zero) in this parameter, the execution context
contains a value of 1 as the sigsetjmp() return value. See the RETURN
VALUES section for more information.
DESCRIPTION
The sigsetjmp() and siglongjmp() functions are useful when handling
errors and interrupts encountered in low-level functions of a program.
The sigsetjmp() function saves the current stack context in the buffer
specified by the environment parameter. If the value of the savemask
parameter is not 0 (zero), the sigsetjmp() function also saves the
process' current signal mask as part of the calling environment.
You use the buffer specified by the environment parameter in a later
call to the siglongjmp() function. The siglongjmp() function restores
the stack context and (optionally) signal mask that were saved by the
sigsetjmp() function.
After the siglongjmp() function runs, program execution continues as if
the corresponding call to the sigsetjmp() function had just returned
the value of the value parameter. The function that called the
sigsetjmp() function must not have returned before the completion of
the siglongjmp() function.
Because it bypasses the usual function call and return mechanisms, the
siglongjmp() function executes correctly in contexts of interrupts,
signals, and any of their associated functions. However, if the sig‐
longjmp() function is invoked from a nested signal handler (that is,
from a function invoked as a result of a signal raised during the han‐
dling of another signal), the behavior is undefined.
RETURN VALUES
After the siglongjmp() function is finished executing, program execu‐
tion continues as if the corresponding call of the sigsetjmp() function
just returned. In other words, the execution context saved by the cor‐
responding sigsetjmp() function is in place and execution continues at
the statement immediately following the call to the sigsetjmp() func‐
tion.
Part of that execution context is the return value from the sigsetjmp()
function. When the sigsetjmp() function actually returns (before the
call to the siglongjmp() function), that return value is 0 (zero). When
the siglongjmp() function returns, the execution context contains a
non-zero value as the return value from the sigsetjmp() function.
The value you specify in the value parameter to the siglongjmp() func‐
tion is written to the execution context as the return value for the
sigsetjmp() function. You cannot cause the execution context to con‐
tain a 0 (zero) value for the sigsetjmp() return value. If you specify
0 in the value parameter, the execution context contains a 1 as the
sigsetjmp() return value.
CAUTION
The results of the siglongjmp() function are undefined if one of the
following is true: The siglongjmp() function is called with an environ‐
ment parameter that was not previously set by the sigsetjmp() function
The function that made the corresponding call to the sigsetjmp() func‐
tion has already returned.
If the siglongjmp() function detects one of these conditions, it calls
the longjmperror() function. If longjmperror() returns, the program is
aborted. The default version of longjmperror() displays an error mes‐
sage to standard error and returns. If you want your program to exit
more gracefully, you can write your own version of the longjmperror()
program.
SEE ALSO
Routines: setjmp(3)
Standards: standards(5)sigsetjmp(3)
