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 .\" Copyright 2023 Oxide Computer Company
47 .\"
48 .Dd March 20, 2023
49 .Dt MAKECONTEXT 3C
50 .Os
51 .Sh NAME
52 .Nm makecontext ,
53 .Nm swapcontext ,
54 .Nm swapcontext_extd
55 .Nd manipulate user contexts
56 .Sh SYNOPSIS
57 .In ucontext.h
58 .Ft void
59 .Fo makecontext
60 .Fa "ucontext_t *ucp"
61 .Fa "void (*ifunc)()"
62 .Fa "int argc"
63 .Fa "..."
64 .Fc
65 .Ft int
66 .Fo swapcontext
67 .Fa "ucontext_t *restrict oucp"
68 .Fa "const ucontext_t *restrict ucp"
69 .Fc
70 .Ft int
71 .Fo swapcontext_extd
72 .Fa "ucontext_t *restrict oucp"
73 .Fa "uint32_t flags"
74 .Fa "const ucontext_t *restrict ucp"
75 .Fc
76 .Sh DESCRIPTION
77 The
78 .Fn makecontext
79 function modifies the context specified by
80 .Fa ucp ,
81 which has been initialized using
82 .Xr getcontext 2 or
83 .Xr getcontext_extd 2 .
84 When this context is resumed using
85 .Fn swapcontext ,
86 .Fn swapcontext_extd ,
87 or
88 .Xr setcontext 2 ,
89 execution continues by calling the function
90 .Fa func ,
91 passing it the arguments that follow
92 .Fa argc
93 in the
94 .Fn makecontext
95 call.
96 The value of
97 .Fa argc
98 must match the number of pointer-sized integer arguments passed to
99 .Fa func ,
100 otherwise the behavior is undefined.
101 .Pp
102 Before a call is made to
103 .Fn makecontext ,
104 the context being modified should have a stack allocated for it.
105 The stack is assigned to the context by initializing the
106 .Fa uc_stack
107 member.
108 .Pp
109 The
110 .Fa uc_link
111 member is used to determine the context that will be resumed when the context
112 being modified by
113 .Fn makecontext
114 returns.
115 The
116 .Fa uc_link
117 member should be initialized prior to the call to
118 .Fn makecontext .
119 If the
120 .Fa uc_link
121 member is initialized to
122 .Dv NULL ,
123 the thread executing
124 .Fa func
125 will exit when
126 .Fa func returns.
127 See
128 .Xr pthread_exit 3C .
129 .Pp
130 The
131 .Fn swapcontext
132 function saves the current context in the context structure pointed to by
133 .Fa oucp
134 and sets the context to the context structure pointed to by
135 .Fa ucp .
136 .Pp
137 If the
138 .Fa ucp
139 or
140 .Fa oucp
141 argument points to an invalid address, the behavior is undefined and
142 .Va errno
143 may be set to
144 .Er EFAULT .
145 .Pp
146 The
147 .Fn swapcontext_extd
148 function is similar to
149 .Fn swapcontext
150 except that it performs a call to
151 .Xr getcontext_extd 2
152 to get and save the current context, passing the
153 .Fa flags
154 argument to
155 .Xr getcontext_extd 2 .
156 Note, the same constraints around the initialization of the
157 .Vt ucontext_t
158 that are discussed in
159 .Xr getcontext_extd 2
160 still apply.
161 Mainly, the context must either have originally come from
162 .Xr ucontext_alloc 3C
163 or prior to its first use been zeroed.
164 See
165 .Xr getcontext_extd 2
166 for more information.
167 .Sh RETURN VALUES
168 On successful completion,
169 .Fn swapcontext
170 and
171 .Fn swapcontext_extd
172 return
173 .Sy 0 .
174 Otherwise,
175 .Sy -1
176 is returned and
177 .Va errno
178 is set to indicate the error.
179 .Sh EXAMPLES
180 .Sy Example 1
181 Alternate execution context on a stack whose memory was allocated using
182 .Fn mmap .
183 .Bd -literal -offset 2
184 #include <stdio.h>
185 #include <ucontext.h>
186 #include <sys/mman.h>
187
188 void
189 assign(long a, int *b)
190 {
191 *b = (int)a;
192 }
193
194 int
195 main(int argc, char **argv)
196 {
197 ucontext_t uc, back;
198 size_t sz = 0x10000;
199 int value = 0;
200
201 getcontext(&uc);
202
203 uc.uc_stack.ss_sp = mmap(0, sz,
204 PROT_READ | PROT_WRITE | PROT_EXEC,
205 MAP_PRIVATE | MAP_ANON, -1, 0);
206 uc.uc_stack.ss_size = sz;
207 uc.uc_stack.ss_flags = 0;
208
209 uc.uc_link = &back;
210
211 makecontext(&uc, assign, 2, 100L, &value);
212 swapcontext(&back, &uc);
213
214 printf("done %d\en", value);
215
216 return (0);
217 }
218 .Ed
219 .Sh ERRORS
220 The
221 .Fn swapcontext
222 and
223 .Fn swapcontext_extd
224 function will fail if:
225 .Bl -tag -width Er
226 .It Er ENOMEM
227 The
228 .Fa ucp
229 argument does not have enough stack left to complete the operation.
230 .El
231 .Pp
232 The
233 .Fn swapcontext
234 and
235 .Fn swapcontext_extd
236 functions may fail if:
237 .Bl -tag -width Er
238 .It Er EFAULT
239 The
240 .Fa ucp
241 or
242 .Fa oucp
243 argument points to an invalid address.
244 .El
245 .Pp
246 The
247 .Fn swapcontext_extd
248 function may additionally fail if:
249 .Bl -tag -width Er
250 .It Er EINVAL
251 The
252 .Fa flags
253 argument contains invalid values.
254 .El
255 .Sh USAGE
256 These functions are useful for implementing user-level context switching
257 between multiple threads of control within a process
258 .Pq co-processing .
259 More effective multiple threads of control can be obtained by using native
260 support for multithreading.
261 See
262 .Xr threads 7 .
263 .Sh INTERFACE STABILITY
264 .Sy Committed
265 .Sh MT-LEVEL
266 .Sy MT-Safe
267 .Sh SEE ALSO
268 .Xr getcontext 2 ,
269 .Xr getcontext_extd 2 ,
270 .Xr mmap 2 ,
271 .Xr sigaction 2 ,
272 .Xr sigprocmask 2 ,
273 .Xr pthread_exit 3C ,
274 .Xr ucontext_alloc 3C ,
275 .Xr ucontext.h 3HEAD ,
276 .Xr attributes 7 ,
277 .Xr standards 7 ,
278 .Xr threads 7
279 .Sh NOTES
280 The semantics of the
281 .Fa uc_stack
282 member of the
283 .Fa ucontext_t
284 structure have changed as they apply to inputs to
285 .Fn makecontext .
286 Prior to Solaris 10, the
287 .Fa ss_sp
288 member of the
289 .Fa uc_stack
290 tructure represented the high memory address of the area reserved for the stack.
291 The
292 .Fa ss_sp
293 member now represents the base
294 .Pq low memory address ,
295 in keeping with other uses of
296 .Fa ss_sp .
297 This change in the meaning of
298 .Fa ss_sp
299 is the default behavior.
300 .Pp
301 Binary compatibility has been preserved with releases prior to Solaris 10.
302 Before recompiling, applications that use
303 .Fn makecontext
304 must be updated to reflect this behavior change.
305 The example below demonstrates a typical change that must be applied:
306 .Bd -literal -offset 2
307 --- example1_s9.c Thu Oct 3 11:58:17 2002
308 +++ example1.c Thu Jun 27 13:28:16 2002
309 @@ -27,12 +27,9 @@
310 uc.uc_stack.ss_sp = mmap(0, sz,
311 PROT_READ | PROT_WRITE | PROT_EXEC,
312 MAP_PRIVATE | MAP_ANON, -1, 0);
313 - uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
314 uc.uc_stack.ss_size = sz;
315 uc.uc_stack.ss_flags = 0;
316
317 uc.uc_link = &back
318
319 makecontext(&uc, assign, 2, 100L, &value);
320 .fi
321 .Ed