usr/src/man/man3proc/Plwp_getxregs.3proc

   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 PLWP_GETXREGS 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Plwp_getxregs ,
  19 .Nm Plwp_setxregs
  20 .Nd get and set extended register state
  21 .Sh SYNOPSIS
  22 .Lb libproc
  23 .In libproc.h
  24 .Ft int
  25 .Fo Plwp_getxregs
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "lwpid_t lwpid"
  28 .Fa "prxregset_t *xregs"
  29 .Fc
  30 .Ft int
  31 .Fo Plwp_setxregs
  32 .Fa "struct ps_prochandle *P"
  33 .Fa "lwpid_t lwpid"
  34 .Fa "const prxregset_t *xregs"
  35 .Fc
  36 .Sh DESCRIPTION
  37 The
  38 .Fn Plwp_getxregs
  39 and
  40 .Fn Plwp_setxregs
  41 functions get and set the extended register state of the thread
  42 .Fa lwpid
  43 in the process handle
  44 .Fa P .
  45 .Pp
  46 The extended register state is defined by the architecture.
  47 These registers may refer to optional registers that have become common on the
  48 platform, but are not part of the standard ABI and thus not covered by
  49 functions such as
  50 .Xr Plwp_getregs 3PROC
  51 and
  52 .Xr Plwp_getfpregs 3PROC .
  53 .Pp
  54 The
  55 .Fn Plwp_getxregs
  56 function gets the extended register state information and places it into
  57 .Fa xregs .
  58 Where as the
  59 .Fn Plwp_setxregs
  60 function sets the extended register state information in
  61 .Fa xregs
  62 for the process handle
  63 .Fa P .
  64 .Pp
  65 Processes must be stopped prior to obtaining the register state of
  66 individual threads.
  67 Processes may be stopped with
  68 .Xr Pstop 3PROC .
  69 .Pp
  70 The
  71 .Sy prxregset_t
  72 structure is described in
  73 .Xr proc 4 .
  74 .Pp
  75 One may not set the register values of a process that is not an active
  76 process, e.g. a process handle that refers to a file or a core file.
  77 .Sh RETURN VALUES
  78 Upon successful completion, the
  79 .Fn Plwp_getxregs
  80 and
  81 .Fn Plwp_setxregs
  82 functions return
  83 .Sy 0
  84 and get or set the register state.
  85 Otherwise,
  86 .Sy -1
  87 is returned and
  88 .Sy errno
  89 is set to indicate the error.
  90 .Sh ERRORS
  91 For a full list of possible errors see the
  92 .Sy DIAGNOSTICS
  93 section in
  94 .Xr proc 4 .
  95 .Pp
  96 The
  97 .Fn Plwp_getxregs
  98 and
  99 .Fn Plwp_setxregs
 100 function will fail if:
 101 .Bl -tag -width Er
 102 .It Er ENODATA
 103 The process handle
 104 .Fa P
 105 does not have any extended register state information.
 106 .It Er EBUSY
 107 The process handle
 108 .Fa P
 109 refers to a live process and it is not stopped.
 110 .It Er ENOENT
 111 The process handle
 112 .Fa P
 113 refers to a live process and there is no thread with id
 114 .Fa lwpid .
 115 .It Er EINVAL
 116 The process handle
 117 .Fa P
 118 refers to a core file and there is no thread with id
 119 .Fa lwpid .
 120 .El
 121 .Sh ARCHITECTURE
 122 The
 123 .Fn Plwp_getxregs
 124 and
 125 .Fn Plwp_setxregs
 126 functions are only available on
 127 .Sy SPARC
 128 platforms.
 129 .Sh INTERFACE STABILITY
 130 .Sy Uncommitted
 131 .Sh MT-LEVEL
 132 See
 133 .Sy LOCKING
 134 in
 135 .Xr libproc 3LIB .
 136 .Sh SEE ALSO
 137 .Xr libproc 3LIB ,
 138 .Xr Plwp_getfpregs 3PROC ,
 139 .Xr Plwp_getregs 3PROC ,
 140 .Xr Plwp_setfpregs 3PROC ,
 141 .Xr Plwp_setregs 3PROC ,
 142 .Xr Pstop 3PROC ,
 143 .Xr proc 4