\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:
the specified name. When an executable is linked with a shared object
which has a DT_SONAME field, then when the executable is run the dynamic
linker will attempt to load the shared object specified by the DT_SONAME
-field rather than the using the file name given to the linker.
+field rather than using the file name given to the linker.
@kindex -i
@cindex incremental link
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}
to indicate compatibility with IBT. This also implies @option{ibtplt}.
Supported for Linux/i386 and Linux/x86_64.
+@item indirect-extern-access
+@itemx noindirect-extern-access
+Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in
+.note.gnu.property section to indicate that object file requires
+canonical function pointers and cannot be used with copy relocation.
+This option also implies @option{noextern-protected-data} and
+@option{nocopyreloc}. Supported for i386 and x86-64.
+
+@option{noindirect-extern-access} removes
+GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property
+section.
+
@item initfirst
This option is only meaningful when building a shared object.
It marks the object so that its runtime initialization will occur
@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
The @option{--reduce-memory-overheads} switch may be also be used to
enable other tradeoffs in future versions of the linker.
+@kindex --max-cache-size=@var{size}
+@item --max-cache-size=@var{size}
+@command{ld} normally caches the relocation information and symbol tables
+of input files in memory with the unlimited size. This option sets the
+maximum cache size to @var{size}.
+
@kindex --build-id
@kindex --build-id=@var{style}
@item --build-id
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
targets this is @code{start}, but PE- and BeOS-based systems for example
check a list of possible entry symbols, matching the first one found.
@item
-the address of the first byte of the @samp{.text} section, if present;
+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;
@item
The address @code{0}.
@end itemize
quotes the following character
@end table
-When a file name is matched with a wildcard, the wildcard characters
-will not match a @samp{/} character (used to separate directory names on
-Unix). A pattern consisting of a single @samp{*} character is an
-exception; it will always match any file name, whether it contains a
-@samp{/} or not. In a section name, the wildcard characters will match
-a @samp{/} character.
-
File name wildcard patterns only match files which are explicitly
specified on the command line or in an @code{INPUT} command. The linker
does not search directories to expand wildcards.
@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
@cindex expressions
@cindex arithmetic
The syntax for expressions in the linker script language is identical to
-that of C expressions. All expressions are evaluated as integers. All
-expressions are evaluated in the same size, which is 32 bits if both the
-host and target are 32 bits, and is otherwise 64 bits.
+that of C expressions, except that whitespace is required in some
+places to resolve syntactic ambiguities. All expressions are
+evaluated as integers. All expressions are evaluated in the same
+size, which is 32 bits if both the host and target are 32 bits, and is
+otherwise 64 bits.
You can use and set symbol values in expressions.
@end smallexample
@item SIZEOF_HEADERS
-@itemx sizeof_headers
@kindex SIZEOF_HEADERS
@cindex header size
Return the size in bytes of the output file's headers. This is
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
projects / binutils-gdb.git / blobdiff