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

   1    1  UCONTEXT_ALLOC(3C)       Standard C Library Functions       UCONTEXT_ALLOC(3C)
   2    2  
   3    3  NAME
   4    4       ucontext_alloc, ucontext_free - allocate and free ucontext structures
   5    5  
   6    6  LIBRARY
   7    7       Standard C Library (libc, -lc)
   8    8  
   9    9  SYNOPSIS
  10   10       #include <ucontext.h>
  11   11  
  12   12       ucontext_t *
  13   13       ucontext_alloc(uint32_t flags);
  14   14  
  15   15       void
  16   16       ucontext_free(ucontext_t *ucp);
  17   17  
  18   18  DESCRIPTION
  19   19       The ucontext_alloc() function allocates and initializes a ucontext_t
  20   20       structure for subsequent use with getcontext_extd(2) or
  21   21       swapcontext_extd(2).
  22   22  
  23   23       Traditionally applications declare the ucontext_t structure on the stack,
  24   24       as part of another structure, or in other global data.  Due to the advent
  25   25       of extended states (such as the x86 xsave state) the traditional
  26   26       structure is not sufficient to capture all state.  The ucontext_alloc()
  27   27       function determines the correct size for the current process to cover all
  28   28       of its extended states in addition to the standard ucontext_t and then
  29   29       proceeds to set up the other members of the ucontext_t to point at the
  30   30       additional memory.
  31   31  
  32   32       It is not recommended that the returned ucontext structure can be used
  33   33       with either getcontext(2) or swapcontext(2).  While the resulting calls
  34   34       will work, they will not preserve that space for the extended state has
  35   35       been allocated.  No memory will be leaked as a result of that.
  36   36  
  37   37       The ucontext_free() function is used to release all the memory associated
  38   38       with ucp.  ucp must have come from a prior call to ucontext_alloc().  If
  39   39       it is not, then it is undefined as to what will happen to the program,
  40   40       but it will result in eventual memory corruption.  If ucp was declared on
  41   41       the stack, as a structure member, as global data, or allocated in some
  42   42       way that wasn't calling ucontext_alloc(), do not pass it to
  43   43       ucontext_free().
  44   44  
  45   45  RETURN VALUES
  46   46       Upon successful completion, the ucontext_alloc() function returns a
  47   47       pointer to an allocated ucontext_t.  Otherwise NULL is returned and errno
  48   48       is set to indicate the error.
  49   49  
  50   50  ERRORS
  51   51       The ucontext_alloc() function will set errno based on the failure of the
  52   52       underlying memory allocator.  For more information and details on these
  53   53       errors, see malloc(3C), the list of errors below may not be exhaustive.
  54   54  
  55   55       The ucontext_alloc() function will fail if:
  56   56  
  57   57       EINVAL             The flags argument had unknown or unsupported values.
  58   58  
  59   59       ENOMEM             There was insufficient memory to allocate an extended
  60   60                          ucontext structure.  See malloc(3C) for more
  61   61                          information.
  62   62  
  63   63       EAGAIN             There was insufficient memory to allocate an extended
  64   64                          ucontext structure, but the application could try
  65   65                          again later.  See malloc(3C) for more information.
  66   66  
  67   67  INTERFACE STABILITY
  68   68       Committed
  69   69  
  70   70  MT-LEVEL
  71   71       Safe
  72   72  
  73   73  SEE ALSO
  74   74  
  75   75  illumos                        January 24, 2023                        illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX