@c @smallbook
+@c man begin NAME
+@ifset man
+@c Configure for the generation of man pages
+@set UsesEnvVars
+@set GENERIC
+@set A29K
+@set ARC
+@set ARM
+@set D10V
+@set D30V
+@set H8/300
+@set H8/500
+@set HPPA
+@set I370
+@set I80386
+@set I860
+@set I960
+@set M32R
+@set M68HC11
+@set M680X0
+@set MCORE
+@set MIPS
+@set PDP11
+@set PJ
+@set SH
+@set SPARC
+@set C54X
+@set V850
+@set VAX
+@end ifset
+@c man end
+
@ifinfo
@format
START-INFO-DIR-ENTRY
@end tex
@vskip 0pt plus 1filll
+@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 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
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, with no Front-Cover Texts, and with no
- Back-Cover Texts. A copy of the license is included in the
- section entitled "GNU Free Documentation License".
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts. A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+@c man end
@end titlepage
@end iftex
@cindex @sc{gnu} linker
@cindex what is this?
+
+@ifset man
+@c man begin SYNOPSIS
+ld [ options ] objfile...
+@c man end
+
+@c man begin SEEALSO
+ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
+the Info entries for @file{binutils} and
+@file{ld}.
+@c man end
+@end ifset
+
+@c man begin DESCRIPTION
+
@code{ld} combines a number of object and archive files, relocates
their data and ties up symbol references. Usually the last step in
compiling a program is to run @code{ld}.
a superset of AT&T's Link Editor Command Language syntax,
to provide explicit and total control over the linking process.
+@ifset man
+@c For the man only
+This man page does not describe the command language; see the
+@code{ld} entry in @code{info}, or the manual
+ld: the GNU linker, for full details on the command language and
+on other aspects of the GNU linker.
+@end ifset
+
@ifclear SingleFormat
This version of @code{ld} uses the general purpose BFD libraries
to operate on object files. This allows @code{ld} to read, combine, and
@code{ld} continues executing, allowing you to identify other errors
(or, in some cases, to get an output file in spite of the error).
+@c man end
+
@node Invocation
@chapter Invocation
+@c man begin DESCRIPTION
+
The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations,
and to be as compatible as possible with other linkers. As a result,
you have many choices to control its behavior.
+@c man end
+
@ifset UsesEnvVars
@menu
* Options:: Command Line Options
@cindex command line
@cindex options
+
+@c man begin OPTIONS
+
The linker supports a plethora of command-line options, but in actual
practice few of them are used in any particular context.
@cindex standard Unix system
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}.
@xref{Environment}.
@end ifset
You can also define the input format from a script, using the command
-@code{TARGET}; see @ref{Format Commands}.
+@code{TARGET};
+@ifclear man
+see @ref{Format Commands}.
+@end ifclear
@end ifclear
@kindex -c @var{MRI-cmdfile}
@itemx --mri-script=@var{MRI-commandfile}
For compatibility with linkers produced by MRI, @code{ld} accepts script
files written in an alternate, restricted command language, described in
-@ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
+@ifclear man
+@ref{MRI,,MRI Compatible Script Files}.
+@end ifclear
+@ifset man
+the MRI Compatible Script Files section of GNU ld documentation.
+@end ifset
+Introduce MRI script files with
the option @samp{-c}; use the @samp{-T} option to run linker
scripts written in the general-purpose @code{ld} scripting language.
If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
@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}
@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.
@cindex dynamic linker, from command line
+@kindex -I@var{file}
@kindex --dynamic-linker @var{file}
@item --dynamic-linker @var{file}
Set the name of the dynamic linker. This is only meaningful when
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
+Treat all warnings as errors.
+
@kindex --force-exe-suffix
@item --force-exe-suffix
Make sure that an output file has a .exe suffix.
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
is only meaningful on ELF platforms which support shared libraries.
@xref{VERSION}.
-@kindex --warn-comon
+@kindex --warn-common
@cindex warnings, on combining symbols
@cindex combining symbols, warnings on
@item --warn-common
@end table
+@c man end
+
@subsection Options specific to i386 PE targets
+@c man begin OPTIONS
+
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
@end table
+@c man end
+
@ifset UsesEnvVars
@node Environment
@section Environment Variables
+@c man begin ENVIRONMENT
+
You can change the behavior of @code{ld} with the environment variables
@code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}.
the @samp{-m} option is not used, and the @code{LDEMULATION} environment
variable is not defined, the default emulation depends upon how the
linker was configured.
-@end ifset
@kindex COLLECT_NO_DEMANGLE
@cindex demangling, default
may be overridden by the @samp{--demangle} and @samp{--no-demangle}
options.
+@c man end
+@end ifset
+
@node Scripts
@chapter Linker Scripts
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.
@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