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 02, 2020
  15 .Dt PLWP_GETREGS 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Plwp_getfpregs ,
  19 .Nm Plwp_setfpregs ,
  20 .Nm Plwp_getregs ,
  21 .Nm Plwp_setregs




  22 .Nd get and set thread registers
  23 .Sh LIBRARY
  24 .Lb libproc
  25 .Sh SYNOPSIS
  26 .In libproc.h
  27 .Ft int
  28 .Fo Plwp_getfpregs
  29 .Fa "struct ps_prochandle *P"
  30 .Fa "lwpid_t lwpid"
  31 .Fa "prfpregset_t *fpregs"
  32 .Fc
  33 .Ft int
  34 .Fo Plwp_setfpregs
  35 .Fa "struct ps_prochandle *P"
  36 .Fa "lwpid_t lwpid"
  37 .Fa "const prfpregset_t fpregs"
  38 .Fc
  39 .Ft int
  40 .Fo Plwp_getregs
  41 .Fa "struct ps_prochandle *P"
  42 .Fa "lwpid_t lwpid"
  43 .Fa "prgregset_t gregs"
  44 .Fc
  45 .Ft int
  46 .Fo Plwp_setregs
  47 .Fa "struct ps_prochandle *P"
  48 .Fa "lwpid_t lwpid"
  49 .Fa "const prgregset_t gregs"
  50 .Fc




















  51 .Sh DESCRIPTION
  52 The
  53 .Fn Plwp_getregs ,
  54 .Fn Plwp_setregs ,
  55 .Fn Plwp_getfpregs ,
  56 and
  57 .Fn Plwp_setfpregs
  58 functions allow one to get and set the general purpose and floating
  59 point registers from the thread
  60 .Fa lwpid
  61 in the process handle
  62 .Fa P .
  63 .Pp
  64 The
  65 .Fn Plwp_getfpregs
  66 function updates the structure pointed to by
  67 .Fa fpregs
  68 with the state and values of the floating point registers of the thread
  69 specified by
  70 .Fa lwpid .

  88 .Fn Plwp_setregs
  89 function updates the general purpose registers of the thread specified
  90 by
  91 .Fa lwpid
  92 to the register state contained in
  93 .Fa gregs .
  94 .Pp
  95 Processes must be stopped before obtaining the register state of
  96 individual threads.
  97 Processes may be stopped with
  98 .Xr Pstop 3PROC .
  99 The structures used for registers are described in
 100 .Xr proc 5
 101 and their definitions may be found in
 102 .In procfs.h .
 103 The definitions of these structures varies based on the architecture of
 104 the system and the running process.
 105 .Pp
 106 One may not set the register values of a process that is not an active
 107 process, e.g. a process handle that refers to a file or a core file.






























 108 .Sh RETURN VALUES
 109 Upon successful completion, the
 110 .Fn Plwp_getregs ,
 111 .Fn Plwp_setregs ,
 112 .Fn Plwp_getfpregs ,




 113 and
 114 .Fn Plwp_setfpregs
 115 functions return
 116 .Sy 0
 117 and obtain or set the register state.
 118 Otherwise,
 119 .Sy -1
 120 is returned,
 121 .Sy errno
 122 is set to indicate the error, and the register state is not updated nor
 123 are the data pointers changed.
 124 .Sh ERRORS


 125 For a full list of possible errors also see the
 126 .Sy DIAGNOSTICS
 127 section in
 128 .Xr proc 5 .
 129 .Pp
 130 The
 131 .Fn Plwp_getregs ,
 132 .Fn Plwp_setregs ,
 133 .Fn Plwp_getfpregs ,
 134 and
 135 .Fn Plwp_setfpregs
 136 will fail if:
 137 .Bl -tag -width Er
 138 .It Er EBUSY
 139 The process handle
 140 .Fa P
 141 is not currently stopped.
 142 .It Er ENOENT
 143 There is no thread in
 144 .Fa P
 145 with id
 146 .Fa lwpid .
 147 .El













 148 .Sh INTERFACE STABILITY
 149 .Sy Uncommitted
 150 .Sh MT-LEVEL
 151 See
 152 .Sy LOCKING
 153 in
 154 .Xr libproc 3LIB .
 155 .Sh SEE ALSO
 156 .Xr libproc 3LIB ,
 157 .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_GETREGS 3PROC
  17 .Os
  18 .Sh NAME
  19 .Nm Plwp_getfpregs ,
  20 .Nm Plwp_setfpregs ,
  21 .Nm Plwp_getregs ,
  22 .Nm Plwp_setregs ,
  23 .Nm Lgetfpregs ,
  24 .Nm Lsetfpregs ,
  25 .Nm Lgetregs ,
  26 .Nm Lsetregs
  27 .Nd get and set thread registers
  28 .Sh LIBRARY
  29 .Lb libproc
  30 .Sh SYNOPSIS
  31 .In libproc.h
  32 .Ft int
  33 .Fo Plwp_getfpregs
  34 .Fa "struct ps_prochandle *P"
  35 .Fa "lwpid_t lwpid"
  36 .Fa "prfpregset_t *fpregs"
  37 .Fc
  38 .Ft int
  39 .Fo Plwp_setfpregs
  40 .Fa "struct ps_prochandle *P"
  41 .Fa "lwpid_t lwpid"
  42 .Fa "const prfpregset_t fpregs"
  43 .Fc
  44 .Ft int
  45 .Fo Plwp_getregs
  46 .Fa "struct ps_prochandle *P"
  47 .Fa "lwpid_t lwpid"
  48 .Fa "prgregset_t gregs"
  49 .Fc
  50 .Ft int
  51 .Fo Plwp_setregs
  52 .Fa "struct ps_prochandle *P"
  53 .Fa "lwpid_t lwpid"
  54 .Fa "const prgregset_t gregs"
  55 .Fc
  56 .Ft int
  57 .Fo Lgetfpregs
  58 .Fa "struct ps_lwphandle *L"
  59 .Fa "prfpregset_t *fpregs"
  60 .Fc
  61 .Ft int
  62 .Fo Lsetfpregs
  63 .Fa "struct ps_lwphandle *L"
  64 .Fa "const prfpregset_t *fpregs"
  65 .Fc
  66 .Ft int
  67 .Fo Lgetregs
  68 .Fa "struct ps_lwphandle *L"
  69 .Fa "prgregset_t gregs"
  70 .Fc
  71 .Ft int
  72 .Fo Lsetregs
  73 .Fa "struct ps_lwphandle *L"
  74 .Fa "const prgregset_t gregs"
  75 .Fc
  76 .Sh DESCRIPTION
  77 The
  78 .Fn Plwp_getregs ,
  79 .Fn Plwp_setregs ,
  80 .Fn Plwp_getfpregs ,
  81 and
  82 .Fn Plwp_setfpregs
  83 functions allow one to get and set the general purpose and floating
  84 point registers from the thread
  85 .Fa lwpid
  86 in the process handle
  87 .Fa P .
  88 .Pp
  89 The
  90 .Fn Plwp_getfpregs
  91 function updates the structure pointed to by
  92 .Fa fpregs
  93 with the state and values of the floating point registers of the thread
  94 specified by
  95 .Fa lwpid .

 113 .Fn Plwp_setregs
 114 function updates the general purpose registers of the thread specified
 115 by
 116 .Fa lwpid
 117 to the register state contained in
 118 .Fa gregs .
 119 .Pp
 120 Processes must be stopped before obtaining the register state of
 121 individual threads.
 122 Processes may be stopped with
 123 .Xr Pstop 3PROC .
 124 The structures used for registers are described in
 125 .Xr proc 5
 126 and their definitions may be found in
 127 .In procfs.h .
 128 The definitions of these structures varies based on the architecture of
 129 the system and the running process.
 130 .Pp
 131 One may not set the register values of a process that is not an active
 132 process, e.g. a process handle that refers to a file or a core file.
 133 .Pp
 134 The
 135 .Fn Lgetfpregs ,
 136 .Fn Lsetfpregs ,
 137 .Fn Lgetregs ,
 138 and
 139 .Fn Lsetregs
 140 functions behave in a same way as the corresponding process-handle
 141 specific functions, with the following differences:
 142 .Bl -dash
 143 .It
 144 Rather than take a specified thread id via
 145 .Fa lwpid ,
 146 they operate on the thread that the thread-handle,
 147 .Fa L ,
 148 refers to.
 149 .It
 150 The process-handle functions will require that the entire process is
 151 stopped before performing a set operation.
 152 In these cases, only the specific thread identified by the handle
 153 .Fa L
 154 must be stopped through a call to
 155 .Xr Lstop 3PROC
 156 or similar.
 157 Note, a suspended thread
 158 .Po
 159 .Xr thr_suspend 3C
 160 .Pc
 161 is not considered stopped for these purposes.
 162 .El
 163 .Sh RETURN VALUES
 164 Upon successful completion, the
 165 .Fn Plwp_getregs ,
 166 .Fn Plwp_setregs ,
 167 .Fn Plwp_getfpregs ,
 168 .Fn Plwp_setfpregs ,
 169 .Fn Lgetfpregs ,
 170 .Fn Lsetfpregs ,
 171 .Fn Lgetregs ,
 172 and
 173 .Fn Lsetregs
 174 functions return
 175 .Sy 0
 176 and obtain or set the register state.
 177 Otherwise,
 178 .Sy -1
 179 is returned,
 180 .Va errno
 181 is set to indicate the error, and the register state is not updated nor
 182 are the data pointers changed.
 183 .Sh ERRORS
 184 The implementations of these functions may use standard system and
 185 library calls that can fail.
 186 For a full list of possible errors also see the
 187 .Sy DIAGNOSTICS
 188 section in
 189 .Xr proc 5 .
 190 .Pp
 191 The
 192 .Fn Plwp_getregs ,
 193 .Fn Plwp_setregs ,
 194 .Fn Plwp_getfpregs ,
 195 and
 196 .Fn Plwp_setfpregs
 197 will fail if:
 198 .Bl -tag -width Er
 199 .It Er EBUSY
 200 The process handle
 201 .Fa P
 202 is not currently stopped.
 203 .It Er ENOENT
 204 There is no thread in
 205 .Fa P
 206 with id
 207 .Fa lwpid .
 208 .El
 209 The
 210 .Fn Lgetfpregs ,
 211 .Fn Lsetfpregs ,
 212 .Fn Lgetregs ,
 213 and
 214 .Fn Lsetregs
 215 will fail if:
 216 .Bl -tag -width Er
 217 .It Er EBUSY
 218 The thread handle
 219 .Fa L
 220 is not currently stopped.
 221 .El
 222 .Sh INTERFACE STABILITY
 223 .Sy Uncommitted
 224 .Sh MT-LEVEL
 225 See
 226 .Sy LOCKING
 227 in
 228 .Xr libproc 3LIB .
 229 .Sh SEE ALSO
 230 .Xr libproc 3LIB ,
 231 .Xr proc 5