Info Catalog gdb: Convenience Vars gdb: Data gdb: Registers

gdb: Convenience Funs

 
 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 Convenience Vars.) 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.
 
 '$_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
 
    GDB provides the ability to list and get help on convenience
 functions.
 
 'help function'
      Print a list of all convenience functions.
 

Info Catalog gdb: Convenience Vars gdb: Data gdb: Registers