Otherwise, the default emulation depends upon how the linker was
configured.
+@cindex remapping inputs
+@kindex --remap-inputs=@file{pattern}=@file{filename}
+@kindex --remap-inputs-file=@file{file}
+@item --remap-inputs=@file{pattern}=@file{filename}
+@itemx --remap-inputs-file=@file{file}
+These options allow the names of input files to be changed before the
+linker attempts to open them. The option
+@option{--remap-inputs=foo.o=bar.o} will cause any attempt to load a
+file called @file{foo.o} to instead try to load a file called
+@file{bar.o}. Wildcard patterns are permitted in the first filename,
+so @option{--remap-inputs=foo*.o=bar.o} will rename any input file that
+matches @file{foo*.o} to @file{bar.o}.
+
+An alternative form of the option
+@option{--remap-inputs-file=filename} allows the remappings to be read
+from a file. Each line in the file can contain a single remapping.
+Blank lines are ignored. Anything from a hash character (@samp{#}) to
+the end of a line is considered to be a comment and is also ignored.
+The mapping pattern can be separated from the filename by whitespace
+or an equals (@samp{=}) character.
+
+The options can be specified multiple times. Their contents
+accumulate. The remappings will be processed in the order in which
+they occur on the command line, and if they come from a file, in the
+order in which they occur in the file. If a match is made, no further
+checking for that filename will be performed.
+
+If the replacement filename is @file{/dev/null} or just @file{NUL}
+then the remapping will actually cause the input file to be ignored.
+This can be a convenient way to experiment with removing input files
+from a complicated build environment.
+
+Note that this option is position dependent and only affects filenames
+that come after it on the command line. Thus:
+
+@smallexample
+ ld foo.o --remap-inputs=foo.o=bar.o
+@end smallexample
+
+Will have no effect, whereas:
+
+@smallexample
+ ld --remap-inputs=foo.o=bar.o foo.o
+@end smallexample
+
+Will rename the input file @file{foo.o} to @file{bar.o}.
+
+Note - these options also affect files referenced by @emph{INPUT}
+statements in linker scripts. But since linker scripts are processed
+after the entire command line is read, the position of the remap
+options on the command line is not significant.
+
+If the @option{verbose} option is enabled then any mappings that match
+will be reported, although again the @option{verbose} option needs to
+be enabled on the command line @emph{before} the remaped filenames
+appear.
+
+If the @option{-Map} or @option{--print-map} options are enabled then
+the remapping list will be included in the map output.
+
@cindex link map
@kindex -M
@kindex --print-map
Print (or do not print) the list of discarded and garbage collected sections
in the link map. Enabled by default.
+@kindex --print-map-locals
+@kindex --no-print-map-locals
+@item --print-map-locals
+@itemx --no-print-map-locals
+Print (or do not print) local symbols in the link map. Local symbols
+will have the text @samp{(local)} printed before their name, and will
+be listed after all of the global symbols in a given section.
+Temporary local symbols (typically those that start with @samp{.L})
+will not be included in the output. Disabled by default.
+
@kindex -n
@cindex read-only text
@cindex NMAGIC
@item -T @var{scriptfile}
@itemx --script=@var{scriptfile}
Use @var{scriptfile} as the linker script. This script replaces
-@command{ld}'s default linker script (rather than adding to it), so
+@command{ld}'s default linker script (rather than adding to it),
+unless the script contains @code{INSERT}, so
@var{commandfile} must specify everything necessary to describe the
output file. @xref{Scripts}. If @var{scriptfile} does not exist in
the current directory, @code{ld} looks for it in the directories
@kindex -Ur
@cindex constructors
@item -Ur
-For anything other than C++ programs, this option is equivalent to
-@samp{-r}: it generates relocatable output---i.e., an output file that can in
-turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur}
-@emph{does} resolve references to constructors, unlike @samp{-r}.
-It does not work to use @samp{-Ur} on files that were themselves linked
-with @samp{-Ur}; once the constructor table has been built, it cannot
-be added to. Use @samp{-Ur} only for the last partial link, and
-@samp{-r} for the others.
+
+For programs that do not use constructors or destructors, or for ELF
+based systems this option is equivalent to @option{-r}: it generates
+relocatable output---i.e., an output file that can in turn serve as
+input to @command{ld}. For other binaries however the @option{-Ur}
+option is similar to @option{-r} but it also resolves references to
+constructors and destructors.
+
+For those systems where @option{-r} and @option{-Ur} behave
+differently, it does not work to use @option{-Ur} on files that were
+themselves linked with @option{-Ur}; once the constructor table has
+been built, it cannot be added to. Use @option{-Ur} only for the last
+partial link, and @option{-r} for the others.
@kindex --orphan-handling=@var{MODE}
@cindex orphan sections
@item max-page-size=@var{value}
Set the maximum memory page size supported to @var{value}.
+@item mark-plt
+@itemx nomark-plt
+Mark PLT entries with dynamic tags, DT_X86_64_PLT, DT_X86_64_PLTSZ and
+DT_X86_64_PLTENT. Since this option stores a non-zero value in the
+r_addend field of R_X86_64_JUMP_SLOT relocations, the resulting
+executables and shared libraries are incompatible with dynamic linkers,
+such as those in older versions of glibc without the change to ignore
+r_addend in R_X86_64_GLOB_DAT and R_X86_64_JUMP_SLOT relocations, which
+don't ignore the r_addend field of R_X86_64_JUMP_SLOT relocations.
+Supported for x86_64.
+
@item muldefs
Allow multiple definitions.
Report dynamic relative relocations generated by linker. Supported for
Linux/i386 and Linux/x86_64.
+@item sectionheader
+@itemx nosectionheader
+Generate section header. Don't generate section header if
+@samp{nosectionheader} is used. @option{sectionheader} is the default.
+
@item separate-code
@itemx noseparate-code
Create separate code @code{PT_LOAD} segment header in the object. This
that binaries produced from identical sources will compare
identically.
+If @option{--insert-timestamp} is active then the time inserted is
+either the time that the linking takes place or, if the
+@code{SOURCE_DATE_EPOCH} environment variable is defined, the number
+of seconds since Unix epoch as specified by that variable.
+
@kindex --enable-reloc-section
@item --enable-reloc-section
@itemx --disable-reloc-section
INSERT AFTER .text;
@end smallexample
+Note that when @samp{-T} is used twice, once to override the default
+script and once to augment that script using @code{INSERT} the order
+of parsing and section assignments apply as for the default script.
+The script with @code{INSERT} should be specified @emph{first} on the
+command line.
+
@item NOCROSSREFS(@var{section} @var{section} @dots{})
@kindex NOCROSSREFS(@var{sections})
@cindex cross references
@ifnottex
@c END TEXI2ROFF-KILL
@smallexample
-precedence associativity Operators Notes
+precedence associativity Operators Notes
(highest)
-1 left ! - ~ (1)
+1 left ! - ~ (1)
2 left * / %
3 left + -
4 left >> <<
-5 left == != > < <= >=
-6 left &
-7 left |
-8 left &&
-9 left ||
-10 right ? :
-11 right &= += -= *= /= (2)
+5 left > < <= >=
+6 left == !=
+7 left &
+8 left ^
+9 left |
+10 left &&
+11 left ||
+12 right ? :
+13 right += -= *= /= <<= >>= &= |= ^= (2)
(lowest)
@end smallexample
Notes:
&2&&left&&* / \%&\cr
&3&&left&&+ -&\cr
&4&&left&&>> <<&\cr
-&5&&left&&== != > < <= >=&\cr
-&6&&left&&\&&\cr
-&7&&left&&|&\cr
-&8&&left&&{\&\&}&\cr
-&9&&left&&||&\cr
-&10&&right&&? :&\cr
-&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
+&5&&left&& > < <= >=&\cr
+&6&&left&&== !=&\cr
+&7&&left&&\&&\cr
+&8&&left&&\^{}&\cr
+&9&&left&&|&\cr
+&10&&left&&{\&\&}&\cr
+&11&&left&&||&\cr
+&12&&right&&? :&\cr
+&13&&right&&\qquad += -= *= /= <<= >>= \&= |= \^{}=\qquad\ddag&\cr
&lowest&&&&&\cr
height2pt&\omit&&\omit&&\omit&\cr}
\hrule}
@kindex ALIGNOF(@var{section})
@cindex section alignment
Return the alignment in bytes of the named @var{section}, if that section has
-been allocated. If the section has not been allocated when this is
-evaluated, the linker will report an error. In the following example,
-the alignment of the @code{.output} section is stored as the first
-value in that section.
+been allocated, or zero if the section has not been allocated. If the
+section does not exist in the linker script the linker will report an
+error. If @var{section} is @code{NEXT_SECTION} then @code{ALIGNOF} will
+return the alignment of the next allocated section specified in the
+linker script, or zero if there is no such section. In the following
+example, the alignment of the @code{.output} section is stored as the
+first value in that section.
@smallexample
@group
SECTIONS@{ @dots{}
@kindex SIZEOF(@var{section})
@cindex section size
Return the size in bytes of the named @var{section}, if that section has
-been allocated. If the section has not been allocated when this is
-evaluated, the linker will report an error. In the following example,
-@code{symbol_1} and @code{symbol_2} are assigned identical values:
+been allocated, or zero if the section has not been allocated. If the
+section does not exist in the linker script the linker will report an
+error. If @var{section} is @code{NEXT_SECTION} then @code{SIZEOF} will
+return the alignment of the next allocated section specified in the
+linker script, or zero if there is no such section. In the following
+example, @code{symbol_1} and @code{symbol_2} are assigned identical
+values:
@smallexample
@group
SECTIONS@{ @dots{}
support for creating such libraries provided with the
@samp{--out-implib} command-line option.
+@item Resource only DLLs
+It is possible to create a DLL that only contains resources, ie just a
+@samp{.rsrc} section, but in order to do so a custom linker script
+must be used. This is because the built-in default linker scripts
+will always create @samp{.text} and @samp{.idata} sections, even if
+there is no input to go into them.
+
+The script should look like this, although the @code{OUTPUT_FORMAT}
+should be changed to match the desired format.
+
+@example
+OUTPUT_FORMAT(pei-i386)
+SECTIONS
+@{
+ . = SIZEOF_HEADERS;
+ . = ALIGN(__section_alignment__);
+ .rsrc __image_base__ + __section_alignment__ : ALIGN(4)
+ @{
+ KEEP (*(.rsrc))
+ KEEP (*(.rsrc$*))
+ @}
+ /DISCARD/ : @{ *(*) @}
+@}
+@end example
+
+With this script saved to a file called, eg @file{rsrc.ld}, a command
+line like this can be used to create the resource only DLL
+@file{rsrc.dll} from an input file called @file{rsrc.o}:
+
+@smallexample
+ld -dll --subsystem windows -e 0 -s rsrc.o -o rsrc.dll -T rsrc.ld
+@end smallexample
+
@item exporting DLL symbols
@cindex exporting DLL symbols
The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
projects / binutils-gdb.git / blobdiff