source: trunk/src/binutils/ld/ld.info-3@ 1372

This is ld.info, produced by makeinfo version 4.3 from ./ld.texinfo.

START-INFO-DIR-ENTRY
* Ld: (ld).                       The GNU linker.
END-INFO-DIR-ENTRY

   This file documents the GNU linker LD version 2.14.

   Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
2002, 2003 Free Software Foundation, Inc.


File: ld.info,  Node: Environment,  Prev: Options,  Up: Invocation

Environment Variables
=====================

   You can change the behavior of `ld' with the environment variables
`GNUTARGET', `LDEMULATION' and `COLLECT_NO_DEMANGLE'.

   `GNUTARGET' determines the input-file object format if you don't use
`-b' (or its synonym `--format').  Its value should be one of the BFD
names for an input format (*note BFD::).  If there is no `GNUTARGET' in
the environment, `ld' uses the natural format of the target. If
`GNUTARGET' is set to `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.

   `LDEMULATION' determines the default emulation if you don't use the
`-m' option.  The emulation can affect various aspects of linker
behaviour, particularly the default linker script.  You can list the
available emulations with the `--verbose' or `-V' options.  If the `-m'
option is not used, and the `LDEMULATION' environment variable is not
defined, the default emulation depends upon how the linker was
configured.

   Normally, the linker will default to demangling symbols.  However, if
`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 `gcc' linker wrapper program.  The default may
be overridden by the `--demangle' and `--no-demangle' options.


File: ld.info,  Node: Scripts,  Next: Machine Dependent,  Prev: Invocation,  Up: Top

Linker Scripts
**************

   Every link is controlled by a "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 `--verbose' command line option to
display the default linker script.  Certain command line options, such
as `-r' or `-N', will affect the default linker script.

   You may supply your own linker script by using the `-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.  *Note
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


File: ld.info,  Node: Basic Script Concepts,  Next: Script Format,  Up: Scripts

Basic 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
"object file format".  Each file is called an "object file".  The
output file is often called an "executable", but for our purposes we
will also call it an object file.  Each object file has, among other
things, a list of "sections".  We sometimes refer to a section in an
input file as an "input section"; similarly, a section in the output
file is an "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 "section contents".
A section may be marked as "loadable", which mean that the contents
should be loaded into memory when the output file is run.  A section
with no contents may be "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 "VMA", or virtual memory address.  This is the address the
section will have when the output file is run.  The second is the
"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 `objdump'
program with the `-h' option.

   Every object file also has a list of "symbols", known as the "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 `nm' program,
or by using the `objdump' program with the `-t' option.


File: ld.info,  Node: Script Format,  Next: Simple Example,  Prev: Basic Script Concepts,  Up: Scripts

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
`/*' and `*/'.  As in C, comments are syntactically equivalent to
whitespace.


File: ld.info,  Node: Simple Example,  Next: Simple Commands,  Prev: Script Format,  Up: Scripts

Simple Linker Script Example
============================

   Many linker scripts are fairly simple.

   The simplest possible linker script has just one command:
`SECTIONS'.  You use the `SECTIONS' command to describe the memory
layout of the output file.

   The `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
`.text', `.data', and `.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:
     SECTIONS
     {
       . = 0x10000;
       .text : { *(.text) }
       . = 0x8000000;
       .data : { *(.data) }
       .bss : { *(.bss) }
     }

   You write the `SECTIONS' command as the keyword `SECTIONS', followed
by a series of symbol assignments and output section descriptions
enclosed in curly braces.

   The first line inside the `SECTIONS' command of the above example
sets the value of the special symbol `.', 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
`SECTIONS' command, the location counter has the value `0'.

   The second line defines an output section, `.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 `*' is a wildcard
which matches any file name.  The expression `*(.text)' means all
`.text' input sections in all input files.

   Since the location counter is `0x10000' when the output section
`.text' is defined, the linker will set the address of the `.text'
section in the output file to be `0x10000'.

   The remaining lines define the `.data' and `.bss' sections in the
output file.  The linker will place the `.data' output section at
address `0x8000000'.  After the linker places the `.data' output
section, the value of the location counter will be `0x8000000' plus the
size of the `.data' output section.  The effect is that the linker will
place the `.bss' output section immediately after the `.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 `.text' and `.data' sections
will probably satisfy any alignment constraints, but the linker may
have to create a small gap between the `.data' and `.bss' sections.

   That's it!  That's a simple and complete linker script.


File: ld.info,  Node: Simple Commands,  Next: Assignments,  Prev: Simple Example,  Up: Scripts

Simple Linker Script Commands
=============================

   In this section we describe the simple linker script commands.

* Menu:

* Entry Point::                 Setting the entry point
* File Commands::               Commands dealing with files

* Format Commands::             Commands dealing with object file formats

* Miscellaneous Commands::      Other linker script commands


File: ld.info,  Node: Entry Point,  Next: File Commands,  Up: Simple Commands

Setting the Entry Point
-----------------------

   The first instruction to execute in a program is called the "entry
point".  You can use the `ENTRY' linker script command to set the entry
point.  The argument is a symbol name:
     ENTRY(SYMBOL)

   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:
   * the `-e' ENTRY command-line option;

   * the `ENTRY(SYMBOL)' command in a linker script;

   * the value of the symbol `start', if defined;

   * the address of the first byte of the `.text' section, if present;

   * The address `0'.


File: ld.info,  Node: File Commands,  Next: Format Commands,  Prev: Entry Point,  Up: Simple Commands

Commands Dealing with Files
---------------------------

   Several linker script commands deal with files.

`INCLUDE FILENAME'
     Include the linker script FILENAME at this point.  The file will
     be searched for in the current directory, and in any directory
     specified with the `-L' option.  You can nest calls to `INCLUDE'
     up to 10 levels deep.

`INPUT(FILE, FILE, ...)'
`INPUT(FILE FILE ...)'
     The `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 `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 `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 `-T'
     option.

     In case a "sysroot prefix" is configured, and the filename starts
     with the `/' character, and the script being processed was located
     inside the "sysroot prefix", the filename will be looked for in
     the "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 `-L' in *Note Command Line Options: Options.

     If you use `INPUT (-lFILE)', `ld' will transform the name to
     `libFILE.a', as with the command line argument `-l'.

     When you use the `INPUT' command in an implicit linker script, the
     files will be included in the link at the point at which the linker