1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH MAKECONTEXT 3C "February 17, 2023"
48 .SH NAME
49 makecontext, swapcontext \- manipulate user contexts
50 .SH SYNOPSIS
51 .nf
52 #include <ucontext.h>
53
54 \fBvoid\fR \fBmakecontext\fR(\fBucontext_t *\fR\fIucp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIargc\fR...);
55 .fi
56
57 .LP
58 .nf
59 \fBint\fR \fBswapcontext\fR(\fBucontext_t *restrict\fR \fIoucp\fR,
60 \fBconst ucontext_t *restrict\fR \fIucp\fR);
61 .fi
62
63 .SH DESCRIPTION
64 The \fBmakecontext()\fR function modifies the context specified by \fIucp\fR,
65 which has been initialized using \fBgetcontext\fR(2). When this context is
66 resumed using \fBswapcontext()\fR or \fBsetcontext\fR(2), execution continues
67 by calling the function \fIfunc\fR, passing it the arguments that follow
68 \fIargc\fR in the \fBmakecontext()\fR call. The value of \fIargc\fR must match
69 the number of pointer-sized integer arguments passed to \fIfunc\fR, otherwise
70 the behavior is undefined.
71 .sp
72 .LP
73 Before a call is made to \fBmakecontext()\fR, the context being modified should
74 have a stack allocated for it. The stack is assigned to the context by
75 initializing the \fBuc_stack\fR member.
76 .sp
77 .LP
78 The \fBuc_link\fR member is used to determine the context that will be resumed
79 when the context being modified by \fBmakecontext()\fR returns. The
80 \fBuc_link\fR member should be initialized prior to the call to
81 \fBmakecontext()\fR. If the \fBuc_link\fR member is initialized to \fINULL\fR,
82 the thread executing \fIfunc\fR will exit when \fIfunc\fR returns. See
83 \fBpthread_exit\fR(3C).
84 .sp
85 .LP
86 The \fBswapcontext()\fR function saves the current context in the context
87 structure pointed to by \fIoucp\fR and sets the context to the context
88 structure pointed to by \fIucp\fR.
89 .sp
90 .LP
91 If the \fIucp\fR or \fIoucp\fR argument points to an invalid address, the
92 behavior is undefined and \fBerrno\fR may be set to \fBEFAULT\fR.
93 .SH RETURN VALUES
94 On successful completion, \fBswapcontext()\fR returns \fB0\fR. Otherwise,
95 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
96 .SH ERRORS
97 The \fBswapcontext()\fR function will fail if:
98 .sp
99 .ne 2
100 .na
101 \fB\fBENOMEM\fR\fR
102 .ad
103 .RS 10n
104 The \fIucp\fR argument does not have enough stack left to complete the
105 operation.
106 .RE
107
108 .sp
109 .LP
110 The \fBswapcontext()\fR function may fail if:
111 .sp
112 .ne 2
113 .na
114 \fB\fBEFAULT\fR\fR
115 .ad
116 .RS 10n
117 The \fIucp\fR or \fIoucp\fR argument points to an invalid address.
118 .RE
119
120 .SH EXAMPLES
121 \fBExample 1 \fRAlternate execution context on a stack whose memory was
122 allocated using \fBmmap()\fR.
123 .sp
124 .in +2
125 .nf
126 #include <stdio.h>
127 #include <ucontext.h>
128 #include <sys/mman.h>
129
130 void
131 assign(long a, int *b)
132 {
133 *b = (int)a;
134 }
135
136 int
137 main(int argc, char **argv)
138 {
139 ucontext_t uc, back;
140 size_t sz = 0x10000;
141 int value = 0;
142
143 getcontext(&uc);
144
145 uc.uc_stack.ss_sp = mmap(0, sz,
146 PROT_READ | PROT_WRITE | PROT_EXEC,
147 MAP_PRIVATE | MAP_ANON, -1, 0);
148 uc.uc_stack.ss_size = sz;
149 uc.uc_stack.ss_flags = 0;
150
151 uc.uc_link = &back;
152
153 makecontext(&uc, assign, 2, 100L, &value);
154 swapcontext(&back, &uc);
155
156 printf("done %d\en", value);
157
158 return (0);
159 }
160 .fi
161 .in -2
162
163 .SH USAGE
164 These functions are useful for implementing user-level context switching
165 between multiple threads of control within a process (co-processing). More
166 effective multiple threads of control can be obtained by using native support
167 for multithreading. See \fBthreads\fR(7).
168 .SH ATTRIBUTES
169 See \fBattributes\fR(7) for descriptions of the following attributes:
170 .sp
171
172 .sp
173 .TS
174 box;
175 c | c
176 l | l .
177 ATTRIBUTE TYPE ATTRIBUTE VALUE
178 _
179 Interface Stability Standard
180 _
181 MT-Level MT-Safe
182 .TE
183
184 .SH SEE ALSO
185 .BR getcontext (2),
186 .BR mmap (2),
187 .BR sigaction (2),
188 .BR sigprocmask (2),
189 .BR pthread_exit (3C),
190 .BR ucontext.h (3HEAD),
191 .BR attributes (7),
192 .BR standards (7),
193 .BR threads (7)
194 .SH NOTES
195 The semantics of the \fBuc_stack\fR member of the \fBucontext_t\fR structure
196 have changed as they apply to inputs to \fBmakecontext()\fR. Prior to Solaris
197 10, the \fBss_sp\fR member of the \fBuc_stack\fR structure represented the high
198 memory address of the area reserved for the stack. The \fBss_sp\fR member now
199 represents the base (low memory address), in keeping with other uses of
200 \fBss_sp\fR.
201 .sp
202 .LP
203 This change in the meaning of \fBss_sp\fR is now the default behavior. The
204 \fB-D__MAKECONTEXT_V2_SOURCE\fR compilation flag used in Solaris 9 update
205 releases to access this behavior is obsolete.
206 .sp
207 .LP
208 Binary compatibility has been preserved with releases prior to Solaris 10.
209 Before recompiling, applications that use \fBmakecontext()\fR must be updated
210 to reflect this behavior change. The example below demonstrates a typical change
211 that must be applied:
212 .sp
213 .in +2
214 .nf
215 --- example1_s9.c Thu Oct 3 11:58:17 2002
216 +++ example1.c Thu Jun 27 13:28:16 2002
217 @@ -27,12 +27,9 @@
218 uc.uc_stack.ss_sp = mmap(0, sz,
219 PROT_READ | PROT_WRITE | PROT_EXEC,
220 MAP_PRIVATE | MAP_ANON, -1, 0);
221 - uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
222 uc.uc_stack.ss_size = sz;
223 uc.uc_stack.ss_flags = 0;
224
225 uc.uc_link = &back
226
227 makecontext(&uc, assign, 2, 100L, &value);
228 .fi
229 .in -2
230