UCONTEXT_ALLOC(3C) Standard C Library Functions UCONTEXT_ALLOC(3C)

NAME

ucontext_alloc, ucontext_free - allocate and free ucontext structures

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <ucontext.h>

ucontext_t *
ucontext_alloc(uint32_t flags);

void
ucontext_free(ucontext_t *ucp);

DESCRIPTION

The ucontext_alloc() function allocates and initializes a ucontext_t
structure for subsequent use with functions such as getcontext_extd(2)
or swapcontext_extd(3C).

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 be used with
either getcontext(2) or swapcontext(3C). 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().

RETURN VALUES

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.

ERRORS

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:

EINVAL The flags argument had unknown or unsupported
values.

ENOMEM There was insufficient memory to allocate an
extended ucontext structure. See malloc(3C) for
more information.

EAGAIN There was insufficient memory to allocate an
extended ucontext structure, but the application
could try again later. See malloc(3C) for more
information.

INTERFACE STABILITY

Committed

MT-LEVEL
Safe

SEE ALSO

illumos January 24, 2023 illumos