\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
@syncodeindex ky cp
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
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 Free Software Foundation, Inc.
+2001, 2002, 2003, 2004 Free Software Foundation, Inc.
@ignore
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003 Free Software Foundation, Inc.
+2002, 2003, 2004 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
Set the text and data sections to be readable and writable. Also, do
not page-align the data segment, and disable linking against shared
libraries. If the output format supports Unix style magic numbers,
-mark the output as @code{OMAGIC}.
+mark the output as @code{OMAGIC}. Note: Although a writable text section
+is allowed for PE-COFF targets, it does not conform to the format
+specification published by Microsoft.
@kindex --no-omagic
@cindex OMAGIC
so the @samp{--accept-unknown-input-arch} option has been added to
restore the old behaviour.
+@kindex --as-needed
+@kindex --no-as-needed
+@item --as-needed
+@itemx --no-as-needed
+This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
+on the command line after the @option{--as-needed} option. Normally,
+the linker will add a DT_NEEDED tag for each dynamic library mentioned
+on the command line, regardless of whether the library is actually
+needed. @option{--as-needed} causes DT_NEEDED tags to only be emitted
+for libraries that satisfy some reference from regular objects.
+@option{--no-as-needed} restores the default behaviour.
+
@kindex -assert @var{keyword}
@item -assert @var{keyword}
This option is ignored for SunOS compatibility.
default on such platforms. The different variants of this option are
for compatibility with various systems. You may use this option
multiple times on the command line: it affects library searching for
-@option{-l} options which follow it. This
-option also implies @option{--unresolved-symbols=ignore-all}.
+@option{-l} options which follow it.
@kindex -Bgroup
@item -Bgroup
linker is normally correct; don't use this unless you know what you are
doing.
-@cindex MIPS embedded PIC code
-@kindex --embedded-relocs
-@item --embedded-relocs
-This option is only meaningful when linking MIPS embedded PIC code,
-generated by the -membedded-pic option to the @sc{gnu} compiler and
-assembler. It causes the linker to create a table which may be used at
-runtime to relocate any data which was statically initialized to pointer
-values. See the code in testsuite/ld-empic for details.
-
@kindex --fatal-warnings
@item --fatal-warnings
@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.
+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.
@cindex help
@cindex usage
@table @samp
@item ignore-all
-Do not report any unresolved symbols. This is the default when
-creating shared libraries or dynamic executables.
+Do not report any unresolved symbols.
@item report-all
-Report all unresolved symbols. This is the default when creating
-static binaries.
+Report all unresolved symbols. This is the default.
@item ignore-in-object-files
Report unresolved symbols that are contained in shared libraries, but
@smallexample
void *
-__wrap_malloc (int c)
+__wrap_malloc (size_t c)
@{
- printf ("malloc called with %ld\n", c);
+ printf ("malloc called with %zu\n", c);
return __real_malloc (c);
@}
@end smallexample
created. By default, the new dynamic tags are not created. Note that
those options are only available for ELF systems.
+@kindex --hash-size=@var{number}
+Set the default size of the linker's hash tables to a prime number
+close to @var{number}. Increasing this value can reduce the length of
+time it takes the linker to perform its tasks, at the expense of
+increasing the linker's memory requirements. Similarly reducing this
+value can reduce the memory requirements at the expense of speed.
+
+@kindex --reduce-memory-overheads
+@item --reduce-memory-overheads
+This option reduces memory requirements at ld runtime, at the expense of
+linking speed. This was introduced to to select the old O(n^2) algorithm
+for link map file generation, rather than the new O(n) algorithm which uses
+about 40% more memory for symbol storage.
+
+Another affect of the switch is to set the default hash table size to
+1021, which again saves memory at the cost of lengthening the linker's
+run time. This is not done however if the @option{--hash-size} switch
+has been used.
+
+The @option{--reduce-memory-overheads} switch may be also be used to
+enable other tradeoffs in future versions of the linker.
+
@end table
@c man end
symbols before they are exported.
[This option is specific to the i386 PE targeted port of the linker]
+@kindex --large-address-aware
+@item --large-address-aware
+If given, the appropriate bit in the ``Charateristics'' 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
+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 --major-image-version
@item --major-image-version @var{value}
Sets the major number of the ``image version''. Defaults to 1.
@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
-building the import libraries with those DATA exports. This generally
-will 'just work' -- but sometimes you may see this message:
+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
+specification published by Microsoft.
+
+Using 'auto-import' generally will 'just work' -- but sometimes you may
+see this message:
"variable '<var>' can't be auto-imported. Please read the
documentation for ld's @code{--enable-auto-import} for details."
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
+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
Discarding}.
@node Output Section Address
-@subsection Output Section Description
+@subsection Output Section Address
@cindex address, section
@cindex section address
The @var{address} is an expression for the VMA (the virtual memory
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. Alternatively, with @samp{AT>@var{lma_region}} expression,
-you may specify a memory region for the section's load address. @xref{MEMORY}.
+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.
+@xref{Output Section Region}.
@cindex ROM initialized data
@cindex initialized data in ROM
@end group
@end smallexample
-@item ALIGN(@var{exp})
-@kindex ALIGN(@var{exp})
+@item ALIGN(@var{align})
+@itemx ALIGN(@var{exp},@var{align})
+@kindex ALIGN(@var{align})
+@kindex ALIGN(@var{exp},@var{align})
@cindex round up location counter
@cindex align location counter
-Return the location counter (@code{.}) aligned to the next @var{exp}
-boundary.
-@code{ALIGN} doesn't change the value of the location counter---it just
-does arithmetic on it. Here is an example which aligns the output
-@code{.data} section to the next @code{0x2000} byte boundary after the
-preceding section and sets a variable within the section to the next
-@code{0x8000} boundary after the input sections:
+@cindex round up expression
+@cindex align expression
+Return the location counter (@code{.}) or arbitrary expression aligned
+to the next @var{align} boundary. The single operand @code{ALIGN}
+doesn't change the value of the location counter---it just does
+arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
+expression to be aligned upwards (@code{ALIGN(@var{align})} is
+equivalent to @code{ALIGN(., @var{align})}).
+
+Here is an example which aligns the output @code{.data} section to the
+next @code{0x2000} byte boundary after the preceding section and sets a
+variable within the section to the next @code{0x8000} boundary after the
+input sections:
@smallexample
@group
SECTIONS @{ @dots{}
(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
top page of memory).
+
+@item bit manipulation instructions
+@command{ld} finds all bit manipulation instructions like @code{band, bclr,
+biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
+which use 32 bit and 16 bit absolute address form, but refer to the top
+page of memory, and changes them to use the 8 bit address form.
+(That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into
+@samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
+the top page of memory).
+
+@item system control instructions
+@command{ld} finds all @code{ldc.w, stc.w} instrcutions 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
+@samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
+the top page of memory).
@end table
@ifclear GENERIC
branched to using a BX instruction, and the program will start
executing in Thumb mode straight away.
+@cindex BE8
+@kindex --be8
+The @samp{--be8} switch instructs @command{ld} to generate BE8 format
+executables. This option is only valid when linking big-endian objects.
+The resulting image will contain big-endian data and little-endian code.
+
@ifclear GENERIC
@lowersections
@end ifclear
projects / deliverable / binutils-gdb.git / blobdiff