1 '\" te
   2 .\"  Copyright (c) 1998 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TD_THR_GETGREGS 3C_DB "Oct 20, 1998"
   7 .SH NAME
   8 td_thr_getgregs, td_thr_setgregs, td_thr_getfpregs, td_thr_setfpregs,
   9 td_thr_getxregsize, td_thr_getxregs, td_thr_setxregs \- reading and writing
  10 thread registers in libc_db
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
  15 #include <proc_service.h>
  16 #include <thread_db.h>
  17 
  18 \fBtd_err_e\fR \fBtd_thr_getgregs\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBprgregset_t\fR\fIgregset\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBtd_err_e\fR \fBtd_thr_setgregs\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBprgregset_t\fR\fIgregset\fR);
  24 .fi
  25 
  26 .LP
  27 .nf
  28 \fBtd_err_e\fR \fBtd_thr_getfpregs\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBprfpregset_t *\fR\fIfpregset\fR);
  29 .fi
  30 
  31 .LP
  32 .nf
  33 \fBtd_err_e\fR \fBtd_thr_setfpregs\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBprfpregset_t *\fR\fIfpregset\fR);
  34 .fi
  35 
  36 .LP
  37 .nf
  38 \fBtd_err_e\fR \fBtd_thr_getxregsize\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBint *\fR\fIxregsize\fR);
  39 .fi
  40 
  41 .LP
  42 .nf
  43 \fBtd_err_e\fR \fBtd_thr_getxregs\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBprxregset_t *\fR\fIxregset\fR);
  44 .fi
  45 
  46 .LP
  47 .nf
  48 \fBtd_err_e\fR \fBtd_thr_setxregs\fR(\fBconst td_thrhandle_t *\fR\fIth_p\fR, \fBprxregset_t *\fR\fIxregset\fR);
  49 .fi
  50 
  51 .SH DESCRIPTION
  52 .sp
  53 .LP






  54 These functions read and write the register sets associated with thread
  55 \fIth_p\fR. The \fBtd_thr_getgregs()\fR and \fBtd_thr_setgregs()\fR functions
  56 get and set, respectively, the general registers of thread \fIth_p\fR. The
  57 \fBtd_thr_getfpregs()\fR and \fBtd_thr_setfpregs()\fR functions get and set,
  58 respectively, the thread's floating point register set. The
  59 \fBtd_thr_getxregsize()\fR, \fBtd_thr_getxregs()\fR, and
  60 \fBtd_thr_setxregs()\fR functions are SPARC-specific. The
  61 \fBtd_thr_getxregsize()\fR function returns in *\fIxregsize\fR the size of the
  62 architecture-dependent extra state registers. The \fBtd_thr_getxregs()\fR and
  63 \fBtd_thr_setxregs()\fR functions get and set, respectively, those extra state
  64 registers. On non-SPARC architectures, these functions return \fBTD_NOXREGS\fR.
  65 .sp
  66 .LP
  67 If the thread specified by \fIth_p\fR is currently executing on a lightweight
  68 process ( \fBLWP),\fR these functions read or write, respectively, the
  69 appropriate register set to the \fBLWP\fR using the imported interface. If the
  70 thread is not  currently executing on an \fBLWP\fR, the floating point and
  71 extra state registers may cannot be read or written. Some of the general
  72 registers might also not be readable or writable, depending on the
  73 architecture, in which case \fBtd_thr_getfpregs()\fR and
  74 \fBtd_thr_setfpregs()\fR return  \fBTD_NOFPREGS\fR and \fBtd_thr_getxregs()\fR
  75 and \fBtd_thr_setxregs()\fR will \fBTD_NOXREGS\fR. Calls to
  76 \fBtd_thr_getgregs()\fR and \fBtd_thr_setgregs()\fR succeed, but values
  77 returned for unreadable registers are undefined, values specified for
  78 unwritable registers are ignored. In this instance, and \fBTD_PARTIALREGS\fR is
  79 returned.  See the architecture-specific notes that follow regarding the
  80 registers that may be read and written for a thread not currently executing on
  81 an \fBLWP\fR.
  82 .SS "SPARC"
  83 .sp
  84 .LP
  85 On a thread not currently assigned to an \fBLWP\fR, only %i0-%i7, %l0-%l7, %g7,
  86 %pc, and %sp (%o6) can be read or written.  %pc and %sp refer to the program
  87 counter and stack pointer that the thread will have when it resumes execution.
  88 .SS "x86 Architecture"
  89 .sp
  90 .LP
  91 On a thread not currently assigned to an \fBLWP,\fR only %pc, %sp, %ebp, %edi,
  92 %edi, and %ebx can be read.
  93 .SH RETURN VALUES
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBTD_OK\fR\fR
  98 .ad
  99 .RS 18n

 100 The call completed successfully.
 101 .RE
 102 
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBTD_BADTH\fR\fR
 107 .ad
 108 .RS 18n
 109 An invalid thread handle was passed in.
 110 .RE
 111 
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBTD_DBERR\fR\fR
 116 .ad
 117 .RS 18n
 118 A call to one of the imported interface routines failed.
 119 .RE
 120 
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBTD_PARTIALREGS\fR\fR
 125 .ad
 126 .RS 18n
 127 Because the thread is not currently assigned to a \fBLWP,\fR not all registers
 128 were read or written. See \fBDESCRIPTION\fR for a discussion about which
 129 registers are not saved when a thread is not assigned to an \fBLWP\fR.
 130 .RE
 131 
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBTD_NOFPREGS\fR\fR
 136 .ad
 137 .RS 18n
 138 Floating point registers could not be read or written, either because the
 139 thread is not currently assigned to an \fBLWP\fR, or because the architecture
 140 does not have such registers.
 141 .RE
 142 
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBTD_NOXREGS\fR\fR
 147 .ad
 148 .RS 18n
 149 Architecture-dependent extra state registers could not be read or written,
 150 either because the thread is not currently assigned to an \fBLWP\fR, or because
 151 the architecture does not have such registers, or because the architecture is
 152 not a SPARC architecture.
 153 .RE
 154 
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBTD_ERR\fR\fR
 159 .ad
 160 .RS 18n
 161 A \fBlibc_db\fR internal error occurred.
 162 .RE
 163 
 164 .SH ATTRIBUTES
 165 .sp
 166 .LP
 167 See \fBattributes\fR(7) for description of the following attributes:
 168 .sp
 169 
 170 .sp
 171 .TS
 172 box;
 173 c | c
 174 l | l .
 175 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 176 _
 177 MT-Level        Safe
 178 .TE
 179 
 180 .SH SEE ALSO
 181 .sp
 182 .LP
 183 .BR libc_db (3LIB),
 184 .BR attributes (7)

   1 .\"
   2 .\"  Copyright (c) 1998 Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .\" Copyright 2023 Oxide Computer Company
   7 .Dd January 23, 2023
   8 .Dt TD_THR_GETGREGS 3C_DB
   9 .Os
  10 .Sh NAME
  11 .Nm td_thr_getgregs ,
  12 .Nm td_thr_setgregs ,
  13 .Nm td_thr_getfpregs ,
  14 .Nm td_thr_setfpregs ,
  15 .Nm td_thr_getxregsize ,
  16 .Nm td_thr_getxregs ,
  17 .Nm td_thr_setxregs
  18 .Nd reading and writing thread registers in libc_db
  19 .Sh LIBRARY
  20 .Lb libc_db
  21 .Sh SYNOPSIS
  22 .In proc_service.h
  23 .In thread_db.h
  24 .Ft td_err_e
  25 .Fo td_thr_getgregs
  26 .Fa "const td_thrhandle_t *th_p"
  27 .Fa "prgregset_t gregset"
  28 .Fc
  29 .Ft td_err_e
  30 .Fo td_thr_setgregs
  31 .Fa "const td_thrhandle_t *th_p"
  32 .Fa "prgregset_t gregset"
  33 .Fc
  34 .Ft td_err_e
  35 .Fo td_thr_getfpregs
  36 .Fa "const td_thrhandle_t *th_p"
  37 .Fa "prfpregset_t *fpregset"
  38 .Fc
  39 .Ft td_err_e
  40 .Fo td_thr_setfpregs
  41 .Fa "const td_thrhandle_t *th_p"
  42 .Fa "prfpregset_t *fpregset"
  43 .Fc
  44 .Ft td_err_e
  45 .Fo td_thr_getxregsize
  46 .Fa "const td_thrhandle_t *th_p"
  47 .Fa "int *xregsize"
  48 .Fc
  49 .Ft td_err_e
  50 .Fo td_thr_getxregs
  51 .Fa "const td_thrhandle_t *th_p"
  52 .Fa "prxregset_t *xregset"
  53 .Fc
  54 .Ft td_err_e
  55 .Fo td_thr_setxregs
  56 .Fa "const td_thrhandle_t *th_p"
  57 .Fa "prxregset_t *xregset"
  58 .Fc
  59 .Sh DESCRIPTION
  60 These functions read and write the register sets associated with thread
  61 .Fa th_p .
  62 The
  63 .Fn td_thr_getgregs
  64 and
  65 .Fn td_thr_setgregs
  66 functions get and set, respectively, the general registers of thread
  67 .Fa th_p .
  68 The
  69 .Fn td_thr_getfpregs
  70 and
  71 .Fn td_thr_setfpregs
  72 functions get and set, respectively, the thread's floating point register set.
  73 .Pp
  74 The
  75 .Fn td_thr_getxregsize
  76 function returns in
  77 .Fa *xregsize
  78 the size of the
  79 architecture-dependent extra state registers.
  80 The
  81 .Fn td_thr_getxregs
  82 and
  83 .Fn td_thr_setxregs
  84 functions get and set, respectively, those extra state registers.
  85 The buffer passed to
  86 .Fn td_thr_getxregs
  87 must be at least the size indicated by
  88 .Fn td_thr_getxregsize .
  89 This size must not be assumed and may change between processes.
  90 Failure to do so, will result in the system overwriting memory.
  91 Not all platforms implement extended registers.
  92 When they are not implemented, these functions return
  93 .Dv TD_NOXREGS .
  94 .Sh RETURN VALUES
  95 The
  96 .Fn td_thr_getgregs ,
  97 .Fn td_thr_setgregs ,
  98 .Fn td_thr_getfpregs ,
  99 .Fn td_thr_setfpregs ,
 100 .Fn td_thr_getxregsize ,
 101 .Fn td_thr_getxregs ,
 102 and
 103 .Fn td_thr_setxregs
 104 functions return one of the following values:
 105 .Bl -tag -width Ds
 106 .It Dv TD_OK
 107 The call completed successfully.
 108 .It Dv TD_BADTH







 109 An invalid thread handle was passed in.
 110 .It Dv TD_DBERR







 111 A call to one of the imported interface routines failed.
 112 .It Dv TD_NOFPREGS
 113 Floating point registers could not be read or written because the architecture



















 114 does not have such registers.
 115 .It Dv TD_NOXREGS







 116 Architecture-dependent extra state registers could not be read or written,
 117 because the architecture does not have such registers.
 118 .It Dv TD_ERR
 119 A
 120 .Sy libc_db
 121 internal error occurred.
 122 .El
 123 .Sh MT-LEVEL
 124 .Sy Safe
 125 .Sh SEE ALSO
 126 .Xr libc_db 3LIB ,
 127 .Xr attributes 7