*** empty log message ***

1 files changed, 221 insertions, 0 deletions

diff --git a/gdb/doc/gdb.bugs-m4 b/gdb/doc/gdb.bugs-m4
new file mode 100755
index 0000000..88ac09f
--- /dev/null
+++ b/gdb/doc/gdb.bugs-m4
@@ -0,0 +1,221 @@
+_dnl__ Copyright (c) 1990 1991 Free Software Foundation, Inc.
+_dnl__ This file is part of the source for the GDB manual.
+_dnl__ $Id$
+@node _GDBN__ Bugs, Renamed Commands, Emacs, Top
+@chapter Reporting Bugs in _GDBN__
+@cindex Bugs in _GDBN__
+@cindex Reporting Bugs in _GDBN__
+
+Your bug reports play an essential role in making _GDBN__ reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or it
+may not.  But in any case the principal function of a bug report is to help
+the entire community by making the next version of _GDBN__ work better.  Bug
+reports are your contribution to the maintenance of _GDBN__.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria::		Have You Found a Bug?
+* Bug Reporting::		How to Report Bugs
+@end menu
+
+@node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs
+@section Have You Found a Bug?
+@cindex Bug Criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@item
+@cindex Fatal Signal
+@cindex Core Dump
+If the debugger gets a fatal signal, for any input whatever, that is a
+_GDBN__ bug.  Reliable debuggers never crash.
+
+@item
+@cindex error on Valid Input
+If _GDBN__ produces an error message for valid input, that is a bug.
+
+@item
+@cindex Invalid Input
+If _GDBN__ does not produce an error message for invalid input,
+that is a bug.  However, you should note that your idea of
+``invalid input'' might be our idea of ``an extension'' or ``support
+for traditional practice''.
+
+@item
+If you are an experienced user of debugging tools, your suggestions
+for improvement of _GDBN__ are welcome in any case.
+@end itemize
+
+@node Bug Reporting,  , Bug Criteria, _GDBN__ Bugs
+@section How to Report Bugs
+@cindex Bug Reports
+@cindex Compiler Bugs, Reporting
+
+A number of companies and individuals offer support for GNU products.
+If you obtained _GDBN__ from a support organization, we recommend you
+contact that organization first. 
+
+Contact information for many support companies and individuals is
+available in the file @file{etc/SERVICE} in the GNU Emacs distribution.
+
+In any event, we also recommend that you send bug reports for _GDBN__ to one
+of these addresses:
+
+@example
+bug-gdb@@prep.ai.mit.edu
+@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
+@end example
+
+@strong{Do not send bug reports to @samp{info-gdb}, or to
+@samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to
+receive bug reports.  Those that do, have arranged to receive @samp{bug-gdb}.
+
+The mailing list @samp{bug-gdb} has a newsgroup which serves as a
+repeater.  The mailing list and the newsgroup carry exactly the same
+messages.  Often people think of posting bug reports to the newsgroup
+instead of mailing them.  This appears to work, but it has one problem
+which can be crucial: a newsgroup posting often lacks a mail path
+back to the sender.  Thus, if we need to ask for more information, we
+may be unable to reach you.  For this reason, it is better to send bug
+reports to the mailing list.
+
+As a last resort, send bug reports on paper to:
+
+@example
+GNU Debugger Bugs
+545 Tech Square
+Cambridge, MA 02139
+@end example
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}.  If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and assume that some details don't matter.  Thus, you might
+assume that the name of the variable you use in an example does not matter.
+Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
+stray memory reference which happens to fetch from the location where that
+name is stored in memory; perhaps, if the name were different, the contents
+of that location would fool the debugger into doing the right thing despite
+the bug.  Play it safe and give a specific, complete example.  That is the
+easiest thing for you to do, and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix
+the bug if it is new to us.  It isn't as important what happens if
+the bug is already known.  Therefore, always write your bug reports on
+the assumption that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?''  Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of _GDBN__.  _GDBN__ announces it if you start with no
+arguments; you can also print it at any time using @code{show version}.
+
+Without this, we won't know whether there is any point in looking for
+the bug in the current version of _GDBN__.
+
+@item
+A complete input script, and all necessary source files, that will
+reproduce the bug.  
+
+@item
+What compiler (and its version) was used to compile _GDBN__---e.g.
+``_GCC__-1.37.1''.
+
+@item
+The command arguments you gave the compiler to compile your example and
+observe the bug.  For example, did you use @samp{-O}?  To guarantee
+you won't omit something important, list them all.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect.  For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that _GDBN__ gets a fatal signal, then we will
+certainly notice it.  But if the bug is incorrect output, we might not
+notice unless it is glaringly wrong.  We are human, after all.  You
+might as well not give us a chance to make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly.  Suppose something strange is going on, such as,
+your copy of _GDBN__ is out of synch, or you have encountered a
+bug in the C library on your system.  (This has happened!)  Your copy
+might crash and ours would not.  If you told us to expect a crash,
+then when ours fails to crash, we would know that the bug was not
+happening for us.  If you had not told us to expect a crash, then we
+would not be able to draw any conclusion from our observations.
+
+@item
+If you wish to suggest changes to the _GDBN__ source, send us context
+diffs.  If you even discuss something in the _GDBN__ source, refer to
+it by context, not by line number.
+
+The line numbers in our development sources won't match those in your
+sources.  Your line numbers would convey no useful information to us.
+
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us.  Errors in the
+output will be easier to spot, running under the debugger will take
+less time, etc. 
+
+However, simplification is not vital; if you don't want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one.  But don't omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need.  We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as _GDBN__ it is very hard to
+construct an example that will make the program follow a certain path
+through the code.  If you don't send us the example, we won't be able
+to construct one, so we won't be able to verify that the bug is fixed.
+
+And if we can't understand what bug you are trying to fix, or why your
+patch should be an improvement, we won't install it.  A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong.  Even we can't guess right about such
+things without first using the debugger to find the facts.
+@end itemize