Turned $Id: from m4 comment into texinfo comment, allowing fragment

[deliverable/binutils-gdb.git] / gdb / doc / gdb.files-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 _GDBN__ Files, Targets, Altering, Top
@chapter _GDBN__'s Files

@menu
* Files::                       Commands to Specify Files
* Symbol Errors::               Errors Reading Symbol Files
@end menu

@node Files, Symbol Errors, _GDBN__ Files, _GDBN__ Files
@section Commands to Specify Files
@cindex core dump file
@cindex symbol table
_GDBN__ needs to know the file name of the program to be debugged, both in
order to read its symbol table and in order to start the program.  To
debug a core dump of a previous run, _GDBN__ must be told the file name of
the core dump.

The usual way to specify the executable and core dump file names is with
the command arguments given when you start _GDBN__, as discussed in
@pxref{Invocation}.

Occasionally it is necessary to change to a different file during a
_GDBN__ session.  Or you may run _GDBN__ and forget to specify the files you
want to use.  In these situations the _GDBN__ commands to specify new files
are useful.

@table @code
@item file @var{filename}
@cindex executable file
@kindex file
Use @var{filename} as the program to be debugged.  It is read for its
symbols and for the contents of pure memory.  It is also the program
executed when you use the @code{run} command.  If you do not specify a
directory and the file is not found in _GDBN__'s working directory,

_GDBN__ uses the environment variable @code{PATH} as a list of
directories to search, just as the shell does when looking for a program
to run.  You can change the value of this variable, for both _GDBN__ and
your program, using the @code{path} command.

@code{file} with no argument makes _GDBN__ discard any information it
has on both executable file and the symbol table.

@item exec-file @var{filename}
@kindex exec-file
Specify that the program to be run (but not the symbol table) is found
in @var{filename}.  _GDBN__ will search the environment variable @code{PATH}
if necessary to locate the program.  

@item symbol-file @var{filename}
@kindex symbol-file
Read symbol table information from file @var{filename}.  @code{PATH} is
searched when necessary.  Use the @code{file} command to get both symbol
table and program to run from the same file.

@code{symbol-file} with no argument clears out _GDBN__'s information on your
program's symbol table.

The @code{symbol-file} command causes _GDBN__ to forget the contents of its
convenience variables, the value history, and all breakpoints and
auto-display expressions.  This is because they may contain pointers to
the internal data recording symbols and data types, which are part of
the old symbol table data being discarded inside _GDBN__.

@code{symbol-file} will not repeat if you press @key{RET} again after
executing it once.

On some kinds of object files, the @code{symbol-file} command does not
actually read the symbol table in full right away.  Instead, it scans
the symbol table quickly to find which source files and which symbols
are present.  The details are read later, one source file at a time,
when they are needed.

The purpose of this two-stage reading strategy is to make _GDBN__ start up
faster.  For the most part, it is invisible except for occasional pauses
while the symbol table details for a particular source file are being
read.  (The @code{set verbose} command can turn these pauses into
messages if desired. @xref{Messages/Warnings}).

When the symbol table is stored in COFF format, @code{symbol-file} does
read the symbol table data in full right away.  We haven't implemented
the two-stage strategy for COFF yet.

When _GDBN__ is configured for a particular environment, it will
understand debugging information in whatever format is the standard
generated for that environment; you may use either a GNU compiler, or
other compilers that adhere to the local conventions.  Best results are
usually obtained from GNU compilers; for example, using @code{_GCC__}
you can generate debugging information for optimized code.

@item core-file @var{filename}
@itemx core @var{filename}
@kindex core
@kindex core-file
Specify the whereabouts of a core dump file to be used as the ``contents
of memory''.  Traditionally, core files contain only some parts of the
address space of the process that generated them; _GDBN__ can access the
executable file itself for other parts.

@code{core-file} with no argument specifies that no core file is
to be used.

Note that the core file is ignored when your program is actually running
under _GDBN__.  So, if you have been running the program and you wish to
debug a core file instead, you must kill the subprocess in which the
program is running.  To do this, use the @code{kill} command
(@pxref{Kill Process}).

@item load @var{filename}
@kindex load
_if__(_GENERIC__)
Depending on what remote debugging facilities are configured into
_GDBN__, the @code{load} command may be available.  Where it exists, it
is meant to make @var{filename} (an executable) available for debugging
on the remote system---by downloading, or dynamic linking, for example.
@code{load} also records @var{filename}'s symbol table in _GDBN__, like
the @code{add-symbol-file} command.

If @code{load} is not available on your _GDBN__, attempting to execute
it gets the error message ``@code{You can't do that when your target is
@dots{}}'' 
_fi__(_GENERIC__)

_if__(_VXWORKS__) 
On VxWorks, @code{load} will dynamically link @var{filename} on the
current target system as well as adding its symbols in _GDBN__.
_fi__(_VXWORKS__)

_if__(_I960__)
@cindex download to Nindy-960
With the Nindy interface to an Intel 960 board, @code{load} will
download @var{filename} to the 960 as well as adding its symbols in
_GDBN__. 
_fi__(_I960__)

@code{load} will not repeat if you press @key{RET} again after using it.

