source: trunk/src/binutils/ld/ld.info-4@ 201

This is ld.info, produced by makeinfo version 4.0 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.11.2.

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


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

Overlay description
-------------------

   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 `OVERLAY' command.  The `OVERLAY'
command is used within a `SECTIONS' command, like an output section
description.  The full syntax of the `OVERLAY' command is as follows:
     OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
       {
         SECNAME1
           {
             OUTPUT-SECTION-COMMAND
             OUTPUT-SECTION-COMMAND
             ...
           } [:PHDR...] [=FILL]
         SECNAME2
           {
             OUTPUT-SECTION-COMMAND
             OUTPUT-SECTION-COMMAND
             ...
           } [:PHDR...] [=FILL]
         ...
       } [>REGION] [:PHDR...] [=FILL]

   Everything is optional except `OVERLAY' (a keyword), and each
section must have a name (SECNAME1 and SECNAME2 above).  The section
definitions within the `OVERLAY' construct are identical to those
within the general `SECTIONS' contruct (*note SECTIONS::), except that
no addresses and no memory regions may be defined for sections within
an `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
`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 `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.  *Note NOCROSSREFS: Miscellaneous
Commands.

   For each section within the `OVERLAY', the linker automatically
defines two symbols.  The symbol `__load_start_SECNAME' is defined as
the starting load address of the section.  The symbol
`__load_stop_SECNAME' is defined as the final load address of the
section.  Any characters within 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
`SECTIONS' construct.
       OVERLAY 0x1000 : AT (0x4000)
        {
          .text0 { o1/*.o(.text) }
          .text1 { o2/*.o(.text) }
        }

This will define both `.text0' and `.text1' to start at address 0x1000.
`.text0' will be loaded at address 0x4000, and `.text1' will be loaded
immediately after `.text0'.  The following symbols will be defined:
`__load_start_text0', `__load_stop_text0', `__load_start_text1',
`__load_stop_text1'.

   C code to copy overlay `.text1' into the overlay area might look
like the following.

       extern char __load_start_text1, __load_stop_text1;
       memcpy ((char *) 0x1000, &__load_start_text1,
               &__load_stop_text1 - &__load_start_text1);

   Note that the `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.

       .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));


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

MEMORY command
==============

   The linker's default configuration permits allocation of all
available memory.  You can override this by using the `MEMORY' command.

   The `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 `MEMORY' command.
However, you can define as many blocks of memory within it as you
wish.  The syntax is:
     MEMORY
       {
         NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
         ...
       }

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

   The 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 *Note
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 ATTR string must consist only of the following characters:
`R'
     Read-only section

`W'
     Read/write section

`X'
     Executable section

`A'
     Allocatable section

`I'
     Initialized section

`L'
     Same as `I'

`!'
     Invert the sense of any of the preceding attributes

   If a unmapped section matches any of the listed attributes other than
`!', it will be placed in the memory region.  The `!' 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.

   The ORIGIN is an expression for the start address of the memory
region.  The expression must evaluate to a constant before memory
allocation is performed, which means that you may not use any section
relative symbols.  The keyword `ORIGIN' may be abbreviated to `org' or
`o' (but not, for example, `ORG').

   The LEN is an expression for the size in bytes of the memory region.
As with the ORIGIN expression, the expression must evaluate to a
constant before memory allocation is performed.  The keyword `LENGTH'
may be abbreviated to `len' or `l'.

   In the following example, we specify that there are two memory
regions available for allocation: one starting at `0' for 256 kilobytes,
and the other starting at `0x40000000' for four megabytes.  The linker
will place into the `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 `ram' memory region.

     MEMORY
       {
         rom (rx)  : ORIGIN = 0, LENGTH = 256K
         ram (!rx) : org = 0x40000000, l = 4M
       }

   Once you define a memory region, you can direct the linker to place
specific output sections into that memory region by using the `>REGION'
output section attribute.  For example, if you have a memory region
named `mem', you would use `>mem' in the output section definition.
*Note 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.


File: ld.info,  Node: PHDRS,  Next: VERSION,  Prev: MEMORY,  Up: Scripts

PHDRS Command
=============

   The ELF object file format uses "program headers", also knows as
"segments".  The program headers describe how the program should be
loaded into memory.  You can print them out by using the `objdump'
program with the `-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 `PHDRS' command for this purpose.  When the
linker sees the `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 `PHDRS' command when
generating an ELF output file.  In other cases, the linker will simply
ignore `PHDRS'.

   This is the syntax of the `PHDRS' command.  The words `PHDRS',
`FILEHDR', `AT', and `FLAGS' are keywords.

     PHDRS
     {
       NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
             [ FLAGS ( FLAGS ) ] ;
     }

   The NAME is used only for reference in the `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 `:PHDR' output section attribute
to place a section in a particular segment.  *Note 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 `:PHDR', using it once for each segment which should contain the
section.

   If you place a section in one or more segments using `:PHDR', then
the linker will place all subsequent allocatable sections which do not
specify `: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 `:NONE' to override the default segment and tell
the linker to not put the section in any segment at all.

   You may use the `FILEHDR' and `PHDRS' keywords appear after the
program header type to further describe the contents of the segment.
The `FILEHDR' keyword means that the segment should include the ELF
file header.  The `PHDRS' keyword means that the segment should include
the ELF program headers themselves.

   The TYPE may be one of the following.  The numbers indicate the
value of the keyword.

`PT_NULL' (0)
     Indicates an unused program header.

`PT_LOAD' (1)
     Indicates that this program header describes a segment to be
     loaded from the file.

`PT_DYNAMIC' (2)
     Indicates a segment where dynamic linking information can be found.

`PT_INTERP' (3)
     Indicates a segment where the name of the program interpreter may
     be found.

`PT_NOTE' (4)
     Indicates a segment holding note information.

`PT_SHLIB' (5)
     A reserved program header type, defined but not specified by the
     ELF ABI.

`PT_PHDR' (6)
     Indicates a segment where the program headers may be found.

EXPRESSION
     An expression giving the numeric type of the program header.  This
     may be used for types not defined above.

   You can specify that a segment should be loaded at a particular
address in memory by using an `AT' expression.  This is identical to the
`AT' command used as an output section attribute (*note Output Section
LMA::).  The `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 `FLAGS' keyword to
explicitly specify the segment flags.  The value of FLAGS must be an
integer.  It is used to set the `p_flags' field of the program header.

   Here is an example of `PHDRS'.  This shows a typical set of program
headers used on a native ELF system.

     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 */
       ...
       . = . + 0x1000; /* move to a new page in memory */
       .data : { *(.data) } :data
       .dynamic : { *(.dynamic) } :data :dynamic
       ...
     }


File: ld.info,  Node: VERSION,  Next: Expressions,  Prev: PHDRS,  Up: Scripts

VERSION Command
===============

   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 `--version-script' linker option.

   The syntax of the `VERSION' command is simply
     VERSION { version-script-commands }

   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.

     VERS_1.1 {
         global:
                 foo1;
         local:
                 old*;
                 original*;
                 new*;
     };
     
     VERS_1.2 {
                 foo2;
     } VERS_1.1;
     
     VERS_2.0 {
                 bar1; bar2;
     } VERS_1.2;

   This example version script defines three version nodes.  The first
version node defined is `VERS_1.1'; it has no other dependencies.  The
script binds the symbol `foo1' to `VERS_1.1'.  It reduces a number of
symbols to local scope so that they are not visible outside of the
shared library.

   Next, the version script defines node `VERS_1.2'.  This node depends
upon `VERS_1.1'.  The script binds the symbol `foo2' to the version
node `VERS_1.2'.

   Finally, the version script defines node `VERS_2.0'.  This node
depends upon `VERS_1.2'.  The scripts binds the symbols `bar1' and
`bar2' are bound to the version node `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 `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 `2.0' version
could just as well have appeared in between `1.1' and `1.2'.  However,
this would be a confusing way to write a version script.

   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:
     __asm__(".symver original_foo,foo@VERS_1.1");

in the C source file.  This renames the function `original_foo' to be
an alias for `foo' bound to the version node `VERS_1.1'.  The `local:'
directive can be used to prevent the symbol `original_foo' from being
exported.

   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 `.symver' directives in the source
file.  Here is an example:

     __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");

   In this example, `foo@' represents the symbol `foo' bound to the
unspecified base version of the symbol.  The source file that contains
this example would define 4 C functions: `original_foo', `old_foo',
`old_foo1', and `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 `foo@@VERS_2.0'
type of `.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.
`old_foo'), or you can use the `.symver' directive to specifically bind
to an external version of the function in question.


File: ld.info,  Node: Expressions,  Next: Implicit Linker Scripts,  Prev: VERSION,  Up: Scripts

Expressions in Linker Scripts
=============================

   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


File: ld.info,  Node: Constants,  Next: Symbols,  Up: Expressions

Constants
---------

   All constants are integers.

   As in C, the linker considers an integer beginning with `0' to be
octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
The linker considers other integers to be decimal.

   In addition, you can use the suffixes `K' and `M' to scale a
constant by `1024' or `1024*1024' respectively. For example, the
following all refer to the same quantity:
       _fourk_1 = 4K;
       _fourk_2 = 4096;
       _fourk_3 = 0x1000;


File: ld.info,  Node: Symbols,  Next: Location Counter,  Prev: Constants,  Up: Expressions

Symbol Names
------------

   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:
       "SECTION" = 9;
       "with a space" = "also with a space" + 10;

   Since symbols can contain many non-alphabetic characters, it is
safest to delimit symbols with spaces.  For example, `A-B' is one
symbol, whereas `A - B' is an expression involving subtraction.


File: ld.info,  Node: Location Counter,  Next: Operators,  Prev: Symbols,  Up: Expressions

The Location Counter
--------------------

   The special linker variable "dot" `.' always contains the current
output location counter.  Since the `.' always refers to a location in
an output section, it may only appear in an expression within a
`SECTIONS' command.  The `.' symbol may appear anywhere that an
ordinary symbol is allowed in an expression.

   Assigning a value to `.' 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.

     SECTIONS
     {
       output :
         {
           file1(.text)
           . = . + 1000;
           file2(.text)
           . += 1000;
           file3(.text)
         } = 0x1234;
     }

In the previous example, the `.text' section from `file1' is located at
the beginning of the output section `output'.  It is followed by a 1000
byte gap.  Then the `.text' section from `file2' appears, also with a
1000 byte gap following before the `.text' section from `file3'.  The
notation `= 0x1234' specifies what data to write in the gaps (*note
Output Section Fill::).

   Note: `.' actually refers to the byte offset from the start of the
current containing object.  Normally this is the `SECTIONS' statement,
whoes start address is 0, hence `.' can be used as an absolute address.
If `.' 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:

     SECTIONS
     {
         . = 0x100
         .text: {
           *(.text)
           . = 0x200
         }
         . = 0x500
         .data: {
           *(.data)
           . += 0x600
         }
     }

   The `.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
`.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 `.'
backwards).  The `.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 `.data' input sections and before the end of the `.data' output
section itself.


