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