share/man/man3proc/Plwp_getasrs.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_GETASRS 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Plwp_getasrs ,
  19 .Nm Plwp_setasrs
  20 .Nd get and set SPARCv9 ancillary state registers
  21 .Sh SYNOPSIS
  22 .Lb libproc
  23 .In libproc.h
  24 .Ft int
  25 .Fo Plwp_getasrs
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "lwpid_t lwpid"
  28 .Fa "asrset_t asrs"
  29 .Fc
  30 .Ft int
  31 .Fo Plwp_setasrs
  32 .Fa "struct ps_prochandle *P"
  33 .Fa "lwpid_t lwpid"
  34 .Fa "const asrset_t asrs"
  35 .Fc
  36 .Sh DESCRIPTION
  37 The
  38 .Fn Plwp_getasrs
  39 and
  40 .Fn Plwp_setasrs
  41 functions get and set the ancillary thread-specific register set of the
  42 thread
  43 .Fa lwpid
  44 in the process handle
  45 .Fa P .
  46 .Pp
  47 The ancillary state registers are only present on 64-bit
  48 .Sy SPARCv9
  49 processes.
  50 They contain information that is specific to the platform and are not included
  51 in the information obtained through functions such as
  52 .Xr Plwp_getregs 3PROC ,
  53 .Xr Plwp_getfpregs 3PROC ,
  54 and
  55 .Xr Plwp_getxregs 3PROC .
  56 .Pp
  57 The
  58 .Fn Plwp_getasrs
  59 function reads the ancillary registers into
  60 .Fa asrs ,
  61 while the
  62 .Fn Plwp_setasrs
  63 sets the thread's ancillary registers to the values provided by
  64 .Fa asrs .
  65 .Pp
  66 Processes should 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 asrset_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_getasrs
  81 and
  82 .Fn Plwp_setasrs
  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_getasrs
  99 and
 100 .Fn Plwp_setasrs
 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 ancillary 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 or it is not a 64-bit SPARCv9 process.
 117 .It Er EINVAL
 118 The process handle
 119 .Fa P
 120 refers to a core file and there is no thread with id
 121 .Fa lwpid .
 122 .El
 123 .Sh ARCHITECTURE
 124 The
 125 .Fn Plwp_getasrs
 126 and
 127 .Fn Plwp_setasrs
 128 functions are only available on
 129 64-bit
 130 .Sy SPARCv9
 131 platforms.
 132 .Sh INTERFACE STABILITY
 133 .Sy Uncommitted
 134 .Sh MT-LEVEL
 135 See
 136 .Sy LOCKING
 137 in
 138 .Xr libproc 3LIB .
 139 .Sh SEE ALSO
 140 .Xr libproc 3LIB ,
 141 .Xr Plwp_getfpregs 3PROC ,
 142 .Xr Plwp_getregs 3PROC ,
 143 .Xr Plwp_setregs 3PROC ,
 144 .Xr Plwp_setregs 3PROC ,
 145 .Xr Pstop 3PROC ,
 146 .Xr proc 4