Print this page
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/getcontext.2
+++ new/usr/src/man/man2/getcontext.2
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) 2001, Sun Microsystems, Inc. All Rights Reserved.
46 46 .\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association.
47 47 .\" Copyright 2023 Oxide Computer Company
48 48 .\"
49 49 .Dd January 24, 2022
50 50 .Dt GETCONTEXT 2
51 51 .Os
52 52 .Sh NAME
53 53 .Nm getcontext ,
54 54 .Nm getcontext_extd ,
55 55 .Nm setcontext
56 56 .Nd get and set current user context
57 57 .Sh SYNOPSIS
58 58 .In ucontext.h
59 59 .Ft int
60 60 .Fo getcontext
61 61 .Fa "ucontext_t *ucp"
62 62 .Fc
63 63 .Ft int
64 64 .Fo getcontext_extd
65 65 .Fa "ucontext_t *ucp"
66 66 .Fa "uint32_t flags"
67 67 .Fc
68 68 .Ft int
69 69 .Fo setcontext
70 70 .Fa "const ucontext_t *ucp"
71 71 .Fc
72 72 .Sh DESCRIPTION
73 73 The
74 74 .Fn getcontext
75 75 function initializes the structure pointed to by
76 76 .Fa ucp
77 77 to the current user context of the calling process.
78 78 The
79 79 .Vt ucontext_t
80 80 type that
81 81 .Fa ucp
82 82 points to defines the user context and includes the contents of the calling
83 83 process' machine registers, the signal mask, and the current execution stack.
84 84 .Pp
85 85 The
86 86 .Vt ucontext_t
87 87 structure is a part of the system ABI.
88 88 However, most architectures have added additional register states such as the
89 89 extended vector and floating point registers that are not part of that.
90 90 To facilitate getting that state
91 91 .Pq such as the x86 xsave area
92 92 the
93 93 .Fn getcontext_extd
94 94 function exists.
95 95 Once called, the context will be initialized and is suitable for use in other
96 96 context operations just as though one had called
97 97 .Fn getcontext .
98 98 .Pp
99 99 Unlike the
100 100 .Fn getcontext
101 101 function,
102 102 .Fn getcontext_extd
103 103 assumes that callers have previously initialized
104 104 .Fa ucp
105 105 and thus it treats additional members
106 106 .Po
107 107 such as the
108 108 .Fa uc_xsave
109 109 member on x86
110 110 .Pc
111 111 as potentially valid.
112 112 To allow for all extended states to be copied out,
113 113 .Fa ucp
114 114 must be allocated with
115 115 .Xr ucontext_alloc 3C .
116 116 Otherwise whether it is declared on the stack, as global data, allocated
117 117 dynamically, or part of a structure,
118 118 .Fa ucp
119 119 must be zeroed through a call to
120 120 .Xr bzero 3C
121 121 or
122 122 .Xr memset 3C
123 123 prior to calling
124 124 .Fn getcontext_extd .
125 125 Improper initialization can lead to memory safety bugs, making it critical that
126 126 this is done.
127 127 .Pp
128 128 The
129 129 .Fa flags
130 130 member must be zero and is present to allow for what is copied out to change in
131 131 the future.
132 132 This indicates that the system should attempt to copy out all extended states,
133 133 though if the
134 134 .Vt ucontext_t
135 135 was not allocated with
136 136 .Xr ucontext_alloc 3C ,
137 137 some extended states may not be.
138 138 .Pp
139 139 The
140 140 .Fn setcontext
141 141 function restores the user context pointed to by
142 142 .Fa ucp .
143 143 A successful call to
144 144 .Fn setcontext
145 145 does not return; program execution resumes at the point specified by the
146 146 .Fa ucp
147 147 argument passed to
148 148 .Fn setcontext .
149 149 The
150 150 .Fa ucp
151 151 argument should be created either by a prior call to
152 152 .Fn getcontext ,
153 153 or by being passed as an argument to a signal handler.
154 154 If the
155 155 .Fa ucp
156 156 argument was created with
157 157 .Fn getcontext ,
158 158 program execution continues as if the corresponding call of
159 159 .Fn getcontext
160 160 had just returned.
161 161 If the
162 162 .Fa ucp
163 163 argument was created with
164 164 .Xr makecontext 3C ,
165 165 program execution continues with the function passed to
166 166 .Xr makecontext 3C .
167 167 When that function returns, the process continues as if after a call to
168 168 .Fn setcontext
169 169 with the
170 170 .Fa ucp
171 171 argument that was input to
172 172 .Xr makecontext 3C .
173 173 If the
174 174 .Fa ucp
175 175 argument was passed to a signal handler, program execution continues with the
176 176 program instruction following the instruction interrupted by the signal.
177 177 If the
178 178 .Fa uc_link
179 179 member of the
180 180 .Vt ucontext_t
181 181 structure pointed to by the
182 182 .Fa ucp
183 183 argument is
184 184 .Dv NULL ,
185 185 then this context is the main context, and the process
186 186 will exit when this context returns.
187 187 The effects of passing a
188 188 .Fa ucp
189 189 argument obtained from any other source are unspecified.
190 190 .Sh RETURN VALUES
191 191 On successful completion,
192 192 .Fn setcontext
193 193 does not return and
194 194 .Fn getcontext
195 195 and
196 196 .Fn getcontext_extd
197 197 returns 0.
198 198 Otherwise, -1 is returned.
199 199 .Sh ERRORS
200 200 No errors are defined for
201 201 .Fn getcontext
202 202 or
203 203 .Fn setcontext .
204 204 .Pp
205 205 The
206 206 .Fn getcontext_extd
207 207 function only sets
208 208 .Va errno
209 209 in some circumstances when it fails.
210 210 The function may fail if:
211 211 .Bl -tag -width Er
212 212 .It Er EINVAL
213 213 .Fa flags
214 214 had invalid values.
215 215 .El
216 216 .Sh USAGE
217 217 When a signal handler is executed, the current user context is saved and a new
218 218 context is created.
219 219 If the thread leaves the signal handler via
220 220 .Xr longjmp 3C ,
221 221 then it is unspecified whether the context at the time of the corresponding
222 222 .Xr setjmp 3C
223 223 call is restored and thus whether future calls to
224 224 .Fn getcontext
225 225 will provide an accurate representation of the current context, since the
226 226 context restored by
227 227 .Xr longjmp 3C
228 228 may not contain all the information that
229 229 .Fn setcontext
230 230 requires.
231 231 Signal handlers should use
232 232 .Xr siglongjmp 3C
233 233 instead.
234 234 .Pp
235 235 Portable applications should not modify or access the
236 236 .Fa uc_mcontext
237 237 member of
238 238 .Vt ucontext_t .
239 239 A portable application cannot assume that context includes any process-wide
240 240 static data, possibly including
241 241 .Va errno .
242 242 Users manipulating contexts should take care to handle these explicitly when
243 243 required.
244 244 .Sh INTERFACE STABILITY
245 245 .Sy Committed
246 246 .Sh SEE ALSO
247 247 .Xr sigaction 2 ,
248 248 .Xr sigaltstack 2 ,
249 249 .Xr sigprocmask 2 ,
250 250 .Xr bsd_signal 3C ,
251 251 .Xr makecontext 3C ,
252 252 .Xr setjmp 3C ,
253 253 .Xr sigsetjmp 3C ,
254 254 .Xr ucontext_alloc 3C ,
255 255 .Xr ucontext.h 3HEAD ,
256 256 .Xr attributes 7 ,
257 257 .Xr standards 7
|
↓ open down ↓ |
257 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX