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]