getcontext() — Get user context
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both | POSIX(ON) |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <ucontext.h>
int getcontext(ucontext_t *ucp);
General description
The getcontext() function initializes the structure pointed to by ucp to the current user context of the calling process. The ucontext_t type that ucp points to defines the user context and includes the contents of the calling process's machine registers, the signal mask, and the current execution stack. A subsequent call to setcontext() restores the saved context and returns control to a point in the program corresponding to the getcontext() call. Execution resumes as if the getcontext() call had just returned. The return value from getcontext() is the same regardless of whether the return is from the initial invocation or using a call to setcontext().
The context created by getcontext() may be modified by the makecontext() function. Refer to makecontext for details.
Portable applications should not modify or access the uc_mcontext member of ucontext_t. A portable application cannot assume that context includes any process-wide static data, possibly including errno. Users manipulating contexts should take care to handle these explicitly when required.
This function is supported only in a POSIX program.
mcontext_t uc_mcontext A machine-specific representation
of the saved context.
ucontext_t *uc_link Pointer to the context that will
be resumed when this context returns.
sigset_t uc_sigmask The set of signals that are blocked
when this context is active.
stack_t uc_stack The stack used by this context.
Special behavior for C++: If getcontext() and setcontext() are used to transfer control in a z/OS® XL C++ program, the behavior in terms of the destruction of automatic objects is undefined. This applies to both z/OS XL C++ and z/OS XL C/C++ ILC modules. The use of getcontext() and setcontext() in conjunction with try(), catch(), and throw() is also undefined.
Do not issue getcontext() in a C++ constructor or destructor, since the saved context would not be usable in a subsequent setcontext() or swapcontext() after the constructor or destructor returns.
- 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_tarea 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
If successful, getcontext() returns 0.
If unsuccessful, getcontext() returns -1.
There are no errno values defined.
Example
/* This example shows the usage of getcontext() and setcontext(). */
#define _XOPEN_SOURCE_EXTENDED 1
#include <stdio.h>
#include <ucontext.h>
void func(void);
int x = 0;
ucontext_t context, *cp = &context;
int main(void) {
getcontext(cp);
if (!x) {
printf("getcontext has been called\n");
func();
}
else {
printf("setcontext has been called\n");
}
}
void func(void) {
x++;
setcontext(cp);
}
getcontext has been called
setcontext has been called
Related information
- ucontext.h
- makecontext() — Modify user context
- setcontext() — Restore user context
- setjmp() — Preserve stack environment
- _setjmp() — Set jump point for a nonlocal goto
- sigaction() — Examine or change a signal action
- sigsetjmp() — Save stack environment and signal mask
- swapcontext() — Save and restore user context