* gdb.texinfo: Document "complaints". Change doc of -q since

        gdb no longer prints the copyright and blurb if you specify a file
        name to be debugged (just like Emacs).  Add doc for Nindy-specific
        command line flags for specifying target serial port and such.
        Update copyright to 1991.

1 files changed, 136 insertions, 10 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 557516a..407a8cd 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -4,7 +4,7 @@
 @ifinfo
 This file documents the GNU debugger GDB.
 
-Copyright (C) 1988, 1989 Free Software Foundation, Inc.
+Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -54,7 +54,7 @@ original English.
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 1989, 1990 Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -698,6 +698,7 @@ uses @samp{/bin/sh}.
 
 The utility @samp{make} is often needed in development environments.
 You don't have to use the @samp{shell} command for this purpose in GDB:
+
 @table @code
 @item make @dots{}
 @kindex make
@@ -803,6 +804,25 @@ Disables GDB's output of certain informational messages.
 Displays whether @samp{set verbose} is on or off.
 @end table
 
+By default, if GDB encounters bugs in the symbol table of an object file,
+it prints a single message about each type of problem it finds, then 
+shuts up.  You can suppress these messages, or allow more than one such
+message to be printed if you want to see how frequent the problems are.
+@xref{File Commands}.
+
+@table @code
+@kindex set complaints
+@item set complaints @var{howmany}
+Permits GDB to output @var{howmany} complaints about each type of unusual
+symbols before becoming silent about the problem.  Set @var{howmany} to
+zero to suppress all complaints; set it to a large number to prevent
+complaints from being suppressed.
+
+@kindex show complaints
+@item show complaints
+Displays how many symbol complaints GDB is permitted to produce.
+@end table
+
 By default, GDB is cautious, and asks what sometimes seem to be a lot of
 stupid questions.  For example, if you try to run a program which is
 already running:
@@ -907,14 +927,15 @@ program's symbol table.
 
 The @samp{symbol-file} command causes GDB 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 GDB.
+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 GDB.
 
-On some systems, the @samp{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.
+On some kinds of object files, the @samp{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 GDB start up
 faster.  For the most part, it is invisible except for occasional pauses
@@ -926,6 +947,87 @@ When the symbol table is stored in COFF format, @samp{symbol-file} does
 read the symbol table data in full right away.  We haven't implemented
 the two-stage strategy for COFF yet.
 
+While the symbol file is being read, GDB 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 @samp{set 
+complaints} command (@xref{User Interface}).
+
+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.  GDB circumvents the problem by treating
+the inner block as if it had the same scope as the outer block.
+@var{symbol} may be ``(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.  GDB 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 turning on
+@samp{info verbose}.  @xref{User Interface}.)
+
+@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.  GDB circumvents
+the problem by treating the symbol scope block as starting on the
+previous source line.
+
+@comment @item{encountered DBX-style class variable debugging information.
+@comment You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
+@comment Therefore GDB will not know about your class variables}
+@comment 
+@comment This error indicates that the symbol information produced for a C++
+@comment program includes zero-size fields, which indicated static fields in
+@comment a previous release of the G++ compiler.  This message is probably
+@comment obsolete.
+@comment
+@item bad string table offset in symbol @var{n}
+
+Symbol number @var{n} contains a pointer into the string table which is
+larger than the size of the string table.  GDB 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.  @index{foo}
+
+@item unknown symbol type @code{0xNN}
+
+The symbol information contains new data types that GDB does not yet
+know how to read.  @code{0xNN} is the symbol type of the misunderstood
+information, in hexadecimal.  GDB 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 gdb
+with itself, breakpoint on "complain", then go "up" to
+read_dbx_symtab() and examine *bufp to see the symbol.
+
+@item stub type has NULL name
+
+FIXME, Mike Tiemann needs to write about what this means.
+
+@item const/volatile indicator missing, got 'X'
+
+The symbol information for a C++ type is missing some information that
+the compiler should have output for it.
+
+@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
+
 @item core-file @var{filename}
 @itemx core @var{filename}
 @kindex core
@@ -3916,7 +4018,9 @@ command options and arguments have been processed.  @xref{Command
 Files}.
 
 @item -q
-``Quiet''.  Do not print the usual introductory messages.
+``Quiet''.  Do not print the introductory and copyright messages.  These
+messages are also suppressed in batch mode, or if an executable file name is
+specified on the GDB command line.
 
 @item -batch
 Run in batch mode.  Exit with code 0 after processing all the command
@@ -3933,6 +4037,28 @@ like two @samp{\032} characters, followed by the file name, line number
 and character position separated by colons, and a newline.  The
 Emacs-to-GDB interface program uses the two @samp{\032} characters as
 a signal to display the source code for the frame.
+
+@item -b @samp{baudrate}
+Set the baud rate of any serial interface used by GDB (e.g. for remote
+debugging).
+
+@item -r @samp{port}
+Specify the serial port name of a serial interface to be used to connect
+to the target system's Nindy monitor.  (Nindy is the name of a ROM Monitor
+program for Intel 960 target systems.)  This option is only available when
+GDB is configured for the Intel 960 target architecture.
+
+@item -O
+Specify that GDB should use the ``old'' Nindy monitor protocol to connect
+to the target system.  This option is only available when GDB is configured
+for the Intel 960 target architecture.
+
+@item -brk
+Specify that GDB should first send a @samp{BREAK} signal to the target
+system, in an attempt to reset it, before connecting to a Nindy target.
+This option is only available when GDB is configured for the Intel 960
+target architecture.
+
 @end table
 
 @node File Options, Other Arguments, Mode Options, Options