166492cf0SYuri Pankov.\" 266492cf0SYuri Pankov.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 366492cf0SYuri Pankov.\" permission to reproduce portions of its copyrighted documentation. 466492cf0SYuri Pankov.\" Original documentation from The Open Group can be obtained online at 5c10c16deSRichard Lowe.\" http://www.opengroup.org/bookstore/. 666492cf0SYuri Pankov.\" 766492cf0SYuri Pankov.\" The Institute of Electrical and Electronics Engineers and The Open 866492cf0SYuri Pankov.\" Group, have given us permission to reprint portions of their 966492cf0SYuri Pankov.\" documentation. 1066492cf0SYuri Pankov.\" 1166492cf0SYuri Pankov.\" In the following statement, the phrase ``this text'' refers to portions 1266492cf0SYuri Pankov.\" of the system documentation. 1366492cf0SYuri Pankov.\" 1466492cf0SYuri Pankov.\" Portions of this text are reprinted and reproduced in electronic form 1566492cf0SYuri Pankov.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 1666492cf0SYuri Pankov.\" Standard for Information Technology -- Portable Operating System 1766492cf0SYuri Pankov.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 1866492cf0SYuri Pankov.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 1966492cf0SYuri Pankov.\" Engineers, Inc and The Open Group. In the event of any discrepancy 2066492cf0SYuri Pankov.\" between these versions and the original IEEE and The Open Group 2166492cf0SYuri Pankov.\" Standard, the original IEEE and The Open Group Standard is the referee 2266492cf0SYuri Pankov.\" document. The original Standard can be obtained online at 2366492cf0SYuri Pankov.\" http://www.opengroup.org/unix/online.html. 2466492cf0SYuri Pankov.\" 25c10c16deSRichard Lowe.\" This notice shall appear on any product containing this material. 2666492cf0SYuri Pankov.\" 2766492cf0SYuri Pankov.\" The contents of this file are subject to the terms of the 2866492cf0SYuri Pankov.\" Common Development and Distribution License (the "License"). 2966492cf0SYuri Pankov.\" You may not use this file except in compliance with the License. 3066492cf0SYuri Pankov.\" 3166492cf0SYuri Pankov.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 3266492cf0SYuri Pankov.\" or http://www.opensolaris.org/os/licensing. 3366492cf0SYuri Pankov.\" See the License for the specific language governing permissions 3466492cf0SYuri Pankov.\" and limitations under the License. 3566492cf0SYuri Pankov.\" 3666492cf0SYuri Pankov.\" When distributing Covered Code, include this CDDL HEADER in each 3766492cf0SYuri Pankov.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 3866492cf0SYuri Pankov.\" If applicable, add the following below this CDDL HEADER, with the 3966492cf0SYuri Pankov.\" fields enclosed by brackets "[]" replaced with your own identifying 4066492cf0SYuri Pankov.\" information: Portions Copyright [yyyy] [name of copyright owner] 4166492cf0SYuri Pankov.\" 4266492cf0SYuri Pankov.\" 4366492cf0SYuri Pankov.\" Copyright 1989 AT&T 4466492cf0SYuri Pankov.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. 4566492cf0SYuri Pankov.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved. 463f3c90a9SAndy Fiddaman.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association. 47*ed093b41SRobert Mustacchi.\" Copyright 2023 Oxide Computer Company 4866492cf0SYuri Pankov.\" 49*ed093b41SRobert Mustacchi.Dd January 24, 2023 503f3c90a9SAndy Fiddaman.Dt GETCONTEXT 2 513f3c90a9SAndy Fiddaman.Os 523f3c90a9SAndy Fiddaman.Sh NAME 533f3c90a9SAndy Fiddaman.Nm getcontext , 54*ed093b41SRobert Mustacchi.Nm getcontext_extd , 553f3c90a9SAndy Fiddaman.Nm setcontext 563f3c90a9SAndy Fiddaman.Nd get and set current user context 573f3c90a9SAndy Fiddaman.Sh SYNOPSIS 583f3c90a9SAndy Fiddaman.In ucontext.h 593f3c90a9SAndy Fiddaman.Ft int 603f3c90a9SAndy Fiddaman.Fo getcontext 613f3c90a9SAndy Fiddaman.Fa "ucontext_t *ucp" 623f3c90a9SAndy Fiddaman.Fc 633f3c90a9SAndy Fiddaman.Ft int 64*ed093b41SRobert Mustacchi.Fo getcontext_extd 65*ed093b41SRobert Mustacchi.Fa "ucontext_t *ucp" 66*ed093b41SRobert Mustacchi.Fa "uint32_t flags" 67*ed093b41SRobert Mustacchi.Fc 68*ed093b41SRobert Mustacchi.Ft int 693f3c90a9SAndy Fiddaman.Fo setcontext 703f3c90a9SAndy Fiddaman.Fa "const ucontext_t *ucp" 713f3c90a9SAndy Fiddaman.Fc 723f3c90a9SAndy Fiddaman.Sh DESCRIPTION 733f3c90a9SAndy FiddamanThe 743f3c90a9SAndy Fiddaman.Fn getcontext 753f3c90a9SAndy Fiddamanfunction initializes the structure pointed to by 763f3c90a9SAndy Fiddaman.Fa ucp 773f3c90a9SAndy Fiddamanto the current user context of the calling process. 783f3c90a9SAndy FiddamanThe 793f3c90a9SAndy Fiddaman.Vt ucontext_t 803f3c90a9SAndy Fiddamantype that 813f3c90a9SAndy Fiddaman.Fa ucp 823f3c90a9SAndy Fiddamanpoints to defines the user context and includes the contents of the calling 833f3c90a9SAndy Fiddamanprocess' machine registers, the signal mask, and the current execution stack. 843f3c90a9SAndy Fiddaman.Pp 853f3c90a9SAndy FiddamanThe 86*ed093b41SRobert Mustacchi.Vt ucontext_t 87*ed093b41SRobert Mustacchistructure is a part of the system ABI. 88*ed093b41SRobert MustacchiHowever, most architectures have added additional register states such as the 89*ed093b41SRobert Mustacchiextended vector and floating point registers that are not part of that. 90*ed093b41SRobert MustacchiTo facilitate getting that state 91*ed093b41SRobert Mustacchi.Pq such as the x86 xsave area 92*ed093b41SRobert Mustacchithe 93*ed093b41SRobert Mustacchi.Fn getcontext_extd 94*ed093b41SRobert Mustacchifunction exists. 95*ed093b41SRobert MustacchiOnce called, the context will be initialized and is suitable for use in other 96*ed093b41SRobert Mustacchicontext operations just as though one had called 97*ed093b41SRobert Mustacchi.Fn getcontext . 98*ed093b41SRobert Mustacchi.Pp 99*ed093b41SRobert MustacchiWhen calling the 100*ed093b41SRobert Mustacchi.Fn getcontext 101*ed093b41SRobert Mustacchifunction the 102*ed093b41SRobert Mustacchi.Vt ucontext_t 103*ed093b41SRobert Mustacchiis completely overwritten without regards for what is currently present. 104*ed093b41SRobert MustacchiThis is different when using 105*ed093b41SRobert Mustacchi.Fn getcontext_extd . 106*ed093b41SRobert MustacchiInstead, the 107*ed093b41SRobert Mustacchi.Vt ucontext_t 108*ed093b41SRobert Mustacchistructure is read by the kernel and it assumes that the user has 109*ed093b41SRobert Mustacchiinitialized it. 110*ed093b41SRobert MustacchiThis allows the system to consider members of the 111*ed093b41SRobert Mustacchi.Vt ucontext_T 112*ed093b41SRobert Mustacchi.Po 113*ed093b41SRobert Mustacchisuch as the 114*ed093b41SRobert Mustacchi.Fa uc_xsave 115*ed093b41SRobert Mustacchimember on x86 116*ed093b41SRobert Mustacchi.Pc 117*ed093b41SRobert Mustacchito point to properly sized memory. 118*ed093b41SRobert Mustacchi.Pp 119*ed093b41SRobert MustacchiTo allow for all extended states to be copied out, 120*ed093b41SRobert Mustacchi.Fa ucp 121*ed093b41SRobert Mustacchimust be allocated with 122*ed093b41SRobert Mustacchi.Xr ucontext_alloc 3C . 123*ed093b41SRobert MustacchiOtherwise whether it is declared on the stack, as global data, allocated 124*ed093b41SRobert Mustacchidynamically, or part of a structure, 125*ed093b41SRobert Mustacchi.Fa ucp 126*ed093b41SRobert Mustacchimust be zeroed through a call to 127*ed093b41SRobert Mustacchi.Xr bzero 3C 128*ed093b41SRobert Mustacchior 129*ed093b41SRobert Mustacchi.Xr memset 3C 130*ed093b41SRobert Mustacchiprior to calling 131*ed093b41SRobert Mustacchi.Fn getcontext_extd . 132*ed093b41SRobert MustacchiImproper initialization can lead to memory safety bugs, making it critical that 133*ed093b41SRobert Mustacchithis is done. 134*ed093b41SRobert Mustacchi.Pp 135*ed093b41SRobert MustacchiThe 136*ed093b41SRobert Mustacchi.Fa flags 137*ed093b41SRobert Mustacchimember must be zero and is present to allow for what is copied out to change in 138*ed093b41SRobert Mustacchithe future. 139*ed093b41SRobert MustacchiThis indicates that the system should attempt to copy out all extended states, 140*ed093b41SRobert Mustacchithough if the 141*ed093b41SRobert Mustacchi.Vt ucontext_t 142*ed093b41SRobert Mustacchiwas not allocated with 143*ed093b41SRobert Mustacchi.Xr ucontext_alloc 3C , 144*ed093b41SRobert Mustacchisome extended states may not be. 145*ed093b41SRobert MustacchiThis happens because 146*ed093b41SRobert Mustacchi.Xr ucontext_alloc 3C 147*ed093b41SRobert Mustacchitakes care of allocating and setting up the 148*ed093b41SRobert Mustacchi.Vt ucontext_t 149*ed093b41SRobert Mustacchito indicate that memory beyond the 150*ed093b41SRobert Mustacchi.Vt ucontext_t 151*ed093b41SRobert Mustacchiis valid and the corresponding flags in the structure are set. 152*ed093b41SRobert Mustacchi.Pp 153*ed093b41SRobert MustacchiThe 1543f3c90a9SAndy Fiddaman.Fn setcontext 1553f3c90a9SAndy Fiddamanfunction restores the user context pointed to by 1563f3c90a9SAndy Fiddaman.Fa ucp . 1573f3c90a9SAndy FiddamanA successful call to 1583f3c90a9SAndy Fiddaman.Fn setcontext 1593f3c90a9SAndy Fiddamandoes not return; program execution resumes at the point specified by the 1603f3c90a9SAndy Fiddaman.Fa ucp 1613f3c90a9SAndy Fiddamanargument passed to 1623f3c90a9SAndy Fiddaman.Fn setcontext . 1633f3c90a9SAndy FiddamanThe 1643f3c90a9SAndy Fiddaman.Fa ucp 1653f3c90a9SAndy Fiddamanargument should be created either by a prior call to 1663f3c90a9SAndy Fiddaman.Fn getcontext , 1673f3c90a9SAndy Fiddamanor by being passed as an argument to a signal handler. 1683f3c90a9SAndy FiddamanIf the 1693f3c90a9SAndy Fiddaman.Fa ucp 1703f3c90a9SAndy Fiddamanargument was created with 1713f3c90a9SAndy Fiddaman.Fn getcontext , 1723f3c90a9SAndy Fiddamanprogram execution continues as if the corresponding call of 1733f3c90a9SAndy Fiddaman.Fn getcontext 1743f3c90a9SAndy Fiddamanhad just returned. 1753f3c90a9SAndy FiddamanIf the 1763f3c90a9SAndy Fiddaman.Fa ucp 1773f3c90a9SAndy Fiddamanargument was created with 1783f3c90a9SAndy Fiddaman.Xr makecontext 3C , 1793f3c90a9SAndy Fiddamanprogram execution continues with the function passed to 1803f3c90a9SAndy Fiddaman.Xr makecontext 3C . 181c10c16deSRichard LoweWhen that function returns, the process continues as if after a call to 1823f3c90a9SAndy Fiddaman.Fn setcontext 1833f3c90a9SAndy Fiddamanwith the 1843f3c90a9SAndy Fiddaman.Fa ucp 1853f3c90a9SAndy Fiddamanargument that was input to 1863f3c90a9SAndy Fiddaman.Xr makecontext 3C . 1873f3c90a9SAndy FiddamanIf the 1883f3c90a9SAndy Fiddaman.Fa ucp 1893f3c90a9SAndy Fiddamanargument was passed to a signal handler, program execution continues with the 1903f3c90a9SAndy Fiddamanprogram instruction following the instruction interrupted by the signal. 1913f3c90a9SAndy FiddamanIf the 1923f3c90a9SAndy Fiddaman.Fa uc_link 1933f3c90a9SAndy Fiddamanmember of the 1943f3c90a9SAndy Fiddaman.Vt ucontext_t 1953f3c90a9SAndy Fiddamanstructure pointed to by the 1963f3c90a9SAndy Fiddaman.Fa ucp 1973f3c90a9SAndy Fiddamanargument is 1983f3c90a9SAndy Fiddaman.Dv NULL , 1993f3c90a9SAndy Fiddamanthen this context is the main context, and the process 2003f3c90a9SAndy Fiddamanwill exit when this context returns. 2013f3c90a9SAndy FiddamanThe effects of passing a 2023f3c90a9SAndy Fiddaman.Fa ucp 2033f3c90a9SAndy Fiddamanargument obtained from any other source are unspecified. 2043f3c90a9SAndy Fiddaman.Sh RETURN VALUES 2053f3c90a9SAndy FiddamanOn successful completion, 2063f3c90a9SAndy Fiddaman.Fn setcontext 2073f3c90a9SAndy Fiddamandoes not return and 2083f3c90a9SAndy Fiddaman.Fn getcontext 209*ed093b41SRobert Mustacchiand 210*ed093b41SRobert Mustacchi.Fn getcontext_extd 2113f3c90a9SAndy Fiddamanreturns 0. 2123f3c90a9SAndy FiddamanOtherwise, -1 is returned. 2133f3c90a9SAndy Fiddaman.Sh ERRORS 214*ed093b41SRobert MustacchiNo errors are defined for 215*ed093b41SRobert Mustacchi.Fn getcontext 216*ed093b41SRobert Mustacchior 217*ed093b41SRobert Mustacchi.Fn setcontext . 218*ed093b41SRobert Mustacchi.Pp 219*ed093b41SRobert MustacchiThe 220*ed093b41SRobert Mustacchi.Fn getcontext_extd 221*ed093b41SRobert Mustacchifunction only sets 222*ed093b41SRobert Mustacchi.Va errno 223*ed093b41SRobert Mustacchiin some circumstances when it fails. 224*ed093b41SRobert MustacchiThe function may fail if: 225*ed093b41SRobert Mustacchi.Bl -tag -width Er 226*ed093b41SRobert Mustacchi.It Er EINVAL 227*ed093b41SRobert Mustacchi.Fa flags 228*ed093b41SRobert Mustacchihad invalid values. 229*ed093b41SRobert Mustacchi.El 2303f3c90a9SAndy Fiddaman.Sh USAGE 231c10c16deSRichard LoweWhen a signal handler is executed, the current user context is saved and a new 2323f3c90a9SAndy Fiddamancontext is created. 2333f3c90a9SAndy FiddamanIf the thread leaves the signal handler via 2343f3c90a9SAndy Fiddaman.Xr longjmp 3C , 2353f3c90a9SAndy Fiddamanthen it is unspecified whether the context at the time of the corresponding 2363f3c90a9SAndy Fiddaman.Xr setjmp 3C 2373f3c90a9SAndy Fiddamancall is restored and thus whether future calls to 2383f3c90a9SAndy Fiddaman.Fn getcontext 2393f3c90a9SAndy Fiddamanwill provide an accurate representation of the current context, since the 2403f3c90a9SAndy Fiddamancontext restored by 2413f3c90a9SAndy Fiddaman.Xr longjmp 3C 2423f3c90a9SAndy Fiddamanmay not contain all the information that 2433f3c90a9SAndy Fiddaman.Fn setcontext 2443f3c90a9SAndy Fiddamanrequires. 2453f3c90a9SAndy FiddamanSignal handlers should use 2463f3c90a9SAndy Fiddaman.Xr siglongjmp 3C 2473f3c90a9SAndy Fiddamaninstead. 2483f3c90a9SAndy Fiddaman.Pp 2493f3c90a9SAndy FiddamanPortable applications should not modify or access the 2503f3c90a9SAndy Fiddaman.Fa uc_mcontext 2513f3c90a9SAndy Fiddamanmember of 2523f3c90a9SAndy Fiddaman.Vt ucontext_t . 2533f3c90a9SAndy FiddamanA portable application cannot assume that context includes any process-wide 2543f3c90a9SAndy Fiddamanstatic data, possibly including 2553f3c90a9SAndy Fiddaman.Va errno . 2563f3c90a9SAndy FiddamanUsers manipulating contexts should take care to handle these explicitly when 257c10c16deSRichard Lowerequired. 2583f3c90a9SAndy Fiddaman.Sh INTERFACE STABILITY 2593f3c90a9SAndy Fiddaman.Sy Committed 2603f3c90a9SAndy Fiddaman.Sh SEE ALSO 2613f3c90a9SAndy Fiddaman.Xr sigaction 2 , 2623f3c90a9SAndy Fiddaman.Xr sigaltstack 2 , 2633f3c90a9SAndy Fiddaman.Xr sigprocmask 2 , 2643f3c90a9SAndy Fiddaman.Xr bsd_signal 3C , 2653f3c90a9SAndy Fiddaman.Xr makecontext 3C , 2663f3c90a9SAndy Fiddaman.Xr setjmp 3C , 2673f3c90a9SAndy Fiddaman.Xr sigsetjmp 3C , 268*ed093b41SRobert Mustacchi.Xr ucontext_alloc 3C , 2693f3c90a9SAndy Fiddaman.Xr ucontext.h 3HEAD , 2703f3c90a9SAndy Fiddaman.Xr attributes 7 , 2713f3c90a9SAndy Fiddaman.Xr standards 7 272