siglongjmp() — Restore the stack environment and signal mask
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1 |
both |
Format
#define _POSIX_SOURCE
#include <setjmp.h>
void siglongjmp(sigjmp_buf env, int val);
General description
For a stack environment previously saved in env by sigsetjmp(), the siglongjmp() function restores all the stack environment and, optionally, the signal mask, depending on whether it was saved by sigsetjmp(). The sigsetjmp() and siglongjmp() functions provide a way to perform a nonlocal goto.
env is an address for a sigjmp_buf structure.
val is the return value from siglongjmp().
siglongjmp() is similar to longjmp(), except for the optional capability of restoring the signal mask. The sigsetjmp()—siglongjmp() pair, the setjmp()—longjmp() pair, the _setjmp()—_longjmp() pair, and the getcontext()—setcontext() pair cannot be intermixed. A stack environment and signal mask saved by sigsetjmp() can be restored only by siglongjmp().
- If you call siglongjmp(), the function in which the corresponding call to sigsetjmp() was made must not have returned first. After the function calling sigsetjmp() returns, calling siglongjmp() causes unpredictable program behavior.
- If siglongjmp() is used to jump back into an XPLINK routine, any alloca() requests issued by the XPLINK routine after the earlier sigsetjmp() (or getcontext(),and so on.) was called and before siglongjmp() is called are backed out. All storage obtained by these alloca() requests is freed before the XPLINK routine is resumed.
- If siglongjmp() is used to jump back into a non-XPLINK routine, alloca() requests made after sigsetjmp() and before siglongjmp() are not backed out.
The value argument passed to siglongjmp() must be nonzero. If you give a zero argument for value, siglongjmp() substitutes the value 1 in its place.
siglongjmp() does not use the normal function call and return mechanisms. siglongjmp() restores the saved signal mask only if the env parameter was initialized by a call to sigsetjmp() with a nonzero savemask argument.
Special behavior for C++: If sigsetjmp() and siglongjmp() are used to transfer control in a z/OS® XL C++ program, the behavior is undefined in terms of the destruction of automatic objects. Additionally, if any automatic objects would be destroyed by a thrown exception transferring control to another (destination) point in the program, then a call to siglongjmp() at the throw point that transfers control to the same (destination) point has undefined behavior. This applies to both z/OS XL C++ and z/OS XL C/C++ ILC modules. The use of sigsetjmp() and siglongjmp() in conjunction with try(), catch(), and throw() is also undefined.
- All XPLINK programs compiled with the V2R10 or later C compilers that are to run with Language Environment V2R10 or later libraries and use the jmp_buf, sigjmp_buf or ucontext_t types must not be compiled with C headers from Language Environment V2R9 or earlier.
- Non-XPLINK functions compiled with any level of Language Environment headers must not define jmp_buf, sigjmp_buf or ucontext_t data items and pass them to XPLINK functions that call getcontext(), longjmp(), _longjmp(), setjmp(), _setjmp(), setcontext(), sigsetjmp(), or swapcontext() with these passed-in data items.
- When __XPLINK__ is defined, the Language Environment V2R10 and later headers define a larger jmp_buf, sigjmp_buf or ucontext_t area that is required by setjmp(), getcontext(), and related functions when they are called from an XPLINK routine. If __XPLINK__ is not defined, the Language Environment V2R10 and later headers define a shorter jmp_buf, sigjmp_buf or ucontext_t area. The Language Environment headers before V2R10 also define the shorter version of these data areas. If an XPLINK function calls setjmp(), getcontext() or similar functions with a short jmp_buf, sigjmp_buf or ucontext_t area, a storage overlay or program check may occur when the C library tries to store past the end of the passed-in (too short) data area.
Returned value
siglongjmp() returns no values.
There are no documented errno values.
Example
This example saves the stack environment and signal mask at the statement: if(sigsetjmp(mark,1) != 0) ...
When the system first performs the if statement, it saves the environment and signal mask in mark and sets the condition to false, because sigsetjmp() returns 0 when it saves the environment. The program prints the message: sigsetjmp() has been called
#define _POSIX_SOURCE
#include <stdio.h>
#include <setjmp.h>
sigjmp_buf mark;
void p(void);
void recover(void);
int main(void)
{
if (sigsetjmp(mark) != 0) {
printf("siglongjmp() has been called\n");
recover();
exit(1);
}
printf("sigsetjmp() has been called\n");
⋮
p();
⋮
}
void p(void) {
int error = 0;
⋮
error = 9;
⋮
if (error != 0)
siglongjmp(mark, -1);
⋮
}
void recover(void) {
⋮
}
Related information
- setjmp.h
- getcontext() — Get user context
- longjmp() — Restore stack environment
- _longjmp() — Nonlocal goto
- setcontext() — Restore user context
- setjmp() — Preserve stack environment
- _setjmp() — Set jump point for a nonlocal goto
- sigaction() — Examine or change a signal action
- sigprocmask() — Examine or change a thread
- sigsetjmp() — Save stack environment and signal mask
- sigsuspend() — Change mask and suspend the thread
- swapcontext() — Save and restore user context