NAME

getcontext, setcontext - get and set current user context

SYNOPSIS

#include <ucontext.h>

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

DESCRIPTION

These functions, along with those defined in makecontext(3C), are useful for implementing user level context switching between multiple threads of control within a process.

getcontext( ) initializes the structure pointed to by ucp to the current user context of the calling process. The user context is defined by ucontext(5) and includes the contents of the calling process's machine registers, signal mask and execution stack.

setcontext( ) restores the user context pointed to by ucp. The call to setcontext( ) does not return; program execution resumes at the point specified by the context structure passed to setcontext( ). The context structure should have been one created either by a prior call to getcontext( ) or makecontext( ) or passed as the third argument to a signal handler (see sigaction(2)). If the context structure was one created with getcontext( ), program execution continues as if the corresponding call of getcontext( ) had just returned. If the context structure was one created with makecontext, program execution continues with the function specified to makecontext.

RETURN VALUES

On successful completion, setcontext( ) does not return and getcontext( ) returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.

ERRORS

getcontext( ) and setcontext( ) will fail if the following is true:

EFAULT

ucp points to an illegal address.

SEE ALSO

sigaction(2), sigaltstack(2), sigprocmask(2), makecontext(3C), ucontext(5)

NOTES

When a signal handler is executed, the current user context is saved and a new context is created by the kernel. If the process leaves the signal handler via longjmp(3C) the original context will not be restored, and future calls to getcontext( ) will not be reliable. Signal handlers should use siglongjmp(3C) or setcontext( ) instead.