1*ed093b41SRobert Mustacchi.\" 2*ed093b41SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*ed093b41SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*ed093b41SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*ed093b41SRobert Mustacchi.\" 1.0 of the CDDL. 6*ed093b41SRobert Mustacchi.\" 7*ed093b41SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*ed093b41SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*ed093b41SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*ed093b41SRobert Mustacchi.\" 11*ed093b41SRobert Mustacchi.\" 12*ed093b41SRobert Mustacchi.\" Copyright 2023 Oxide Computer Company 13*ed093b41SRobert Mustacchi.\" 14*ed093b41SRobert Mustacchi.Dd January 24, 2023 15*ed093b41SRobert Mustacchi.Dt UCONTEXT_ALLOC 3C 16*ed093b41SRobert Mustacchi.Os 17*ed093b41SRobert Mustacchi.Sh NAME 18*ed093b41SRobert Mustacchi.Nm ucontext_alloc , 19*ed093b41SRobert Mustacchi.Nm ucontext_free 20*ed093b41SRobert Mustacchi.Nd allocate and free ucontext structures 21*ed093b41SRobert Mustacchi.Sh LIBRARY 22*ed093b41SRobert Mustacchi.Lb libc 23*ed093b41SRobert Mustacchi.Sh SYNOPSIS 24*ed093b41SRobert Mustacchi.In ucontext.h 25*ed093b41SRobert Mustacchi.Ft "ucontext_t *" 26*ed093b41SRobert Mustacchi.Fo ucontext_alloc 27*ed093b41SRobert Mustacchi.Fa "uint32_t flags" 28*ed093b41SRobert Mustacchi.Fc 29*ed093b41SRobert Mustacchi.Ft void 30*ed093b41SRobert Mustacchi.Fo ucontext_free 31*ed093b41SRobert Mustacchi.Fa "ucontext_t *ucp" 32*ed093b41SRobert Mustacchi.Fc 33*ed093b41SRobert Mustacchi.Sh DESCRIPTION 34*ed093b41SRobert MustacchiThe 35*ed093b41SRobert Mustacchi.Fn ucontext_alloc 36*ed093b41SRobert Mustacchifunction allocates and initializes a 37*ed093b41SRobert Mustacchi.Vt ucontext_t 38*ed093b41SRobert Mustacchistructure for subsequent use with functions such as 39*ed093b41SRobert Mustacchi.Xr getcontext_extd 2 40*ed093b41SRobert Mustacchior 41*ed093b41SRobert Mustacchi.Xr swapcontext_extd 2 . 42*ed093b41SRobert Mustacchi.Pp 43*ed093b41SRobert MustacchiTraditionally applications declare the 44*ed093b41SRobert Mustacchi.Vt ucontext_t 45*ed093b41SRobert Mustacchistructure on the stack, as part of another structure, or in other global data. 46*ed093b41SRobert MustacchiDue to the advent of extended states 47*ed093b41SRobert Mustacchi.Pq such as the x86 xsave state 48*ed093b41SRobert Mustacchithe traditional structure is not sufficient to capture all state. 49*ed093b41SRobert MustacchiThe 50*ed093b41SRobert Mustacchi.Fn ucontext_alloc 51*ed093b41SRobert Mustacchifunction determines the correct size for the current process to cover all of its 52*ed093b41SRobert Mustacchiextended states in addition to the standard 53*ed093b41SRobert Mustacchi.Vt ucontext_t 54*ed093b41SRobert Mustacchiand then proceeds to set up the other members of the 55*ed093b41SRobert Mustacchi.Vt ucontext_t 56*ed093b41SRobert Mustacchito point at the additional memory. 57*ed093b41SRobert Mustacchi.Pp 58*ed093b41SRobert MustacchiIt is not recommended that the returned 59*ed093b41SRobert Mustacchi.Vt ucontext 60*ed093b41SRobert Mustacchistructure be used with either 61*ed093b41SRobert Mustacchi.Xr getcontext 2 62*ed093b41SRobert Mustacchior 63*ed093b41SRobert Mustacchi.Xr swapcontext 2 . 64*ed093b41SRobert MustacchiWhile the resulting calls will work, they will not preserve that space for the 65*ed093b41SRobert Mustacchiextended state has been allocated. 66*ed093b41SRobert MustacchiNo memory will be leaked as a result of that. 67*ed093b41SRobert Mustacchi.Pp 68*ed093b41SRobert MustacchiThe 69*ed093b41SRobert Mustacchi.Fn ucontext_free 70*ed093b41SRobert Mustacchifunction is used to release all the memory associated with 71*ed093b41SRobert Mustacchi.Fa ucp . 72*ed093b41SRobert Mustacchi.Fa ucp 73*ed093b41SRobert Mustacchimust have come from a prior call to 74*ed093b41SRobert Mustacchi.Fn ucontext_alloc . 75*ed093b41SRobert MustacchiIf it is not, then it is undefined as to what will happen to the program, but it 76*ed093b41SRobert Mustacchiwill result in eventual memory corruption. 77*ed093b41SRobert MustacchiIf 78*ed093b41SRobert Mustacchi.Fa ucp 79*ed093b41SRobert Mustacchiwas declared on the stack, as a structure member, as global data, or allocated 80*ed093b41SRobert Mustacchiin some way that wasn't calling 81*ed093b41SRobert Mustacchi.Fn ucontext_alloc , 82*ed093b41SRobert Mustacchido not pass it to 83*ed093b41SRobert Mustacchi.Fn ucontext_free . 84*ed093b41SRobert Mustacchi.Sh RETURN VALUES 85*ed093b41SRobert MustacchiUpon successful completion, the 86*ed093b41SRobert Mustacchi.Fn ucontext_alloc 87*ed093b41SRobert Mustacchifunction returns a pointer to an allocated 88*ed093b41SRobert Mustacchi.Vt ucontext_t . 89*ed093b41SRobert MustacchiOtherwise 90*ed093b41SRobert Mustacchi.Dv NULL 91*ed093b41SRobert Mustacchiis returned and 92*ed093b41SRobert Mustacchi.Va errno 93*ed093b41SRobert Mustacchiis set to indicate the error. 94*ed093b41SRobert Mustacchi.Sh ERRORS 95*ed093b41SRobert MustacchiThe 96*ed093b41SRobert Mustacchi.Fn ucontext_alloc 97*ed093b41SRobert Mustacchifunction will set 98*ed093b41SRobert Mustacchi.Va errno 99*ed093b41SRobert Mustacchibased on the failure of the underlying memory allocator. 100*ed093b41SRobert MustacchiFor more information and details on these errors, see 101*ed093b41SRobert Mustacchi.Xr malloc 3C , 102*ed093b41SRobert Mustacchithe list of errors below may not be exhaustive. 103*ed093b41SRobert Mustacchi.Pp 104*ed093b41SRobert MustacchiThe 105*ed093b41SRobert Mustacchi.Fn ucontext_alloc 106*ed093b41SRobert Mustacchifunction will fail if: 107*ed093b41SRobert Mustacchi.Bl -tag -width Er 108*ed093b41SRobert Mustacchi.It Er EINVAL 109*ed093b41SRobert MustacchiThe 110*ed093b41SRobert Mustacchi.Fa flags 111*ed093b41SRobert Mustacchiargument had unknown or unsupported values. 112*ed093b41SRobert Mustacchi.It Er ENOMEM 113*ed093b41SRobert MustacchiThere was insufficient memory to allocate an extended ucontext 114*ed093b41SRobert Mustacchistructure. 115*ed093b41SRobert MustacchiSee 116*ed093b41SRobert Mustacchi.Xr malloc 3C 117*ed093b41SRobert Mustacchifor more information. 118*ed093b41SRobert Mustacchi.It Er EAGAIN 119*ed093b41SRobert MustacchiThere was insufficient memory to allocate an extended ucontext 120*ed093b41SRobert Mustacchistructure, but the application could try again later. 121*ed093b41SRobert MustacchiSee 122*ed093b41SRobert Mustacchi.Xr malloc 3C 123*ed093b41SRobert Mustacchifor more information. 124*ed093b41SRobert Mustacchi.El 125*ed093b41SRobert Mustacchi.Sh INTERFACE STABILITY 126*ed093b41SRobert Mustacchi.Sy Committed 127*ed093b41SRobert Mustacchi.Sh MT-LEVEL 128*ed093b41SRobert Mustacchi.Sy Safe 129*ed093b41SRobert Mustacchi.Sh SEE ALSO 130