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