Next: Symbol Tables In Python, Previous: Blocks In Python, Up: Python API [Contents][Index]
GDB represents every variable, function and type as an
entry in a symbol table. See Examining the Symbol Table.
Similarly, Python represents these symbols in GDB with the
gdb.Symbol
object.
The following symbol-related functions are available in the gdb
module:
This function searches for a symbol by name. The search scope can be restricted to the parameters defined in the optional domain and block arguments.
name is the name of the symbol. It must be a string. The
optional block argument restricts the search to symbols visible
in that block. The block argument must be a
gdb.Block
object. If omitted, the block for the current frame
is used. The optional domain argument restricts
the search to the domain type. The domain argument must be a
domain constant defined in the gdb
module and described later
in this chapter.
The result is a tuple of two elements.
The first element is a gdb.Symbol
object or None
if the symbol
is not found.
If the symbol is found, the second element is True
if the symbol
is a field of a method’s object (e.g., this
in C++),
otherwise it is False
.
If the symbol is not found, the second element is False
.
This function searches for a global symbol by name. The search scope can be restricted to by the domain argument.
name is the name of the symbol. It must be a string.
The optional domain argument restricts the search to the domain type.
The domain argument must be a domain constant defined in the gdb
module and described later in this chapter.
The result is a gdb.Symbol
object or None
if the symbol
is not found.
This function searches for a global symbol with static linkage by name. The search scope can be restricted to by the domain argument.
name is the name of the symbol. It must be a string.
The optional domain argument restricts the search to the domain type.
The domain argument must be a domain constant defined in the gdb
module and described later in this chapter.
The result is a gdb.Symbol
object or None
if the symbol
is not found.
Note that this function will not find function-scoped static variables. To look
up such variables, iterate over the variables of the function’s
gdb.Block
and check that block.addr_class
is
gdb.SYMBOL_LOC_STATIC
.
There can be multiple global symbols with static linkage with the same name. This function will only return the first matching symbol that it finds. Which symbol is found depends on where GDB is currently stopped, as GDB will first search for matching symbols in the current object file, and then search all other object files. If the application is not yet running then GDB will search all object files in the order they appear in the debug information.
Similar to gdb.lookup_static_symbol
, this function searches for
global symbols with static linkage by name, and optionally restricted
by the domain argument. However, this function returns a list of all
matching symbols found, not just the first one.
name is the name of the symbol. It must be a string.
The optional domain argument restricts the search to the domain type.
The domain argument must be a domain constant defined in the gdb
module and described later in this chapter.
The result is a list of gdb.Symbol
objects which could be empty
if no matching symbols were found.
Note that this function will not find function-scoped static variables. To look
up such variables, iterate over the variables of the function’s
gdb.Block
and check that block.addr_class
is
gdb.SYMBOL_LOC_STATIC
.
A gdb.Symbol
object has the following attributes:
The type of the symbol or None
if no type is recorded.
This attribute is represented as a gdb.Type
object.
See Types In Python. This attribute is not writable.
The symbol table in which the symbol appears. This attribute is
represented as a gdb.Symtab
object. See Symbol Tables In Python. This attribute is not writable.
The line number in the source code at which the symbol was defined. This is an integer.
The name of the symbol as a string. This attribute is not writable.
The name of the symbol, as used by the linker (i.e., may be mangled). This attribute is not writable.
The name of the symbol in a form suitable for output. This is either
name
or linkage_name
, depending on whether the user
asked GDB to display demangled or mangled names.
The address class of the symbol. This classifies how to find the value
of a symbol. Each address class is a constant defined in the
gdb
module and described later in this chapter.
This is True
if evaluating this symbol’s value requires a frame
(see Frames In Python) and False
otherwise. Typically,
local variables will require a frame, but other symbols will not.
True
if the symbol is an argument of a function.
True
if the symbol is a constant.
True
if the symbol is a function or a method.
True
if the symbol is a variable, as opposed to something like
a function or type. Note that this also returns False
for
arguments.
A gdb.Symbol
object has the following methods:
Returns True
if the gdb.Symbol
object is valid,
False
if not. A gdb.Symbol
object can become invalid if
the symbol it refers to does not exist in GDB any longer.
All other gdb.Symbol
methods will throw an exception if it is
invalid at the time the method is called.
Compute the value of the symbol, as a gdb.Value
. For
functions, this computes the address of the function, cast to the
appropriate type. If the symbol requires a frame in order to compute
its value, then frame must be given. If frame is not
given, or if frame is invalid, then this method will throw an
exception.
The available domain categories in gdb.Symbol
are represented
as constants in the gdb
module:
gdb.SYMBOL_UNDEF_DOMAIN
This is used when a domain has not been discovered or none of the following domains apply. This usually indicates an error either in the symbol information or in GDB’s handling of symbols.
gdb.SYMBOL_VAR_DOMAIN
This domain contains variables.
gdb.SYMBOL_FUNCTION_DOMAIN
This domain contains functions.
gdb.SYMBOL_TYPE_DOMAIN
This domain contains types. In a C-like language, types using a tag
(the name appearing after a struct
, union
, or
enum
keyword) will not appear here; in other languages, all
types are in this domain.
gdb.SYMBOL_STRUCT_DOMAIN
This domain holds struct, union and enum tag names. This domain is only used for C-like languages. For example, in this code:
struct type_one { int x; }; typedef struct type_one type_two;
Here type_one
will be in SYMBOL_STRUCT_DOMAIN
, but
type_two
will be in SYMBOL_TYPE_DOMAIN
.
gdb.SYMBOL_LABEL_DOMAIN
This domain contains names of labels (for gotos).
gdb.SYMBOL_MODULE_DOMAIN
This domain contains names of Fortran module types.
gdb.SYMBOL_COMMON_BLOCK_DOMAIN
This domain contains names of Fortran common blocks.
When searching for a symbol, the desired domain constant can be passed verbatim to the lookup function. For example:
symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN)
For more complex searches, there is a corresponding set of constants,
each named after one of the preceding constants, but with the
‘SEARCH’ prefix replacing the ‘SYMBOL’ prefix; for example,
SEARCH_LABEL_DOMAIN
. These may be or’d together to form a
search constant, e.g.:
symbol = gdb.lookup_symbol ("name", domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN)
The available address class categories in gdb.Symbol
are represented
as constants in the gdb
module:
gdb.SYMBOL_LOC_UNDEF
If this is returned by address class, it indicates an error either in the symbol information or in GDB’s handling of symbols.
gdb.SYMBOL_LOC_CONST
Value is constant int.
gdb.SYMBOL_LOC_STATIC
Value is at a fixed address.
gdb.SYMBOL_LOC_REGISTER
Value is in a register.
gdb.SYMBOL_LOC_ARG
Value is an argument. This value is at the offset stored within the symbol inside the frame’s argument list.
gdb.SYMBOL_LOC_REF_ARG
Value address is stored in the frame’s argument list. Just like
LOC_ARG
except that the value’s address is stored at the
offset, not the value itself.
gdb.SYMBOL_LOC_REGPARM_ADDR
Value is a specified register. Just like LOC_REGISTER
except
the register holds the address of the argument instead of the argument
itself.
gdb.SYMBOL_LOC_LOCAL
Value is a local variable.
gdb.SYMBOL_LOC_TYPEDEF
Value not used. Symbols in the domain SYMBOL_STRUCT_DOMAIN
all
have this class.
gdb.SYMBOL_LOC_LABEL
Value is a label.
gdb.SYMBOL_LOC_BLOCK
Value is a block.
gdb.SYMBOL_LOC_CONST_BYTES
Value is a byte-sequence.
gdb.SYMBOL_LOC_UNRESOLVED
Value is at a fixed address, but the address of the variable has to be determined from the minimal symbol table whenever the variable is referenced.
gdb.SYMBOL_LOC_OPTIMIZED_OUT
The value does not actually exist in the program.
gdb.SYMBOL_LOC_COMPUTED
The value’s address is a computed location.
gdb.SYMBOL_LOC_COMMON_BLOCK
The value’s address is a symbol. This is only used for Fortran common blocks.
Next: Symbol Tables In Python, Previous: Blocks In Python, Up: Python API [Contents][Index]