Man Getcontext en anglais
GETCONTEXT(2) Linux Programmer's Manual GETCONTEXT(2)
NAME
getcontext, setcontext - get or set the user context
SYNOPSIS
#include
int getcontext(ucontext_t *ucp);
int setcontext(const ucontext_t *ucp);
DESCRIPTION
In a System V-like environment, one has the two types mcontext_t and
ucontext_t defined in and the four functions getcontext(),
setcontext(), makecontext(3) and swapcontext(3) that allow user-level
context switching between multiple threads of control within a process.
The mcontext_t type is machine-dependent and opaque. The ucontext_t
type is a structure that has at least the following fields:
typedef struct ucontext {
struct ucontext *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
} ucontext_t;
with sigset_t and stack_t defined in . Here uc_link points
to the context that will be resumed when the current context terminates
(in case the current context was created using makecontext(3)), uc_sig-
mask is the set of signals blocked in this context (see sigproc-
mask(2)), uc_stack is the stack used by this context (see sigalt-
stack(2)), and uc_mcontext is the machine-specific representation of
the saved context, that includes the calling thread's machine regis-
ters.
The function getcontext() initializes the structure pointed at by ucp
to the currently active context.
The function setcontext() restores the user context pointed at by ucp.
A successful call does not return. The context should have been
obtained by a call of getcontext(), or makecontext(3), or passed as
third argument to a signal handler.
If the context was obtained by a call of getcontext(), program execu-
tion continues as if this call just returned.
If the context was obtained by a call of makecontext(3), program execu-
tion continues by a call to the function func specified as the second
argument of that call to makecontext(3). When the function func
returns, we continue with the uc_link member of the structure ucp spec-
ified as the first argument of that call to makecontext(3). When this
member is NULL, the thread exits.
If the context was obtained by a call to a signal handler, then old
standard text says that "program execution continues with the program
instruction following the instruction interrupted by the signal". How-
ever, this sentence was removed in SUSv2, and the present verdict is
"the result is unspecified".
RETURN VALUE
When successful, getcontext() returns 0 and setcontext() does not
return. On error, both return -1 and set errno appropriately.
ERRORS
None defined.
CONFORMING TO
SUSv2, POSIX.1-2001.
NOTES
The earliest incarnation of this mechanism was the setjmp(3)/longjmp(3)
mechanism. Since that does not define the handling of the signal con-
text, the next stage was the sigsetjmp(3)/siglongjmp(3) pair. The
present mechanism gives much more control. On the other hand, there is
no easy way to detect whether a return from getcontext() is from the
first call, or via a setcontext() call. The user has to invent her own
bookkeeping device, and a register variable won't do since registers
are restored.
When a signal occurs, the current user context is saved and a new con-
text is created by the kernel for the signal handler. Do not leave the
handler using longjmp(3): it is undefined what would happen with con-
texts. Use siglongjmp(3) or setcontext() instead.
SEE ALSO
sigaction(2), sigaltstack(2), sigprocmask(2), longjmp(3), makecon-
text(3), sigsetjmp(3)
COLOPHON
This page is part of release 3.05 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2001-11-15 GETCONTEXT(2)
|
