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