Next: Registers, Previous: Convenience Vars, Up: Data [Contents][Index]

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

Next: Registers, Previous: Convenience Vars, Up: Data [Contents][Index]