*** empty log message ***

1 files changed, 300 insertions, 0 deletions

diff --git a/gdb/doc/gdb.files-m4 b/gdb/doc/gdb.files-m4
new file mode 100755
index 0000000..344a78b
--- /dev/null
+++ b/gdb/doc/gdb.files-m4
@@ -0,0 +1,300 @@
+_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.
+_dnl__ $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