different option arguments to enter additional undefined symbols. This
option is equivalent to the @code{EXTERN} linker script command.
+If this option is being used to force additional modules to be pulled
+into the link, and if it is an error for the symbol to remain
+undefined, then the option @option{--require-defined} should be used
+instead.
+
+@kindex --require-defined=@var{symbol}
+@cindex symbols, require defined
+@cindex defined symbol
+@item --require-defined=@var{symbol}
+Require that @var{symbol} is defined in the output file. This option
+is the same as option @option{--undefined} except that if @var{symbol}
+is not defined in the output file then the linker will issue an error
+and exit. The same effect can be achieved in a linker script by using
+@code{EXTERN}, @code{ASSERT} and @code{DEFINED} together. This option
+can be used multiple times to require additional symbols.
+
@kindex -Ur
@cindex constructors
@item -Ur
be added to. Use @samp{-Ur} only for the last partial link, and
@samp{-r} for the others.
+@kindex --orphan-handling=@var{MODE}
+@cindex orphan sections
+@cindex sections, orphan
+@item --orphan-handling=@var{MODE}
+Control how orphan sections are handled. An orphan section is one not
+specifically mentioned in a linker script. @xref{Orphan Sections}.
+
+@var{MODE} can have any of the following values:
+
+@table @code
+@item place
+Orphan sections are placed into a suitable output section following
+the strategy described in @ref{Orphan Sections}. The option
+@samp{--unique} also effects how sections are placed.
+
+@item discard
+All orphan sections are discarded, by placing them in the
+@samp{/DISCARD/} section (@pxref{Output Section Discarding}).
+
+@item warn
+The linker will place the orphan section as for @code{place} and also
+issue a warning.
+
+@item error
+The linker will exit with an error if any orphan section is found.
+@end table
+
+The default if @samp{--orphan-handling} is not given is @code{place}.
+
@kindex --unique[=@var{SECTION}]
@item --unique[=@var{SECTION}]
Creates a separate output section for every input section matching
linker is normally correct; don't use this unless you know what you are
doing.
+@kindex --no-dynamic-linker
+@item --no-dynamic-linker
+When producing an executable file, omit the request for a dynamic
+linker to be used at load-time. This is only meaningful for ELF
+executables that contain dynamic relocations, and usually requires
+entry point code that is capable of processing these relocations.
+
@kindex --fatal-warnings
@kindex --no-fatal-warnings
@item --fatal-warnings
Enable garbage collection of unused input sections. It is ignored on
targets that do not support this option. The default behaviour (of not
performing this garbage collection) can be restored by specifying
-@samp{--no-gc-sections} on the command line.
+@samp{--no-gc-sections} on the command line. Note that garbage
+collection for COFF and PE format targets is supported, but the
+implementation is currently considered to be experimental.
@samp{--gc-sections} decides which input sections are used by
examining symbols and relocations. The section containing the entry
Only warn once for each undefined symbol, rather than once per module
which refers to it.
-@kindex --warn-orphan
-@kindex --no-warn-orphan
-@cindex warnings, on orphan sections
-@cindex orphan sections, warnings on
-@item --warn-orphan
-The @option{--warn-orphan} option tells the linker to generate a
-warning message whenever it has to place an orphan section into the
-output file. @xref{Orphan Sections} The @option{--no-warn-orphan}
-option restores the default behaviour of just silently placing these
-sections.
-
@kindex --warn-section-align
@cindex warnings, on section alignment
@cindex section alignment, warnings on
@itemx --compress-debug-sections=zlib-gabi
On ELF platforms , these options control how DWARF debug sections are
compressed using zlib. @option{--compress-debug-sections=none} doesn't
-compress DWARF debug sections. @option{--compress-debug-sections=zlib}
-and @option{--compress-debug-sections=zlib-gnu} compress DWARF debug
+compress DWARF debug sections.
+@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
sections and rename debug section names to begin with @samp{.zdebug}
-instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
-compresses DWARF debug sections with SHF_COMPRESSED from the ELF ABI.
+instead of @samp{.debug}. @option{--compress-debug-sections=zlib}
+and @option{--compress-debug-sections=zlib-gabi}
+compress DWARF debug sections with SHF_COMPRESSED from the ELF ABI.
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
@item --build-id
@itemx --build-id=@var{style}
Request the creation of a @code{.note.gnu.build-id} ELF note section
-or a @code{.build-id} COFF section. The contents of the note are
+or a @code{.buildid} COFF section. The contents of the note are
unique bits identifying this linked file. @var{style} can be
@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
@sc{SHA1} hash on the normative parts of the output contents,
@kindex --disable-long-section-names
@item --enable-long-section-names
@itemx --disable-long-section-names
-The PE variants of the Coff object format add an extension that permits
+The PE variants of the COFF object format add an extension that permits
the use of section names longer than eight characters, the normal limit
-for Coff. By default, these names are only allowed in object files, as
-fully-linked executable images do not carry the Coff string table required
+for COFF. By default, these names are only allowed in object files, as
+fully-linked executable images do not carry the COFF string table required
to support the longer names. As a GNU extension, it is possible to
allow their use in executable images as well, or to (probably pointlessly!)
disallow it in object files, by using these two options. Executable images
Insert a real timestamp into the image. This is the default behaviour
as it matches legacy code and it means that the image will work with
other, proprietary tools. The problem with this default is that it
-will result in slightly different images being produced each tiem the
+will result in slightly different images being produced each time the
same sources are linked. The option @option{--no-insert-timestamp}
can be used to insert a zero value for the timestamp, this ensuring
-that binaries produced from indentical sources will compare
+that binaries produced from identical sources will compare
identically.
@end table
@kindex --dsbt-size
@item --dsbt-size @var{size}
-This option sets the number of entires in the DSBT of the current executable
+This option sets the number of entries in the DSBT of the current executable
or shared library to @var{size}. The default is to create a table with 64
entries.
@smallexample
@group
start_of_ROM = .ROM;
- end_of_ROM = .ROM + sizeof (.ROM) - 1;
+ end_of_ROM = .ROM + sizeof (.ROM);
start_of_FLASH = .FLASH;
@end group
@end smallexample
@end smallexample
Note the use of the @samp{&} operators. These are correct.
+Alternatively the symbols can be treated as the names of vectors or
+arrays and then the code will again work as expected:
+
+@smallexample
+@group
+ extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
+
+ memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
+@end group
+@end smallexample
+
+Note how using this method does not require the use of @samp{&}
+operators.
@node SECTIONS
@section SECTIONS Command
regions that become too full. The linker will not shuffle sections
around to fit into the available regions.
-A linker script may contain at most one use of the @code{MEMORY}
-command. However, you can define as many blocks of memory within it as
-you wish. The syntax is:
+A linker script may contain many uses of the @code{MEMORY} command,
+however, all memory blocks defined are treated as if they were
+specified inside a single @code{MEMORY} command. The syntax for
+@code{MEMORY} is:
@smallexample
@group
MEMORY
For ELF targets, the attribute of the section includes section type as
well as section flag.
+The command line options @samp{--orphan-handling} and @samp{--unique}
+(@pxref{Options,,Command Line Options}) can be used to control which
+output sections an orphan is placed in.
+
If an orphaned section's name is representable as a C identifier then
the linker will automatically @pxref{PROVIDE} two symbols:
__start_SECNAME and __stop_SECNAME, where SECNAME is the name of the
doesn't change the value of the location counter---it just does
arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
expression to be aligned upwards (@code{ALIGN(@var{align})} is
-equivalent to @code{ALIGN(., @var{align})}).
+equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
Here is an example which aligns the output @code{.data} section to the
next @code{0x2000} byte boundary after the preceding section and sets a
@cindex PowerPC64 dot symbols
@kindex --dotsyms
@kindex --no-dotsyms
-@item --dotsyms, --no-dotsyms
+@item --dotsyms
+@itemx --no-dotsyms
These two options control how @command{ld} interprets version patterns
in a version script. Older PowerPC64 compilers emitted both a
function descriptor symbol with the same name as the function, and a
dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
feature.
+@cindex PowerPC64 register save/restore functions
+@kindex --save-restore-funcs
+@kindex --no-save-restore-funcs
+@item --save-restore-funcs
+@itemx --no-save-restore-funcs
+These two options control whether PowerPC64 @command{ld} automatically
+provides out-of-line register save and restore functions used by
+@samp{-Os} code. The default is to provide any such referenced
+function for a normal final link, and to not do so for a relocatable
+link.
+
@cindex PowerPC64 TLS optimization
@kindex --no-tls-optimize
@item --no-tls-optimize
sequences used to access Thread-Local Storage. Use this option to
disable the optimization.
+@cindex PowerPC64 __tls_get_addr optimization
+@kindex --tls-get-addr-optimize
+@kindex --no-tls-get-addr-optimize
+@item --tls-get-addr-optimize
+@itemx --no-tls-get-addr-optimize
+These options control whether PowerPC64 @command{ld} uses a special
+stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
+an optimization that allows the second and subsequent calls to
+@code{__tls_get_addr} for a given symbol to be resolved by the special
+stub without calling in to glibc. By default the linker enables this
+option when glibc advertises the availability of __tls_get_addr_opt.
+Forcing this option on when using an older glibc won't do much besides
+slow down your applications, but may be useful if linking an
+application against an older glibc with the expectation that it will
+normally be used on systems having a newer glibc.
+
@cindex PowerPC64 OPD optimization
@kindex --no-opd-optimize
@item --no-opd-optimize