xref: /illumos-gate/usr/src/man/man3proc/Plwp_getregs.3proc (revision dd72704bd9e794056c558153663c739e2012d721)
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 02, 2020
15.Dt PLWP_GETREGS 3PROC
16.Os
17.Sh NAME
18.Nm Plwp_getfpregs ,
19.Nm Plwp_setfpregs ,
20.Nm Plwp_getregs ,
21.Nm Plwp_setregs
22.Nd get and set thread registers
23.Sh LIBRARY
24.Lb libproc
25.Sh SYNOPSIS
26.In libproc.h
27.Ft int
28.Fo Plwp_getfpregs
29.Fa "struct ps_prochandle *P"
30.Fa "lwpid_t lwpid"
31.Fa "prfpregset_t *fpregs"
32.Fc
33.Ft int
34.Fo Plwp_setfpregs
35.Fa "struct ps_prochandle *P"
36.Fa "lwpid_t lwpid"
37.Fa "const prfpregset_t fpregs"
38.Fc
39.Ft int
40.Fo Plwp_getregs
41.Fa "struct ps_prochandle *P"
42.Fa "lwpid_t lwpid"
43.Fa "prgregset_t gregs"
44.Fc
45.Ft int
46.Fo Plwp_setregs
47.Fa "struct ps_prochandle *P"
48.Fa "lwpid_t lwpid"
49.Fa "const prgregset_t gregs"
50.Fc
51.Sh DESCRIPTION
52The
53.Fn Plwp_getregs ,
54.Fn Plwp_setregs ,
55.Fn Plwp_getfpregs ,
56and
57.Fn Plwp_setfpregs
58functions allow one to get and set the general purpose and floating
59point registers from the thread
60.Fa lwpid
61in the process handle
62.Fa P .
63.Pp
64The
65.Fn Plwp_getfpregs
66function updates the structure pointed to by
67.Fa fpregs
68with the state and values of the floating point registers of the thread
69specified by
70.Fa lwpid .
71.Pp
72The
73.Fn Plwp_setfpregs
74function updates the floating point registers of the thread specified by
75.Fa lwpid
76to the register state contained in
77.Fa fpregs .
78.Pp
79The
80.Fn Plwp_getregs
81function updates the structure pointed to by
82.Fa gregs
83with the state and values of the general purpose registers of the thread
84specified by
85.Fa lwpid.
86.Pp
87The
88.Fn Plwp_setregs
89function updates the general purpose registers of the thread specified
90by
91.Fa lwpid
92to the register state contained in
93.Fa gregs .
94.Pp
95Processes must be stopped before obtaining the register state of
96individual threads.
97Processes may be stopped with
98.Xr Pstop 3PROC .
99The structures used for registers are described in
100.Xr proc 5
101and their definitions may be found in
102.In procfs.h .
103The definitions of these structures varies based on the architecture of
104the system and the running process.
105.Pp
106One may not set the register values of a process that is not an active
107process, e.g. a process handle that refers to a file or a core file.
108.Sh RETURN VALUES
109Upon successful completion, the
110.Fn Plwp_getregs ,
111.Fn Plwp_setregs ,
112.Fn Plwp_getfpregs ,
113and
114.Fn Plwp_setfpregs
115functions return
116.Sy 0
117and obtain or set the register state.
118Otherwise,
119.Sy -1
120is returned,
121.Sy errno
122is set to indicate the error, and the register state is not updated nor
123are the data pointers changed.
124.Sh ERRORS
125For a full list of possible errors also see the
126.Sy DIAGNOSTICS
127section in
128.Xr proc 5 .
129.Pp
130The
131.Fn Plwp_getregs ,
132.Fn Plwp_setregs ,
133.Fn Plwp_getfpregs ,
134and
135.Fn Plwp_setfpregs
136will fail if:
137.Bl -tag -width Er
138.It Er EBUSY
139The process handle
140.Fa P
141is not currently stopped.
142.It Er ENOENT
143There is no thread in
144.Fa P
145with id
146.Fa lwpid .
147.El
148.Sh INTERFACE STABILITY
149.Sy Uncommitted
150.Sh MT-LEVEL
151See
152.Sy LOCKING
153in
154.Xr libproc 3LIB .
155.Sh SEE ALSO
156.Xr libproc 3LIB ,
157.Xr proc 5
158