GETCONTEXT(2) Linux Programmer s Manual GETCONTEXT(2)

NAME getcontext, setcontext - get or set the user context

SYNOPSIS #include <ucontext.h>

int getcontext(ucontext_t *ucp); int setcontext(const ucontext_t *ucp);

DESCRIPTION In a System V-like environment, one has the two types mcontext_t and ucontext_t defined in <ucontext.h> and the four functions getcontext(), setcontext(), makecontext(3) and swapcontext(3) 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(3)), 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(3), 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(3), program execu- tion continues by a call to the function func specified as the second argument of that call to makecontext(3). 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(3). 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".

RETURN VALUE When successful, getcontext() returns 0 and setcontext() does not return. On error, both return -1 and set errno appropriately.

ERRORS None defined.

CONFORMING TO SUSv2, POSIX.1-2001. POSIX.1-2008 removes the specification of getcon- text(), citing portability issues, and recommending that applications be rewritten to use POSIX threads instead.

NOTES The earliest incarnation of this mechanism was the setjmp(3)/longjmp(3) mechanism. Since that does not define the handling of the signal con- text, the next stage was the sigsetjmp(3)/siglongjmp(3) 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 wont 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(3): it is undefined what would happen with con- texts. Use siglongjmp(3) or setcontext() instead.

SEE ALSO sigaction(2), sigaltstack(2), sigprocmask(2), longjmp(3), makecon- text(3), sigsetjmp(3)

COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.

Linux 2009-03-15 GETCONTEXT(2)