\input texinfo
@setfilename ld.info
+@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
+@c 2001 Free Software Foundation, Inc.
@syncodeindex ky cp
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
option that requires them.
For options whose names are multiple letters, either one dash or two can
-precede the option name; for example, @samp{--oformat} and
-@samp{--oformat} are equivalent. Arguments to multiple-letter options
-must either be separated from the option name by an equals sign, or be
-given as separate arguments immediately following the option that
-requires them. For example, @samp{--oformat srec} and
-@samp{--oformat=srec} are equivalent. Unique abbreviations of the names
-of multiple-letter options are accepted.
+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
+@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.
+
+Arguments to multiple-letter options must either be separated from the
+option name by an equals sign, or be given as separate arguments
+immediately following the option that requires them. For example,
+@samp{--trace-symbol foo} and @samp{--trace-symbol=foo} 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
binary format. You can also use @samp{-b} to switch formats explicitly (when
linking object files of different formats), by including
@samp{-b @var{input-format}} before each group of object files in a
-particular format.
+particular format.
The default format is taken from the environment variable
@code{GNUTARGET}.
@kindex -d
@kindex -dc
@kindex -dp
-@item -d
+@item -d
@itemx -dc
@itemx -dp
These three options are equivalent; multiple forms are supported for
@cindex entry point, from command line
@kindex -e @var{entry}
@kindex --entry=@var{entry}
-@item -e @var{entry}
+@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. If there is no symbol
@cindex search directory, from cmd line
@kindex -L@var{dir}
@kindex --library-path=@var{dir}
-@item -L@var{searchdir}
+@item -L@var{searchdir}
@itemx --library-path=@var{searchdir}
Add path @var{searchdir} to the list of paths that @code{ld} will search
for archive libraries and @code{ld} control scripts. You may use this
@item -n
@itemx --nmagic
Turn off page alignment of sections, and mark the output as
-@code{NMAGIC} if possible.
+@code{NMAGIC} if possible.
@kindex -N
@kindex --omagic
@cindex read/write from cmd line
@cindex OMAGIC
-@item -N
+@item -N
@itemx --omagic
Set the text and data sections to be readable and writable. Also, do
not page-align the data segment. If the output format supports Unix
linking}. As a side effect, in environments that support standard Unix
magic numbers, this option also sets the output file's magic number to
@code{OMAGIC}.
-@c ; see @code{-N}.
+@c ; see @code{-N}.
If this option is not specified, an absolute file is produced. When
linking C++ programs, this option @emph{will not} resolve references to
constructors; to do that, use @samp{-Ur}.
@kindex -s
@kindex --strip-all
@cindex strip all symbols
-@item -s
+@item -s
@itemx --strip-all
Omit all symbol information from the output file.
@kindex -S
@kindex --strip-debug
@cindex strip debugger symbols
-@item -S
+@item -S
@itemx --strip-debug
Omit debugger symbol information (but not all symbols) from the output file.
@kindex -t
@kindex --trace
@cindex input files, displaying
-@item -t
+@item -t
@itemx --trace
Print the names of the input files as @code{ld} processes them.
@kindex -Ur
@cindex constructors
-@item -Ur
+@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}
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 --unique[=@var{SECTION}]
+@item --unique[=@var{SECTION}]
+Creates a separate output section for every input section matching
+@var{SECTION}, or if the optional wildcard @var{SECTION} argument is
+missing, for every orphan input section. An orphan section is one not
+specifically mentioned in a linker script. You may use this option
+multiple times on the command line; It prevents the normal merging of
+input sections with the same name, overriding output section assignments
+in a linker script.
@kindex -v
@kindex -V
@kindex --discard-locals
@cindex local symbols, deleting
@cindex L, deleting symbols beginning
-@item -X
+@item -X
@itemx --discard-locals
Delete all temporary local symbols. For most targets, this is all local
symbols whose names begin with @samp{L}.
@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.
+@code{defs} disallows undefined symbols.
@kindex -(
@cindex groups of archives
multiple times on the command line: it affects library searching for
@code{-l} options which follow it.
+@kindex -Bgroup
+@item -Bgroup
+Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
+section. This causes the runtime linker to handle lookups in this
+object and its dependencies to be performed only inside the group.
+@code{--no-undefined} is implied. This option is only meaningful on ELF
+platforms which support shared libraries.
+
@kindex -Bstatic
@kindex -dn
@kindex -non_shared
@kindex -static
-@item -Bstatic
+@item -Bstatic
@itemx -dn
@itemx -non_shared
@itemx -static
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
+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.
while linking a large executable.
@kindex --no-undefined
+@kindex -z defs
@item --no-undefined
+@itemx -z defs
Normally when creating a non-symbolic shared library, undefined symbols
-are allowed and left to be resolved by the runtime loader. This option
+are allowed and left to be resolved by the runtime loader. These options
disallows such undefined symbols.
@kindex --allow-shlib-undefined
@cindex synthesizing linker
@cindex relaxing addressing modes
@item --relax
-An option with machine dependent effects.
+An option with machine dependent effects.
@ifset GENERIC
This option is only supported on a few targets.
@end ifset
library, forcing every object to be included in the resulting shared
library. This option may be used more than once.
+Two notes when using this option from gcc: First, gcc doesn't know
+about this option, so you have to use @code{-Wl,-whole-archive}.
+Second, don't forget to use @code{-Wl,-no-whole-archive} after your
+list of archives, because gcc will add its own list of archives to
+your link and you may not want this flag to affect those as well.
+
@kindex --wrap
@item --wrap @var{symbol}
Use a wrapper function for @var{symbol}. Any undefined reference to
entry point by trying each of the following methods in order, and
stopping when one of them succeeds:
@itemize @bullet
-@item
+@item
the @samp{-e} @var{entry} command-line option;
-@item
+@item
the @code{ENTRY(@var{symbol})} command in a linker script;
-@item
+@item
the value of the symbol @code{start}, if defined;
-@item
+@item
the address of the first byte of the @samp{.text} section, if present;
-@item
+@item
The address @code{0}.
@end itemize
@subsection Output section description
The full description of an output section looks like this:
@smallexample
-@group
+@group
@var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
@{
@var{output-section-command}
@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.
+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))}.
@}
@}
@end group
-@end smallexample
+@end smallexample
@node Output Section Data
@subsection Output section data
We showed above that the full description of an output section looked
like this:
@smallexample
-@group
+@group
@var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
@{
@var{output-section-command}
@var{output-section-command}. In this section we will describe the
remaining section attributes.
-@menu
+@menu
* Output Section Type:: Output section type
* Output Section LMA:: Output section LMA
* Output Section Region:: Output section region
SECTIONS
@{
.text 0x1000 : @{ *(.text) _etext = . ; @}
- .mdata 0x2000 :
+ .mdata 0x2000 :
AT ( ADDR (.text) + SIZEOF (.text) )
@{ _data = . ; *(.data); _edata = . ; @}
.bss 0x3000 :
you wish. The syntax is:
@smallexample
@group
-MEMORY
+MEMORY
@{
@var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
@dots{}
@smallexample
@group
-MEMORY
+MEMORY
@{
rom (rx) : ORIGIN = 0, LENGTH = 256K
ram (!rx) : org = 0x40000000, l = 4M
global:
foo1;
local:
- old*;
- original*;
- new*;
+ old*;
+ original*;
+ new*;
@};
VERS_1.2 @{
(lowest)
@end smallexample
Notes:
-(1) Prefix operators
+(1) Prefix operators
(2) @xref{Assignments}.
@c TEXI2ROFF-KILL
@end ifinfo
height2pt&\omit&&\omit&&\omit&\cr
&highest&&&&&\cr
% '176 is tilde, '~' in tt font
-&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
+&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
&2&&left&&* / \%&\cr
&3&&left&&+ -&\cr
&4&&left&&>> <<&\cr
@group
SECTIONS
@{
- .text 9+this_isnt_constant :
+ .text 9+this_isnt_constant :
@{ *(.text) @}
@}
@end group
@group
SECTIONS @{ @dots{}
.output1 :
- @{
+ @{
start_of_output_1 = ABSOLUTE(.);
@dots{}
@}
@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.
+@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.
distribution.
Otherwise, send bug reports for @code{ld} to
-@samp{bug-gnu-utils@@gnu.org}.
+@samp{bug-binutils@@gnu.org}.
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
@cindex @code{FORMAT} (MRI)
@item FORMAT @var{output-format}
Similar to the @code{OUTPUT_FORMAT} command in the more general linker
-language, but restricted to one of these output formats:
+language, but restricted to one of these output formats:
@enumerate
-@item
+@item
S-records, if @var{output-format} is @samp{S}
@item
@cindex GNU Free Documentation License
GNU Free Documentation License
-
+
Version 1.1, March 2000
Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
+
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@contents
@bye
-
-
projects / deliverable / binutils-gdb.git / blobdiff