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