| UCONTEXT_ALLOC(3C) | Standard C Library Functions | UCONTEXT_ALLOC(3C) |
ucontext_alloc,
ucontext_free — allocate and
free ucontext structures
Standard C Library (libc, -lc)
#include
<ucontext.h>
ucontext_t *
ucontext_alloc(uint32_t
flags);
void
ucontext_free(ucontext_t
*ucp);
The
ucontext_alloc()
function allocates and initializes a ucontext_t
structure for subsequent use with getcontext_extd(2) or
swapcontext_extd(2).
Traditionally applications declare the
ucontext_t structure on the stack, as part of another
structure, or in other global data. Due to the advent of extended states
(such as the x86 xsave state) the traditional structure is not sufficient to
capture all state. The
ucontext_alloc()
function determines the correct size for the current process to cover all of
its extended states in addition to the standard
ucontext_t and then proceeds to set up the other
members of the ucontext_t to point at the additional
memory.
It is not recommended that the returned ucontext structure can be used with either getcontext(2) or swapcontext(2). While the resulting calls will work, they will not preserve that space for the extended state has been allocated. No memory will be leaked as a result of that.
The
ucontext_free()
function is used to release all the memory associated with
ucp. ucp must have come from a
prior call to ucontext_alloc(). If it is not, then
it is undefined as to what will happen to the program, but it will result in
eventual memory corruption. If ucp was declared on the
stack, as a structure member, as global data, or allocated in some way that
wasn't calling ucontext_alloc(), do not pass it to
ucontext_free().
Upon successful completion, the
ucontext_alloc() function returns a pointer to an
allocated ucontext_t. Otherwise
NULL is returned and errno is
set to indicate the error.
The ucontext_alloc() function will set
errno based on the failure of the underlying memory
allocator. For more information and details on these errors, see
malloc(3C), the list of errors below may not be
exhaustive.
The ucontext_alloc() function will fail
if:
EINVALENOMEMEAGAIN| January 24, 2023 | illumos |