6064 lines
224 KiB
Plaintext
6064 lines
224 KiB
Plaintext
\input texinfo
|
|
@setfilename ld.info
|
|
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
|
|
@c 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
|
|
@syncodeindex ky cp
|
|
@include configdoc.texi
|
|
@c (configdoc.texi is generated by the Makefile)
|
|
@include ldver.texi
|
|
|
|
@c @smallbook
|
|
|
|
@macro gcctabopt{body}
|
|
@code{\body\}
|
|
@end macro
|
|
|
|
@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 MMIX
|
|
@set MSP430
|
|
@set PDP11
|
|
@set PJ
|
|
@set SH
|
|
@set SPARC
|
|
@set TIC54X
|
|
@set V850
|
|
@set VAX
|
|
@set WIN32
|
|
@set XTENSA
|
|
@end ifset
|
|
@c man end
|
|
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Ld: (ld). The GNU linker.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
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, 2004 Free Software Foundation, Inc.
|
|
|
|
@ignore
|
|
|
|
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 process this file through Tex and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
@end ifinfo
|
|
@iftex
|
|
@finalout
|
|
@setchapternewpage odd
|
|
@settitle Using LD, the GNU linker
|
|
@titlepage
|
|
@title Using ld
|
|
@subtitle The GNU linker
|
|
@sp 1
|
|
@subtitle @code{ld} version 2
|
|
@subtitle Version @value{VERSION}
|
|
@author Steve Chamberlain
|
|
@author Ian Lance Taylor
|
|
@page
|
|
|
|
@tex
|
|
{\parskip=0pt
|
|
\hfill Red Hat Inc\par
|
|
\hfill nickc\@credhat.com, doc\@redhat.com\par
|
|
\hfill {\it Using LD, the GNU linker}\par
|
|
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
|
|
}
|
|
\global\parindent=0pt % Steve likes it this way.
|
|
@end tex
|
|
|
|
@vskip 0pt plus 1filll
|
|
@c man begin COPYRIGHT
|
|
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
|
|
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
|
|
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
|
|
@c FIXME: Talk about importance of *order* of args, cmds to linker!
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Using ld
|
|
This file documents the @sc{gnu} linker ld version @value{VERSION}.
|
|
|
|
This document is distributed under the terms of the GNU Free
|
|
Documentation License. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.
|
|
|
|
@menu
|
|
* Overview:: Overview
|
|
* Invocation:: Invocation
|
|
* Scripts:: Linker Scripts
|
|
@ifset GENERIC
|
|
* Machine Dependent:: Machine Dependent Features
|
|
@end ifset
|
|
@ifclear GENERIC
|
|
@ifset H8300
|
|
* H8/300:: ld and the H8/300
|
|
@end ifset
|
|
@ifset Renesas
|
|
* Renesas:: ld and other Renesas micros
|
|
@end ifset
|
|
@ifset I960
|
|
* i960:: ld and the Intel 960 family
|
|
@end ifset
|
|
@ifset ARM
|
|
* ARM:: ld and the ARM family
|
|
@end ifset
|
|
@ifset HPPA
|
|
* HPPA ELF32:: ld and HPPA 32-bit ELF
|
|
@end ifset
|
|
@ifset M68HC11
|
|
* M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families
|
|
@end ifset
|
|
@ifset TICOFF
|
|
* TI COFF:: ld and the TI COFF
|
|
@end ifset
|
|
@ifset WIN32
|
|
* Win32:: ld and WIN32 (cygwin/mingw)
|
|
@end ifset
|
|
@ifset XTENSA
|
|
* Xtensa:: ld and Xtensa Processors
|
|
@end ifset
|
|
@end ifclear
|
|
@ifclear SingleFormat
|
|
* BFD:: BFD
|
|
@end ifclear
|
|
@c Following blank line required for remaining bug in makeinfo conds/menus
|
|
|
|
* Reporting Bugs:: Reporting Bugs
|
|
* MRI:: MRI Compatible Script Files
|
|
* GNU Free Documentation License:: GNU Free Documentation License
|
|
* Index:: Index
|
|
@end menu
|
|
@end ifnottex
|
|
|
|
@node Overview
|
|
@chapter Overview
|
|
|
|
@cindex @sc{gnu} linker
|
|
@cindex what is this?
|
|
|
|
@ifset man
|
|
@c man begin SYNOPSIS
|
|
ld [@b{options}] @var{objfile} @dots{}
|
|
@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
|
|
|
|
@command{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 @command{ld}.
|
|
|
|
@command{ld} accepts Linker Command Language files written in
|
|
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
|
|
@command{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 @command{ld} uses the general purpose BFD libraries
|
|
to operate on object files. This allows @command{ld} to read, combine, and
|
|
write object files in many different formats---for example, COFF or
|
|
@code{a.out}. Different formats may be linked together to produce any
|
|
available kind of object file. @xref{BFD}, for more information.
|
|
@end ifclear
|
|
|
|
Aside from its flexibility, the @sc{gnu} linker is more helpful than other
|
|
linkers in providing diagnostic information. Many linkers abandon
|
|
execution immediately upon encountering an error; whenever possible,
|
|
@command{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 @command{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
|
|
* Environment:: Environment Variables
|
|
@end menu
|
|
|
|
@node Options
|
|
@section Command Line Options
|
|
@end ifset
|
|
|
|
@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
|
|
For instance, a frequent use of @command{ld} is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file @code{hello.o}:
|
|
|
|
@smallexample
|
|
ld -o @var{output} /lib/crt0.o hello.o -lc
|
|
@end smallexample
|
|
|
|
This tells @command{ld} to produce a file called @var{output} as the
|
|
result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
|
|
the library @code{libc.a}, which will come from the standard search
|
|
directories. (See the discussion of the @samp{-l} option below.)
|
|
|
|
Some of the command-line options to @command{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 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},
|
|
and the script command language. If @emph{no} binary input files at all
|
|
are specified, the linker does not produce any output, and issues the
|
|
message @samp{No input files}.
|
|
|
|
If the linker cannot recognize the format of an object file, it will
|
|
assume that it is a linker script. A script specified in this way
|
|
augments the main linker script used for the link (either the default
|
|
linker script or the one specified by using @samp{-T}). This feature
|
|
permits the linker to link against a file which appears to be an object
|
|
or an archive, but actually merely defines some symbol values, or uses
|
|
@code{INPUT} or @code{GROUP} to load other objects. Note that
|
|
specifying a script in this way merely augments the main linker script;
|
|
use the @samp{-T} option to replace the default linker script entirely.
|
|
@xref{Scripts}.
|
|
|
|
For options whose names are a single letter,
|
|
option arguments must either follow the option letter without intervening
|
|
whitespace, or be given as separate arguments immediately following the
|
|
option that requires them.
|
|
|
|
For options whose names are multiple letters, either one dash or two can
|
|
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
|
|
(e.g. @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 @gcctabopt
|
|
@kindex -a@var{keyword}
|
|
@item -a@var{keyword}
|
|
This option is supported for HP/UX compatibility. The @var{keyword}
|
|
argument must be one of the strings @samp{archive}, @samp{shared}, or
|
|
@samp{default}. @samp{-aarchive} is functionally equivalent to
|
|
@samp{-Bstatic}, and the other two keywords are functionally equivalent
|
|
to @samp{-Bdynamic}. This option may be used any number of times.
|
|
|
|
@ifset I960
|
|
@cindex architectures
|
|
@kindex -A@var{arch}
|
|
@item -A@var{architecture}
|
|
@kindex --architecture=@var{arch}
|
|
@itemx --architecture=@var{architecture}
|
|
In the current release of @command{ld}, this option is useful only for the
|
|
Intel 960 family of architectures. In that @command{ld} configuration, the
|
|
@var{architecture} argument identifies the particular architecture in
|
|
the 960 family, enabling some safeguards and modifying the
|
|
archive-library search path. @xref{i960,,@command{ld} and the Intel 960
|
|
family}, for details.
|
|
|
|
Future releases of @command{ld} may support similar functionality for
|
|
other architecture families.
|
|
@end ifset
|
|
|
|
@ifclear SingleFormat
|
|
@cindex binary input format
|
|
@kindex -b @var{format}
|
|
@kindex --format=@var{format}
|
|
@cindex input format
|
|
@cindex input format
|
|
@item -b @var{input-format}
|
|
@itemx --format=@var{input-format}
|
|
@command{ld} may be configured to support more than one kind of object
|
|
file. If your @command{ld} is configured this way, you can use the
|
|
@samp{-b} option to specify the binary format for input object files
|
|
that follow this option on the command line. Even when @command{ld} is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as @command{ld} should be configured to expect as a
|
|
default input format the most usual format on each machine.
|
|
@var{input-format} is a text string, the name of a particular format
|
|
supported by the BFD libraries. (You can list the available binary
|
|
formats with @samp{objdump -i}.)
|
|
@xref{BFD}.
|
|
|
|
You may want to use this option if you are linking files with an unusual
|
|
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.
|
|
|
|
The default format is taken from the environment variable
|
|
@code{GNUTARGET}.
|
|
@ifset UsesEnvVars
|
|
@xref{Environment}.
|
|
@end ifset
|
|
You can also define the input format from a script, using the command
|
|
@code{TARGET};
|
|
@ifclear man
|
|
see @ref{Format Commands}.
|
|
@end ifclear
|
|
@end ifclear
|
|
|
|
@kindex -c @var{MRI-cmdfile}
|
|
@kindex --mri-script=@var{MRI-cmdfile}
|
|
@cindex compatibility, MRI
|
|
@item -c @var{MRI-commandfile}
|
|
@itemx --mri-script=@var{MRI-commandfile}
|
|
For compatibility with linkers produced by MRI, @command{ld} accepts script
|
|
files written in an alternate, restricted command language, described in
|
|
@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 @command{ld} scripting language.
|
|
If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
|
|
specified by any @samp{-L} options.
|
|
|
|
@cindex common allocation
|
|
@kindex -d
|
|
@kindex -dc
|
|
@kindex -dp
|
|
@item -d
|
|
@itemx -dc
|
|
@itemx -dp
|
|
These three options are equivalent; multiple forms are supported for
|
|
compatibility with other linkers. They assign space to common symbols
|
|
even if a relocatable output file is specified (with @samp{-r}). The
|
|
script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
|
|
@xref{Miscellaneous Commands}.
|
|
|
|
@cindex entry point, from command line
|
|
@kindex -e @var{entry}
|
|
@kindex --entry=@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
|
|
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.
|
|
|
|
@kindex --exclude-libs
|
|
@item --exclude-libs @var{lib},@var{lib},...
|
|
Specifies a list of archive libraries from which symbols should not be automatically
|
|
exported. The library names may be delimited by commas or colons. Specifying
|
|
@code{--exclude-libs ALL} excludes symbols in all archive libraries from
|
|
automatic export. This option is available only for the i386 PE targeted
|
|
port of the linker and for ELF targeted ports. For i386 PE, symbols
|
|
explicitly listed in a .def file are still exported, regardless of this
|
|
option. For ELF targeted ports, symbols affected by this option will
|
|
be treated as hidden.
|
|
|
|
@cindex dynamic symbol table
|
|
@kindex -E
|
|
@kindex --export-dynamic
|
|
@item -E
|
|
@itemx --export-dynamic
|
|
When creating a dynamically linked executable, add all symbols to the
|
|
dynamic symbol table. The dynamic symbol table is the set of symbols
|
|
which are visible from dynamic objects at run time.
|
|
|
|
If you do not use this option, the dynamic symbol table will normally
|
|
contain only those symbols which are referenced by some dynamic object
|
|
mentioned in the link.
|
|
|
|
If you use @code{dlopen} to load a dynamic object which needs to refer
|
|
back to the symbols defined by the program, rather than some other
|
|
dynamic object, then you will probably need to use this option when
|
|
linking the program itself.
|
|
|
|
You can also use the version script to control what symbols should
|
|
be added to the dynamic symbol table if the output format supports it.
|
|
See the description of @samp{--version-script} in @ref{VERSION}.
|
|
|
|
@ifclear SingleFormat
|
|
@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.
|
|
@end ifclear
|
|
|
|
@kindex -f
|
|
@kindex --auxiliary
|
|
@item -f
|
|
@itemx --auxiliary @var{name}
|
|
When creating an ELF shared object, set the internal DT_AUXILIARY field
|
|
to the specified name. This tells the dynamic linker that the symbol
|
|
table of the shared object should be used as an auxiliary filter on the
|
|
symbol table of the shared object @var{name}.
|
|
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the DT_AUXILIARY field. If
|
|
the dynamic linker resolves any symbols from the filter object, it will
|
|
first check whether there is a definition in the shared object
|
|
@var{name}. If there is one, it will be used instead of the definition
|
|
in the filter object. The shared object @var{name} need not exist.
|
|
Thus the shared object @var{name} may be used to provide an alternative
|
|
implementation of certain functions, perhaps for debugging or for
|
|
machine specific performance.
|
|
|
|
This option may be specified more than once. The DT_AUXILIARY entries
|
|
will be created in the order in which they appear on the command line.
|
|
|
|
@kindex -F
|
|
@kindex --filter
|
|
@item -F @var{name}
|
|
@itemx --filter @var{name}
|
|
When creating an ELF shared object, set the internal DT_FILTER field to
|
|
the specified name. This tells the dynamic linker that the symbol table
|
|
of the shared object which is being created should be used as a filter
|
|
on the symbol table of the shared object @var{name}.
|
|
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the DT_FILTER field. The
|
|
dynamic linker will resolve symbols according to the symbol table of the
|
|
filter object as usual, but it will actually link to the definitions
|
|
found in the shared object @var{name}. Thus the filter object can be
|
|
used to select a subset of the symbols provided by the object
|
|
@var{name}.
|
|
|
|
Some older linkers used the @option{-F} option throughout a compilation
|
|
toolchain for specifying object-file format for both input and output
|
|
object files.
|
|
@ifclear SingleFormat
|
|
The @sc{gnu} linker uses other mechanisms for this purpose: the
|
|
@option{-b}, @option{--format}, @option{--oformat} options, the
|
|
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
|
|
environment variable.
|
|
@end ifclear
|
|
The @sc{gnu} linker will ignore the @option{-F} option when not
|
|
creating an ELF shared object.
|
|
|
|
@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
|
|
Ignored. Provided for compatibility with other tools.
|
|
|
|
@kindex -G
|
|
@kindex --gpsize
|
|
@cindex object size
|
|
@item -G@var{value}
|
|
@itemx --gpsize=@var{value}
|
|
Set the maximum size of objects to be optimized using the GP register to
|
|
@var{size}. This is only meaningful for object file formats such as
|
|
MIPS ECOFF which supports putting large and small objects into different
|
|
sections. This is ignored for other object file formats.
|
|
|
|
@cindex runtime library name
|
|
@kindex -h@var{name}
|
|
@kindex -soname=@var{name}
|
|
@item -h@var{name}
|
|
@itemx -soname=@var{name}
|
|
When creating an ELF shared object, set the internal DT_SONAME field to
|
|
the specified name. When an executable is linked with a shared object
|
|
which has a DT_SONAME field, then when the executable is run the dynamic
|
|
linker will attempt to load the shared object specified by the DT_SONAME
|
|
field rather than the using the file name given to the linker.
|
|
|
|
@kindex -i
|
|
@cindex incremental link
|
|
@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}
|
|
@item -l@var{archive}
|
|
@itemx --library=@var{archive}
|
|
Add archive file @var{archive} to the list of files to link. This
|
|
option may be used any number of times. @command{ld} will search its
|
|
path-list for occurrences of @code{lib@var{archive}.a} for every
|
|
@var{archive} specified.
|
|
|
|
On systems which support shared libraries, @command{ld} may also search for
|
|
libraries with extensions other than @code{.a}. Specifically, on ELF
|
|
and SunOS systems, @command{ld} will search a directory for a library with
|
|
an extension of @code{.so} before searching for one with an extension of
|
|
@code{.a}. By convention, a @code{.so} extension indicates a shared
|
|
library.
|
|
|
|
The linker will search an archive only once, at the location where it is
|
|
specified on the command line. If the archive defines a symbol which
|
|
was undefined in some object which appeared before the archive on the
|
|
command line, the linker will include the appropriate file(s) from the
|
|
archive. However, an undefined symbol in an object appearing later on
|
|
the command line will not cause the linker to search the archive again.
|
|
|
|
See the @option{-(} option for a way to force the linker to search
|
|
archives multiple times.
|
|
|
|
You may list the same archive multiple times on the command line.
|
|
|
|
@ifset GENERIC
|
|
This type of archive searching is standard for Unix linkers. However,
|
|
if you are using @command{ld} on AIX, note that it is different from the
|
|
behaviour of the AIX linker.
|
|
@end ifset
|
|
|
|
@cindex search directory, from cmd line
|
|
@kindex -L@var{dir}
|
|
@kindex --library-path=@var{dir}
|
|
@item -L@var{searchdir}
|
|
@itemx --library-path=@var{searchdir}
|
|
Add path @var{searchdir} to the list of paths that @command{ld} will search
|
|
for archive libraries and @command{ld} control scripts. You may use this
|
|
option any number of times. The directories are searched in the order
|
|
in which they are specified on the command line. Directories specified
|
|
on the command line are searched before the default directories. All
|
|
@option{-L} options apply to all @option{-l} options, regardless of the
|
|
order in which the options appear.
|
|
|
|
If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
|
|
by the @dfn{sysroot prefix}, a path specified when the linker is configured.
|
|
|
|
@ifset UsesEnvVars
|
|
The default set of paths searched (without being specified with
|
|
@samp{-L}) depends on which emulation mode @command{ld} is using, and in
|
|
some cases also on how it was configured. @xref{Environment}.
|
|
@end ifset
|
|
|
|
The paths can also be specified in a link script with the
|
|
@code{SEARCH_DIR} command. Directories specified this way are searched
|
|
at the point in which the linker script appears in the command line.
|
|
|
|
@cindex emulation
|
|
@kindex -m @var{emulation}
|
|
@item -m@var{emulation}
|
|
Emulate the @var{emulation} linker. You can list the available
|
|
emulations with the @samp{--verbose} or @samp{-V} options.
|
|
|
|
If the @samp{-m} option is not used, the emulation is taken from the
|
|
@code{LDEMULATION} environment variable, if that is defined.
|
|
|
|
Otherwise, the default emulation depends upon how the linker was
|
|
configured.
|
|
|
|
@cindex link map
|
|
@kindex -M
|
|
@kindex --print-map
|
|
@item -M
|
|
@itemx --print-map
|
|
Print a link map to the standard output. A link map provides
|
|
information about the link, including the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Where object files and symbols are mapped into memory.
|
|
@item
|
|
How common symbols are allocated.
|
|
@item
|
|
All archive members included in the link, with a mention of the symbol
|
|
which caused the archive member to be brought in.
|
|
@end itemize
|
|
|
|
@kindex -n
|
|
@cindex read-only text
|
|
@cindex NMAGIC
|
|
@kindex --nmagic
|
|
@item -n
|
|
@itemx --nmagic
|
|
Turn off page alignment of sections, and mark the output as
|
|
@code{NMAGIC} if possible.
|
|
|
|
@kindex -N
|
|
@kindex --omagic
|
|
@cindex read/write from cmd line
|
|
@cindex OMAGIC
|
|
@item -N
|
|
@itemx --omagic
|
|
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}. 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
|
|
@item --no-omagic
|
|
This option negates most of the effects of the @option{-N} option. It
|
|
sets the text section to be read-only, and forces the data segment to
|
|
be page-aligned. Note - this option does not enable linking against
|
|
shared libraries. Use @option{-Bdynamic} for this.
|
|
|
|
@kindex -o @var{output}
|
|
@kindex --output=@var{output}
|
|
@cindex naming the output file
|
|
@item -o @var{output}
|
|
@itemx --output=@var{output}
|
|
Use @var{output} as the name for the program produced by @command{ld}; if this
|
|
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 @command{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.
|
|
|
|
This option is currently only supported on ELF platforms.
|
|
|
|
@cindex partial link
|
|
@cindex relocatable output
|
|
@kindex -r
|
|
@kindex --relocatable
|
|
@item -r
|
|
@itemx --relocatable
|
|
Generate relocatable output---i.e., generate an output file that can in
|
|
turn serve as input to @command{ld}. This is often called @dfn{partial
|
|
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 @option{-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}.
|
|
|
|
When an input file does not have the same format as the output file,
|
|
partial linking is only supported if that input file does not contain any
|
|
relocations. Different output formats can have further restrictions; for
|
|
example some @code{a.out}-based formats do not support partial linking
|
|
with input files in other formats at all.
|
|
|
|
This option does the same thing as @samp{-i}.
|
|
|
|
@kindex -R @var{file}
|
|
@kindex --just-symbols=@var{file}
|
|
@cindex symbol-only input
|
|
@item -R @var{filename}
|
|
@itemx --just-symbols=@var{filename}
|
|
Read symbol names and their addresses from @var{filename}, but do not
|
|
relocate it or include it in the output. This allows your output file
|
|
to refer symbolically to absolute locations of memory defined in other
|
|
programs. You may use this option more than once.
|
|
|
|
For compatibility with other ELF linkers, if the @option{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @option{-rpath} option.
|
|
|
|
@kindex -s
|
|
@kindex --strip-all
|
|
@cindex strip all symbols
|
|
@item -s
|
|
@itemx --strip-all
|
|
Omit all symbol information from the output file.
|
|
|
|
@kindex -S
|
|
@kindex --strip-debug
|
|
@cindex strip debugger symbols
|
|
@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
|
|
@itemx --trace
|
|
Print the names of the input files as @command{ld} processes them.
|
|
|
|
@kindex -T @var{script}
|
|
@kindex --script=@var{script}
|
|
@cindex script files
|
|
@item -T @var{scriptfile}
|
|
@itemx --script=@var{scriptfile}
|
|
Use @var{scriptfile} as the linker script. This script replaces
|
|
@command{ld}'s default linker script (rather than adding to it), so
|
|
@var{commandfile} must specify everything necessary to describe the
|
|
output file. @xref{Scripts}. If @var{scriptfile} does not exist in
|
|
the current directory, @code{ld} looks for it in the directories
|
|
specified by any preceding @samp{-L} options. Multiple @samp{-T}
|
|
options accumulate.
|
|
|
|
@kindex -u @var{symbol}
|
|
@kindex --undefined=@var{symbol}
|
|
@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. 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 @command{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[=@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 --version
|
|
@cindex version
|
|
@item -v
|
|
@itemx --version
|
|
@itemx -V
|
|
Display the version number for @command{ld}. The @option{-V} option also
|
|
lists the supported emulations.
|
|
|
|
@kindex -x
|
|
@kindex --discard-all
|
|
@cindex deleting local symbols
|
|
@item -x
|
|
@itemx --discard-all
|
|
Delete all local symbols.
|
|
|
|
@kindex -X
|
|
@kindex --discard-locals
|
|
@cindex local symbols, deleting
|
|
@cindex L, deleting symbols beginning
|
|
@item -X
|
|
@itemx --discard-locals
|
|
Delete all temporary local symbols. For most targets, this is all local
|
|
symbols whose names begin with @samp{L}.
|
|
|
|
@kindex -y @var{symbol}
|
|
@kindex --trace-symbol=@var{symbol}
|
|
@cindex symbol tracing
|
|
@item -y @var{symbol}
|
|
@itemx --trace-symbol=@var{symbol}
|
|
Print the name of each linked file in which @var{symbol} appears. This
|
|
option may be given any number of times. On many systems it is necessary
|
|
to prepend an underscore.
|
|
|
|
This option is useful when you have an undefined symbol in your link but
|
|
don't know where the reference is coming from.
|
|
|
|
@kindex -Y @var{path}
|
|
@item -Y @var{path}
|
|
Add @var{path} to the default library search path. This option exists
|
|
for Solaris compatibility.
|
|
|
|
@kindex -z @var{keyword}
|
|
@item -z @var{keyword}
|
|
The recognized keywords are:
|
|
@table @samp
|
|
|
|
@item combreloc
|
|
Combines multiple reloc sections and sorts them to make dynamic symbol
|
|
lookup caching possible.
|
|
|
|
@item defs
|
|
Disallows undefined symbols in object files. Undefined symbols in
|
|
shared libraries are still allowed.
|
|
|
|
@item initfirst
|
|
This option is only meaningful when building a shared object.
|
|
It marks the object so that its runtime initialization will occur
|
|
before the runtime initialization of any other objects brought into
|
|
the process at the same time. Similarly the runtime finalization of
|
|
the object will occur after the runtime finalization of any other
|
|
objects.
|
|
|
|
@item interpose
|
|
Marks the object that its symbol table interposes before all symbols
|
|
but the primary executable.
|
|
|
|
@item loadfltr
|
|
Marks the object that its filters be processed immediately at
|
|
runtime.
|
|
|
|
@item muldefs
|
|
Allows multiple definitions.
|
|
|
|
@item nocombreloc
|
|
Disables multiple reloc sections combining.
|
|
|
|
@item nocopyreloc
|
|
Disables production of copy relocs.
|
|
|
|
@item nodefaultlib
|
|
Marks the object that the search for dependencies of this object will
|
|
ignore any default library search paths.
|
|
|
|
@item nodelete
|
|
Marks the object shouldn't be unloaded at runtime.
|
|
|
|
@item nodlopen
|
|
Marks the object not available to @code{dlopen}.
|
|
|
|
@item nodump
|
|
Marks the object can not be dumped by @code{dldump}.
|
|
|
|
@item now
|
|
When generating an executable or shared library, mark it to tell the
|
|
dynamic linker to resolve all symbols when the program is started, or
|
|
when the shared library is linked to using dlopen, instead of
|
|
deferring function call resolution to the point when the function is
|
|
first called.
|
|
|
|
@item origin
|
|
Marks the object may contain $ORIGIN.
|
|
|
|
@end table
|
|
|
|
Other keywords are ignored for Solaris compatibility.
|
|
|
|
@kindex -(
|
|
@cindex groups of archives
|
|
@item -( @var{archives} -)
|
|
@itemx --start-group @var{archives} --end-group
|
|
The @var{archives} should be a list of archive files. They may be
|
|
either explicit file names, or @samp{-l} options.
|
|
|
|
The specified archives are searched repeatedly until no new undefined
|
|
references are created. Normally, an archive is searched only once in
|
|
the order that it is specified on the command line. If a symbol in that
|
|
archive is needed to resolve an undefined symbol referred to by an
|
|
object in an archive that appears later on the command line, the linker
|
|
would not be able to resolve that reference. By grouping the archives,
|
|
they all be searched repeatedly until all possible references are
|
|
resolved.
|
|
|
|
Using this option has a significant performance cost. It is best to use
|
|
it only when there are unavoidable circular references between two or
|
|
more archives.
|
|
|
|
@kindex --accept-unknown-input-arch
|
|
@kindex --no-accept-unknown-input-arch
|
|
@item --accept-unknown-input-arch
|
|
@itemx --no-accept-unknown-input-arch
|
|
Tells the linker to accept input files whose architecture cannot be
|
|
recognised. The assumption is that the user knows what they are doing
|
|
and deliberately wants to link in these unknown input files. This was
|
|
the default behaviour of the linker, before release 2.14. The default
|
|
behaviour from release 2.14 onwards is to reject such input files, and
|
|
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 --add-needed
|
|
@kindex --no-add-needed
|
|
@item --add-needed
|
|
@itemx --no-add-needed
|
|
This option affects the treatment of dynamic libraries from ELF
|
|
DT_NEEDED tags in dynamic libraries mentioned on the command line after
|
|
the @option{--no-add-needed} option. Normally, the linker will add
|
|
a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
|
|
@option{--no-add-needed} causes DT_NEEDED tags will never be emitted
|
|
for those libraries from DT_NEEDED tags. @option{--add-needed} restores
|
|
the default behaviour.
|
|
|
|
@kindex -assert @var{keyword}
|
|
@item -assert @var{keyword}
|
|
This option is ignored for SunOS compatibility.
|
|
|
|
@kindex -Bdynamic
|
|
@kindex -dy
|
|
@kindex -call_shared
|
|
@item -Bdynamic
|
|
@itemx -dy
|
|
@itemx -call_shared
|
|
Link against dynamic libraries. This is only meaningful on platforms
|
|
for which shared libraries are supported. This option is normally the
|
|
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.
|
|
|
|
@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.
|
|
@option{--unresolved-symbols=report-all} 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
|
|
@itemx -dn
|
|
@itemx -non_shared
|
|
@itemx -static
|
|
Do not link against shared libraries. This is only meaningful on
|
|
platforms for which shared libraries are supported. 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=report-all}.
|
|
|
|
@kindex -Bsymbolic
|
|
@item -Bsymbolic
|
|
When creating a shared library, bind references to global symbols to the
|
|
definition within the shared library, if any. Normally, it is possible
|
|
for a program linked against a shared library to override the definition
|
|
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 @option{--check-sections}.
|
|
|
|
@cindex cross reference table
|
|
@kindex --cref
|
|
@item --cref
|
|
Output a cross reference table. If a linker map file is being
|
|
generated, the cross reference table is printed to the map file.
|
|
Otherwise, it is printed on the standard output.
|
|
|
|
The format of the table is intentionally simple, so that it may be
|
|
easily processed by a script if necessary. The symbols are printed out,
|
|
sorted by name. For each symbol, a list of file names is given. If the
|
|
symbol is defined, the first file listed is the location of the
|
|
definition. The remaining files contain references to the symbol.
|
|
|
|
@cindex common allocation
|
|
@kindex --no-define-common
|
|
@item --no-define-common
|
|
This option inhibits the assignment of addresses to common symbols.
|
|
The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
|
|
@xref{Miscellaneous Commands}.
|
|
|
|
The @samp{--no-define-common} option allows decoupling
|
|
the decision to assign addresses to Common symbols from the choice
|
|
of the output file type; otherwise a non-Relocatable output type
|
|
forces assigning addresses to Common symbols.
|
|
Using @samp{--no-define-common} allows Common symbols that are referenced
|
|
from a shared library to be assigned addresses only in the main program.
|
|
This eliminates the unused duplicate space in the shared library,
|
|
and also prevents any possible confusion over resolving to the wrong
|
|
duplicate when there are many dynamic modules with specialized search
|
|
paths for runtime symbol resolution.
|
|
|
|
@cindex symbols, from command line
|
|
@kindex --defsym @var{symbol}=@var{exp}
|
|
@item --defsym @var{symbol}=@var{expression}
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by @var{expression}. You may use this option as many
|
|
times as necessary to define multiple symbols in the command line. A
|
|
limited form of arithmetic is supported for the @var{expression} in this
|
|
context: you may give a hexadecimal constant or the name of an existing
|
|
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
|
|
constants or symbols. If you need more elaborate expressions, consider
|
|
using the linker command language from a script (@pxref{Assignments,,
|
|
Assignment: Symbol Definitions}). @emph{Note:} there should be no white
|
|
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 -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
|
|
generating dynamically linked ELF executables. The default dynamic
|
|
linker is normally correct; don't use this unless you know what you are
|
|
doing.
|
|
|
|
|
|
@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.
|
|
|
|
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}. 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
|
|
@item --help
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
|
|
@kindex --target-help
|
|
@item --target-help
|
|
Print a summary of all target specific options on the standard output and exit.
|
|
|
|
@kindex -Map
|
|
@item -Map @var{mapfile}
|
|
Print a link map to the file @var{mapfile}. See the description of the
|
|
@option{-M} option, above.
|
|
|
|
@cindex memory usage
|
|
@kindex --no-keep-memory
|
|
@item --no-keep-memory
|
|
@command{ld} normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells @command{ld} to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if @command{ld} runs out of memory space
|
|
while linking a large executable.
|
|
|
|
@kindex --no-undefined
|
|
@kindex -z defs
|
|
@item --no-undefined
|
|
@itemx -z defs
|
|
Report unresolved symbol references from regular object files. This
|
|
is done even if the linker is creating a non-symbolic shared library.
|
|
The switch @option{--[no-]allow-shlib-undefined} controls the
|
|
behaviour for reporting unresolved references found in shared
|
|
libraries being linked in.
|
|
|
|
@kindex --allow-multiple-definition
|
|
@kindex -z muldefs
|
|
@item --allow-multiple-definition
|
|
@itemx -z muldefs
|
|
Normally when a symbol is defined multiple times, the linker will
|
|
report a fatal error. These options allow multiple definitions and the
|
|
first definition will be used.
|
|
|
|
@kindex --allow-shlib-undefined
|
|
@kindex --no-allow-shlib-undefined
|
|
@item --allow-shlib-undefined
|
|
@itemx --no-allow-shlib-undefined
|
|
Allows (the default) or disallows undefined symbols in shared libraries.
|
|
This switch is similar to @option{--no-undefined} except that it
|
|
determines the behaviour when the undefined symbols are in a
|
|
shared library rather than a regular object file. It does not affect
|
|
how undefined symbols in regular object files are handled.
|
|
|
|
The reason that @option{--allow-shlib-undefined} is the default is that
|
|
the shared library being specified at link time may not be the same as
|
|
the one that is available at load time, so the symbols might actually be
|
|
resolvable at load time. Plus there are some systems, (eg BeOS) where
|
|
undefined symbols in shared libraries is normal. (The kernel patches
|
|
them at load time to select which function is most appropriate
|
|
for the current architecture. This is used for example to dynamically
|
|
select an appropriate memset function). Apparently it is also normal
|
|
for HPPA shared libraries to have undefined symbols.
|
|
|
|
@kindex --no-undefined-version
|
|
@item --no-undefined-version
|
|
Normally when a symbol has an undefined version, the linker will ignore
|
|
it. This option disallows symbols with undefined version and a fatal error
|
|
will be issued instead.
|
|
|
|
@kindex --default-symver
|
|
@item --default-symver
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
exported symbols.
|
|
|
|
@kindex --default-imported-symver
|
|
@item --default-imported-symver
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
imported symbols.
|
|
|
|
@kindex --no-warn-mismatch
|
|
@item --no-warn-mismatch
|
|
Normally @command{ld} will give an error if you try to link together input
|
|
files that are mismatched for some reason, perhaps because they have
|
|
been compiled for different processors or for different endiannesses.
|
|
This option tells @command{ld} that it should silently permit such possible
|
|
errors. This option should only be used with care, in cases when you
|
|
have taken some special action that ensures that the linker errors are
|
|
inappropriate.
|
|
|
|
@kindex --no-whole-archive
|
|
@item --no-whole-archive
|
|
Turn off the effect of the @option{--whole-archive} option for subsequent
|
|
archive files.
|
|
|
|
@cindex output file after errors
|
|
@kindex --noinhibit-exec
|
|
@item --noinhibit-exec
|
|
Retain the executable output file whenever it is still usable.
|
|
Normally, the linker will not produce an output file if it encounters
|
|
errors during the link process; it exits without writing an output file
|
|
when it issues any error whatsoever.
|
|
|
|
@kindex -nostdlib
|
|
@item -nostdlib
|
|
Only search library directories explicitly specified on the
|
|
command line. Library directories specified in linker scripts
|
|
(including linker scripts specified on the command line) are ignored.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex --oformat
|
|
@item --oformat @var{output-format}
|
|
@command{ld} may be configured to support more than one kind of object
|
|
file. If your @command{ld} is configured this way, you can use the
|
|
@samp{--oformat} option to specify the binary format for the output
|
|
object file. Even when @command{ld} is configured to support alternative
|
|
object formats, you don't usually need to specify this, as @command{ld}
|
|
should be configured to produce as a default output format the most
|
|
usual format on each machine. @var{output-format} is a text string, the
|
|
name of a particular format supported by the BFD libraries. (You can
|
|
list the available binary formats with @samp{objdump -i}.) The script
|
|
command @code{OUTPUT_FORMAT} can also specify the output format, but
|
|
this option overrides it. @xref{BFD}.
|
|
@end ifclear
|
|
|
|
@kindex -pie
|
|
@kindex --pic-executable
|
|
@item -pie
|
|
@itemx --pic-executable
|
|
@cindex position independent executables
|
|
Create a position independent executable. This is currently only supported on
|
|
ELF platforms. Position independent executables are similar to shared
|
|
libraries in that they are relocated by the dynamic linker to the virtual
|
|
address the OS chooses for them (which can vary between invocations). Like
|
|
normal dynamically linked executables they can be executed and symbols
|
|
defined in the executable cannot be overridden by shared libraries.
|
|
|
|
@kindex -qmagic
|
|
@item -qmagic
|
|
This option is ignored for Linux compatibility.
|
|
|
|
@kindex -Qy
|
|
@item -Qy
|
|
This option is ignored for SVR4 compatibility.
|
|
|
|
@kindex --relax
|
|
@cindex synthesizing linker
|
|
@cindex relaxing addressing modes
|
|
@item --relax
|
|
An option with machine dependent effects.
|
|
@ifset GENERIC
|
|
This option is only supported on a few targets.
|
|
@end ifset
|
|
@ifset H8300
|
|
@xref{H8/300,,@command{ld} and the H8/300}.
|
|
@end ifset
|
|
@ifset I960
|
|
@xref{i960,, @command{ld} and the Intel 960 family}.
|
|
@end ifset
|
|
@ifset XTENSA
|
|
@xref{Xtensa,, @command{ld} and Xtensa Processors}.
|
|
@end ifset
|
|
@ifset M68HC11
|
|
@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
|
|
@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.
|
|
@end ifset
|
|
|
|
@cindex retaining specified symbols
|
|
@cindex stripping all but some symbols
|
|
@cindex symbols, retaining selectively
|
|
@item --retain-symbols-file @var{filename}
|
|
Retain @emph{only} the symbols listed in the file @var{filename},
|
|
discarding all others. @var{filename} is simply a flat file, with one
|
|
symbol name per line. This option is especially useful in environments
|
|
@ifset GENERIC
|
|
(such as VxWorks)
|
|
@end ifset
|
|
where a large global symbol table is accumulated gradually, to conserve
|
|
run-time memory.
|
|
|
|
@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
|
|
or symbols needed for relocations.
|
|
|
|
You may only specify @samp{--retain-symbols-file} once in the command
|
|
line. It overrides @samp{-s} and @samp{-S}.
|
|
|
|
@ifset GENERIC
|
|
@item -rpath @var{dir}
|
|
@cindex runtime library search path
|
|
@kindex -rpath
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an ELF executable with shared objects. All @option{-rpath}
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The @option{-rpath} option is
|
|
also used when locating shared objects which are needed by shared
|
|
objects explicitly included in the link; see the description of the
|
|
@option{-rpath-link} option. If @option{-rpath} is not used when linking an
|
|
ELF executable, the contents of the environment variable
|
|
@code{LD_RUN_PATH} will be used if it is defined.
|
|
|
|
The @option{-rpath} option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search patch out of all the
|
|
@option{-L} options it is given. If a @option{-rpath} option is used, the
|
|
runtime search path will be formed exclusively using the @option{-rpath}
|
|
options, ignoring the @option{-L} options. This can be useful when using
|
|
gcc, which adds many @option{-L} options which may be on NFS mounted
|
|
filesystems.
|
|
|
|
For compatibility with other ELF linkers, if the @option{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @option{-rpath} option.
|
|
@end ifset
|
|
|
|
@ifset GENERIC
|
|
@cindex link-time runtime library search path
|
|
@kindex -rpath-link
|
|
@item -rpath-link @var{DIR}
|
|
When using ELF or SunOS, one shared library may require another. This
|
|
happens when an @code{ld -shared} link includes a shared library as one
|
|
of the input files.
|
|
|
|
When the linker encounters such a dependency when doing a non-shared,
|
|
non-relocatable link, it will automatically try to locate the required
|
|
shared library and include it in the link, if it is not included
|
|
explicitly. In such a case, the @option{-rpath-link} option
|
|
specifies the first set of directories to search. The
|
|
@option{-rpath-link} option may specify a sequence of directory names
|
|
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
|
|
@item
|
|
Any directories specified by @option{-rpath-link} options.
|
|
@item
|
|
Any directories specified by @option{-rpath} options. The difference
|
|
between @option{-rpath} and @option{-rpath-link} is that directories
|
|
specified by @option{-rpath} options are included in the executable and
|
|
used at runtime, whereas the @option{-rpath-link} option is only effective
|
|
at link time. It is for the native linker only.
|
|
@item
|
|
On an ELF system, if the @option{-rpath} and @code{rpath-link} options
|
|
were not used, search the contents of the environment variable
|
|
@code{LD_RUN_PATH}. It is for the native linker only.
|
|
@item
|
|
On SunOS, if the @option{-rpath} option was not used, search any
|
|
directories specified using @option{-L} options.
|
|
@item
|
|
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
|
|
warning and continue with the link.
|
|
@end ifset
|
|
|
|
@kindex -shared
|
|
@kindex -Bshareable
|
|
@item -shared
|
|
@itemx -Bshareable
|
|
@cindex shared libraries
|
|
Create a shared library. This is currently only supported on ELF, XCOFF
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
|
shared library if the @option{-e} option is not used and there are
|
|
undefined symbols in the link.
|
|
|
|
@item --sort-common
|
|
@kindex --sort-common
|
|
This option tells @command{ld} to sort the common symbols by size when it
|
|
places them in the appropriate output sections. First come all the one
|
|
byte symbols, then all the two byte, then all the four byte, and then
|
|
everything else. This is to prevent gaps between symbols due to
|
|
alignment constraints.
|
|
|
|
@kindex --sort-section name
|
|
@item --sort-section name
|
|
This option will apply @code{SORT_BY_NAME} to all wildcard section
|
|
patterns in the linker script.
|
|
|
|
@kindex --sort-section alignment
|
|
@item --sort-section alignment
|
|
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
|
|
patterns in the linker script.
|
|
|
|
@kindex --split-by-file
|
|
@item --split-by-file [@var{size}]
|
|
Similar to @option{--split-by-reloc} but creates a new output section for
|
|
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}]
|
|
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 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. @var{count} defaults to a value of 32768.
|
|
|
|
@kindex --stats
|
|
@item --stats
|
|
Compute and display statistics about the operation of the linker, such
|
|
as execution time and memory usage.
|
|
|
|
@kindex --traditional-format
|
|
@cindex traditional format
|
|
@item --traditional-format
|
|
For some targets, the output of @command{ld} is different in some ways from
|
|
the output of some existing linker. This switch requests @command{ld} to
|
|
use the traditional format instead.
|
|
|
|
@cindex dbx
|
|
For example, on SunOS, @command{ld} combines duplicate entries in the
|
|
symbol string table. This can reduce the size of an output file with
|
|
full debugging information by over 30 percent. Unfortunately, the SunOS
|
|
@code{dbx} program can not read the resulting program (@code{gdb} has no
|
|
trouble). The @samp{--traditional-format} switch tells @command{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}
|
|
@cindex segment origins, cmd line
|
|
@item -Tbss @var{org}
|
|
@itemx -Tdata @var{org}
|
|
@itemx -Ttext @var{org}
|
|
Same as --section-start, with @code{.bss}, @code{.data} or
|
|
@code{.text} as the @var{sectionname}.
|
|
|
|
@kindex --unresolved-symbols
|
|
@item --unresolved-symbols=@var{method}
|
|
Determine how to handle unresolved symbols. There are four possible
|
|
values for @samp{method}:
|
|
|
|
@table @samp
|
|
@item ignore-all
|
|
Do not report any unresolved symbols.
|
|
|
|
@item report-all
|
|
Report all unresolved symbols. This is the default.
|
|
|
|
@item ignore-in-object-files
|
|
Report unresolved symbols that are contained in shared libraries, but
|
|
ignore them if they come from regular object files.
|
|
|
|
@item ignore-in-shared-libs
|
|
Report unresolved symbols that come from regular object files, but
|
|
ignore them if they come from shared libraries. This can be useful
|
|
when creating a dynamic binary and it is known that all the shared
|
|
libraries that it should be referencing are included on the linker's
|
|
command line.
|
|
@end table
|
|
|
|
The behaviour for shared libraries on their own can also be controlled
|
|
by the @option{--[no-]allow-shlib-undefined} option.
|
|
|
|
Normally the linker will generate an error message for each reported
|
|
unresolved symbol but the option @option{--warn-unresolved-symbols}
|
|
can change this to a warning.
|
|
|
|
@kindex --verbose
|
|
@cindex verbose
|
|
@item --dll-verbose
|
|
@itemx --verbose
|
|
Display the version number for @command{ld} and list the linker emulations
|
|
supported. Display which input files can and cannot be opened. Display
|
|
the linker script being used by the linker.
|
|
|
|
@kindex --version-script=@var{version-scriptfile}
|
|
@cindex version script, symbol versions
|
|
@itemx --version-script=@var{version-scriptfile}
|
|
Specify the name of a version script to the linker. This is typically
|
|
used when creating shared libraries to specify additional information
|
|
about the version hierarchy for the library being created. This option
|
|
is only meaningful on ELF platforms which support shared libraries.
|
|
@xref{VERSION}.
|
|
|
|
@kindex --warn-common
|
|
@cindex warnings, on combining symbols
|
|
@cindex combining symbols, warnings on
|
|
@item --warn-common
|
|
Warn when a common symbol is combined with another common symbol or with
|
|
a symbol definition. Unix linkers allow this somewhat sloppy practise,
|
|
but linkers on some other operating systems do not. This option allows
|
|
you to find potential problems from combining global symbols.
|
|
Unfortunately, some C libraries use this practise, so you may get some
|
|
warnings about symbols in the libraries as well as in your programs.
|
|
|
|
There are three kinds of global symbols, illustrated here by C examples:
|
|
|
|
@table @samp
|
|
@item int i = 1;
|
|
A definition, which goes in the initialized data section of the output
|
|
file.
|
|
|
|
@item extern int i;
|
|
An undefined reference, which does not allocate space.
|
|
There must be either a definition or a common symbol for the
|
|
variable somewhere.
|
|
|
|
@item int i;
|
|
A common symbol. If there are only (one or more) common symbols for a
|
|
variable, it goes in the uninitialized data area of the output file.
|
|
The linker merges multiple common symbols for the same variable into a
|
|
single symbol. If they are of different sizes, it picks the largest
|
|
size. The linker turns a common symbol into a declaration, if there is
|
|
a definition of the same variable.
|
|
@end table
|
|
|
|
The @samp{--warn-common} option can produce five kinds of warnings.
|
|
Each warning consists of a pair of lines: the first describes the symbol
|
|
just encountered, and the second describes the previous symbol
|
|
encountered with the same name. One or both of the two symbols will be
|
|
a common symbol.
|
|
|
|
@enumerate
|
|
@item
|
|
Turning a common symbol into a reference, because there is already a
|
|
definition for the symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overridden by definition
|
|
@var{file}(@var{section}): warning: defined here
|
|
@end smallexample
|
|
|
|
@item
|
|
Turning a common symbol into a reference, because a later definition for
|
|
the symbol is encountered. This is the same as the previous case,
|
|
except that the symbols are encountered in a different order.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: definition of `@var{symbol}'
|
|
overriding common
|
|
@var{file}(@var{section}): warning: common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous same-sized common symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: multiple common
|
|
of `@var{symbol}'
|
|
@var{file}(@var{section}): warning: previous common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous larger common symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overridden by larger common
|
|
@var{file}(@var{section}): warning: larger common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous smaller common symbol. This is
|
|
the same as the previous case, except that the symbols are
|
|
encountered in a different order.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overriding smaller common
|
|
@var{file}(@var{section}): warning: smaller common is here
|
|
@end smallexample
|
|
@end enumerate
|
|
|
|
@kindex --warn-constructors
|
|
@item --warn-constructors
|
|
Warn if any global constructors are used. This is only useful for a few
|
|
object file formats. For formats like COFF or ELF, the linker can not
|
|
detect the use of global constructors.
|
|
|
|
@kindex --warn-multiple-gp
|
|
@item --warn-multiple-gp
|
|
Warn if multiple global pointer values are required in the output file.
|
|
This is only meaningful for certain processors, such as the Alpha.
|
|
Specifically, some processors put large-valued constants in a special
|
|
section. A special register (the global pointer) points into the middle
|
|
of this section, so that constants can be loaded efficiently via a
|
|
base-register relative addressing mode. Since the offset in
|
|
base-register relative mode is fixed and relatively small (e.g., 16
|
|
bits), this limits the maximum size of the constant pool. Thus, in
|
|
large programs, it is often necessary to use multiple global pointer
|
|
values in order to be able to address all possible constants. This
|
|
option causes a warning to be issued whenever this case occurs.
|
|
|
|
@kindex --warn-once
|
|
@cindex warnings, on undefined symbols
|
|
@cindex undefined symbols, warnings on
|
|
@item --warn-once
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
|
|
@kindex --warn-section-align
|
|
@cindex warnings, on section alignment
|
|
@cindex section alignment, warnings on
|
|
@item --warn-section-align
|
|
Warn if the address of an output section is changed because of
|
|
alignment. Typically, the alignment will be set by an input section.
|
|
The address will only be changed if it not explicitly specified; that
|
|
is, if the @code{SECTIONS} command does not specify a start address for
|
|
the section (@pxref{SECTIONS}).
|
|
|
|
@kindex --warn-shared-textrel
|
|
@item --warn-shared-textrel
|
|
Warn if the linker adds a DT_TEXTREL to a shared object.
|
|
|
|
@kindex --warn-unresolved-symbols
|
|
@item --warn-unresolved-symbols
|
|
If the linker is going to report an unresolved symbol (see the option
|
|
@option{--unresolved-symbols}) it will normally generate an error.
|
|
This option makes it generate a warning instead.
|
|
|
|
@kindex --error-unresolved-symbols
|
|
@item --error-unresolved-symbols
|
|
This restores the linker's default behaviour of generating errors when
|
|
it is reporting unresolved symbols.
|
|
|
|
@kindex --whole-archive
|
|
@cindex including an entire archive
|
|
@item --whole-archive
|
|
For each archive mentioned on the command line after the
|
|
@option{--whole-archive} option, include every object file in the archive
|
|
in the link, rather than searching the archive for the required object
|
|
files. This is normally used to turn an archive file into a shared
|
|
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 @option{-Wl,-whole-archive}.
|
|
Second, don't forget to use @option{-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
|
|
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
|
|
undefined reference to @code{__real_@var{symbol}} will be resolved to
|
|
@var{symbol}.
|
|
|
|
This can be used to provide a wrapper for a system function. The
|
|
wrapper function should be called @code{__wrap_@var{symbol}}. If it
|
|
wishes to call the system function, it should call
|
|
@code{__real_@var{symbol}}.
|
|
|
|
Here is a trivial example:
|
|
|
|
@smallexample
|
|
void *
|
|
__wrap_malloc (size_t c)
|
|
@{
|
|
printf ("malloc called with %zu\n", c);
|
|
return __real_malloc (c);
|
|
@}
|
|
@end smallexample
|
|
|
|
If you link other code with this file using @option{--wrap malloc}, then
|
|
all calls to @code{malloc} will call the function @code{__wrap_malloc}
|
|
instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
|
|
call the real @code{malloc} function.
|
|
|
|
You may wish to provide a @code{__real_malloc} function as well, so that
|
|
links without the @option{--wrap} option will succeed. If you do this,
|
|
you should not put the definition of @code{__real_malloc} in the same
|
|
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
|
|
@option{--enable-new-dtags}, the dynamic tags will be created as needed.
|
|
If you specify @option{--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.
|
|
|
|
@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
|
|
|
|
@subsection Options Specific to i386 PE Targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The i386 PE linker supports the @option{-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 @gcctabopt
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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}.
|
|
[This is an i386 PE specific option]
|
|
|
|
@kindex --dll
|
|
@item --dll
|
|
Create a DLL instead of a regular executable. You may also use
|
|
@option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
|
|
file.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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 @option{--enable-stdcall-fixup}, this
|
|
feature is fully enabled and warnings are not printed. If you specify
|
|
@option{--disable-stdcall-fixup}, this feature is disabled and such
|
|
mismatches are considered to be errors.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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}, @code{DllMainCRTStartup@@12}, and
|
|
@code{impure_ptr} will not be automatically
|
|
exported. Also, symbols imported from other DLLs will not be
|
|
re-exported, nor will symbols specifying the DLL's internal layout
|
|
such as those beginning with @code{_head_} or ending with
|
|
@code{_iname}. In addition, no symbols from @code{libgcc},
|
|
@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
|
|
Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
|
|
not be exported, to help with C++ DLLs. Finally, there is an
|
|
extensive list of cygwin-private symbols that are not exported
|
|
(obviously, this applies on when building DLLs for cygwin targets).
|
|
These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
|
|
@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
|
|
@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
|
|
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
|
|
@code{cygwin_premain3}, and @code{environ}.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --kill-at
|
|
@item --kill-at
|
|
If given, the stdcall suffixes (@@@var{nn}) will be stripped from
|
|
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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --major-os-version
|
|
@item --major-os-version @var{value}
|
|
Sets the major number of the ``os version''. Defaults to 4.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --major-subsystem-version
|
|
@item --major-subsystem-version @var{value}
|
|
Sets the major number of the ``subsystem version''. Defaults to 4.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --minor-image-version
|
|
@item --minor-image-version @var{value}
|
|
Sets the minor number of the ``image version''. Defaults to 0.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --minor-os-version
|
|
@item --minor-os-version @var{value}
|
|
Sets the minor number of the ``os version''. Defaults to 0.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --minor-subsystem-version
|
|
@item --minor-subsystem-version @var{value}
|
|
Sets the minor number of the ``subsystem version''. Defaults to 0.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex DLLs, creating
|
|
@kindex --out-implib
|
|
@item --out-implib @var{file}
|
|
The linker will create the file @var{file} which will contain an
|
|
import lib corresponding to the DLL the linker is generating. This
|
|
import lib (which should be called @code{*.dll.a} or @code{*.a}
|
|
may be used to link clients against the generated DLL; this behaviour
|
|
makes it possible to skip a separate @code{dlltool} import library
|
|
creation step.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-auto-image-base
|
|
@item --enable-auto-image-base
|
|
Automatically choose the image base for DLLs, unless one is specified
|
|
using the @code{--image-base} argument. By using a hash generated
|
|
from the dllname to create unique image bases for each DLL, in-memory
|
|
collisions and relocations which can delay program execution are
|
|
avoided.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --disable-auto-image-base
|
|
@item --disable-auto-image-base
|
|
Do not automatically generate a unique image base. If there is no
|
|
user-specified image base (@code{--image-base}) then use the platform
|
|
default.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@cindex DLLs, linking to
|
|
@kindex --dll-search-prefix
|
|
@item --dll-search-prefix @var{string}
|
|
When linking dynamically to a dll without an import library,
|
|
search for @code{<string><basename>.dll} in preference to
|
|
@code{lib<basename>.dll}. This behaviour allows easy distinction
|
|
between DLLs built for the various "subplatforms": native, cygwin,
|
|
uwin, pw, etc. For instance, cygwin DLLs typically use
|
|
@code{--dll-search-prefix=cyg}.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-auto-import
|
|
@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. 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."
|
|
|
|
This message occurs when some (sub)expression accesses an address
|
|
ultimately given by the sum of two constants (Win32 import tables only
|
|
allow one). Instances where this may occur include accesses to member
|
|
fields of struct variables imported from a DLL, as well as using a
|
|
constant index into an array variable imported from a DLL. Any
|
|
multiword variable (arrays, structs, long long, etc) may trigger
|
|
this error condition. However, regardless of the exact data type
|
|
of the offending exported variable, ld will always detect it, issue
|
|
the warning, and exit.
|
|
|
|
There are several ways to address this difficulty, regardless of the
|
|
data type of the exported variable:
|
|
|
|
One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
|
|
of adjusting references in your client code for runtime environment, so
|
|
this method works only when runtime environment supports this feature.
|
|
|
|
A second solution is to force one of the 'constants' to be a variable --
|
|
that is, unknown and un-optimizable at compile time. For arrays,
|
|
there are two possibilities: a) make the indexee (the array's address)
|
|
a variable, or b) make the 'constant' index a variable. Thus:
|
|
|
|
@example
|
|
extern type extern_array[];
|
|
extern_array[1] -->
|
|
@{ volatile type *t=extern_array; t[1] @}
|
|
@end example
|
|
|
|
or
|
|
|
|
@example
|
|
extern type extern_array[];
|
|
extern_array[1] -->
|
|
@{ volatile int t=1; extern_array[t] @}
|
|
@end example
|
|
|
|
For structs (and most other multiword data types) the only option
|
|
is to make the struct itself (or the long long, or the ...) variable:
|
|
|
|
@example
|
|
extern struct s extern_struct;
|
|
extern_struct.field -->
|
|
@{ volatile struct s *t=&extern_struct; t->field @}
|
|
@end example
|
|
|
|
or
|
|
|
|
@example
|
|
extern long long extern_ll;
|
|
extern_ll -->
|
|
@{ volatile long long * local_ll=&extern_ll; *local_ll @}
|
|
@end example
|
|
|
|
A third method of dealing with this difficulty is to abandon
|
|
'auto-import' for the offending symbol and mark it with
|
|
@code{__declspec(dllimport)}. However, in practise that
|
|
requires using compile-time #defines to indicate whether you are
|
|
building a DLL, building client code that will link to the DLL, or
|
|
merely building/linking to a static library. In making the choice
|
|
between the various methods of resolving the 'direct address with
|
|
constant offset' problem, you should consider typical real-world usage:
|
|
|
|
Original:
|
|
@example
|
|
--foo.h
|
|
extern int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv)@{
|
|
printf("%d\n",arr[1]);
|
|
@}
|
|
@end example
|
|
|
|
Solution 1:
|
|
@example
|
|
--foo.h
|
|
extern int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv)@{
|
|
/* This workaround is for win32 and cygwin; do not "optimize" */
|
|
volatile int *parr = arr;
|
|
printf("%d\n",parr[1]);
|
|
@}
|
|
@end example
|
|
|
|
Solution 2:
|
|
@example
|
|
--foo.h
|
|
/* Note: auto-export is assumed (no __declspec(dllexport)) */
|
|
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
|
|
!(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
|
|
#define FOO_IMPORT __declspec(dllimport)
|
|
#else
|
|
#define FOO_IMPORT
|
|
#endif
|
|
extern FOO_IMPORT int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv)@{
|
|
printf("%d\n",arr[1]);
|
|
@}
|
|
@end example
|
|
|
|
A fourth way to avoid this problem is to re-code your
|
|
library to use a functional interface rather than a data interface
|
|
for the offending variables (e.g. set_foo() and get_foo() accessor
|
|
functions).
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --disable-auto-import
|
|
@item --disable-auto-import
|
|
Do not attempt to do sophisticated linking of @code{_symbol} to
|
|
@code{__imp__symbol} for DATA imports from DLLs.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-runtime-pseudo-reloc
|
|
@item --enable-runtime-pseudo-reloc
|
|
If your code contains expressions described in --enable-auto-import section,
|
|
that is, DATA imports from DLL with non-zero offset, this switch will create
|
|
a vector of 'runtime pseudo relocations' which can be used by runtime
|
|
environment to adjust references to such data in your client code.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --disable-runtime-pseudo-reloc
|
|
@item --disable-runtime-pseudo-reloc
|
|
Do not create pseudo relocations for non-zero offset DATA imports from
|
|
DLLs. This is the default.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@kindex --enable-extra-pe-debug
|
|
@item --enable-extra-pe-debug
|
|
Show additional debug info related to auto-import symbol thunking.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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 2Mb reserved, 4K
|
|
committed.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@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}, @code{posix}, and @code{xbox}. You may optionally set
|
|
the subsystem version also. Numeric values are also accepted for
|
|
@var{which}.
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
|
|
@ifset M68HC11
|
|
@subsection Options specific to Motorola 68HC11 and 68HC12 targets
|
|
|
|
@c man begin OPTIONS
|
|
|
|
The 68HC11 and 68HC12 linkers support specific options to control the
|
|
memory bank switching mapping and trampoline code generation.
|
|
|
|
@table @gcctabopt
|
|
|
|
@kindex --no-trampoline
|
|
@item --no-trampoline
|
|
This option disables the generation of trampoline. By default a trampoline
|
|
is generated for each far function which is called using a @code{jsr}
|
|
instruction (this happens when a pointer to a far function is taken).
|
|
|
|
@kindex --bank-window
|
|
@item --bank-window @var{name}
|
|
This option indicates to the linker the name of the memory region in
|
|
the @samp{MEMORY} specification that describes the memory bank window.
|
|
The definition of such region is then used by the linker to compute
|
|
paging and addresses within the memory window.
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@ifset UsesEnvVars
|
|
@node Environment
|
|
@section Environment Variables
|
|
|
|
@c man begin ENVIRONMENT
|
|
|
|
You can change the behaviour of @command{ld} with the environment variables
|
|
@ifclear SingleFormat
|
|
@code{GNUTARGET},
|
|
@end ifclear
|
|
@code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex GNUTARGET
|
|
@cindex default input format
|
|
@code{GNUTARGET} determines the input-file object format if you don't
|
|
use @samp{-b} (or its synonym @samp{--format}). Its value should be one
|
|
of the BFD names for an input format (@pxref{BFD}). If there is no
|
|
@code{GNUTARGET} in the environment, @command{ld} uses the natural format
|
|
of the target. If @code{GNUTARGET} is set to @code{default} then BFD
|
|
attempts to discover the input format by examining binary input files;
|
|
this method often succeeds, but there are potential ambiguities, since
|
|
there is no method of ensuring that the magic number used to specify
|
|
object-file formats is unique. However, the configuration procedure for
|
|
BFD on each system places the conventional format for that system first
|
|
in the search-list, so ambiguities are resolved in favor of convention.
|
|
@end ifclear
|
|
|
|
@kindex LDEMULATION
|
|
@cindex default emulation
|
|
@cindex emulation, default
|
|
@code{LDEMULATION} determines the default emulation if you don't use the
|
|
@samp{-m} option. The emulation can affect various aspects of linker
|
|
behaviour, particularly the default linker script. You can list the
|
|
available emulations with the @samp{--verbose} or @samp{-V} options. If
|
|
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.
|
|
|
|
@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.
|
|
|
|
@c man end
|
|
@end ifset
|
|
|
|
@node Scripts
|
|
@chapter Linker Scripts
|
|
|
|
@cindex scripts
|
|
@cindex linker scripts
|
|
@cindex command files
|
|
Every link is controlled by a @dfn{linker script}. This script is
|
|
written in the linker command language.
|
|
|
|
The main purpose of the linker script is to describe how the sections in
|
|
the input files should be mapped into the output file, and to control
|
|
the memory layout of the output file. Most linker scripts do nothing
|
|
more than this. However, when necessary, the linker script can also
|
|
direct the linker to perform many other operations, using the commands
|
|
described below.
|
|
|
|
The linker always uses a linker script. If you do not supply one
|
|
yourself, the linker will use a default script that is compiled into the
|
|
linker executable. You can use the @samp{--verbose} command line option
|
|
to display the default linker script. Certain command line options,
|
|
such as @samp{-r} or @samp{-N}, will affect the default linker script.
|
|
|
|
You may supply your own linker script by using the @samp{-T} command
|
|
line option. When you do this, your linker script will replace the
|
|
default linker script.
|
|
|
|
You may also use linker scripts implicitly by naming them as input files
|
|
to the linker, as though they were files to be linked. @xref{Implicit
|
|
Linker Scripts}.
|
|
|
|
@menu
|
|
* Basic Script Concepts:: Basic Linker Script Concepts
|
|
* Script Format:: Linker Script Format
|
|
* Simple Example:: Simple Linker Script Example
|
|
* Simple Commands:: Simple Linker Script Commands
|
|
* Assignments:: Assigning Values to Symbols
|
|
* SECTIONS:: SECTIONS Command
|
|
* MEMORY:: MEMORY Command
|
|
* PHDRS:: PHDRS Command
|
|
* VERSION:: VERSION Command
|
|
* Expressions:: Expressions in Linker Scripts
|
|
* Implicit Linker Scripts:: Implicit Linker Scripts
|
|
@end menu
|
|
|
|
@node Basic Script Concepts
|
|
@section Basic Linker Script Concepts
|
|
@cindex linker script concepts
|
|
We need to define some basic concepts and vocabulary in order to
|
|
describe the linker script language.
|
|
|
|
The linker combines input files into a single output file. The output
|
|
file and each input file are in a special data format known as an
|
|
@dfn{object file format}. Each file is called an @dfn{object file}.
|
|
The output file is often called an @dfn{executable}, but for our
|
|
purposes we will also call it an object file. Each object file has,
|
|
among other things, a list of @dfn{sections}. We sometimes refer to a
|
|
section in an input file as an @dfn{input section}; similarly, a section
|
|
in the output file is an @dfn{output section}.
|
|
|
|
Each section in an object file has a name and a size. Most sections
|
|
also have an associated block of data, known as the @dfn{section
|
|
contents}. A section may be marked as @dfn{loadable}, which mean that
|
|
the contents should be loaded into memory when the output file is run.
|
|
A section with no contents may be @dfn{allocatable}, which means that an
|
|
area in memory should be set aside, but nothing in particular should be
|
|
loaded there (in some cases this memory must be zeroed out). A section
|
|
which is neither loadable nor allocatable typically contains some sort
|
|
of debugging information.
|
|
|
|
Every loadable or allocatable output section has two addresses. The
|
|
first is the @dfn{VMA}, or virtual memory address. This is the address
|
|
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
|
|
is loaded into ROM, and then copied into RAM when the program starts up
|
|
(this technique is often used to initialize global variables in a ROM
|
|
based system). In this case the ROM address would be the LMA, and the
|
|
RAM address would be the VMA.
|
|
|
|
You can see the sections in an object file by using the @code{objdump}
|
|
program with the @samp{-h} option.
|
|
|
|
Every object file also has a list of @dfn{symbols}, known as the
|
|
@dfn{symbol table}. A symbol may be defined or undefined. Each symbol
|
|
has a name, and each defined symbol has an address, among other
|
|
information. If you compile a C or C++ program into an object file, you
|
|
will get a defined symbol for every defined function and global or
|
|
static variable. Every undefined function or global variable which is
|
|
referenced in the input file will become an undefined symbol.
|
|
|
|
You can see the symbols in an object file by using the @code{nm}
|
|
program, or by using the @code{objdump} program with the @samp{-t}
|
|
option.
|
|
|
|
@node Script Format
|
|
@section Linker Script Format
|
|
@cindex linker script format
|
|
Linker scripts are text files.
|
|
|
|
You write a linker script as a series of commands. Each command is
|
|
either a keyword, possibly followed by arguments, or an assignment to a
|
|
symbol. You may separate commands using semicolons. Whitespace is
|
|
generally ignored.
|
|
|
|
Strings such as file or format names can normally be entered directly.
|
|
If the file name contains a character such as a comma which would
|
|
otherwise serve to separate file names, you may put the file name in
|
|
double quotes. There is no way to use a double quote character in a
|
|
file name.
|
|
|
|
You may include comments in linker scripts just as in C, delimited by
|
|
@samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
|
|
to whitespace.
|
|
|
|
@node Simple Example
|
|
@section Simple Linker Script Example
|
|
@cindex linker script example
|
|
@cindex example of linker script
|
|
Many linker scripts are fairly simple.
|
|
|
|
The simplest possible linker script has just one command:
|
|
@samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
|
|
memory layout of the output file.
|
|
|
|
The @samp{SECTIONS} command is a powerful command. Here we will
|
|
describe a simple use of it. Let's assume your program consists only of
|
|
code, initialized data, and uninitialized data. These will be in the
|
|
@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
|
|
Let's assume further that these are the only sections which appear in
|
|
your input files.
|
|
|
|
For this example, let's say that the code should be loaded at address
|
|
0x10000, and that the data should start at address 0x8000000. Here is a
|
|
linker script which will do that:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
. = 0x10000;
|
|
.text : @{ *(.text) @}
|
|
. = 0x8000000;
|
|
.data : @{ *(.data) @}
|
|
.bss : @{ *(.bss) @}
|
|
@}
|
|
@end smallexample
|
|
|
|
You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
|
|
followed by a series of symbol assignments and output section
|
|
descriptions enclosed in curly braces.
|
|
|
|
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
|
|
after the output section name, you list the names of the input sections
|
|
which should be placed into this output section. The @samp{*} is a
|
|
wildcard which matches any file name. The expression @samp{*(.text)}
|
|
means all @samp{.text} input sections in all input files.
|
|
|
|
Since the location counter is @samp{0x10000} when the output section
|
|
@samp{.text} is defined, the linker will set the address of the
|
|
@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 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.
|
|
|
|
@node Simple Commands
|
|
@section Simple Linker Script Commands
|
|
@cindex linker script simple commands
|
|
In this section we describe the simple linker script commands.
|
|
|
|
@menu
|
|
* Entry Point:: Setting the entry point
|
|
* File Commands:: Commands dealing with files
|
|
@ifclear SingleFormat
|
|
* Format Commands:: Commands dealing with object file formats
|
|
@end ifclear
|
|
|
|
* Miscellaneous Commands:: Other linker script commands
|
|
@end menu
|
|
|
|
@node Entry Point
|
|
@subsection Setting the Entry Point
|
|
@kindex ENTRY(@var{symbol})
|
|
@cindex start of execution
|
|
@cindex first instruction
|
|
@cindex entry point
|
|
The first instruction to execute in a program is called the @dfn{entry
|
|
point}. You can use the @code{ENTRY} linker script command to set the
|
|
entry point. The argument is a symbol name:
|
|
@smallexample
|
|
ENTRY(@var{symbol})
|
|
@end smallexample
|
|
|
|
There are several ways to set the entry point. The linker will set the
|
|
entry point by trying each of the following methods in order, and
|
|
stopping when one of them succeeds:
|
|
@itemize @bullet
|
|
@item
|
|
the @samp{-e} @var{entry} command-line option;
|
|
@item
|
|
the @code{ENTRY(@var{symbol})} command in a linker script;
|
|
@item
|
|
the value of the symbol @code{start}, if defined;
|
|
@item
|
|
the address of the first byte of the @samp{.text} section, if present;
|
|
@item
|
|
The address @code{0}.
|
|
@end itemize
|
|
|
|
@node File Commands
|
|
@subsection Commands Dealing with Files
|
|
@cindex linker script file commands
|
|
Several linker script commands deal with files.
|
|
|
|
@table @code
|
|
@item INCLUDE @var{filename}
|
|
@kindex INCLUDE @var{filename}
|
|
@cindex including a linker script
|
|
Include the linker script @var{filename} at this point. The file will
|
|
be searched for in the current directory, and in any directory specified
|
|
with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
|
|
10 levels deep.
|
|
|
|
@item INPUT(@var{file}, @var{file}, @dots{})
|
|
@itemx INPUT(@var{file} @var{file} @dots{})
|
|
@kindex INPUT(@var{files})
|
|
@cindex input files in linker scripts
|
|
@cindex input object files in linker scripts
|
|
@cindex linker script input object files
|
|
The @code{INPUT} command directs the linker to include the named files
|
|
in the link, as though they were named on the command line.
|
|
|
|
For example, if you always want to include @file{subr.o} any time you do
|
|
a link, but you can't be bothered to put it on every link command line,
|
|
then you can put @samp{INPUT (subr.o)} in your linker script.
|
|
|
|
In fact, if you like, you can list all of your input files in the linker
|
|
script, and then invoke the linker with nothing but a @samp{-T} option.
|
|
|
|
In case a @dfn{sysroot prefix} is configured, and the filename starts
|
|
with the @samp{/} character, and the script being processed was
|
|
located inside the @dfn{sysroot prefix}, the filename will be looked
|
|
for in the @dfn{sysroot prefix}. Otherwise, the linker will try to
|
|
open the file in the current directory. If it is not found, the
|
|
linker will search through the archive library search path. See the
|
|
description of @samp{-L} in @ref{Options,,Command Line Options}.
|
|
|
|
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
|
|
name to @code{lib@var{file}.a}, as with the command line argument
|
|
@samp{-l}.
|
|
|
|
When you use the @code{INPUT} command in an implicit linker script, the
|
|
files will be included in the link at the point at which the linker
|
|
script file is included. This can affect archive searching.
|
|
|
|
@item GROUP(@var{file}, @var{file}, @dots{})
|
|
@itemx GROUP(@var{file} @var{file} @dots{})
|
|
@kindex GROUP(@var{files})
|
|
@cindex grouping input files
|
|
The @code{GROUP} command is like @code{INPUT}, except that the named
|
|
files should all be archives, and they are searched repeatedly until no
|
|
new undefined references are created. See the description of @samp{-(}
|
|
in @ref{Options,,Command Line Options}.
|
|
|
|
@item OUTPUT(@var{filename})
|
|
@kindex OUTPUT(@var{filename})
|
|
@cindex output file name in linker scripot
|
|
The @code{OUTPUT} command names the output file. Using
|
|
@code{OUTPUT(@var{filename})} in the linker script is exactly like using
|
|
@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
|
|
Line Options}). If both are used, the command line option takes
|
|
precedence.
|
|
|
|
You can use the @code{OUTPUT} command to define a default name for the
|
|
output file other than the usual default of @file{a.out}.
|
|
|
|
@item SEARCH_DIR(@var{path})
|
|
@kindex SEARCH_DIR(@var{path})
|
|
@cindex library search path in linker script
|
|
@cindex archive search path in linker script
|
|
@cindex search path in linker script
|
|
The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
|
|
@command{ld} looks for archive libraries. Using
|
|
@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
|
|
on the command line (@pxref{Options,,Command Line Options}). If both
|
|
are used, then the linker will search both paths. Paths specified using
|
|
the command line option are searched first.
|
|
|
|
@item STARTUP(@var{filename})
|
|
@kindex STARTUP(@var{filename})
|
|
@cindex first input file
|
|
The @code{STARTUP} command is just like the @code{INPUT} command, except
|
|
that @var{filename} will become the first input file to be linked, as
|
|
though it were specified first on the command line. This may be useful
|
|
when using a system in which the entry point is always the start of the
|
|
first file.
|
|
@end table
|
|
|
|
@ifclear SingleFormat
|
|
@node Format Commands
|
|
@subsection Commands Dealing with Object File Formats
|
|
A couple of linker script commands deal with object file formats.
|
|
|
|
@table @code
|
|
@item OUTPUT_FORMAT(@var{bfdname})
|
|
@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
|
|
@kindex OUTPUT_FORMAT(@var{bfdname})
|
|
@cindex output file format in linker script
|
|
The @code{OUTPUT_FORMAT} command names the BFD format to use for the
|
|
output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
|
|
exactly like using @samp{--oformat @var{bfdname}} on the command line
|
|
(@pxref{Options,,Command Line Options}). If both are used, the command
|
|
line option takes precedence.
|
|
|
|
You can use @code{OUTPUT_FORMAT} with three arguments to use different
|
|
formats based on the @samp{-EB} and @samp{-EL} command line options.
|
|
This permits the linker script to set the output format based on the
|
|
desired endianness.
|
|
|
|
If neither @samp{-EB} nor @samp{-EL} are used, then the output format
|
|
will be the first argument, @var{default}. If @samp{-EB} is used, the
|
|
output format will be the second argument, @var{big}. If @samp{-EL} is
|
|
used, the output format will be the third argument, @var{little}.
|
|
|
|
For example, the default linker script for the MIPS ELF target uses this
|
|
command:
|
|
@smallexample
|
|
OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
|
|
@end smallexample
|
|
This says that the default format for the output file is
|
|
@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line
|
|
option, the output file will be created in the @samp{elf32-littlemips}
|
|
format.
|
|
|
|
@item TARGET(@var{bfdname})
|
|
@kindex TARGET(@var{bfdname})
|
|
@cindex input file format in linker script
|
|
The @code{TARGET} command names the BFD format to use when reading input
|
|
files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
|
|
This command is like using @samp{-b @var{bfdname}} on the command line
|
|
(@pxref{Options,,Command Line Options}). If the @code{TARGET} command
|
|
is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
|
|
command is also used to set the format for the output file. @xref{BFD}.
|
|
@end table
|
|
@end ifclear
|
|
|
|
@node Miscellaneous Commands
|
|
@subsection Other Linker Script Commands
|
|
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
|
|
This command has the same effect as the @samp{-d} command-line option:
|
|
to make @command{ld} assign space to common symbols even if a relocatable
|
|
output file is specified (@samp{-r}).
|
|
|
|
@item INHIBIT_COMMON_ALLOCATION
|
|
@kindex INHIBIT_COMMON_ALLOCATION
|
|
@cindex common allocation in linker script
|
|
This command has the same effect as the @samp{--no-define-common}
|
|
command-line option: to make @code{ld} omit the assignment of addresses
|
|
to common symbols even for a non-relocatable output file.
|
|
|
|
@item NOCROSSREFS(@var{section} @var{section} @dots{})
|
|
@kindex NOCROSSREFS(@var{sections})
|
|
@cindex cross references
|
|
This command may be used to tell @command{ld} to issue an error about any
|
|
references among certain output sections.
|
|
|
|
In certain types of programs, particularly on embedded systems when
|
|
using overlays, when one section is loaded into memory, another section
|
|
will not be. Any direct references between the two sections would be
|
|
errors. For example, it would be an error if code in one section called
|
|
a function defined in the other section.
|
|
|
|
The @code{NOCROSSREFS} command takes a list of output section names. If
|
|
@command{ld} detects any cross references between the sections, it reports
|
|
an error and returns a non-zero exit status. Note that the
|
|
@code{NOCROSSREFS} command uses output section names, not input section
|
|
names.
|
|
|
|
@ifclear SingleFormat
|
|
@item OUTPUT_ARCH(@var{bfdarch})
|
|
@kindex OUTPUT_ARCH(@var{bfdarch})
|
|
@cindex machine architecture
|
|
@cindex architecture
|
|
Specify a particular output machine architecture. The argument is one
|
|
of the names used by the BFD library (@pxref{BFD}). You can see the
|
|
architecture of an object file by using the @code{objdump} program with
|
|
the @samp{-f} option.
|
|
@end ifclear
|
|
@end table
|
|
|
|
@node Assignments
|
|
@section Assigning Values to Symbols
|
|
@cindex assignment in scripts
|
|
@cindex symbol definition, scripts
|
|
@cindex variables, defining
|
|
You may assign a value to a symbol in a linker script. This will define
|
|
the symbol as a global symbol.
|
|
|
|
@menu
|
|
* Simple Assignments:: Simple Assignments
|
|
* PROVIDE:: PROVIDE
|
|
@end menu
|
|
|
|
@node Simple Assignments
|
|
@subsection Simple Assignments
|
|
|
|
You may assign to a symbol using any of the C assignment operators:
|
|
|
|
@table @code
|
|
@item @var{symbol} = @var{expression} ;
|
|
@itemx @var{symbol} += @var{expression} ;
|
|
@itemx @var{symbol} -= @var{expression} ;
|
|
@itemx @var{symbol} *= @var{expression} ;
|
|
@itemx @var{symbol} /= @var{expression} ;
|
|
@itemx @var{symbol} <<= @var{expression} ;
|
|
@itemx @var{symbol} >>= @var{expression} ;
|
|
@itemx @var{symbol} &= @var{expression} ;
|
|
@itemx @var{symbol} |= @var{expression} ;
|
|
@end table
|
|
|
|
The first case will define @var{symbol} to the value of
|
|
@var{expression}. In the other cases, @var{symbol} must already be
|
|
defined, and the value will be adjusted accordingly.
|
|
|
|
The special symbol name @samp{.} indicates the location counter. You
|
|
may only use this within a @code{SECTIONS} command.
|
|
|
|
The semicolon after @var{expression} is required.
|
|
|
|
Expressions are defined below; see @ref{Expressions}.
|
|
|
|
You may write symbol assignments as commands in their own right, or as
|
|
statements within a @code{SECTIONS} command, or as part of an output
|
|
section description in a @code{SECTIONS} command.
|
|
|
|
The section of the symbol will be set from the section of the
|
|
expression; for more information, see @ref{Expression Section}.
|
|
|
|
Here is an example showing the three different places that symbol
|
|
assignments may be used:
|
|
|
|
@smallexample
|
|
floating_point = 0;
|
|
SECTIONS
|
|
@{
|
|
.text :
|
|
@{
|
|
*(.text)
|
|
_etext = .;
|
|
@}
|
|
_bdata = (. + 3) & ~ 3;
|
|
.data : @{ *(.data) @}
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
In this example, the symbol @samp{floating_point} will be defined as
|
|
zero. The symbol @samp{_etext} will be defined as the address following
|
|
the last @samp{.text} input section. The symbol @samp{_bdata} will be
|
|
defined as the address following the @samp{.text} output section aligned
|
|
upward to a 4 byte boundary.
|
|
|
|
@node PROVIDE
|
|
@subsection PROVIDE
|
|
@cindex PROVIDE
|
|
In some cases, it is desirable for a linker script to define a symbol
|
|
only if it is referenced and is not defined by any object included in
|
|
the link. For example, traditional linkers defined the symbol
|
|
@samp{etext}. However, ANSI C requires that the user be able to use
|
|
@samp{etext} as a function name without encountering an error. The
|
|
@code{PROVIDE} keyword may be used to define a symbol, such as
|
|
@samp{etext}, only if it is referenced but not defined. The syntax is
|
|
@code{PROVIDE(@var{symbol} = @var{expression})}.
|
|
|
|
Here is an example of using @code{PROVIDE} to define @samp{etext}:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
.text :
|
|
@{
|
|
*(.text)
|
|
_etext = .;
|
|
PROVIDE(etext = .);
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
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
|
|
@kindex SECTIONS
|
|
The @code{SECTIONS} command tells the linker how to map input sections
|
|
into output sections, and how to place the output sections in memory.
|
|
|
|
The format of the @code{SECTIONS} command is:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
@var{sections-command}
|
|
@var{sections-command}
|
|
@dots{}
|
|
@}
|
|
@end smallexample
|
|
|
|
Each @var{sections-command} may of be one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
|
|
@item
|
|
a symbol assignment (@pxref{Assignments})
|
|
@item
|
|
an output section description
|
|
@item
|
|
an overlay description
|
|
@end itemize
|
|
|
|
The @code{ENTRY} command and symbol assignments are permitted inside the
|
|
@code{SECTIONS} command for convenience in using the location counter in
|
|
those commands. This can also make the linker script easier to
|
|
understand because you can use those commands at meaningful points in
|
|
the layout of the output file.
|
|
|
|
Output section descriptions and overlay descriptions are described
|
|
below.
|
|
|
|
If you do not use a @code{SECTIONS} command in your linker script, the
|
|
linker will place each input section into an identically named output
|
|
section in the order that the sections are first encountered in the
|
|
input files. If all input sections are present in the first file, for
|
|
example, the order of sections in the output file will match the order
|
|
in the first input file. The first section will be at address zero.
|
|
|
|
@menu
|
|
* Output Section Description:: Output section description
|
|
* Output Section Name:: Output section name
|
|
* Output Section Address:: Output section address
|
|
* Input Section:: Input section description
|
|
* Output Section Data:: Output section data
|
|
* Output Section Keywords:: Output section keywords
|
|
* Output Section Discarding:: Output section discarding
|
|
* Output Section Attributes:: Output section attributes
|
|
* Overlay Description:: Overlay description
|
|
@end menu
|
|
|
|
@node Output Section Description
|
|
@subsection Output Section Description
|
|
The full description of an output section looks like this:
|
|
@smallexample
|
|
@group
|
|
@var{section} [@var{address}] [(@var{type})] :
|
|
[AT(@var{lma})] [SUBALIGN(@var{subsection_align})]
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
|
|
@end group
|
|
@end smallexample
|
|
|
|
Most output sections do not use most of the optional section attributes.
|
|
|
|
The whitespace around @var{section} is required, so that the section
|
|
name is unambiguous. The colon and the curly braces are also required.
|
|
The line breaks and other white space are optional.
|
|
|
|
Each @var{output-section-command} may be one of the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
a symbol assignment (@pxref{Assignments})
|
|
@item
|
|
an input section description (@pxref{Input Section})
|
|
@item
|
|
data values to include directly (@pxref{Output Section Data})
|
|
@item
|
|
a special output section keyword (@pxref{Output Section Keywords})
|
|
@end itemize
|
|
|
|
@node Output Section Name
|
|
@subsection Output Section Name
|
|
@cindex name, section
|
|
@cindex section name
|
|
The name of the output section is @var{section}. @var{section} must
|
|
meet the constraints of your output format. In formats which only
|
|
support a limited number of sections, such as @code{a.out}, the name
|
|
must be one of the names supported by the format (@code{a.out}, for
|
|
example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
|
|
output format supports any number of sections, but with numbers and not
|
|
names (as is the case for Oasys), the name should be supplied as a
|
|
quoted numeric string. A section name may consist of any sequence of
|
|
characters, but a name which contains any unusual characters such as
|
|
commas must be quoted.
|
|
|
|
The output section name @samp{/DISCARD/} is special; @ref{Output Section
|
|
Discarding}.
|
|
|
|
@node Output Section Address
|
|
@subsection Output Section Address
|
|
@cindex address, section
|
|
@cindex section address
|
|
The @var{address} is an expression for the VMA (the virtual memory
|
|
address) of the output section. If you do not provide @var{address},
|
|
the linker will set it based on @var{region} if present, or otherwise
|
|
based on the current value of the location counter.
|
|
|
|
If you provide @var{address}, the address of the output section will be
|
|
set to precisely that. If you provide neither @var{address} nor
|
|
@var{region}, then the address of the output section will be set to the
|
|
current value of the location counter aligned to the alignment
|
|
requirements of the output section. The alignment requirement of the
|
|
output section is the strictest alignment of any input section contained
|
|
within the output section.
|
|
|
|
For example,
|
|
@smallexample
|
|
.text . : @{ *(.text) @}
|
|
@end smallexample
|
|
@noindent
|
|
and
|
|
@smallexample
|
|
.text : @{ *(.text) @}
|
|
@end smallexample
|
|
@noindent
|
|
are subtly different. The first will set the address of the
|
|
@samp{.text} output section to the current value of the location
|
|
counter. The second will set it to the current value of the location
|
|
counter aligned to the strictest alignment of a @samp{.text} input
|
|
section.
|
|
|
|
The @var{address} may be an arbitrary expression; @ref{Expressions}.
|
|
For example, if you want to align the section on a 0x10 byte boundary,
|
|
so that the lowest four bits of the section address are zero, you could
|
|
do something like this:
|
|
@smallexample
|
|
.text ALIGN(0x10) : @{ *(.text) @}
|
|
@end smallexample
|
|
@noindent
|
|
This works because @code{ALIGN} returns the current location counter
|
|
aligned upward to the specified value.
|
|
|
|
Specifying @var{address} for a section will change the value of the
|
|
location counter.
|
|
|
|
@node Input Section
|
|
@subsection Input Section Description
|
|
@cindex input sections
|
|
@cindex mapping input sections to output sections
|
|
The most common output section command is an input section description.
|
|
|
|
The input section description is the most basic linker script operation.
|
|
You use output sections to tell the linker how to lay out your program
|
|
in memory. You use input section descriptions to tell the linker how to
|
|
map the input files into your memory layout.
|
|
|
|
@menu
|
|
* 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
|
|
|
|
@node Input Section Basics
|
|
@subsubsection Input Section Basics
|
|
@cindex input section basics
|
|
An input section description consists of a file name optionally followed
|
|
by a list of section names in parentheses.
|
|
|
|
The file name and the section name may be wildcard patterns, which we
|
|
describe further below (@pxref{Input Section Wildcards}).
|
|
|
|
The most common input section description is to include all input
|
|
sections with a particular name in the output section. For example, to
|
|
include all input @samp{.text} sections, you would write:
|
|
@smallexample
|
|
*(.text)
|
|
@end smallexample
|
|
@noindent
|
|
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
|
|
*(.text .rdata)
|
|
*(.text) *(.rdata)
|
|
@end smallexample
|
|
@noindent
|
|
The difference between these is the order in which the @samp{.text} and
|
|
@samp{.rdata} input sections will appear in the output section. In the
|
|
first example, they will be intermingled, appearing in the same order as
|
|
they are found in the linker input. In the second example, all
|
|
@samp{.text} input sections will appear first, followed by all
|
|
@samp{.rdata} input sections.
|
|
|
|
You can specify a file name to include sections from a particular file.
|
|
You would do this if one or more of your files contain special data that
|
|
needs to be at a particular location in memory. For example:
|
|
@smallexample
|
|
data.o(.data)
|
|
@end smallexample
|
|
|
|
If you use a file name without a list of sections, then all sections in
|
|
the input file will be included in the output section. This is not
|
|
commonly done, but it may by useful on occasion. For example:
|
|
@smallexample
|
|
data.o
|
|
@end smallexample
|
|
|
|
When you use a file name which does not contain any wild card
|
|
characters, the linker will first see if you also specified the file
|
|
name on the linker command line or in an @code{INPUT} command. If you
|
|
did not, the linker will attempt to open the file as an input file, as
|
|
though it appeared on the command line. Note that this differs from an
|
|
@code{INPUT} command, because the linker will not search for the file in
|
|
the archive search path.
|
|
|
|
@node Input Section Wildcards
|
|
@subsubsection Input Section Wildcard Patterns
|
|
@cindex input section wildcards
|
|
@cindex wildcard file name patterns
|
|
@cindex file name wildcard patterns
|
|
@cindex section name wildcard patterns
|
|
In an input section description, either the file name or the section
|
|
name or both may be wildcard patterns.
|
|
|
|
The file name of @samp{*} seen in many examples is a simple wildcard
|
|
pattern for the file name.
|
|
|
|
The wildcard patterns are like those used by the Unix shell.
|
|
|
|
@table @samp
|
|
@item *
|
|
matches any number of characters
|
|
@item ?
|
|
matches any single character
|
|
@item [@var{chars}]
|
|
matches a single instance of any of the @var{chars}; the @samp{-}
|
|
character may be used to specify a range of characters, as in
|
|
@samp{[a-z]} to match any lower case letter
|
|
@item \
|
|
quotes the following character
|
|
@end table
|
|
|
|
When a file name is matched with a wildcard, the wildcard characters
|
|
will not match a @samp{/} character (used to separate directory names on
|
|
Unix). A pattern consisting of a single @samp{*} character is an
|
|
exception; it will always match any file name, whether it contains a
|
|
@samp{/} or not. In a section name, the wildcard characters will match
|
|
a @samp{/} character.
|
|
|
|
File name wildcard patterns only match files which are explicitly
|
|
specified on the command line or in an @code{INPUT} command. The linker
|
|
does not search directories to expand wildcards.
|
|
|
|
If a file name matches more than one wildcard pattern, or if a file name
|
|
appears explicitly and is also matched by a wildcard pattern, the linker
|
|
will use the first match in the linker script. For example, this
|
|
sequence of input section descriptions is probably in error, because the
|
|
@file{data.o} rule will not be used:
|
|
@smallexample
|
|
.data : @{ *(.data) @}
|
|
.data1 : @{ data.o(.data) @}
|
|
@end smallexample
|
|
|
|
@cindex SORT_BY_NAME
|
|
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_BY_NAME} keyword, which appears before a wildcard
|
|
pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the
|
|
@code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
|
|
into ascending order by name before placing them in the output file.
|
|
|
|
@cindex SORT_BY_ALIGNMENT
|
|
@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
|
|
difference is @code{SORT_BY_ALIGNMENT} will sort sections into
|
|
ascending order by alignment before placing them in the output file.
|
|
|
|
@cindex SORT
|
|
@code{SORT} is an alias for @code{SORT_BY_NAME}.
|
|
|
|
When there are nested section sorting commands in linker script, there
|
|
can be at most 1 level of nesting for section sorting commands.
|
|
|
|
@enumerate
|
|
@item
|
|
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
|
|
It will sort the input sections by name first, then by alignment if 2
|
|
sections have the same name.
|
|
@item
|
|
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
|
|
It will sort the input sections by alignment first, then by name if 2
|
|
sections have the same alignment.
|
|
@item
|
|
@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
|
|
treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
|
|
@item
|
|
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
|
|
is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
|
|
@item
|
|
All other nested section sorting commands are invalid.
|
|
@end enumerate
|
|
|
|
When both command line section sorting option and linker script
|
|
section sorting command are used, section sorting command always
|
|
takes precedence over the command line option.
|
|
|
|
If the section sorting command in linker script isn't nested, the
|
|
command line option will make the section sorting command to be
|
|
treated as nested sorting command.
|
|
|
|
@enumerate
|
|
@item
|
|
@code{SORT_BY_NAME} (wildcard section pattern ) with
|
|
@option{--sort-sections alignment} is equivalent to
|
|
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
|
|
@item
|
|
@code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
|
|
@option{--sort-section name} is equivalent to
|
|
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
|
|
@end enumerate
|
|
|
|
If the section sorting command in linker script is nested, the
|
|
command line option will be ignored.
|
|
|
|
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.
|
|
|
|
This example shows how wildcard patterns might be used to partition
|
|
files. This linker script directs the linker to place all @samp{.text}
|
|
sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
|
|
The linker will place the @samp{.data} section from all files beginning
|
|
with an upper case character in @samp{.DATA}; for all other files, the
|
|
linker will place the @samp{.data} section in @samp{.data}.
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text : @{ *(.text) @}
|
|
.DATA : @{ [A-Z]*(.data) @}
|
|
.data : @{ *(.data) @}
|
|
.bss : @{ *(.bss) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Input Section Common
|
|
@subsubsection Input Section for Common Symbols
|
|
@cindex common symbol placement
|
|
@cindex uninitialized data placement
|
|
A special notation is needed for common symbols, because in many object
|
|
file formats common symbols do not have a particular input section. The
|
|
linker treats common symbols as though they are in an input section
|
|
named @samp{COMMON}.
|
|
|
|
You may use file names with the @samp{COMMON} section just as with any
|
|
other input sections. You can use this to place common symbols from a
|
|
particular input file in one section while common symbols from other
|
|
input files are placed in another section.
|
|
|
|
In most cases, common symbols in input files will be placed in the
|
|
@samp{.bss} section in the output file. For example:
|
|
@smallexample
|
|
.bss @{ *(.bss) *(COMMON) @}
|
|
@end smallexample
|
|
|
|
@cindex scommon section
|
|
@cindex small common symbols
|
|
Some object file formats have more than one type of common symbol. For
|
|
example, the MIPS ELF object file format distinguishes standard common
|
|
symbols and small common symbols. In this case, the linker will use a
|
|
different special section name for other types of common symbols. In
|
|
the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
|
|
symbols and @samp{.scommon} for small common symbols. This permits you
|
|
to map the different types of common symbols into memory at different
|
|
locations.
|
|
|
|
@cindex [COMMON]
|
|
You will sometimes see @samp{[COMMON]} in old linker scripts. This
|
|
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_BY_NAME(*)(.ctors))}.
|
|
|
|
@node Input Section Example
|
|
@subsubsection Input Section Example
|
|
The following example is a complete linker script. It tells the linker
|
|
to read all of the sections from file @file{all.o} and place them at the
|
|
start of output section @samp{outputa} which starts at location
|
|
@samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
|
|
follows immediately, in the same output section. All of section
|
|
@samp{.input2} from @file{foo.o} goes into output section
|
|
@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
|
|
All of the remaining @samp{.input1} and @samp{.input2} sections from any
|
|
files are written to output section @samp{outputc}.
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
outputa 0x10000 :
|
|
@{
|
|
all.o
|
|
foo.o (.input1)
|
|
@}
|
|
@end group
|
|
@group
|
|
outputb :
|
|
@{
|
|
foo.o (.input2)
|
|
foo1.o (.input1)
|
|
@}
|
|
@end group
|
|
@group
|
|
outputc :
|
|
@{
|
|
*(.input1)
|
|
*(.input2)
|
|
@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section Data
|
|
@subsection Output Section Data
|
|
@cindex data
|
|
@cindex section data
|
|
@cindex output section data
|
|
@kindex BYTE(@var{expression})
|
|
@kindex SHORT(@var{expression})
|
|
@kindex LONG(@var{expression})
|
|
@kindex QUAD(@var{expression})
|
|
@kindex SQUAD(@var{expression})
|
|
You can include explicit bytes of data in an output section by using
|
|
@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
|
|
an output section command. Each keyword is followed by an expression in
|
|
parentheses providing the value to store (@pxref{Expressions}). The
|
|
value of the expression is stored at the current value of the location
|
|
counter.
|
|
|
|
The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
|
|
store one, two, four, and eight bytes (respectively). After storing the
|
|
bytes, the location counter is incremented by the number of bytes
|
|
stored.
|
|
|
|
For example, this will store the byte 1 followed by the four byte value
|
|
of the symbol @samp{addr}:
|
|
@smallexample
|
|
BYTE(1)
|
|
LONG(addr)
|
|
@end smallexample
|
|
|
|
When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
|
|
same; they both store an 8 byte, or 64 bit, value. When both host and
|
|
target are 32 bits, an expression is computed as 32 bits. In this case
|
|
@code{QUAD} stores a 32 bit value zero extended to 64 bits, and
|
|
@code{SQUAD} stores a 32 bit value sign extended to 64 bits.
|
|
|
|
If the object file format of the output file has an explicit endianness,
|
|
which is the normal case, the value will be stored in that endianness.
|
|
When the object file format does not have an explicit endianness, as is
|
|
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
|
|
You may use the @code{FILL} command to set the fill pattern for the
|
|
current section. It is followed by an expression in parentheses. Any
|
|
otherwise unspecified regions of memory within the section (for example,
|
|
gaps left due to the required alignment of input sections) are filled
|
|
with the value of the expression, repeated as
|
|
necessary. A @code{FILL} statement covers memory locations after the
|
|
point at which it occurs in the section definition; by including more
|
|
than one @code{FILL} statement, you can have different fill patterns in
|
|
different parts of an output section.
|
|
|
|
This example shows how to fill unspecified regions of memory with the
|
|
value @samp{0x90}:
|
|
@smallexample
|
|
FILL(0x90909090)
|
|
@end smallexample
|
|
|
|
The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
|
|
section attribute, but it only affects the
|
|
part of the section following the @code{FILL} command, rather than the
|
|
entire section. If both are used, the @code{FILL} command takes
|
|
precedence. @xref{Output Section Fill}, for details on the fill
|
|
expression.
|
|
|
|
@node Output Section Keywords
|
|
@subsection Output Section Keywords
|
|
There are a couple of keywords which can appear as output section
|
|
commands.
|
|
|
|
@table @code
|
|
@kindex CREATE_OBJECT_SYMBOLS
|
|
@cindex input filename symbols
|
|
@cindex filename symbols
|
|
@item CREATE_OBJECT_SYMBOLS
|
|
The command tells the linker to create a symbol for each input file.
|
|
The name of each symbol will be the name of the corresponding input
|
|
file. The section of each symbol will be the output section in which
|
|
the @code{CREATE_OBJECT_SYMBOLS} command appears.
|
|
|
|
This is conventional for the a.out object file format. It is not
|
|
normally used for any other object file format.
|
|
|
|
@kindex CONSTRUCTORS
|
|
@cindex C++ constructors, arranging in link
|
|
@cindex constructors, arranging in link
|
|
@item CONSTRUCTORS
|
|
When linking using the a.out object file format, the linker uses an
|
|
unusual set construct to support C++ global constructors and
|
|
destructors. When linking object file formats which do not support
|
|
arbitrary sections, such as ECOFF and XCOFF, the linker will
|
|
automatically recognize C++ global constructors and destructors by name.
|
|
For these object file formats, the @code{CONSTRUCTORS} command tells the
|
|
linker to place constructor information in the output section where the
|
|
@code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
|
|
ignored for other object file formats.
|
|
|
|
The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
|
|
constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The
|
|
first word in the list is the number of entries, followed by the address
|
|
of each constructor or destructor, followed by a zero word. The
|
|
compiler must arrange to actually run the code. For these object file
|
|
formats @sc{gnu} C++ normally calls constructors from a subroutine
|
|
@code{__main}; a call to @code{__main} is automatically inserted into
|
|
the startup code for @code{main}. @sc{gnu} C++ normally runs
|
|
destructors either by using @code{atexit}, or directly from the function
|
|
@code{exit}.
|
|
|
|
For object file formats such as @code{COFF} or @code{ELF} which support
|
|
arbitrary section names, @sc{gnu} C++ will normally arrange to put the
|
|
addresses of global constructors and destructors into the @code{.ctors}
|
|
and @code{.dtors} sections. Placing the following sequence into your
|
|
linker script will build the sort of table which the @sc{gnu} C++
|
|
runtime code expects to see.
|
|
|
|
@smallexample
|
|
__CTOR_LIST__ = .;
|
|
LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
|
|
*(.ctors)
|
|
LONG(0)
|
|
__CTOR_END__ = .;
|
|
__DTOR_LIST__ = .;
|
|
LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
|
|
*(.dtors)
|
|
LONG(0)
|
|
__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_BY_NAME(CONSTRUCTORS)} instead. When using the
|
|
@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
|
|
@samp{*(SORT_BY_NAME(.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
|
|
@subsection Output Section Discarding
|
|
@cindex discarding sections
|
|
@cindex sections, discarding
|
|
@cindex removing sections
|
|
The linker will not create output section which do not have any
|
|
contents. This is for convenience when referring to input sections that
|
|
may or may not be present in any of the input files. For example:
|
|
@smallexample
|
|
.foo @{ *(.foo) @}
|
|
@end smallexample
|
|
@noindent
|
|
will only create a @samp{.foo} section in the output file if there is a
|
|
@samp{.foo} section in at least one input file.
|
|
|
|
If you use anything other than an input section description as an output
|
|
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.
|
|
|
|
@node Output Section Attributes
|
|
@subsection Output Section Attributes
|
|
@cindex output section attributes
|
|
We showed above that the full description of an output section looked
|
|
like this:
|
|
@smallexample
|
|
@group
|
|
@var{section} [@var{address}] [(@var{type})] :
|
|
[AT(@var{lma})] [SUBALIGN(@var{subsection_align})]
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [>@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
|
|
@var{output-section-command}. In this section we will describe the
|
|
remaining section attributes.
|
|
|
|
@menu
|
|
* Output Section Type:: Output section type
|
|
* Output Section LMA:: Output section LMA
|
|
* Forced Input Alignment:: Forced Input Alignment
|
|
* Output Section Region:: Output section region
|
|
* Output Section Phdr:: Output section phdr
|
|
* Output Section Fill:: Output section fill
|
|
@end menu
|
|
|
|
@node Output Section Type
|
|
@subsubsection Output Section Type
|
|
Each output section may have a type. The type is a keyword in
|
|
parentheses. The following types are defined:
|
|
|
|
@table @code
|
|
@item NOLOAD
|
|
The section should be marked as not loadable, so that it will not be
|
|
loaded into memory when the program is run.
|
|
@item DSECT
|
|
@itemx COPY
|
|
@itemx INFO
|
|
@itemx OVERLAY
|
|
These type names are supported for backward compatibility, and are
|
|
rarely used. They all have the same effect: the section should be
|
|
marked as not allocatable, so that no memory is allocated for the
|
|
section when the program is run.
|
|
@end table
|
|
|
|
@kindex NOLOAD
|
|
@cindex prevent unnecessary loading
|
|
@cindex loading, preventing
|
|
The linker normally sets the attributes of an output section based on
|
|
the input sections which map into it. You can override this by using
|
|
the section type. For example, in the script sample below, the
|
|
@samp{ROM} section is addressed at memory location @samp{0} and does not
|
|
need to be loaded when the program is run. The contents of the
|
|
@samp{ROM} section will appear in the linker output file as usual.
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
ROM 0 (NOLOAD) : @{ @dots{} @}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section LMA
|
|
@subsubsection Output Section LMA
|
|
@kindex AT>@var{lma_region}
|
|
@kindex AT(@var{lma})
|
|
@cindex load address
|
|
@cindex section load address
|
|
Every section has a virtual address (VMA) and a load address (LMA); see
|
|
@ref{Basic Script Concepts}. The address expression which may appear in
|
|
an output section description sets the VMA (@pxref{Output Section
|
|
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.
|
|
|
|
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
|
|
This feature is designed to make it easy to build a ROM image. For
|
|
example, the following linker script creates three output sections: one
|
|
called @samp{.text}, which starts at @code{0x1000}, one called
|
|
@samp{.mdata}, which is loaded at the end of the @samp{.text} section
|
|
even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
|
|
uninitialized data at address @code{0x3000}. The symbol @code{_data} is
|
|
defined with the value @code{0x2000}, which shows that the location
|
|
counter holds the VMA value, not the LMA value.
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS
|
|
@{
|
|
.text 0x1000 : @{ *(.text) _etext = . ; @}
|
|
.mdata 0x2000 :
|
|
AT ( ADDR (.text) + SIZEOF (.text) )
|
|
@{ _data = . ; *(.data); _edata = . ; @}
|
|
.bss 0x3000 :
|
|
@{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The run-time initialization code for use with a program generated with
|
|
this linker script would include something like the following, to copy
|
|
the initialized data from the ROM image to its runtime address. Notice
|
|
how this code takes advantage of the symbols defined by the linker
|
|
script.
|
|
|
|
@smallexample
|
|
@group
|
|
extern char _etext, _data, _edata, _bstart, _bend;
|
|
char *src = &_etext;
|
|
char *dst = &_data;
|
|
|
|
/* ROM has data at end of text; copy it. */
|
|
while (dst < &_edata) @{
|
|
*dst++ = *src++;
|
|
@}
|
|
|
|
/* Zero bss */
|
|
for (dst = &_bstart; dst< &_bend; dst++)
|
|
*dst = 0;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Forced Input Alignment
|
|
@subsubsection Forced Input Alignment
|
|
@kindex SUBALIGN(@var{subsection_align})
|
|
@cindex forcing input section alignment
|
|
@cindex input section alignment
|
|
You can force input section alignment within an output section by using
|
|
SUBALIGN. The value specified overrides any alignment given by input
|
|
sections, whether larger or smaller.
|
|
|
|
@node Output Section Region
|
|
@subsubsection Output Section Region
|
|
@kindex >@var{region}
|
|
@cindex section, assigning to memory region
|
|
@cindex memory regions and sections
|
|
You can assign a section to a previously defined region of memory by
|
|
using @samp{>@var{region}}. @xref{MEMORY}.
|
|
|
|
Here is a simple example:
|
|
@smallexample
|
|
@group
|
|
MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
|
|
SECTIONS @{ ROM : @{ *(.text) @} >rom @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section Phdr
|
|
@subsubsection Output Section Phdr
|
|
@kindex :@var{phdr}
|
|
@cindex section, assigning to program header
|
|
@cindex program headers and sections
|
|
You can assign a section to a previously defined program segment by
|
|
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. 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
|
|
@group
|
|
PHDRS @{ text PT_LOAD ; @}
|
|
SECTIONS @{ .text : @{ *(.text) @} :text @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Output Section Fill
|
|
@subsubsection Output Section Fill
|
|
@kindex =@var{fillexp}
|
|
@cindex section fill pattern
|
|
@cindex fill pattern, entire section
|
|
You can set the fill pattern for an entire section by using
|
|
@samp{=@var{fillexp}}. @var{fillexp} is an expression
|
|
(@pxref{Expressions}). Any otherwise unspecified regions of memory
|
|
within the output section (for example, gaps left due to the required
|
|
alignment of input sections) will be filled with the value, repeated as
|
|
necessary. If the fill expression is a simple hex number, ie. a string
|
|
of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
|
|
an arbitrarily long sequence of hex digits can be used to specify the
|
|
fill pattern; Leading zeros become part of the pattern too. For all
|
|
other cases, including extra parentheses or a unary @code{+}, the fill
|
|
pattern is the four least significant bytes of the value of the
|
|
expression. In all cases, the number is big-endian.
|
|
|
|
You can also change the fill value with a @code{FILL} command in the
|
|
output section commands; (@pxref{Output Section Data}).
|
|
|
|
Here is a simple example:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Overlay Description
|
|
@subsection Overlay Description
|
|
@kindex OVERLAY
|
|
@cindex overlays
|
|
An overlay description provides an easy way to describe sections which
|
|
are to be loaded as part of a single memory image but are to be run at
|
|
the same memory address. At run time, some sort of overlay manager will
|
|
copy the overlaid sections in and out of the runtime memory address as
|
|
required, perhaps by simply manipulating addressing bits. This approach
|
|
can be useful, for example, when a certain region of memory is faster
|
|
than another.
|
|
|
|
Overlays are described using the @code{OVERLAY} command. The
|
|
@code{OVERLAY} command is used within a @code{SECTIONS} command, like an
|
|
output section description. The full syntax of the @code{OVERLAY}
|
|
command is as follows:
|
|
@smallexample
|
|
@group
|
|
OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
|
|
@{
|
|
@var{secname1}
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [:@var{phdr}@dots{}] [=@var{fill}]
|
|
@var{secname2}
|
|
@{
|
|
@var{output-section-command}
|
|
@var{output-section-command}
|
|
@dots{}
|
|
@} [:@var{phdr}@dots{}] [=@var{fill}]
|
|
@dots{}
|
|
@} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
|
|
@end group
|
|
@end smallexample
|
|
|
|
Everything is optional except @code{OVERLAY} (a keyword), and each
|
|
section must have a name (@var{secname1} and @var{secname2} above). The
|
|
section definitions within the @code{OVERLAY} construct are identical to
|
|
those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
|
|
except that no addresses and no memory regions may be defined for
|
|
sections within an @code{OVERLAY}.
|
|
|
|
The sections are all defined with the same starting address. The load
|
|
addresses of the sections are arranged such that they are consecutive in
|
|
memory starting at the load address used for the @code{OVERLAY} as a
|
|
whole (as with normal section definitions, the load address is optional,
|
|
and defaults to the start address; the start address is also optional,
|
|
and defaults to the current value of the location counter).
|
|
|
|
If the @code{NOCROSSREFS} keyword is used, and there any references
|
|
among the sections, the linker will report an error. Since the sections
|
|
all run at the same address, it normally does not make sense for one
|
|
section to refer directly to another. @xref{Miscellaneous Commands,
|
|
NOCROSSREFS}.
|
|
|
|
For each section within the @code{OVERLAY}, the linker automatically
|
|
defines two symbols. The symbol @code{__load_start_@var{secname}} is
|
|
defined as the starting load address of the section. The symbol
|
|
@code{__load_stop_@var{secname}} is defined as the final load address of
|
|
the section. Any characters within @var{secname} which are not legal
|
|
within C identifiers are removed. C (or assembler) code may use these
|
|
symbols to move the overlaid sections around as necessary.
|
|
|
|
At the end of the overlay, the value of the location counter is set to
|
|
the start address of the overlay plus the size of the largest section.
|
|
|
|
Here is an example. Remember that this would appear inside a
|
|
@code{SECTIONS} construct.
|
|
@smallexample
|
|
@group
|
|
OVERLAY 0x1000 : AT (0x4000)
|
|
@{
|
|
.text0 @{ o1/*.o(.text) @}
|
|
.text1 @{ o2/*.o(.text) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
This will define both @samp{.text0} and @samp{.text1} to start at
|
|
address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
|
|
@samp{.text1} will be loaded immediately after @samp{.text0}. The
|
|
following symbols will be defined: @code{__load_start_text0},
|
|
@code{__load_stop_text0}, @code{__load_start_text1},
|
|
@code{__load_stop_text1}.
|
|
|
|
C code to copy overlay @code{.text1} into the overlay area might look
|
|
like the following.
|
|
|
|
@smallexample
|
|
@group
|
|
extern char __load_start_text1, __load_stop_text1;
|
|
memcpy ((char *) 0x1000, &__load_start_text1,
|
|
&__load_stop_text1 - &__load_start_text1);
|
|
@end group
|
|
@end smallexample
|
|
|
|
Note that the @code{OVERLAY} command is just syntactic sugar, since
|
|
everything it does can be done using the more basic commands. The above
|
|
example could have been written identically as follows.
|
|
|
|
@smallexample
|
|
@group
|
|
.text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
|
|
__load_start_text0 = LOADADDR (.text0);
|
|
__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
|
|
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
|
|
__load_start_text1 = LOADADDR (.text1);
|
|
__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
|
|
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node MEMORY
|
|
@section MEMORY Command
|
|
@kindex MEMORY
|
|
@cindex memory regions
|
|
@cindex regions of memory
|
|
@cindex allocating memory
|
|
@cindex discontinuous memory
|
|
The linker's default configuration permits allocation of all available
|
|
memory. You can override this by using the @code{MEMORY} command.
|
|
|
|
The @code{MEMORY} command describes the location and size of blocks of
|
|
memory in the target. You can use it to describe which memory regions
|
|
may be used by the linker, and which memory regions it must avoid. You
|
|
can then assign sections to particular memory regions. The linker will
|
|
set section addresses based on the memory regions, and will warn about
|
|
regions that become too full. The linker will not shuffle sections
|
|
around to fit into the available regions.
|
|
|
|
A linker script may contain at most one use of the @code{MEMORY}
|
|
command. However, you can define as many blocks of memory within it as
|
|
you wish. The syntax is:
|
|
@smallexample
|
|
@group
|
|
MEMORY
|
|
@{
|
|
@var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @var{name} is a name used in the linker script to refer to the
|
|
region. The region name has no meaning outside of the linker script.
|
|
Region names are stored in a separate name space, and will not conflict
|
|
with symbol names, file names, or section names. Each memory region
|
|
must have a distinct name.
|
|
|
|
@cindex memory region attributes
|
|
The @var{attr} string is an optional list of attributes that specify
|
|
whether to use a particular memory region for an input section which is
|
|
not explicitly mapped in the linker script. As described in
|
|
@ref{SECTIONS}, if you do not specify an output section for some input
|
|
section, the linker will create an output section with the same name as
|
|
the input section. If you define region attributes, the linker will use
|
|
them to select the memory region for the output section that it creates.
|
|
|
|
The @var{attr} string must consist only of the following characters:
|
|
@table @samp
|
|
@item R
|
|
Read-only section
|
|
@item W
|
|
Read/write section
|
|
@item X
|
|
Executable section
|
|
@item A
|
|
Allocatable section
|
|
@item I
|
|
Initialized section
|
|
@item L
|
|
Same as @samp{I}
|
|
@item !
|
|
Invert the sense of any of the preceding attributes
|
|
@end table
|
|
|
|
If a unmapped section matches any of the listed attributes other than
|
|
@samp{!}, it will be placed in the memory region. The @samp{!}
|
|
attribute reverses this test, so that an unmapped section will be placed
|
|
in the memory region only if it does not match any of the listed
|
|
attributes.
|
|
|
|
@kindex ORIGIN =
|
|
@kindex o =
|
|
@kindex org =
|
|
The @var{origin} is an numerical expression for the start address of
|
|
the memory region. The expression must evaluate to a constant and it
|
|
cannot involve any symbols. The keyword @code{ORIGIN} may be
|
|
abbreviated to @code{org} or @code{o} (but not, for example,
|
|
@code{ORG}).
|
|
|
|
@kindex LENGTH =
|
|
@kindex len =
|
|
@kindex l =
|
|
The @var{len} is an expression for the size in bytes of the memory
|
|
region. As with the @var{origin} expression, the expression must
|
|
be numerical only and must evaluate to a constant. The keyword
|
|
@code{LENGTH} may be abbreviated to @code{len} or @code{l}.
|
|
|
|
In the following example, we specify that there are two memory regions
|
|
available for allocation: one starting at @samp{0} for 256 kilobytes,
|
|
and the other starting at @samp{0x40000000} for four megabytes. The
|
|
linker will place into the @samp{rom} memory region every section which
|
|
is not explicitly mapped into a memory region, and is either read-only
|
|
or executable. The linker will place other sections which are not
|
|
explicitly mapped into a memory region into the @samp{ram} memory
|
|
region.
|
|
|
|
@smallexample
|
|
@group
|
|
MEMORY
|
|
@{
|
|
rom (rx) : ORIGIN = 0, LENGTH = 256K
|
|
ram (!rx) : org = 0x40000000, l = 4M
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
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.
|
|
|
|
It is possible to access the origin and length of a memory in an
|
|
expression via the @code{ORIGIN(@var{memory})} and
|
|
@code{LENGTH(@var{memory})} functions:
|
|
|
|
@smallexample
|
|
@group
|
|
_fstack = ORIGIN(ram) + LENGTH(ram) - 4;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node PHDRS
|
|
@section PHDRS Command
|
|
@kindex PHDRS
|
|
@cindex program headers
|
|
@cindex ELF program headers
|
|
@cindex program segments
|
|
@cindex segments, ELF
|
|
The ELF object file format uses @dfn{program headers}, also knows as
|
|
@dfn{segments}. The program headers describe how the program should be
|
|
loaded into memory. You can print them out by using the @code{objdump}
|
|
program with the @samp{-p} option.
|
|
|
|
When you run an ELF program on a native ELF system, the system loader
|
|
reads the program headers in order to figure out how to load the
|
|
program. This will only work if the program headers are set correctly.
|
|
This manual does not describe the details of how the system loader
|
|
interprets program headers; for more information, see the ELF ABI.
|
|
|
|
The linker will create reasonable program headers by default. However,
|
|
in some cases, you may need to specify the program headers more
|
|
precisely. You may use the @code{PHDRS} command for this purpose. When
|
|
the linker sees the @code{PHDRS} command in the linker script, it will
|
|
not create any program headers other than the ones specified.
|
|
|
|
The linker only pays attention to the @code{PHDRS} command when
|
|
generating an ELF output file. In other cases, the linker will simply
|
|
ignore @code{PHDRS}.
|
|
|
|
This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
|
|
@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
|
|
|
|
@smallexample
|
|
@group
|
|
PHDRS
|
|
@{
|
|
@var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
|
|
[ FLAGS ( @var{flags} ) ] ;
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @var{name} is used only for reference in the @code{SECTIONS} command
|
|
of the linker script. It is not put into the output file. Program
|
|
header names are stored in a separate name space, and will not conflict
|
|
with symbol names, file names, or section names. Each program header
|
|
must have a distinct name.
|
|
|
|
Certain program header types describe segments of memory which the
|
|
system loader will load from the file. In the linker script, you
|
|
specify the contents of these segments by placing allocatable output
|
|
sections in the segments. You use the @samp{:@var{phdr}} output section
|
|
attribute to place a section in a particular segment. @xref{Output
|
|
Section Phdr}.
|
|
|
|
It is normal to put certain sections in more than one segment. This
|
|
merely implies that one segment of memory contains another. You may
|
|
repeat @samp{:@var{phdr}}, using it once for each segment which should
|
|
contain the section.
|
|
|
|
If you place a section in one or more segments using @samp{:@var{phdr}},
|
|
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. 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
|
|
You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after
|
|
the program header type to further describe the contents of the segment.
|
|
The @code{FILEHDR} keyword means that the segment should include the ELF
|
|
file header. The @code{PHDRS} keyword means that the segment should
|
|
include the ELF program headers themselves.
|
|
|
|
The @var{type} may be one of the following. The numbers indicate the
|
|
value of the keyword.
|
|
|
|
@table @asis
|
|
@item @code{PT_NULL} (0)
|
|
Indicates an unused program header.
|
|
|
|
@item @code{PT_LOAD} (1)
|
|
Indicates that this program header describes a segment to be loaded from
|
|
the file.
|
|
|
|
@item @code{PT_DYNAMIC} (2)
|
|
Indicates a segment where dynamic linking information can be found.
|
|
|
|
@item @code{PT_INTERP} (3)
|
|
Indicates a segment where the name of the program interpreter may be
|
|
found.
|
|
|
|
@item @code{PT_NOTE} (4)
|
|
Indicates a segment holding note information.
|
|
|
|
@item @code{PT_SHLIB} (5)
|
|
A reserved program header type, defined but not specified by the ELF
|
|
ABI.
|
|
|
|
@item @code{PT_PHDR} (6)
|
|
Indicates a segment where the program headers may be found.
|
|
|
|
@item @var{expression}
|
|
An expression giving the numeric type of the program header. This may
|
|
be used for types not defined above.
|
|
@end table
|
|
|
|
You can specify that a segment should be loaded at a particular address
|
|
in memory by using an @code{AT} expression. This is identical to the
|
|
@code{AT} command used as an output section attribute (@pxref{Output
|
|
Section LMA}). The @code{AT} command for a program header overrides the
|
|
output section attribute.
|
|
|
|
The linker will normally set the segment flags based on the sections
|
|
which comprise the segment. You may use the @code{FLAGS} keyword to
|
|
explicitly specify the segment flags. The value of @var{flags} must be
|
|
an integer. It is used to set the @code{p_flags} field of the program
|
|
header.
|
|
|
|
Here is an example of @code{PHDRS}. This shows a typical set of program
|
|
headers used on a native ELF system.
|
|
|
|
@example
|
|
@group
|
|
PHDRS
|
|
@{
|
|
headers PT_PHDR PHDRS ;
|
|
interp PT_INTERP ;
|
|
text PT_LOAD FILEHDR PHDRS ;
|
|
data PT_LOAD ;
|
|
dynamic PT_DYNAMIC ;
|
|
@}
|
|
|
|
SECTIONS
|
|
@{
|
|
. = SIZEOF_HEADERS;
|
|
.interp : @{ *(.interp) @} :text :interp
|
|
.text : @{ *(.text) @} :text
|
|
.rodata : @{ *(.rodata) @} /* defaults to :text */
|
|
@dots{}
|
|
. = . + 0x1000; /* move to a new page in memory */
|
|
.data : @{ *(.data) @} :data
|
|
.dynamic : @{ *(.dynamic) @} :data :dynamic
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
@node VERSION
|
|
@section VERSION Command
|
|
@kindex VERSION @{script text@}
|
|
@cindex symbol versions
|
|
@cindex version script
|
|
@cindex versions of symbols
|
|
The linker supports symbol versions when using ELF. Symbol versions are
|
|
only useful when using shared libraries. The dynamic linker can use
|
|
symbol versions to select a specific version of a function when it runs
|
|
a program that may have been linked against an earlier version of the
|
|
shared library.
|
|
|
|
You can include a version script directly in the main linker script, or
|
|
you can supply the version script as an implicit linker script. You can
|
|
also use the @samp{--version-script} linker option.
|
|
|
|
The syntax of the @code{VERSION} command is simply
|
|
@smallexample
|
|
VERSION @{ version-script-commands @}
|
|
@end smallexample
|
|
|
|
The format of the version script commands is identical to that used by
|
|
Sun's linker in Solaris 2.5. The version script defines a tree of
|
|
version nodes. You specify the node names and interdependencies in the
|
|
version script. You can specify which symbols are bound to which
|
|
version nodes, and you can reduce a specified set of symbols to local
|
|
scope so that they are not globally visible outside of the shared
|
|
library.
|
|
|
|
The easiest way to demonstrate the version script language is with a few
|
|
examples.
|
|
|
|
@smallexample
|
|
VERS_1.1 @{
|
|
global:
|
|
foo1;
|
|
local:
|
|
old*;
|
|
original*;
|
|
new*;
|
|
@};
|
|
|
|
VERS_1.2 @{
|
|
foo2;
|
|
@} VERS_1.1;
|
|
|
|
VERS_2.0 @{
|
|
bar1; bar2;
|
|
@} VERS_1.2;
|
|
@end smallexample
|
|
|
|
This example version script defines three version nodes. The first
|
|
version node defined is @samp{VERS_1.1}; it has no other dependencies.
|
|
The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
|
|
a number of symbols to local scope so that they are not visible outside
|
|
of the shared library; this is done using wildcard patterns, so that any
|
|
symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
|
|
is matched. The wildcard patterns available are the same as those used
|
|
in the shell when matching filenames (also known as ``globbing'').
|
|
|
|
Next, the version script defines node @samp{VERS_1.2}. This node
|
|
depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
|
|
to the version node @samp{VERS_1.2}.
|
|
|
|
Finally, the version script defines node @samp{VERS_2.0}. This node
|
|
depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
|
|
and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
|
|
|
|
When the linker finds a symbol defined in a library which is not
|
|
specifically bound to a version node, it will effectively bind it to an
|
|
unspecified base version of the library. You can bind all otherwise
|
|
unspecified symbols to a given version node by using @samp{global: *;}
|
|
somewhere in the version script.
|
|
|
|
The names of the version nodes have no specific meaning other than what
|
|
they might suggest to the person reading them. The @samp{2.0} version
|
|
could just as well have appeared in between @samp{1.1} and @samp{1.2}.
|
|
However, this would be a confusing way to write a version script.
|
|
|
|
Node name can be omited, provided it is the only version node
|
|
in the version script. Such version script doesn't assign any versions to
|
|
symbols, only selects which symbols will be globally visible out and which
|
|
won't.
|
|
|
|
@smallexample
|
|
@{ global: foo; bar; local: *; @};
|
|
@end smallexample
|
|
|
|
When you link an application against a shared library that has versioned
|
|
symbols, the application itself knows which version of each symbol it
|
|
requires, and it also knows which version nodes it needs from each
|
|
shared library it is linked against. Thus at runtime, the dynamic
|
|
loader can make a quick check to make sure that the libraries you have
|
|
linked against do in fact supply all of the version nodes that the
|
|
application will need to resolve all of the dynamic symbols. In this
|
|
way it is possible for the dynamic linker to know with certainty that
|
|
all external symbols that it needs will be resolvable without having to
|
|
search for each symbol reference.
|
|
|
|
The symbol versioning is in effect a much more sophisticated way of
|
|
doing minor version checking that SunOS does. The fundamental problem
|
|
that is being addressed here is that typically references to external
|
|
functions are bound on an as-needed basis, and are not all bound when
|
|
the application starts up. If a shared library is out of date, a
|
|
required interface may be missing; when the application tries to use
|
|
that interface, it may suddenly and unexpectedly fail. With symbol
|
|
versioning, the user will get a warning when they start their program if
|
|
the libraries being used with the application are too old.
|
|
|
|
There are several GNU extensions to Sun's versioning approach. The
|
|
first of these is the ability to bind a symbol to a version node in the
|
|
source file where the symbol is defined instead of in the versioning
|
|
script. This was done mainly to reduce the burden on the library
|
|
maintainer. You can do this by putting something like:
|
|
@smallexample
|
|
__asm__(".symver original_foo,foo@@VERS_1.1");
|
|
@end smallexample
|
|
@noindent
|
|
in the C source file. This renames the function @samp{original_foo} to
|
|
be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
|
|
The @samp{local:} directive can be used to prevent the symbol
|
|
@samp{original_foo} from being exported. A @samp{.symver} directive
|
|
takes precedence over a version script.
|
|
|
|
The second GNU extension is to allow multiple versions of the same
|
|
function to appear in a given shared library. In this way you can make
|
|
an incompatible change to an interface without increasing the major
|
|
version number of the shared library, while still allowing applications
|
|
linked against the old interface to continue to function.
|
|
|
|
To do this, you must use multiple @samp{.symver} directives in the
|
|
source file. Here is an example:
|
|
|
|
@smallexample
|
|
__asm__(".symver original_foo,foo@@");
|
|
__asm__(".symver old_foo,foo@@VERS_1.1");
|
|
__asm__(".symver old_foo1,foo@@VERS_1.2");
|
|
__asm__(".symver new_foo,foo@@@@VERS_2.0");
|
|
@end smallexample
|
|
|
|
In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
|
|
unspecified base version of the symbol. The source file that contains this
|
|
example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
|
|
@samp{old_foo1}, and @samp{new_foo}.
|
|
|
|
When you have multiple definitions of a given symbol, there needs to be
|
|
some way to specify a default version to which external references to
|
|
this symbol will be bound. You can do this with the
|
|
@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
|
|
declare one version of a symbol as the default in this manner; otherwise
|
|
you would effectively have multiple definitions of the same symbol.
|
|
|
|
If you wish to bind a reference to a specific version of the symbol
|
|
within the shared library, you can use the aliases of convenience
|
|
(i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to
|
|
specifically bind to an external version of the function in question.
|
|
|
|
You can also specify the language in the version script:
|
|
|
|
@smallexample
|
|
VERSION extern "lang" @{ version-script-commands @}
|
|
@end smallexample
|
|
|
|
The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
|
|
The linker will iterate over the list of symbols at the link time and
|
|
demangle them according to @samp{lang} before matching them to the
|
|
patterns specified in @samp{version-script-commands}.
|
|
|
|
@node Expressions
|
|
@section Expressions in Linker Scripts
|
|
@cindex expressions
|
|
@cindex arithmetic
|
|
The syntax for expressions in the linker script language is identical to
|
|
that of C expressions. All expressions are evaluated as integers. All
|
|
expressions are evaluated in the same size, which is 32 bits if both the
|
|
host and target are 32 bits, and is otherwise 64 bits.
|
|
|
|
You can use and set symbol values in expressions.
|
|
|
|
The linker defines several special purpose builtin functions for use in
|
|
expressions.
|
|
|
|
@menu
|
|
* Constants:: Constants
|
|
* Symbols:: Symbol Names
|
|
* Location Counter:: The Location Counter
|
|
* Operators:: Operators
|
|
* Evaluation:: Evaluation
|
|
* Expression Section:: The Section of an Expression
|
|
* Builtin Functions:: Builtin Functions
|
|
@end menu
|
|
|
|
@node Constants
|
|
@subsection Constants
|
|
@cindex integer notation
|
|
@cindex constants in linker scripts
|
|
All constants are integers.
|
|
|
|
As in C, the linker considers an integer beginning with @samp{0} to be
|
|
octal, and an integer beginning with @samp{0x} or @samp{0X} to be
|
|
hexadecimal. The linker considers other integers to be decimal.
|
|
|
|
@cindex scaled integers
|
|
@cindex K and M integer suffixes
|
|
@cindex M and K integer suffixes
|
|
@cindex suffixes for integers
|
|
@cindex integer suffixes
|
|
In addition, you can use the suffixes @code{K} and @code{M} to scale a
|
|
constant by
|
|
@c TEXI2ROFF-KILL
|
|
@ifnottex
|
|
@c END TEXI2ROFF-KILL
|
|
@code{1024} or @code{1024*1024}
|
|
@c TEXI2ROFF-KILL
|
|
@end ifnottex
|
|
@tex
|
|
${\rm 1024}$ or ${\rm 1024}^2$
|
|
@end tex
|
|
@c END TEXI2ROFF-KILL
|
|
respectively. For example, the following all refer to the same quantity:
|
|
@smallexample
|
|
_fourk_1 = 4K;
|
|
_fourk_2 = 4096;
|
|
_fourk_3 = 0x1000;
|
|
@end smallexample
|
|
|
|
@node Symbols
|
|
@subsection Symbol Names
|
|
@cindex symbol names
|
|
@cindex names
|
|
@cindex quoted symbol names
|
|
@kindex "
|
|
Unless quoted, symbol names start with a letter, underscore, or period
|
|
and may include letters, digits, underscores, periods, and hyphens.
|
|
Unquoted symbol names must not conflict with any keywords. You can
|
|
specify a symbol which contains odd characters or has the same name as a
|
|
keyword by surrounding the symbol name in double quotes:
|
|
@smallexample
|
|
"SECTION" = 9;
|
|
"with a space" = "also with a space" + 10;
|
|
@end smallexample
|
|
|
|
Since symbols can contain many non-alphabetic characters, it is safest
|
|
to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
|
|
whereas @samp{A - B} is an expression involving subtraction.
|
|
|
|
@node Location Counter
|
|
@subsection The Location Counter
|
|
@kindex .
|
|
@cindex dot
|
|
@cindex location counter
|
|
@cindex current output location
|
|
The special linker variable @dfn{dot} @samp{.} always contains the
|
|
current output location counter. Since the @code{.} always refers to a
|
|
location in an output section, it may only appear in an expression
|
|
within a @code{SECTIONS} command. The @code{.} symbol may appear
|
|
anywhere that an ordinary symbol is allowed in an expression.
|
|
|
|
@cindex holes
|
|
Assigning a value to @code{.} will cause the location counter to be
|
|
moved. This may be used to create holes in the output section. The
|
|
location counter may never be moved backwards.
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
output :
|
|
@{
|
|
file1(.text)
|
|
. = . + 1000;
|
|
file2(.text)
|
|
. += 1000;
|
|
file3(.text)
|
|
@} = 0x12345678;
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
In the previous example, the @samp{.text} section from @file{file1} is
|
|
located at the beginning of the output section @samp{output}. It is
|
|
followed by a 1000 byte gap. Then the @samp{.text} section from
|
|
@file{file2} appears, also with a 1000 byte gap following before the
|
|
@samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
|
|
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, whose 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
|
|
@cindex operators for arithmetic
|
|
@cindex arithmetic operators
|
|
@cindex precedence in expressions
|
|
The linker recognizes the standard C set of arithmetic operators, with
|
|
the standard bindings and precedence levels:
|
|
@c TEXI2ROFF-KILL
|
|
@ifnottex
|
|
@c END TEXI2ROFF-KILL
|
|
@smallexample
|
|
precedence associativity Operators Notes
|
|
(highest)
|
|
1 left ! - ~ (1)
|
|
2 left * / %
|
|
3 left + -
|
|
4 left >> <<
|
|
5 left == != > < <= >=
|
|
6 left &
|
|
7 left |
|
|
8 left &&
|
|
9 left ||
|
|
10 right ? :
|
|
11 right &= += -= *= /= (2)
|
|
(lowest)
|
|
@end smallexample
|
|
Notes:
|
|
(1) Prefix operators
|
|
(2) @xref{Assignments}.
|
|
@c TEXI2ROFF-KILL
|
|
@end ifnottex
|
|
@tex
|
|
\vskip \baselineskip
|
|
%"lispnarrowing" is the extra indent used generally for smallexample
|
|
\hskip\lispnarrowing\vbox{\offinterlineskip
|
|
\hrule
|
|
\halign
|
|
{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
&Precedence&& Associativity &&{\rm Operators}&\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
\noalign{\hrule}
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
&highest&&&&&\cr
|
|
% '176 is tilde, '~' in tt font
|
|
&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
|
|
&2&&left&&* / \%&\cr
|
|
&3&&left&&+ -&\cr
|
|
&4&&left&&>> <<&\cr
|
|
&5&&left&&== != > < <= >=&\cr
|
|
&6&&left&&\&&\cr
|
|
&7&&left&&|&\cr
|
|
&8&&left&&{\&\&}&\cr
|
|
&9&&left&&||&\cr
|
|
&10&&right&&? :&\cr
|
|
&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
|
|
&lowest&&&&&\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr}
|
|
\hrule}
|
|
@end tex
|
|
@iftex
|
|
{
|
|
@obeylines@parskip=0pt@parindent=0pt
|
|
@dag@quad Prefix operators.
|
|
@ddag@quad @xref{Assignments}.
|
|
}
|
|
@end iftex
|
|
@c END TEXI2ROFF-KILL
|
|
|
|
@node Evaluation
|
|
@subsection Evaluation
|
|
@cindex lazy evaluation
|
|
@cindex expression evaluation order
|
|
The linker evaluates expressions lazily. It only computes the value of
|
|
an expression when absolutely necessary.
|
|
|
|
The linker needs some information, such as the value of the start
|
|
address of the first section, and the origins and lengths of memory
|
|
regions, in order to do any linking at all. These values are computed
|
|
as soon as possible when the linker reads in the linker script.
|
|
|
|
However, other values (such as symbol values) are not known or needed
|
|
until after storage allocation. Such values are evaluated later, when
|
|
other information (such as the sizes of output sections) is available
|
|
for use in the symbol assignment expression.
|
|
|
|
The sizes of sections cannot be known until after allocation, so
|
|
assignments dependent upon these are not performed until after
|
|
allocation.
|
|
|
|
Some expressions, such as those depending upon the location counter
|
|
@samp{.}, must be evaluated during section allocation.
|
|
|
|
If the result of an expression is required, but the value is not
|
|
available, then an error results. For example, a script like the
|
|
following
|
|
@smallexample
|
|
@group
|
|
SECTIONS
|
|
@{
|
|
.text 9+this_isnt_constant :
|
|
@{ *(.text) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
will cause the error message @samp{non constant expression for initial
|
|
address}.
|
|
|
|
@node Expression Section
|
|
@subsection The Section of an Expression
|
|
@cindex expression sections
|
|
@cindex absolute expressions
|
|
@cindex relative expressions
|
|
@cindex absolute and relocatable symbols
|
|
@cindex relocatable and absolute symbols
|
|
@cindex symbols, relocatable and absolute
|
|
When the linker evaluates an expression, the result is either absolute
|
|
or relative to some section. A relative expression is expressed as a
|
|
fixed offset from the base of a section.
|
|
|
|
The position of the expression within the linker script determines
|
|
whether it is absolute or relative. An expression which appears within
|
|
an output section definition is relative to the base of the output
|
|
section. An expression which appears elsewhere will be absolute.
|
|
|
|
A symbol set to a relative expression will be relocatable if you request
|
|
relocatable output using the @samp{-r} option. That means that a
|
|
further link operation may change the value of the symbol. The symbol's
|
|
section will be the section of the relative expression.
|
|
|
|
A symbol set to an absolute expression will retain the same value
|
|
through any further link operation. The symbol will be absolute, and
|
|
will not have any particular associated section.
|
|
|
|
You can use the builtin function @code{ABSOLUTE} to force an expression
|
|
to be absolute when it would otherwise be relative. For example, to
|
|
create an absolute symbol set to the address of the end of the output
|
|
section @samp{.data}:
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
.data : @{ *(.data) _edata = ABSOLUTE(.); @}
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
|
|
@samp{.data} section.
|
|
|
|
@node Builtin Functions
|
|
@subsection Builtin Functions
|
|
@cindex functions in expressions
|
|
The linker script language includes a number of builtin functions for
|
|
use in linker script expressions.
|
|
|
|
@table @code
|
|
@item ABSOLUTE(@var{exp})
|
|
@kindex ABSOLUTE(@var{exp})
|
|
@cindex expression, absolute
|
|
Return the absolute (non-relocatable, as opposed to non-negative) value
|
|
of the expression @var{exp}. Primarily useful to assign an absolute
|
|
value to a symbol within a section definition, where symbol values are
|
|
normally section relative. @xref{Expression Section}.
|
|
|
|
@item ADDR(@var{section})
|
|
@kindex ADDR(@var{section})
|
|
@cindex section address in expression
|
|
Return the absolute address (the VMA) of the named @var{section}. Your
|
|
script must previously have defined the location of that section. In
|
|
the following example, @code{symbol_1} and @code{symbol_2} are assigned
|
|
identical values:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ @dots{}
|
|
.output1 :
|
|
@{
|
|
start_of_output_1 = ABSOLUTE(.);
|
|
@dots{}
|
|
@}
|
|
.output :
|
|
@{
|
|
symbol_1 = ADDR(.output1);
|
|
symbol_2 = start_of_output_1;
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@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
|
|
@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{}
|
|
.data ALIGN(0x2000): @{
|
|
*(.data)
|
|
variable = ALIGN(0x8000);
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
The first use of @code{ALIGN} in this example specifies the location of
|
|
a section because it is used as the optional @var{address} attribute of
|
|
a section definition (@pxref{Output Section Address}). The second use
|
|
of @code{ALIGN} is used to defines the value of a symbol.
|
|
|
|
The builtin function @code{NEXT} is closely related to @code{ALIGN}.
|
|
|
|
@item BLOCK(@var{exp})
|
|
@kindex BLOCK(@var{exp})
|
|
This is a synonym for @code{ALIGN}, for compatibility with older linker
|
|
scripts. It is most often seen when setting the address of an output
|
|
section.
|
|
|
|
@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
|
|
@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
|
|
This is equivalent to either
|
|
@smallexample
|
|
(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
|
|
@end smallexample
|
|
or
|
|
@smallexample
|
|
(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
|
|
@end smallexample
|
|
@noindent
|
|
depending on whether the latter uses fewer @var{commonpagesize} sized pages
|
|
for the data segment (area between the result of this expression and
|
|
@code{DATA_SEGMENT_END}) than the former or not.
|
|
If the latter form is used, it means @var{commonpagesize} bytes of runtime
|
|
memory will be saved at the expense of up to @var{commonpagesize} wasted
|
|
bytes in the on-disk file.
|
|
|
|
This expression can only be used directly in @code{SECTIONS} commands, not in
|
|
any output section descriptions and only once in the linker script.
|
|
@var{commonpagesize} should be less or equal to @var{maxpagesize} and should
|
|
be the system page size the object wants to be optimized for (while still
|
|
working on system page sizes up to @var{maxpagesize}).
|
|
|
|
@noindent
|
|
Example:
|
|
@smallexample
|
|
. = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
|
|
@end smallexample
|
|
|
|
@item DATA_SEGMENT_END(@var{exp})
|
|
@kindex DATA_SEGMENT_END(@var{exp})
|
|
This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
|
|
evaluation purposes.
|
|
|
|
@smallexample
|
|
. = DATA_SEGMENT_END(.);
|
|
@end smallexample
|
|
|
|
@item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
|
|
@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
|
|
This defines the end of the @code{PT_GNU_RELRO} segment when
|
|
@samp{-z relro} option is used. Second argument is returned.
|
|
When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
|
|
does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
|
|
@var{exp} + @var{offset} is aligned to the most commonly used page
|
|
boundary for particular target. If present in the linker script,
|
|
it must always come in between @code{DATA_SEGMENT_ALIGN} and
|
|
@code{DATA_SEGMENT_END}.
|
|
|
|
@smallexample
|
|
. = DATA_SEGMENT_RELRO_END(24, .);
|
|
@end smallexample
|
|
|
|
@item DEFINED(@var{symbol})
|
|
@kindex DEFINED(@var{symbol})
|
|
@cindex symbol defaults
|
|
Return 1 if @var{symbol} is in the linker global symbol table and is
|
|
defined before the statement using DEFINED in the script, otherwise
|
|
return 0. You can use this function to provide
|
|
default values for symbols. For example, the following script fragment
|
|
shows how to set a global symbol @samp{begin} to the first location in
|
|
the @samp{.text} section---but if a symbol called @samp{begin} already
|
|
existed, its value is preserved:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{ @dots{}
|
|
.text : @{
|
|
begin = DEFINED(begin) ? begin : . ;
|
|
@dots{}
|
|
@}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item LENGTH(@var{memory})
|
|
@kindex LENGTH(@var{memory})
|
|
Return the length of the memory region named @var{memory}.
|
|
|
|
@item LOADADDR(@var{section})
|
|
@kindex LOADADDR(@var{section})
|
|
@cindex section load address in expression
|
|
Return the absolute LMA of the named @var{section}. This is normally
|
|
the same as @code{ADDR}, but it may be different if the @code{AT}
|
|
attribute is used in the output section definition (@pxref{Output
|
|
Section LMA}).
|
|
|
|
@kindex MAX
|
|
@item MAX(@var{exp1}, @var{exp2})
|
|
Returns the maximum of @var{exp1} and @var{exp2}.
|
|
|
|
@kindex MIN
|
|
@item MIN(@var{exp1}, @var{exp2})
|
|
Returns the minimum of @var{exp1} and @var{exp2}.
|
|
|
|
@item NEXT(@var{exp})
|
|
@kindex NEXT(@var{exp})
|
|
@cindex unallocated address, next
|
|
Return the next unallocated address that is a multiple of @var{exp}.
|
|
This function is closely related to @code{ALIGN(@var{exp})}; unless you
|
|
use the @code{MEMORY} command to define discontinuous memory for the
|
|
output file, the two functions are equivalent.
|
|
|
|
@item ORIGIN(@var{memory})
|
|
@kindex ORIGIN(@var{memory})
|
|
Return the origin of the memory region named @var{memory}.
|
|
|
|
@item SEGMENT_START(@var{segment}, @var{default})
|
|
@kindex SEGMENT_START(@var{segment}, @var{default})
|
|
Return the base address of the named @var{segment}. If an explicit
|
|
value has been given for this segment (with a command-line @samp{-T}
|
|
option) that value will be returned; otherwise the value will be
|
|
@var{default}. At present, the @samp{-T} command-line option can only
|
|
be used to set the base address for the ``text'', ``data'', and
|
|
``bss'' sections, but you use @code{SEGMENT_START} with any segment
|
|
name.
|
|
|
|
@item SIZEOF(@var{section})
|
|
@kindex SIZEOF(@var{section})
|
|
@cindex section size
|
|
Return the size in bytes of the named @var{section}, if that section has
|
|
been allocated. If the section has not been allocated when this is
|
|
evaluated, the linker will report an error. In the following example,
|
|
@code{symbol_1} and @code{symbol_2} are assigned identical values:
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.output @{
|
|
.start = . ;
|
|
@dots{}
|
|
.end = . ;
|
|
@}
|
|
symbol_1 = .end - .start ;
|
|
symbol_2 = SIZEOF(.output);
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@item SIZEOF_HEADERS
|
|
@itemx sizeof_headers
|
|
@kindex SIZEOF_HEADERS
|
|
@cindex header size
|
|
Return the size in bytes of the output file's headers. This is
|
|
information which appears at the start of the output file. You can use
|
|
this number when setting the start address of the first section, if you
|
|
choose, to facilitate paging.
|
|
|
|
@cindex not enough room for program headers
|
|
@cindex program headers, not enough room
|
|
When producing an ELF output file, if the linker script uses the
|
|
@code{SIZEOF_HEADERS} builtin function, the linker must compute the
|
|
number of program headers before it has determined all the section
|
|
addresses and sizes. If the linker later discovers that it needs
|
|
additional program headers, it will report an error @samp{not enough
|
|
room for program headers}. To avoid this error, you must avoid using
|
|
the @code{SIZEOF_HEADERS} function, or you must rework your linker
|
|
script to avoid forcing the linker to use additional program headers, or
|
|
you must define the program headers yourself using the @code{PHDRS}
|
|
command (@pxref{PHDRS}).
|
|
@end table
|
|
|
|
@node Implicit Linker Scripts
|
|
@section Implicit Linker Scripts
|
|
@cindex implicit linker scripts
|
|
If you specify a linker input file which the linker can not recognize as
|
|
an object file or an archive file, it will try to read the file as a
|
|
linker script. If the file can not be parsed as a linker script, the
|
|
linker will report an error.
|
|
|
|
An implicit linker script will not replace the default linker script.
|
|
|
|
Typically an implicit linker script would contain only symbol
|
|
assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
|
|
commands.
|
|
|
|
Any input files read because of an implicit linker script will be read
|
|
at the position in the command line where the implicit linker script was
|
|
read. This can affect archive searching.
|
|
|
|
@ifset GENERIC
|
|
@node Machine Dependent
|
|
@chapter Machine Dependent Features
|
|
|
|
@cindex machine dependencies
|
|
@command{ld} has additional features on some platforms; the following
|
|
sections describe them. Machines where @command{ld} has no additional
|
|
functionality are not listed.
|
|
|
|
@menu
|
|
@ifset H8300
|
|
* H8/300:: @command{ld} and the H8/300
|
|
@end ifset
|
|
@ifset I960
|
|
* i960:: @command{ld} and the Intel 960 family
|
|
@end ifset
|
|
@ifset ARM
|
|
* ARM:: @command{ld} and the ARM family
|
|
@end ifset
|
|
@ifset HPPA
|
|
* HPPA ELF32:: @command{ld} and HPPA 32-bit ELF
|
|
@end ifset
|
|
@ifset MMIX
|
|
* MMIX:: @command{ld} and MMIX
|
|
@end ifset
|
|
@ifset MSP430
|
|
* MSP430:: @command{ld} and MSP430
|
|
@end ifset
|
|
@ifset M68HC11
|
|
* M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families
|
|
@end ifset
|
|
@ifset TICOFF
|
|
* TI COFF:: @command{ld} and TI COFF
|
|
@end ifset
|
|
@ifset WIN32
|
|
* WIN32:: @command{ld} and WIN32 (cygwin/mingw)
|
|
@end ifset
|
|
@ifset XTENSA
|
|
* Xtensa:: @command{ld} and Xtensa Processors
|
|
@end ifset
|
|
@end menu
|
|
@end ifset
|
|
|
|
@ifset H8300
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node H8/300
|
|
@section @command{ld} and the H8/300
|
|
|
|
@cindex H8/300 support
|
|
For the H8/300, @command{ld} can perform these global optimizations when
|
|
you specify the @samp{--relax} command-line option.
|
|
|
|
@table @emph
|
|
@cindex relaxing on H8/300
|
|
@item relaxing address modes
|
|
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
|
|
targets are within eight bits, and turns them into eight-bit
|
|
program-counter relative @code{bsr} and @code{bra} instructions,
|
|
respectively.
|
|
|
|
@cindex synthesizing on H8/300
|
|
@item synthesizing instructions
|
|
@c FIXME: specifically mov.b, or any mov instructions really?
|
|
@command{ld} finds all @code{mov.b} instructions which use the
|
|
sixteen-bit absolute address form, but refer to the top
|
|
page of memory, and changes them to use the eight-bit address form.
|
|
(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
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear GENERIC
|
|
@ifset Renesas
|
|
@c This stuff is pointless to say unless you're especially concerned
|
|
@c with Renesas chips; don't enable it for generic case, please.
|
|
@node Renesas
|
|
@chapter @command{ld} and Other Renesas Chips
|
|
|
|
@command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
|
|
H8/500, and SH chips. No special features, commands, or command-line
|
|
options are required for these chips.
|
|
@end ifset
|
|
@end ifclear
|
|
|
|
@ifset I960
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node i960
|
|
@section @command{ld} and the Intel 960 Family
|
|
|
|
@cindex i960 support
|
|
|
|
You can use the @samp{-A@var{architecture}} command line option to
|
|
specify one of the two-letter names identifying members of the 960
|
|
family; the option specifies the desired output target, and warns of any
|
|
incompatible instructions in the input files. It also modifies the
|
|
linker's search strategy for archive libraries, to support the use of
|
|
libraries specific to each particular architecture, by including in the
|
|
search loop names suffixed with the string identifying the architecture.
|
|
|
|
For example, if your @command{ld} command line included @w{@samp{-ACA}} as
|
|
well as @w{@samp{-ltry}}, the linker would look (in its built-in search
|
|
paths, and in any paths you specify with @samp{-L}) for a library with
|
|
the names
|
|
|
|
@smallexample
|
|
@group
|
|
try
|
|
libtry.a
|
|
tryca
|
|
libtryca.a
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The first two possibilities would be considered in any event; the last
|
|
two are due to the use of @w{@samp{-ACA}}.
|
|
|
|
You can meaningfully use @samp{-A} more than once on a command line, since
|
|
the 960 architecture family allows combination of target architectures; each
|
|
use will add another pair of name variants to search for when @w{@samp{-l}}
|
|
specifies a library.
|
|
|
|
@cindex @option{--relax} on i960
|
|
@cindex relaxing on i960
|
|
@command{ld} supports the @samp{--relax} option for the i960 family. If
|
|
you specify @samp{--relax}, @command{ld} finds all @code{balx} and
|
|
@code{calx} instructions whose targets are within 24 bits, and turns
|
|
them into 24-bit program-counter relative @code{bal} and @code{cal}
|
|
instructions, respectively. @command{ld} also turns @code{cal}
|
|
instructions into @code{bal} instructions when it determines that the
|
|
target subroutine is a leaf routine (that is, the target subroutine does
|
|
not itself call any subroutines).
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset ARM
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@ifset M68HC11
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node M68HC11/68HC12
|
|
@section @command{ld} and the Motorola 68HC11 and 68HC12 families
|
|
|
|
@cindex M68HC11 and 68HC12 support
|
|
|
|
@subsection Linker Relaxation
|
|
|
|
For the Motorola 68HC11, @command{ld} can perform these global
|
|
optimizations when you specify the @samp{--relax} command-line option.
|
|
|
|
@table @emph
|
|
@cindex relaxing on M68HC11
|
|
@item relaxing address modes
|
|
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
|
|
targets are within eight bits, and turns them into eight-bit
|
|
program-counter relative @code{bsr} and @code{bra} instructions,
|
|
respectively.
|
|
|
|
@command{ld} also looks at all 16-bit extended addressing modes and
|
|
transforms them in a direct addressing mode when the address is in
|
|
page 0 (between 0 and 0x0ff).
|
|
|
|
@item relaxing gcc instruction group
|
|
When @command{gcc} is called with @option{-mrelax}, it can emit group
|
|
of instructions that the linker can optimize to use a 68HC11 direct
|
|
addressing mode. These instructions consists of @code{bclr} or
|
|
@code{bset} instructions.
|
|
|
|
@end table
|
|
|
|
@subsection Trampoline Generation
|
|
|
|
@cindex trampoline generation on M68HC11
|
|
@cindex trampoline generation on M68HC12
|
|
For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
|
|
call a far function using a normal @code{jsr} instruction. The linker
|
|
will also change the relocation to some far function to use the
|
|
trampoline address instead of the function address. This is typically the
|
|
case when a pointer to a function is taken. The pointer will in fact
|
|
point to the function trampoline.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@node ARM
|
|
@section @command{ld} and the ARM family
|
|
|
|
@cindex ARM interworking support
|
|
@kindex --support-old-code
|
|
For the ARM, @command{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.
|
|
|
|
@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.
|
|
|
|
@cindex TARGET1
|
|
@kindex --target1-rel
|
|
@kindex --target1-abs
|
|
The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
|
|
@samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32}
|
|
or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel}
|
|
and @samp{--target1-abs} switches override the default.
|
|
|
|
@cindex TARGET2
|
|
@kindex --target2=@var{type}
|
|
The @samp{--target2=type} switch overrides the default definition of the
|
|
@samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their
|
|
meanings, and target defaults are as follows:
|
|
@table @samp
|
|
@item rel
|
|
@samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
|
|
@item abs
|
|
@samp{R_ARM_ABS32} (arm*-*-symbianelf)
|
|
@item got-rel
|
|
@samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset HPPA
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node HPPA ELF32
|
|
@section @command{ld} and HPPA 32-bit ELF Support
|
|
@cindex HPPA multiple sub-space stubs
|
|
@kindex --multi-subspace
|
|
When generating a shared library, @command{ld} will by default generate
|
|
import stubs suitable for use with a single sub-space application.
|
|
The @samp{--multi-subspace} switch causes @command{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 @command{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
|
|
@command{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.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset MMIX
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node MMIX
|
|
@section @code{ld} and MMIX
|
|
For MMIX, there is a choice of generating @code{ELF} object files or
|
|
@code{mmo} object files when linking. The simulator @code{mmix}
|
|
understands the @code{mmo} format. The binutils @code{objcopy} utility
|
|
can translate between the two formats.
|
|
|
|
There is one special section, the @samp{.MMIX.reg_contents} section.
|
|
Contents in this section is assumed to correspond to that of global
|
|
registers, and symbols referring to it are translated to special symbols,
|
|
equal to registers. In a final link, the start address of the
|
|
@samp{.MMIX.reg_contents} section corresponds to the first allocated
|
|
global register multiplied by 8. Register @code{$255} is not included in
|
|
this section; it is always set to the program entry, which is at the
|
|
symbol @code{Main} for @code{mmo} files.
|
|
|
|
Symbols with the prefix @code{__.MMIX.start.}, for example
|
|
@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special;
|
|
there must be only one each, even if they are local. The default linker
|
|
script uses these to set the default start address of a section.
|
|
|
|
Initial and trailing multiples of zero-valued 32-bit words in a section,
|
|
are left out from an mmo file.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset MSP430
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node MSP430
|
|
@section @code{ld} and MSP430
|
|
For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]}
|
|
will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
|
|
just pass @samp{-m help} option to the linker).
|
|
|
|
@cindex MSP430 extra sections
|
|
The linker will recognize some extra sections which are MSP430 specific:
|
|
|
|
@table @code
|
|
@item @samp{.vectors}
|
|
Defines a portion of ROM where interrupt vectors located.
|
|
|
|
@item @samp{.bootloader}
|
|
Defines the bootloader portion of the ROM (if applicable). Any code
|
|
in this section will be uploaded to the MPU.
|
|
|
|
@item @samp{.infomem}
|
|
Defines an information memory section (if applicable). Any code in
|
|
this section will be uploaded to the MPU.
|
|
|
|
@item @samp{.infomemnobits}
|
|
This is the same as the @samp{.infomem} section except that any code
|
|
in this section will not be uploaded to the MPU.
|
|
|
|
@item @samp{.noinit}
|
|
Denotes a portion of RAM located above @samp{.bss} section.
|
|
|
|
The last two sections are used by gcc.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset TICOFF
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node TI COFF
|
|
@section @command{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; @command{ld} will read any version or byte order, but the output
|
|
header format depends on the default specified by the specific target.
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset WIN32
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node WIN32
|
|
@section @command{ld} and WIN32 (cygwin/mingw)
|
|
|
|
This section describes some of the win32 specific @command{ld} issues.
|
|
See @ref{Options,,Command Line Options} for detailed decription of the
|
|
command line options mentioned here.
|
|
|
|
@table @emph
|
|
@cindex import libraries
|
|
@item import libraries
|
|
The standard Windows linker creates and uses so-called import
|
|
libraries, which contains information for linking to dll's. They are
|
|
regular static archives and are handled as any other static
|
|
archive. The cygwin and mingw ports of @command{ld} have specific
|
|
support for creating such libraries provided with the
|
|
@samp{--out-implib} command line option.
|
|
|
|
@item exporting DLL symbols
|
|
@cindex exporting DLL symbols
|
|
The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
|
|
|
|
@table @emph
|
|
@item using auto-export functionality
|
|
@cindex using auto-export functionality
|
|
By default @command{ld} exports symbols with the auto-export functionality,
|
|
which is controlled by the following command line options:
|
|
|
|
@itemize
|
|
@item --export-all-symbols [This is the default]
|
|
@item --exclude-symbols
|
|
@item --exclude-libs
|
|
@end itemize
|
|
|
|
If, however, @samp{--export-all-symbols} is not given explicitly on the
|
|
command line, then the default auto-export behavior will be @emph{disabled}
|
|
if either of the following are true:
|
|
|
|
@itemize
|
|
@item A DEF file is used.
|
|
@item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
|
|
@end itemize
|
|
|
|
@item using a DEF file
|
|
@cindex using a DEF file
|
|
Another way of exporting symbols is using a DEF file. A DEF file is
|
|
an ASCII file containing definitions of symbols which should be
|
|
exported when a dll is created. Usually it is named @samp{<dll
|
|
name>.def} and is added as any other object file to the linker's
|
|
command line. The file's name must end in @samp{.def} or @samp{.DEF}.
|
|
|
|
@example
|
|
gcc -o <output> <objectfiles> <dll name>.def
|
|
@end example
|
|
|
|
Using a DEF file turns off the normal auto-export behavior, unless the
|
|
@samp{--export-all-symbols} option is also used.
|
|
|
|
Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
|
|
|
|
@example
|
|
LIBRARY "xyz.dll" BASE=0x10000000
|
|
|
|
EXPORTS
|
|
foo
|
|
bar
|
|
_bar = bar
|
|
@end example
|
|
|
|
This example defines a base address and three symbols. The third
|
|
symbol is an alias for the second. For the complete format
|
|
specification see ld/deffilep.y in the binutils sources.
|
|
|
|
@cindex creating a DEF file
|
|
While linking a shared dll, @command{ld} is able to create a DEF file
|
|
with the @samp{--output-def <file>} command line option.
|
|
|
|
@item Using decorations
|
|
@cindex Using decorations
|
|
Another way of marking symbols for export is to modify the source code
|
|
itself, so that when building the DLL each symbol to be exported is
|
|
declared as:
|
|
|
|
@example
|
|
__declspec(dllexport) int a_variable
|
|
__declspec(dllexport) void a_function(int with_args)
|
|
@end example
|
|
|
|
All such symbols will be exported from the DLL. If, however,
|
|
any of the object files in the DLL contain symbols decorated in
|
|
this way, then the normal auto-export behavior is disabled, unless
|
|
the @samp{--export-all-symbols} option is also used.
|
|
|
|
Note that object files that wish to access these symbols must @emph{not}
|
|
decorate them with dllexport. Instead, they should use dllimport,
|
|
instead:
|
|
|
|
@example
|
|
__declspec(dllimport) int a_variable
|
|
__declspec(dllimport) void a_function(int with_args)
|
|
@end example
|
|
|
|
This complicates the structure of library header files, because
|
|
when included by the library itself the header must declare the
|
|
variables and functions as dllexport, but when included by client
|
|
code the header must declare them as dllimport. There are a number
|
|
of idioms that are typically used to do this; often client code can
|
|
omit the __declspec() declaration completely. See
|
|
@samp{--enable-auto-import} and @samp{automatic data imports} for more
|
|
imformation.
|
|
@end table
|
|
|
|
@cindex automatic data imports
|
|
@item automatic data imports
|
|
The standard Windows dll format supports data imports from dlls only
|
|
by adding special decorations (dllimport/dllexport), which let the
|
|
compiler produce specific assembler instructions to deal with this
|
|
issue. This increases the effort necessary to port existing Un*x
|
|
code to these platforms, especially for large
|
|
c++ libraries and applications. The auto-import feature, which was
|
|
initially provided by Paul Sokolovsky, allows one to omit the
|
|
decorations to archieve a behavior that conforms to that on POSIX/Un*x
|
|
platforms. This feature is enabled with the @samp{--enable-auto-import}
|
|
command-line option, although it is enabled by default on cygwin/mingw.
|
|
The @samp{--enable-auto-import} option itself now serves mainly to
|
|
suppress any warnings that are ordinarily emitted when linked objects
|
|
trigger the feature's use.
|
|
|
|
auto-import of variables does not always work flawlessly without
|
|
additional assistance. Sometimes, you will see this message
|
|
|
|
"variable '<var>' can't be auto-imported. Please read the
|
|
documentation for ld's @code{--enable-auto-import} for details."
|
|
|
|
The @samp{--enable-auto-import} documentation explains why this error
|
|
occurs, and several methods that can be used to overcome this difficulty.
|
|
One of these methods is the @emph{runtime pseudo-relocs} feature, described
|
|
below.
|
|
|
|
@cindex runtime pseudo-relocation
|
|
For complex variables imported from DLLs (such as structs or classes),
|
|
object files typically contain a base address for the variable and an
|
|
offset (@emph{addend}) within the variable--to specify a particular
|
|
field or public member, for instance. Unfortunately, the runtime loader used
|
|
in win32 environments is incapable of fixing these references at runtime
|
|
without the additional information supplied by dllimport/dllexport decorations.
|
|
The standard auto-import feature described above is unable to resolve these
|
|
references.
|
|
|
|
The @samp{--enable-runtime-pseudo-relocs} switch allows these references to
|
|
be resolved without error, while leaving the task of adjusting the references
|
|
themselves (with their non-zero addends) to specialized code provided by the
|
|
runtime environment. Recent versions of the cygwin and mingw environments and
|
|
compilers provide this runtime support; older versions do not. However, the
|
|
support is only necessary on the developer's platform; the compiled result will
|
|
run without error on an older system.
|
|
|
|
@samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
|
|
enabled as needed.
|
|
|
|
@cindex direct linking to a dll
|
|
@item direct linking to a dll
|
|
The cygwin/mingw ports of @command{ld} support the direct linking,
|
|
including data symbols, to a dll without the usage of any import
|
|
libraries. This is much faster and uses much less memory than does the
|
|
traditional import library method, expecially when linking large
|
|
libraries or applications. When @command{ld} creates an import lib, each
|
|
function or variable exported from the dll is stored in its own bfd, even
|
|
though a single bfd could contain many exports. The overhead involved in
|
|
storing, loading, and processing so many bfd's is quite large, and explains the
|
|
tremendous time, memory, and storage needed to link against particularly
|
|
large or complex libraries when using import libs.
|
|
|
|
Linking directly to a dll uses no extra command-line switches other than
|
|
@samp{-L} and @samp{-l}, because @command{ld} already searches for a number
|
|
of names to match each library. All that is needed from the developer's
|
|
perspective is an understanding of this search, in order to force ld to
|
|
select the dll instead of an import library.
|
|
|
|
|
|
For instance, when ld is called with the argument @samp{-lxxx} it will attempt
|
|
to find, in the first directory of its search path,
|
|
|
|
@example
|
|
libxxx.dll.a
|
|
xxx.dll.a
|
|
libxxx.a
|
|
cygxxx.dll (*)
|
|
libxxx.dll
|
|
xxx.dll
|
|
@end example
|
|
|
|
before moving on to the next directory in the search path.
|
|
|
|
(*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
|
|
where @samp{<prefix>} is set by the @command{ld} option
|
|
@samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
|
|
file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
|
|
@samp{cygxxx.dll}.
|
|
|
|
Other win32-based unix environments, such as mingw or pw32, may use other
|
|
@samp{<prefix>}es, although at present only cygwin makes use of this feature. It
|
|
was originally intended to help avoid name conflicts among dll's built for the
|
|
various win32/un*x environments, so that (for example) two versions of a zlib dll
|
|
could coexist on the same machine.
|
|
|
|
The generic cygwin/mingw path layout uses a @samp{bin} directory for
|
|
applications and dll's and a @samp{lib} directory for the import
|
|
libraries (using cygwin nomenclature):
|
|
|
|
@example
|
|
bin/
|
|
cygxxx.dll
|
|
lib/
|
|
libxxx.dll.a (in case of dll's)
|
|
libxxx.a (in case of static archive)
|
|
@end example
|
|
|
|
Linking directly to a dll without using the import library can be
|
|
done two ways:
|
|
|
|
1. Use the dll directly by adding the @samp{bin} path to the link line
|
|
@example
|
|
gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
|
|
@end example
|
|
|
|
However, as the dll's often have version numbers appended to their names
|
|
(@samp{cygncurses-5.dll}) this will often fail, unless one specifies
|
|
@samp{-L../bin -lncurses-5} to include the version. Import libs are generally
|
|
not versioned, and do not have this difficulty.
|
|
|
|
2. Create a symbolic link from the dll to a file in the @samp{lib}
|
|
directory according to the above mentioned search pattern. This
|
|
should be used to avoid unwanted changes in the tools needed for
|
|
making the app/dll.
|
|
|
|
@example
|
|
ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
|
|
@end example
|
|
|
|
Then you can link without any make environment changes.
|
|
|
|
@example
|
|
gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
|
|
@end example
|
|
|
|
This technique also avoids the version number problems, because the following is
|
|
perfectly legal
|
|
|
|
@example
|
|
bin/
|
|
cygxxx-5.dll
|
|
lib/
|
|
libxxx.dll.a -> ../bin/cygxxx-5.dll
|
|
@end example
|
|
|
|
Linking directly to a dll without using an import lib will work
|
|
even when auto-import features are exercised, and even when
|
|
@samp{--enable-runtime-pseudo-relocs} is used.
|
|
|
|
Given the improvements in speed and memory usage, one might justifiably
|
|
wonder why import libraries are used at all. There are two reasons:
|
|
|
|
1. Until recently, the link-directly-to-dll functionality did @emph{not}
|
|
work with auto-imported data.
|
|
|
|
2. Sometimes it is necessary to include pure static objects within the
|
|
import library (which otherwise contains only bfd's for indirection
|
|
symbols that point to the exports of a dll). Again, the import lib
|
|
for the cygwin kernel makes use of this ability, and it is not
|
|
possible to do this without an import lib.
|
|
|
|
So, import libs are not going away. But the ability to replace
|
|
true import libs with a simple symbolic link to (or a copy of)
|
|
a dll, in most cases, is a useful addition to the suite of tools
|
|
binutils makes available to the win32 developer. Given the
|
|
massive improvements in memory requirements during linking, storage
|
|
requirements, and linking speed, we expect that many developers
|
|
will soon begin to use this feature whenever possible.
|
|
|
|
@item symbol aliasing
|
|
@table @emph
|
|
@item adding additional names
|
|
Sometimes, it is useful to export symbols with additional names.
|
|
A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
|
|
exported as @samp{_foo} by using special directives in the DEF file
|
|
when creating the dll. This will affect also the optional created
|
|
import library. Consider the following DEF file:
|
|
|
|
@example
|
|
LIBRARY "xyz.dll" BASE=0x61000000
|
|
|
|
EXPORTS
|
|
foo
|
|
_foo = foo
|
|
@end example
|
|
|
|
The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
|
|
|
|
Another method for creating a symbol alias is to create it in the
|
|
source code using the "weak" attribute:
|
|
|
|
@example
|
|
void foo () @{ /* Do something. */; @}
|
|
void _foo () __attribute__ ((weak, alias ("foo")));
|
|
@end example
|
|
|
|
See the gcc manual for more information about attributes and weak
|
|
symbols.
|
|
|
|
@item renaming symbols
|
|
Sometimes it is useful to rename exports. For instance, the cygwin
|
|
kernel does this regularly. A symbol @samp{_foo} can be exported as
|
|
@samp{foo} but not as @samp{_foo} by using special directives in the
|
|
DEF file. (This will also affect the import library, if it is
|
|
created). In the following example:
|
|
|
|
@example
|
|
LIBRARY "xyz.dll" BASE=0x61000000
|
|
|
|
EXPORTS
|
|
_foo = foo
|
|
@end example
|
|
|
|
The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
|
|
@samp{_foo}.
|
|
@end table
|
|
|
|
Note: using a DEF file disables the default auto-export behavior,
|
|
unless the @samp{--export-all-symbols} command line option is used.
|
|
If, however, you are trying to rename symbols, then you should list
|
|
@emph{all} desired exports in the DEF file, including the symbols
|
|
that are not being renamed, and do @emph{not} use the
|
|
@samp{--export-all-symbols} option. If you list only the
|
|
renamed symbols in the DEF file, and use @samp{--export-all-symbols}
|
|
to handle the other symbols, then the both the new names @emph{and}
|
|
the original names for the renamed symbols will be exported.
|
|
In effect, you'd be aliasing those symbols, not renaming them,
|
|
which is probably not what you wanted.
|
|
|
|
@cindex weak externals
|
|
@item weak externals
|
|
The Windows object format, PE, specifies a form of weak symbols called
|
|
weak externals. When a weak symbol is linked and the symbol is not
|
|
defined, the weak symbol becomes an alias for some other symbol. There
|
|
are three variants of weak externals:
|
|
@itemize
|
|
@item Definition is searched for in objects and libraries, historically
|
|
called lazy externals.
|
|
@item Definition is searched for only in other objects, not in libraries.
|
|
This form is not presently implemented.
|
|
@item No search; the symbol is an alias. This form is not presently
|
|
implemented.
|
|
@end itemize
|
|
As a GNU extension, weak symbols that do not specify an alternate symbol
|
|
are supported. If the symbol is undefined when linking, the symbol
|
|
uses a default value.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifset XTENSA
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
|
|
@node Xtensa
|
|
@section @code{ld} and Xtensa Processors
|
|
|
|
@cindex Xtensa processors
|
|
The default @command{ld} behavior for Xtensa processors is to interpret
|
|
@code{SECTIONS} commands so that lists of explicitly named sections in a
|
|
specification with a wildcard file will be interleaved when necessary to
|
|
keep literal pools within the range of PC-relative load offsets. For
|
|
example, with the command:
|
|
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
.text : @{
|
|
*(.literal .text)
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@command{ld} may interleave some of the @code{.literal}
|
|
and @code{.text} sections from different object files to ensure that the
|
|
literal pools are within the range of PC-relative load offsets. A valid
|
|
interleaving might place the @code{.literal} sections from an initial
|
|
group of files followed by the @code{.text} sections of that group of
|
|
files. Then, the @code{.literal} sections from the rest of the files
|
|
and the @code{.text} sections from the rest of the files would follow.
|
|
|
|
@cindex @option{--relax} on Xtensa
|
|
@cindex relaxing on Xtensa
|
|
Relaxation is enabled by default for the Xtensa version of @command{ld} and
|
|
provides two important link-time optimizations. The first optimization
|
|
is to combine identical literal values to reduce code size. A redundant
|
|
literal will be removed and all the @code{L32R} instructions that use it
|
|
will be changed to reference an identical literal, as long as the
|
|
location of the replacement literal is within the offset range of all
|
|
the @code{L32R} instructions. The second optimization is to remove
|
|
unnecessary overhead from assembler-generated ``longcall'' sequences of
|
|
@code{L32R}/@code{CALLX@var{n}} when the target functions are within
|
|
range of direct @code{CALL@var{n}} instructions.
|
|
|
|
For each of these cases where an indirect call sequence can be optimized
|
|
to a direct call, the linker will change the @code{CALLX@var{n}}
|
|
instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
|
|
instruction, and remove the literal referenced by the @code{L32R}
|
|
instruction if it is not used for anything else. Removing the
|
|
@code{L32R} instruction always reduces code size but can potentially
|
|
hurt performance by changing the alignment of subsequent branch targets.
|
|
By default, the linker will always preserve alignments, either by
|
|
switching some instructions between 24-bit encodings and the equivalent
|
|
density instructions or by inserting a no-op in place of the @code{L32R}
|
|
instruction that was removed. If code size is more important than
|
|
performance, the @option{--size-opt} option can be used to prevent the
|
|
linker from widening density instructions or inserting no-ops, except in
|
|
a few cases where no-ops are required for correctness.
|
|
|
|
The following Xtensa-specific command-line options can be used to
|
|
control the linker:
|
|
|
|
@cindex Xtensa options
|
|
@table @option
|
|
@kindex --no-relax
|
|
@item --no-relax
|
|
Since the Xtensa version of @code{ld} enables the @option{--relax} option
|
|
by default, the @option{--no-relax} option is provided to disable
|
|
relaxation.
|
|
|
|
@item --size-opt
|
|
When optimizing indirect calls to direct calls, optimize for code size
|
|
more than performance. With this option, the linker will not insert
|
|
no-ops or widen density instructions to preserve branch target
|
|
alignment. There may still be some cases where no-ops are required to
|
|
preserve the correctness of the code.
|
|
@end table
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear SingleFormat
|
|
@node BFD
|
|
@chapter BFD
|
|
|
|
@cindex back end
|
|
@cindex object file management
|
|
@cindex object formats available
|
|
@kindex objdump -i
|
|
The linker accesses object and archive files using the BFD libraries.
|
|
These libraries allow the linker to use the same routines to operate on
|
|
object files whatever the object file format. A different object file
|
|
format can be supported simply by creating a new BFD back end and adding
|
|
it to the library. To conserve runtime memory, however, the linker and
|
|
associated tools are usually configured to support only a subset of the
|
|
object file formats available. You can use @code{objdump -i}
|
|
(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
|
|
list all the formats available for your configuration.
|
|
|
|
@cindex BFD requirements
|
|
@cindex requirements for BFD
|
|
As with most implementations, BFD is a compromise between
|
|
several conflicting requirements. The major factor influencing
|
|
BFD design was efficiency: any time used converting between
|
|
formats is time which would not have been spent had BFD not
|
|
been involved. This is partly offset by abstraction payback; since
|
|
BFD simplifies applications and back ends, more time and care
|
|
may be spent optimizing algorithms for a greater speed.
|
|
|
|
One minor artifact of the BFD solution which you should bear in
|
|
mind is the potential for information loss. There are two places where
|
|
useful information can be lost using the BFD mechanism: during
|
|
conversion and during output. @xref{BFD information loss}.
|
|
|
|
@menu
|
|
* BFD outline:: How it works: an outline of BFD
|
|
@end menu
|
|
|
|
@node BFD outline
|
|
@section How It Works: An Outline of BFD
|
|
@cindex opening object files
|
|
@include bfdsumm.texi
|
|
@end ifclear
|
|
|
|
@node Reporting Bugs
|
|
@chapter Reporting Bugs
|
|
@cindex bugs in @command{ld}
|
|
@cindex reporting bugs in @command{ld}
|
|
|
|
Your bug reports play an essential role in making @command{ld} reliable.
|
|
|
|
Reporting a bug may help you by bringing a solution to your problem, or
|
|
it may not. But in any case the principal function of a bug report is
|
|
to help the entire community by making the next version of @command{ld}
|
|
work better. Bug reports are your contribution to the maintenance of
|
|
@command{ld}.
|
|
|
|
In order for a bug report to serve its purpose, you must include the
|
|
information that enables us to fix the bug.
|
|
|
|
@menu
|
|
* Bug Criteria:: Have you found a bug?
|
|
* Bug Reporting:: How to report bugs
|
|
@end menu
|
|
|
|
@node Bug Criteria
|
|
@section Have You Found a Bug?
|
|
@cindex bug criteria
|
|
|
|
If you are not sure whether you have found a bug, here are some guidelines:
|
|
|
|
@itemize @bullet
|
|
@cindex fatal signal
|
|
@cindex linker crash
|
|
@cindex crash of linker
|
|
@item
|
|
If the linker gets a fatal signal, for any input whatever, that is a
|
|
@command{ld} bug. Reliable linkers never crash.
|
|
|
|
@cindex error on valid input
|
|
@item
|
|
If @command{ld} produces an error message for valid input, that is a bug.
|
|
|
|
@cindex invalid input
|
|
@item
|
|
If @command{ld} does not produce an error message for invalid input, that
|
|
may be a bug. In the general case, the linker can not verify that
|
|
object files are correct.
|
|
|
|
@item
|
|
If you are an experienced user of linkers, your suggestions for
|
|
improvement of @command{ld} are welcome in any case.
|
|
@end itemize
|
|
|
|
@node Bug Reporting
|
|
@section How to Report Bugs
|
|
@cindex bug reports
|
|
@cindex @command{ld} bugs, reporting
|
|
|
|
A number of companies and individuals offer support for @sc{gnu}
|
|
products. If you obtained @command{ld} from a support organization, we
|
|
recommend you contact that organization first.
|
|
|
|
You can find contact information for many support companies and
|
|
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
|
|
distribution.
|
|
|
|
Otherwise, send bug reports for @command{ld} to
|
|
@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
|
|
fact or leave it out, state it!
|
|
|
|
Often people omit facts because they think they know what causes the
|
|
problem and assume that some details do not matter. Thus, you might
|
|
assume that the name of a symbol you use in an example does not
|
|
matter. Well, probably it does not, but one cannot be sure. Perhaps
|
|
the bug is a stray memory reference which happens to fetch from the
|
|
location where that name is stored in memory; perhaps, if the name
|
|
were different, the contents of that location would fool the linker
|
|
into doing the right thing despite the bug. Play it safe and give a
|
|
specific, complete example. That is the easiest thing for you to do,
|
|
and the most helpful.
|
|
|
|
Keep in mind that the purpose of a bug report is to enable us to fix
|
|
the bug if it is new to us. Therefore, always write your bug reports
|
|
on the assumption that the bug has not been reported previously.
|
|
|
|
Sometimes people give a few sketchy facts and ask, ``Does this ring a
|
|
bell?'' This cannot help us fix a bug, so it is basically useless. We
|
|
respond by asking for enough details to enable us to investigate.
|
|
You might as well expedite matters by sending them to begin with.
|
|
|
|
To enable us to fix the bug, you should include all these things:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The version of @command{ld}. @command{ld} announces it if you start it with
|
|
the @samp{--version} argument.
|
|
|
|
Without this, we will not know whether there is any point in looking for
|
|
the bug in the current version of @command{ld}.
|
|
|
|
@item
|
|
Any patches you may have applied to the @command{ld} source, including any
|
|
patches made to the @code{BFD} library.
|
|
|
|
@item
|
|
The type of machine you are using, and the operating system name and
|
|
version number.
|
|
|
|
@item
|
|
What compiler (and its version) was used to compile @command{ld}---e.g.
|
|
``@code{gcc-2.7}''.
|
|
|
|
@item
|
|
The command arguments you gave the linker to link your example and
|
|
observe the bug. To guarantee you will not omit something important,
|
|
list them all. A copy of the Makefile (or the output from make) is
|
|
sufficient.
|
|
|
|
If we were to try to guess the arguments, we would probably guess wrong
|
|
and then we might not encounter the bug.
|
|
|
|
@item
|
|
A complete input file, or set of input files, that will reproduce the
|
|
bug. It is generally most helpful to send the actual object files
|
|
provided that they are reasonably small. Say no more than 10K. For
|
|
bigger files you can either make them available by FTP or HTTP or else
|
|
state that you are willing to send the object file(s) to whomever
|
|
requests them. (Note - your email will be going to a mailing list, so
|
|
we do not want to clog it up with large attachments). But small
|
|
attachments are best.
|
|
|
|
If the source files were assembled using @code{gas} or compiled using
|
|
@code{gcc}, then it may be OK to send the source files rather than the
|
|
object files. In this case, be sure to say exactly what version of
|
|
@code{gas} or @code{gcc} was used to produce the object files. Also say
|
|
how @code{gas} or @code{gcc} were configured.
|
|
|
|
@item
|
|
A description of what behavior you observe that you believe is
|
|
incorrect. For example, ``It gets a fatal signal.''
|
|
|
|
Of course, if the bug is that @command{ld} gets a fatal signal, then we
|
|
will certainly notice it. But if the bug is incorrect output, we might
|
|
not notice unless it is glaringly wrong. You might as well not give us
|
|
a chance to make a mistake.
|
|
|
|
Even if the problem you experience is a fatal signal, you should still
|
|
say so explicitly. Suppose something strange is going on, such as, your
|
|
copy of @command{ld} is out of synch, or you have encountered a bug in the
|
|
C library on your system. (This has happened!) Your copy might crash
|
|
and ours would not. If you told us to expect a crash, then when ours
|
|
fails to crash, we would know that the bug was not happening for us. If
|
|
you had not told us to expect a crash, then we would not be able to draw
|
|
any conclusion from our observations.
|
|
|
|
@item
|
|
If you wish to suggest changes to the @command{ld} source, send us context
|
|
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
|
|
@samp{-p} option. Always send diffs from the old file to the new file.
|
|
If you even discuss something in the @command{ld} source, refer to it by
|
|
context, not by line number.
|
|
|
|
The line numbers in our development sources will not match those in your
|
|
sources. Your line numbers would convey no useful information to us.
|
|
@end itemize
|
|
|
|
Here are some things that are not necessary:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A description of the envelope of the bug.
|
|
|
|
Often people who encounter a bug spend a lot of time investigating
|
|
which changes to the input file will make the bug go away and which
|
|
changes will not affect it.
|
|
|
|
This is often time consuming and not very useful, because the way we
|
|
will find the bug is by running a single example under the debugger
|
|
with breakpoints, not by pure deduction from a series of examples.
|
|
We recommend that you save your time for something else.
|
|
|
|
Of course, if you can find a simpler example to report @emph{instead}
|
|
of the original one, that is a convenience for us. Errors in the
|
|
output will be easier to spot, running under the debugger will take
|
|
less time, and so on.
|
|
|
|
However, simplification is not vital; if you do not want to do this,
|
|
report the bug anyway and send us the entire test case you used.
|
|
|
|
@item
|
|
A patch for the bug.
|
|
|
|
A patch for the bug does help us if it is a good one. But do not omit
|
|
the necessary information, such as the test case, on the assumption that
|
|
a patch is all we need. We might see problems with your patch and decide
|
|
to fix the problem another way, or we might not understand it at all.
|
|
|
|
Sometimes with a program as complicated as @command{ld} it is very hard to
|
|
construct an example that will make the program follow a certain path
|
|
through the code. If you do not send us the example, we will not be
|
|
able to construct one, so we will not be able to verify that the bug is
|
|
fixed.
|
|
|
|
And if we cannot understand what bug you are trying to fix, or why your
|
|
patch should be an improvement, we will not install it. A test case will
|
|
help us to understand.
|
|
|
|
@item
|
|
A guess about what the bug is or what it depends on.
|
|
|
|
Such guesses are usually wrong. Even we cannot guess right about such
|
|
things without first using the debugger to find the facts.
|
|
@end itemize
|
|
|
|
@node MRI
|
|
@appendix MRI Compatible Script Files
|
|
@cindex MRI compatibility
|
|
To aid users making the transition to @sc{gnu} @command{ld} from the MRI
|
|
linker, @command{ld} can use MRI compatible linker scripts as an
|
|
alternative to the more general-purpose linker scripting language
|
|
described in @ref{Scripts}. MRI compatible linker scripts have a much
|
|
simpler command set than the scripting language otherwise used with
|
|
@command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
|
|
linker commands; these commands are described here.
|
|
|
|
In general, MRI scripts aren't of much use with the @code{a.out} object
|
|
file format, since it only has three sections and MRI scripts lack some
|
|
features to make use of them.
|
|
|
|
You can specify a file containing an MRI-compatible script using the
|
|
@samp{-c} command-line option.
|
|
|
|
Each command in an MRI-compatible script occupies its own line; each
|
|
command line starts with the keyword that identifies the command (though
|
|
blank lines are also allowed for punctuation). If a line of an
|
|
MRI-compatible script begins with an unrecognized keyword, @command{ld}
|
|
issues a warning message, but continues processing the script.
|
|
|
|
Lines beginning with @samp{*} are comments.
|
|
|
|
You can write these commands using all upper-case letters, or all
|
|
lower case; for example, @samp{chip} is the same as @samp{CHIP}.
|
|
The following list shows only the upper-case form of each command.
|
|
|
|
@table @code
|
|
@cindex @code{ABSOLUTE} (MRI)
|
|
@item ABSOLUTE @var{secname}
|
|
@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
|
|
Normally, @command{ld} includes in the output file all sections from all
|
|
the input files. However, in an MRI-compatible script, you can use the
|
|
@code{ABSOLUTE} command to restrict the sections that will be present in
|
|
your output program. If the @code{ABSOLUTE} command is used at all in a
|
|
script, then only the sections named explicitly in @code{ABSOLUTE}
|
|
commands will appear in the linker output. You can still use other
|
|
input sections (whatever you select on the command line, or using
|
|
@code{LOAD}) to resolve addresses in the output file.
|
|
|
|
@cindex @code{ALIAS} (MRI)
|
|
@item ALIAS @var{out-secname}, @var{in-secname}
|
|
Use this command to place the data from input section @var{in-secname}
|
|
in a section called @var{out-secname} in the linker output file.
|
|
|
|
@var{in-secname} may be an integer.
|
|
|
|
@cindex @code{ALIGN} (MRI)
|
|
@item ALIGN @var{secname} = @var{expression}
|
|
Align the section called @var{secname} to @var{expression}. The
|
|
@var{expression} should be a power of two.
|
|
|
|
@cindex @code{BASE} (MRI)
|
|
@item BASE @var{expression}
|
|
Use the value of @var{expression} as the lowest address (other than
|
|
absolute addresses) in the output file.
|
|
|
|
@cindex @code{CHIP} (MRI)
|
|
@item CHIP @var{expression}
|
|
@itemx CHIP @var{expression}, @var{expression}
|
|
This command does nothing; it is accepted only for compatibility.
|
|
|
|
@cindex @code{END} (MRI)
|
|
@item END
|
|
This command does nothing whatever; it's only accepted for compatibility.
|
|
|
|
@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:
|
|
|
|
@enumerate
|
|
@item
|
|
S-records, if @var{output-format} is @samp{S}
|
|
|
|
@item
|
|
IEEE, if @var{output-format} is @samp{IEEE}
|
|
|
|
@item
|
|
COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
|
|
@samp{COFF}
|
|
@end enumerate
|
|
|
|
@cindex @code{LIST} (MRI)
|
|
@item LIST @var{anything}@dots{}
|
|
Print (to the standard output file) a link map, as produced by the
|
|
@command{ld} command-line option @samp{-M}.
|
|
|
|
The keyword @code{LIST} may be followed by anything on the
|
|
same line, with no change in its effect.
|
|
|
|
@cindex @code{LOAD} (MRI)
|
|
@item LOAD @var{filename}
|
|
@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
|
|
Include one or more object file @var{filename} in the link; this has the
|
|
same effect as specifying @var{filename} directly on the @command{ld}
|
|
command line.
|
|
|
|
@cindex @code{NAME} (MRI)
|
|
@item NAME @var{output-name}
|
|
@var{output-name} is the name for the program produced by @command{ld}; the
|
|
MRI-compatible command @code{NAME} is equivalent to the command-line
|
|
option @samp{-o} or the general script language command @code{OUTPUT}.
|
|
|
|
@cindex @code{ORDER} (MRI)
|
|
@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
|
|
@itemx ORDER @var{secname} @var{secname} @var{secname}
|
|
Normally, @command{ld} orders the sections in its output file in the
|
|
order in which they first appear in the input files. In an MRI-compatible
|
|
script, you can override this ordering with the @code{ORDER} command. The
|
|
sections you list with @code{ORDER} will appear first in your output
|
|
file, in the order specified.
|
|
|
|
@cindex @code{PUBLIC} (MRI)
|
|
@item PUBLIC @var{name}=@var{expression}
|
|
@itemx PUBLIC @var{name},@var{expression}
|
|
@itemx PUBLIC @var{name} @var{expression}
|
|
Supply a value (@var{expression}) for external symbol
|
|
@var{name} used in the linker input files.
|
|
|
|
@cindex @code{SECT} (MRI)
|
|
@item SECT @var{secname}, @var{expression}
|
|
@itemx SECT @var{secname}=@var{expression}
|
|
@itemx SECT @var{secname} @var{expression}
|
|
You can use any of these three forms of the @code{SECT} command to
|
|
specify the start address (@var{expression}) for section @var{secname}.
|
|
If you have more than one @code{SECT} statement for the same
|
|
@var{secname}, only the @emph{first} sets the start address.
|
|
@end table
|
|
|
|
@include fdl.texi
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@tex
|
|
% I think something like @colophon should be in texinfo. In the
|
|
% meantime:
|
|
\long\def\colophon{\hbox to0pt{}\vfill
|
|
\centerline{The body of this manual is set in}
|
|
\centerline{\fontname\tenrm,}
|
|
\centerline{with headings in {\bf\fontname\tenbf}}
|
|
\centerline{and examples in {\tt\fontname\tentt}.}
|
|
\centerline{{\it\fontname\tenit\/} and}
|
|
\centerline{{\sl\fontname\tensl\/}}
|
|
\centerline{are used for emphasis.}\vfill}
|
|
\page\colophon
|
|
% Blame: doc@cygnus.com, 28mar91.
|
|
@end tex
|
|
|
|
|
|
@contents
|
|
@bye
|