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