1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Data</title> 18 19<meta name="description" content="Debugging with GDB: Data"> 20<meta name="keywords" content="Debugging with GDB: Data"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="index.html#Top" rel="up" title="Top"> 29<link href="Expressions.html#Expressions" rel="next" title="Expressions"> 30<link href="Machine-Code.html#Machine-Code" rel="previous" title="Machine Code"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Data"></a> 65<div class="header"> 66<p> 67Next: <a href="Optimized-Code.html#Optimized-Code" accesskey="n" rel="next">Optimized Code</a>, Previous: <a href="Source.html#Source" accesskey="p" rel="previous">Source</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Examining-Data"></a> 71<h2 class="chapter">10 Examining Data</h2> 72 73<a name="index-printing-data"></a> 74<a name="index-examining-data"></a> 75<a name="index-print"></a> 76<a name="index-inspect"></a> 77<p>The usual way to examine data in your program is with the <code>print</code> 78command (abbreviated <code>p</code>), or its synonym <code>inspect</code>. It 79evaluates and prints the value of an expression of the language your 80program is written in (see <a href="Languages.html#Languages">Using <small>GDB</small> with 81Different Languages</a>). It may also print the expression using a 82Python-based pretty-printer (see <a href="Pretty-Printing.html#Pretty-Printing">Pretty Printing</a>). 83</p> 84<dl compact="compact"> 85<dt><code>print [[<var>options</var>] --] <var>expr</var></code></dt> 86<dt><code>print [[<var>options</var>] --] /<var>f</var> <var>expr</var></code></dt> 87<dd><p><var>expr</var> is an expression (in the source language). By default the 88value of <var>expr</var> is printed in a format appropriate to its data type; 89you can choose a different format by specifying ‘<samp>/<var>f</var></samp>’, where 90<var>f</var> is a letter specifying the format; see <a href="Output-Formats.html#Output-Formats">Output 91Formats</a>. 92</p> 93<a name="print-options"></a><p>The <code>print</code> command supports a number of options that allow 94overriding relevant global print settings as set by <code>set print</code> 95subcommands: 96</p> 97<dl compact="compact"> 98<dt><code>-address [<code>on</code>|<code>off</code>]</code></dt> 99<dd><p>Set printing of addresses. 100Related setting: <a href="Print-Settings.html#set-print-address">set print address</a>. 101</p> 102</dd> 103<dt><code>-array [<code>on</code>|<code>off</code>]</code></dt> 104<dd><p>Pretty formatting of arrays. 105Related setting: <a href="Print-Settings.html#set-print-array">set print array</a>. 106</p> 107</dd> 108<dt><code>-array-indexes [<code>on</code>|<code>off</code>]</code></dt> 109<dd><p>Set printing of array indexes. 110Related setting: <a href="Print-Settings.html#set-print-array_002dindexes">set print array-indexes</a>. 111</p> 112</dd> 113<dt><code>-elements <var>number-of-elements</var>|<code>unlimited</code></code></dt> 114<dd><p>Set limit on string chars or array elements to print. The value 115<code>unlimited</code> causes there to be no limit. Related setting: 116<a href="Print-Settings.html#set-print-elements">set print elements</a>. 117</p> 118</dd> 119<dt><code>-max-depth <var>depth</var>|<code>unlimited</code></code></dt> 120<dd><p>Set the threshold after which nested structures are replaced with 121ellipsis. Related setting: <a href="Print-Settings.html#set-print-max_002ddepth">set print max-depth</a>. 122</p> 123</dd> 124<dt><code>-null-stop [<code>on</code>|<code>off</code>]</code></dt> 125<dd><p>Set printing of char arrays to stop at first null char. Related 126setting: <a href="Print-Settings.html#set-print-null_002dstop">set print null-stop</a>. 127</p> 128</dd> 129<dt><code>-object [<code>on</code>|<code>off</code>]</code></dt> 130<dd><p>Set printing C<tt>++</tt> virtual function tables. Related setting: 131<a href="Print-Settings.html#set-print-object">set print object</a>. 132</p> 133</dd> 134<dt><code>-pretty [<code>on</code>|<code>off</code>]</code></dt> 135<dd><p>Set pretty formatting of structures. Related setting: <a href="Print-Settings.html#set-print-pretty">set print pretty</a>. 136</p> 137</dd> 138<dt><code>-raw-values [<code>on</code>|<code>off</code>]</code></dt> 139<dd><p>Set whether to print values in raw form, bypassing any 140pretty-printers for that value. Related setting: <a href="Print-Settings.html#set-print-raw_002dvalues">set print raw-values</a>. 141</p> 142</dd> 143<dt><code>-repeats <var>number-of-repeats</var>|<code>unlimited</code></code></dt> 144<dd><p>Set threshold for repeated print elements. <code>unlimited</code> causes 145all elements to be individually printed. Related setting: <a href="Print-Settings.html#set-print-repeats">set print repeats</a>. 146</p> 147</dd> 148<dt><code>-static-members [<code>on</code>|<code>off</code>]</code></dt> 149<dd><p>Set printing C<tt>++</tt> static members. Related setting: <a href="Print-Settings.html#set-print-static_002dmembers">set print static-members</a>. 150</p> 151</dd> 152<dt><code>-symbol [<code>on</code>|<code>off</code>]</code></dt> 153<dd><p>Set printing of symbol names when printing pointers. Related setting: 154<a href="Print-Settings.html#set-print-symbol">set print symbol</a>. 155</p> 156</dd> 157<dt><code>-union [<code>on</code>|<code>off</code>]</code></dt> 158<dd><p>Set printing of unions interior to structures. Related setting: 159<a href="Print-Settings.html#set-print-union">set print union</a>. 160</p> 161</dd> 162<dt><code>-vtbl [<code>on</code>|<code>off</code>]</code></dt> 163<dd><p>Set printing of C++ virtual function tables. Related setting: 164<a href="Print-Settings.html#set-print-vtbl">set print vtbl</a>. 165</p></dd> 166</dl> 167 168<p>Because the <code>print</code> command accepts arbitrary expressions which 169may look like options (including abbreviations), if you specify any 170command option, then you must use a double dash (<code>--</code>) to mark 171the end of option processing. 172</p> 173<p>For example, this prints the value of the <code>-p</code> expression: 174</p> 175<div class="smallexample"> 176<pre class="smallexample">(gdb) print -p 177</pre></div> 178 179<p>While this repeats the last value in the value history (see below) 180with the <code>-pretty</code> option in effect: 181</p> 182<div class="smallexample"> 183<pre class="smallexample">(gdb) print -p -- 184</pre></div> 185 186<p>Here is an example including both on option and an expression: 187</p> 188<div class="smallexample"> 189<pre class="smallexample">(gdb) print -pretty -- *myptr 190$1 = { 191 next = 0x0, 192 flags = { 193 sweet = 1, 194 sour = 1 195 }, 196 meat = 0x54 "Pork" 197} 198</pre></div> 199 200</dd> 201<dt><code>print [<var>options</var>]</code></dt> 202<dt><code>print [<var>options</var>] /<var>f</var></code></dt> 203<dd><a name="index-reprint-the-last-value"></a> 204<p>If you omit <var>expr</var>, <small>GDB</small> displays the last value again (from the 205<em>value history</em>; see <a href="Value-History.html#Value-History">Value History</a>). This allows you to 206conveniently inspect the same value in an alternative format. 207</p></dd> 208</dl> 209 210<p>A more low-level way of examining data is with the <code>x</code> command. 211It examines data in memory at a specified address and prints it in a 212specified format. See <a href="Memory.html#Memory">Examining Memory</a>. 213</p> 214<p>If you are interested in information about types, or about how the 215fields of a struct or a class are declared, use the <code>ptype <var>exp</var></code> 216command rather than <code>print</code>. See <a href="Symbols.html#Symbols">Examining the Symbol 217Table</a>. 218</p> 219<a name="index-exploring-hierarchical-data-structures"></a> 220<a name="index-explore"></a> 221<p>Another way of examining values of expressions and type information is 222through the Python extension command <code>explore</code> (available only if 223the <small>GDB</small> build is configured with <code>--with-python</code>). It 224offers an interactive way to start at the highest level (or, the most 225abstract level) of the data type of an expression (or, the data type 226itself) and explore all the way down to leaf scalar values/fields 227embedded in the higher level data types. 228</p> 229<dl compact="compact"> 230<dt><code>explore <var>arg</var></code></dt> 231<dd><p><var>arg</var> is either an expression (in the source language), or a type 232visible in the current context of the program being debugged. 233</p></dd> 234</dl> 235 236<p>The working of the <code>explore</code> command can be illustrated with an 237example. If a data type <code>struct ComplexStruct</code> is defined in your 238C program as 239</p> 240<div class="smallexample"> 241<pre class="smallexample">struct SimpleStruct 242{ 243 int i; 244 double d; 245}; 246 247struct ComplexStruct 248{ 249 struct SimpleStruct *ss_p; 250 int arr[10]; 251}; 252</pre></div> 253 254<p>followed by variable declarations as 255</p> 256<div class="smallexample"> 257<pre class="smallexample">struct SimpleStruct ss = { 10, 1.11 }; 258struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } }; 259</pre></div> 260 261<p>then, the value of the variable <code>cs</code> can be explored using the 262<code>explore</code> command as follows. 263</p> 264<div class="smallexample"> 265<pre class="smallexample">(gdb) explore cs 266The value of `cs' is a struct/class of type `struct ComplexStruct' with 267the following fields: 268 269 ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'> 270 arr = <Enter 1 to explore this field of type `int [10]'> 271 272Enter the field number of choice: 273</pre></div> 274 275<p>Since the fields of <code>cs</code> are not scalar values, you are being 276prompted to chose the field you want to explore. Let’s say you choose 277the field <code>ss_p</code> by entering <code>0</code>. Then, since this field is a 278pointer, you will be asked if it is pointing to a single value. From 279the declaration of <code>cs</code> above, it is indeed pointing to a single 280value, hence you enter <code>y</code>. If you enter <code>n</code>, then you will 281be asked if it were pointing to an array of values, in which case this 282field will be explored as if it were an array. 283</p> 284<div class="smallexample"> 285<pre class="smallexample">`cs.ss_p' is a pointer to a value of type `struct SimpleStruct' 286Continue exploring it as a pointer to a single value [y/n]: y 287The value of `*(cs.ss_p)' is a struct/class of type `struct 288SimpleStruct' with the following fields: 289 290 i = 10 .. (Value of type `int') 291 d = 1.1100000000000001 .. (Value of type `double') 292 293Press enter to return to parent value: 294</pre></div> 295 296<p>If the field <code>arr</code> of <code>cs</code> was chosen for exploration by 297entering <code>1</code> earlier, then since it is as array, you will be 298prompted to enter the index of the element in the array that you want 299to explore. 300</p> 301<div class="smallexample"> 302<pre class="smallexample">`cs.arr' is an array of `int'. 303Enter the index of the element you want to explore in `cs.arr': 5 304 305`(cs.arr)[5]' is a scalar value of type `int'. 306 307(cs.arr)[5] = 4 308 309Press enter to return to parent value: 310</pre></div> 311 312<p>In general, at any stage of exploration, you can go deeper towards the 313leaf values by responding to the prompts appropriately, or hit the 314return key to return to the enclosing data structure (the <i>higher</i> 315level data structure). 316</p> 317<p>Similar to exploring values, you can use the <code>explore</code> command to 318explore types. Instead of specifying a value (which is typically a 319variable name or an expression valid in the current context of the 320program being debugged), you specify a type name. If you consider the 321same example as above, your can explore the type 322<code>struct ComplexStruct</code> by passing the argument 323<code>struct ComplexStruct</code> to the <code>explore</code> command. 324</p> 325<div class="smallexample"> 326<pre class="smallexample">(gdb) explore struct ComplexStruct 327</pre></div> 328 329<p>By responding to the prompts appropriately in the subsequent interactive 330session, you can explore the type <code>struct ComplexStruct</code> in a 331manner similar to how the value <code>cs</code> was explored in the above 332example. 333</p> 334<p>The <code>explore</code> command also has two sub-commands, 335<code>explore value</code> and <code>explore type</code>. The former sub-command is 336a way to explicitly specify that value exploration of the argument is 337being invoked, while the latter is a way to explicitly specify that type 338exploration of the argument is being invoked. 339</p> 340<dl compact="compact"> 341<dt><code>explore value <var>expr</var></code></dt> 342<dd><a name="index-explore-value"></a> 343<p>This sub-command of <code>explore</code> explores the value of the 344expression <var>expr</var> (if <var>expr</var> is an expression valid in the 345current context of the program being debugged). The behavior of this 346command is identical to that of the behavior of the <code>explore</code> 347command being passed the argument <var>expr</var>. 348</p> 349</dd> 350<dt><code>explore type <var>arg</var></code></dt> 351<dd><a name="index-explore-type"></a> 352<p>This sub-command of <code>explore</code> explores the type of <var>arg</var> (if 353<var>arg</var> is a type visible in the current context of program being 354debugged), or the type of the value/expression <var>arg</var> (if <var>arg</var> 355is an expression valid in the current context of the program being 356debugged). If <var>arg</var> is a type, then the behavior of this command is 357identical to that of the <code>explore</code> command being passed the 358argument <var>arg</var>. If <var>arg</var> is an expression, then the behavior of 359this command will be identical to that of the <code>explore</code> command 360being passed the type of <var>arg</var> as the argument. 361</p></dd> 362</dl> 363 364<table class="menu" border="0" cellspacing="0"> 365<tr><td align="left" valign="top">• <a href="Expressions.html#Expressions" accesskey="1">Expressions</a>:</td><td> </td><td align="left" valign="top">Expressions 366</td></tr> 367<tr><td align="left" valign="top">• <a href="Ambiguous-Expressions.html#Ambiguous-Expressions" accesskey="2">Ambiguous Expressions</a>:</td><td> </td><td align="left" valign="top">Ambiguous Expressions 368</td></tr> 369<tr><td align="left" valign="top">• <a href="Variables.html#Variables" accesskey="3">Variables</a>:</td><td> </td><td align="left" valign="top">Program variables 370</td></tr> 371<tr><td align="left" valign="top">• <a href="Arrays.html#Arrays" accesskey="4">Arrays</a>:</td><td> </td><td align="left" valign="top">Artificial arrays 372</td></tr> 373<tr><td align="left" valign="top">• <a href="Output-Formats.html#Output-Formats" accesskey="5">Output Formats</a>:</td><td> </td><td align="left" valign="top">Output formats 374</td></tr> 375<tr><td align="left" valign="top">• <a href="Memory.html#Memory" accesskey="6">Memory</a>:</td><td> </td><td align="left" valign="top">Examining memory 376</td></tr> 377<tr><td align="left" valign="top">• <a href="Auto-Display.html#Auto-Display" accesskey="7">Auto Display</a>:</td><td> </td><td align="left" valign="top">Automatic display 378</td></tr> 379<tr><td align="left" valign="top">• <a href="Print-Settings.html#Print-Settings" accesskey="8">Print Settings</a>:</td><td> </td><td align="left" valign="top">Print settings 380</td></tr> 381<tr><td align="left" valign="top">• <a href="Pretty-Printing.html#Pretty-Printing" accesskey="9">Pretty Printing</a>:</td><td> </td><td align="left" valign="top">Python pretty printing 382</td></tr> 383<tr><td align="left" valign="top">• <a href="Value-History.html#Value-History">Value History</a>:</td><td> </td><td align="left" valign="top">Value history 384</td></tr> 385<tr><td align="left" valign="top">• <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>:</td><td> </td><td align="left" valign="top">Convenience variables 386</td></tr> 387<tr><td align="left" valign="top">• <a href="Convenience-Funs.html#Convenience-Funs">Convenience Funs</a>:</td><td> </td><td align="left" valign="top">Convenience functions 388</td></tr> 389<tr><td align="left" valign="top">• <a href="Registers.html#Registers">Registers</a>:</td><td> </td><td align="left" valign="top">Registers 390</td></tr> 391<tr><td align="left" valign="top">• <a href="Floating-Point-Hardware.html#Floating-Point-Hardware">Floating Point Hardware</a>:</td><td> </td><td align="left" valign="top">Floating point hardware 392</td></tr> 393<tr><td align="left" valign="top">• <a href="Vector-Unit.html#Vector-Unit">Vector Unit</a>:</td><td> </td><td align="left" valign="top">Vector Unit 394</td></tr> 395<tr><td align="left" valign="top">• <a href="OS-Information.html#OS-Information">OS Information</a>:</td><td> </td><td align="left" valign="top">Auxiliary data provided by operating system 396</td></tr> 397<tr><td align="left" valign="top">• <a href="Memory-Region-Attributes.html#Memory-Region-Attributes">Memory Region Attributes</a>:</td><td> </td><td align="left" valign="top">Memory region attributes 398</td></tr> 399<tr><td align="left" valign="top">• <a href="Dump_002fRestore-Files.html#Dump_002fRestore-Files">Dump/Restore Files</a>:</td><td> </td><td align="left" valign="top">Copy between memory and a file 400</td></tr> 401<tr><td align="left" valign="top">• <a href="Core-File-Generation.html#Core-File-Generation">Core File Generation</a>:</td><td> </td><td align="left" valign="top">Cause a program dump its core 402</td></tr> 403<tr><td align="left" valign="top">• <a href="Character-Sets.html#Character-Sets">Character Sets</a>:</td><td> </td><td align="left" valign="top">Debugging programs that use a different 404 character set than GDB does 405</td></tr> 406<tr><td align="left" valign="top">• <a href="Caching-Target-Data.html#Caching-Target-Data">Caching Target Data</a>:</td><td> </td><td align="left" valign="top">Data caching for targets 407</td></tr> 408<tr><td align="left" valign="top">• <a href="Searching-Memory.html#Searching-Memory">Searching Memory</a>:</td><td> </td><td align="left" valign="top">Searching memory for a sequence of bytes 409</td></tr> 410<tr><td align="left" valign="top">• <a href="Value-Sizes.html#Value-Sizes">Value Sizes</a>:</td><td> </td><td align="left" valign="top">Managing memory allocated for values 411</td></tr> 412</table> 413 414<hr> 415<div class="header"> 416<p> 417Next: <a href="Optimized-Code.html#Optimized-Code" accesskey="n" rel="next">Optimized Code</a>, Previous: <a href="Source.html#Source" accesskey="p" rel="previous">Source</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 418</div> 419 420 421 422</body> 423</html> 424