gdb.info: Symbols

Go forward to Altering
Go backward to Languages
Go up to Top
Go to the top op gdb

Examining the Symbol Table

The commands described in this chapter allow you to inquire about the
symbols (names of variables, functions and types) defined in your
program.  This information is inherent in the text of your program and
does not change as your program executes.  GDB finds it in your
program's symbol table, in the file indicated when you started GDB
(*note Choosing files: File Options.), or by one of the file-management
commands (*note Commands to specify files: Files.).
   Occasionally, you may need to refer to symbols that contain unusual
characters, which GDB ordinarily treats as word delimiters.  The most
frequent case is in referring to static variables in other source files
(*note Program variables: Variables.).  File names are recorded in
object files as debugging symbols, but GDB would ordinarily parse a
typical file name, like `foo.c', as the three words `foo' `.' `c'.  To
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
quotes; for example,

p 'foo.c'::x

looks up the value of `x' in the scope of the file `foo.c'.
`info address SYMBOL'
     Describe where the data for SYMBOL is stored.  For a register
     variable, this says which register it is kept in.  For a
     non-register local variable, this prints the stack-frame offset at
     which the variable is always stored.
     Note the contrast with `print &SYMBOL', which does not work at all
     for a register variable, and for a stack local variable prints the
     exact address of the current instantiation of the variable.
`info symbol ADDR'
     Print the name of a symbol which is stored at the address ADDR.
     If no symbol is stored exactly at ADDR, GDB prints the nearest
     symbol and an offset from it:
          (gdb) info symbol 0x54320
          _initialize_vx + 396 in section .text
     This is the opposite of the `info address' command.  You can use
     it to find out the name of a variable or a function given its
     address.
`whatis EXPR'
     Print the data type of expression EXPR.  EXPR is not actually
     evaluated, and any side-effecting operations (such as assignments
     or function calls) inside it do not take place.  *Note
     Expressions: Expressions.
`whatis'
     Print the data type of `$', the last value in the value history.
`ptype TYPENAME'
     Print a description of data type TYPENAME.  TYPENAME may be the
     name of a type, or for C code it may have the form `class
     CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
     ENUM-TAG'.
`ptype EXPR'
`ptype'
     Print a description of the type of expression EXPR.  `ptype'
     differs from `whatis' by printing a detailed description, instead
     of just the name of the type.
     For example, for this variable declaration:
          struct complex {double real; double imag;} v;
     the two commands give this output:
          (gdb) whatis v
          type = struct complex
          (gdb) ptype v
          type = struct complex {
              double real;
              double imag;
          }
     As with `whatis', using `ptype' without an argument refers to the
     type of `$', the last value in the value history.
`info types REGEXP'
`info types'
     Print a brief description of all types whose names match REGEXP
     (or all types in your program, if you supply no argument).  Each
     complete typename is matched as though it were a complete line;
     thus, `i type value' gives information on all types in your
     program whose names include the string `value', but `i type
     ^value$' gives information only on types whose complete name is
     `value'.
     This command differs from `ptype' in two ways: first, like
     `whatis', it does not print a detailed description; second, it
     lists all source files where a type is defined.
`info scope ADDR'
     List all the variables local to a particular scope.  This command
     accepts a location--a function name, a source line, or an address
     preceded by a `*', and prints all the variables local to the scope
     defined by that location.  For example:
          (gdb) info scope command_line_handler
          Scope for command_line_handler:
          Symbol rl is an argument at stack/frame offset 8, length 4.
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
          Symbol linelength is in static storage at address 0x150a1c, length 4.
          Symbol p is a local variable in register $esi, length 4.
          Symbol p1 is a local variable in register $ebx, length 4.
          Symbol nline is a local variable in register $edx, length 4.
          Symbol repeat is a local variable at frame offset -8, length 4.
     This command is especially useful for determining what data to
     collect during a "trace experiment", see *Note collect: Tracepoint
     Actions.
`info source'
     Show information about the current source file--that is, the
     source file for the function containing the current point of
     execution:
        * the name of the source file, and the directory containing it,
        * the directory it was compiled in,
        * its length, in lines,
        * which programming language it is written in,
        * whether the executable includes debugging information for
          that file, and if so, what format the information is in
          (e.g., STABS, Dwarf 2, etc.), and
        * whether the debugging information includes information about
          preprocessor macros.
`info sources'
     Print the names of all source files in your program for which
     there is debugging information, organized into two lists: files
     whose symbols have already been read, and files whose symbols will
     be read when needed.
`info functions'
     Print the names and data types of all defined functions.
