GETCONTEXT(3)

NAME
getcontext, setcontext - get and set current user context

LIBRARY
libc

SYNOPSIS
#include <ucontext.h>
int
getcontext(ucontext_t *ucp);
int
setcontext(const ucontext_t *ucp);

DESCRIPTION
The makecontext(3) , swapcontext(3) , getcontext(3) , and setcontext(3) together form a set of functions that allow user-level context switching between multiple threads of control within a process.

The ucontext_t type is a structure that has at least the following members:

    typedef struct __ucontext {
    	ucontext_t *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 returns (if uc_link is NULL, the process exits), uc_sigmask is the set of signals blocked in this context, uc_stack is the stack used by this context (when the context was modified by makecontext(3) ), and uc_mcontext is the machine-specific representation of the saved context. The mcontext_t type is machine-dependent and opaque.

MINIX 3 has an additional uc_flags member that supports the following flags:

    UCF_IGNSIGM /* Current signal mask is not stored or restored */
    UCF_IGNFPU  /* FPU state is not stored or restored for this context */

Not storing and restoring the signal mask and/or FPU state speeds up context switching considerably.

The getcontext() function initializes the structure pointed to by ucp to the current user context of the calling thread.

The setcontext() function restores the user context pointed to by ucp. A succesful call does not return; program execution resumes at the point specified by the ucp argument passed to setcontext(). The ucp argument should be created either by a prior call to getcontext() or makecontext(). If the ucp argument was created with getcontext(), program execution continues as if the corresponding call of getcontext() had just returned. If the ucp argument was created with makecontext(), program execution continues with the function passed to makecontext().

RETURN VALUES
When successful, getcontext() returns 0 and setcontext() does not return. Otherwise, both return -1 and errno is set to indicate the error.

ERRORS

[EINVAL]
    The context is not properly initialized.

[EFAULT]
    ucp is a NULL pointer.

SEE ALSO
makecontext(3), swapcontext(3)

STANDARDS
The getcontext(), and setcontext() functions conform to xsh5 and p1003.1-2001.

AUTHORS
Thomas Veerman