10.12 Convenience Variables

ROCGDB provides convenience variables that you can use within ROCGDB to hold on to a value and refer to it later. These variables exist entirely within ROCGDB; 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 ROCGDB 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, ROCGDB 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, ROCGDB 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, ROCGDB 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 ROCGDB 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 number.

$_thread_systag

The target system’s thread identifier (systag) string of the current thread. See target system thread identifier.

$_thread_name

The thread name string of the current thread, or the empty string if no name has been assigned. See thread name.

$_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 ROCGDB. Development snapshots and pretest versions have their minor version incremented by one; thus, ROCGDB 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 ROCGDB without errors caused by features unavailable in some of those versions.

$_shell_exitcode ¶

$_shell_exitsignal

ROCGDB commands such as shell and | are launching shell commands. When a launched command terminates, ROCGDB 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.

$_agent

The per-inferior heterogeneous agent number of the current thread, or 0 if not associated with a heterogeneous dispatch. See Debugging Heterogeneous Programs.

$_agent_systag

The target system’s heterogeneous agent identifier (agent_systag) string of the heterogeneous agent of the current thread.

$_queue

The per-inferior heterogeneous queue number of the current thread, or 0 if not associated with a heterogeneous dispatch. See Debugging Heterogeneous Programs.

$_queue_systag

The target system’s heterogeneous queue identifier (queue_systag) string of the heterogeneous queue of the current thread.

$_dispatch

The per-inferior heterogeneous dispatch number of the current thread, or 0 if not associated with a heterogeneous dispatch. See Debugging Heterogeneous Programs.

$_dispatch_systag

The target system’s heterogeneous dispatch identifier (disatch_systag) string of the heterogeneous dispatch of the current thread.

$_lane

The per-thread lane index of the current heterogeneous lane of the current thread. See lane ID.

$_lane_count

The number of heterogeneous lanes in the thread, taking into account lanes which have not been assigned to a heterogeneous work-group. See Debugging Heterogeneous Programs.

$_lane_systag

The target system’s heterogeneous lane identifier (lane_systag) string of the current heterogeneous lane in the current thread. See target system lane identifier.

$_lane_name

The heterogeneous lane name string of the current heterogeneous lane, or the empty string if no name has been assigned by the ‘lane name’ command. See Debugging Heterogeneous Programs.

$_dispatch_pos

The heterogeneous dispatch position string of the current thread, or the empty string if not associated with a heterogeneous dispatch. See Debugging Heterogeneous Programs.

$_thread_workgroup_pos

$_lane_workgroup_pos

The heterogeneous work-group position string of the current thread or heterogeneous lane respectively, or the empty string if not associated with a heterogeneous dispatch. See Debugging Heterogeneous Programs.