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