@item add-symbol-file @var{filename} @var{address}
@kindex add-symbol-file
@cindex dynamic linking
The @code{add-symbol-file} command reads additional symbol table information
from the file @var{filename}.  You would use this command when that file
has been dynamically loaded (by some other means) into the program that
is running.  @var{address} should be the memory address at which the
file has been loaded; _GDBN__ cannot figure this out for itself.

The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command.  You can use the
@code{add-symbol-file} command any number of times; the new symbol data thus
read keeps adding to the old.  To discard all old symbol data instead,
use the @code{symbol-file} command. 

@code{add-symbol-file} will not repeat if you press @key{RET} after using it.

@item info files
@itemx info target
@kindex info files
@kindex info target
@code{info files} and @code{info target} are synonymous; both print the
current targets (@pxref{Targets}), including the names of the executable
and core dump files currently in use by _GDBN__, and the files from
which symbols were loaded.  The command @code{help targets} lists all
possible targets rather than current ones.

@end table

All file-specifying commands allow both absolute and relative file names
as arguments.  _GDBN__ always converts the file name to an absolute path
name and remembers it that way.

@kindex sharedlibrary
@kindex share
@cindex shared libraries

_GDBN__ supports the SunOS shared library format.  Symbols from a shared
library cannot be referenced before the shared library has been linked
with the program.  (That is to say, until after you type @code{run} and 
the function @code{main} has been entered; or when examining core
files.)  Once the shared library has been linked in, you can use the
following commands:

@table @code
@item sharedlibrary @var{regex}
@itemx share @var{regex}
Load shared object library symbols for files matching a UNIX regular
expression.  

@item share
@itemx sharedlibrary
Load symbols for all shared libraries.

@item info share
@itemx info sharedlibrary
@kindex info sharedlibrary
@kindex info share
Print the names of the shared libraries which you have loaded with the
@code{sharedlibrary} command.
@end table

@code{sharedlibrary} does not repeat automatically when you press
@key{RET} after using it once.

@node Symbol Errors,  , Files, _GDBN__ Files
@section Errors Reading Symbol Files
While a symbol file is being read, _GDBN__ will occasionally encounter
problems, such as symbol types it does not recognize, or known bugs in
compiler output.  By default, it prints one message about each such
type of problem, no matter how many times the problem occurs.  You can
ask it to print more messages, to see how many times the problems occur,
or can shut the messages off entirely, with the @code{set 
complaints} command (@xref{Messages/Warnings}).

The messages currently printed, and their meanings, are:

@table @code
@item inner block not inside outer block in @var{symbol}

The symbol information shows where symbol scopes begin and end
(such as at the start of a function or a block of statements).  This
error indicates that an inner scope block is not fully contained
in its outer scope blocks.  

_GDBN__ circumvents the problem by treating the inner block as if it had
the same scope as the outer block.  In the error message, @var{symbol}
may be shown as ``@code{(don't know)}'' if the outer block is not a
function.

@item block at @var{address} out of order

The symbol information for symbol scope blocks should occur in 
order of increasing addresses.  This error indicates that it does not
do so.  

_GDBN__ does not circumvent this problem, and will have trouble locating
symbols in the source file whose symbols being read.  (You can often
determine what source file is affected by specifying @code{set verbose
on}.  @xref{Messages/Warnings}.)

@item bad block start address patched

The symbol information for a symbol scope block has a start address
smaller than the address of the preceding source line.  This is known
to occur in the SunOS 4.1.1 (and earlier) C compiler.  

_GDBN__ circumvents the problem by treating the symbol scope block as
starting on the previous source line.

@c @item{encountered DBX-style class variable debugging information.
@c You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
@c Therefore _GDBN__ will not know about your class variables}
@c 
@c This error indicates that the symbol information produced for a C++
@c program includes zero-size fields, which indicated static fields in
@c a previous release of the G++ compiler.  This message is probably
@c obsolete.
@c
@item bad string table offset in symbol @var{n}

@cindex foo
Symbol number @var{n} contains a pointer into the string table which is
larger than the size of the string table.  

_GDBN__ circumvents the problem by considering the symbol to have the
name @code{foo}, which may cause other problems if many symbols end up
with this name.

@item unknown symbol type @code{0x@var{nn}}

The symbol information contains new data types that _GDBN__ does not yet
know how to read.  @code{0x@var{nn}} is the symbol type of the misunderstood
information, in hexadecimal.  

_GDBN__ circumvents the error by ignoring this symbol information.  This
will usually allow the program to be debugged, though certain symbols
will not be accessible.  If you encounter such a problem and feel like
debugging it, you can debug @code{_GDBP__} with itself, breakpoint on
@code{complain}, then go up to the function @code{read_dbx_symtab} and
examine @code{*bufp} to see the symbol.

@item stub type has NULL name
_GDBN__ could not find the full definition for a struct or class. 

@ignore
@c this is #if 0'd in dbxread.c as of (at least!) 17 may 1991
@item const/volatile indicator missing, got '@var{X}'

The symbol information for a C++ member function is missing some
information that the compiler should have output for it.
@end ignore

@item C++ type mismatch between compiler and debugger

The debugger could not parse a type specification output by the compiler
for some C++ object.

@end table