swapcontext(3C)
NAME
makecontext, swapcontext - manipulate user contexts
SYNOPSIS
cc -D__MAKECONTEXT_V2_SOURCE [ flag... ] file... [ library... ]
#include <ucontext.h>
void makecontext(ucontext_t *ucp, void(*func)(), int argc,
...);
int swapcontext(ucontext_t *oucp, const ucontext_t *ucp);
DESCRIPTION
These functions are useful for implementing user-level con-
text switching between multiple threads of control within a
process.
The makecontext() function modifies the context specified by
ucp, which has been initialized using getcontext(2). When
this context is resumed using swapcontext() or setcon-
text(2)), program execution continues by calling the func-
tion 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 value of
argc must match the number of integer arguments passed to
func, otherwise the behavior is undefined.
The uc_link member is used to determine the context that
will be resumed when the context being modified by makecon-
text() 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(3THR).
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 illegal address,
the behavior is undefined and errno may be set to EFAULT.
RETURN VALUES
Upon successful completion, swapcontext() returns 0. Other-
wise, -1 is returned and errno is set to indicate the error.
ERRORS
The swapcontext() function will fail if:
ENOMEM
The ucp argument does not have enough stack left to
complete the operation.
The swapcontext() function may fail if:
EFAULT
The ucp or oucp argument points to an invalid address.
EXAMPLES
Example 1: Alternate execution context on a stack whose
memory was allocated using mmap(2).
#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);
}
USAGE
These functions are useful for implementing user-level con-
text 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 mul-
tithreading. See threads(3THR).
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Standard |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
exit(2), getcontext(2), mmap(2)sigaction(2), sigprocmask(2),
threads(3THR), ucontext(3HEAD), attributes(5)
NOTES
The Solaris 9 4/03 release introduced new semantics for the
uc_stack member of the ucontext_t structure as they apply to
inputs to makecontext(). The previous implementation of
makecontext() for SPARC and SPARCv9 was in violation of the
standard. To access the updated version with the corrected
behavior, specify -D__MAKECONTEXT_V2_SOURCE when invoking
the compiler. See the EXAMPLES section for the correct
usage.
Man(1) output converted with
man2html