usr/src/man/man3c_db/td_thr_getgregs.3c_db

   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(5) 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 \fBlibc_db\fR(3LIB), \fBattributes\fR(5)