Go to the previous, next section.

Examining Data

The usual way to examine data in your program is with the print command (abbreviated p), or its synonym inspect. _if__(!_CONLY__) It evaluates and prints the value of an expression of the language your program is written in (see section Using _GDBN__ with Different Languages). _fi__(!_CONLY__)

print exp

print /f exp

exp is an expression (in the source language). By default the value of exp 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 section Output formats.

print

print /f

If you omit exp, _GDBN__ displays the last value again (from the value history; see section 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 section Examining Memory.

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

Expressions

print and many other _GDBN__ commands accept an expression and compute its value. Any kind of constant, variable or operator defined by the programming language you are using is legal in an expression in _GDBN__. This includes conditional expressions, function calls, casts and string constants. It unfortunately does not include symbols defined by preprocessor #define commands.

_if__(!_CONLY__) Because C is so widespread, most of the expressions shown in examples in this manual are in C. See section Using _GDBN__ with Different Languages, for information on how to use expressions in other languages.

In this section, we discuss operators that you can use in _GDBN__ expressions regardless of your programming language.

Casts are supported in all languages, not just in C, because it is so useful to cast a number into a pointer so as to examine a structure at that address in memory. _fi__(!_CONLY__)

_GDBN__ supports these operators in addition to those of programming languages:

@

`@' is a binary operator for treating parts of memory as arrays. See section Artificial Arrays, for more information.

::

`::' allows you to specify a variable in terms of the file or function where it is defined. See section Program Variables.

{type2 addr

Refers to an object of type type stored at address addr in memory. addr may be any expression whose value is an integer or pointer (but parentheses are required around binary operators, just as in a cast). This construct is allowed regardless of what kind of data is normally supposed to reside at addr.

Program Variables

The most common kind of expression to use is the name of a variable in your program.

Variables in expressions are understood in the selected stack frame (see section Selecting a Frame); they must either be global (or static) or be visible according to the scope rules of the programming language from the point of execution in that frame. This means that in the function

foo (a)
     int a;
{
  bar (a);
  {
    int b = test ();
    bar (b);
  }
}

the variable a is usable whenever your program is executing within the function foo, but the variable b is visible only while your program is executing inside the block in which b is declared.

There is an exception: you can refer to a variable or function whose scope is a single source file even if the current execution point is not in this file. But it is possible to have more than one such variable or function with the same name (in different source files). If that happens, referring to that name has unpredictable effects. If you wish, you can specify a static variable in a particular function or file, using the colon-colon notation:

file::variable
function::variable

Here file or function is the name of the context for the static variable. In the case of file names, you can use quotes to make sure _GDBN__ parses the file name as a single word--for example, to print a global value of x defined in `f2.c':

(_GDBP__) p 'f2.c'::x

_if__(!_CONLY__) This use of `::' is very rarely in conflict with the very similar use of the same notation in C++. _GDBN__ also supports use of the C++ scope resolution operator in _GDBN__ expressions. _fi__(!_CONLY__)

Warning: Occasionally, a local variable may appear to have the wrong value at certain points in a function--just after entry to the function, and just before exit. You may see this problem when you are stepping by machine instructions. This is because on most machines, it takes more than one instruction to set up a stack frame (including local variable definitions); if you are stepping by machine instructions, variables may appear to have the wrong values until the stack frame is completely built. On function exit, it usually also takes more than one machine instruction to destroy a stack frame; after you begin stepping through that group of instructions, local variable definitions may be gone.

Artificial Arrays

It is often useful to print out several successive objects of the same type in memory; a section of an array, or an array of dynamically determined size for which only a pointer exists in the program.

This can be done by constructing an artificial array with the binary operator `@'. The left operand of `@' should be the first element of the desired array, as an individual object. The right operand should be the desired length of the array. The result is an array value whose elements are all of the type of the left argument. The first element is actually the left argument; the second element comes from bytes of memory immediately following those that hold the first element, and so on. Here is an example. If a program says

int *array = (int *) malloc (len * sizeof (int));

you can print the contents of array with

p *array@len

The left operand of `@' must reside in memory. Array values made with `@' in this way behave just like other arrays in terms of subscripting, and are coerced to pointers when used in expressions. Artificial arrays most often appear in expressions via the value history (see section Value History), after printing one out.)

Sometimes the artificial array mechanism is not quite enough; in moderately complex data structures, the elements of interest may not actually be adjacent--for example, if you are interested in the values of pointers in an array. One useful work-around in this situation is to use a convenience variable (see section Convenience Variables) as a counter in an expression that prints the first interesting value, and then repeat that expression via RET. For instance, suppose you have an array dtab of pointers to structures, and you are interested in the values of a field fv in each structure. Here is an example of what you might type:

set $i = 0
p dtab[$i++]->fv
RET
RET
...

Output formats

By default, _GDBN__ prints a value according to its data type. Sometimes this is not what you want. For example, you might want to print a number in hex, or a pointer in decimal. Or you might want to view data in memory at a certain address as a character string or as an instruction. To do these things, specify an output format when you print a value.

The simplest use of output formats is to say how to print a value already computed. This is done by starting the arguments of the print command with a slash and a format letter. The format letters supported are:

x

Regard the bits of the value as an integer, and print the integer in hexadecimal.

d

Print as integer in signed decimal.

u

Print as integer in unsigned decimal.

o

Print as integer in octal.

t

Print as integer in binary. The letter `t' stands for "two".

a

Print as an address, both absolute in hex and as an offset from the nearest preceding symbol. This format can be used to discover where (in what function) an unknown address is located:

(_GDBP__) p/a 0x54320
_0__$3 = 0x54320 <_initialize_vx+396>_1__

c

Regard as an integer and print it as a character constant.

f

Regard the bits of the value as a floating point number and print using typical floating point syntax.

For example, to print the program counter in hex (see section Registers), type

p/x $pc

Note that no space is required before the slash; this is because command names in _GDBN__ cannot contain a slash.

To reprint the last value in the value history with a different format, you can use the print command with just a format and no expression. For example, `p/x' reprints the last value in hex.

Examining Memory

You can use the command x (for "examine") to examine memory in any of several formats, independently of your program's data types.

x/nfu addr

x addr

x

Use the command x to examine memory.

n, f, and u are all optional parameters that specify how much memory to display and how to format it; addr is an expression giving the address where you want to start displaying memory. If you use defaults for nfu, you need not type the slash `/'. Several commands set convenient defaults for addr.

n, the repeat count

The repeat count is a decimal integer; the default is 1. It specifies how much memory (counting by units u) to display.

f, the display format

The display format is one of the formats used by print, or `s' (null-terminated string) or `i' (machine instruction). The default is `x' (hexadecimal) initially, or the format from the last time you used either x or print.

u, the unit size

The unit size is any of

b

Bytes.

h

Halfwords (two bytes).

w

Words (four bytes). This is the initial default.

g

Giant words (eight bytes).

Each time you specify a unit size with x, that size becomes the default unit the next time you use x. (For the `s' and `i' formats, the unit size is ignored and is normally not written.)

addr, starting display address addr is the address where you want _GDBN__ to begin displaying memory. The expression need not have a pointer value (though it may); it is always interpreted as an integer address of a byte of memory. See section Expressions, for more information on expressions. The default for addr is usually just after the last address examined--but several other commands also set the default address: info breakpoints (to the address of the last breakpoint listed), info line (to the starting address of a line), and print (if you use it to display a value from memory).

For example, `x/3uh 0x54320' is a request to display three halfwords (h) of memory, formatted as unsigned decimal integers (`u'), starting at address 0x54320. `x/4xw $sp' prints the four words (`w') of memory above the stack pointer (here, `$sp'; see section Registers) in hexadecimal (`x').

Since the letters indicating unit sizes are all distinct from the letters specifying output formats, you do not have to remember whether unit size or format comes first; either order will work. The output specifications `4xw' and `4wx' mean exactly the same thing. (However, the count n must come first; `wx4' will not work.)

Even though the unit size u is ignored for the formats `s' and `i', you might still want to use a count n; for example, `3i' specifies that you want to see three machine instructions, including any operands. The command disassemble gives an alternative way of inspecting machine instructions; see section Source and Machine Code.

All the defaults for the arguments to x are designed to make it easy to continue scanning memory with minimal specifications each time you use x. For example, after you have inspected three machine instructions with `x/3i addr', you can inspect the next seven with just `x/7'. If you use RET to repeat the x command, the repeat count n is used again; the other arguments default as for successive uses of x.

The addresses and contents printed by the x command are not saved in the value history because there is often too much of them and they would get in the way. Instead, _GDBN__ makes these values available for subsequent use in expressions as values of the convenience variables $_ and $__. After an x command, the last address examined is available for use in expressions in the convenience variable $_. The contents of that address, as examined, are available in the convenience variable $__.

If the x command has a repeat count, the address and contents saved