1.\" Copyright (c) 2002 Packet Design, LLC. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, 5.\" use and redistribution of this software, in source or object code 6.\" forms, with or without modifications are expressly permitted by 7.\" Packet Design; provided, however, that: 8.\" 9.\" (i) Any and all reproductions of the source or object code 10.\" must include the copyright notice above and the following 11.\" disclaimer of warranties; and 12.\" (ii) No rights are granted, in any manner or form, to use 13.\" Packet Design trademarks, including the mark "PACKET DESIGN" 14.\" on advertising, endorsements, or otherwise except as such 15.\" appears in the above copyright notice or in the software. 16.\" 17.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND 18.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO 19.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING 20.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED 21.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 22.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, 23.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS 24.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, 25.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE 26.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE 27.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, 28.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL 29.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF 30.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF 31.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 33.\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF 34.\" THE POSSIBILITY OF SUCH DAMAGE. 35.\" 36.Dd March 23, 2020 37.Dt GETCONTEXT 3 38.Os 39.Sh NAME 40.Nm getcontext , getcontextx , setcontext 41.Nd get and set user thread context 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In ucontext.h 46.Ft int 47.Fn getcontext "ucontext_t *ucp" 48.Ft ucontext_t * 49.Fn getcontextx "void" 50.Ft int 51.Fn setcontext "const ucontext_t *ucp" 52.Sh DESCRIPTION 53The 54.Fn getcontext 55function 56saves the current thread's execution context in the structure pointed to by 57.Fa ucp . 58This saved context may then later be restored by calling 59.Fn setcontext . 60.Pp 61The 62.Fn getcontextx 63function saves the current execution context in the newly allocated structure 64.Vt ucontext_t , 65which is returned on success. 66If architecture defines additional CPU states that can be stored in extended 67blocks referenced from the 68.Vt ucontext_t , 69the memory for them may be allocated and their context also stored. 70Memory returned by 71.Fn getcontextx 72function shall be freed using 73.Fn free 3 . 74.Pp 75The 76.Fn setcontext 77function 78makes a previously saved thread context the current thread context, i.e., 79the current context is lost and 80.Fn setcontext 81does not return. 82Instead, execution continues in the context specified by 83.Fa ucp , 84which must have been previously initialized by a call to 85.Fn getcontext , 86.Xr makecontext 3 , 87or by being passed as an argument to a signal handler (see 88.Xr sigaction 2 ) . 89.Pp 90If 91.Fa ucp 92was initialized by 93.Fn getcontext , 94then execution continues as if the original 95.Fn getcontext 96call had just returned (again). 97.Pp 98If 99.Fa ucp 100was initialized by 101.Xr makecontext 3 , 102execution continues with the invocation of the function specified to 103.Xr makecontext 3 . 104When that function returns, 105.Fa "ucp->uc_link" 106determines what happens next: 107if 108.Fa "ucp->uc_link" 109is 110.Dv NULL , 111the process exits; 112otherwise, 113.Fn setcontext "ucp->uc_link" 114is implicitly invoked. 115.Pp 116If 117.Fa ucp 118was initialized by the invocation of a signal handler, execution continues 119at the point the thread was interrupted by the signal. 120.Sh RETURN VALUES 121If successful, 122.Fn getcontext 123returns zero and 124.Fn setcontext 125does not return; otherwise \-1 is returned. 126The 127.Fn getcontextx 128returns pointer to the allocated and initialized context on success, and 129.Va NULL 130on failure. 131.Sh ERRORS 132No errors are defined for 133.Fn getcontext 134or 135.Fn setcontext . 136The 137.Fn getcontextx 138may return the following errors in 139.Va errno : 140.Bl -tag -width Er 141.It Bq Er ENOMEM 142No memory was available to allocate for the context or some extended state. 143.El 144.Sh SEE ALSO 145.Xr sigaction 2 , 146.Xr sigaltstack 2 , 147.Xr makecontext 3 , 148.Xr ucontext 3 149.Sh STANDARDS 150The 151.Fn getcontext 152and 153.Fn setcontext 154functions conform to 155.St -xsh5 156and 157.St -p1003.1-2001 . 158The 159.Va errno 160indications are an extension to the standard. 161.Pp 162The 163.St -p1003.1-2004 164revision marked the functions 165.Fn getcontext 166and 167.Fn setcontext 168as obsolete, citing portability issues and recommending the use of 169.Tn POSIX 170threads instead. 171The 172.St -p1003.1-2008 173revision removed the functions from the specification. 174.Sh HISTORY 175The 176.Fn getcontext 177and 178.Fn setcontext 179functions first appeared in 180.At V.4 . 181