RFC: Document unexpected behaviour of --fatal-warnings

[Nick Clifton <nickc@redhat.com>]

Hi Guys,

  It was recently pointed out to me that the bfd linker's
  --fatal-warnings option can behave in an unexpected manner.  For
  example:

    $ ld.bfd -z bad-option --fatal-warnings -e 0/dev/null
    ld.bfd: warning: -z bad-option ignored
    $ echo $?
    0

  ie the warning about the ignored option is not being treated as an
  error.  This happens because the --fatal-warnings option only takes
  affect after it has been processed, and we process the options in a
  linear order.  So the following works:

    $ ld.bfd --fatal-warnings -z bad-option -e 0 /dev/null
    ld.bfd: warning: -z bad-option ignored
    $ echo $?
    1

  This behaviour differs from gold and lld, both of which honour
  --fatal-warnings no matter where it occurs on the command line.

  So we could fix the linker, create a two pass argument scan and the
  problem would be solved.  But a) I am lazy and b) we already have a
  precedent for options on the command line only affecting options that
  come after it.  (I am thinking of the -L option here, although there
  are probably several others).  So instead I am considering documenting
  the current behaviour as expected.  (See the patch below).

  What do people think ?

Cheers
  Nick

diff --git a/ld/ld.texi b/ld/ld.texi
index 4fda259a552..16ab08e03f2 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1993,7 +1993,20 @@ in filename invoked by -R or --just-symbols
 @item --fatal-warnings
 @itemx --no-fatal-warnings
 Treat all warnings as errors.  The default behaviour can be restored
-with the option @option{--no-fatal-warnings}.
+with the option @option{--no-fatal-warnings}.  Note: this option does
+not affects warnings generated by other command line options that are
+placed before it on the command line.  So for example:
+
+@smallexample
+$ ld -z bad-option --fatal-warnings -e 0/dev/null
+ld: warning: -z bad-option ignored
+$ echo $?
+0
+$ ld --fatal-warnings -z bad-option -e 0 /dev/null
+ld: warning: -z bad-option ignored
+$ echo $?
+1
+@end smallexample
 
 @kindex -w
 @kindex --no-warnings