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 PGETAREG 3PROC
16.Os
17.Sh NAME
18.Nm Pgetareg ,
19.Nm Pputareg ,
20.Nm Lgetareg ,
21.Nm Lputareg
22.Nd set and get a register from a stopped process or thread
23.Sh LIBRARY
24.Lb libproc
25.Sh SYNOPSIS
26.In libproc.h
27.Ft int
28.Fo Pgetareg
29.Fa "struct ps_prochandle *P"
30.Fa "int regno"
31.Fa "prgreg_t *preg"
32.Fc
33.Ft int
34.Fo Pputareg
35.Fa "struct ps_prochandle *P"
36.Fa "int regno"
37.Fa "prgreg_t preg"
38.Fc
39.Ft int
40.Fo Lgetareg
41.Fa "struct ps_lwphandle *L"
42.Fa "int regno"
43.Fa "prgreg_t *preg"
44.Fc
45.Ft int
46.Fo Lputareg
47.Fa "struct ps_lwphandle *L"
48.Fa "int regno"
49.Fa "prgreg_t preg"
50.Fc
51.Sh DESCRIPTION
52The
53.Fn Pgetareg
54and
55.Fn Pputareg
56functions read and update the registers of the process handle referred
57to by
58.Fa P .
59The getting and setting of registers of the process operates on the
60representative thread (LWP).
61For more information on how the representative is chosen, see
62.Xr proc 5 .
63.Pp
64To change the registers of a specific thread, use the
65.Fn Lgetareg
66and
67.Fn Lputareg
68functions.
69.Pp
70The getting and setting of registers only applies to stopped processes.
71In addition, one may obtain registers from core files, but not set them.
72To stop a process, see the
73.Xr Pstop 3PROC
74function.
75.Pp
76The register to get or set is indicated by the
77.Fa regno
78argument.
79For a list of registers, see
80.In sys/regset.h .
81The set of registers is specific to each architecture of the system.
82The
83.Fn Pgetareg
84function will fill in the value of
85.Fa preg
86with the value of the register
87.Fa regno ,
88while the
89.Fn Pputareg
90function will update the value of the register
91.Fa regno
92with the value in
93.Fa preg .
94Updated registers will be set when the process resumes execution.
95.Pp
96The
97.Fn Lgetareg
98and
99.Fn Lputareg
100functions are equivalent to the
101.Fn Pgetareg
102and
103.Fn Psetareg
104functions, except rather than operating on the process and its
105representative thread, they instead operate on the thread handle
106.Fa L .
107.Sh RETURN VALUES
108Upon successful completion, the
109.Fn Pgetareg
110and
111.Fn Pputareg
112function return
113.Sy 0 .
114Otherwise,
115.Sy -1
116is returned,
117.Sy errno
118is set, and no registers will have been gotten or updated.
119.Sh ERRORS
120The
121.Fn Pgetareg
122and
123.Fn Lgetareg
124functions will fail if:
125.Bl -tag -width Er
126.It Er EINVAL
127The value of
128.Fa regno
129is invalid.
130This means it is less than
131.Sy 0
132and greater than
133.Sy NPRGREG .
134Note,
135.Sy NPRGREG Ns 's
136value varies based on process architecture.
137.It Er EBUSY
138The handle
139.Fa P
140is neither stopped nor a core file.
141.It Er ENODATA
142The handle
143.Fa P
144refers to a file obtained through
145.Xr Pgrab_file 3PROC .
146.El
147.Pp
148The
149.Fn Pputareg
150and
151.Fn Lputareg
152functions will fail if:
153.Bl -tag -width Er
154.It Er EINVAL
155The value of
156.Fa regno
157is invalid.
158This means it is less than
159.Sy 0
160and greater than
161.Sy NPRGREG .
162Note,
163.Sy NPRGREG Ns 's
164value varies based on process architecture.
165.It Er EBUSY
166The handle
167.Fa P
168is not stopped or refers to a non-active process.
169.El
170.Sh INTERFACE STABILITY
171.Sy Uncommitted
172.Sh MT-LEVEL
173See
174.Sy LOCKING
175in
176.Xr libproc 3LIB .
177.Sh SEE ALSO
178.Xr errno 3C ,
179.Xr libproc 3LIB ,
180.Xr Lgrab 3PROC ,
181.Xr Pgrab_file 3PROC ,
182.Xr Pstop 3PROC ,
183.Xr proc 5
184