xref: /illumos-gate/usr/src/man/man2/getcontext.2 (revision ed093b41a93e8563e6e1e5dae0768dda2a7bcc27)
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