getcontext() — Get user context

Standards

Standards / Extensions	C or C++	Dependencies
XPG4.2 Single UNIX Specification, Version 3	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.

getcontext() is similar in some respects to sigsetjmp() (and setjmp() and _setjmp()). The getcontext()–setcontext() pair, the sigsetjmp()–siglongjmp() pair, the setjmp()–longjmp() pair, and the _setjmp()–_longjmp() pair cannot be intermixed. A context saved by getcontext() should be restored only by setcontext().

Note: Some compatibility exists with siglongjmp(), so it is possible to use siglongjmp() from a signal handler to restore a context created with getcontext(), but it is not recommended.

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.

The <ucontext.h> header file defines the ucontext_t type as a structure that includes the following members:

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.

Special behavior for XPLINK-compiled C/C++: Restrictions concerning setjmp.h and ucontext.h:

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 saves the context in main with the getcontext() statement. It then returns to that statement from the function func using the setcontext() statement. Since getcontext() always returns 0 if successful, the program uses the variable x to determine if getcontext() returns as a result of setcontext() or not.

/* 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);

}

Output

getcontext has been called
setcontext has been called