#### 23.4.3.17 Guile representation of Symbols. ¶

GDB represents every variable, function and type as an entry in a symbol table. See Examining the Symbol Table. Guile represents these symbols in GDB with the `<gdb:symbol>` object.

The following symbol-related procedures are provided by the `(gdb)` module:

Scheme Procedure: symbol? object ¶

  Return `#t` if object is an object of type `<gdb:symbol>`. Otherwise return `#f`.

Scheme Procedure: symbol-valid? symbol ¶

  Return `#t` if the `<gdb:symbol>` object is valid, `#f` 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>` procedures will throw an exception if it is invalid at the time the procedure is called.

Scheme Procedure: symbol-type symbol ¶

  Return the type of symbol or `#f` if no type is recorded. The result is an object of type `<gdb:type>`. See Types In Guile.

Scheme Procedure: symbol-symtab symbol ¶

  Return the symbol table in which symbol appears. The result is an object of type `<gdb:symtab>`. See Symbol table representation in Guile..

Scheme Procedure: symbol-line symbol ¶

  Return the line number in the source code at which symbol was defined. This is an integer.

Scheme Procedure: symbol-name symbol ¶

  Return the name of symbol as a string.

Scheme Procedure: symbol-linkage-name symbol ¶

  Return the name of symbol, as used by the linker (i.e., may be mangled).

Scheme Procedure: symbol-print-name symbol ¶

  Return the name of 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.

Scheme Procedure: symbol-addr-class symbol ¶

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

Scheme Procedure: symbol-needs-frame? symbol ¶

  Return `#t` if evaluating symbol’s value requires a frame (see Accessing inferior stack frames from Guile.) and `#f` otherwise. Typically, local variables will require a frame, but other symbols will not.

Scheme Procedure: symbol-argument? symbol ¶

  Return `#t` if symbol is an argument of a function. Otherwise return `#f`.

Scheme Procedure: symbol-constant? symbol ¶

  Return `#t` if symbol is a constant. Otherwise return `#f`.

Scheme Procedure: symbol-function? symbol ¶

  Return `#t` if symbol is a function or a method. Otherwise return `#f`.

Scheme Procedure: symbol-variable? symbol ¶

  Return `#t` if symbol is a variable. Otherwise return `#f`.

Scheme Procedure: symbol-value symbol [#:frame frame] ¶

  Compute the value of 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 an exception is thrown.

Scheme Procedure: lookup-symbol name [#:block block] [#:domain 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 list of two elements. The first element is a `<gdb:symbol>` object or `#f` if the symbol is not found. If the symbol is found, the second element is `#t` if the symbol is a field of a method’s object (e.g., `this` in C`++`), otherwise it is `#f`. If the symbol is not found, the second element is `#f`.

Scheme Procedure: lookup-global-symbol name [#:domain domain] ¶

  This function searches for a global symbol by name. The search scope can be restricted 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 `#f` if the symbol is not found.

The available domain categories in `<gdb:symbol>` are represented as constants in the `(gdb)` module:

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

`SYMBOL_VAR_DOMAIN` ¶

  This domain contains variables, function names, typedef names and enum type values.

`SYMBOL_FUNCTION_DOMAIN` ¶

  This domain contains functions.

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

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

`SYMBOL_LABEL_DOMAIN` ¶

  This domain contains names of labels (for gotos).

`SYMBOL_VARIABLES_DOMAIN` ¶

  This domain holds a subset of the `SYMBOLS_VAR_DOMAIN`; it contains everything minus functions and types.

`SYMBOL_FUNCTIONS_DOMAIN` ¶

  This domain contains all functions.

`SYMBOL_TYPES_DOMAIN` ¶

  This domain contains all types.

The available address class categories in `<gdb:symbol>` are represented as constants in the `gdb` module:

When searching for a symbol, the desired domain constant can be passed verbatim to the lookup function.

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.

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

`SYMBOL_LOC_CONST` ¶

  Value is constant int.

`SYMBOL_LOC_STATIC` ¶

  Value is at a fixed address.

`SYMBOL_LOC_REGISTER` ¶

  Value is in a register.

`SYMBOL_LOC_ARG` ¶

  Value is an argument. This value is at the offset stored within the symbol inside the frame’s argument list.

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

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

`SYMBOL_LOC_LOCAL` ¶

  Value is a local variable.

`SYMBOL_LOC_TYPEDEF` ¶

  Value not used. Symbols in the domain `SYMBOL_STRUCT_DOMAIN` all have this class.

`SYMBOL_LOC_BLOCK` ¶

  Value is a block.

`SYMBOL_LOC_CONST_BYTES` ¶

  Value is a byte-sequence.

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

`SYMBOL_LOC_OPTIMIZED_OUT` ¶

  The value does not actually exist in the program.

`SYMBOL_LOC_COMPUTED` ¶

  The value’s address is a computed location.