-_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
projects / deliverable / binutils-gdb.git / blobdiff