@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, 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
@subtitle The GNU linker
@sp 1
@subtitle @code{ld} version 2
-@subtitle April 1998
+@subtitle Version @value{VERSION}
@author Steve Chamberlain
@author Ian Lance Taylor
@author Cygnus Solutions
@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
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},
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}
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.
+
@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 -v
@kindex -V
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
+@kindex --no-demangle
+@item --demangle
+@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. 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
instructions in the output object file.
On some platforms these link time global optimizations may make symbolic
-debugging of the resulting executable impossible. This is known to be
+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,
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.
@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
@node Environment
@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
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 in linker script
* 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 file
+from matching the file name wildcard, EXCLUDE_FILE may be used to match all files
+except the one specified by EXCLUDE_FILE. For example:
+@smallexample
+(*(EXCLUDE_FILE (*crtend.o) .ctors))
+@end smallexample
+will cause all .ctors sections from all files except crtend.o to be included.
There are two ways to include more than one section:
@smallexample
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
__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.
@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
@section @code{ld}'s support for interworking between ARM and Thumb code
@cindex ARM interworking support
-@cindex --support-old-code
+@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
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.
+
@ifclear GENERIC
@lowersections
@end ifclear
projects / deliverable / binutils-gdb.git / blobdiff