Update the description of the linker script's TYPE directive.

	PR 29861
	* ld.texi (Output Section Type): Note that setting the output
	section type only works if the section contains untyped data.

1 files changed, 24 insertions, 0 deletions

diff --git a/ld/ld.texi b/ld/ld.texi
index 3836465730c..9b937f0c072 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -5548,11 +5548,14 @@ Each output section may have a type.  The type is a keyword in
 parentheses.  The following types are defined:
 
 @table @code
+
 @item NOLOAD
 The section should be marked as not loadable, so that it will not be
 loaded into memory when the program is run.
+
 @item READONLY
 The section should be marked as read-only.
+
 @item DSECT
 @item COPY
 @item INFO
@@ -5561,6 +5564,7 @@ These type names are supported for backward compatibility, and are
 rarely used.  They all have the same effect: the section should be
 marked as not allocatable, so that no memory is allocated for the
 section when the program is run.
+
 @item TYPE = @var{type}
 Set the section type to the integer @var{type}. When generating an ELF
 output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
@@ -5568,9 +5572,29 @@ output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
 @code{SHT_FINI_ARRAY}, and @code{SHT_PREINIT_ARRAY} are also allowed
 for @var{type}.  It is the user's responsibility to ensure that any
 special requirements of the section type are met.
+
+Note - the TYPE only is used if some or all of the contents of the
+section do not have an implicit type of their own.  So for example:
+@smallexample
+  .foo . TYPE = SHT_PROGBITS @{ *(.bar) @}
+@end smallexample
+will set the type of section @samp{.foo} to the type of the section
+@samp{.bar} in the input files, which may not be the SHT_PROGBITS
+type.  Whereas:
+@smallexample
+  .foo . TYPE = SHT_PROGBITS @{ BYTE(1) @}
+@end smallexample
+will set the type of @samp{.foo} to SHT_PROGBBITS.  If it is necessary
+to override the type of incoming sections and force the output section
+type then an extra piece of untyped data will be needed:
+@smallexample
+  .foo . TYPE = SHT_PROGBITS @{ BYTE(1); *(.bar) @}
+@end smallexample
+
 @item READONLY ( TYPE = @var{type} )
 This form of the syntax combines the @var{READONLY} type with the
 type specified by @var{type}.
+
 @end table
 
 @kindex NOLOAD