MAKECONTEXT(3C) Standard C Library Functions MAKECONTEXT(3C)
NAME
makecontext,
swapcontext,
swapcontext_extd - manipulate user contexts
SYNOPSIS
#include <ucontext.h> void makecontext(
ucontext_t *ucp,
void (*ifunc)(),
int argc,
...);
int swapcontext(
ucontext_t *restrict oucp,
const ucontext_t *restrict ucp);
int swapcontext_extd(
ucontext_t *restrict oucp,
uint32_t flags,
const ucontext_t *restrict ucp);
DESCRIPTION
The
makecontext() function modifies the context specified by
ucp, which
has been initialized using
getcontext(2) or
getcontext_extd(2). When
this context is resumed using
swapcontext(),
swapcontext_extd(), or
setcontext(2), execution continues by calling the function
func,
passing it the arguments that follow
argc in the
makecontext() call.
The value of
argc must match the number of pointer-sized integer
arguments passed to
func, otherwise the behavior is undefined.
Before a call is made to
makecontext(), the context being modified
should have a stack allocated for it. The stack is assigned to the
context by initializing the
uc_stack member.
The
uc_link member is used to determine the context that will be
resumed when the context being modified by
makecontext() returns. The
uc_link member should be initialized prior to the call to
makecontext(). If the
uc_link member is initialized to NULL, the
thread executing
func will exit when
func returns. See
pthread_exit(3C).
The
swapcontext() function saves the current context in the context
structure pointed to by
oucp and sets the context to the context
structure pointed to by
ucp.
If the
ucp or
oucp argument points to an invalid address, the behavior
is undefined and
errno may be set to EFAULT.
The
swapcontext_extd() function is similar to
swapcontext() except that
it performs a call to
getcontext_extd(2) to get and save the current
context, passing the
flags argument to
getcontext_extd(2). Note, the
same constraints around the initialization of the
ucontext_t that are
discussed in
getcontext_extd(2) still apply. Mainly, the context must
either have originally come from
ucontext_alloc(3C) or prior to its
first use been zeroed. See
getcontext_extd(2) for more information.
RETURN VALUES
On successful completion,
swapcontext() and
swapcontext_extd() return
0. Otherwise,
-1 is returned and
errno is set to indicate the error.
EXAMPLES
Example 1 Alternate execution context on a stack whose memory was
allocated using
mmap().
#include <stdio.h>
#include <ucontext.h>
#include <sys/mman.h>
void
assign(long a, int *b)
{
*b = (int)a;
}
int
main(int argc, char **argv)
{
ucontext_t uc, back;
size_t sz = 0x10000;
int value = 0;
getcontext(&uc);
uc.uc_stack.ss_sp = mmap(0, sz,
PROT_READ | PROT_WRITE | PROT_EXEC,
MAP_PRIVATE | MAP_ANON, -1, 0);
uc.uc_stack.ss_size = sz;
uc.uc_stack.ss_flags = 0;
uc.uc_link = &back;
makecontext(&uc, assign, 2, 100L, &value);
swapcontext(&back, &uc);
printf("done %d\n", value);
return (0);
}
ERRORS
The
swapcontext() and
swapcontext_extd() function will fail if:
ENOMEM The
ucp argument does not have enough stack left to
complete the operation.
The
swapcontext() and
swapcontext_extd() functions may fail if:
EFAULT The
ucp or
oucp argument points to an invalid
address.
The
swapcontext_extd() function may additionally fail if:
EINVAL The
flags argument contains invalid values.
USAGE
These functions are useful for implementing user-level context
switching between multiple threads of control within a process
(co-processing). More effective multiple threads of control can be
obtained by using native support for multithreading. See
threads(7).
INTERFACE STABILITY
CommittedMT-LEVEL MT-SafeSEE ALSO
getcontext(2),
getcontext_extd(2),
mmap(2),
sigaction(2),
sigprocmask(2),
pthread_exit(3C),
ucontext_alloc(3C),
ucontext.h(3HEAD),
attributes(7),
standards(7),
threads(7)NOTES
The semantics of the
uc_stack member of the
ucontext_t structure have
changed as they apply to inputs to
makecontext(). Prior to Solaris 10,
the
ss_sp member of the
uc_stack tructure represented the high memory
address of the area reserved for the stack. The
ss_sp member now
represents the base (low memory address), in keeping with other uses of
ss_sp. This change in the meaning of
ss_sp is the default behavior.
Binary compatibility has been preserved with releases prior to Solaris
10. Before recompiling, applications that use
makecontext() must be
updated to reflect this behavior change. The example below
demonstrates a typical change that must be applied:
--- example1_s9.c Thu Oct 3 11:58:17 2002
+++ example1.c Thu Jun 27 13:28:16 2002
@@ -27,12 +27,9 @@
uc.uc_stack.ss_sp = mmap(0, sz,
PROT_READ | PROT_WRITE | PROT_EXEC,
MAP_PRIVATE | MAP_ANON, -1, 0);
- uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
uc.uc_stack.ss_size = sz;
uc.uc_stack.ss_flags = 0;
uc.uc_link = &back
makecontext(&uc, assign, 2, 100L, &value);
illumos March 20, 2023 illumos
