##### 23.2.2.18 Python representation of Symbols.

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:

— Function: gdb.lookup_symbol (name [, block [, domain]])

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

— Function: gdb.lookup_global_symbol (name [, domain])

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

A `gdb.Symbol` object has the following attributes:

— Variable: Symbol.type

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

— Variable: Symbol.symtab

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

— Variable: Symbol.name

> The name of the symbol as a string. This attribute is not writable.

— Variable: Symbol.linkage_name

> The name of the symbol, as used by the linker (i.e., may be mangled). This attribute is not writable.

— Variable: Symbol.print_name

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

— Variable: Symbol.addr_class

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

— Variable: Symbol.is_argument

> `True` if the symbol is an argument of a function.

— Variable: Symbol.is_constant

> `True` if the symbol is a constant.

— Variable: Symbol.is_function

> `True` if the symbol is a function or a method.

— Variable: Symbol.is_variable

> `True` if the symbol is a variable.

A `gdb.Symbol` object has the following methods:

— Function: Symbol.is_valid ()

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

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, function names, typedef names and enum type values.
`gdb.SYMBOL_STRUCT_DOMAIN`
  This domain holds struct, union and enum type names.
`gdb.SYMBOL_LABEL_DOMAIN`
  This domain contains names of labels (for gotos).
`gdb.SYMBOL_VARIABLES_DOMAIN`
  This domain holds a subset of the `SYMBOLS_VAR_DOMAIN`; it contains everything minus functions and types.
`gdb.SYMBOL_FUNCTION_DOMAIN`
  This domain contains all functions.
`gdb.SYMBOL_TYPES_DOMAIN`
  This domain contains all types.

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