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). For more information on how the 61representative 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 70processes. In addition, one may obtain registers from core files, but 71not set them. To 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. For a list of registers, see 78.In sys/regset.h . 79The set of registers is specific to each architecture of the system. The 80.Fn Pgetareg 81function will fill in the value of 82.Fa preg 83with the value of the register 84.Fa regno , 85while the 86.Fn Pputareg 87function will update the value of the register 88.Fa regno 89with the value in 90.Fa preg . 91Updated registers will be set when the process resumes execution. 92.Pp 93The 94.Fn Lgetareg 95and 96.Fn Lputareg 97functions are equivalent to the 98.Fn Pgetareg 99and 100.Fn Psetareg 101functions, except rather than operating on the process and its 102representative thread, they instead operate on the thread handle 103.Fa L . 104.Sh RETURN VALUES 105Upon successful completion, the 106.Fn Pgetareg 107and 108.Fn Pputareg 109function return 110.Sy 0 . 111Otherwise, 112.Sy -1 113is returned, 114.Sy errno 115is set, and no registers will have been gotten or updated. 116.Sh ERRORS 117The 118.Fn Pgetareg 119and 120.Fn Lgetareg 121functions will fail if: 122.Bl -tag -width Er 123.It Er EINVAL 124The value of 125.Fa regno 126is invalid. This means it is less than 127.Sy 0 128and greater than 129.Sy NPRGREG . 130Note, 131.Sy NPRGREG Ns 's 132value varies based on process architecture. 133.It Er EBUSY 134The handle 135.Fa P 136is neither stopped nor a core file. 137.It Er ENODATA 138The handle 139.Fa P 140refers to a file obtained through 141.Xr Pgrab_file 3PROC . 142.El 143.Pp 144The 145.Fn Pputareg 146and 147.Fn Lputareg 148functions will fail if: 149.Bl -tag -width Er 150.It Er EINVAL 151The value of 152.Fa regno 153is invalid. This means it is less than 154.Sy 0 155and greater than 156.Sy NPRGREG . 157Note, 158.Sy NPRGREG Ns 's 159value varies based on process architecture. 160.It Er EBUSY 161The handle 162.Fa P 163is not stopped or refers to a non-active process. 164.El 165.Sh INTERFACE STABILITY 166.Sy Uncommitted 167.Sh MT-LEVEL 168See 169.Sy LOCKING 170in 171.Xr libproc 3LIB . 172.Sh SEE ALSO 173.Xr errno 3C , 174.Xr libproc 3LIB , 175.Xr Lgrab 3PROC , 176.Xr Pgrab_file 3PROC , 177.Xr Pstop 3PROC , 178.Xr proc 4 179