@syncodeindex ky cp
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
+@include ldver.texi
@c @smallbook
@end ifinfo
@ifinfo
-This file documents the @sc{gnu} linker LD.
+This file documents the @sc{gnu} linker LD version @value{VERSION}.
-Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
+Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@subtitle The GNU linker
@sp 1
@subtitle @code{ld} version 2
-@subtitle January 1994
+@subtitle Version @value{VERSION}
@author Steve Chamberlain
-@author Cygnus Support
+@author Ian Lance Taylor
+@author Cygnus Solutions
@page
@tex
{\parskip=0pt
-\hfill Cygnus Support\par
-\hfill steve\@cygnus.com, doc\@cygnus.com\par
+\hfill Cygnus Solutions\par
+\hfill ian\@cygnus.com, doc\@cygnus.com\par
\hfill {\it Using LD, the GNU linker}\par
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
}
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@ifinfo
@node Top
@top Using ld
-This file documents the @sc{gnu} linker ld.
+This file documents the @sc{gnu} linker ld version @value{VERSION}.
@menu
* Overview:: Overview
@ifset I960
* i960:: ld and the Intel 960 family
@end ifset
+@ifset TICOFF
+* TI COFF:: ld and the TI COFF
+@end ifset
@end ifclear
@ifclear SingleFormat
* BFD:: BFD
the library @code{libc.a}, which will come from the standard search
directories. (See the discussion of the @samp{-l} option below.)
-The command-line options to @code{ld} may be specified in any order, and
-may be repeated at will. Repeating most options with a different
-argument will either have no further effect, or override prior
+Some of the command-line options to @code{ld} may be specified at any
+point in the command line. However, options which refer to files, such
+as @samp{-l} or @samp{-T}, cause the file to be read at the point at
+which the option appears in the command line, relative to the object
+files and other file options. Repeating non-file options with a
+different argument will either have no further effect, or override prior
occurrences (those further to the left on the command line) of that
option. Options which may be meaningfully specified more than once are
noted in the descriptions below.
@cindex object files
-Non-option arguments are objects files which are to be linked together.
-They may follow, precede, or be mixed in with command-line options,
-except that an object file argument may not be placed between an option
-and its argument.
+Non-option arguments are object files or archives which are to be linked
+together. They may follow, precede, or be mixed in with command-line
+options, except that an object file argument may not be placed between
+an option and its argument.
Usually the linker is invoked with at least one object file, but you can
specify other forms of binary input files using @samp{-l}, @samp{-R},
@samp{--oformat=srec} are equivalent. Unique abbreviations of the names
of multiple-letter options are accepted.
+Note - if the linker is being invoked indirectly, via a compiler driver
+(eg @samp{gcc}) then all the linker command line options should be
+prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
+compiler driver) like this:
+
+@smallexample
+ gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
+@end smallexample
+
+This is important, because otherwise the compiler driver program may
+silently drop the linker options, resulting in a bad link.
+
+Here is a table of the generic command line switches accepted by the GNU
+linker:
+
@table @code
@kindex -a@var{keyword}
@item -a@var{keyword}
@item -e @var{entry}
@itemx --entry=@var{entry}
Use @var{entry} as the explicit symbol for beginning execution of your
-program, rather than the default entry point. @xref{Entry Point}, for a
-discussion of defaults and other ways of specifying the
-entry point.
+program, rather than the default entry point. If there is no symbol
+named @var{entry}, the linker will try to parse @var{entry} as a number,
+and use that as the entry address (the number will be interpreted in
+base 10; you may use a leading @samp{0x} for base 16, or a leading
+@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
+and other ways of specifying the entry point.
@cindex dynamic symbol table
@kindex -E
dynamic object, then you will probably need to use this option when
linking the program itself.
+@cindex big-endian objects
+@cindex endianness
+@kindex -EB
+@item -EB
+Link big-endian objects. This affects the default output format.
+
+@cindex little-endian objects
+@kindex -EL
+@item -EL
+Link little-endian objects. This affects the default output format.
+
@kindex -f
@kindex --auxiliary
@item -f
environment variable. The @sc{gnu} linker will ignore the @code{-F}
option when not creating an ELF shared object.
-@kindex --force-exe-suffix
-@item --force-exe-suffix
-Make sure that an output file has a .exe suffix.
-
-If a successfully built fully linked output file does not have a
-@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
-the output file to one of the same name with a @code{.exe} suffix. This
-option is useful when using unmodified Unix makefiles on a Microsoft
-Windows host, since some versions of Windows won't run an image unless
-it ends in a @code{.exe} suffix.
+@cindex finalization function
+@kindex -fini
+@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
+the function to call.
@kindex -g
@item -g
@item -i
Perform an incremental link (same as option @samp{-r}).
+@cindex initialization function
+@kindex -init
+@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{archive}
@kindex --library=@var{archive}
@kindex --nmagic
@item -n
@itemx --nmagic
-Set the text segment to be read only, and mark the output as
-@code{NMAGIC} if possible.
+Turn off page alignment of sections, and mark the output as
+@code{NMAGIC} if possible.
@kindex -N
@kindex --omagic
option is not specified, the name @file{a.out} is used by default. The
script command @code{OUTPUT} can also specify the output file name.
+@kindex -O @var{level}
+@cindex generating optimized output
+@item -O @var{level}
+If @var{level} is a numeric values greater than zero @code{ld} optimizes
+the output. This might take significantly longer and therefore probably
+should only be enabled for the final binary.
+
+@kindex -q
+@kindex --emit-relocs
+@cindex retain relocations in final executable
+@item -q
+@itemx --emit-relocs
+Leave relocation sections and contents in fully linked exececutables.
+Post link analysis and optimization tools may need this information in
+order to perform correct modifications of executables. This results
+in larger executables.
+
@cindex partial link
@cindex relocatable output
@kindex -r
@cindex undefined symbol
@item -u @var{symbol}
@itemx --undefined=@var{symbol}
-Force @var{symbol} to be entered in the output file as an undefined symbol.
-Doing this may, for example, trigger linking of additional modules from
-standard libraries. @samp{-u} may be repeated with different option
-arguments to enter additional undefined symbols.
-@c Nice idea, but no such command: This option is equivalent
-@c to the @code{EXTERN} linker command.
+Force @var{symbol} to be entered in the output file as an undefined
+symbol. Doing this may, for example, trigger linking of additional
+modules from standard libraries. @samp{-u} may be repeated with
+different option arguments to enter additional undefined symbols. This
+option is equivalent to the @code{EXTERN} linker script command.
+
+@kindex -Ur
+@cindex constructors
+@item -Ur
+For anything other than C++ programs, this option is equivalent to
+@samp{-r}: it generates relocatable output---i.e., an output file that can in
+turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
+@emph{does} resolve references to constructors, unlike @samp{-r}.
+It does not work to use @samp{-Ur} on files that were themselves linked
+with @samp{-Ur}; once the constructor table has been built, it cannot
+be added to. Use @samp{-Ur} only for the last partial link, and
+@samp{-r} for the others.
+
+@kindex --unique
+@item --unique
+Creates a separate output section for every orphan input section. This
+option prevents the normal merging of orphan input sections with the same
+name. An orphan section is one not specifically mentioned in a linker
+script, so this option along with a custom linker script allows any
+selection of input sections to be merged while others are kept separate.
@kindex -v
@kindex -V
@kindex -z @var{keyword}
@item -z @var{keyword}
-This option is ignored for Solaris compatibility.
+The recognized keywords are @code{initfirst}, @code{interpose},
+@code{loadfltr}, @code{nodefaultlib}, @code{nodelete}, @code{nodlopen},
+@code{nodump}, @code{now} and @code{origin}. The other keywords are
+ignored for Solaris compatibility. @code{initfirst} marks the object
+to be initialized first at runtime before any other objects.
+@code{interpose} marks the object that its symbol table interposes
+before all symbols but the primary executable. @code{loadfltr} marks
+the object that its filtees be processed immediately at runtime.
+@code{nodefaultlib} marks the object that the search for dependencies
+of this object will ignore any default library search paths.
+@code{nodelete} marks the object shouldn't be unloaded at runtime.
+@code{nodlopen} marks the object not available to @code{dlopen}.
+@code{nodump} marks the object can not be dumped by @code{dldump}.
+@code{now} marks the object with the non-lazy runtime binding.
+@code{origin} marks the object may contain $ORIGIN.
@kindex -(
@cindex groups of archives
within the shared library. This option is only meaningful on ELF
platforms which support shared libraries.
+@kindex --check-sections
+@kindex --no-check-sections
+@item --check-sections
+@itemx --no-check-sections
+Asks the linker @emph{not} to check section addresses after they have
+been assigned to see if there any overlaps. Normally the linker will
+perform this check, and if it finds any overlaps it will produce
+suitable error messages. The linker does know about, and does make
+allowances for sections in overlays. The default behaviour can be
+restored by using the command line switch @samp{--check-sections}.
+
@cindex cross reference table
@kindex --cref
@item --cref
space between @var{symbol}, the equals sign (``@key{=}''), and
@var{expression}.
+@cindex demangling, from command line
+@kindex --demangle[=@var{style}]
+@kindex --no-demangle
+@item --demangle[=@var{style}]
+@itemx --no-demangle
+These options control whether to demangle symbol names in error messages
+and other output. When the linker is told to demangle, it tries to
+present symbol names in a readable fashion: it strips leading
+underscores if they are used by the object file format, and converts C++
+mangled symbol names into user readable names. Different compilers have
+different mangling styles. The optional demangling style argument can be used
+to choose an appropriate demangling style for your compiler. The linker will
+demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
+is set. These options may be used to override the default.
+
@cindex dynamic linker, from command line
@kindex --dynamic-linker @var{file}
@item --dynamic-linker @var{file}
linker is normally correct; don't use this unless you know what you are
doing.
-@cindex big-endian objects
-@cindex endianness
-@kindex -EB
-@item -EB
-Link big-endian objects. This affects the default output format.
-
-@cindex little-endian objects
-@kindex -EL
-@item -EL
-Link little-endian objects. This affects the default output format.
-
@cindex MIPS embedded PIC code
@kindex --embedded-relocs
@item --embedded-relocs
runtime to relocate any data which was statically initialized to pointer
values. See the code in testsuite/ld-empic for details.
+@kindex --force-exe-suffix
+@item --force-exe-suffix
+Make sure that an output file has a .exe suffix.
+
+If a successfully built fully linked output file does not have a
+@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
+the output file to one of the same name with a @code{.exe} suffix. This
+option is useful when using unmodified Unix makefiles on a Microsoft
+Windows host, since some versions of Windows won't run an image unless
+it ends in a @code{.exe} suffix.
+
+@kindex --gc-sections
+@kindex --no-gc-sections
+@cindex garbage collection
+@item --no-gc-sections
+@itemx --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}, nor should it be used with dynamic linking. The default
+behaviour (of not performing this garbage collection) can be restored by
+specifying @samp{--no-gc-sections} on the command line.
+
@cindex help
@cindex usage
@kindex --help
necessary. This may be required if @code{ld} runs out of memory space
while linking a large executable.
+@kindex --no-undefined
+@item --no-undefined
+Normally when creating a non-symbolic shared library, undefined symbols
+are allowed and left to be resolved by the runtime loader. This option
+disallows such undefined symbols.
+
@kindex --no-warn-mismatch
@item --no-warn-mismatch
Normally @code{ld} will give an error if you try to link together input
@xref{i960,, @code{ld} and the Intel 960 family}.
@end ifset
+
On some platforms, the @samp{--relax} option performs global
optimizations that become possible when the linker resolves addressing
in the program, such as relaxing address modes and synthesizing new
instructions in the output object file.
+On some platforms these link time global optimizations may make symbolic
+debugging of the resulting executable impossible.
+@ifset GENERIC
+This is known to be
+the case for the Matsushita MN10200 and MN10300 family of processors.
+@end ifset
+
@ifset GENERIC
On platforms where this is not supported, @samp{--relax} is accepted,
but ignored.
either by specifying a list of names separated by colons, or by
appearing multiple times.
+This option should be used with caution as it overrides the search path
+that may have been hard compiled into a shared library. In such a case it
+is possible to use unintentionally a different search path than the
+runtime linker would do.
+
The linker uses the following search paths to locate required shared
libraries.
@enumerate
between @code{-rpath} and @code{-rpath-link} is that directories
specified by @code{-rpath} options are included in the executable and
used at runtime, whereas the @code{-rpath-link} option is only effective
-at link time.
+at link time. It is for the native linker only.
@item
On an ELF system, if the @code{-rpath} and @code{rpath-link} options
were not used, search the contents of the environment variable
-@code{LD_RUN_PATH}.
+@code{LD_RUN_PATH}. It is for the native linker only.
@item
On SunOS, if the @code{-rpath} option was not used, search any
directories specified using @code{-L} options.
For a native linker, the contents of the environment variable
@code{LD_LIBRARY_PATH}.
@item
+For a native ELF linker, the directories in @code{DT_RUNPATH} or
+@code{DT_RPATH} of a shared library are searched for shared
+libraries needed by it. The @code{DT_RPATH} entries are ignored if
+@code{DT_RUNPATH} entries exist.
+@item
The default directories, normally @file{/lib} and @file{/usr/lib}.
+@item
+For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
+exists, the list of directories found in that file.
@end enumerate
If the required shared library is not found, the linker will issue a
alignment constraints.
@kindex --split-by-file
-@item --split-by-file
+@item --split-by-file [@var{size}]
Similar to @code{--split-by-reloc} but creates a new output section for
-each input file.
+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}
-Trys to creates extra sections in the output file so that no single
+@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 for downloading into
+This is useful when generating huge relocatable files for downloading into
certain real time kernels with the COFF object file format; since COFF
cannot represent more than 65535 relocations in a single section. Note
that this will fail to work with object file formats which do not
support arbitrary sections. The linker will not split up individual
input sections for redistribution, so if a single input section contains
more than @var{count} relocations one output section will contain that
-many relocations.
+many relocations. @var{count} defaults to a value of 32768.
@kindex --stats
@item --stats
trouble). The @samp{--traditional-format} switch tells @code{ld} to not
combine duplicate entries.
+@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
+line.
+@var{org} must be a single hexadecimal integer;
+for compatibility with other linkers, you may omit the leading
+@samp{0x} usually associated with hexadecimal values. @emph{Note:} there
+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}
for compatibility with other linkers, you may omit the leading
@samp{0x} usually associated with hexadecimal values.
-@kindex -Ur
-@cindex constructors
-@item -Ur
-For anything other than C++ programs, this option is equivalent to
-@samp{-r}: it generates relocatable output---i.e., an output file that can in
-turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
-@emph{does} resolve references to constructors, unlike @samp{-r}.
-It does not work to use @samp{-Ur} on files that were themselves linked
-with @samp{-Ur}; once the constructor table has been built, it cannot
-be added to. Use @samp{-Ur} only for the last partial link, and
-@samp{-r} for the others.
-
@kindex --verbose
@cindex verbose
-@item --verbose
+@item --dll-verbose
+@itemx --verbose
Display the version number for @code{ld} and list the linker emulations
supported. Display which input files can and cannot be opened. Display
the linker script if using a default builtin script.
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
call before the linker has a chance to wrap it to @code{malloc}.
+@kindex --enable-new-dtags
+@kindex --disable-new-dtags
+@item --enable-new-dtags
+@itemx --disable-new-dtags
+This linker can create the new dynamic tags in ELF. But the older ELF
+systems may not understand them. If you specify
+@code{--enable-new-dtags}, the dynamic tags will be created as needed.
+If you specify @code{--disable-new-dtags}, no new dynamic tags will be
+created. By default, the new dynamic tags are not created. Note that
+those options are only available for ELF systems.
+
+@end table
+
+@subsection Options specific to i386 PE targets
+
+The i386 PE linker supports the @code{-shared} option, which causes
+the output to be a dynamically linked library (DLL) instead of a
+normal executable. You should name the output @code{*.dll} when you
+use this option. In addition, the linker fully supports the standard
+@code{*.def} files, which may be specified on the linker command line
+like an object file (in fact, it should precede archives it exports
+symbols from, to ensure that they get linked in, just like a normal
+object file).
+
+In addition to the options common to all targets, the i386 PE linker
+support additional command line options that are specific to the i386
+PE target. Options that take values may be separated from their
+values by either a space or an equals sign.
+
+@table @code
+
+@kindex --add-stdcall-alias
+@item --add-stdcall-alias
+If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
+as-is and also with the suffix stripped.
+
+@kindex --base-file
+@item --base-file @var{file}
+Use @var{file} as the name of a file in which to save the base
+addresses of all the relocations needed for generating DLLs with
+@file{dlltool}.
+
+@kindex --dll
+@item --dll
+Create a DLL instead of a regular executable. You may also use
+@code{-shared} or specify a @code{LIBRARY} in a given @code{.def}
+file.
+
+@kindex --enable-stdcall-fixup
+@kindex --disable-stdcall-fixup
+@item --enable-stdcall-fixup
+@itemx --disable-stdcall-fixup
+If the link finds a symbol that it cannot resolve, it will attempt to
+do "fuzzy linking" by looking for another defined symbol that differs
+only in the format of the symbol name (cdecl vs stdcall) and will
+resolve that symbol by linking to the match. For example, the
+undefined symbol @code{_foo} might be linked to the function
+@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
+to the function @code{_bar}. When the linker does this, it prints a
+warning, since it normally should have failed to link, but sometimes
+import libraries generated from third-party dlls may need this feature
+to be usable. If you specify @code{--enable-stdcall-fixup}, this
+feature is fully enabled and warnings are not printed. If you specify
+@code{--disable-stdcall-fixup}, this feature is disabled and such
+mismatches are considered to be errors.
+
+@cindex DLLs, creating
+@kindex --export-all-symbols
+@item --export-all-symbols
+If given, all global symbols in the objects used to build a DLL will
+be exported by the DLL. Note that this is the default if there
+otherwise wouldn't be any exported symbols. When symbols are
+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}, and @code{impure_ptr} will not be automatically
+exported.
+
+@kindex --exclude-symbols
+@item --exclude-symbols @var{symbol},@var{symbol},...
+Specifies a list of symbols which should not be automatically
+exported. The symbol names may be delimited by commas or colons.
+
+@kindex --file-alignment
+@item --file-alignment
+Specify the file alignment. Sections in the file will always begin at
+file offsets which are multiples of this number. This defaults to
+512.
+
+@cindex heap size
+@kindex --heap
+@item --heap @var{reserve}
+@itemx --heap @var{reserve},@var{commit}
+Specify the amount of memory to reserve (and optionally commit) to be
+used as heap for this program. The default is 1Mb reserved, 4K
+committed.
+
+@cindex image base
+@kindex --image-base
+@item --image-base @var{value}
+Use @var{value} as the base address of your program or dll. This is
+the lowest memory location that will be used when your program or dll
+is loaded. To reduce the need to relocate and improve performance of
+your dlls, each should have a unique base address and not overlap any
+other dlls. The default is 0x400000 for executables, and 0x10000000
+for dlls.
+
+@kindex --kill-at
+@item --kill-at
+If given, the stdcall suffixes (@@@var{nn}) will be stripped from
+symbols before they are exported.
+
+@kindex --major-image-version
+@item --major-image-version @var{value}
+Sets the major number of the "image version". Defaults to 1.
+
+@kindex --major-os-version
+@item --major-os-version @var{value}
+Sets the major number of the "os version". Defaults to 4.
+
+@kindex --major-subsystem-version
+@item --major-subsystem-version @var{value}
+Sets the major number of the "subsystem version". Defaults to 4.
+
+@kindex --minor-image-version
+@item --minor-image-version @var{value}
+Sets the minor number of the "image version". Defaults to 0.
+
+@kindex --minor-os-version
+@item --minor-os-version @var{value}
+Sets the minor number of the "os version". Defaults to 0.
+
+@kindex --minor-subsystem-version
+@item --minor-subsystem-version @var{value}
+Sets the minor number of the "subsystem version". Defaults to 0.
+
+@cindex DEF files, creating
+@cindex DLLs, creating
+@kindex --output-def
+@item --output-def @var{file}
+The linker will create the file @var{file} which will contain a DEF
+file corresponding to the DLL the linker is generating. This DEF file
+(which should be called @code{*.def}) may be used to create an import
+library with @code{dlltool} or may be used as a reference to
+automatically or implicitly exported symbols.
+
+@kindex --section-alignment
+@item --section-alignment
+Sets the section alignment. Sections in memory will always begin at
+addresses which are a multiple of this number. Defaults to 0x1000.
+
+@cindex stack size
+@kindex --stack
+@item --stack @var{reserve}
+@itemx --stack @var{reserve},@var{commit}
+Specify the amount of memory to reserve (and optionally commit) to be
+used as stack for this program. The default is 32Mb reserved, 4K
+committed.
+
+@kindex --subsystem
+@item --subsystem @var{which}
+@itemx --subsystem @var{which}:@var{major}
+@itemx --subsystem @var{which}:@var{major}.@var{minor}
+Specifies the subsystem under which your program will execute. The
+legal values for @var{which} are @code{native}, @code{windows},
+@code{console}, and @code{posix}. You may optionally set the
+subsystem version also.
+
@end table
@ifset UsesEnvVars
@section Environment Variables
You can change the behavior of @code{ld} with the environment variables
-@code{GNUTARGET} and @code{LDEMULATION}.
+@code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}.
@kindex GNUTARGET
@cindex default input format
linker was configured.
@end ifset
+@kindex COLLECT_NO_DEMANGLE
+@cindex demangling, default
+Normally, the linker will default to demangling symbols. However, if
+@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
+default to not demangling symbols. This environment variable is used in
+a similar fashion by the @code{gcc} linker wrapper program. The default
+may be overridden by the @samp{--demangle} and @samp{--no-demangle}
+options.
+
@node Scripts
@chapter Linker Scripts
Every loadable or allocatable output section has two addresses. The
first is the @dfn{VMA}, or virtual memory address. This is the address
-the sectin will have when the output file is run. The second is the
+the section will have when the output file is run. The second is the
@dfn{LMA}, or load memory address. This is the address at which the
section will be loaded. In most cases the two addresses will be the
same. An example of when they might be different is when a data section
followed by a series of symbol assignments and output section
descriptions enclosed in curly braces.
-The first line in the above example sets the special symbol @samp{.},
-which is the location counter. If you do not specify the address of an
-output section in some other way (other ways are described later), the
-address is set from the current value of the location counter. The
-location counter is then incremented by the size of the output section.
+The first line inside the @samp{SECTIONS} command of the above example
+sets the value of the special symbol @samp{.}, which is the location
+counter. If you do not specify the address of an output section in some
+other way (other ways are described later), the address is set from the
+current value of the location counter. The location counter is then
+incremented by the size of the output section. At the start of the
+@samp{SECTIONS} command, the location counter has the value @samp{0}.
The second line defines an output section, @samp{.text}. The colon is
required syntax which may be ignored for now. Within the curly braces
@samp{.text} section in the output file to be @samp{0x10000}.
The remaining lines define the @samp{.data} and @samp{.bss} sections in
-the output file. The @samp{.data} output section will be at address
-@samp{0x8000000}. When the @samp{.bss} output section is defined, the
-value of the location counter will be @samp{0x8000000} plus the size of
-the @samp{.data} output section. The effect is that the @samp{.bss}
-output section will follow immediately after the @samp{.data} output
-section in memory.
+the output file. The linker will place the @samp{.data} output section
+at address @samp{0x8000000}. After the linker places the @samp{.data}
+output section, the value of the location counter will be
+@samp{0x8000000} plus the size of the @samp{.data} output section. The
+effect is that the linker will place the @samp{.bss} output section
+immediately after the @samp{.data} output section in memory
+
+The linker will ensure that each output section has the required
+alignment, by increasing the location counter if necessary. In this
+example, the specified addresses for the @samp{.text} and @samp{.data}
+sections will probably satisfy any alignment constraints, but the linker
+may have to create a small gap between the @samp{.data} and @samp{.bss}
+sections.
That's it! That's a simple and complete linker script.
There are a few other linker scripts commands.
@table @code
+@item ASSERT(@var{exp}, @var{message})
+@kindex ASSERT
+@cindex assertion in linker script
+Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
+with an error code, and print @var{message}.
+
+@item EXTERN(@var{symbol} @var{symbol} @dots{})
+@kindex EXTERN
+@cindex undefined symbol in linker script
+Force @var{symbol} to be entered in the output file as an undefined
+symbol. Doing this may, for example, trigger linking of additional
+modules from standard libraries. You may list several @var{symbol}s for
+each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
+command has the same effect as the @samp{-u} command-line option.
+
@item FORCE_COMMON_ALLOCATION
@kindex FORCE_COMMON_ALLOCATION
-@cindex common allocation
+@cindex common allocation in linker script
This command has the same effect as the @samp{-d} command-line option:
to make @code{ld} assign space to common symbols even if a relocatable
output file is specified (@samp{-r}).
@}
@end smallexample
-In this example, if the program defines @samp{_etext}, the linker will
-give a multiple definition error. If, on the other hand, the program
-defines @samp{etext}, the linker will silently use the definition in the
-program. If the program references @samp{etext} but does not define it,
-the linker will use the definition in the linker script.
+In this example, if the program defines @samp{_etext} (with a leading
+underscore), the linker will give a multiple definition error. If, on
+the other hand, the program defines @samp{etext} (with no leading
+underscore), the linker will silently use the definition in the program.
+If the program references @samp{etext} but does not define it, the
+linker will use the definition in the linker script.
@node SECTIONS
@section SECTIONS command
@var{output-section-command}
@var{output-section-command}
@dots{}
- @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+ @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
@end group
@end smallexample
* Input Section Basics:: Input section basics
* Input Section Wildcards:: Input section wildcard patterns
* Input Section Common:: Input section for common symbols
+* Input Section Keep:: Input section and garbage collection
* Input Section Example:: Input section example
@end menu
*(.text)
@end smallexample
@noindent
-Here the @samp{*} is a wildcard which matches any file name.
+Here the @samp{*} is a wildcard which matches any file name. To exclude a list
+of files from matching the file name wildcard, EXCLUDE_FILE may be used to
+match all files except the ones specified in the EXCLUDE_FILE list. For
+example:
+@smallexample
+(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
+@end smallexample
+will cause all .ctors sections from all files except @file{crtend.o} and
+@file{otherfile.o} to be included.
There are two ways to include more than one section:
@smallexample
.data1 : @{ data.o(.data) @}
@end smallexample
+@cindex SORT
+Normally, the linker will place files and sections matched by wildcards
+in the order in which they are seen during the link. You can change
+this by using the @code{SORT} keyword, which appears before a wildcard
+pattern in parentheses (e.g., @code{SORT(.text*)}). When the
+@code{SORT} keyword is used, the linker will sort the files or sections
+into ascending order by name before placing them in the output file.
+
If you ever get confused about where input sections are going, use the
@samp{-M} linker option to generate a map file. The map file shows
precisely how input sections are mapped to output sections.
notation is now considered obsolete. It is equivalent to
@samp{*(COMMON)}.
+@node Input Section Keep
+@subsubsection Input section and garbage collection
+@cindex KEEP
+@cindex garbage collection
+When link-time garbage collection is in use (@samp{--gc-sections}),
+it is often useful to mark sections that should not be eliminated.
+This is accomplished by surrounding an input section's wildcard entry
+with @code{KEEP()}, as in @code{KEEP(*(.init))} or
+@code{KEEP(SORT(*)(.ctors))}.
+
@node Input Section Example
@subsubsection Input section example
The following example is a complete linker script. It tells the linker
true of, for example, S-records, the value will be stored in the
endianness of the first input object file.
+Note - these commands only work inside a section description and not
+between them, so the following will produce an error from the linker:
+@smallexample
+SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
+@end smallexample
+whereas this will work:
+@smallexample
+SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
+@end smallexample
+
@kindex FILL(@var{expression})
@cindex holes, filling
@cindex unspecified memory
__DTOR_END__ = .;
@end smallexample
+If you are using the @sc{gnu} C++ support for initialization priority,
+which provides some control over the order in which global constructors
+are run, you must sort the constructors at link time to ensure that they
+are executed in the correct order. When using the @code{CONSTRUCTORS}
+command, use @samp{SORT(CONSTRUCTORS)} instead. When using the
+@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and
+@samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and
+@samp{*(.dtors)}.
+
Normally the compiler and linker will handle these issues automatically,
and you will not need to concern yourself with them. However, you may
need to consider this if you are using C++ and writing your own linker
scripts.
+
@end table
@node Output Section Discarding
section command, such as a symbol assignment, then the output section
will always be created, even if there are no matching input sections.
+@cindex /DISCARD/
The special output section name @samp{/DISCARD/} may be used to discard
input sections. Any input sections which are assigned to an output
section named @samp{/DISCARD/} are not included in the output file.
@var{output-section-command}
@var{output-section-command}
@dots{}
- @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+ @} [>@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
@node Output Section LMA
@subsubsection Output section LMA
+@kindex AT>@var{lma_region}
@kindex AT(@var{lma})
@cindex load address
@cindex section load 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.
+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}.
@cindex ROM initialized data
@cindex initialized data in ROM
using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
one or more segments, then all subsequent allocated sections will be
assigned to those segments as well, unless they use an explicitly
-@code{:@var{phdr}} modifier. To prevent a section from being assigned
-to a segment when it would normally default to one, use @code{:NONE}.
+@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
+linker to not put the section in any segment at all.
Here is a simple example:
@smallexample
@end group
@end smallexample
-If you have defined a memory region named @samp{mem}, you can direct the
-linker to place specific output sections into that memory region by
-using the @samp{>@var{region}} output section attribute. @xref{Output
-Section Region}. If no address was specified for the output section,
-the linker will set the address to the next available address within the
-memory region. If the combined output sections directed to a memory
-region are too large for the region, the linker will issue an error
-message.
+Once you define a memory region, you can direct the linker to place
+specific output sections into that memory region by using the
+@samp{>@var{region}} output section attribute. For example, if you have
+a memory region named @samp{mem}, you would use @samp{>mem} in the
+output section definition. @xref{Output Section Region}. If no address
+was specified for the output section, the linker will set the address to
+the next available address within the memory region. If the combined
+output sections directed to a memory region are too large for the
+region, the linker will issue an error message.
@node PHDRS
@section PHDRS Command
then the linker will place all subsequent allocatable sections which do
not specify @samp{:@var{phdr}} in the same segments. This is for
convenience, since generally a whole set of contiguous sections will be
-placed in a single segment. To prevent a section from being assigned to
-a segment when it would normally default to one, use @code{:NONE}.
+placed in a single segment. You can use @code{:NONE} to override the
+default segment and tell the linker to not put the section in any
+segment at all.
@kindex FILEHDR
@kindex PHDRS
@samp{.text} section from @file{file3}. The notation @samp{= 0x1234}
specifies what data to write in the gaps (@pxref{Output Section Fill}).
+@cindex dot inside sections
+Note: @code{.} actually refers to the byte offset from the start of the
+current containing object. Normally this is the @code{SECTIONS}
+statement, whoes start address is 0, hence @code{.} can be used as an
+absolute address. If @code{.} is used inside a section description
+however, it refers to the byte offset from the start of that section,
+not an absolute address. Thus in a script like this:
+
+@smallexample
+SECTIONS
+@{
+ . = 0x100
+ .text: @{
+ *(.text)
+ . = 0x200
+ @}
+ . = 0x500
+ .data: @{
+ *(.data)
+ . += 0x600
+ @}
+@}
+@end smallexample
+
+The @samp{.text} section will be assigned a starting address of 0x100
+and a size of exactly 0x200 bytes, even if there is not enough data in
+the @samp{.text} input sections to fill this area. (If there is too
+much data, an error will be produced because this would be an attempt to
+move @code{.} backwards). The @samp{.data} section will start at 0x500
+and it will have an extra 0x600 bytes worth of space after the end of
+the values from the @samp{.data} input sections and before the end of
+the @samp{.data} output section itself.
+
@need 2000
@node Operators
@subsection Operators
@smallexample
@group
-SECTIONS@{ @dots{}
+SECTIONS @{ @dots{}
.text : @{
begin = DEFINED(begin) ? begin : . ;
@dots{}
@}
-@dots{} @}
+ @dots{}
+@}
@end group
@end smallexample
@menu
* H8/300:: @code{ld} and the H8/300
* i960:: @code{ld} and the Intel 960 family
+* ARM:: @code{ld} and the ARM family
+* HPPA ELF32:: @code{ld} and HPPA 32-bit ELF
+@ifset TICOFF
+* TI COFF:: @code{ld} and TI COFF
+@end ifset
@end menu
@end ifset
@ifclear GENERIC
@raisesections
@end ifclear
+
@node H8/300
@section @code{ld} and the H8/300
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
top page of memory).
@end table
+
@ifclear GENERIC
@lowersections
@end ifclear
@ifclear GENERIC
@raisesections
@end ifclear
+
@node i960
@section @code{ld} and the Intel 960 family
@end ifclear
@end ifset
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node ARM
+@section @code{ld}'s support for interworking between ARM and Thumb code
+
+@cindex ARM interworking support
+@kindex --support-old-code
+For the ARM, @code{ld} will generate code stubs to allow functions calls
+betweem 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
+option then the @samp{--support-old-code} command line switch should be
+given to the linker. This will make it generate larger stub functions
+which will work with non-interworking aware ARM code. Note, however,
+the linker does not support generating stubs for function calls to
+non-interworking aware Thumb code.
+
+@cindex thumb entry point
+@cindex entry point, thumb
+@kindex --thumb-entry=@var{entry}
+The @samp{--thumb-entry} switch is a duplicate of the generic
+@samp{--entry} switch, in that it sets the program's starting address.
+But it also sets the bottom bit of the address, so that it can be
+branched to using a BX instruction, and the program will start
+executing in Thumb mode straight away.
+
+@node HPPA ELF32
+@section @code{ld} and HPPA 32-bit ELF support
+@cindex HPPA multiple sub-space stubs
+@kindex --multi-subspace
+When generating a shared library, @code{ld} will by default generate
+import stubs suitable for use with a single sub-space application.
+The @samp{--multi-subspace} switch causes @code{ld} to generate export
+stubs, and different (larger) import stubs suitable for use with
+multiple sub-spaces.
+
+@cindex HPPA stub grouping
+@kindex --stub-group-size=@var{N}
+Long branch stubs and import/export stubs are placed by @code{ld} in
+stub sections located between groups of input sections.
+@samp{--stub-group-size} specifies the maximum size of a group of input
+sections handled by one stub section. Since branch offsets are signed,
+a stub section may serve two groups of input sections, one group before
+the stub section, and one group after it. However, when using
+conditional branches that require stubs, it may be better (for branch
+prediction) that stub sections only serve one group of input sections.
+A negative value for @samp{N} chooses this scheme, ensuring that
+branches to stubs always use a negative offset. Two special values of
+@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
+@code{ld} to automatically size input section groups for the branch types
+detected, with the same behaviour regarding stub placement as other
+positive or negative values of @samp{N} respectively.
+
+Note that @samp{--stub-group-size} does not split input sections. A
+single input section larger than the group size specified will of course
+create a larger group (of one section). If input sections are too
+large, it may not be possible for a branch to reach its stub.
+
+@ifset TICOFF
+@node TI COFF
+@section @code{ld}'s support for various TI COFF versions
+@cindex TI COFF versions
+@kindex --format=@var{version}
+The @samp{--format} switch allows selection of one of the various
+TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
+also supported. The TI COFF versions also vary in header byte-order
+format; @code{ld} will read any version or byte order, but the output
+header format depends on the default specified by the specific target.
+@end ifset
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+
@ifclear SingleFormat
@node BFD
@chapter BFD
projects / deliverable / binutils-gdb.git / blobdiff