.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\" Copyright 2023 Oxide Computer Company
.\"
.Dd January 19, 2023
.Dt PLWP_GETREGS 3PROC
.Os
.Sh NAME
.Nm Plwp_getfpregs ,
.Nm Plwp_setfpregs ,
.Nm Plwp_getregs ,
.Nm Plwp_setregs ,
.Nm Lgetfpregs ,
.Nm Lsetfpregs ,
.Nm Lgetregs ,
.Nm Lsetregs
.Nd get and set thread registers
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft int
.Fo Plwp_getfpregs
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "prfpregset_t *fpregs"
.Fc
.Ft int
.Fo Plwp_setfpregs
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "const prfpregset_t fpregs"
.Fc
.Ft int
.Fo Plwp_getregs
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "prgregset_t gregs"
.Fc
.Ft int
.Fo Plwp_setregs
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "const prgregset_t gregs"
.Fc
.Ft int
.Fo Lgetfpregs
.Fa "struct ps_lwphandle *L"
.Fa "prfpregset_t *fpregs"
.Fc
.Ft int
.Fo Lsetfpregs
.Fa "struct ps_lwphandle *L"
.Fa "const prfpregset_t *fpregs"
.Fc
.Ft int
.Fo Lgetregs
.Fa "struct ps_lwphandle *L"
.Fa "prgregset_t gregs"
.Fc
.Ft int
.Fo Lsetregs
.Fa "struct ps_lwphandle *L"
.Fa "const prgregset_t gregs"
.Fc
.Sh DESCRIPTION
The
.Fn Plwp_getregs ,
.Fn Plwp_setregs ,
.Fn Plwp_getfpregs ,
and
.Fn Plwp_setfpregs
functions allow one to get and set the general purpose and floating
point registers from the thread
.Fa lwpid
in the process handle
.Fa P .
.Pp
The
.Fn Plwp_getfpregs
function updates the structure pointed to by
.Fa fpregs
with the state and values of the floating point registers of the thread
specified by
.Fa lwpid .
.Pp
The
.Fn Plwp_setfpregs
function updates the floating point registers of the thread specified by
.Fa lwpid
to the register state contained in
.Fa fpregs .
.Pp
The
.Fn Plwp_getregs
function updates the structure pointed to by
.Fa gregs
with the state and values of the general purpose registers of the thread
specified by
.Fa lwpid.
.Pp
The
.Fn Plwp_setregs
function updates the general purpose registers of the thread specified
by
.Fa lwpid
to the register state contained in
.Fa gregs .
.Pp
Processes must be stopped before obtaining the register state of
individual threads.
Processes may be stopped with
.Xr Pstop 3PROC .
The structures used for registers are described in
.Xr proc 5
and their definitions may be found in
.In procfs.h .
The definitions of these structures varies based on the architecture of
the system and the running process.
.Pp
One may not set the register values of a process that is not an active
process, e.g. a process handle that refers to a file or a core file.
.Pp
The
.Fn Lgetfpregs ,
.Fn Lsetfpregs ,
.Fn Lgetregs ,
and
.Fn Lsetregs
functions behave in a same way as the corresponding process-handle
specific functions, with the following differences:
.Bl -dash
.It
Rather than take a specified thread id via
.Fa lwpid ,
they operate on the thread that the thread-handle,
.Fa L ,
refers to.
.It
The process-handle functions will require that the entire process is
stopped before performing a set operation.
In these cases, only the specific thread identified by the handle
.Fa L
must be stopped through a call to
.Xr Lstop 3PROC
or similar.
Note, a suspended thread
.Po
.Xr thr_suspend 3C
.Pc
is not considered stopped for these purposes.
.El
.Sh RETURN VALUES
Upon successful completion, the
.Fn Plwp_getregs ,
.Fn Plwp_setregs ,
.Fn Plwp_getfpregs ,
.Fn Plwp_setfpregs ,
.Fn Lgetfpregs ,
.Fn Lsetfpregs ,
.Fn Lgetregs ,
and
.Fn Lsetregs
functions return
.Sy 0
and obtain or set the register state.
Otherwise,
.Sy -1
is returned,
.Va errno
is set to indicate the error, and the register state is not updated nor
are the data pointers changed.
.Sh ERRORS
The implementations of these functions may use standard system and
library calls that can fail.
For a full list of possible errors also see the
.Sy DIAGNOSTICS
section in
.Xr proc 5 .
.Pp
The
.Fn Plwp_getregs ,
.Fn Plwp_setregs ,
.Fn Plwp_getfpregs ,
and
.Fn Plwp_setfpregs
will fail if:
.Bl -tag -width Er
.It Er EBUSY
The process handle
.Fa P
is not currently stopped.
.It Er ENOENT
There is no thread in
.Fa P
with id
.Fa lwpid .
.El
The
.Fn Lgetfpregs ,
.Fn Lsetfpregs ,
.Fn Lgetregs ,
and
.Fn Lsetregs
will fail if:
.Bl -tag -width Er
.It Er EBUSY
The thread handle
.Fa L
is not currently stopped.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr proc 5