Tribblix: manual page: Plwp

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

Uncommitted

MT-LEVEL
See LOCKING in libproc(3LIB).