\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@c Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
version @value{VERSION}.
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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
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
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
@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.
on the command line after the @option{--as-needed} option. Normally,
the linker will add a DT_NEEDED tag for each dynamic library mentioned
on the command line, regardless of whether the library is actually
-needed. @option{--as-needed} causes DT_NEEDED tags to only be emitted
-for libraries that satisfy some symbol reference from regular objects
-which is undefined at the point that the library was linked.
+needed. @option{--as-needed} causes a DT_NEEDED tag to only be emitted
+for a library that satisfies a symbol reference from regular objects
+which is undefined at the point that the library was linked, or, if
+the library is not found in the DT_NEEDED lists of other libraries
+linked up to that point, a reference from another dynamic library.
@option{--no-as-needed} restores the default behaviour.
@kindex --add-needed
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.
@kindex --no-allow-shlib-undefined
@item --allow-shlib-undefined
@itemx --no-allow-shlib-undefined
-Allows (the default) or disallows undefined symbols in shared libraries.
+Allows or disallows undefined symbols in shared libraries.
This switch is similar to @option{--no-undefined} except that it
determines the behaviour when the undefined symbols are in a
shared library rather than a regular object file. It does not affect
how undefined symbols in regular object files are handled.
-The reason that @option{--allow-shlib-undefined} is the default is that
-the shared library being specified at link time may not be the same as
-the one that is available at load time, so the symbols might actually be
-resolvable at load time. Plus there are some systems, (eg BeOS) where
-undefined symbols in shared libraries is normal. (The kernel patches
-them at load time to select which function is most appropriate
-for the current architecture. This is used for example to dynamically
-select an appropriate memset function). Apparently it is also normal
-for HPPA shared libraries to have undefined symbols.
+The default behaviour is to report errors for any undefined symbols
+referenced in shared libraries if the linker is being used to create
+an executable, but to allow them if the linker is being used to create
+a shared library.
+
+The reasons for allowing undefined symbol references in shared
+libraries specified at link time are that:
+
+@itemize @bullet
+@item
+A shared library specified at link time may not be the same as the one
+that is available at load time, so the symbol might actually be
+resolvable at load time.
+@item
+There are some operating systems, eg BeOS and HPPA, where undefined
+symbols in shared libraries are normal.
+
+The BeOS kernel for example patches shared libraries at load time to
+select whichever function is most appropriate for the current
+architecture. This is used, for example, to dynamically select an
+appropriate memset function.
+@end itemize
@kindex --no-undefined-version
@item --no-undefined-version
(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
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
file.
[This option is specific to the i386 PE targeted port of the linker]
+@kindex --enable-long-section-names
+@kindex --disable-long-section-names
+@item --enable-long-section-names
+@itemx --disable-long-section-names
+The PE variants of the Coff object format add an extension that permits
+the use of section names longer than eight characters, the normal limit
+for Coff. By default, these names are only allowed in object files, as
+fully-linked executable images do not carry the Coff string table required
+to support the longer names. As a GNU extension, it is possible to
+allow their use in executable images as well, or to (probably pointlessly!)
+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. 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
@kindex --disable-stdcall-fixup
@item --enable-stdcall-fixup
* 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.
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
As in C, the linker considers an integer beginning with @samp{0} to be
octal, and an integer beginning with @samp{0x} or @samp{0X} to be
-hexadecimal. The linker considers other integers to be decimal.
+hexadecimal. Alternatively the linker accepts suffixes of @samp{h} or
+@samp{H} for hexadeciaml, @samp{o} or @samp{O} for octal, @samp{b} or
+@samp{B} for binary and @samp{d} or @samp{D} for decimal. Any integer
+value without a prefix or a suffix is considered to be decimal.
@cindex scaled integers
@cindex K and M integer suffixes
${\rm 1024}$ or ${\rm 1024}^2$
@end tex
@c END TEXI2ROFF-KILL
-respectively. For example, the following all refer to the same quantity:
+respectively. For example, the following
+all refer to the same quantity:
+
@smallexample
_fourk_1 = 4K;
_fourk_2 = 4096;
_fourk_3 = 0x1000;
+_fourk_4 = 10000o;
@end smallexample
+Note - the @code{K} and @code{M} suffixes cannot be used in
+conjunction with the base suffixes mentioned above.
+
@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
projects / deliverable / binutils-gdb.git / blobdiff