10.12 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 is void. Otherwise it returns zero.

A void expression is an expression where the type of the result is void. For example, you can examine a convenience variable (see Convenience Variables) to check whether it is void:

          (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 is void before and after the execution of the program being debugged. Before the execution there is no exit code to be examined, therefore $_exitcode is void. After the execution the program being debugged returned zero, therefore $_exitcode is zero, which means that it is not void 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

These functions require gdb to be configured with Python support.

$_memeq(buf1, buf2, length)

Returns one if the length bytes at the addresses given by buf1 and buf2 are equal. Otherwise it returns zero.

$_regex(str, regex)

Returns one if the string str matches the regular expression regex. Otherwise it returns zero. The syntax of the regular expression is that specified by Python's regular expression support.

$_streq(str1, str2)

Returns one if the strings str1 and str2 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 by number_of_frames, whereas $_caller_is only checks the frame specified by number_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 by number_of_frames, whereas $_caller_matches only checks the frame specified by number_of_frames.

gdb provides the ability to list and get help on convenience functions.

help function

Print a list of all convenience functions.