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