--- old/usr/src/man/man3c/ucontext_alloc.3c
          +++ new/usr/src/man/man3c/ucontext_alloc.3c

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

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX