.Dd Mar 2, 2010
.Dt MAKECONTEXT 3
.Os
.Sh NAME
.Nm makecontext ,
.Nm swapcontext
.Nd manipulate user contexts
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In ucontext.h
.Ft void
.Fn makecontext "ucontext_t *ucp" "void (*func)(void)" "int argc" ...
.Ft int
.Fn swapcontext "ucontext_t *oucp" "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
.Fn makecontext 
function modifies the user thread pointed to by
.Va ucp
to continue execution by invoking function
.Va func
and passing that function a number of 
.Va argc
integer arguments. The value of
.Va argc
must match the number of integer arguments passed to
.Va func ,
otherwise the behavior is undefined. Context
.Va ucp
must have been initialized by a call to 
.Xr getcontext 3
and have a stack allocated for it. The address of the stack must be assigned to 
.Va ucp->uc_stack.ss_sp
and the size of the stack to
.Va ucp->uc_stack.ss_size .
The
.Va ucp->uc_link
member is used to determine which successor context is run after the context modified by 
.Fn makecontext
returns. If left NULL, the process exits. 
.Pp
The
.Fn swapcontext 
function saves the current context in the context structure pointed to by
.Va oucp
and sets the context to the context structure pointed to by 
.Va ucp .
.Sh RETURN VALUES
When successful,
.Fn swapcontext 
returns 0. Otherwise, -1 is returned and
.Va errno
is set to indicate the error. Note that a successful call to
.Fn swapcontext
actually does not return. Only after returning to the context that called
.Fn swapcontext ,
it appears as if
.Fn swapcontext 
returned 0.
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EFAULT
Either the 
.Va ucp
or
.Va oucp
is a NULL pointer.
.It Bq Er EINVAL
The context is not properly initialized.
.It Bq Er ENOMEM
The
.Va ucp
argument does not have enough stack left to complete the operation.
.El
.Sh SEE ALSO
.Xr getcontext 3 ,
.Xr setcontext 3 
.Sh STANDARDS
The
.Fn makecontext ,
and
.Fn swapcontext
functions conform to
.St -xsh5
and
.St -p1003.1-2001 .
.Sh AUTHORS
Thomas Veerman