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