minix/man/man3/getcontext.3

.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