File: ld.info,  Node: Operators,  Next: Evaluation,  Prev: Location Counter,  Up: Expressions

Operators
---------

   The linker recognizes the standard C set of arithmetic operators,
with the standard bindings and precedence levels:
     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)
   Notes: (1) Prefix operators (2) *Note Assignments::.


File: ld.info,  Node: Evaluation,  Next: Expression Section,  Prev: Operators,  Up: Expressions

Evaluation
----------

   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
`.', 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
     SECTIONS
       {
         .text 9+this_isnt_constant :
           { *(.text) }
       }

will cause the error message `non constant expression for initial
address'.


File: ld.info,  Node: Expression Section,  Next: Builtin Functions,  Prev: Evaluation,  Up: Expressions

The Section of an Expression
----------------------------

   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 `-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 `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 `.data':
     SECTIONS
       {
         .data : { *(.data) _edata = ABSOLUTE(.); }
       }

If `ABSOLUTE' were not used, `_edata' would be relative to the `.data'
section.


File: ld.info,  Node: Builtin Functions,  Prev: Expression Section,  Up: Expressions

Builtin Functions
-----------------

   The linker script language includes a number of builtin functions for
use in linker script expressions.

`ABSOLUTE(EXP)'
     Return the absolute (non-relocatable, as opposed to non-negative)
     value of the expression EXP.  Primarily useful to assign an
     absolute value to a symbol within a section definition, where
     symbol values are normally section relative.  *Note Expression
     Section::.

