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.\"
14.Dd May 11, 2016
15.Dt PLWP_GETXREGS 3PROC
16.Os
17.Sh NAME
18.Nm Plwp_getxregs ,
19.Nm Plwp_setxregs
20.Nd get and set extended register state
21.Sh LIBRARY
22.Lb libproc
23.Sh SYNOPSIS
24.In libproc.h
25.Ft int
26.Fo Plwp_getxregs
27.Fa "struct ps_prochandle *P"
28.Fa "lwpid_t lwpid"
29.Fa "prxregset_t *xregs"
30.Fc
31.Ft int
32.Fo Plwp_setxregs
33.Fa "struct ps_prochandle *P"
34.Fa "lwpid_t lwpid"
35.Fa "const prxregset_t *xregs"
36.Fc
37.Sh DESCRIPTION
38The
39.Fn Plwp_getxregs
40and
41.Fn Plwp_setxregs
42functions get and set the extended register state of the thread
43.Fa lwpid
44in the process handle
45.Fa P .
46.Pp
47The extended register state is defined by the architecture.
48These registers may refer to optional registers that have become common on the
49platform, but are not part of the standard ABI and thus not covered by
50functions such as
51.Xr Plwp_getregs 3PROC
52and
53.Xr Plwp_getfpregs 3PROC .
54.Pp
55The
56.Fn Plwp_getxregs
57function gets the extended register state information and places it into
58.Fa xregs .
59Where as the
60.Fn Plwp_setxregs
61function sets the extended register state information in
62.Fa xregs
63for the process handle
64.Fa P .
65.Pp
66Processes must be stopped prior to obtaining the register state of
67individual threads.
68Processes may be stopped with
69.Xr Pstop 3PROC .
70.Pp
71The
72.Sy prxregset_t
73structure is described in
74.Xr proc 4 .
75.Pp
76One may not set the register values of a process that is not an active
77process, e.g. a process handle that refers to a file or a core file.
78.Sh RETURN VALUES
79Upon successful completion, the
80.Fn Plwp_getxregs
81and
82.Fn Plwp_setxregs
83functions return
84.Sy 0
85and get or set the register state.
86Otherwise,
87.Sy -1
88is returned and
89.Sy errno
90is set to indicate the error.
91.Sh ERRORS
92For a full list of possible errors see the
93.Sy DIAGNOSTICS
94section in
95.Xr proc 4 .
96.Pp
97The
98.Fn Plwp_getxregs
99and
100.Fn Plwp_setxregs
101function will fail if:
102.Bl -tag -width Er
103.It Er ENODATA
104The process handle
105.Fa P
106does not have any extended register state information.
107.It Er EBUSY
108The process handle
109.Fa P
110refers to a live process and it is not stopped.
111.It Er ENOENT
112The process handle
113.Fa P
114refers to a live process and there is no thread with id
115.Fa lwpid .
116.It Er EINVAL
117The process handle
118.Fa P
119refers to a core file and there is no thread with id
120.Fa lwpid .
121.El
122.Sh ARCHITECTURE
123The
124.Fn Plwp_getxregs
125and
126.Fn Plwp_setxregs
127functions are only available on
128.Sy SPARC
129platforms.
130.Sh INTERFACE STABILITY
131.Sy Uncommitted
132.Sh MT-LEVEL
133See
134.Sy LOCKING
135in
136.Xr libproc 3LIB .
137.Sh SEE ALSO
138.Xr libproc 3LIB ,
139.Xr Plwp_getfpregs 3PROC ,
140.Xr Plwp_getregs 3PROC ,
141.Xr Plwp_setfpregs 3PROC ,
142.Xr Plwp_setregs 3PROC ,
143.Xr Pstop 3PROC ,
144.Xr proc 4
145