getcontext(2)
getcontext, setcontext --
get and set current user context
Synopsis
#include <ucontext.h>
int getcontext(ucontext_t *ucp);
int setcontext(const 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 "thread".
The user context is defined by
ucontext(5)
and includes the contents of the calling "thread"'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 success, setcontext does not return and getcontext returns 0.
On failure, setcontext and getcontext return -1 and set errno
to identify the error.
References
makecontext(3C),
setjmp(3C),
sigaction(2),
sigaltstack(2),
sigprocmask(2),
ucontext(5)
Notices
When a signal handler is executed, the current user context is saved
and a new context is created by the kernel.
If the "thread" leaves the signal handler via longjmp
[see
setjmp(3C)]
the original context will not be restored, and future calls to
getcontext will not be reliable.
Signal handlers should use siglongjmp
[see
setjmp(3C)]
or setcontext instead.
Considerations for threads programming
setcontext affects the calling thread only; siblings are not affected.
Considerations for lightweight processes
The Threads Library has a ``wrapper'' function for setcontext
that will set the thread's signal mask as well.
The system call itself only modifies the underlying LWP.
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.