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
|
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
|