'\" te
.\"  Copyright (c) 1998 Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.\" Copyright 2023 Oxide Computer Company
.TH PS_LGETREGS 3PROC "January 23, 2023"
.SH NAME
ps_lgetregs, ps_lsetregs, ps_lgetfpregs, ps_lsetfpregs, ps_lgetxregsize,
ps_lgetxregs, ps_lsetxregs \- routines that access the target process register
in libthread_db
.SH SYNOPSIS
.nf
#include <proc_service.h>

\fBps_err_e\fR \fBps_lgetregs\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBprgregset_t\fR \fIgregset\fR);
.fi

.LP
.nf
\fBps_err_e\fR \fBps_lsetregs\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBstatic prgregset_t\fR \fIgregset\fR);
.fi

.LP
.nf
\fBps_err_e\fR \fBps_lgetfpregs\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBprfpregset_t *\fR\fIfpregs\fR);
.fi

.LP
.nf
\fBps_err_e\fR \fBps_lsetfpregs\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBstatic prfpregset_t *\fR\fIfpregs\fR);
.fi

.LP
.nf
\fBps_err_e\fR \fBps_lgetxregsize\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBint *\fR\fIxregsize\fR);
.fi

.LP
.nf
\fBps_err_e\fR \fBps_lgetxregs\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBcaddr_t\fR \fIxregset\fR);
.fi

.LP
.nf
\fBps_err_e\fR \fBps_lsetxregs\fR(\fBstruct ps_prochandle *\fR\fIph\fR, \fBlwpid_t\fR \fIlid\fR,
     \fBcaddr_t\fR \fIxregset\fR);
.fi

.SH DESCRIPTION
\fBps_lgetregs()\fR, \fBps_lsetregs()\fR, \fBps_lgetfpregs()\fR,
\fBps_lsetfpregs()\fR, \fBps_lgetxregsize()\fR, \fBps_lgetxregs()\fR,
\fBps_lsetxregs()\fR read and write register sets from lightweight processes
(\fBLWP\fRs) within the target process identified by \fIph\fR.
\fBps_lgetregs()\fR gets the general registers of the \fBLWP\fR identified by
\fIlid\fR, and \fBps_lsetregs()\fR sets them. \fBps_lgetfpregs()\fR gets the
\fBLWP\fR's floating point register set, while \fBps_lsetfpregs()\fR sets it.
.LP
\fBps_lgetxregsize()\fR, \fBps_lgetxregs()\fR, and \fBps_lsetxregs()\fR are used
to get and set the extended register set. Support for an extended register set
depends on both the instruction-set architecture and the specific CPU (e.g.
while x86 supports xregs, their availability depends on the CPU's support for
the xsave feature set). On platforms without support for these, controlling
processes will still need to define them; however, they are allowed to simply
return errors.
.LP
\fBps_lgetxregsize()\fR returns in \fB*\fR\fIxregsize\fR the size of the
architecture-dependent extra state registers. \fBps_lgetxregs()\fR gets the
extra state registers, and \fBps_lsetxregs()\fR sets them. When getting the
registers, the size of \fIxregset\fR must be at least the size returned by
\fBps_lgetxregsize()\fR.
.SH RETURN VALUES
.ne 2
.na
\fB\fBPS_OK\fR \fR
.ad
.RS 16n
The call returned successfully.
.RE

.sp
.ne 2
.na
\fB\fBPS_NOFREGS\fR \fR
.ad
.RS 16n
Floating point registers are neither available for this architecture nor for
this process.
.RE

.sp
.ne 2
.na
\fB\fBPS_NOXREGS\fR \fR
.ad
.RS 16n
Extra state registers are not available on this architecture.
.RE

.sp
.ne 2
.na
\fB\fBPS_ERR\fR \fR
.ad
.RS 16n
The function did not return successfully.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT Level	Safe
.TE

.SH SEE ALSO
.BR libc_db (3LIB),
.BR proc_service (3PROC),
.BR attributes (7),
.BR threads (7)