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