`ADDR(SECTION)'
     Return the absolute address (the VMA) of the named SECTION.  Your
     script must previously have defined the location of that section.
     In the following example, `symbol_1' and `symbol_2' are assigned
     identical values:
          SECTIONS { ...
            .output1 :
              {
              start_of_output_1 = ABSOLUTE(.);
              ...
              }
            .output :
              {
              symbol_1 = ADDR(.output1);
              symbol_2 = start_of_output_1;
              }
          ... }

`ALIGN(EXP)'
     Return the location counter (`.') aligned to the next EXP
     boundary.  EXP must be an expression whose value is a power of
     two.  This is equivalent to
          (. + EXP - 1) & ~(EXP - 1)

     `ALIGN' doesn't change the value of the location counter--it just
     does arithmetic on it.  Here is an example which aligns the output
     `.data' section to the next `0x2000' byte boundary after the
     preceding section and sets a variable within the section to the
     next `0x8000' boundary after the input sections:
          SECTIONS { ...
            .data ALIGN(0x2000): {
              *(.data)
              variable = ALIGN(0x8000);
            }
          ... }

     The first use of `ALIGN' in this example specifies the location of
     a section because it is used as the optional ADDRESS attribute of
     a section definition (*note Output Section Address::).  The second
     use of `ALIGN' is used to defines the value of a symbol.

     The builtin function `NEXT' is closely related to `ALIGN'.

