getcontext, setcontext - Initiates and restores user level
ucontext_t *ucp ); int setcontext(
const ucontext_t *ucp );
Interfaces documented on this reference page conform to
industry standards as follows:
getcontext(), setcontext(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Provides a pointer to a ucontext structure, defined in the
<ucontext.h> header file. The ucontext structure contains
the signal mask, execution stack, and machine registers.
(See ucontext(5) for more information about the format of
the ucontext structure.)
Using both the getcontext() and setcontext() functions
enables you to initiate user level context control,
switching between multiple threads of control within a
When you call getcontext(), it initializes the ucp argument
to the current user context of the calling process.
Use the setcontext() function to restore the state of the
user context pointed to by the ucp argument. The setcontext()
function, if successful, does not return; application
execution continues from the point specified by the
ucontext structure you pass to the setcontext() function.
The ucontext structure that you pass to the setcontext()
function must have been created by a call to the getcontext()
function or the makecontext() function, or have
been passed as the third argument to a signal handler.
(The third argument in a call to the sigaction() function
determines the action to be performed when a signal is
delivered. For more information, see sigaction(2).)
When a context structure is created by the getcontext()
function, execution of the program continues as if the
corresponding call of the getcontext() function had just
When a context structure is created by the makecontext()
function, program execution continues with the function
passed to makecontext(). When that function returns, the
thread continues as if after a call to setcontext() with
the context structure argument that was input to makecontext().
If the uc_link member of the ucontext_t structure pointed
to by the ucp argument is 0 (zero), then this context is
the main context, and the thread will exit when this context
returns. The effects of passing a ucp argument from
any other source are unspecified.
When a signal handler executes, the current user context
is saved and a new context is created by the kernel. If
the process leaves the signal handler using the longjmp()
function, the original context cannot be restored, and the
result of future calls to the getcontext() function are
unpredictable. Use the siglongjmp() or setcontext() functions
in signal handlers, instead of the longjmp() function.
The setcontext() function does not return upon success.
The getcontext() function returns 0 (zero) upon success.
Upon failure, both the setcontext() and getcontext() functions
return a value of -1.
Functions: bsd_signal(2), makecontext(2), sigaction(2),
sigaltstack(2), sigprocmask(2), setjmp(3), sigsetjmp(3)
[ Back ]