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

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: 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; this is done using wildcard patterns, so that any
symbol whose name begins with `old', `original', or `new' is matched.
The wildcard patterns available are the same as those used in the shell
when matching filenames (also known as "globbing").

   Next, the version script defines node `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.

   Node name can be omited, provided it is the only version node in the
version script.  Such version script doesn't assign any versions to
symbols, only selects which symbols will be globally visible out and
which won't.

     { global: foo; bar; local: *; };

   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.