`BLOCK(EXP)'
     This is a synonym for `ALIGN', for compatibility with older linker
     scripts.  It is most often seen when setting the address of an
     output section.

`DEFINED(SYMBOL)'
     Return 1 if SYMBOL is in the linker global symbol table and is
     defined, 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 `begin' to the first
     location in the `.text' section--but if a symbol called `begin'
     already existed, its value is preserved:

          SECTIONS { ...
            .text : {
              begin = DEFINED(begin) ? begin : . ;
              ...
            }
            ...
          }

`LOADADDR(SECTION)'
     Return the absolute LMA of the named SECTION.  This is normally
     the same as `ADDR', but it may be different if the `AT' attribute
     is used in the output section definition (*note Output Section
     LMA::).

`MAX(EXP1, EXP2)'
     Returns the maximum of EXP1 and EXP2.

`MIN(EXP1, EXP2)'
     Returns the minimum of EXP1 and EXP2.

`NEXT(EXP)'
     Return the next unallocated address that is a multiple of EXP.
     This function is closely related to `ALIGN(EXP)'; unless you use
     the `MEMORY' command to define discontinuous memory for the output
     file, the two functions are equivalent.

`SIZEOF(SECTION)'
     Return the size in bytes of the named 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, `symbol_1' and `symbol_2' are assigned identical values:
          SECTIONS{ ...
            .output {
              .start = . ;
              ...
              .end = . ;
              }
            symbol_1 = .end - .start ;
            symbol_2 = SIZEOF(.output);
          ... }

`SIZEOF_HEADERS'
`sizeof_headers'
     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.

     When producing an ELF output file, if the linker script uses the
     `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 `not enough
     room for program headers'.  To avoid this error, you must avoid
     using the `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
     `PHDRS' command (*note PHDRS::).


File: ld.info,  Node: Implicit Linker Scripts,  Prev: Expressions,  Up: Scripts

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 `INPUT', `GROUP', or `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.


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

Machine Dependent Features
**************************

   `ld' has additional features on some platforms; the following
sections describe them.  Machines where `ld' has no additional
functionality are not listed.

* Menu:

* H8/300::                      `ld' and the H8/300
* i960::                        `ld' and the Intel 960 family
* ARM::                         `ld' and the ARM family
* HPPA ELF32::                  `ld' and HPPA 32-bit ELF

* TI COFF::                     `ld' and TI COFF


File: ld.info,  Node: H8/300,  Next: i960,  Up: Machine Dependent

`ld' and the H8/300
===================

   For the H8/300, `ld' can perform these global optimizations when you
specify the `--relax' command-line option.

_relaxing address modes_
     `ld' finds all `jsr' and `jmp' instructions whose targets are
     within eight bits, and turns them into eight-bit program-counter
     relative `bsr' and `bra' instructions, respectively.

_synthesizing instructions_
     `ld' finds all `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 `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
     address AA is in the top page of memory).


File: ld.info,  Node: i960,  Next: ARM,  Prev: H8/300,  Up: Machine Dependent

`ld' and the Intel 960 family
=============================

   You can use the `-AARCHITECTURE' 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 `ld' command line included `-ACA' as well as
