--- old/usr/src/man/man2/getcontext.2.man.txt
          +++ new/usr/src/man/man2/getcontext.2.man.txt

   1    1  GETCONTEXT(2)                    System Calls                    GETCONTEXT(2)
   2    2  
   3    3  NAME
   4    4       getcontext, getcontext_extd, setcontext - get and set current user
   5    5       context
   6    6  
   7    7  SYNOPSIS
   8    8       #include <ucontext.h>
   9    9  
  10   10       int
  11   11       getcontext(ucontext_t *ucp);
  12   12  
  13   13       int
  14   14       getcontext_extd(ucontext_t *ucp, uint32_t flags);
  15   15  
  16   16       int
  17   17       setcontext(const ucontext_t *ucp);
  18   18  
  19   19  DESCRIPTION
  20   20       The getcontext() function initializes the structure pointed to by ucp to
  21   21       the current user context of the calling process.  The ucontext_t type
  22   22       that ucp points to defines the user context and includes the contents of
  23   23       the calling process' machine registers, the signal mask, and the current
  24   24       execution stack.
  25   25  
  26   26       The ucontext_t structure is a part of the system ABI.  However, most
  27   27       architectures have added additional register states such as the extended
  28   28       vector and floating point registers that are not part of that.  To
  29   29       facilitate getting that state (such as the x86 xsave area) the
  30   30       getcontext_extd() function exists.  Once called, the context will be
  31   31       initialized and is suitable for use in other context operations just as
  32   32       though one had called getcontext().
  33   33  
  34   34       Unlike the getcontext() function, getcontext_extd() assumes that callers
  35   35       have previously initialized ucp and thus it treats additional members
  36   36       (such as the uc_xsave member on x86) as potentially valid.  To allow for
  37   37       all extended states to be copied out, ucp must be allocated with
  38   38       ucontext_alloc(3C).  Otherwise whether it is declared on the stack, as
  39   39       global data, allocated dynamically, or part of a structure, ucp must be
  40   40       zeroed through a call to bzero(3C) or memset(3C) prior to calling
  41   41       getcontext_extd().  Improper initialization can lead to memory safety
  42   42       bugs, making it critical that this is done.
  43   43  
  44   44       The flags member must be zero and is present to allow for what is copied
  45   45       out to change in the future.  This indicates that the system should
  46   46       attempt to copy out all extended states, though if the ucontext_t was not
  47   47       allocated with ucontext_alloc(3C), some extended states may not be.
  48   48  
  49   49       The setcontext() function restores the user context pointed to by ucp.  A
  50   50       successful call to setcontext() does not return; program execution
  51   51       resumes at the point specified by the ucp argument passed to
  52   52       setcontext().  The ucp argument should be created either by a prior call
  53   53       to getcontext(), or by being passed as an argument to a signal handler.
  54   54       If the ucp argument was created with getcontext(), program execution
  55   55       continues as if the corresponding call of getcontext() had just returned.
  56   56       If the ucp argument was created with makecontext(3C), program execution
  57   57       continues with the function passed to makecontext(3C).  When that
  58   58       function returns, the process continues as if after a call to
  59   59       setcontext() with the ucp argument that was input to makecontext(3C).  If
  60   60       the ucp argument was passed to a signal handler, program execution
  61   61       continues with the program instruction following the instruction
  62   62       interrupted by the signal.  If the uc_link member of the ucontext_t
  63   63       structure pointed to by the ucp argument is NULL, then this context is
  64   64       the main context, and the process will exit when this context returns.
  65   65       The effects of passing a ucp argument obtained from any other source are
  66   66       unspecified.
  67   67  
  68   68  RETURN VALUES
  69   69       On successful completion, setcontext() does not return and getcontext()
  70   70       and getcontext_extd() returns 0.  Otherwise, -1 is returned.
  71   71  
  72   72  ERRORS
  73   73       No errors are defined for getcontext() or setcontext().
  74   74  
  75   75       The getcontext_extd() function only sets errno in some circumstances when
  76   76       it fails.  The function may fail if:
  77   77  
  78   78       EINVAL             flags had invalid values.
  79   79  
  80   80  USAGE
  81   81       When a signal handler is executed, the current user context is saved and
  82   82       a new context is created.  If the thread leaves the signal handler via
  83   83       longjmp(3C), then it is unspecified whether the context at the time of
  84   84       the corresponding setjmp(3C) call is restored and thus whether future
  85   85       calls to getcontext() will provide an accurate representation of the
  86   86       current context, since the context restored by longjmp(3C) may not
  87   87       contain all the information that setcontext() requires.  Signal handlers
  88   88       should use siglongjmp(3C) instead.
  89   89  
  90   90       Portable applications should not modify or access the uc_mcontext member
  91   91       of ucontext_t.  A portable application cannot assume that context
  92   92       includes any process-wide static data, possibly including errno.  Users
  93   93       manipulating contexts should take care to handle these explicitly when
  94   94       required.
  95   95  
  96   96  INTERFACE STABILITY
  97   97       Committed
  98   98  
  99   99  SEE ALSO
 100  100       sigaction(2), sigaltstack(2), sigprocmask(2), bsd_signal(3C),
 101  101       makecontext(3C), setjmp(3C), sigsetjmp(3C), ucontext_alloc(3C),
 102  102       ucontext.h(3HEAD), attributes(7), standards(7)
 103  103  
 104  104  illumos                        January 24, 2022                        illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX