\input texinfo
@setfilename ld.info
-@c Copyright (C) 1991-2021 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-2021 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-2021 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:
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
@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
The recognized keywords are:
@table @samp
-@item bndplt
-Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
-
@item call-nop=prefix-addr
@itemx call-nop=suffix-nop
@itemx call-nop=prefix-@var{byte}
@item origin
Specify that the object requires @samp{$ORIGIN} handling in paths.
+@item pack-relative-relocs
+@itemx nopack-relative-relocs
+Generate compact relative relocation in position-independent executable
+and shared library. It adds @code{DT_RELR}, @code{DT_RELRSZ} and
+@code{DT_RELRENT} entries to the dynamic section. It is ignored when
+building position-dependent executable and relocatable output.
+@option{nopack-relative-relocs} is the default, which disables compact
+relative relocation. When linked against the GNU C Library, a
+GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is
+added to the output. Supported for i386 and x86-64.
+
@item relro
@itemx norelro
Create an ELF @code{PT_GNU_RELRO} segment header in the object. This
Treat all warnings as errors. The default behaviour can be restored
with the option @option{--no-fatal-warnings}.
+@kindex -w
+@kindex --no-warnings
+@item -w
+@itemx --no-warnings
+Do not display any warning or error messages. This overrides
+@option{--fatal-warnings} if it has been enabled. This option can be
+used when it is known that the output binary will not work, but there
+is still a need to create it.
+
@kindex --force-exe-suffix
@item --force-exe-suffix
Make sure that an output file has a .exe suffix.
@var{scriptname} whenever an error is encountered. Currently however
only two kinds of error are supported: missing symbols and missing
libraries. Two arguments will be passed to script: the keyword
-``undefined-symbol'' or `missing-lib'' and the @var{name} of the
+``undefined-symbol'' or `missing-lib'' and the @var{name} of the
undefined symbol or missing library. The intention is that the script
will provide suggestions to the user as to where the symbol or library
might be found. After the script has finished then the normal linker
On platforms where the feature is not supported, both @option{--relax}
and @option{--no-relax} are accepted, but ignored.
-
+
@cindex retaining specified symbols
@cindex stripping all but some symbols
@cindex symbols, retaining selectively
object file formats. For formats like COFF or ELF, the linker can not
detect the use of global constructors.
+@kindex --warn-execstack
+@cindex warnings, on executable stack
+@cindex executable stack, warnings on
+@item --warn-execstack
+@itemx --no-warn-execstack
+On ELF platforms this option controls how the linker generates warning
+messages when it creates an output file with an executable stack. By
+default the linker will not warn if the @command{-z execstack} command
+line option has been used, but this behaviour can be overridden by the
+@option{--warn-execstack} option.
+
+On the other hand the linker will normally warn if the stack is made
+executable because one or more of the input files need an execuable
+stack and neither of the @command{-z execstack} or @command{-z
+noexecstack} command line options have been specified. This warning
+can be disabled via the @command{--no-warn-execstack} option.
+
+Note: ELF format input files specify that they need an executable
+stack by having a @var{.note.GNU-stack} section with the executable
+bit set in its section flags. They can specify that they do not need
+an executable stack by having that section, but without the executable
+flag bit set. If an input file does not have a @var{.note.GNU-stack}
+section present then the default behaviour is target specific. For
+some targets, then absence of such a section implies that an
+executable stack @emph{is} required. This is often a problem for hand
+crafted assembler files.
+
@kindex --warn-multiple-gp
@item --warn-multiple-gp
Warn if multiple global pointer values are required in the output file.
Only warn once for each undefined symbol, rather than once per module
which refers to it.
+@kindex --warn-rwx-segments
+@cindex warnings, on writeable and exectuable segments
+@cindex executable segments, warnings on
+@item --warn-rwx-segments
+@itemx --no-warn-rwx-segments
+Warn if the linker creates a loadable, non-zero sized segment that has
+all three of the read, write and execute permission flags set. Such a
+segment represents a potential security vulnerability. In addition
+warnings will be generated if a thread local storage segment is
+created with the execute permission flag set, regardless of whether or
+not it has the read and/or write flags set.
+
+These warnings are enabled by default. They can be disabled via the
+@option{--no-warn-rwx-segments} option and re-enabled via the
+@option{--warn-rwx-segments} option.
+
@kindex --warn-section-align
@cindex warnings, on section alignment
@cindex section alignment, warnings on
@item --no-ld-generated-unwind-info
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.
+if linker generated unwind info is supported. This option also
+controls the generation of @code{.sframe} stack trace info for linker
+generated code sections like PLT.
@kindex --enable-new-dtags
@kindex --disable-new-dtags
@kindex --compress-debug-sections=zlib
@kindex --compress-debug-sections=zlib-gnu
@kindex --compress-debug-sections=zlib-gabi
+@kindex --compress-debug-sections=zstd
@item --compress-debug-sections=none
@itemx --compress-debug-sections=zlib
@itemx --compress-debug-sections=zlib-gnu
@itemx --compress-debug-sections=zlib-gabi
+@itemx --compress-debug-sections=zstd
On ELF platforms, these options control how DWARF debug sections are
compressed using zlib.
The @option{--compress-debug-sections=zlib} option is an alias for
@option{--compress-debug-sections=zlib-gabi}.
+@option{--compress-debug-sections=zstd} compresses DWARF debug sections using
+zstd.
+
Note that this option overrides any compression in input debug
sections, so if a binary is linked with @option{--compress-debug-sections=none}
for example, then any compressed debug sections in input files will be
Passing @code{none} for @var{style} disables the setting from any
@code{--build-id} options earlier on the command line.
+
+@kindex --package-metadata=@var{JSON}
+@item --package-metadata=@var{JSON}
+Request the creation of a @code{.note.package} ELF note section. The
+contents of the note are in JSON format, as per the package metadata
+specification. For more information see:
+https://systemd.io/ELF_PACKAGE_METADATA/
+If the JSON argument is missing/empty then this will disable the
+creation of the metadata note, if one had been enabled by an earlier
+occurrence of the --package-metdata option.
+If the linker has been built with libjansson, then the JSON string
+will be validated.
@end table
@c man end
@item
the address of the first byte of the code section, if present and an
executable is being created - the code section is usually
-@samp{.text}, but can be something else;
+@samp{.text}, but can be something else;
@item
The address @code{0}.
@end itemize
@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
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
-@itemx COPY
-@itemx INFO
-@itemx OVERLAY
+@item COPY
+@item INFO
+@item OVERLAY
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},
+@code{SHT_NOTE}, @code{SHT_NOBITS}, @code{SHT_INIT_ARRAY},
+@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
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