`-ltry', the linker would look (in its built-in search paths, and in
any paths you specify with `-L') for a library with the names

     try
     libtry.a
     tryca
     libtryca.a

The first two possibilities would be considered in any event; the last
two are due to the use of `-ACA'.

   You can meaningfully use `-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 `-l'
specifies a library.

   `ld' supports the `--relax' option for the i960 family.  If you
specify `--relax', `ld' finds all `balx' and `calx' instructions whose
targets are within 24 bits, and turns them into 24-bit program-counter
relative `bal' and `cal' instructions, respectively.  `ld' also turns
`cal' instructions into `bal' instructions when it determines that the
target subroutine is a leaf routine (that is, the target subroutine does
not itself call any subroutines).


File: ld.info,  Node: ARM,  Next: HPPA ELF32,  Prev: i960,  Up: Machine Dependent

`ld''s support for interworking between ARM and Thumb code
==========================================================

   For the ARM, `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 `-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 `--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.

   The `--thumb-entry' switch is a duplicate of the generic `--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.


File: ld.info,  Node: HPPA ELF32,  Next: TI COFF,  Prev: ARM,  Up: Machine Dependent

`ld' and HPPA 32-bit ELF support
================================

   When generating a shared library, `ld' will by default generate
import stubs suitable for use with a single sub-space application.  The
`--multi-subspace' switch causes `ld' to generate export stubs, and
different (larger) import stubs suitable for use with multiple
sub-spaces.

   Long branch stubs and import/export stubs are placed by `ld' in stub
sections located between groups of input sections.  `--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
`N' chooses this scheme, ensuring that branches to stubs always use a
negative offset.  Two special values of `N' are recognized, `1' and
`-1'.  These both instruct `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 `N' respectively.

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


File: ld.info,  Node: TI COFF,  Prev: HPPA ELF32,  Up: Machine Dependent

`ld''s support for various TI COFF versions
===========================================

   The `--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;
`ld' will read any version or byte order, but the output header format
depends on the default specified by the specific target.


File: ld.info,  Node: BFD,  Next: Reporting Bugs,  Prev: Machine Dependent,  Up: Top

BFD
***

   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 `objdump -i' (*note
objdump: (binutils.info)objdump.) to list all the formats available for
your configuration.

   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. *Note BFD information loss::.

* Menu:

* BFD outline::                 How it works: an outline of BFD


File: ld.info,  Node: BFD outline,  Up: BFD

How it works: an outline of BFD
===============================

   When an object file is opened, BFD subroutines automatically
determine the format of the input object file.  They then build a
descriptor in memory with pointers to routines that will be used to
access elements of the object file's data structures.

   As different information from the the object files is required, BFD
reads from different sections of the file and processes them.  For
example, a very common operation for the linker is processing symbol
tables.  Each BFD back end provides a routine for converting between
the object file's representation of symbols and an internal canonical
format. When the linker asks for the symbol table of an object file, it
calls through a memory pointer to the routine from the relevant BFD
back end which reads and converts the table into a canonical form.  The
linker then operates upon the canonical form. When the link is finished
and the linker writes the output file's symbol table, another BFD back
end routine is called to take the newly created symbol table and
convert it into the chosen output format.

* Menu:

* BFD information loss::        Information Loss
* Canonical format::            The BFD canonical object-file format


File: ld.info,  Node: BFD information loss,  Next: Canonical format,  Up: BFD outline

Information Loss
----------------

   _Information can be lost during output._ The output formats
supported by BFD do not provide identical facilities, and information
which can be described in one form has nowhere to go in another format.
One example of this is alignment information in `b.out'. There is
nowhere in an `a.out' format file to store alignment information on the
contained data, so when a file is linked from `b.out' and an `a.out'
image is produced, alignment information will not propagate to the
output file. (The linker will still use the alignment information
internally, so the link is performed correctly).

   Another example is COFF section names. COFF files may contain an
