minix/man/man3/getcontext.3

97 lines
2.7 KiB
Groff
Raw Normal View History

.TH GETCONTEXT 3 "Mar 2, 2010"
.SH NAME
getcontext, setcontext \- get and set current user context
.SH SYNOPSIS
.nf
.ft B
#include <ucontext.h>
int getcontext(ucontext\_t *\fIucp\fP)
int setcontext(const ucontext\_t *\fIoucp\fP)
.SH DESCRIPTION
The
.BR makecontext (3)
,
.BR swapcontext (3)
,
.BR getcontext (3)
, and
.BR setcontext (3)
together form a set of functions that allow user-level context switching between multiple threads of control within a process.
.PP
The \fIucontext_t\fP type is a structure that has at least the following members:
.in +4
.nf
typedef struct __ucontext {
ucontext_t *uc_link;
sigset_t uc_sigmask;
stack_t uc_stack;
mcontext_t uc_mcontext;
...
} ucontext_t;
.fi
.in
with \fIsigset_t\fP and \fIstack_t\fP defined in
.IR <signal.h> .
Here \fIuc_link\fP points to the context that will be resumed when the current context returns (if \fIuc_link\fP is NULL, the process exits), \fIsigset_t\fP is the set of signals blocks in this context, \fIuc_stack\fP is the stack used by this context (when the context was modified by
.BR makecontext (3)),
and \fIuc_mcontext\fP is the machine-specific representation of the saved context. The \fImcontext_t\fP type is machine-dependent and opaque.
.PP
MINIX 3 has an additional \fIuc_flags\fP member that supports the following flags:
.PP
.in +2
.nf
UCF_IGNSIGM /* Current signal mask is not stored or restored */
UCF_IGNFPU /* FPU state is not stored or restored for this context */
.fi
.in
.PP
Not storing and restoring the signal mask and/or FPU state speeds up context switching considerably.
.PP
The
.BR getcontext ()
function initializes the structure pointed to by \fIucp\fP to the current user context of the calling thread.
.PP
The
.BR setcontext ()
function restores the user context pointed to by \fIucp\fP. A succesful call does not return; program execution resumes at the point specified by the \fIucp\fP argument passed to
.BR setcontext ().
The \fIucp\fP argument should be created either by a prior call to
.BR getcontext ()
or
.BR makecontext ().
If the \fIucp\fP argument was created with
.BR getcontext (),
program execution continues as if the corresponding call of
.BR getcontext ()
had just returned. If the \fIucp\fP argument was created with
.BR makecontext (),
program execution continues with the function passed to
.BR makecontext ().
.SH "RETURN VALUE"
When successful,
.BR getcontext ()
returns 0 and
.BR setcontext ()
does not return. Otherwise, both return -1 and
.I errno
is set to indicate the error.
.SH "ERRORS"
.TP 15
[EINVAL]
The context is not properly initialized.
.TP 15
[EFAULT]
\fIucp\fP is a NULL pointer.
.SH "SEE ALSO"
.BR makecontext (3).
.SH "AUTHORS"
Thomas Veerman