1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.

  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PLWP_GETXREGS 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Plwp_getxregs ,
  19 .Nm Plwp_setxregs



  20 .Nd get and set extended register state
  21 .Sh LIBRARY
  22 .Lb libproc
  23 .Sh SYNOPSIS
  24 .In libproc.h
  25 .Ft int
  26 .Fo Plwp_getxregs
  27 .Fa "struct ps_prochandle *P"
  28 .Fa "lwpid_t lwpid"







  29 .Fa "prxregset_t *xregs"

  30 .Fc
  31 .Ft int
  32 .Fo Plwp_setxregs
  33 .Fa "struct ps_prochandle *P"
  34 .Fa "lwpid_t lwpid"
  35 .Fa "const prxregset_t *xregs"
  36 .Fc











  37 .Sh DESCRIPTION
  38 The
  39 .Fn Plwp_getxregs
  40 and
  41 .Fn Plwp_setxregs
  42 functions get and set the extended register state of the thread
  43 .Fa lwpid
  44 in the process handle
  45 .Fa P .
  46 .Pp
  47 The extended register state is defined by the architecture.
  48 These registers may refer to optional registers that have become common on the
  49 platform, but are not part of the standard ABI and thus not covered by
  50 functions such as
  51 .Xr Plwp_getregs 3PROC
  52 and
  53 .Xr Plwp_getfpregs 3PROC .




  54 .Pp
  55 The
  56 .Fn Plwp_getxregs
  57 function gets the extended register state information and places it into
  58 .Fa xregs .
  59 Where as the
























  60 .Fn Plwp_setxregs
  61 function sets the extended register state information in
  62 .Fa xregs
  63 for the process handle
  64 .Fa P .
  65 .Pp
  66 Processes must be stopped prior to obtaining the register state of
  67 individual threads.
  68 Processes may be stopped with
  69 .Xr Pstop 3PROC .
  70 .Pp
  71 The
  72 .Sy prxregset_t
  73 structure is described in
  74 .Xr proc 5 .
  75 .Pp
  76 One may not set the register values of a process that is not an active
  77 process, e.g. a process handle that refers to a file or a core file.


















  78 .Sh RETURN VALUES
  79 Upon successful completion, the
  80 .Fn Plwp_getxregs
  81 and
  82 .Fn Plwp_setxregs
  83 functions return
  84 .Sy 0
  85 and get or set the register state.
  86 Otherwise,
  87 .Sy -1
  88 is returned and
  89 .Sy errno
  90 is set to indicate the error.
  91 .Sh ERRORS
  92 For a full list of possible errors see the
  93 .Sy DIAGNOSTICS
  94 section in
  95 .Xr proc 5 .
  96 .Pp
  97 The
  98 .Fn Plwp_getxregs
  99 and
 100 .Fn Plwp_setxregs
 101 function will fail if:
 102 .Bl -tag -width Er
 103 .It Er ENODATA
 104 The process handle
 105 .Fa P
 106 does not have any extended register state information.

 107 .It Er EBUSY
 108 The process handle
 109 .Fa P
 110 refers to a live process and it is not stopped.
 111 .It Er ENOENT
 112 The process handle
 113 .Fa P
 114 refers to a live process and there is no thread with id
 115 .Fa lwpid .
 116 .It Er EINVAL
 117 The process handle
 118 .Fa P
 119 refers to a core file and there is no thread with id
 120 .Fa lwpid .
 121 .El
 122 .Sh ARCHITECTURE
 123 The
 124 .Fn Plwp_getxregs
 125 and
 126 .Fn Plwp_setxregs
 127 functions are only available on
 128 .Sy SPARC
 129 platforms.









 130 .Sh INTERFACE STABILITY
 131 .Sy Uncommitted
 132 .Sh MT-LEVEL
 133 See
 134 .Sy LOCKING
 135 in
 136 .Xr libproc 3LIB .
 137 .Sh SEE ALSO
 138 .Xr libproc 3LIB ,
 139 .Xr Plwp_getfpregs 3PROC ,
 140 .Xr Plwp_getregs 3PROC ,
 141 .Xr Plwp_setfpregs 3PROC ,
 142 .Xr Plwp_setregs 3PROC ,
 143 .Xr Pstop 3PROC ,
 144 .Xr proc 5

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\" Copyright 2023 Oxide Computer Company
  14 .\"
  15 .Dd January 19, 2023
  16 .Dt PLWP_GETXREGS 3PROC
  17 .Os
  18 .Sh NAME
  19 .Nm Plwp_getxregs ,
  20 .Nm Plwp_freexregs ,
  21 .Nm Plwp_setxregs ,
  22 .Nm Lgetxregs ,
  23 .Nm Lsetxregs
  24 .Nd get and set extended register state
  25 .Sh LIBRARY
  26 .Lb libproc
  27 .Sh SYNOPSIS
  28 .In libproc.h
  29 .Ft int
  30 .Fo Plwp_getxregs
  31 .Fa "struct ps_prochandle *P"
  32 .Fa "lwpid_t lwpid"
  33 .Fa "prxregset_t **xregsp"
  34 .Fa "size_t *sizep"
  35 .Fc
  36 .Ft int
  37 .Fo Plwp_freexregs
  38 .Fa "struct ps_prochandle *P"
  39 .Fa "lwpid_t lwpid"
  40 .Fa "prxregset_t *xregs"
  41 .Fa "size_t size"
  42 .Fc
  43 .Ft int
  44 .Fo Plwp_setxregs
  45 .Fa "struct ps_prochandle *P"
  46 .Fa "lwpid_t lwpid"
  47 .Fa "const prxregset_t *xregs"
  48 .Fc
  49 .Ft int
  50 .Fo Lgetxregs
  51 .Fa "struct ps_lwphandle *L"
  52 .Fa "prxregset_t **xregsp"
  53 .Fa "size_t *sizep"
  54 .Fc
  55 .Ft int
  56 .Fo Lsetxregs
  57 .Fa "struct ps_lwphandle *L"
  58 .Fa "const prxregset_t *xregs"
  59 .Fc
  60 .Sh DESCRIPTION
  61 The
  62 .Fn Plwp_getxregs
  63 and
  64 .Fn Plwp_setxregs
  65 functions get and set the extended register state of the thread
  66 .Fa lwpid
  67 in the process handle
  68 .Fa P .
  69 .Pp
  70 The extended register state is defined by the architecture.
  71 These registers may refer to optional registers that have become common on the
  72 platform, but are not part of the traditional ABI and thus not covered by
  73 functions such as
  74 .Xr Plwp_getregs 3PROC
  75 and
  76 .Xr Plwp_getfpregs 3PROC .
  77 Support for the extended registers varies based on the architecture and
  78 varies based on the specific system.
  79 For example, on x86 based CPUs the xregs functionality requires the x86
  80 xsave functionality to be supported.
  81 .Pp
  82 The
  83 .Fn Plwp_getxregs
  84 function gets the extended register state information, allocates the
  85 appropriate sized buffer for it, and places a pointer to that buffer
  86 into
  87 .Fa xregs
  88 and updates
  89 .Fa sizep
  90 to indicate the size of the allocated structure.
  91 Due to the fact that hardware has varying sized extended register sets,
  92 the exact size of the structure can vary between different running
  93 systems and core files.
  94 It is also possible that some processor extensions are enabled at
  95 process runtime, leading for this to further be different between
  96 different processes on the same system.
  97 As such, all of the different platform instantiations of the
  98 .Vt prxregset_t
  99 end up generally being opaque structures that can be cast to something
 100 more specific that also includes its size.
 101 .Pp
 102 The obtained
 103 .Vt prxregset_t
 104 in
 105 .Fa xregsp
 106 must be freed by the caller with the
 107 .Fn Plwp_freexregs
 108 function.
 109 .Pp
 110 The
 111 .Fn Plwp_setxregs
 112 function sets the extended register state information in
 113 .Fa xregs
 114 for the process handle
 115 .Fa P .
 116 .Pp
 117 Processes must be stopped prior to obtaining the register state of
 118 individual threads.
 119 Processes may be stopped with
 120 .Xr Pstop 3PROC .
 121 .Pp
 122 The
 123 .Sy prxregset_t
 124 structure is described in
 125 .Xr proc 5 .
 126 .Pp
 127 One may not set the register values of a process that is not an active
 128 process, e.g. a process handle that refers to a file or a core file.
 129 .Pp
 130 The
 131 .Fn Lgetxregs
 132 and
 133 .Fn Lsetxregs
 134 functions are equivalent to the
 135 .Fn Plwp_getxregs
 136 and
 137 .Fn Plwp_setxregs
 138 functions except that they operate on a specific thread identified by
 139 the handle
 140 .Fa L
 141 and only require that the thread in question be stopped.
 142 Data allocated with the
 143 .Fn Lgetxregs
 144 functions should be freed with the
 145 .Fn Plwp_freexregs
 146 function.
 147 .Sh RETURN VALUES
 148 Upon successful completion, the
 149 .Fn Plwp_getxregs
 150 and
 151 .Fn Plwp_setxregs
 152 functions return
 153 .Sy 0
 154 and get or set the register state.
 155 Otherwise,
 156 .Sy -1
 157 is returned and
 158 .Sy errno
 159 is set to indicate the error.
 160 .Sh ERRORS
 161 For a full list of possible errors see the
 162 .Sy DIAGNOSTICS
 163 section in
 164 .Xr proc 5 .
 165 .Pp
 166 The
 167 .Fn Plwp_getxregs
 168 and
 169 .Fn Plwp_setxregs
 170 function will fail if:
 171 .Bl -tag -width Er
 172 .It Er ENODATA
 173 The process handle
 174 .Fa P
 175 does not have any extended register state information.
 176 This generally happens because the platform does not support it.
 177 .It Er EBUSY
 178 The process handle
 179 .Fa P
 180 refers to a live process and it is not stopped.
 181 .It Er ENOENT
 182 There is no thread with id
 183 .Fa lwpid
 184 in the process handle
 185 .Fa P .





 186 .El

 187 The
 188 .Fn Lgetxregs
 189 and
 190 .Fn Lsetxregs
 191 function will fail if:
 192 .Bl -tag -width Er
 193 .It Er ENODATA
 194 The thread handle
 195 .Fa L
 196 does not have any extended register state information.
 197 This generally happens because the platform does not support it.
 198 .It Er EBUSY
 199 The thread handle
 200 .Fa L
 201 refers to a live process and the thread is not stopped.
 202 .El
 203 .Sh INTERFACE STABILITY
 204 .Sy Uncommitted
 205 .Sh MT-LEVEL
 206 See
 207 .Sy LOCKING
 208 in
 209 .Xr libproc 3LIB .
 210 .Sh SEE ALSO
 211 .Xr libproc 3LIB ,
 212 .Xr Plwp_getfpregs 3PROC ,
 213 .Xr Plwp_getregs 3PROC ,
 214 .Xr Plwp_setfpregs 3PROC ,
 215 .Xr Plwp_setregs 3PROC ,
 216 .Xr Pstop 3PROC ,
 217 .Xr proc 5