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