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

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
     script file is included.  This can affect archive searching.

`GROUP(FILE, FILE, ...)'
`GROUP(FILE FILE ...)'
     The `GROUP' command is like `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 `-('
     in *Note Command Line Options: Options.

`OUTPUT(FILENAME)'
     The `OUTPUT' command names the output file.  Using
     `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
     FILENAME' on the command line (*note Command Line Options:
     Options.).  If both are used, the command line option takes
     precedence.

     You can use the `OUTPUT' command to define a default name for the
     output file other than the usual default of `a.out'.

`SEARCH_DIR(PATH)'
     The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
     looks for archive libraries.  Using `SEARCH_DIR(PATH)' is exactly
     like using `-L PATH' on the command line (*note Command Line
     Options: Options.).  If both are used, then the linker will search
     both paths.  Paths specified using the command line option are
     searched first.

`STARTUP(FILENAME)'
     The `STARTUP' command is just like the `INPUT' command, except
     that 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.


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

Commands Dealing with Object File Formats
-----------------------------------------

   A couple of linker script commands deal with object file formats.

`OUTPUT_FORMAT(BFDNAME)'
`OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
     The `OUTPUT_FORMAT' command names the BFD format to use for the
     output file (*note BFD::).  Using `OUTPUT_FORMAT(BFDNAME)' is
     exactly like using `--oformat BFDNAME' on the command line (*note
     Command Line Options: Options.).  If both are used, the command
     line option takes precedence.

     You can use `OUTPUT_FORMAT' with three arguments to use different
     formats based on the `-EB' and `-EL' command line options.  This
     permits the linker script to set the output format based on the
     desired endianness.

     If neither `-EB' nor `-EL' are used, then the output format will
     be the first argument, DEFAULT.  If `-EB' is used, the output
     format will be the second argument, BIG.  If `-EL' is used, the
     output format will be the third argument, LITTLE.

     For example, the default linker script for the MIPS ELF target
     uses this command:
          OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
     This says that the default format for the output file is
     `elf32-bigmips', but if the user uses the `-EL' command line
     option, the output file will be created in the `elf32-littlemips'
     format.

`TARGET(BFDNAME)'
     The `TARGET' command names the BFD format to use when reading input
     files.  It affects subsequent `INPUT' and `GROUP' commands.  This
     command is like using `-b BFDNAME' on the command line (*note
     Command Line Options: Options.).  If the `TARGET' command is used
     but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
     used to set the format for the output file.  *Note BFD::.


File: ld.info,  Node: Miscellaneous Commands,  Prev: Format Commands,  Up: Simple Commands

Other Linker Script Commands
----------------------------

   There are a few other linker scripts commands.

