usr/src/man/man3proc/Plwp_getregs.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_GETREGS 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Plwp_getfpregs ,
  19 .Nm Plwp_setfpregs ,
  20 .Nm Plwp_getregs ,
  21 .Nm Plwp_setregs
  22 .Nd get and set thread registers
  23 .Sh LIBRARY
  24 .Lb libproc
  25 .Sh SYNOPSIS
  26 .In libproc.h
  27 .Ft int
  28 .Fo Plwp_getfpregs
  29 .Fa "struct ps_prochandle *P"
  30 .Fa "lwpid_t lwpid"
  31 .Fa "prfpregset_t *fpregs"
  32 .Fc
  33 .Ft int
  34 .Fo Plwp_setfpregs
  35 .Fa "struct ps_prochandle *P"
  36 .Fa "lwpid_t lwpid"
  37 .Fa "const prfpregset_t fpregs"
  38 .Fc
  39 .Ft int
  40 .Fo Plwp_getregs
  41 .Fa "struct ps_prochandle *P"
  42 .Fa "lwpid_t lwpid"
  43 .Fa "prpregset_t *gregs"
  44 .Fc
  45 .Ft int
  46 .Fo Plwp_setregs
  47 .Fa "struct ps_prochandle *P"
  48 .Fa "lwpid_t lwpid"
  49 .Fa "const prpregset_t gregs"
  50 .Fc
  51 .Sh DESCRIPTION
  52 The
  53 .Fn Plwp_getregs ,
  54 .Fn Plwp_setregs ,
  55 .Fn Plwp_getfpregs ,
  56 and
  57 .Fn Plwp_setfpregs
  58 functions allow one to get and set the general purpose and floating
  59 point registers from the thread
  60 .Fa lwpid
  61 in the process handle
  62 .Fa P .
  63 .Pp
  64 The
  65 .Fn Plwp_getfpregs
  66 function updates the structure pointed to by
  67 .Fa fpregs
  68 with the state and values of the floating point registers of the thread
  69 specified by
  70 .Fa lwpid .
  71 .Pp
  72 The
  73 .Fn Plwp_setfpregs
  74 function updates the floating point registers of the thread specified by
  75 .Fa lwpid
  76 to the register state contained in
  77 .Fa fpregs .
  78 .Pp
  79 The
  80 .Fn Plwp_getregs
  81 function updates the structure pointed to by
  82 .Fa gregs
  83 with the state and values of the general purpose registers of the thread
  84 specified by
  85 .Fa lwpid.
  86 .Pp
  87 The
  88 .Fn Plwp_setregs
  89 function updates the general purpose registers of the thread specified
  90 by
  91 .Fa lwpid
  92 to the register state contained in
  93 .Fa gregs .
  94 .Pp
  95 Processes must be stopped before obtaining the register state of
  96 individual threads.
  97 Processes may be stopped with
  98 .Xr Pstop 3PROC .
  99 The structures used for registers are described in
 100 .Xr proc 4
 101 and their defintions may be found in
 102 .In sys/regset.h .
 103 The definitions of these structures varies based on the architecture of
 104 the system and the running process.
 105 .Pp
 106 One may not set the register values of a process that is not an active
 107 process, e.g. a process handle that refers to a file or a core file.
 108 .Sh RETURN VALUES
 109 Upon successful completion, the
 110 .Fn Plwp_getregs ,
 111 .Fn Plwp_setregs ,
 112 .Fn Plwp_getfpregs ,
 113 and
 114 .Fn Plwp_setfpregs
 115 functions return
 116 .Sy 0
 117 and obtain or set the register state.
 118 Otherwise,
 119 .Sy -1
 120 is returned,
 121 .Sy errno
 122 is set to indicate the error, and the register state is not updated nor
 123 are the data pointers changed.
 124 .Sh ERRORS
 125 For a full list of possible errors also see the
 126 .Sy DIAGNOSTICS
 127 section in
 128 .Xr proc 4 .
 129 .Pp
 130 The
 131 .Fn Plwp_getregs ,
 132 .Fn Plwp_setregs ,
 133 .Fn Plwp_getfpregs ,
 134 and
 135 .Fn Plwp_setfpregs
 136 will fail if:
 137 .Bl -tag -width Er
 138 .It Er EBUSY
 139 The process handle
 140 .Fa P
 141 is not currently stopped.
 142 .It Er ENOENT
 143 There is no thread in
 144 .Fa P
 145 with id
 146 .Fa lwpid .
 147 .El
 148 .Sh INTERFACE STABILITY
 149 .Sy Uncommitted
 150 .Sh MT-LEVEL
 151 See
 152 .Sy LOCKING
 153 in
 154 .Xr libproc 3LIB .
 155 .Sh SEE ALSO
 156 .Xr libproc 3LIB ,
 157 .Xr proc 4