### 10.12 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 Setting Catchpoints.

`$_ada_exception`

  The variable `$_ada_exception` is set to the address of the exception being caught or thrown at an Ada exception-related catchpoint. See Setting 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.

`$_inferior`

  The number of the current inferior. See Debugging Multiple Inferiors Connections and Programs.

`$_thread`

  The thread number of the current thread. See thread numbers.

`$_gthread`

  The global number of the current thread. See global thread numbers.

`$_inferior_thread_count`

  The number of live threads in the current inferior. See Debugging Programs with Multiple Threads.

`$_gdb_major` ¶
`$_gdb_minor`

  The major and minor version numbers of the running GDB. Development snapshots and pretest versions have their minor version incremented by one; thus, GDB pretest 9.11.90 will produce the value 12 for `$_gdb_minor`. These variables allow you to write scripts that work with different versions of GDB without errors caused by features unavailable in some of those versions.

`$_shell_exitcode` ¶
`$_shell_exitsignal`

  GDB commands such as `shell` and `|` are launching shell commands. When a launched command terminates, GDB automatically maintains the variables `$_shell_exitcode` and `$_shell_exitsignal` according to the exit status of the last launched command. These variables are set and used similarly to the variables `$_exitcode` and `$_exitsignal`.

`$_colorsupport` ¶

  Comma-separated list of color space names supported by terminal. Names could be any of ‘`monochrome`’, ‘`ansi_8color`’, ‘`aixterm_16color`’, ‘`xterm_256color`’, ‘`rgb_24bit`’. E.g., for plain linux terminal the value could be ‘`monochrome,ansi_8color`’ and for terminal with truecolor support it could be ‘`monochrome,ansi_8color,aixterm_16color,xterm_256color,rgb_24bit`’. ‘`rgb_24bit`’ availability is determined by the `COLORTERM` environment variable which may be ‘`truecolor`’ or ‘`24bit`’. Other color spaces are determined by the "Co" termcap which in turn depends on the `TERM` environment variable.

`$_linker_namespace_count` ¶

  Number of active linker namespaces in the inferior (see Commands to Specify Files). In systems with no support for linker namespaces or if the inferior hasn’t started, this variable will always be set to ‘`0`’.

`$_linker_namespace` ¶

  The namespace which contains the current location in the inferior. This returns GDB’s internal numbering for the namespace. In systems with no support for linker namespaces, this variable will always be set to ‘`0`’.