unlimited number of sections, each one with a textual section name. If
the target of the link is a format which does not have many sections
(e.g., `a.out') or has sections without names (e.g., the Oasys format),
the link cannot be done simply. You can circumvent this problem by
describing the desired input-to-output section mapping with the linker
command language.

   _Information can be lost during canonicalization._ The BFD internal
canonical form of the external formats is not exhaustive; there are
structures in input formats for which there is no direct representation
internally.  This means that the BFD back ends cannot maintain all
possible data richness through the transformation between external to
internal and back to external formats.

   This limitation is only a problem when an application reads one
format and writes another.  Each BFD back end is responsible for
maintaining as much data as possible, and the internal BFD canonical
form has structures which are opaque to the BFD core, and exported only
to the back ends. When a file is read in one format, the canonical form
is generated for BFD and the application. At the same time, the back
end saves away any information which may otherwise be lost. If the data
is then written back in the same format, the back end routine will be
able to use the canonical form provided by the BFD core as well as the
information it prepared earlier.  Since there is a great deal of
commonality between back ends, there is no information lost when
linking or copying big endian COFF to little endian COFF, or `a.out' to
`b.out'.  When a mixture of formats is linked, the information is only
lost from the files whose format differs from the destination.


File: ld.info,  Node: Canonical format,  Prev: BFD information loss,  Up: BFD outline

The BFD canonical object-file format
------------------------------------

   The greatest potential for loss of information occurs when there is
the least overlap between the information provided by the source
format, that stored by the canonical format, and that needed by the
destination format. A brief description of the canonical form may help
you understand which kinds of data you can count on preserving across
conversions.

_files_
     Information stored on a per-file basis includes target machine
     architecture, particular implementation format type, a demand
     pageable bit, and a write protected bit.  Information like Unix
     magic numbers is not stored here--only the magic numbers' meaning,
     so a `ZMAGIC' file would have both the demand pageable bit and the
     write protected text bit set.  The byte order of the target is
     stored on a per-file basis, so that big- and little-endian object
     files may be used with one another.

_sections_
     Each section in the input file contains the name of the section,
     the section's original address in the object file, size and
     alignment information, various flags, and pointers into other BFD
     data structures.

_symbols_
     Each symbol contains a pointer to the information for the object
     file which originally defined it, its name, its value, and various
     flag bits.  When a BFD back end reads in a symbol table, it
     relocates all symbols to make them relative to the base of the
     section where they were defined.  Doing this ensures that each
     symbol points to its containing section.  Each symbol also has a
     varying amount of hidden private data for the BFD back end.  Since
     the symbol points to the original file, the private data format
     for that symbol is accessible.  `ld' can operate on a collection
     of symbols of wildly different formats without problems.

     Normal global and simple local symbols are maintained on output,
     so an output file (no matter its format) will retain symbols
     pointing to functions and to global, static, and common variables.
     Some symbol information is not worth retaining; in `a.out', type
     information is stored in the symbol table as long symbol names.
     This information would be useless to most COFF debuggers; the
     linker has command line switches to allow users to throw it away.

     There is one word of type information within the symbol, so if the
     format supports symbol type information within symbols (for
     example, COFF, IEEE, Oasys) and the type is simple enough to fit
     within one word (nearly everything but aggregates), the
     information will be preserved.

_relocation level_
     Each canonical BFD relocation record contains a pointer to the
     symbol to relocate to, the offset of the data to relocate, the
     section the data is in, and a pointer to a relocation type
     descriptor. Relocation is performed by passing messages through
     the relocation type descriptor and the symbol pointer. Therefore,
     relocations can be performed on output data using a relocation
     method that is only available in one of the input formats. For
     instance, Oasys provides a byte relocation format.  A relocation
     record requesting this relocation type would point indirectly to a
     routine to perform this, so the relocation may be performed on a
     byte being written to a 68k COFF file, even though 68k COFF has no
     such relocation type.

_line numbers_
     Object formats can contain, for debugging purposes, some form of
     mapping between symbols, source line numbers, and addresses in the
     output file.  These addresses have to be relocated along with the
     symbol information.  Each symbol with an associated list of line
     number records points to the first record of the list.  The head
     of a line number list consists of a pointer to the symbol, which
     allows finding out the address of the function whose line number
     is being described. The rest of the list is made up of pairs:
     offsets into the section and line numbers. Any format which can
     simply derive this information can pass it successfully between
     formats (COFF, IEEE and Oasys).


File: ld.info,  Node: Reporting Bugs,  Next: MRI,  Prev: BFD,  Up: Top

Reporting Bugs
**************

   Your bug reports play an essential role in making `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 `ld' work
better.  Bug reports are your contribution to the maintenance of `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