Fix: symbols eliminated by --gc-sections still trigger warnings for gnu.warning.SYM

PR 31067
  * linker.c (_bfd_generic_link_add_one_symbol): When issuing a warning message, also display a message about the warning not being affected by garbage colleciton.
  * ld.texi (Special Sections): New entry in the linker manual. Describes how the .gnu.warning and .gnu.warning.SYM sections behave.

bfd/ChangeLog

@@ -1,3 +1,10 @@
+2023-11-21  Nick Clifton  <nickc@redhat.com>
+
+	PR 31067
+	linker.c (_bfd_generic_link_add_one_symbol): When issuing a
+	warning message, also display a message about the warning not
+	being affected by garbage colleciton.
+
 2023-11-15  Arsen Arsenović  <arsen@aarsen.me>
 
 	* aclocal.m4: Regenerate.

bfd/linker.c

@@ -1784,6 +1784,14 @@ _bfd_generic_link_add_one_symbol (struct bfd_link_info *info,
 	    {
 	      (*info->callbacks->warning) (info, string, h->root.string,
 					   hash_entry_bfd (h), NULL, 0);
+	      /* PR 31067: If garbage collection is enabled then the
+		 referenced symbol may actually be discarded later on.
+		 This could be very confusing to the user.  So give them
+		 a hint as to what might be happening.  */
+	      if (info->gc_sections)
+		(*info->callbacks->info)
+		  (_("%P: %pB: note: the message above does not take linker garbage collection into account\n"),
+		   hash_entry_bfd (h));
 	      break;
 	    }
 	  /* Fall through.  */

ld/ChangeLog

@@ -1,3 +1,10 @@
+2023-11-21  Nick Clifton  <nickc@redhat.com>
+
+	PR 31067
+	* ld.texi (Special Sections): New entry in the linker manual.
+	Describes how the .gnu.warning and .gnu.warning.SYM sections
+	behave.
+
 2023-11-15  Arsen Arsenović  <arsen@aarsen.me>
 
 	* aclocal.m4: Regenerate.

ld/ld.texi

@@ -127,6 +127,7 @@ in the section entitled ``GNU Free Documentation License''.
 * Invocation::                  Invocation
 * Scripts::                     Linker Scripts
 * Plugins::                     Linker Plugins
+* Special Sections::            Special Sections
 @ifset GENERIC
 * Machine Dependent::           Machine Dependent Features
 @end ifset
@@ -7525,6 +7526,50 @@ the @samp{__.LIBDEP} member of @file{libssl.a} would contain
 -L/usr/local/lib -lcrypto
 @end smallexample
 
+@node Special Sections
+When linking ELF format object files @command{ld} treats some sections
+in a special, non standard manner.  This part of the manual describes
+these sections.
+
+@table @gcctabopt
+@item .gnu.warning
+The contents of any section with this name are assumed to be an ascii
+format warning message.  The contents will be displayed to the user if
+the sections appears in any input file, but the section will not be
+copied into the output image.  If the @option{--fatal-warnings} option
+is enabled then the warnings - if any are encountered - will also stop
+the link from completing.
+
+Note - the @samp{.gnu.warning} section is not subject to linker
+garbage collection or orphan handling.
+
+@item .gnu.warning.@var{SYM}
+The contents of any section whoes name starts with the prefix
+@samp{.gnu.warning.} and then finishes with the name of a symbol is
+treated in a similar fashion to the @samp{.gnu.warning} section, but
+only if the named symbol is defined.  So for example the contents of a
+section called @samp{.gnu.warning.foo} will be displayed as warning
+message if, and only if, the symbol @samp{foo} is defined by one or
+more of the input files.  This includes object files pulled in from
+static libraries, shared objects needed to complete the link and so
+on.
+
+Note - because these warning messages are generated before the linker
+performs garbage collection (if enabled) it is possible for a warning
+to be displayed for a symbol that is later removed and then never
+appears in the final output.
+
+@item .note.gnu.property
+When the linker combines sections of this name it will merge them
+together according to various rules encoded into the notes
+themselves.  Therefore the contents of the output .note.gnu.property
+section may not correspond to a simple concatenation of the input
+sections.  If the @option{-Map} option has been used to request a
+linker map then details of any property merging will be included in
+the map.
+
+@end table
+
 @ifset GENERIC
 @node Machine Dependent
 @chapter Machine Dependent Features