NAME
getcontext(), setcontext() — get and set current user context; DEPRECATED
SYNOPSIS
#include <ucontext.h>
int getcontext(ucontext_t *ucp);
int setcontext(const ucontext_t *ucp);
Remarks
getcontext()
and
setcontext()
are deprecated.
See the
WARNINGS
section.
DESCRIPTION
The
getcontext()
function initializes the structure pointed to by
ucp
to the current user context of the
calling process. The
ucontext_t
type that
ucp
points to defines the user context and includes the
contents of the calling process' machine registers,
the signal mask, and the current execution stack.
The
setcontext()
function restores the user context pointed to by
ucp.
A successful call to
setcontext()
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 by being passed as an argument to a signal handler.
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().
When that function returns, the process continues as if after a call to
setcontext()
with the
ucp
argument that was input to
makecontext().
If the
ucp
argument was passed to a signal handler, program execution continues
with the program instruction following the instruction
interrupted by the signal. If the
uc_link
member of the
ucontext_t
structure pointed to by the
ucp
argument is equal to 0, then this context is the main context, and
the process will exit when this context returns. The effects of
passing a
ucp
argument obtained from any other source are unspecified.
RETURN VALUE
On successful completion,
setcontext()
does not return and
getcontext()
returns 0. Otherwise, a value of -1 is returned.
WARNINGS
getcontext()
and
setcontext()
are deprecated and should be used only by legacy applications.
Context APIs are not recommended due to possible compatibility
problems from release to release,
because context APIs are very architecture-specific.
The context APIs "expose" the architecture to the application, such
that the application may not be compatible with all releases.
If you must use context APIs, be aware of the following:
Do not copy the context yourself. It is not contiguous.
The context may have pointers that may point back to the
original context rather than in the copied context; hence,
it will be broken.
The size of the context will vary in length from release to release.
ERRORS
No errors are defined.
APPLICATION USAGE
When a signal handler is executed, the current user
context is saved and a new context is created. If
the process leaves the signal handler via
longjmp(),
then it is unspecified whether the context at the
time of the corresponding
setjmp()
call is restored and thus whether future calls to
getcontext()
will provide an accurate representation of the current
context, since the context restored by
longjmp()
may not contain all the information that
setcontext()
requires. Signal handlers should use
siglongjmp()
or
setcontext()
instead.
Portable applications should not modify or access the
uc_mcontext
member of
ucontext_t.
A portable application cannot assume that context includes
any process-wide static data, possibly including
errno.
Users manipulating contexts should take care to
handle these explicitly when required.
Printable version
