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
@item bndplt
Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
+@item noextern-protected-data
+Don't treat protected data symbol as external when building shared
+library. This option overrides linker backend default. It can be used
+to workaround incorrect relocations against protected data symbols
+generated by compiler. Updates on protected data symbols by another
+module aren't visibile to the resulting shared library. Supported for
+i386 and x86-64.
+
@end table
Other keywords are ignored for Solaris compatibility.
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
other command-line options). This is the string that would appear
in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
+@kindex --print-memory-usage
+@cindex memory usage
+@item --print-memory-usage
+Print used size, total size and used size of memory regions created with
+the @ref{MEMORY} command. This is useful on embedded targets to have a
+quick view of amount of free memory. The format of the output has one
+headline and one line per region. It is both human readable and easily
+parsable by tools. Here is an example of an output:
+
+@smallexample
+Memory region Used Size Region Size %age Used
+ ROM: 256 KB 1 MB 25.00%
+ RAM: 32 B 2 GB 0.00%
+@end smallexample
+
@cindex help
@cindex usage
@kindex --help
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
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
hash tables. The default is @code{sysv}.
+@kindex --compress-debug-sections=none
+@kindex --compress-debug-sections=zlib
+@kindex --compress-debug-sections=zlib-gnu
+@kindex --compress-debug-sections=zlib-gabi
+@item --compress-debug-sections=none
+@itemx --compress-debug-sections=zlib
+@itemx --compress-debug-sections=zlib-gnu
+@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-gnu} compresses DWARF debug
+sections and rename debug section names to begin with @samp{.zdebug}
+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
This option reduces memory requirements at ld runtime, at the expense of
@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,
Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
with an error code, and print @var{message}.
+Note that assertions are checked before the final stages of linking
+take place. This means that expressions involving symbols PROVIDEd
+inside section definitions will fail if the user has not set values
+for those symbols. The only exception to this rule is PROVIDEd
+symbols that just reference dot. Thus an assertion like this:
+
+@smallexample
+ .stack :
+ @{
+ PROVIDE (__stack = .);
+ PROVIDE (__stack_size = 0x100);
+ ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+ @}
+@end smallexample
+
+will fail if @code{__stack_size} is not defined elsewhere. Symbols
+PROVIDEd outside of section definitions are evaluated earlier, so they
+can be used inside ASSERTions. Thus:
+
+@smallexample
+ PROVIDE (__stack_size = 0x100);
+ .stack :
+ @{
+ PROVIDE (__stack = .);
+ ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
+ @}
+@end smallexample
+
+will work.
+
@item EXTERN(@var{symbol} @var{symbol} @dots{})
@kindex EXTERN
@cindex undefined symbol in linker script
@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
projects / deliverable / binutils-gdb.git / blobdiff