--- old/usr/src/man/man3proc/Plwp_getxregs.3proc.man.txt
          +++ new/usr/src/man/man3proc/Plwp_getxregs.3proc.man.txt

   1    1  PLWP_GETXREGS(3PROC)   Process Control Library Functions  PLWP_GETXREGS(3PROC)
   2    2  
   3    3  NAME
   4    4       Plwp_getxregs, Plwp_freexregs, Plwp_setxregs, Lgetxregs, Lsetxregs - get
   5    5       and set extended register state
   6    6  
   7    7  LIBRARY
   8    8       Process Control Library (libproc, -lproc)
   9    9  
  10   10  SYNOPSIS
  11   11       #include <libproc.h>
  12   12  
  13   13       int
  14   14       Plwp_getxregs(struct ps_prochandle *P, lwpid_t lwpid,
  15   15           prxregset_t **xregsp, size_t *sizep);
  16   16  
  17   17       int
  18   18       Plwp_freexregs(struct ps_prochandle *P, lwpid_t lwpid,
  19   19           prxregset_t *xregs, size_t size);
  20   20  
  21   21       int
  22   22       Plwp_setxregs(struct ps_prochandle *P, lwpid_t lwpid,
  23   23           const prxregset_t *xregs);
  24   24  
  25   25       int
  26   26       Lgetxregs(struct ps_lwphandle *L, prxregset_t **xregsp, size_t *sizep);
  27   27  
  28   28       int
  29   29       Lsetxregs(struct ps_lwphandle *L, const prxregset_t *xregs);
  30   30  
  31   31  DESCRIPTION
  32   32       The Plwp_getxregs() and Plwp_setxregs() functions get and set the
  33   33       extended register state of the thread lwpid in the process handle P.
  34   34  
  35   35       The extended register state is defined by the architecture.  These
  36   36       registers may refer to optional registers that have become common on the
  37   37       platform, but are not part of the traditional ABI and thus not covered by
  38   38       functions such as Plwp_getregs(3PROC) and Plwp_getfpregs(3PROC).  Support
  39   39       for the extended registers varies based on the architecture and varies
  40   40       based on the specific system.  For example, on x86 based CPUs the xregs
  41   41       functionality requires the x86 xsave functionality to be supported.
  42   42  
  43   43       The Plwp_getxregs() function gets the extended register state
  44   44       information, allocates the appropriate sized buffer for it, and places a
  45   45       pointer to that buffer into xregs and updates sizep to indicate the size
  46   46       of the allocated structure.  Due to the fact that hardware has varying
  47   47       sized extended register sets, the exact size of the structure can vary
  48   48       between different running systems and core files.  It is also possible
  49   49       that some processor extensions are enabled at process runtime, leading
  50   50       for this to further be different between different processes on the same
  51   51       system.  As such, all of the different platform instantiations of the
  52   52       prxregset_t end up generally being opaque structures that can be cast to
  53   53       something more specific that also includes its size.
  54   54  
  55   55       The obtained prxregset_t in xregsp must be freed by the caller with the
  56   56       Plwp_freexregs() function.
  57   57  
  58   58       The Plwp_setxregs() function sets the extended register state information
  59   59       in xregs for the process handle P.
  60   60  
  61   61       Processes must be stopped prior to obtaining the register state of
  62   62       individual threads.  Processes may be stopped with Pstop(3PROC).
  63   63  
  64   64       The prxregset_t structure is described in proc(5).
  65   65  
  66   66       One may not set the register values of a process that is not an active
  67   67       process, e.g. a process handle that refers to a file or a core file.
  68   68  
  69   69       The Lgetxregs() and Lsetxregs() functions are equivalent to the
  70   70       Plwp_getxregs() and Plwp_setxregs() functions except that they operate on
  71   71       a specific thread identified by the handle L and only require that the
  72   72       thread in question be stopped.  Data allocated with the Lgetxregs()
  73   73       functions should be freed with the Plwp_freexregs() function.
  74   74  
  75   75  RETURN VALUES
  76   76       Upon successful completion, the Plwp_getxregs() and Plwp_setxregs()
  77   77       functions return 0 and get or set the register state.  Otherwise, -1 is
  78   78       returned and errno is set to indicate the error.
  79   79  
  80   80  ERRORS
  81   81       For a full list of possible errors see the DIAGNOSTICS section in
  82   82       proc(5).
  83   83  
  84   84       The Plwp_getxregs() and Plwp_setxregs() function will fail if:
  85   85  
  86   86       ENODATA            The process handle P does not have any extended
  87   87                          register state information.  This generally happens
  88   88                          because the platform does not support it.
  89   89  
  90   90       EBUSY              The process handle P refers to a live process and it
  91   91                          is not stopped.
  92   92  
  93   93       ENOENT             There is no thread with id lwpid in the process handle
  94   94                          P.
  95   95       The Lgetxregs() and Lsetxregs() function will fail if:
  96   96  
  97   97       ENODATA            The thread handle L does not have any extended
  98   98                          register state information.  This generally happens
  99   99                          because the platform does not support it.
 100  100  
 101  101       EBUSY              The thread handle L refers to a live process and the
 102  102                          thread is not stopped.
 103  103  
 104  104  INTERFACE STABILITY
 105  105       Uncommitted
 106  106  
 107  107  MT-LEVEL
 108  108       See LOCKING in libproc(3LIB).
 109  109  
 110  110  SEE ALSO
 111  111       libproc(3LIB), Plwp_getfpregs(3PROC), Plwp_getregs(3PROC),
 112  112       Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Pstop(3PROC), proc(5)
 113  113  
 114  114  illumos                        January 19, 2023                        illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX