binutils-gdb/gdb/doc/gdb.symb-m4

_dnl__								-*- Texinfo -*-
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
_dnl__ This file is part of the source for the GDB manual.
@c M4 FRAGMENT: $Id$
@node Symbols, Altering, Data, Top
@chapter Examining the Symbol Table

The commands described in this section 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 the program executes.  _GDBN__ finds it in your
program's symbol table, in the file indicated when you started _GDBN__ 
(@pxref{File Options}), or by one of the file-management commands
(@pxref{Files}).

@table @code
@item info address @var{symbol}
@kindex info address
Describe where the data for @var{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 @samp{print &@var{symbol}}, which does not work
at all for a register variables, and for a stack local variable prints
the exact address of the current instantiation of the variable.

@item whatis @var{exp}
@kindex whatis
Print the data type of expression @var{exp}.  @var{exp} is not
actually evaluated, and any side-effecting operations (such as
assignments or function calls) inside it do not take place.
@xref{Expressions}.

@item whatis
Print the data type of @code{$}, the last value in the value history.

@item ptype @var{typename}
@kindex ptype
Print a description of data type @var{typename}.  @var{typename} may be
the name of a type, or for C code it may have the form
@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
@samp{enum @var{enum-tag}}.@refill

@item ptype @var{exp}
Print a description of the type of expression @var{exp}.  @code{ptype}
differs from @code{whatis} by printing a detailed description, instead of just
the name of the type.  For example, if your program declares a variable
as
@example
struct complex @{double real; double imag;@} v;
@end example
@noindent
compare the output of the two commands:
@example
(_GDBP__) whatis v
type = struct complex
(_GDBP__) ptype v
type = struct complex @{
    double real;
    double imag;
@}
@end example

@item info types @var{regexp}
@itemx info types
@kindex info types 
Print a brief description of all types whose name matches @var{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,
@samp{i type value} gives information on all types in your program whose
name includes the string @code{value}, but @samp{i type ^value$} gives
information only on types whose complete name is @code{value}.

This command differs from @code{ptype} in two ways: first, like
@code{whatis}, it does not print a detailed description; second, it
lists all source files where a type is defined.

@item info source
@kindex info source
Show the name of the current source file---that is, the source file for
the function containing the current point of execution.

@item info sources
@kindex info sources
Print the names of all source files in the program for which there is
debugging information, organized into two lists: those for which symbols
have been read in, and those for which symbols will be read in on
demand.
@c FIXME: above passive AND awkward!

@item info functions
@kindex info functions
Print the names and data types of all defined functions.

@item info functions @var{regexp}
Print the names and data types of all defined functions
whose names contain a match for regular expression @var{regexp}.
Thus, @samp{info fun step} finds all functions whose names
include @code{step}; @samp{info fun ^step} finds those whose names
start with @code{step}.

@item info variables
@kindex info variables
Print the names and data types of all variables that are declared
outside of functions (i.e., excluding local variables).

@item info variables @var{regexp}
Print the names and data types of all variables (except for local
variables) whose names contain a match for regular expression
@var{regexp}.


@ignore
This was never implemented.
@item info methods
@itemx info methods @var{regexp}
@kindex info methods
The @code{info methods} command permits the user to examine all defined
methods within C++ program, or (with the @var{regexp} argument) a
specific set of methods found in the various C++ classes.  Many
C++ classes provide a large number of methods.  Thus, the output
from the @code{ptype} command can be overwhelming and hard to use.  The
@code{info-methods} command filters the methods, printing only those
which match the regular-expression @var{regexp}.
@end ignore

@item printsyms @var{filename}
@kindex printsyms
Write a complete dump of the debugger's symbol data into the
file @var{filename}.
@end table