Next: , Previous: Value History, Up: Data

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, as well as a list of the convenience functions. 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.
When the program being debugged terminates normally, gdb automatically sets this variable to the exit code of the program, and resets $_exitsignal to void.
When the program being debugged dies due to an uncaught signal, gdb automatically sets this variable to that signal's number, and resets $_exitcode to void.

To distinguish between whether the program being debugged has exited (i.e., $_exitcode is not void) or signalled (i.e., $_exitsignal is not void), the convenience function $_isvoid can be used (see Convenience Functions). For example, considering the following source code:

          #include <signal.h>
          main (int argc, char *argv[])
            raise (SIGALRM);
            return 0;

A valid way of telling whether the program being debugged has exited or signalled would be:

          (gdb) define has_exited_or_signalled
          Type commands for definition of ``has_exited_or_signalled''.
          End with a line saying just ``end''.
          >if $_isvoid ($_exitsignal)
           >echo The program has exited\n
           >echo The program has signalled\n
          (gdb) run
          Starting program:
          Program terminated with signal SIGALRM, Alarm clock.
          The program no longer exists.
          (gdb) has_exited_or_signalled
          The program has signalled

As can be seen, gdb correctly informs that the program being debugged has signalled, since it calls raise and raises a SIGALRM signal. If the program being debugged had not called raise, then gdb would report a normal exit:

          (gdb) has_exited_or_signalled
          The program has exited

The variable $_exception is set to the exception object being thrown at an exception-related catchpoint. See Set Catchpoints.
Arguments to a static probe. See Static Probe Points.
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.
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.
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.