10.11 Convenience Variables

gdb provides convenience variables that you can use within gdb to hold on to a value and refer to it later. These variables exist entirely within gdb; they are not part of your program, and setting a convenience variable has no direct effect on further execution of your program. That is why you can use them freely.

Convenience variables are prefixed with `$'. Any name preceded by `$' can be used for a convenience variable, unless it is one of the predefined machine-specific register names (see Registers). (Value history references, in contrast, are numbers preceded by `$'. See Value History.)

You can save a value in a convenience variable with an assignment expression, just as you would set a variable in your program. For example:

     set $foo = *object_ptr

would save in $foo the value contained in the object pointed to by object_ptr.

Using a convenience variable for the first time creates it, but its value is void until you assign a new value. You can alter the value with another assignment at any time.

Convenience variables have no fixed types. You can assign a convenience variable any type of value, including structures and arrays, even if that variable already has a value of a different type. The convenience variable, when used as an expression, has the type of its current value.

show convenience

Print a list of convenience variables used so far, and their values. Abbreviated show conv.

init-if-undefined $variable = expression

Set a convenience variable if it has not already been set. This is useful for user-defined commands that keep some state. It is similar, in concept, to using local static variables with initializers in C (except that convenience variables are global). It can also be used to allow users to override default values used in a command script.

If the variable is already defined then the expression is not evaluated so any side-effects do not occur.

One of the ways to use a convenience variable is as a counter to be incremented or a pointer to be advanced. For example, to print a field from successive elements of an array of structures:

     set $i = 0
     print bar[$i++]->contents

Repeat that command by typing <RET>.

Some convenience variables are created automatically by gdb and given values likely to be useful.

$_

The variable $_ is automatically set by the x command to the last address examined (see Examining Memory). Other commands which provide a default address for x to examine also set $_ to that address; these commands include info line and info breakpoint. The type of $_ is void * except when set by the x command, in which case it is a pointer to the type of $__.

$__

The variable $__ is automatically set by the x command to the value found in the last address examined. Its type is chosen to match the format in which the data was printed.

$_exitcode

The variable $_exitcode is automatically set to the exit code when the program being debugged terminates.

$_sdata

The variable $_sdata contains extra collected static tracepoint data. See Tracepoint Action Lists. Note that $_sdata could be empty, if not inspecting a trace buffer, or if extra static tracepoint data has not been collected.

$_siginfo

The variable $_siginfo contains extra signal information (see extra signal information). Note that $_siginfo could be empty, if the application has not yet received any signals. For example, it will be empty before you execute the run command.

$_tlb

The variable $_tlb is automatically set when debugging applications running on MS-Windows in native mode or connected to gdbserver that supports the qGetTIBAddr request. See General Query Packets. This variable contains the address of the thread information block.

On HP-UX systems, if you refer to a function or variable name that begins with a dollar sign, gdb searches for a user or system name first, before it searches for a convenience variable.

gdb also supplies some convenience functions. These have a syntax similar to convenience variables. A convenience function can be used in an expression just like an ordinary function; however, a convenience function is implemented internally to gdb.

help function

Print a list of all convenience functions.