136 lines
2.8 KiB
Groff
136 lines
2.8 KiB
Groff
.Dd Mar 2, 2010
|
|
.Dt GETCONTEXT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm getcontext ,
|
|
.Nm setcontext
|
|
.Nd get and set current user context
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In ucontext.h
|
|
.Ft int
|
|
.Fn getcontext "ucontext_t *ucp"
|
|
.Ft int
|
|
.Fn setcontext "const ucontext_t *ucp"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Xr makecontext 3
|
|
,
|
|
.Xr swapcontext 3
|
|
,
|
|
.Xr getcontext 3
|
|
, and
|
|
.Xr setcontext 3
|
|
together form a set of functions that allow user-level context switching between multiple threads of control within a process.
|
|
.Pp
|
|
The
|
|
.Vt ucontext_t
|
|
type is a structure that has at least the following members:
|
|
.Bd -offset 4n -literal
|
|
typedef struct __ucontext {
|
|
ucontext_t *uc_link;
|
|
sigset_t uc_sigmask;
|
|
stack_t uc_stack;
|
|
mcontext_t uc_mcontext;
|
|
...
|
|
} ucontext_t;
|
|
.Ed
|
|
|
|
with
|
|
.Vt sigset_t
|
|
and
|
|
.Vt stack_t
|
|
defined in
|
|
.In signal.h .
|
|
Here
|
|
.Va uc_link
|
|
points to the context that will be resumed when the current context returns (if
|
|
.Va uc_link
|
|
is NULL, the process exits),
|
|
.Va uc_sigmask
|
|
is the set of signals blocked in this context,
|
|
.Va uc_stack
|
|
is the stack used by this context (when the context was modified by
|
|
.Xr makecontext 3 ),
|
|
and
|
|
.Va uc_mcontext
|
|
is the machine-specific representation of the saved context. The
|
|
.Vt mcontext_t
|
|
type is machine-dependent and opaque.
|
|
.Pp
|
|
MINIX 3 has an additional
|
|
.Va uc_flags
|
|
member that supports the following flags:
|
|
.Pp
|
|
.Bd -offset 4n -literal
|
|
UCF_IGNSIGM /* Current signal mask is not stored or restored */
|
|
UCF_IGNFPU /* FPU state is not stored or restored for this context */
|
|
.Ed
|
|
.Pp
|
|
Not storing and restoring the signal mask and/or FPU state speeds up context switching considerably.
|
|
.Pp
|
|
The
|
|
.Fn getcontext
|
|
function initializes the structure pointed to by
|
|
.Va ucp
|
|
to the current user context of the calling thread.
|
|
.Pp
|
|
The
|
|
.Fn setcontext
|
|
function restores the user context pointed to by
|
|
.Va ucp .
|
|
A succesful call does not return; program execution resumes at the point specified by the
|
|
.Va ucp
|
|
argument passed to
|
|
.Fn setcontext .
|
|
The
|
|
.Va ucp
|
|
argument should be created either by a prior call to
|
|
.Fn getcontext
|
|
or
|
|
.Fn makecontext .
|
|
If the
|
|
.Va ucp
|
|
argument was created with
|
|
.Fn getcontext ,
|
|
program execution continues as if the corresponding call of
|
|
.Fn getcontext
|
|
had just returned. If the
|
|
.Va ucp
|
|
argument was created with
|
|
.Fn makecontext ,
|
|
program execution continues with the function passed to
|
|
.Fn makecontext .
|
|
|
|
.Sh RETURN VALUES
|
|
When successful,
|
|
.Fn getcontext
|
|
returns 0 and
|
|
.Fn setcontext
|
|
does not return. Otherwise, both return -1 and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
|
|
.Sh ERRORS
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The context is not properly initialized.
|
|
.It Bq Er EFAULT
|
|
.Va ucp
|
|
is a NULL pointer.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr makecontext 3 ,
|
|
.Xr swapcontext 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn getcontext ,
|
|
and
|
|
.Fn setcontext
|
|
functions conform to
|
|
.St -xsh5
|
|
and
|
|
.St -p1003.1-2001 .
|
|
.Sh AUTHORS
|
|
Thomas Veerman
|