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 .
  96 .Pp
  97 The
  98 .Fn Plwp_setfpregs
  99 function updates the floating point registers of the thread specified by
 100 .Fa lwpid
 101 to the register state contained in
 102 .Fa fpregs .
 103 .Pp
 104 The
 105 .Fn Plwp_getregs
 106 function updates the structure pointed to by
 107 .Fa gregs
 108 with the state and values of the general purpose registers of the thread
 109 specified by
 110 .Fa lwpid.
 111 .Pp
 112 The
 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