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 . 58The getting and setting of registers of the process operates on the 59representative thread (LWP). 60For more information on how the representative is chosen, see 61.Xr proc 4 . 62.Pp 63To change the registers of a specific thread, use the 64.Fn Lgetareg 65and 66.Fn Lputareg 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