\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
This file documents the @sc{gnu} linker LD version @value{VERSION}.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
-2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@ignore
@iftex
@finalout
@setchapternewpage odd
-@settitle Using LD, the GNU linker
+@settitle The GNU linker
@titlepage
-@title Using ld
-@subtitle The GNU linker
+@title The GNU linker
@sp 1
@subtitle @code{ld} version 2
@subtitle Version @value{VERSION}
{\parskip=0pt
\hfill Red Hat Inc\par
\hfill nickc\@credhat.com, doc\@redhat.com\par
-\hfill {\it Using LD, the GNU linker}\par
+\hfill {\it The GNU linker}\par
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
}
\global\parindent=0pt % Steve likes it this way.
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004 Free Software Foundation, Inc.
+2002, 2003, 2004, 2005, 2006 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.1
@ifnottex
@node Top
-@top Using ld
+@top LD
This file documents the @sc{gnu} linker ld version @value{VERSION}.
This document is distributed under the terms of the GNU Free
@ifset man
@c For the man only
-This man page does not describe the command language; see the
-@command{ld} entry in @code{info}, or the manual
-ld: the GNU linker, for full details on the command language and
-on other aspects of the GNU linker.
+This man page does not describe the command language; see the
+@command{ld} entry in @code{info} for full details on the command
+language and on other aspects of the GNU linker.
@end ifset
@ifclear SingleFormat
precede the option name; for example, @samp{-trace-symbol} and
@samp{--trace-symbol} are equivalent. Note---there is one exception to
this rule. Multiple letter options that start with a lower case 'o' can
-only be preceeded by two dashes. This is to reduce confusion with the
+only be preceded by two dashes. This is to reduce confusion with the
@samp{-o} option. So for example @samp{-omagic} sets the output file
name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
output.
dynamic object, then you will probably need to use this option when
linking the program itself.
-You can also use the version script to control what symbols should
+You can also use the dynamic list to control what symbols should
be added to the dynamic symbol table if the output format supports it.
-See the description of @samp{--version-script} in @ref{VERSION}.
+See the description of @samp{--dynamic-list}.
@ifclear SingleFormat
@cindex big-endian objects
object files.
@ifclear SingleFormat
The @sc{gnu} linker uses other mechanisms for this purpose: the
-@option{-b}, @option{--format}, @option{--oformat} options, the
+@option{-b}, @option{--format}, @option{--oformat} options, the
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
environment variable.
@end ifclear
@cindex retain relocations in final executable
@item -q
@itemx --emit-relocs
-Leave relocation sections and contents in fully linked exececutables.
+Leave relocation sections and contents in fully linked executables.
Post link analysis and optimization tools may need this information in
order to perform correct modifications of executables. This results
in larger executables.
@kindex -X
@kindex --discard-locals
@cindex local symbols, deleting
-@cindex L, deleting symbols beginning
@item -X
@itemx --discard-locals
-Delete all temporary local symbols. For most targets, this is all local
-symbols whose names begin with @samp{L}.
+Delete all temporary local symbols. (These symbols start with
+system-specific local label prefixes, typically @samp{.L} for ELF systems
+or @samp{L} for traditional a.out systems.)
@kindex -y @var{symbol}
@kindex --trace-symbol=@var{symbol}
Marks the object that its symbol table interposes before all symbols
but the primary executable.
+@item lazy
+When generating an executable or shared library, mark it to tell the
+dynamic linker to defer function call resolution to the point when
+the function is called (lazy binding), rather than at load time.
+Lazy binding is the default.
+
@item loadfltr
Marks the object that its filters be processed immediately at
runtime.
@end table
-Other keywords are ignored for Solaris compatibility.
+Other keywords are ignored for Solaris compatibility.
@kindex -(
@cindex groups of archives
option can be used with @option{-shared}. Doing so means that a
shared library is being created but that all of the library's external
references must be resolved by pulling in entries from static
-libraries.
+libraries.
@kindex -Bsymbolic
@item -Bsymbolic
within the shared library. This option is only meaningful on ELF
platforms which support shared libraries.
+@kindex --dynamic-list=@var{dynamic-list-file}
+@item --dynamic-list=@var{dynamic-list-file}
+Specify the name of a dynamic list file to the linker. This is
+typically used when creating shared libraries to specify a list of
+global symbols whose references shouldn't be bound to the definition
+within the shared library, or creating dynamically linked executables
+to specify a list of symbols which should be added to the symbol table
+in the executable. This option is only meaningful on ELF platforms
+which support shared libraries.
+
+The format of the dynamic list is the same as the version node without
+scope and node name. See @ref{VERSION} for more information.
+
+@kindex --dynamic-list-cpp-typeinfo
+@item --dynamic-list-cpp-typeinfo
+Provide the builtin dynamic list for C++ runtime type identification.
+
@kindex --check-sections
@kindex --no-check-sections
@item --check-sections
@kindex --gc-sections
@kindex --no-gc-sections
@cindex garbage collection
-@item --no-gc-sections
-@itemx --gc-sections
+@item --gc-sections
+@itemx --no-gc-sections
Enable garbage collection of unused input sections. It is ignored on
targets that do not support this option. This option is not compatible
-with @samp{-r}. The default behaviour (of not performing this garbage
-collection) can be restored by specifying @samp{--no-gc-sections} on
-the command line.
+with @samp{-r} or @samp{--emit-relocs}. The default behaviour (of not
+performing this garbage collection) can be restored by specifying
+@samp{--no-gc-sections} on the command line.
+
+@kindex --print-gc-sections
+@kindex --no-print-gc-sections
+@cindex garbage collection
+@item --print-gc-sections
+@itemx --no-print-gc-sections
+List all sections removed by garbage collection. The listing is
+printed on stderr. This option is only effective if garbage
+collection has been enabled via the @samp{--gc-sections}) option. The
+default behaviour (of not listing the sections that are removed) can
+be restored by specifying @samp{--no-print-gc-sections} on the command
+line.
@cindex help
@cindex usage
is done even if the linker is creating a non-symbolic shared library.
The switch @option{--[no-]allow-shlib-undefined} controls the
behaviour for reporting unresolved references found in shared
-libraries being linked in.
+libraries being linked in.
@kindex --allow-multiple-definition
@kindex -z muldefs
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
+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.
runtime search path will be formed exclusively using the @option{-rpath}
options, ignoring the @option{-L} options. This can be useful when using
gcc, which adds many @option{-L} options which may be on NFS mounted
-filesystems.
+file systems.
For compatibility with other ELF linkers, if the @option{-R} option is
followed by a directory name, rather than a file name, it is treated as
runtime linker would do.
The linker uses the following search paths to locate required shared
-libraries.
+libraries:
@enumerate
@item
Any directories specified by @option{-rpath-link} options.
between @option{-rpath} and @option{-rpath-link} is that directories
specified by @option{-rpath} options are included in the executable and
used at runtime, whereas the @option{-rpath-link} option is only effective
-at link time. It is for the native linker only.
+at link time. Searching @option{-rpath} in this way is only supported
+by native linkers and cross linkers which have been configured with
+the @option{--with-sysroot} option.
@item
On an ELF system, if the @option{-rpath} and @code{rpath-link} options
were not used, search the contents of the environment variable
@kindex --warn-shared-textrel
@item --warn-shared-textrel
-Warn if the linker adds a DT_TEXTREL to a shared object.
+Warn if the linker adds a DT_TEXTREL to a shared object.
@kindex --warn-unresolved-symbols
@item --warn-unresolved-symbols
increasing the linker's memory requirements. Similarly reducing this
value can reduce the memory requirements at the expense of speed.
+@kindex --hash-style=@var{style}
+@item --hash-style=@var{style}
+Set the type of linker's hash table(s). @var{style} can be either
+@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
+new style GNU @code{.gnu.hash} section or @code{both} for both
+the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
+hash tables. The default is @code{sysv}.
+
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
This option reduces memory requirements at ld runtime, at the expense of
explicitly exported via DEF files or implicitly exported via function
attributes, the default is to not export anything else unless this
option is given. Note that the symbols @code{DllMain@@12},
-@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
+@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
@code{impure_ptr} will not be automatically
-exported. Also, symbols imported from other DLLs will not be
-re-exported, nor will symbols specifying the DLL's internal layout
-such as those beginning with @code{_head_} or ending with
-@code{_iname}. In addition, no symbols from @code{libgcc},
+exported. Also, symbols imported from other DLLs will not be
+re-exported, nor will symbols specifying the DLL's internal layout
+such as those beginning with @code{_head_} or ending with
+@code{_iname}. In addition, no symbols from @code{libgcc},
@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
not be exported, to help with C++ DLLs. Finally, there is an
-extensive list of cygwin-private symbols that are not exported
+extensive list of cygwin-private symbols that are not exported
(obviously, this applies on when building DLLs for cygwin targets).
-These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
+These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
-@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
+@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
-@code{cygwin_premain3}, and @code{environ}.
+@code{cygwin_premain3}, and @code{environ}.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --exclude-symbols
@kindex --large-address-aware
@item --large-address-aware
-If given, the appropriate bit in the ``Charateristics'' field of the COFF
+If given, the appropriate bit in the ``Characteristics'' field of the COFF
header is set to indicate that this executable supports virtual addresses
-greater than 2 gigabytes. This should be used in conjuction with the /3GB
+greater than 2 gigabytes. This should be used in conjunction with the /3GB
or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
section of the BOOT.INI. Otherwise, this bit has no effect.
[This option is specific to PE targeted ports of the linker]
@kindex --dll-search-prefix
@item --dll-search-prefix @var{string}
When linking dynamically to a dll without an import library,
-search for @code{<string><basename>.dll} in preference to
+search for @code{<string><basename>.dll} in preference to
@code{lib<basename>.dll}. This behaviour allows easy distinction
between DLLs built for the various "subplatforms": native, cygwin,
uwin, pw, etc. For instance, cygwin DLLs typically use
-@code{--dll-search-prefix=cyg}.
+@code{--dll-search-prefix=cyg}.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-auto-import
@item --enable-auto-import
-Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
-DATA imports from DLLs, and create the necessary thunking symbols when
+Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
+DATA imports from DLLs, and create the necessary thunking symbols when
building the import libraries with those DATA exports. Note: Use of the
'auto-import' extension will cause the text section of the image file
to be made writable. This does not conform to the PE-COFF format
Using 'auto-import' generally will 'just work' -- but sometimes you may
see this message:
-"variable '<var>' can't be auto-imported. Please read the
+"variable '<var>' can't be auto-imported. Please read the
documentation for ld's @code{--enable-auto-import} for details."
-This message occurs when some (sub)expression accesses an address
-ultimately given by the sum of two constants (Win32 import tables only
+This message occurs when some (sub)expression accesses an address
+ultimately given by the sum of two constants (Win32 import tables only
allow one). Instances where this may occur include accesses to member
fields of struct variables imported from a DLL, as well as using a
constant index into an array variable imported from a DLL. Any
@item OUTPUT(@var{filename})
@kindex OUTPUT(@var{filename})
-@cindex output file name in linker scripot
+@cindex output file name in linker script
The @code{OUTPUT} command names the output file. Using
@code{OUTPUT(@var{filename})} in the linker script is exactly like using
@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
@cindex discarding sections
@cindex sections, discarding
@cindex removing sections
-The linker will not create output section which do not have any
-contents. This is for convenience when referring to input sections that
-may or may not be present in any of the input files. For example:
+The linker will not create output sections with no contents. This is
+for convenience when referring to input sections that may or may not
+be present in any of the input files. For example:
@smallexample
-.foo @{ *(.foo) @}
+.foo : @{ *(.foo) @}
@end smallexample
@noindent
will only create a @samp{.foo} section in the output file if there is a
-@samp{.foo} section in at least one input file.
+@samp{.foo} section in at least one input file, and if the input
+sections are not all empty. Other link script directives that allocate
+space in an output section will also create the output section.
-If you use anything other than an input section description as an output
-section command, such as a symbol assignment, then the output section
-will always be created, even if there are no matching input sections.
+The linker will ignore address assignments (@xref{Output Section Address})
+on discarded output sections, except when the linker script defines
+symbols in the output section. In that case the linker will obey
+the address assignments, possibly advancing dot and/or current lma
+even though the section is discarded.
@cindex /DISCARD/
The special output section name @samp{/DISCARD/} may be used to discard
an output section description sets the VMA (@pxref{Output Section
Address}).
-The linker will normally set the LMA equal to the VMA. You can change
-that by using the @code{AT} keyword. The expression @var{lma} that
-follows the @code{AT} keyword specifies the load address of the
-section.
+The expression @var{lma} that follows the @code{AT} keyword specifies
+the load address of the section.
Alternatively, with @samp{AT>@var{lma_region}} expression, you may
specify a memory region for the section's load address. @xref{MEMORY}.
Note that if the section has not had a VMA assigned to it then the
linker will use the @var{lma_region} as the VMA region as well.
+
+If neither @code{AT} nor @code{AT>} is specified for an allocatable
+section, the linker will set the LMA such that the difference between
+VMA and LMA for the section is the same as the preceding output
+section in the same region. If there is no preceding output section
+or the section is not allocatable, the linker will set the LMA equal
+to the VMA.
@xref{Output Section Region}.
@cindex ROM initialized data
@cindex holes
Assigning a value to @code{.} will cause the location counter to be
moved. This may be used to create holes in the output section. The
-location counter may never be moved backwards.
+location counter may not be moved backwards inside an output section,
+and may not be moved backwards outside of an output section if so
+doing creates areas with overlapping LMAs.
@smallexample
SECTIONS
the top page of memory).
@item system control instructions
-@command{ld} finds all @code{ldc.w, stc.w} instrcutions which use the
+@command{ld} finds all @code{ldc.w, stc.w} instructions which use the
32 bit absolute address form, but refer to the top page of memory, and
changes them to use 16 bit address form.
(That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
@cindex ARM interworking support
@kindex --support-old-code
For the ARM, @command{ld} will generate code stubs to allow functions calls
-betweem ARM and Thumb code. These stubs only work with code that has
+between ARM and Thumb code. These stubs only work with code that has
been compiled and assembled with the @samp{-mthumb-interwork} command
line option. If it is necessary to link with old ARM object files or
libraries, which have not been compiled with the -mthumb-interwork
@section @command{ld} and WIN32 (cygwin/mingw)
This section describes some of the win32 specific @command{ld} issues.
-See @ref{Options,,Command Line Options} for detailed decription of the
+See @ref{Options,,Command Line Options} for detailed description of the
command line options mentioned here.
@table @emph
name of the output DLL. If @samp{<name>} does not include a suffix,
the default library suffix, @samp{.DLL} is appended.
-When the .DEF file is used to build an application. rather than a
-library, the @code{NAME <name>} command shoud be used instead of
+When the .DEF file is used to build an application, rather than a
+library, the @code{NAME <name>} command should be used instead of
@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
executable suffix, @samp{.EXE} is appended.
of idioms that are typically used to do this; often client code can
omit the __declspec() declaration completely. See
@samp{--enable-auto-import} and @samp{automatic data imports} for more
-imformation.
+information.
@end table
@cindex automatic data imports
code to these platforms, especially for large
c++ libraries and applications. The auto-import feature, which was
initially provided by Paul Sokolovsky, allows one to omit the
-decorations to archieve a behavior that conforms to that on POSIX/Un*x
+decorations to achieve a behavior that conforms to that on POSIX/Un*x
platforms. This feature is enabled with the @samp{--enable-auto-import}
command-line option, although it is enabled by default on cygwin/mingw.
The @samp{--enable-auto-import} option itself now serves mainly to
The cygwin/mingw ports of @command{ld} support the direct linking,
including data symbols, to a dll without the usage of any import
libraries. This is much faster and uses much less memory than does the
-traditional import library method, expecially when linking large
+traditional import library method, especially when linking large
libraries or applications. When @command{ld} creates an import lib, each
function or variable exported from the dll is stored in its own bfd, even
though a single bfd could contain many exports. The overhead involved in
to find, in the first directory of its search path,
@example
-libxxx.dll.a
-xxx.dll.a
-libxxx.a
+libxxx.dll.a
+xxx.dll.a
+libxxx.a
+xxx.lib
cygxxx.dll (*)
-libxxx.dll
-xxx.dll
+libxxx.dll
+xxx.dll
@end example
before moving on to the next directory in the search path.
@samp{--enable-runtime-pseudo-relocs} is used.
Given the improvements in speed and memory usage, one might justifiably
-wonder why import libraries are used at all. There are two reasons:
+wonder why import libraries are used at all. There are three reasons:
1. Until recently, the link-directly-to-dll functionality did @emph{not}
work with auto-imported data.
for the cygwin kernel makes use of this ability, and it is not
possible to do this without an import lib.
+3. Symbol aliases can only be resolved using an import lib. This is
+critical when linking against OS-supplied dll's (eg, the win32 API)
+in which symbols are usually exported as undecorated aliases of their
+stdcall-decorated assembly names.
+
So, import libs are not going away. But the ability to replace
true import libs with a simple symbolic link to (or a copy of)
-a dll, in most cases, is a useful addition to the suite of tools
+a dll, in many cases, is a useful addition to the suite of tools
binutils makes available to the win32 developer. Given the
massive improvements in memory requirements during linking, storage
requirements, and linking speed, we expect that many developers
Even if the problem you experience is a fatal signal, you should still
say so explicitly. Suppose something strange is going on, such as, your
-copy of @command{ld} is out of synch, or you have encountered a bug in the
+copy of @command{ld} is out of sync, or you have encountered a bug in the
C library on your system. (This has happened!) Your copy might crash
and ours would not. If you told us to expect a crash, then when ours
fails to crash, we would know that the bug was not happening for us. If
projects / deliverable / binutils-gdb.git / blobdiff