176 lines
4.6 KiB
Groff
176 lines
4.6 KiB
Groff
|
.\" $NetBSD: makecontext.3,v 1.9 2010/04/29 06:07:35 jruoho Exp $
|
||
|
|
.\"
|
||
|
|
.\" Copyright (c) 2001, 2009 The NetBSD Foundation, Inc.
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
||
|
|
.\" by Klaus Klein.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
||
|
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
||
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
||
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
||
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
.\"
|
||
|
|
.Dd April 29, 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)()" "int argc" ...
|
||
|
|
.Ft int
|
||
|
|
.Fn swapcontext "ucontext_t * restrict oucp" "ucontext_t * restrict ucp"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
The
|
||
|
|
.Fn makecontext
|
||
|
|
function modifies the object pointed to by
|
||
|
|
.Fa ucp ,
|
||
|
|
which has been initialized using
|
||
|
|
.Xr getcontext 2 .
|
||
|
|
When this context is resumed using
|
||
|
|
.Fn swapcontext
|
||
|
|
or
|
||
|
|
.Xr setcontext 2 ,
|
||
|
|
program execution continues as if
|
||
|
|
.Fa func
|
||
|
|
had been called with the arguments specified after
|
||
|
|
.Fa argc
|
||
|
|
in the call of
|
||
|
|
.Fn makecontext .
|
||
|
|
The value of
|
||
|
|
.Fa argc
|
||
|
|
must be equal to the number of integer arguments following it,
|
||
|
|
and must be equal to the number of integer arguments expected by
|
||
|
|
.Fa func ;
|
||
|
|
otherwise, the behavior is undefined.
|
||
|
|
.Pp
|
||
|
|
Before being modified using
|
||
|
|
.Fn makecontext ,
|
||
|
|
a stack must be allocated for the context (in the
|
||
|
|
.Fa uc_stack
|
||
|
|
member), and a context to resume after
|
||
|
|
.Fa func
|
||
|
|
has returned must be determined (pointed to by the
|
||
|
|
.Fa uc_link
|
||
|
|
member);
|
||
|
|
otherwise, the behavior is undefined.
|
||
|
|
If
|
||
|
|
.Fa uc_link
|
||
|
|
is a null pointer, then the context is the main context,
|
||
|
|
and the process will exit with an exit status of 0 upon return.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn swapcontext
|
||
|
|
function saves the current context in the object pointed to by
|
||
|
|
.Fa oucp ,
|
||
|
|
sets the current context to that specified in the object pointed to by
|
||
|
|
.Fa ucp ,
|
||
|
|
and resumes execution.
|
||
|
|
When a context saved by
|
||
|
|
.Fn swapcontext
|
||
|
|
is restored using
|
||
|
|
.Xr setcontext 2 ,
|
||
|
|
execution will resume as if the corresponding invocation of
|
||
|
|
.Fn swapcontext
|
||
|
|
had just returned (successfully).
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
The
|
||
|
|
.Fn makecontext
|
||
|
|
function returns no value.
|
||
|
|
.Pp
|
||
|
|
On success,
|
||
|
|
.Fn swapcontext
|
||
|
|
returns a value of 0,
|
||
|
|
Otherwise, \-1 is returned and
|
||
|
|
.Va errno
|
||
|
|
is set to indicate the error.
|
||
|
|
.Sh ERRORS
|
||
|
|
The
|
||
|
|
.Fn swapcontext
|
||
|
|
function will fail if:
|
||
|
|
.Bl -tag -width Er
|
||
|
|
.It Bq Er EFAULT
|
||
|
|
The
|
||
|
|
.Fa oucp
|
||
|
|
argument or the
|
||
|
|
.Fa ucp
|
||
|
|
argument points to an invalid address.
|
||
|
|
.It Bq Er EINVAL
|
||
|
|
The contents of the datum pointed to by
|
||
|
|
.Fa ucp
|
||
|
|
are invalid.
|
||
|
|
.El
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr _exit 2 ,
|
||
|
|
.Xr getcontext 2 ,
|
||
|
|
.Xr setcontext 2 ,
|
||
|
|
.Xr ucontext 2
|
||
|
|
.Sh STANDARDS
|
||
|
|
The
|
||
|
|
.Fn makecontext
|
||
|
|
and
|
||
|
|
.Fn swapcontext
|
||
|
|
functions conform to
|
||
|
|
.St -xsh5
|
||
|
|
and
|
||
|
|
.St -p1003.1-2001 .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.St -p1003.1-2004
|
||
|
|
revision marked the functions
|
||
|
|
.Fn makecontext
|
||
|
|
and
|
||
|
|
.Fn swapcontext
|
||
|
|
as obsolete, citing portability issues and recommending the use of
|
||
|
|
.Tn POSIX
|
||
|
|
threads instead.
|
||
|
|
The
|
||
|
|
.St -p1003.1-2008
|
||
|
|
revision removed the functions from the specification.
|
||
|
|
.Pp
|
||
|
|
.Bf -symbolic
|
||
|
|
The standard does not clearly define the type of integer arguments
|
||
|
|
passed to
|
||
|
|
.Fa func
|
||
|
|
via
|
||
|
|
.Fn makecontext ;
|
||
|
|
portable applications should not rely on the implementation detail that
|
||
|
|
it may be possible to pass pointer arguments to functions.
|
||
|
|
.Ef
|
||
|
|
This may be clarified in a future revision of the standard.
|
||
|
|
.Sh HISTORY
|
||
|
|
The
|
||
|
|
.Fn makecontext
|
||
|
|
and
|
||
|
|
.Fn swapcontext
|
||
|
|
functions first appeared in
|
||
|
|
.At V.4 .
|
||
|
|
.Sh CAVEATS
|
||
|
|
Due to limitations in the current pthread implementation,
|
||
|
|
.Nm
|
||
|
|
should not be used in programs which link against the
|
||
|
|
.Xr pthread 3
|
||
|
|
library (whether threads are used or not).
|