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, 2022 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 73 The 74 .Fn getcontext 75 function initializes the structure pointed to by 76 .Fa ucp 77 to the current user context of the calling process. 78 The 79 .Vt ucontext_t 80 type that 81 .Fa ucp 82 points to defines the user context and includes the contents of the calling 83 process' machine registers, the signal mask, and the current execution stack. 84 .Pp 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 140 .Fn setcontext 141 function restores the user context pointed to by 142 .Fa ucp . 143 A successful call to 144 .Fn setcontext 145 does not return; program execution resumes at the point specified by the 146 .Fa ucp 147 argument passed to 148 .Fn setcontext . 149 The 150 .Fa ucp 151 argument should be created either by a prior call to 152 .Fn getcontext , 153 or by being passed as an argument to a signal handler. 154 If the 155 .Fa ucp 156 argument was created with 157 .Fn getcontext , 158 program execution continues as if the corresponding call of 159 .Fn getcontext 160 had just returned. 161 If the 162 .Fa ucp 163 argument was created with 164 .Xr makecontext 3C , 165 program execution continues with the function passed to 166 .Xr makecontext 3C . 167 When that function returns, the process continues as if after a call to 168 .Fn setcontext 169 with the 170 .Fa ucp 171 argument that was input to 172 .Xr makecontext 3C . 173 If the 174 .Fa ucp 175 argument was passed to a signal handler, program execution continues with the 176 program instruction following the instruction interrupted by the signal. 177 If the 178 .Fa uc_link 179 member of the 180 .Vt ucontext_t 181 structure pointed to by the 182 .Fa ucp 183 argument is 184 .Dv NULL , 185 then this context is the main context, and the process 186 will exit when this context returns. 187 The effects of passing a 188 .Fa ucp 189 argument obtained from any other source are unspecified. 190 .Sh RETURN VALUES 191 On successful completion, 192 .Fn setcontext 193 does not return and 194 .Fn getcontext 195 and 196 .Fn getcontext_extd 197 returns 0. 198 Otherwise, -1 is returned. 199 .Sh ERRORS 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 216 .Sh USAGE 217 When a signal handler is executed, the current user context is saved and a new 218 context is created. 219 If the thread leaves the signal handler via 220 .Xr longjmp 3C , 221 then it is unspecified whether the context at the time of the corresponding 222 .Xr setjmp 3C 223 call is restored and thus whether future calls to 224 .Fn getcontext 225 will provide an accurate representation of the current context, since the 226 context restored by 227 .Xr longjmp 3C 228 may not contain all the information that 229 .Fn setcontext 230 requires. 231 Signal handlers should use 232 .Xr siglongjmp 3C 233 instead. 234 .Pp 235 Portable applications should not modify or access the 236 .Fa uc_mcontext 237 member of 238 .Vt ucontext_t . 239 A portable application cannot assume that context includes any process-wide 240 static data, possibly including 241 .Va errno . 242 Users manipulating contexts should take care to handle these explicitly when 243 required. 244 .Sh INTERFACE STABILITY 245 .Sy Committed 246 .Sh SEE ALSO 247 .Xr sigaction 2 , 248 .Xr sigaltstack 2 , 249 .Xr sigprocmask 2 , 250 .Xr bsd_signal 3C , 251 .Xr makecontext 3C , 252 .Xr setjmp 3C , 253 .Xr sigsetjmp 3C , 254 .Xr ucontext_alloc 3C , 255 .Xr ucontext.h 3HEAD , 256 .Xr attributes 7 , 257 .Xr standards 7