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