1 PLWP_GETXREGS(3PROC) Process Control Library Functions PLWP_GETXREGS(3PROC)
2
3 NAME
4 Plwp_getxregs, Plwp_setxregs - get and set extended register state
5
6 LIBRARY
7 Process Control Library (libproc, -lproc)
8
9 SYNOPSIS
10 #include <libproc.h>
11
12 int
13 Plwp_getxregs(struct ps_prochandle *P, lwpid_t lwpid,
14 prxregset_t *xregs);
15
16 int
17 Plwp_setxregs(struct ps_prochandle *P, lwpid_t lwpid,
18 const prxregset_t *xregs);
19
20 DESCRIPTION
21 The Plwp_getxregs() and Plwp_setxregs() functions get and set the
22 extended register state of the thread lwpid in the process handle P.
23
24 The extended register state is defined by the architecture. These
25 registers may refer to optional registers that have become common on the
26 platform, but are not part of the standard ABI and thus not covered by
27 functions such as Plwp_getregs(3PROC) and Plwp_getfpregs(3PROC).
28
29 The Plwp_getxregs() function gets the extended register state information
30 and places it into xregs. Where as the Plwp_setxregs() function sets the
31 extended register state information in xregs for the process handle P.
32
33 Processes must be stopped prior to obtaining the register state of
34 individual threads. Processes may be stopped with Pstop(3PROC).
35
36 The prxregset_t structure is described in proc(5).
37
38 One may not set the register values of a process that is not an active
39 process, e.g. a process handle that refers to a file or a core file.
40
41 RETURN VALUES
42 Upon successful completion, the Plwp_getxregs() and Plwp_setxregs()
43 functions return 0 and get or set the register state. Otherwise, -1 is
44 returned and errno is set to indicate the error.
45
46 ERRORS
47 For a full list of possible errors see the DIAGNOSTICS section in
48 proc(5).
49
50 The Plwp_getxregs() and Plwp_setxregs() function will fail if:
51
52 ENODATA The process handle P does not have any extended
53 register state information.
54
55 EBUSY The process handle P refers to a live process and it
56 is not stopped.
57
58 ENOENT The process handle P refers to a live process and
59 there is no thread with id lwpid.
60
61 EINVAL The process handle P refers to a core file and there
62 is no thread with id lwpid.
63
64 ARCHITECTURE
65 The Plwp_getxregs() and Plwp_setxregs() functions are only available on
66 SPARC platforms.
67
68 INTERFACE STABILITY
69 Uncommitted
70
71 MT-LEVEL
72 See LOCKING in libproc(3LIB).
73
74 SEE ALSO
75 libproc(3LIB), Plwp_getfpregs(3PROC), Plwp_getregs(3PROC),
76 Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Pstop(3PROC), proc(5)
77
78 illumos May 11, 2016 illumos
|
1 PLWP_GETXREGS(3PROC) Process Control Library Functions PLWP_GETXREGS(3PROC)
2
3 NAME
4 Plwp_getxregs, Plwp_freexregs, Plwp_setxregs, Lgetxregs, Lsetxregs - get
5 and set extended register state
6
7 LIBRARY
8 Process Control Library (libproc, -lproc)
9
10 SYNOPSIS
11 #include <libproc.h>
12
13 int
14 Plwp_getxregs(struct ps_prochandle *P, lwpid_t lwpid,
15 prxregset_t **xregsp, size_t *sizep);
16
17 int
18 Plwp_freexregs(struct ps_prochandle *P, lwpid_t lwpid,
19 prxregset_t *xregs, size_t size);
20
21 int
22 Plwp_setxregs(struct ps_prochandle *P, lwpid_t lwpid,
23 const prxregset_t *xregs);
24
25 int
26 Lgetxregs(struct ps_lwphandle *L, prxregset_t **xregsp, size_t *sizep);
27
28 int
29 Lsetxregs(struct ps_lwphandle *L, const prxregset_t *xregs);
30
31 DESCRIPTION
32 The Plwp_getxregs() and Plwp_setxregs() functions get and set the
33 extended register state of the thread lwpid in the process handle P.
34
35 The extended register state is defined by the architecture. These
36 registers may refer to optional registers that have become common on the
37 platform, but are not part of the traditional ABI and thus not covered by
38 functions such as Plwp_getregs(3PROC) and Plwp_getfpregs(3PROC). Support
39 for the extended registers varies based on the architecture and varies
40 based on the specific system. For example, on x86 based CPUs the xregs
41 functionality requires the x86 xsave functionality to be supported.
42
43 The Plwp_getxregs() function gets the extended register state
44 information, allocates the appropriate sized buffer for it, and places a
45 pointer to that buffer into xregs and updates sizep to indicate the size
46 of the allocated structure. Due to the fact that hardware has varying
47 sized extended register sets, the exact size of the structure can vary
48 between different running systems and core files. It is also possible
49 that some processor extensions are enabled at process runtime, leading
50 for this to further be different between different processes on the same
51 system. As such, all of the different platform instantiations of the
52 prxregset_t end up generally being opaque structures that can be cast to
53 something more specific that also includes its size.
54
55 The obtained prxregset_t in xregsp must be freed by the caller with the
56 Plwp_freexregs() function.
57
58 The Plwp_setxregs() function sets the extended register state information
59 in xregs for the process handle P.
60
61 Processes must be stopped prior to obtaining the register state of
62 individual threads. Processes may be stopped with Pstop(3PROC).
63
64 The prxregset_t structure is described in proc(5).
65
66 One may not set the register values of a process that is not an active
67 process, e.g. a process handle that refers to a file or a core file.
68
69 The Lgetxregs() and Lsetxregs() functions are equivalent to the
70 Plwp_getxregs() and Plwp_setxregs() functions except that they operate on
71 a specific thread identified by the handle L and only require that the
72 thread in question be stopped. Data allocated with the Lgetxregs()
73 functions should be freed with the Plwp_freexregs() function.
74
75 RETURN VALUES
76 Upon successful completion, the Plwp_getxregs() and Plwp_setxregs()
77 functions return 0 and get or set the register state. Otherwise, -1 is
78 returned and errno is set to indicate the error.
79
80 ERRORS
81 For a full list of possible errors see the DIAGNOSTICS section in
82 proc(5).
83
84 The Plwp_getxregs() and Plwp_setxregs() function will fail if:
85
86 ENODATA The process handle P does not have any extended
87 register state information. This generally happens
88 because the platform does not support it.
89
90 EBUSY The process handle P refers to a live process and it
91 is not stopped.
92
93 ENOENT There is no thread with id lwpid in the process handle
94 P.
95 The Lgetxregs() and Lsetxregs() function will fail if:
96
97 ENODATA The thread handle L does not have any extended
98 register state information. This generally happens
99 because the platform does not support it.
100
101 EBUSY The thread handle L refers to a live process and the
102 thread is not stopped.
103
104 INTERFACE STABILITY
105 Uncommitted
106
107 MT-LEVEL
108 See LOCKING in libproc(3LIB).
109
110 SEE ALSO
111 libproc(3LIB), Plwp_getfpregs(3PROC), Plwp_getregs(3PROC),
112 Plwp_setfpregs(3PROC), Plwp_setregs(3PROC), Pstop(3PROC), proc(5)
113
114 illumos January 19, 2023 illumos
|