GETCONTEXT(2) Linux Programmer's Manual GETCONTEXT(2)
NAME
getcontext, setcontext - get or set the user context
SYNOPSIS
#include<ucontext.h>
intgetcontext(ucontext_t*ucp);
intsetcontext(constucontext_t*ucp);
DESCRIPTION
In a SysV-like environment, one has the two types mcontext_t and ucon-
text_t defined in <ucontext.h> and the four functions getcontext(),
setcontext(), makecontext() and swapcontext() that allow user-level
context switching between multiple threads of control within a process.
The mcontext_t type is machine-dependent and opaque. The ucontext_t
type is a structure that has at least the following fields:
typedef struct ucontext {
struct ucontext *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
} ucontext_t;
with sigset_t and stack_t defined in <signal.h>. Here uc_link points
to the context that will be resumed when the current context terminates
(in case the current context was created using makecontext()), uc_sig-
mask is the set of signals blocked in this context (see sigproc-
mask(2)), uc_stack is the stack used by this context (see sigalt-
stack(2)), and uc_mcontext is the machine-specific representation of
the saved context, that includes the calling thread's machine regis-
ters.
The function getcontext() initializes the structure pointed at by ucp
to the currently active context.
The function setcontext() restores the user context pointed at by ucp.
A successful call does not return. The context should have been
obtained by a call of getcontext(), or makecontext(), or passed as
third argument to a signal handler.
If the context was obtained by a call of getcontext(), program execu-
tion continues as if this call just returned.
If the context was obtained by a call of makecontext(), program execu-
tion continues by a call to the function func specified as the second
argument of that call to makecontext(). When the function func
returns, we continue with the uc_link member of the structure ucp spec-
ified as the first argument of that call to makecontext(). When this
member is NULL, the thread exits.
If the context was obtained by a call to a signal handler, then old
standard text says that "program execution continues with the program
instruction following the instruction interrupted by the signal". How-
ever, this sentence was removed in SUSv2, and the present verdict is
"the result is unspecified".
RETURNVALUE
When successful, getcontext() returns 0 and setcontext() does not
return. On error, both return -1 and set errno appropriately.
ERRORS
None defined.
NOTES
The earliest incarnation of this mechanism was the setjmp()/longjmp()
mechanism. Since that does not define the handling of the signal con-
text, the next stage was the sigsetjmp()/siglongjmp() pair. The
present mechanism gives much more control. On the other hand, there is
no easy way to detect whether a return from getcontext() is from the
first call, or via a setcontext() call. The user has to invent her own
bookkeeping device, and a register variable won't do since registers
are restored.
When a signal occurs, the current user context is saved and a new con-
text is created by the kernel for the signal handler. Do not leave the
handler using longjmp() - it is undefined what would happen with con-
texts. Use siglongjmp() or setcontext() instead.
CONFORMINGTO
SUSv2
SEEALSO
sigaction(2), sigaltstack(2), sigprocmask(2), longjmp(3), sigsetjmp(3),
makecontext(3)
Linux 2.4 2001-11-15 GETCONTEXT(2)
Take our 
