compiler driver) like this:
@smallexample
- gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+ gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
@end smallexample
This is important, because otherwise the compiler driver program may
-silently drop the linker options, resulting in a bad link.
+silently drop the linker options, resulting in a bad link. Confusion
+may also arise when passing options that require values through a
+driver, as the use of a space between option and argument acts as
+a separator, and causes the driver to pass only the option to the linker
+and the argument to the compiler. In this case, it is simplest to use
+the joined forms of both single- and multiple-letter options, such as:
+
+@smallexample
+ gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
+@end smallexample
Here is a table of the generic command line switches accepted by the GNU
linker:
@table @gcctabopt
@include at-file.texi
-@kindex -a@var{keyword}
-@item -a@var{keyword}
+@kindex -a @var{keyword}
+@item -a @var{keyword}
This option is supported for HP/UX compatibility. The @var{keyword}
argument must be one of the strings @samp{archive}, @samp{shared}, or
@samp{default}. @samp{-aarchive} is functionally equivalent to
@ifset I960
@cindex architectures
-@kindex -A@var{arch}
-@item -A@var{architecture}
+@kindex -A @var{arch}
+@item -A @var{architecture}
@kindex --architecture=@var{arch}
@itemx --architecture=@var{architecture}
In the current release of @command{ld}, this option is useful only for the
be added to the dynamic symbol table if the output format supports it.
See the description of @samp{--dynamic-list}.
+Note that this option is specific to ELF targeted ports. PE targets
+support a similar function to export all symbols from a DLL or EXE; see
+the description of @samp{--export-all-symbols} below.
+
@ifclear SingleFormat
@cindex big-endian objects
@cindex endianness
Link little-endian objects. This affects the default output format.
@end ifclear
-@kindex -f
-@kindex --auxiliary
-@item -f
-@itemx --auxiliary @var{name}
+@kindex -f @var{name}
+@kindex --auxiliary=@var{name}
+@item -f @var{name}
+@itemx --auxiliary=@var{name}
When creating an ELF shared object, set the internal DT_AUXILIARY field
to the specified name. This tells the dynamic linker that the symbol
table of the shared object should be used as an auxiliary filter on the
This option may be specified more than once. The DT_AUXILIARY entries
will be created in the order in which they appear on the command line.
-@kindex -F
-@kindex --filter
+@kindex -F @var{name}
+@kindex --filter=@var{name}
@item -F @var{name}
-@itemx --filter @var{name}
+@itemx --filter=@var{name}
When creating an ELF shared object, set the internal DT_FILTER field to
the specified name. This tells the dynamic linker that the symbol table
of the shared object which is being created should be used as a filter
creating an ELF shared object.
@cindex finalization function
-@kindex -fini
-@item -fini @var{name}
+@kindex -fini=@var{name}
+@item -fini=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is unloaded, by setting DT_FINI to the
address of the function. By default, the linker uses @code{_fini} as
@item -g
Ignored. Provided for compatibility with other tools.
-@kindex -G
-@kindex --gpsize
+@kindex -G @var{value}
+@kindex --gpsize=@var{value}
@cindex object size
-@item -G@var{value}
+@item -G @var{value}
@itemx --gpsize=@var{value}
Set the maximum size of objects to be optimized using the GP register to
@var{size}. This is only meaningful for object file formats such as
sections. This is ignored for other object file formats.
@cindex runtime library name
-@kindex -h@var{name}
+@kindex -h @var{name}
@kindex -soname=@var{name}
-@item -h@var{name}
+@item -h @var{name}
@itemx -soname=@var{name}
When creating an ELF shared object, set the internal DT_SONAME field to
the specified name. When an executable is linked with a shared object
Perform an incremental link (same as option @samp{-r}).
@cindex initialization function
-@kindex -init
-@item -init @var{name}
+@kindex -init=@var{name}
+@item -init=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is loaded, by setting DT_INIT to the address
of the function. By default, the linker uses @code{_init} as the
function to call.
@cindex archive files, from cmd line
-@kindex -l@var{namespec}
+@kindex -l @var{namespec}
@kindex --library=@var{namespec}
-@item -l@var{namespec}
+@item -l @var{namespec}
@itemx --library=@var{namespec}
Add the archive or object file specified by @var{namespec} to the
list of files to link. This option may be used any number of times.
@end ifset
@cindex search directory, from cmd line
-@kindex -L@var{dir}
+@kindex -L @var{dir}
@kindex --library-path=@var{dir}
-@item -L@var{searchdir}
+@item -L @var{searchdir}
@itemx --library-path=@var{searchdir}
Add path @var{searchdir} to the list of paths that @command{ld} will search
for archive libraries and @command{ld} control scripts. You may use this
in which they are specified on the command line. Directories specified
on the command line are searched before the default directories. All
@option{-L} options apply to all @option{-l} options, regardless of the
-order in which the options appear.
+order in which the options appear. @option{-L} options do not affect
+how @command{ld} searches for a linker script unless @option{-T}
+option is specified.
If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
by the @dfn{sysroot prefix}, a path specified when the linker is configured.
@cindex emulation
@kindex -m @var{emulation}
-@item -m@var{emulation}
+@item -m @var{emulation}
Emulate the @var{emulation} linker. You can list the available
emulations with the @samp{--verbose} or @samp{-V} options.
paths for runtime symbol resolution.
@cindex symbols, from command line
-@kindex --defsym @var{symbol}=@var{exp}
-@item --defsym @var{symbol}=@var{expression}
+@kindex --defsym=@var{symbol}=@var{exp}
+@item --defsym=@var{symbol}=@var{expression}
Create a global symbol in the output file, containing the absolute
address given by @var{expression}. You may use this option as many
times as necessary to define multiple symbols in the command line. A
@cindex dynamic linker, from command line
@kindex -I@var{file}
-@kindex --dynamic-linker @var{file}
-@item --dynamic-linker @var{file}
+@kindex --dynamic-linker=@var{file}
+@item -I@var{file}
+@itemx --dynamic-linker=@var{file}
Set the name of the dynamic linker. This is only meaningful when
generating dynamically linked ELF executables. The default dynamic
linker is normally correct; don't use this unless you know what you are
@item --target-help
Print a summary of all target specific options on the standard output and exit.
-@kindex -Map
-@item -Map @var{mapfile}
+@kindex -Map=@var{mapfile}
+@item -Map=@var{mapfile}
Print a link map to the file @var{mapfile}. See the description of the
@option{-M} option, above.
(including linker scripts specified on the command line) are ignored.
@ifclear SingleFormat
-@kindex --oformat
-@item --oformat @var{output-format}
+@kindex --oformat=@var{output-format}
+@item --oformat=@var{output-format}
@command{ld} may be configured to support more than one kind of object
file. If your @command{ld} is configured this way, you can use the
@samp{--oformat} option to specify the binary format for the output
@cindex retaining specified symbols
@cindex stripping all but some symbols
@cindex symbols, retaining selectively
-@item --retain-symbols-file @var{filename}
+@kindex --retain-symbols-file=@var{filename}
+@item --retain-symbols-file=@var{filename}
Retain @emph{only} the symbols listed in the file @var{filename},
discarding all others. @var{filename} is simply a flat file, with one
symbol name per line. This option is especially useful in environments
line. It overrides @samp{-s} and @samp{-S}.
@ifset GENERIC
-@item -rpath @var{dir}
+@item -rpath=@var{dir}
@cindex runtime library search path
-@kindex -rpath
+@kindex -rpath=@var{dir}
Add a directory to the runtime library search path. This is used when
linking an ELF executable with shared objects. All @option{-rpath}
arguments are concatenated and passed to the runtime linker, which uses
@ifset GENERIC
@cindex link-time runtime library search path
-@kindex -rpath-link
-@item -rpath-link @var{DIR}
+@kindex -rpath-link=@var{dir}
+@item -rpath-link=@var{dir}
When using ELF or SunOS, one shared library may require another. This
happens when an @code{ld -shared} link includes a shared library as one
of the input files.
shared library if the @option{-e} option is not used and there are
undefined symbols in the link.
-@item --sort-common [= ascending | descending]
@kindex --sort-common
+@item --sort-common
+@itemx --sort-common=ascending
+@itemx --sort-common=descending
This option tells @command{ld} to sort the common symbols by alignment in
ascending or descending order when it places them in the appropriate output
sections. The symbol alignments considered are sixteen-byte or larger,
between symbols due to alignment constraints. If no sorting order is
specified, then descending order is assumed.
-@kindex --sort-section name
-@item --sort-section name
+@kindex --sort-section=name
+@item --sort-section=name
This option will apply @code{SORT_BY_NAME} to all wildcard section
patterns in the linker script.
-@kindex --sort-section alignment
-@item --sort-section alignment
+@kindex --sort-section=alignment
+@item --sort-section=alignment
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
patterns in the linker script.
@kindex --split-by-file
-@item --split-by-file [@var{size}]
+@item --split-by-file[=@var{size}]
Similar to @option{--split-by-reloc} but creates a new output section for
each input file when @var{size} is reached. @var{size} defaults to a
size of 1 if not given.
@kindex --split-by-reloc
-@item --split-by-reloc [@var{count}]
+@item --split-by-reloc[=@var{count}]
Tries to creates extra sections in the output file so that no single
output section in the file contains more than @var{count} relocations.
This is useful when generating huge relocatable files for downloading into
Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
-@kindex --sysroot
+@kindex --sysroot=@var{directory}
@item --sysroot=@var{directory}
Use @var{directory} as the location of the sysroot, overriding the
configure-time default. This option is only supported by linkers
trouble). The @samp{--traditional-format} switch tells @command{ld} to not
combine duplicate entries.
-@kindex --section-start @var{sectionname}=@var{org}
-@item --section-start @var{sectionname}=@var{org}
+@kindex --section-start=@var{sectionname}=@var{org}
+@item --section-start=@var{sectionname}=@var{org}
Locate a section in the output file at the absolute
address given by @var{org}. You may use this option as many
times as necessary to locate multiple sections in the command
should be no white space between @var{sectionname}, the equals
sign (``@key{=}''), and @var{org}.
-@kindex -Tbss @var{org}
-@kindex -Tdata @var{org}
-@kindex -Ttext @var{org}
+@kindex -Tbss=@var{org}
+@kindex -Tdata=@var{org}
+@kindex -Ttext=@var{org}
@cindex segment origins, cmd line
-@item -Tbss @var{org}
-@itemx -Tdata @var{org}
-@itemx -Ttext @var{org}
-Same as --section-start, with @code{.bss}, @code{.data} or
+@item -Tbss=@var{org}
+@itemx -Tdata=@var{org}
+@itemx -Ttext=@var{org}
+Same as @option{--section-start}, with @code{.bss}, @code{.data} or
@code{.text} as the @var{sectionname}.
-@kindex -Ttext-segment @var{org}
-@itemx -Ttext-segment @var{org}
+@kindex -Ttext-segment=@var{org}
+@item -Ttext-segment=@var{org}
@cindex text segment origin, cmd line
When creating an ELF executable or shared object, it will set the address
of the first byte of the text segment.
@kindex --version-script=@var{version-scriptfile}
@cindex version script, symbol versions
-@itemx --version-script=@var{version-scriptfile}
+@item --version-script=@var{version-scriptfile}
Specify the name of a version script to the linker. This is typically
used when creating shared libraries to specify additional information
about the version hierarchy for the library being created. This option
@item --warn-shared-textrel
Warn if the linker adds a DT_TEXTREL to a shared object.
+@kindex --warn-alternate-em
+@item --warn-alternate-em
+Warn if an object has alternate ELF machine code.
+
@kindex --warn-unresolved-symbols
@item --warn-unresolved-symbols
If the linker is going to report an unresolved symbol (see the option
list of archives, because gcc will add its own list of archives to
your link and you may not want this flag to affect those as well.
-@kindex --wrap
-@item --wrap @var{symbol}
+@kindex --wrap=@var{symbol}
+@item --wrap=@var{symbol}
Use a wrapper function for @var{symbol}. Any undefined reference to
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
undefined reference to @code{__real_@var{symbol}} will be resolved to
disallow it in object files, by using these two options. Executable images
generated with these long section names are slightly non-standard, carrying
as they do a string table, and may generate confusing output when examined
-with non-GNU PE-aware tools, such as file viewers and dumpers.
+with non-GNU PE-aware tools, such as file viewers and dumpers. However,
+GDB relies on the use of PE long section names to find Dwarf-2 debug
+information sections in an executable image at runtime, and so if neither
+option is specified on the command-line, @command{ld} will enable long
+section names, overriding the default and technically correct behaviour,
+when it finds the presence of debug information while linking an executable
+image and not stripping symbols.
[This option is valid for all PE targeted ports of the linker]
@kindex --enable-stdcall-fixup
@var{which}.
[This option is specific to the i386 PE targeted port of the linker]
+The following options set flags in the @code{DllCharacteristics} field
+of the PE file header:
+[These options are specific to PE targeted ports of the linker]
+
+@kindex --dynamicbase
+@item --dynamicbase
+The image base address may be relocated using address space layout
+randomization (ASLR). This feature was introduced with MS Windows
+Vista for i386 PE targets.
+
+@kindex --forceinteg
+@item --forceinteg
+Code integrity checks are enforced.
+
+@kindex --nxcompat
+@item --nxcompat
+The image is compatible with the Data Execution Prevention.
+This feature was introduced with MS Windows XP SP2 for i386 PE targets.
+
+@kindex --no-isolation
+@item --no-isolation
+Although the image understands isolation, do not isolate the image.
+
+@kindex --no-seh
+@item --no-seh
+The image does not use SEH. No SE handler may be called from
+this image.
+
+@kindex --no-bind
+@item --no-bind
+Do not bind this image.
+
+@kindex --wdmdriver
+@item --wdmdriver
+The driver uses the MS Windows Driver Model.
+
+@kindex --tsaware
+@item --tsaware
+The image is Terminal Server aware.
+
@end table
@c man end
* Format Commands:: Commands dealing with object file formats
@end ifclear
+* REGION_ALIAS:: Assign alias names to memory regions
* Miscellaneous Commands:: Other linker script commands
@end menu
@end table
@end ifclear
+@node REGION_ALIAS
+@subsection Assign alias names to memory regions
+@kindex REGION_ALIAS(@var{alias}, @var{region})
+@cindex region alias
+@cindex region names
+
+Alias names can be added to existing memory regions created with the
+@ref{MEMORY} command. Each name corresponds to at most one memory region.
+
+@smallexample
+REGION_ALIAS(@var{alias}, @var{region})
+@end smallexample
+
+The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
+memory region @var{region}. This allows a flexible mapping of output sections
+to memory regions. An example follows.
+
+Suppose we have an application for embedded systems which come with various
+memory storage devices. All have a general purpose, volatile memory @code{RAM}
+that allows code execution or data storage. Some may have a read-only,
+non-volatile memory @code{ROM} that allows code execution and read-only data
+access. The last variant is a read-only, non-volatile memory @code{ROM2} with
+read-only data access and no code execution capability. We have four output
+sections:
+
+@itemize @bullet
+@item
+@code{.text} program code;
+@item
+@code{.rodata} read-only data;
+@item
+@code{.data} read-write initialized data;
+@item
+@code{.bss} read-write zero initialized data.
+@end itemize
+
+The goal is to provide a linker command file that contains a system independent
+part defining the output sections and a system dependent part mapping the
+output sections to the memory regions available on the system. Our embedded
+systems come with three different memory setups @code{A}, @code{B} and
+@code{C}:
+@multitable @columnfractions .25 .25 .25 .25
+@item Section @tab Variant A @tab Variant B @tab Variant C
+@item .text @tab RAM @tab ROM @tab ROM
+@item .rodata @tab RAM @tab ROM @tab ROM2
+@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
+@item .bss @tab RAM @tab RAM @tab RAM
+@end multitable
+The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
+loaded into region @code{ROM} or @code{ROM2} respectively. Please note that
+the load address of the @code{.data} section starts in all three variants at
+the end of the @code{.rodata} section.
+
+The base linker script that deals with the output sections follows. It
+includes the system dependent @code{linkcmds.memory} file that describes the
+memory layout:
+@smallexample
+INCLUDE linkcmds.memory
+
+SECTIONS
+ @{
+ .text :
+ @{
+ *(.text)
+ @} > REGION_TEXT
+ .rodata :
+ @{
+ *(.rodata)
+ rodata_end = .;
+ @} > REGION_RODATA
+ .data : AT (rodata_end)
+ @{
+ data_start = .;
+ *(.data)
+ @} > REGION_DATA
+ data_size = SIZEOF(.data);
+ data_load_start = LOADADDR(.data);
+ .bss :
+ @{
+ *(.bss)
+ @} > REGION_BSS
+ @}
+@end smallexample
+
+Now we need three different @code{linkcmds.memory} files to define memory
+regions and alias names. The content of @code{linkcmds.memory} for the three
+variants @code{A}, @code{B} and @code{C}:
+@table @code
+@item A
+Here everything goes into the @code{RAM}.
+@smallexample
+MEMORY
+ @{
+ RAM : ORIGIN = 0, LENGTH = 4M
+ @}
+
+REGION_ALIAS("REGION_TEXT", RAM);
+REGION_ALIAS("REGION_RODATA", RAM);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@item B
+Program code and read-only data go into the @code{ROM}. Read-write data goes
+into the @code{RAM}. An image of the initialized data is loaded into the
+@code{ROM} and will be copied during system start into the @code{RAM}.
+@smallexample
+MEMORY
+ @{
+ ROM : ORIGIN = 0, LENGTH = 3M
+ RAM : ORIGIN = 0x10000000, LENGTH = 1M
+ @}
+
+REGION_ALIAS("REGION_TEXT", ROM);
+REGION_ALIAS("REGION_RODATA", ROM);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@item C
+Program code goes into the @code{ROM}. Read-only data goes into the
+@code{ROM2}. Read-write data goes into the @code{RAM}. An image of the
+initialized data is loaded into the @code{ROM2} and will be copied during
+system start into the @code{RAM}.
+@smallexample
+MEMORY
+ @{
+ ROM : ORIGIN = 0, LENGTH = 2M
+ ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
+ RAM : ORIGIN = 0x20000000, LENGTH = 1M
+ @}
+
+REGION_ALIAS("REGION_TEXT", ROM);
+REGION_ALIAS("REGION_RODATA", ROM2);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@end table
+
+It is possible to write a common system initialization routine to copy the
+@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
+necessary:
+@smallexample
+#include <string.h>
+
+extern char data_start [];
+extern char data_size [];
+extern char data_load_start [];
+
+void copy_data(void)
+@{
+ if (data_start != data_load_start)
+ @{
+ memcpy(data_start, data_load_start, (size_t) data_size);
+ @}
+@}
+@end smallexample
+
@node Miscellaneous Commands
@subsection Other Linker Script Commands
There are a few other linker scripts commands.
@smallexample
@group
@var{section} [@var{address}] [(@var{type})] :
- [AT(@var{lma})] [ALIGN(@var{section_align})] [SUBALIGN(@var{subsection_align})]
+ [AT(@var{lma})]
+ [ALIGN(@var{section_align})]
+ [SUBALIGN(@var{subsection_align})]
+ [@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
aligned upward to the specified value.
Specifying @var{address} for a section will change the value of the
-location counter.
+location counter, provided that the section is non-empty. (Empty
+sections are ignored).
@node Input Section
@subsection Input Section Description
@cindex output section attributes
We showed above that the full description of an output section looked
like this:
+
@smallexample
@group
@var{section} [@var{address}] [(@var{type})] :
- [AT(@var{lma})] [ALIGN(@var{section_align})] [SUBALIGN(@var{subsection_align})]
+ [AT(@var{lma})]
+ [ALIGN(@var{section_align})]
+ [SUBALIGN(@var{subsection_align})]
+ [@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
@end group
@end smallexample
+
We've already described @var{section}, @var{address}, and
@var{output-section-command}. In this section we will describe the
remaining section attributes.
* Output Section LMA:: Output section LMA
* Forced Output Alignment:: Forced Output Alignment
* Forced Input Alignment:: Forced Input Alignment
+* Output Section Constraint:: Output section constraint
* Output Section Region:: Output section region
* Output Section Phdr:: Output section phdr
* Output Section Fill:: Output section fill
SUBALIGN. The value specified overrides any alignment given by input
sections, whether larger or smaller.
+@node Output Section Constraint
+@subsubsection Output Section Constraint
+@kindex ONLY_IF_RO
+@kindex ONLY_IF_RW
+@cindex constraints on output sections
+You can specify that an output section should only be created if all
+of its input sections are read-only or all of its input sections are
+read-write by using the keyword @code{ONLY_IF_RO} and
+@code{ONLY_IF_RW} respectively.
+
@node Output Section Region
@subsubsection Output Section Region
@kindex >@var{region}
region. The region name has no meaning outside of the linker script.
Region names are stored in a separate name space, and will not conflict
with symbol names, file names, or section names. Each memory region
-must have a distinct name.
+must have a distinct name within the @code{MEMORY} command. However you can
+add later alias names to existing memory regions with the @ref{REGION_ALIAS}
+command.
@cindex memory region attributes
The @var{attr} string is an optional list of attributes that specify
@menu
* Constants:: Constants
+* Symbolic Constants:: Symbolic constants
* Symbols:: Symbol Names
* Orphan Sections:: Orphan Sections
* Location Counter:: The Location Counter
Note - the @code{K} and @code{M} suffixes cannot be used in
conjunction with the base suffixes mentioned above.
+@node Symbolic Constants
+@subsection Symbolic Constants
+@cindex symbolic constants
+@kindex CONSTANT
+It is possible to refer to target specific constants via the use of
+the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
+
+@table @code
+@item MAXPAGESIZE
+@kindex MAXPAGESIZE
+The target's maximum page size.
+
+@item COMMONPAGESIZE
+@kindex COMMONPAGESIZE
+The target's default page size.
+@end table
+
+So for example:
+
+@smallexample
+ .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
+@end smallexample
+
+will create a text section aligned to the largest page boundary
+supported by the target.
+
@node Symbols
@subsection Symbol Names
@cindex symbol names
The value of @samp{N}, the parameter to the
@option{--stub-group-size=} option controls where the stub groups are
-placed. If it is negative then all stubs are placed before the first
+placed. If it is negative then all stubs are placed after the first
branch that needs them. If it is positive then the stubs can be
placed either before or after the branches that need them. If the
value of @samp{N} is 1 (either +1 or -1) then the linker will choose