NAME

makecontext, swapcontext − manipulate user contexts

SYNOPSIS

#include <ucontext.h>

void makecontext (ucontext_t ∗ucp, (void(∗)())func, int argc,...);

int swapcontext (ucontext_t ∗oucp, ucontext_t ∗ucp);

DESCRIPTION

These functions are useful for implementing user-level context switching between multiple threads of control within a process. 

makecontext modifies the context specified by ucp, which has been initialized using getcontext; when this context is resumed using swapcontext or setcontext [see getcontext(2)], program execution continues by calling the function func, passing it the arguments that follow argc in the makecontext call.  The integer value of argc must match the number of arguments that follow argc.  ­Otherwise the behavior is undefined. 

A process using makecontext to modify a saved context must provide a separate stack area for the context to execute in; the modified context cannot safely use the process’s main stack.  The caller must have changed the values in the uc_stack member of the structure pointed to by ucp before calling makecontext to modify the context.  The new stack area must not overlap either the process’s main stack area or any area defined as the alternate stack by sigaltstack. 

swapcontext saves the current context in the context structure pointed to by oucp and sets the context to the context structure pointed to by ucp. swapcontext does not return; program execution continues at the point specified by the context structure ucp passed to swapcontext. 

These functions will fail if either of the following is true:

ENOMEM ucp does not have enough stack left to complete the operation. 

EFAULT ucp or oucp points to an invalid address. 

SEE ALSO

exit(2), getcontext(2), sigaction(2), sigaltmask(2), sigprocmask(2), ucontext(5). 

DIAGNOSTICS

On successful completion, swapcontext does not return.  Otherwise, a value of −1 is returned and errno is set to indicate the error. 

NOTES

The size of the ucontext_t structure may change in future releases.  To remain binary compatible, users of these features must always use makecontext or getcontext to create new instances of them. 

The size of the new stack area should be at least MINSIGSTKSZ bytes; the value SIGSTKSZ is defined to be the usual size for alternate stack areas.  See sigaltstack(2) for code suggestions on how to allocate a new stack. 

When the process calls setcontext or swapcontext to begin execution in the new context, the process will begin executing on the new stack as though it were the main stack;  the SS_ONSTACK flag will not be set in the uc_stack returned by a subsequent call to sigaltstack unless the caller explicitly set it in the uc_stack member of ucp;  in the latter case the effect will be as though the caller had done an explicit sigaltstack in the new context. 

If the caller does not provide a separate stack area for the context before passing it to makecontext and subsequently switches to the modified context, the process is likely to fail in an unpredictable manner.