PLWP_GETXREGS(3PROC) Process Control Library Functions PLWP_GETXREGS(3PROC)
NAME
Plwp_getxregs,
Plwp_freexregs,
Plwp_setxregs,
Lgetxregs,
Lsetxregs - get
and set extended register state
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> int Plwp_getxregs(
struct ps_prochandle *P,
lwpid_t lwpid,
prxregset_t **xregsp,
size_t *sizep);
int Plwp_freexregs(
struct ps_prochandle *P,
lwpid_t lwpid,
prxregset_t *xregs,
size_t size);
int Plwp_setxregs(
struct ps_prochandle *P,
lwpid_t lwpid,
const prxregset_t *xregs);
int Lgetxregs(
struct ps_lwphandle *L,
prxregset_t **xregsp,
size_t *sizep);
int Lsetxregs(
struct ps_lwphandle *L,
const prxregset_t *xregs);
DESCRIPTION
The
Plwp_getxregs() and
Plwp_setxregs() functions get and set the extended
register state of the thread
lwpid in the process handle
P.
The extended register state is defined by the architecture. These
registers may refer to optional registers that have become common on the
platform, but are not part of the traditional ABI and thus not covered by
functions such as
Plwp_getregs(3PROC) and
Plwp_getfpregs(3PROC). Support
for the extended registers varies based on the architecture and varies
based on the specific system. For example, on x86 based CPUs the xregs
functionality requires the x86 xsave functionality to be supported.
The
Plwp_getxregs() function gets the extended register state information,
allocates the appropriate sized buffer for it, and places a pointer to that
buffer into
xregs and updates
sizep to indicate the size of the allocated
structure. Due to the fact that hardware has varying sized extended
register sets, the exact size of the structure can vary between different
running systems and core files. It is also possible that some processor
extensions are enabled at process runtime, leading for this to further be
different between different processes on the same system. As such, all of
the different platform instantiations of the
prxregset_t end up generally
being opaque structures that can be cast to something more specific that
also includes its size.
The obtained
prxregset_t in
xregsp must be freed by the caller with the
Plwp_freexregs() function.
The
Plwp_setxregs() function sets the extended register state information
in
xregs for the process handle
P.
Processes must be stopped prior to obtaining the register state of
individual threads. Processes may be stopped with
Pstop(3PROC).
The
prxregset_t structure is described in
proc(5).
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.
The
Lgetxregs() and
Lsetxregs() functions are equivalent to the
Plwp_getxregs() and
Plwp_setxregs() functions except that they operate on a
specific thread identified by the handle
L and only require that the thread
in question be stopped. Data allocated with the
Lgetxregs() functions
should be freed with the
Plwp_freexregs() function.
RETURN VALUES
Upon successful completion, the
Plwp_getxregs() and
Plwp_setxregs()
functions return
0 and get or set the register state. Otherwise,
-1 is
returned and
errno is set to indicate the error.
ERRORS
For a full list of possible errors see the
DIAGNOSTICS section in
proc(5).
The
Plwp_getxregs() and
Plwp_setxregs() function will fail if:
ENODATA The process handle
P does not have any extended register
state information. This generally happens because the
platform does not support it.
EBUSY The process handle
P refers to a live process and it is
not stopped.
ENOENT There is no thread with id
lwpid in the process handle
P.
The
Lgetxregs() and
Lsetxregs() function will fail if:
ENODATA The thread handle
L does not have any extended register
state information. This generally happens because the
platform does not support it.
EBUSY The thread handle
L refers to a live process and the
thread is not stopped.
INTERFACE STABILITY
UncommittedMT-LEVEL See
LOCKING in
libproc(3LIB).
SEE ALSO
libproc(3LIB),
Plwp_getfpregs(3PROC),
Plwp_getregs(3PROC),
Plwp_setfpregs(3PROC),
Plwp_setregs(3PROC),
Pstop(3PROC),
proc(5)illumos January 19, 2023 illumos