Debugging with GDB: Convenience Vars

Next: Convenience Funs, Previous: Value History, Up: Data [Contents][Index]

### 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.

`$_exitcode`

  When the program being debugged terminates normally, GDB automatically sets this variable to the exit code of the program, and resets `$_exitsignal` to `void`.

`$_exitsignal`

  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>

      int
      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
       >else
       >echo The program has signalled\n
       >end
      >end
      (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

`$_exception`

  The variable `$_exception` is set to the exception object being thrown at an exception-related catchpoint. See Set Catchpoints.

`$_probe_argc`
`$_probe_arg0…$_probe_arg11`

  Arguments to a static probe. See Static Probe Points.

`$_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.

Next: Convenience Funs, Previous: Value History, Up: Data [Contents][Index]