\input texinfo
@setfilename ld.info
-@c Copyright (C) 1991-2022 Free Software Foundation, Inc.
+@c Copyright (C) 1991-2023 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@end ifset
version @value{VERSION}.
-Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
@tex
{\parskip=0pt
\hfill Red Hat Inc\par
-\hfill nickc\@credhat.com, doc\@redhat.com\par
+\hfill nickc\@redhat.com, doc\@redhat.com\par
\hfill {\it The GNU linker}\par
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
}
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
-Copyright @copyright{} 1991-2022 Free Software Foundation, Inc.
+Copyright @copyright{} 1991-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
option is only meaningful on ELF platforms supporting the rtld-audit interface.
The -P option is provided for Solaris compatibility.
+@kindex --enable-linker-version
+@item --enable-linker-version
+Enables the @code{LINKER_VERSION} linker script directive, described
+in @ref{Output Section Data}. If this directive is used in a linker
+script and this option has been enabled then a string containing the
+linker version will be inserted at the current point.
+
+Note - this location of this option on the linker command line is
+significant. It will only affect linker scripts that come after it on
+the command line, or which are built into the linker.
+
+@kindex --disable-linker-version
+@item --disable-linker-version
+Disables the @code{LINKER_VERSION} linker script directive, so that it
+does not insert a version string. This is the default.
+
@kindex --enable-non-contiguous-regions
@item --enable-non-contiguous-regions
This option avoids generating an error if an input section does not
@smallexample
MEMORY @{
- MEM1 (rwx) : ORIGIN : 0x1000, LENGTH = 0x14
- MEM2 (rwx) : ORIGIN : 0x1000, LENGTH = 0x40
- MEM3 (rwx) : ORIGIN : 0x2000, LENGTH = 0x40
+ MEM1 (rwx) : ORIGIN = 0x1000, LENGTH = 0x14
+ MEM2 (rwx) : ORIGIN = 0x1000, LENGTH = 0x40
+ MEM3 (rwx) : ORIGIN = 0x2000, LENGTH = 0x40
@}
SECTIONS @{
mem1 : @{ *(.data.*); @} > MEM1
mem2 : @{ *(.data.*); @} > MEM2
- mem3 : @{ *(.data.*); @} > MEM2
+ mem3 : @{ *(.data.*); @} > MEM3
@}
with input sections:
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
@itemx --version
@itemx -V
Display the version number for @command{ld}. The @option{-V} option also
-lists the supported emulations.
+lists the supported emulations. See also the description of the
+@option{--enable-linker-version} in @ref{Options,,Command-line Options}
+which can be used to insert the linker version string into a binary.
@kindex -x
@kindex --discard-all
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
Request creation of @code{.eh_frame} unwind info for linker
generated code sections like PLT. This option is on by default
if linker generated unwind info is supported. This option also
-controls the generation of @code{.sframe} unwind info for linker
+controls the generation of @code{.sframe} stack trace info for linker
generated code sections like PLT.
@kindex --enable-new-dtags
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
@cindex data
@cindex section data
@cindex output section data
+@kindex ASCIZ ``@var{string}''
@kindex BYTE(@var{expression})
@kindex SHORT(@var{expression})
@kindex LONG(@var{expression})
true of, for example, S-records, the value will be stored in the
endianness of the first input object file.
+You can include a zero-terminated string in an output section by using
+@code{ASCIZ}. The keyword is followed by a string which is stored at
+the current value of the location counter adding a zero byte at the
+end. If the string includes spaces it must be enclosed in double
+quotes. The string may contain '\n', '\r', '\t' and octal numbers.
+Hex numbers are not supported.
+
+For example, this string of 16 characters will create a 17 byte area
+@smallexample
+ ASCIZ "This is 16 bytes"
+@end smallexample
+
Note---these commands only work inside a section description and not
between them, so the following will produce an error from the linker:
@smallexample
precedence. @xref{Output Section Fill}, for details on the fill
expression.
+@kindex LINKER_VERSION
+@cindex LINKER_VERSION
+Inserts a string containing the version of the linker at the current
+point. Note - by default this directive is disabled and will do
+nothing. It only becomes active if the
+@option{--enable-linker-version} command line option is used.
+
+Built-in linker scripts for ELF based targets already include this
+directive in their @samp{.comment} section.
+
@node Output Section Keywords
@subsection Output Section Keywords
There are a couple of keywords which can appear as output section
@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{}
Currently there is only one plugin shipped by default, but more may
be added here later.
+Plugins are enabled via the use of the @option{-plugin @var{name}}
+command line option. @xref{Options}.
+
@menu
* libdep Plugin:: Static Library Dependencies Plugin
@end menu
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