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