10 Examining Data

The usual way to examine data in your program is with the print command (abbreviated p), or its synonym inspect. It evaluates and prints the value of an expression of the language your program is written in (see Using GDB with Different Languages). It may also print the expression using a Python-based pretty-printer (see Pretty Printing).

print [[options] --] expr

print [[options] --] /f expr

expr is an expression (in the source language). By default the value of expr is printed in a format appropriate to its data type; you can choose a different format by specifying ‘/f’, where f is a letter specifying the format; see Output Formats.

The print command supports a number of options that allow overriding relevant global print settings as set by set print subcommands:

-address [on|off]

Set printing of addresses. Related setting: set print address.

-array [on|off]

Pretty formatting of arrays. Related setting: set print array.

-array-indexes [on|off]

Set printing of array indexes. Related setting: set print array-indexes.

-elements number-of-elements|unlimited

Set limit on string chars or array elements to print. The value unlimited causes there to be no limit. Related setting: set print elements.

-max-depth depth|unlimited

Set the threshold after which nested structures are replaced with ellipsis. Related setting: set print max-depth.

-null-stop [on|off]

Set printing of char arrays to stop at first null char. Related setting: set print null-stop.

-object [on|off]

Set printing C++ virtual function tables. Related setting: set print object.

-pretty [on|off]

Set pretty formatting of structures. Related setting: set print pretty.

-raw-values [on|off]

Set whether to print values in raw form, bypassing any pretty-printers for that value. Related setting: set print raw-values.

-repeats number-of-repeats|unlimited

Set threshold for repeated print elements. unlimited causes all elements to be individually printed. Related setting: set print repeats.

-static-members [on|off]

Set printing C++ static members. Related setting: set print static-members.

-symbol [on|off]

Set printing of symbol names when printing pointers. Related setting: set print symbol.

-union [on|off]

Set printing of unions interior to structures. Related setting: set print union.

-vtbl [on|off]

Set printing of C++ virtual function tables. Related setting: set print vtbl.

Because the print command accepts arbitrary expressions which may look like options (including abbreviations), if you specify any command option, then you must use a double dash (--) to mark the end of option processing.

For example, this prints the value of the -p expression:

(gdb) print -p

While this repeats the last value in the value history (see below) with the -pretty option in effect:

(gdb) print -p --

Here is an example including both on option and an expression:

(gdb) print -pretty -- *myptr
$1 = {
  next = 0x0,
  flags = {
    sweet = 1,
    sour = 1
  },
  meat = 0x54 "Pork"
}

print [options]

print [options] /f

If you omit expr, GDB displays the last value again (from the value history; see Value History). This allows you to conveniently inspect the same value in an alternative format.

A more low-level way of examining data is with the x command. It examines data in memory at a specified address and prints it in a specified format. See Examining Memory.

If you are interested in information about types, or about how the fields of a struct or a class are declared, use the ptype exp command rather than print. See Examining the Symbol Table.

Another way of examining values of expressions and type information is through the Python extension command explore (available only if the GDB build is configured with --with-python). It offers an interactive way to start at the highest level (or, the most abstract level) of the data type of an expression (or, the data type itself) and explore all the way down to leaf scalar values/fields embedded in the higher level data types.

explore arg

arg is either an expression (in the source language), or a type visible in the current context of the program being debugged.

The working of the explore command can be illustrated with an example. If a data type struct ComplexStruct is defined in your C program as

struct SimpleStruct
{
  int i;
  double d;
};

struct ComplexStruct
{
  struct SimpleStruct *ss_p;
  int arr[10];
};

followed by variable declarations as

struct SimpleStruct ss = { 10, 1.11 };
struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } };

then, the value of the variable cs can be explored using the explore command as follows.

(gdb) explore cs
The value of `cs' is a struct/class of type `struct ComplexStruct' with
the following fields:

  ss_p = <Enter 0 to explore this field of type `struct SimpleStruct *'>
   arr = <Enter 1 to explore this field of type `int [10]'>

Enter the field number of choice:

Since the fields of cs are not scalar values, you are being prompted to chose the field you want to explore. Let’s say you choose the field ss_p by entering 0. Then, since this field is a pointer, you will be asked if it is pointing to a single value. From the declaration of cs above, it is indeed pointing to a single value, hence you enter y. If you enter n, then you will be asked if it were pointing to an array of values, in which case this field will be explored as if it were an array.

`cs.ss_p' is a pointer to a value of type `struct SimpleStruct'
Continue exploring it as a pointer to a single value [y/n]: y
The value of `*(cs.ss_p)' is a struct/class of type `struct
SimpleStruct' with the following fields:

  i = 10 .. (Value of type `int')
  d = 1.1100000000000001 .. (Value of type `double')

Press enter to return to parent value:

If the field arr of cs was chosen for exploration by entering 1 earlier, then since it is as array, you will be prompted to enter the index of the element in the array that you want to explore.

`cs.arr' is an array of `int'.
Enter the index of the element you want to explore in `cs.arr': 5

`(cs.arr)[5]' is a scalar value of type `int'.

(cs.arr)[5] = 4

Press enter to return to parent value: 

In general, at any stage of exploration, you can go deeper towards the leaf values by responding to the prompts appropriately, or hit the return key to return to the enclosing data structure (the higher level data structure).

Similar to exploring values, you can use the explore command to explore types. Instead of specifying a value (which is typically a variable name or an expression valid in the current context of the program being debugged), you specify a type name. If you consider the same example as above, your can explore the type struct ComplexStruct by passing the argument struct ComplexStruct to the explore command.

(gdb) explore struct ComplexStruct

By responding to the prompts appropriately in the subsequent interactive session, you can explore the type struct ComplexStruct in a manner similar to how the value cs was explored in the above example.

The explore command also has two sub-commands, explore value and explore type. The former sub-command is a way to explicitly specify that value exploration of the argument is being invoked, while the latter is a way to explicitly specify that type exploration of the argument is being invoked.

explore value expr

This sub-command of explore explores the value of the expression expr (if expr is an expression valid in the current context of the program being debugged). The behavior of this command is identical to that of the behavior of the explore command being passed the argument expr.

explore type arg

This sub-command of explore explores the type of arg (if arg is a type visible in the current context of program being debugged), or the type of the value/expression arg (if arg is an expression valid in the current context of the program being debugged). If arg is a type, then the behavior of this command is identical to that of the explore command being passed the argument arg. If arg is an expression, then the behavior of this command will be identical to that of the explore command being passed the type of arg as the argument.