1<html lang="en"> 2<head> 3<title>Values From Inferior - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Python-API.html#Python-API" title="Python API"> 9<link rel="prev" href="Exception-Handling.html#Exception-Handling" title="Exception Handling"> 10<link rel="next" href="Types-In-Python.html#Types-In-Python" title="Types In Python"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Free Software'' and ``Free Software Needs 19Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 20and with the Back-Cover Texts as in (a) below. 21 22(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 23this GNU Manual. Buying copies from GNU Press supports the FSF in 24developing GNU and promoting software freedom.'' 25--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Values-From-Inferior"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Types-In-Python.html#Types-In-Python">Types In Python</a>, 45Previous: <a rel="previous" accesskey="p" href="Exception-Handling.html#Exception-Handling">Exception Handling</a>, 46Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 47<hr> 48</div> 49 50<h5 class="subsubsection">23.2.2.3 Values From Inferior</h5> 51 52<p><a name="index-values-from-inferior_002c-with-Python-1781"></a><a name="index-python_002c-working-with-values-from-inferior-1782"></a> 53<a name="index-g_t_0040code_007bgdb_002eValue_007d-1783"></a><span class="sc">gdb</span> provides values it obtains from the inferior program in 54an object of type <code>gdb.Value</code>. <span class="sc">gdb</span> uses this object 55for its internal bookkeeping of the inferior's values, and for 56fetching values when necessary. 57 58 <p>Inferior values that are simple scalars can be used directly in 59Python expressions that are valid for the value's data type. Here's 60an example for an integer or floating-point value <code>some_val</code>: 61 62<pre class="smallexample"> bar = some_val + 2 63</pre> 64 <p class="noindent">As result of this, <code>bar</code> will also be a <code>gdb.Value</code> object 65whose values are of the same type as those of <code>some_val</code>. 66 67 <p>Inferior values that are structures or instances of some class can 68be accessed using the Python <dfn>dictionary syntax</dfn>. For example, if 69<code>some_val</code> is a <code>gdb.Value</code> instance holding a structure, you 70can access its <code>foo</code> element with: 71 72<pre class="smallexample"> bar = some_val['foo'] 73</pre> 74 <p>Again, <code>bar</code> will also be a <code>gdb.Value</code> object. 75 76 <p>A <code>gdb.Value</code> that represents a function can be executed via 77inferior function call. Any arguments provided to the call must match 78the function's prototype, and must be provided in the order specified 79by that prototype. 80 81 <p>For example, <code>some_val</code> is a <code>gdb.Value</code> instance 82representing a function that takes two integers as arguments. To 83execute this function, call it like so: 84 85<pre class="smallexample"> result = some_val (10,20) 86</pre> 87 <p>Any values returned from a function call will be stored as a 88<code>gdb.Value</code>. 89 90 <p>The following attributes are provided: 91 92<div class="defun"> 93— Variable: <b>Value.address</b><var><a name="index-Value_002eaddress-1784"></a></var><br> 94<blockquote><p>If this object is addressable, this read-only attribute holds a 95<code>gdb.Value</code> object representing the address. Otherwise, 96this attribute holds <code>None</code>. 97</p></blockquote></div> 98 99 <p><a name="index-optimized-out-value-in-Python-1785"></a> 100 101<div class="defun"> 102— Variable: <b>Value.is_optimized_out</b><var><a name="index-Value_002eis_005foptimized_005fout-1786"></a></var><br> 103<blockquote><p>This read-only boolean attribute is true if the compiler optimized out 104this value, thus it is not available for fetching from the inferior. 105</p></blockquote></div> 106 107<div class="defun"> 108— Variable: <b>Value.type</b><var><a name="index-Value_002etype-1787"></a></var><br> 109<blockquote><p>The type of this <code>gdb.Value</code>. The value of this attribute is a 110<code>gdb.Type</code> object (see <a href="Types-In-Python.html#Types-In-Python">Types In Python</a>). 111</p></blockquote></div> 112 113<div class="defun"> 114— Variable: <b>Value.dynamic_type</b><var><a name="index-Value_002edynamic_005ftype-1788"></a></var><br> 115<blockquote><p>The dynamic type of this <code>gdb.Value</code>. This uses C<tt>++</tt> run-time 116type information (<acronym>RTTI</acronym>) to determine the dynamic type of the 117value. If this value is of class type, it will return the class in 118which the value is embedded, if any. If this value is of pointer or 119reference to a class type, it will compute the dynamic type of the 120referenced object, and return a pointer or reference to that type, 121respectively. In all other cases, it will return the value's static 122type. 123 124 <p>Note that this feature will only work when debugging a C<tt>++</tt> program 125that includes <acronym>RTTI</acronym> for the object in question. Otherwise, 126it will just return the static type of the value as in <kbd>ptype foo</kbd> 127(see <a href="Symbols.html#Symbols">ptype</a>). 128</p></blockquote></div> 129 130<div class="defun"> 131— Variable: <b>Value.is_lazy</b><var><a name="index-Value_002eis_005flazy-1789"></a></var><br> 132<blockquote><p>The value of this read-only boolean attribute is <code>True</code> if this 133<code>gdb.Value</code> has not yet been fetched from the inferior. 134<span class="sc">gdb</span> does not fetch values until necessary, for efficiency. 135For example: 136 137 <pre class="smallexample"> myval = gdb.parse_and_eval ('somevar') 138</pre> 139 <p>The value of <code>somevar</code> is not fetched at this time. It will be 140fetched when the value is needed, or when the <code>fetch_lazy</code> 141method is invoked. 142</p></blockquote></div> 143 144 <p>The following methods are provided: 145 146<div class="defun"> 147— Function: <b>Value.__init__</b> (<var>val</var>)<var><a name="index-Value_002e_005f_005finit_005f_005f-1790"></a></var><br> 148<blockquote><p>Many Python values can be converted directly to a <code>gdb.Value</code> via 149this object initializer. Specifically: 150 151 <dl> 152<dt>Python boolean<dd>A Python boolean is converted to the boolean type from the current 153language. 154 155 <br><dt>Python integer<dd>A Python integer is converted to the C <code>long</code> type for the 156current architecture. 157 158 <br><dt>Python long<dd>A Python long is converted to the C <code>long long</code> type for the 159current architecture. 160 161 <br><dt>Python float<dd>A Python float is converted to the C <code>double</code> type for the 162current architecture. 163 164 <br><dt>Python string<dd>A Python string is converted to a target string, using the current 165target encoding. 166 167 <br><dt><code>gdb.Value</code><dd>If <code>val</code> is a <code>gdb.Value</code>, then a copy of the value is made. 168 169 <br><dt><code>gdb.LazyString</code><dd>If <code>val</code> is a <code>gdb.LazyString</code> (see <a href="Lazy-Strings-In-Python.html#Lazy-Strings-In-Python">Lazy Strings In Python</a>), then the lazy string's <code>value</code> method is called, and 170its result is used. 171</dl> 172 </p></blockquote></div> 173 174<div class="defun"> 175— Function: <b>Value.cast</b> (<var>type</var>)<var><a name="index-Value_002ecast-1791"></a></var><br> 176<blockquote><p>Return a new instance of <code>gdb.Value</code> that is the result of 177casting this instance to the type described by <var>type</var>, which must 178be a <code>gdb.Type</code> object. If the cast cannot be performed for some 179reason, this method throws an exception. 180</p></blockquote></div> 181 182<div class="defun"> 183— Function: <b>Value.dereference</b> ()<var><a name="index-Value_002edereference-1792"></a></var><br> 184<blockquote><p>For pointer data types, this method returns a new <code>gdb.Value</code> object 185whose contents is the object pointed to by the pointer. For example, if 186<code>foo</code> is a C pointer to an <code>int</code>, declared in your C program as 187 188 <pre class="smallexample"> int *foo; 189</pre> 190 <p class="noindent">then you can use the corresponding <code>gdb.Value</code> to access what 191<code>foo</code> points to like this: 192 193 <pre class="smallexample"> bar = foo.dereference () 194</pre> 195 <p>The result <code>bar</code> will be a <code>gdb.Value</code> object holding the 196value pointed to by <code>foo</code>. 197 198 <p>A similar function <code>Value.referenced_value</code> exists which also 199returns <code>gdb.Value</code> objects corresonding to the values pointed to 200by pointer values (and additionally, values referenced by reference 201values). However, the behavior of <code>Value.dereference</code> 202differs from <code>Value.referenced_value</code> by the fact that the 203behavior of <code>Value.dereference</code> is identical to applying the C 204unary operator <code>*</code> on a given value. For example, consider a 205reference to a pointer <code>ptrref</code>, declared in your C<tt>++</tt> program 206as 207 208 <pre class="smallexample"> typedef int *intptr; 209 ... 210 int val = 10; 211 intptr ptr = &val; 212 intptr &ptrref = ptr; 213</pre> 214 <p>Though <code>ptrref</code> is a reference value, one can apply the method 215<code>Value.dereference</code> to the <code>gdb.Value</code> object corresponding 216to it and obtain a <code>gdb.Value</code> which is identical to that 217corresponding to <code>val</code>. However, if you apply the method 218<code>Value.referenced_value</code>, the result would be a <code>gdb.Value</code> 219object identical to that corresponding to <code>ptr</code>. 220 221 <pre class="smallexample"> py_ptrref = gdb.parse_and_eval ("ptrref") 222 py_val = py_ptrref.dereference () 223 py_ptr = py_ptrref.referenced_value () 224</pre> 225 <p>The <code>gdb.Value</code> object <code>py_val</code> is identical to that 226corresponding to <code>val</code>, and <code>py_ptr</code> is identical to that 227corresponding to <code>ptr</code>. In general, <code>Value.dereference</code> can 228be applied whenever the C unary operator <code>*</code> can be applied 229to the corresponding C value. For those cases where applying both 230<code>Value.dereference</code> and <code>Value.referenced_value</code> is allowed, 231the results obtained need not be identical (as we have seen in the above 232example). The results are however identical when applied on 233<code>gdb.Value</code> objects corresponding to pointers (<code>gdb.Value</code> 234objects with type code <code>TYPE_CODE_PTR</code>) in a C/C<tt>++</tt> program. 235</p></blockquote></div> 236 237<div class="defun"> 238— Function: <b>Value.referenced_value</b> ()<var><a name="index-Value_002ereferenced_005fvalue-1793"></a></var><br> 239<blockquote><p>For pointer or reference data types, this method returns a new 240<code>gdb.Value</code> object corresponding to the value referenced by the 241pointer/reference value. For pointer data types, 242<code>Value.dereference</code> and <code>Value.referenced_value</code> produce 243identical results. The difference between these methods is that 244<code>Value.dereference</code> cannot get the values referenced by reference 245values. For example, consider a reference to an <code>int</code>, declared 246in your C<tt>++</tt> program as 247 248 <pre class="smallexample"> int val = 10; 249 int &ref = val; 250</pre> 251 <p class="noindent">then applying <code>Value.dereference</code> to the <code>gdb.Value</code> object 252corresponding to <code>ref</code> will result in an error, while applying 253<code>Value.referenced_value</code> will result in a <code>gdb.Value</code> object 254identical to that corresponding to <code>val</code>. 255 256 <pre class="smallexample"> py_ref = gdb.parse_and_eval ("ref") 257 er_ref = py_ref.dereference () # Results in error 258 py_val = py_ref.referenced_value () # Returns the referenced value 259</pre> 260 <p>The <code>gdb.Value</code> object <code>py_val</code> is identical to that 261corresponding to <code>val</code>. 262</p></blockquote></div> 263 264<div class="defun"> 265— Function: <b>Value.dynamic_cast</b> (<var>type</var>)<var><a name="index-Value_002edynamic_005fcast-1794"></a></var><br> 266<blockquote><p>Like <code>Value.cast</code>, but works as if the C<tt>++</tt> <code>dynamic_cast</code> 267operator were used. Consult a C<tt>++</tt> reference for details. 268</p></blockquote></div> 269 270<div class="defun"> 271— Function: <b>Value.reinterpret_cast</b> (<var>type</var>)<var><a name="index-Value_002ereinterpret_005fcast-1795"></a></var><br> 272<blockquote><p>Like <code>Value.cast</code>, but works as if the C<tt>++</tt> <code>reinterpret_cast</code> 273operator were used. Consult a C<tt>++</tt> reference for details. 274</p></blockquote></div> 275 276<div class="defun"> 277— Function: <b>Value.string</b> (<span class="roman">[</span><var>encoding</var><span class="roman">[</span><var>, errors</var><span class="roman">[</span><var>, length</var><span class="roman">]]]</span>)<var><a name="index-Value_002estring-1796"></a></var><br> 278<blockquote><p>If this <code>gdb.Value</code> represents a string, then this method 279converts the contents to a Python string. Otherwise, this method will 280throw an exception. 281 282 <p>Strings are recognized in a language-specific way; whether a given 283<code>gdb.Value</code> represents a string is determined by the current 284language. 285 286 <p>For C-like languages, a value is a string if it is a pointer to or an 287array of characters or ints. The string is assumed to be terminated 288by a zero of the appropriate width. However if the optional length 289argument is given, the string will be converted to that given length, 290ignoring any embedded zeros that the string may contain. 291 292 <p>If the optional <var>encoding</var> argument is given, it must be a string 293naming the encoding of the string in the <code>gdb.Value</code>, such as 294<code>"ascii"</code>, <code>"iso-8859-6"</code> or <code>"utf-8"</code>. It accepts 295the same encodings as the corresponding argument to Python's 296<code>string.decode</code> method, and the Python codec machinery will be used 297to convert the string. If <var>encoding</var> is not given, or if 298<var>encoding</var> is the empty string, then either the <code>target-charset</code> 299(see <a href="Character-Sets.html#Character-Sets">Character Sets</a>) will be used, or a language-specific encoding 300will be used, if the current language is able to supply one. 301 302 <p>The optional <var>errors</var> argument is the same as the corresponding 303argument to Python's <code>string.decode</code> method. 304 305 <p>If the optional <var>length</var> argument is given, the string will be 306fetched and converted to the given length. 307</p></blockquote></div> 308 309<div class="defun"> 310— Function: <b>Value.lazy_string</b> (<span class="roman">[</span><var>encoding </var><span class="roman">[</span><var>, length</var><span class="roman">]]</span>)<var><a name="index-Value_002elazy_005fstring-1797"></a></var><br> 311<blockquote><p>If this <code>gdb.Value</code> represents a string, then this method 312converts the contents to a <code>gdb.LazyString</code> (see <a href="Lazy-Strings-In-Python.html#Lazy-Strings-In-Python">Lazy Strings In Python</a>). Otherwise, this method will throw an exception. 313 314 <p>If the optional <var>encoding</var> argument is given, it must be a string 315naming the encoding of the <code>gdb.LazyString</code>. Some examples are: 316‘<samp><span class="samp">ascii</span></samp>’, ‘<samp><span class="samp">iso-8859-6</span></samp>’ or ‘<samp><span class="samp">utf-8</span></samp>’. If the 317<var>encoding</var> argument is an encoding that <span class="sc">gdb</span> does 318recognize, <span class="sc">gdb</span> will raise an error. 319 320 <p>When a lazy string is printed, the <span class="sc">gdb</span> encoding machinery is 321used to convert the string during printing. If the optional 322<var>encoding</var> argument is not provided, or is an empty string, 323<span class="sc">gdb</span> will automatically select the encoding most suitable for 324the string type. For further information on encoding in <span class="sc">gdb</span> 325please see <a href="Character-Sets.html#Character-Sets">Character Sets</a>. 326 327 <p>If the optional <var>length</var> argument is given, the string will be 328fetched and encoded to the length of characters specified. If 329the <var>length</var> argument is not provided, the string will be fetched 330and encoded until a null of appropriate width is found. 331</p></blockquote></div> 332 333<div class="defun"> 334— Function: <b>Value.fetch_lazy</b> ()<var><a name="index-Value_002efetch_005flazy-1798"></a></var><br> 335<blockquote><p>If the <code>gdb.Value</code> object is currently a lazy value 336(<code>gdb.Value.is_lazy</code> is <code>True</code>), then the value is 337fetched from the inferior. Any errors that occur in the process 338will produce a Python exception. 339 340 <p>If the <code>gdb.Value</code> object is not a lazy value, this method 341has no effect. 342 343 <p>This method does not return a value. 344</p></blockquote></div> 345 346 </body></html> 347 348