[PATCH] ld/doc: Document interaction between unresolved-symbols

[Dimitri John Ledkov]

The --unresolved-symbols option is confusing, as setting it to the
default value report-all, can actually change behaviour and cause link
failures. This is because the implicit (unset) value of
unresolved-symbols can set both objects and shared libraries to either
the value of ignore-all or report-all, when -shared or -static options
are used. Inversally, setting `--unresolved-symbols` to any value
negates the implicit default of `-shared` or `-static`. Fun fact,
util-linux fails to link, when using autoconf build system as libpam
is not linked but is needed - and setting unresolved-symbols to the
default value of report-all breaks the build.

Reading documentation and using the options was not obvious as to what
effects it may have. Hence this patch tries to expand documentation to
call out the potentially unexpected interactions between `-shared`,
`-static` and `--unresolved-symbols`.

Signed-off-by: Dimitri John Ledkov <dimitri.ledkov@surgut.co.uk>
---
 ld/ld.texi | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/ld/ld.texi b/ld/ld.texi
index afcc3fea94f..bf87a9b2911 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -2662,7 +2662,9 @@ about any other sections, or memory regions, or anything else.
 Create a shared library.  This is currently only supported on ELF, XCOFF
 and SunOS platforms.  On SunOS, the linker will automatically create a
 shared library if the @option{-e} option is not used and there are
-undefined symbols in the link.
+undefined symbols in the link. This option also implies
+@option{--unresolved-symbols=ignore=all}, unless a different value was
+specified.
 
 @kindex --sort-common
 @item --sort-common
@@ -2866,15 +2868,16 @@ model, it will set the address of the first byte of the ldata segment.
 
 @kindex --unresolved-symbols
 @item --unresolved-symbols=@var{method}
-Determine how to handle unresolved symbols.  There are four possible
-values for @samp{method}:
+Determine how to handle unresolved symbols.  This option also disables
+implied default behaviour of @option{-static} and @option{-shared}.
+There are four possible values for @samp{method}:
 
 @table @samp
 @item ignore-all
-Do not report any unresolved symbols.
+Do not report any unresolved symbols. This is the implied default, if @option{-shared} is used.
 
 @item report-all
-Report all unresolved symbols.  This is the default.
+Report all unresolved symbols.  This is the implied default, unless @option{-shared} is used.
 
 @item ignore-in-object-files
 Report unresolved symbols that are contained in shared libraries, but
-- 
2.48.1