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
  34 The
  35 .Fn ucontext_alloc
  36 function allocates and initializes a
  37 .Vt ucontext_t
  38 structure for subsequent use with
  39 .Xr getcontext_extd 2
  40 or
  41 .Xr swapcontext_extd 2 .
  42 .Pp
  43 Traditionally applications declare the
  44 .Vt ucontext_t
  45 structure on the stack, as part of another structure, or in other global data.
  46 Due to the advent of extended states
  47 .Pq such as the x86 xsave state
  48 the traditional structure is not sufficient to capture all state.
  49 The
  50 .Fn ucontext_alloc
  51 function determines the correct size for the current process to cover all of its
  52 extended states in addition to the standard
  53 .Vt ucontext_t
  54 and then proceeds to set up the other members of the
  55 .Vt ucontext_t
  56 to point at the additional memory.
  57 .Pp
  58 It is not recommended that the returned
  59 .Vt ucontext
  60 structure can be used with either
  61 .Xr getcontext 2
  62 or
  63 .Xr swapcontext 2 .
  64 While the resulting calls will work, they will not preserve that space for the
  65 extended state has been allocated.
  66 No memory will be leaked as a result of that.
  67 .Pp
  68 The
  69 .Fn ucontext_free
  70 function is used to release all the memory associated with
  71 .Fa ucp .
  72 .Fa ucp
  73 must have come from a prior call to
  74 .Fn ucontext_alloc .
  75 If it is not, then it is undefined as to what will happen to the program, but it
  76 will result in eventual memory corruption.
  77 If
  78 .Fa ucp
  79 was declared on the stack, as a structure member, as global data, or allocated
  80 in some way that wasn't calling
  81 .Fn ucontext_alloc ,
  82 do not pass it to
  83 .Fn ucontext_free .
  84 .Sh RETURN VALUES
  85 Upon successful completion, the
  86 .Fn ucontext_alloc
  87 function returns a pointer to an allocated
  88 .Vt ucontext_t .
  89 Otherwise
  90 .Dv NULL
  91 is returned and
  92 .Va errno
  93 is set to indicate the error.
  94 .Sh ERRORS
  95 The
  96 .Fn ucontext_alloc
  97 function will set
  98 .Va errno
  99 based on the failure of the underlying memory allocator.
 100 For more information and details on these errors, see
 101 .Xr malloc 3C ,
 102 the list of errors below may not be exhaustive.
 103 .Pp
 104 The
 105 .Fn ucontext_alloc
 106 function will fail if:
 107 .Bl -tag -width Er
 108 .It Er EINVAL
 109 The
 110 .Fa flags
 111 argument had unknown or unsupported values.
 112 .It Er ENOMEM
 113 There was insufficient memory to allocate an extended ucontext
 114 structure.
 115 See
 116 .Xr malloc 3C
 117 for more information.
 118 .It Er EAGAIN
 119 There was insufficient memory to allocate an extended ucontext
 120 structure, but the application could try again later.
 121 See
 122 .Xr malloc 3C
 123 for more information.
 124 .El
 125 .Sh INTERFACE STABILITY
 126 .Sy Committed
 127 .Sh MT-LEVEL
 128 .Sy Safe
 129 .Sh SEE ALSO