Convenience Funs (Debugging with GDB)
Next: Registers, Previous: Convenience Vars, Up: Data [Contents][Index]
10.13 Convenience Functions
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.
These functions do not require GDB to be configured with Python
support, which means that they are always available.
$_isvoid (expr)
Return one if the expression
expr
isvoid
. Otherwise it returns zero.A
void
expression is an expression where the type of the result isvoid
. For example, you can examine a convenience variable (see Convenience Variables) to check whether it isvoid
:(gdb) print $_exitcode $1 = void (gdb) print $_isvoid ($_exitcode) $2 = 1 (gdb) run Starting program: ./a.out [Inferior 1 (process 29572) exited normally] (gdb) print $_exitcode $3 = 0 (gdb) print $_isvoid ($_exitcode) $4 = 0
In the example above, we used
$_isvoid
to check whether$_exitcode
isvoid
before and after the execution of the program being debugged. Before the execution there is no exit code to be examined, therefore$_exitcode
isvoid
. After the execution the program being debugged returned zero, therefore$_exitcode
is zero, which means that it is notvoid
anymore.The
void
expression can also be a call of a function from the program being debugged. For example, given the following function:void foo (void) { }
The result of calling it inside GDB is
void
:(gdb) print foo () $1 = void (gdb) print $_isvoid (foo ()) $2 = 1 (gdb) set $v = foo () (gdb) print $v $3 = void (gdb) print $_isvoid ($v) $4 = 1
$_gdb_setting_str (setting)
Return the value of the GDB
setting
as a string.setting
is any setting that can be used in aset
orshow
command (see Controlling GDB).(gdb) show print frame-arguments Printing of non-scalar frame arguments is "scalars". (gdb) p $_gdb_setting_str("print frame-arguments") $1 = "scalars" (gdb) p $_gdb_setting_str("height") $2 = "30" (gdb)
$_gdb_setting (setting)
Return the value of the GDB
setting
. The type of the returned value depends on the setting.The value type for boolean and auto boolean settings is
int
. The boolean valuesoff
andon
are converted to the integer values0
and1
. The valueauto
is converted to the value-1
.The value type for integer settings is either
unsigned int
orint
, depending on the setting.Some integer settings accept an
unlimited
value. Depending on the setting, theset
command also accepts the value0
or the value-1
as a synonym forunlimited
. For example,set height unlimited
is equivalent toset height 0
.Some other settings that accept the
unlimited
value use the value0
to literally mean zero. For example,set history size 0
indicates to not record any GDB commands in the command history. For such settings,-1
is the synonym forunlimited
.See the documentation of the corresponding
set
command for the numerical value equivalent tounlimited
.The
$_gdb_setting
function converts the unlimited value to a0
or a-1
value according to what theset
command uses.(gdb) p $_gdb_setting_str("height") $1 = "30" (gdb) p $_gdb_setting("height") $2 = 30 (gdb) set height unlimited (gdb) p $_gdb_setting_str("height") $3 = "unlimited" (gdb) p $_gdb_setting("height") $4 = 0
(gdb) p $_gdb_setting_str("history size") $5 = "unlimited" (gdb) p $_gdb_setting("history size") $6 = -1 (gdb) p $_gdb_setting_str("disassemble-next-line") $7 = "auto" (gdb) p $_gdb_setting("disassemble-next-line") $8 = -1 (gdb)
Other setting types (enum, filename, optional filename, string, string noescape) are returned as string values.
$_gdb_maint_setting_str (setting)
Like the
$_gdb_setting_str
function, but works withmaintenance set
variables.$_gdb_maint_setting (setting)
Like the
$_gdb_setting
function, but works withmaintenance set
variables.
The following functions require GDB to be configured with Python
support.
$_memeq(buf1, buf2, length)
Returns one if the
length
bytes at the addresses given bybuf1
andbuf2
are equal. Otherwise it returns zero.$_regex(str, regex)
Returns one if the string
str
matches the regular expressionregex
. Otherwise it returns zero. The syntax of the regular expression is that specified byPython
’s regular expression support.$_streq(str1, str2)
Returns one if the strings
str1
andstr2
are equal. Otherwise it returns zero.$_strlen(str)
Returns the length of string
str
.$_caller_is(name[, number_of_frames])
Returns one if the calling function’s name is equal to
name
. Otherwise it returns zero.If the optional argument
number_of_frames
is provided, it is the number of frames up in the stack to look. The default is 1.Example:
(gdb) backtrace #0 bottom_func () at testsuite/gdb.python/py-caller-is.c:21 #1 0x00000000004005a0 in middle_func () at testsuite/gdb.python/py-caller-is.c:27 #2 0x00000000004005ab in top_func () at testsuite/gdb.python/py-caller-is.c:33 #3 0x00000000004005b6 in main () at testsuite/gdb.python/py-caller-is.c:39 (gdb) print $_caller_is ("middle_func") $1 = 1 (gdb) print $_caller_is ("top_func", 2) $1 = 1
$_caller_matches(regexp[, number_of_frames])
Returns one if the calling function’s name matches the regular expression
regexp
. Otherwise it returns zero.If the optional argument
number_of_frames
is provided, it is the number of frames up in the stack to look. The default is 1.$_any_caller_is(name[, number_of_frames])
Returns one if any calling function’s name is equal to
name
. Otherwise it returns zero.If the optional argument
number_of_frames
is provided, it is the number of frames up in the stack to look. The default is 1.This function differs from
$_caller_is
in that this function checks all stack frames from the immediate caller to the frame specified bynumber_of_frames
, whereas$_caller_is
only checks the frame specified bynumber_of_frames
.$_any_caller_matches(regexp[, number_of_frames])
Returns one if any calling function’s name matches the regular expression
regexp
. Otherwise it returns zero.If the optional argument
number_of_frames
is provided, it is the number of frames up in the stack to look. The default is 1.This function differs from
$_caller_matches
in that this function checks all stack frames from the immediate caller to the frame specified bynumber_of_frames
, whereas$_caller_matches
only checks the frame specified bynumber_of_frames
.$_as_string(value)
Return the string representation of
value
.This function is useful to obtain the textual label (enumerator) of an enumeration value. For example, assuming the variable
node
is of an enumerated type:(gdb) printf "Visiting node of type %s\n", $_as_string(node) Visiting node of type NODE_INTEGER
$_cimag(value)
$_creal(value)
Return the imaginary (
$_cimag
) or real ($_creal
) part of the complex numbervalue
.The type of the imaginary or real part depends on the type of the complex number, e.g., using
$_cimag
on afloat complex
will return an imaginary part of typefloat
.
GDB provides the ability to list and get help on convenience functions.
help function
Print a list of all convenience functions.
Next: Registers, Previous: Convenience Vars, Up: Data [Contents][Index]