Print this page
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/makecontext.3c
+++ new/usr/src/man/man3c/makecontext.3c
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Copyright 1989 AT&T
44 44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 45 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
46 46 .\" Copyright 2023 Oxide Computer Company
47 47 .\"
48 48 .Dd March 20, 2023
49 49 .Dt MAKECONTEXT 3C
50 50 .Os
51 51 .Sh NAME
52 52 .Nm makecontext ,
53 53 .Nm swapcontext ,
54 54 .Nm swapcontext_extd
55 55 .Nd manipulate user contexts
56 56 .Sh SYNOPSIS
57 57 .In ucontext.h
58 58 .Ft void
59 59 .Fo makecontext
60 60 .Fa "ucontext_t *ucp"
61 61 .Fa "void (*ifunc)()"
62 62 .Fa "int argc"
63 63 .Fa "..."
64 64 .Fc
65 65 .Ft int
66 66 .Fo swapcontext
67 67 .Fa "ucontext_t *restrict oucp"
68 68 .Fa "const ucontext_t *restrict ucp"
69 69 .Fc
70 70 .Ft int
71 71 .Fo swapcontext_extd
72 72 .Fa "ucontext_t *restrict oucp"
73 73 .Fa "uint32_t flags"
74 74 .Fa "const ucontext_t *restrict ucp"
75 75 .Fc
76 76 .Sh DESCRIPTION
77 77 The
78 78 .Fn makecontext
79 79 function modifies the context specified by
80 80 .Fa ucp ,
81 81 which has been initialized using
82 82 .Xr getcontext 2 or
83 83 .Xr getcontext_extd 2 .
84 84 When this context is resumed using
85 85 .Fn swapcontext ,
86 86 .Fn swapcontext_extd ,
87 87 or
88 88 .Xr setcontext 2 ,
89 89 execution continues by calling the function
90 90 .Fa func ,
91 91 passing it the arguments that follow
92 92 .Fa argc
93 93 in the
94 94 .Fn makecontext
95 95 call.
96 96 The value of
97 97 .Fa argc
98 98 must match the number of pointer-sized integer arguments passed to
99 99 .Fa func ,
100 100 otherwise the behavior is undefined.
101 101 .Pp
102 102 Before a call is made to
103 103 .Fn makecontext ,
104 104 the context being modified should have a stack allocated for it.
105 105 The stack is assigned to the context by initializing the
106 106 .Fa uc_stack
107 107 member.
108 108 .Pp
109 109 The
110 110 .Fa uc_link
111 111 member is used to determine the context that will be resumed when the context
112 112 being modified by
113 113 .Fn makecontext
114 114 returns.
115 115 The
116 116 .Fa uc_link
117 117 member should be initialized prior to the call to
118 118 .Fn makecontext .
119 119 If the
120 120 .Fa uc_link
121 121 member is initialized to
122 122 .Dv NULL ,
123 123 the thread executing
124 124 .Fa func
125 125 will exit when
126 126 .Fa func returns.
127 127 See
128 128 .Xr pthread_exit 3C .
129 129 .Pp
130 130 The
131 131 .Fn swapcontext
132 132 function saves the current context in the context structure pointed to by
133 133 .Fa oucp
134 134 and sets the context to the context structure pointed to by
135 135 .Fa ucp .
136 136 .Pp
137 137 If the
138 138 .Fa ucp
139 139 or
140 140 .Fa oucp
141 141 argument points to an invalid address, the behavior is undefined and
142 142 .Va errno
143 143 may be set to
144 144 .Er EFAULT .
145 145 .Pp
146 146 The
147 147 .Fn swapcontext_extd
148 148 function is similar to
149 149 .Fn swapcontext
150 150 except that it performs a call to
151 151 .Xr getcontext_extd 2
152 152 to get and save the current context, passing the
153 153 .Fa flags
154 154 argument to
155 155 .Xr getcontext_extd 2 .
156 156 Note, the same constraints around the initialization of the
157 157 .Vt ucontext_t
158 158 that are discussed in
159 159 .Xr getcontext_extd 2
160 160 still apply.
161 161 Mainly, the context must either have originally come from
162 162 .Xr ucontext_alloc 3C
163 163 or prior to its first use been zeroed.
164 164 See
165 165 .Xr getcontext_extd 2
166 166 for more information.
167 167 .Sh RETURN VALUES
168 168 On successful completion,
169 169 .Fn swapcontext
170 170 and
171 171 .Fn swapcontext_extd
172 172 return
173 173 .Sy 0 .
174 174 Otherwise,
175 175 .Sy -1
176 176 is returned and
177 177 .Va errno
178 178 is set to indicate the error.
179 179 .Sh EXAMPLES
180 180 .Sy Example 1
181 181 Alternate execution context on a stack whose memory was allocated using
182 182 .Fn mmap .
183 183 .Bd -literal -offset 2
184 184 #include <stdio.h>
185 185 #include <ucontext.h>
186 186 #include <sys/mman.h>
187 187
188 188 void
189 189 assign(long a, int *b)
190 190 {
191 191 *b = (int)a;
192 192 }
193 193
194 194 int
195 195 main(int argc, char **argv)
196 196 {
197 197 ucontext_t uc, back;
198 198 size_t sz = 0x10000;
199 199 int value = 0;
200 200
201 201 getcontext(&uc);
202 202
203 203 uc.uc_stack.ss_sp = mmap(0, sz,
204 204 PROT_READ | PROT_WRITE | PROT_EXEC,
205 205 MAP_PRIVATE | MAP_ANON, -1, 0);
206 206 uc.uc_stack.ss_size = sz;
207 207 uc.uc_stack.ss_flags = 0;
208 208
209 209 uc.uc_link = &back;
210 210
211 211 makecontext(&uc, assign, 2, 100L, &value);
212 212 swapcontext(&back, &uc);
213 213
214 214 printf("done %d\en", value);
215 215
216 216 return (0);
217 217 }
218 218 .Ed
219 219 .Sh ERRORS
220 220 The
221 221 .Fn swapcontext
222 222 and
223 223 .Fn swapcontext_extd
224 224 function will fail if:
225 225 .Bl -tag -width Er
226 226 .It Er ENOMEM
227 227 The
228 228 .Fa ucp
229 229 argument does not have enough stack left to complete the operation.
230 230 .El
231 231 .Pp
232 232 The
233 233 .Fn swapcontext
234 234 and
235 235 .Fn swapcontext_extd
236 236 functions may fail if:
237 237 .Bl -tag -width Er
238 238 .It Er EFAULT
239 239 The
240 240 .Fa ucp
241 241 or
242 242 .Fa oucp
243 243 argument points to an invalid address.
244 244 .El
245 245 .Pp
246 246 The
247 247 .Fn swapcontext_extd
248 248 function may additionally fail if:
249 249 .Bl -tag -width Er
250 250 .It Er EINVAL
251 251 The
252 252 .Fa flags
253 253 argument contains invalid values.
254 254 .El
255 255 .Sh USAGE
256 256 These functions are useful for implementing user-level context switching
257 257 between multiple threads of control within a process
258 258 .Pq co-processing .
259 259 More effective multiple threads of control can be obtained by using native
260 260 support for multithreading.
261 261 See
262 262 .Xr threads 7 .
263 263 .Sh INTERFACE STABILITY
264 264 .Sy Committed
265 265 .Sh MT-LEVEL
266 266 .Sy MT-Safe
267 267 .Sh SEE ALSO
268 268 .Xr getcontext 2 ,
269 269 .Xr getcontext_extd 2 ,
270 270 .Xr mmap 2 ,
271 271 .Xr sigaction 2 ,
272 272 .Xr sigprocmask 2 ,
273 273 .Xr pthread_exit 3C ,
274 274 .Xr ucontext_alloc 3C ,
275 275 .Xr ucontext.h 3HEAD ,
276 276 .Xr attributes 7 ,
277 277 .Xr standards 7 ,
278 278 .Xr threads 7
279 279 .Sh NOTES
280 280 The semantics of the
281 281 .Fa uc_stack
282 282 member of the
283 283 .Fa ucontext_t
284 284 structure have changed as they apply to inputs to
285 285 .Fn makecontext .
286 286 Prior to Solaris 10, the
287 287 .Fa ss_sp
288 288 member of the
289 289 .Fa uc_stack
290 290 tructure represented the high memory address of the area reserved for the stack.
291 291 The
292 292 .Fa ss_sp
293 293 member now represents the base
294 294 .Pq low memory address ,
295 295 in keeping with other uses of
296 296 .Fa ss_sp .
297 297 This change in the meaning of
298 298 .Fa ss_sp
299 299 is the default behavior.
300 300 .Pp
301 301 Binary compatibility has been preserved with releases prior to Solaris 10.
302 302 Before recompiling, applications that use
303 303 .Fn makecontext
304 304 must be updated to reflect this behavior change.
305 305 The example below demonstrates a typical change that must be applied:
306 306 .Bd -literal -offset 2
307 307 --- example1_s9.c Thu Oct 3 11:58:17 2002
308 308 +++ example1.c Thu Jun 27 13:28:16 2002
309 309 @@ -27,12 +27,9 @@
310 310 uc.uc_stack.ss_sp = mmap(0, sz,
311 311 PROT_READ | PROT_WRITE | PROT_EXEC,
312 312 MAP_PRIVATE | MAP_ANON, -1, 0);
313 313 - uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
314 314 uc.uc_stack.ss_size = sz;
315 315 uc.uc_stack.ss_flags = 0;
316 316
317 317 uc.uc_link = &back
318 318
319 319 makecontext(&uc, assign, 2, 100L, &value);
320 320 .fi
321 321 .Ed
|
↓ open down ↓ |
321 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX