xref: /illumos-gate/usr/src/man/man3c/makecontext.3c (revision ed093b41a93e8563e6e1e5dae0768dda2a7bcc27)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2023 Oxide Computer Company
.\"
.Dd March 20, 2023
.Dt MAKECONTEXT 3C
.Os
.Sh NAME
.Nm makecontext ,
.Nm swapcontext ,
.Nm swapcontext_extd
.Nd manipulate user contexts
.Sh SYNOPSIS
.In ucontext.h
.Ft void
.Fo makecontext
.Fa "ucontext_t *ucp"
.Fa "void (*ifunc)()"
.Fa "int argc"
.Fa "..."
.Fc
.Ft int
.Fo swapcontext
.Fa "ucontext_t *restrict oucp"
.Fa "const ucontext_t *restrict ucp"
.Fc
.Ft int
.Fo swapcontext_extd
.Fa "ucontext_t *restrict oucp"
.Fa "uint32_t flags"
.Fa "const ucontext_t *restrict ucp"
.Fc
.Sh DESCRIPTION
The
.Fn makecontext
function modifies the context specified by
.Fa ucp ,
which has been initialized using
.Xr getcontext 2 or
.Xr getcontext_extd 2 .
When this context is resumed using
.Fn swapcontext ,
.Fn swapcontext_extd ,
or
.Xr setcontext 2 ,
execution continues by calling the function
.Fa func ,
passing it the arguments that follow
.Fa argc
in the
.Fn makecontext
call.
The value of
.Fa argc
must match the number of pointer-sized integer arguments passed to
.Fa func ,
otherwise the behavior is undefined.
.Pp
Before a call is made to
.Fn makecontext ,
the context being modified should have a stack allocated for it.
The stack is assigned to the context by initializing the
.Fa uc_stack
member.
.Pp
The
.Fa uc_link
member is used to determine the context that will be resumed when the context
being modified by
.Fn makecontext
returns.
The
.Fa uc_link
member should be initialized prior to the call to
.Fn makecontext .
If the
.Fa uc_link
member is initialized to
.Dv NULL ,
the thread executing
.Fa func
will exit when
.Fa func returns.
See
.Xr pthread_exit 3C .
.Pp
The
.Fn swapcontext
function saves the current context in the context structure pointed to by
.Fa oucp
and sets the context to the context structure pointed to by
.Fa ucp .
.Pp
If the
.Fa ucp
or
.Fa oucp
argument points to an invalid address, the behavior is undefined and
.Va errno
may be set to
.Er EFAULT .
.Pp
The
.Fn swapcontext_extd
function is similar to
.Fn swapcontext
except that it performs a call to
.Xr getcontext_extd 2
to get and save the current context, passing the
.Fa flags
argument to
.Xr getcontext_extd 2 .
Note, the same constraints around the initialization of the
.Vt ucontext_t
that are discussed in
.Xr getcontext_extd 2
still apply.
Mainly, the context must either have originally come from
.Xr ucontext_alloc 3C
or prior to its first use been zeroed.
See
.Xr getcontext_extd 2
for more information.
.Sh RETURN VALUES
On successful completion,
.Fn swapcontext
and
.Fn swapcontext_extd
return
.Sy 0 .
Otherwise,
.Sy -1
is returned and
.Va errno
is set to indicate the error.
.Sh EXAMPLES
.Sy Example 1
Alternate execution context on a stack whose memory was allocated using
.Fn mmap .
.Bd -literal -offset 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\en", value);

        return (0);
}
.Ed
.Sh ERRORS
The
.Fn swapcontext
and
.Fn swapcontext_extd
function will fail if:
.Bl -tag -width Er
.It Er ENOMEM
The
.Fa ucp
argument does not have enough stack left to complete the operation.
.El
.Pp
The
.Fn swapcontext
and
.Fn swapcontext_extd
functions may fail if:
.Bl -tag -width Er
.It Er EFAULT
The
.Fa ucp
or
.Fa oucp
argument points to an invalid address.
.El
.Pp
The
.Fn swapcontext_extd
function may additionally fail if:
.Bl -tag -width Er
.It Er EINVAL
The
.Fa flags
argument contains invalid values.
.El
.Sh USAGE
These functions are useful for implementing user-level context switching
between multiple threads of control within a process
.Pq co-processing .
More effective multiple threads of control can be obtained by using native
support for multithreading.
See
.Xr threads 7 .
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr getcontext 2 ,
.Xr getcontext_extd 2 ,
.Xr mmap 2 ,
.Xr sigaction 2 ,
.Xr sigprocmask 2 ,
.Xr pthread_exit 3C ,
.Xr ucontext_alloc 3C ,
.Xr ucontext.h 3HEAD ,
.Xr attributes 7 ,
.Xr standards 7 ,
.Xr threads 7
.Sh NOTES
The semantics of the
.Fa uc_stack
member of the
.Fa ucontext_t
structure have changed as they apply to inputs to
.Fn makecontext .
Prior to Solaris 10, the
.Fa ss_sp
member of the
.Fa uc_stack
tructure represented the high memory address of the area reserved for the stack.
The
.Fa ss_sp
member now represents the base
.Pq low memory address ,
in keeping with other uses of
.Fa ss_sp .
This change in the meaning of
.Fa ss_sp
is the default behavior.
.Pp
Binary compatibility has been preserved with releases prior to Solaris 10.
Before recompiling, applications that use
.Fn makecontext
must be updated to reflect this behavior change.
The example below demonstrates a typical change that must be applied:
.Bd -literal -offset 2
--- 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);
.fi
.Ed