`info functions REGEXP'
     Print the names and data types of all defined functions whose
     names contain a match for regular expression REGEXP.  Thus, `info
     fun step' finds all functions whose names include `step'; `info
     fun ^step' finds those whose names start with `step'.  If a
     function name contains characters that conflict with the regular
     expression language (eg.  `operator*()'), they may be quoted with
     a backslash.
`info variables'
     Print the names and data types of all variables that are declared
     outside of functions (i.e. excluding local variables).
`info variables REGEXP'
     Print the names and data types of all variables (except for local
     variables) whose names contain a match for regular expression
     REGEXP.
`info classes'
`info classes REGEXP'
     Display all Objective-C classes in your program, or (with the
     REGEXP argument) all those matching a particular regular
     expression.
`info selectors'
`info selectors REGEXP'
     Display all Objective-C selectors in your program, or (with the
     REGEXP argument) all those matching a particular regular
     expression.
     Some systems allow individual object files that make up your
     program to be replaced without stopping and restarting your
     program.  For example, in VxWorks you can simply recompile a
     defective object file and keep on running.  If you are running on
     one of these systems, you can allow GDB to reload the symbols for
     automatically relinked modules:
    `set symbol-reloading on'
          Replace symbol definitions for the corresponding source file
          when an object file with a particular name is seen again.
    `set symbol-reloading off'
          Do not replace symbol definitions when encountering object
          files of the same name more than once.  This is the default
          state; if you are not running on a system that permits
          automatic relinking of modules, you should leave
          `symbol-reloading' off, since otherwise GDB may discard
          symbols when linking large programs, that may contain several
          modules (from different directories or libraries) with the
          same name.
    `show symbol-reloading'
          Show the current `on' or `off' setting.
`set opaque-type-resolution on'
     Tell GDB to resolve opaque types.  An opaque type is a type
     declared as a pointer to a `struct', `class', or `union'--for
     example, `struct MyType *'--that is used in one source file
     although the full declaration of `struct MyType' is in another
     source file.  The default is on.
     A change in the setting of this subcommand will not take effect
     until the next time symbols for a file are loaded.
`set opaque-type-resolution off'
     Tell GDB not to resolve opaque types.  In this case, the type is
     printed as follows:
          {<no data fields>}
`show opaque-type-resolution'
     Show whether opaque types are resolved or not.
`maint print symbols FILENAME'
`maint print psymbols FILENAME'
`maint print msymbols FILENAME'
     Write a dump of debugging symbol data into the file FILENAME.
     These commands are used to debug the GDB symbol-reading code.  Only
     symbols with debugging data are included.  If you use `maint print
     symbols', GDB includes all the symbols for which it has already
     collected full details: that is, FILENAME reflects symbols for
     only those files whose symbols GDB has read.  You can use the
     command `info sources' to find out which files these are.  If you
     use `maint print psymbols' instead, the dump shows information
     about symbols that GDB only knows partially--that is, symbols
     defined in files that GDB has skimmed, but not yet read
     completely.  Finally, `maint print msymbols' dumps just the
     minimal symbol information required for each object file from
     which GDB has read some symbols.  *Note Commands to specify files:
     Files, for a discussion of how GDB reads symbols (in the
     description of `symbol-file').
`maint info symtabs [ REGEXP ]'
`maint info psymtabs [ REGEXP ]'
     List the `struct symtab' or `struct partial_symtab' structures
     whose names match REGEXP.  If REGEXP is not given, list them all.
     The output includes expressions which you can copy into a GDB
     debugging this one to examine a particular structure in more
     detail.  For example:
          (gdb) maint info psymtabs dwarf2read
          { objfile /home/gnu/build/gdb/gdb
            ((struct objfile *) 0x82e69d0)
            { psymtab /home/gnu/src/gdb/dwarf2read.c
              ((struct partial_symtab *) 0x8474b10)
              readin no
              fullname (null)
              text addresses 0x814d3c8 -- 0x8158074
              globals (* (struct partial_symbol **) 0x8507a08 @ 9)
              statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
              dependencies (none)
            }
          }
          (gdb) maint info symtabs
          (gdb)
     We see that there is one partial symbol table whose filename
     contains the string `dwarf2read', belonging to the `gdb'
     executable; and we see that GDB has not read in any symtabs yet at
     all.  If we set a breakpoint on a function, that will cause GDB to
     read the symtab for the compilation unit containing that function:
          (gdb) break dwarf2_psymtab_to_symtab
          Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
          line 1574.
          (gdb) maint info symtabs
          { objfile /home/gnu/build/gdb/gdb
            ((struct objfile *) 0x82e69d0)
            { symtab /home/gnu/src/gdb/dwarf2read.c
              ((struct symtab *) 0x86c1f38)
              dirname (null)
              fullname (null)
              blockvector ((struct blockvector *) 0x86c1bd0) (primary)
              debugformat DWARF 2
            }
          }
          (gdb)