`ASSERT(EXP, MESSAGE)'
     Ensure that EXP is non-zero.  If it is zero, then exit the linker
     with an error code, and print MESSAGE.

`EXTERN(SYMBOL SYMBOL ...)'
     Force 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 SYMBOLs for
     each `EXTERN', and you may use `EXTERN' multiple times.  This
     command has the same effect as the `-u' command-line option.

`FORCE_COMMON_ALLOCATION'
     This command has the same effect as the `-d' command-line option:
     to make `ld' assign space to common symbols even if a relocatable
     output file is specified (`-r').

`INHIBIT_COMMON_ALLOCATION'
     This command has the same effect as the `--no-define-common'
     command-line option: to make `ld' omit the assignment of addresses
     to common symbols even for a non-relocatable output file.

`NOCROSSREFS(SECTION SECTION ...)'
     This command may be used to tell `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 `NOCROSSREFS' command takes a list of output section names.  If
     `ld' detects any cross references between the sections, it reports
     an error and returns a non-zero exit status.  Note that the
     `NOCROSSREFS' command uses output section names, not input section
     names.

`OUTPUT_ARCH(BFDARCH)'
     Specify a particular output machine architecture.  The argument is
     one of the names used by the BFD library (*note BFD::).  You can
     see the architecture of an object file by using the `objdump'
     program with the `-f' option.


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

Assigning Values to Symbols
===========================

   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


File: ld.info,  Node: Simple Assignments,  Next: PROVIDE,  Up: Assignments

Simple Assignments
------------------

   You may assign to a symbol using any of the C assignment operators:

`SYMBOL = EXPRESSION ;'
`SYMBOL += EXPRESSION ;'
`SYMBOL -= EXPRESSION ;'
`SYMBOL *= EXPRESSION ;'
`SYMBOL /= EXPRESSION ;'
`SYMBOL <<= EXPRESSION ;'
`SYMBOL >>= EXPRESSION ;'
`SYMBOL &= EXPRESSION ;'
`SYMBOL |= EXPRESSION ;'
   The first case will define SYMBOL to the value of EXPRESSION.  In
the other cases, SYMBOL must already be defined, and the value will be
adjusted accordingly.

   The special symbol name `.' indicates the location counter.  You may
only use this within a `SECTIONS' command.

   The semicolon after EXPRESSION is required.

   Expressions are defined below; see *Note Expressions::.

   You may write symbol assignments as commands in their own right, or
as statements within a `SECTIONS' command, or as part of an output
section description in a `SECTIONS' command.

   The section of the symbol will be set from the section of the
expression; for more information, see *Note Expression Section::.

   Here is an example showing the three different places that symbol
assignments may be used:

     floating_point = 0;
     SECTIONS
     {
       .text :
         {
           *(.text)
           _etext = .;
         }
       _bdata = (. + 3) & ~ 3;
       .data : { *(.data) }
     }

In this example, the symbol `floating_point' will be defined as zero.
The symbol `_etext' will be defined as the address following the last
`.text' input section.  The symbol `_bdata' will be defined as the
address following the `.text' output section aligned upward to a 4 byte
boundary.


File: ld.info,  Node: PROVIDE,  Prev: Simple Assignments,  Up: Assignments

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 `etext'.
However, ANSI C requires that the user be able to use `etext' as a
function name without encountering an error.  The `PROVIDE' keyword may
be used to define a symbol, such as `etext', only if it is referenced
but not defined.  The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.

   Here is an example of using `PROVIDE' to define `etext':
     SECTIONS
     {
       .text :
         {
           *(.text)
           _etext = .;
           PROVIDE(etext = .);
         }
     }

   In this example, if the program defines `_etext' (with a leading
underscore), the linker will give a multiple definition error.  If, on
the other hand, the program defines `etext' (with no leading
underscore), the linker will silently use the definition in the program.
If the program references `etext' but does not define it, the linker
will use the definition in the linker script.


File: ld.info,  Node: SECTIONS,  Next: MEMORY,  Prev: Assignments,  Up: Scripts

SECTIONS Command
================

   The `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 `SECTIONS' command is:
     SECTIONS
     {
       SECTIONS-COMMAND
       SECTIONS-COMMAND
       ...
     }

   Each SECTIONS-COMMAND may of be one of the following:

   * an `ENTRY' command (*note Entry command: Entry Point.)

   * a symbol assignment (*note Assignments::)

   * an output section description

   * an overlay description

   The `ENTRY' command and symbol assignments are permitted inside the
`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 `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


File: ld.info,  Node: Output Section Description,  Next: Output Section Name,  Up: SECTIONS

Output Section Description
--------------------------

   The full description of an output section looks like this:
     SECTION [ADDRESS] [(TYPE)] : [AT(LMA)]
       {
         OUTPUT-SECTION-COMMAND
         OUTPUT-SECTION-COMMAND
         ...
       } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]

   Most output sections do not use most of the optional section
attributes.

   The whitespace around 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 OUTPUT-SECTION-COMMAND may be one of the following:

   * a symbol assignment (*note Assignments::)

   * an input section description (*note Input Section::)

   * data values to include directly (*note Output Section Data::)

   * a special output section keyword (*note Output Section Keywords::)


File: ld.info,  Node: Output Section Name,  Next: Output Section Address,  Prev: Output Section Description,  Up: SECTIONS

Output Section Name
-------------------

   The name of the output section is SECTION.  SECTION must meet the
constraints of your output format.  In formats which only support a
limited number of sections, such as `a.out', the name must be one of
the names supported by the format (`a.out', for example, allows only
`.text', `.data' or `.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 `/DISCARD/' is special; *Note Output Section
Discarding::.


File: ld.info,  Node: Output Section Address,  Next: Input Section,  Prev: Output Section Name,  Up: SECTIONS

Output Section Description
--------------------------

   The ADDRESS is an expression for the VMA (the virtual memory
address) of the output section.  If you do not provide ADDRESS, the
linker will set it based on REGION if present, or otherwise based on
the current value of the location counter.

   If you provide ADDRESS, the address of the output section will be
set to precisely that.  If you provide neither ADDRESS nor 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,
     .text . : { *(.text) }

and
     .text : { *(.text) }

are subtly different.  The first will set the address of the `.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 `.text' input section.

   The ADDRESS may be an arbitrary expression; *Note 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:
     .text ALIGN(0x10) : { *(.text) }

This works because `ALIGN' returns the current location counter aligned
upward to the specified value.

   Specifying ADDRESS for a section will change the value of the
location counter.


File: ld.info,  Node: Input Section,  Next: Output Section Data,  Prev: Output Section Address,  Up: SECTIONS

Input Section Description
-------------------------

   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


File: ld.info,  Node: Input Section Basics,  Next: Input Section Wildcards,  Up: Input Section

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 (*note 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 `.text' sections, you would write:
     *(.text)

Here the `*' 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:
     (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
   will cause all .ctors sections from all files except `crtend.o' and
`otherfile.o' to be included.

   There are two ways to include more than one section:
     *(.text .rdata)
     *(.text) *(.rdata)

The difference between these is the order in which the `.text' and
`.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 `.text'
input sections will appear first, followed by all `.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:
     data.o(.data)

   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:
     data.o

   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 `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
`INPUT' command, because the linker will not search for the file in the
archive search path.


File: ld.info,  Node: Input Section Wildcards,  Next: Input Section Common,  Prev: Input Section Basics,  Up: Input Section

Input Section 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 `*' seen in many examples is a simple wildcard
pattern for the file name.

   The wildcard patterns are like those used by the Unix shell.

`*'
     matches any number of characters

`?'
     matches any single character

`[CHARS]'
     matches a single instance of any of the CHARS; the `-' character
     may be used to specify a range of characters, as in `[a-z]' to
     match any lower case letter

`\'
     quotes the following character

   When a file name is matched with a wildcard, the wildcard characters
will not match a `/' character (used to separate directory names on
Unix).  A pattern consisting of a single `*' character is an exception;
it will always match any file name, whether it contains a `/' or not.
In a section name, the wildcard characters will match a `/' character.

   File name wildcard patterns only match files which are explicitly
specified on the command line or in an `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
`data.o' rule will not be used:
     .data : { *(.data) }
     .data1 : { data.o(.data) }

   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 `SORT' keyword, which appears before a wildcard
pattern in parentheses (e.g., `SORT(.text*)').  When the `SORT' keyword
is used, the linker will sort the files or sections into ascending
order by name before placing them in the output file.

   If you ever get confused about where input sections are going, use
the `-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 `.text'
sections in `.text' and all `.bss' sections in `.bss'.  The linker will
place the `.data' section from all files beginning with an upper case
character in `.DATA'; for all other files, the linker will place the
`.data' section in `.data'.
     SECTIONS {
       .text : { *(.text) }
       .DATA : { [A-Z]*(.data) }
       .data : { *(.data) }
       .bss : { *(.bss) }
     }


File: ld.info,  Node: Input Section Common,  Next: Input Section Keep,  Prev: Input Section Wildcards,  Up: Input Section

Input Section for Common Symbols
................................

   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 `COMMON'.

   You may use file names with the `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
`.bss' section in the output file.  For example:
     .bss { *(.bss) *(COMMON) }

   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 `COMMON' for standard common
symbols and `.scommon' for small common symbols.  This permits you to
map the different types of common symbols into memory at different
locations.

   You will sometimes see `[COMMON]' in old linker scripts.  This
notation is now considered obsolete.  It is equivalent to `*(COMMON)'.


File: ld.info,  Node: Input Section Keep,  Next: Input Section Example,  Prev: Input Section Common,  Up: Input Section

Input Section and Garbage Collection
....................................

   When link-time garbage collection is in use (`--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
`KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT(*)(.ctors))'.


File: ld.info,  Node: Input Section Example,  Prev: Input Section Keep,  Up: Input Section

Input Section Example
.....................

   The following example is a complete linker script.  It tells the
linker to read all of the sections from file `all.o' and place them at
the start of output section `outputa' which starts at location
`0x10000'.  All of section `.input1' from file `foo.o' follows
immediately, in the same output section.  All of section `.input2' from
`foo.o' goes into output section `outputb', followed by section
`.input1' from `foo1.o'.  All of the remaining `.input1' and `.input2'
sections from any files are written to output section `outputc'.

     SECTIONS {
       outputa 0x10000 :
         {
         all.o
         foo.o (.input1)
         }
       outputb :
         {
         foo.o (.input2)
         foo1.o (.input1)
         }
       outputc :
         {
         *(.input1)
         *(.input2)
         }
     }


File: ld.info,  Node: Output Section Data,  Next: Output Section Keywords,  Prev: Input Section,  Up: SECTIONS

Output Section Data
-------------------

   You can include explicit bytes of data in an output section by using
`BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
command.  Each keyword is followed by an expression in parentheses
providing the value to store (*note Expressions::).  The value of the
expression is stored at the current value of the location counter.

   The `BYTE', `SHORT', `LONG', and `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 `addr':
     BYTE(1)
     LONG(addr)

   When using a 64 bit host or target, `QUAD' and `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 `QUAD'
stores a 32 bit value zero extended to 64 bits, and `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:
     SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
   whereas this will work:
     SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }

   You may use the `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 `FILL'
statement covers memory locations after the point at which it occurs in
the section definition; by including more than one `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 `0x90':
     FILL(0x90909090)

   The `FILL' command is similar to the `=FILLEXP' output section
attribute, but it only affects the part of the section following the
`FILL' command, rather than the entire section.  If both are used, the
`FILL' command takes precedence.  *Note Output Section Fill::, for
details on the fill expression.


File: ld.info,  Node: Output Section Keywords,  Next: Output Section Discarding,  Prev: Output Section Data,  Up: SECTIONS

Output Section Keywords
-----------------------

   There are a couple of keywords which can appear as output section
commands.

`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 `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.

`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 `CONSTRUCTORS' command
     tells the linker to place constructor information in the output
     section where the `CONSTRUCTORS' command appears.  The
     `CONSTRUCTORS' command is ignored for other object file formats.

     The symbol `__CTOR_LIST__' marks the start of the global
     constructors, and the symbol `__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 GNU C++ normally calls constructors from
     a subroutine `__main'; a call to `__main' is automatically
     inserted into the startup code for `main'.  GNU C++ normally runs
     destructors either by using `atexit', or directly from the function
     `exit'.

     For object file formats such as `COFF' or `ELF' which support
     arbitrary section names, GNU C++ will normally arrange to put the
     addresses of global constructors and destructors into the `.ctors'
     and `.dtors' sections.  Placing the following sequence into your
     linker script will build the sort of table which the GNU C++
     runtime code expects to see.

                __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__ = .;

     If you are using the 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 `CONSTRUCTORS' command, use `SORT(CONSTRUCTORS)' instead.
     When using the `.ctors' and `.dtors' sections, use
     `*(SORT(.ctors))' and `*(SORT(.dtors))' instead of just
     `*(.ctors)' and `*(.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.


File: ld.info,  Node: Output Section Discarding,  Next: Output Section Attributes,  Prev: Output Section Keywords,  Up: SECTIONS

Output Section Discarding
-------------------------

   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:
     .foo { *(.foo) }

will only create a `.foo' section in the output file if there is a
`.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.

   The special output section name `/DISCARD/' may be used to discard
input sections.  Any input sections which are assigned to an output
section named `/DISCARD/' are not included in the output file.


File: ld.info,  Node: Output Section Attributes,  Next: Overlay Description,  Prev: Output Section Discarding,  Up: SECTIONS

Output Section Attributes
-------------------------

   We showed above that the full description of an output section looked
like this:
     SECTION [ADDRESS] [(TYPE)] : [AT(LMA)]
       {
         OUTPUT-SECTION-COMMAND
         OUTPUT-SECTION-COMMAND
         ...
       } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
We've already described SECTION, ADDRESS, and
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
* Output Section Region::       Output section region
* Output Section Phdr::         Output section phdr
* Output Section Fill::         Output section fill


File: ld.info,  Node: Output Section Type,  Next: Output Section LMA,  Up: Output Section Attributes

Output Section Type
...................

   Each output section may have a type.  The type is a keyword in
parentheses.  The following types are defined:

`NOLOAD'
     The section should be marked as not loadable, so that it will not
     be loaded into memory when the program is run.

`DSECT'
`COPY'
`INFO'
`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.

   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 `ROM'
section is addressed at memory location `0' and does not need to be
loaded when the program is run.  The contents of the `ROM' section will
appear in the linker output file as usual.
     SECTIONS {
       ROM 0 (NOLOAD) : { ... }
       ...
     }


File: ld.info,  Node: Output Section LMA,  Next: Output Section Region,  Prev: Output Section Type,  Up: Output Section Attributes

Output Section LMA
..................

   Every section has a virtual address (VMA) and a load address (LMA);
see *Note Basic Script Concepts::.  The address expression which may
appear in an output section description sets the VMA (*note Output
Section Address::).

   The linker will normally set the LMA equal to the VMA.  You can
change that by using the `AT' keyword.  The expression LMA that follows
the `AT' keyword specifies the load address of the section.
Alternatively, with `AT>LMA_REGION' expression, you may specify a
memory region for the section's load address. *Note MEMORY::.

   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 `.text', which starts at `0x1000', one called `.mdata', which is
loaded at the end of the `.text' section even though its VMA is
`0x2000', and one called `.bss' to hold uninitialized data at address
`0x3000'.  The symbol `_data' is defined with the value `0x2000', which
shows that the location counter holds the VMA value, not the LMA value.

     SECTIONS
       {
       .text 0x1000 : { *(.text) _etext = . ; }
       .mdata 0x2000 :
         AT ( ADDR (.text) + SIZEOF (.text) )
         { _data = . ; *(.data); _edata = . ;  }
       .bss 0x3000 :
         { _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;}
     }

   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.

     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;


File: ld.info,  Node: Output Section Region,  Next: Output Section Phdr,  Prev: Output Section LMA,  Up: Output Section Attributes

Output Section Region
.....................

   You can assign a section to a previously defined region of memory by
using `>REGION'.  *Note MEMORY::.

   Here is a simple example:
     MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
     SECTIONS { ROM : { *(.text) } >rom }


File: ld.info,  Node: Output Section Phdr,  Next: Output Section Fill,  Prev: Output Section Region,  Up: Output Section Attributes

Output Section Phdr
...................

   You can assign a section to a previously defined program segment by
using `:PHDR'.  *Note 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 `:PHDR' modifier.
You can use `:NONE' to tell the linker to not put the section in any
segment at all.

   Here is a simple example:
     PHDRS { text PT_LOAD ; }
     SECTIONS { .text : { *(.text) } :text }


File: ld.info,  Node: Output Section Fill,  Prev: Output Section Phdr,  Up: Output Section Attributes

Output Section Fill
...................

   You can set the fill pattern for an entire section by using
`=FILLEXP'.  FILLEXP is an expression (*note 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 `0x' and without a trailing `k' or `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 `+', 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 `FILL' command in the
output section commands; (*note Output Section Data::).

   Here is a simple example:
     SECTIONS { .text : { *(.text) } =0x90909090 }