Home | History | Annotate | Download | only in info
      1 This is ld.info, produced by makeinfo version 4.11 from /home/jingyu/projects/gcc/android-toolchainsrc/build/../binutils/binutils-2.19/ld/ld.texinfo.
      2 
      3 START-INFO-DIR-ENTRY
      4 * Ld: (ld).                       The GNU linker.
      5 END-INFO-DIR-ENTRY
      6 
      7    This file documents the GNU linker LD (GNU Binutils) version 2.19.
      8 
      9    Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
     10 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
     11 
     12    Permission is granted to copy, distribute and/or modify this document
     13 under the terms of the GNU Free Documentation License, Version 1.1 or
     14 any later version published by the Free Software Foundation; with no
     15 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
     16 Texts.  A copy of the license is included in the section entitled "GNU
     17 Free Documentation License".
     18 
     19 
     20 File: ld.info,  Node: Top,  Next: Overview,  Up: (dir)
     21 
     22 LD
     23 **
     24 
     25 This file documents the GNU linker ld (GNU Binutils) version 2.19.
     26 
     27    This document is distributed under the terms of the GNU Free
     28 Documentation License.  A copy of the license is included in the
     29 section entitled "GNU Free Documentation License".
     30 
     31 * Menu:
     32 
     33 * Overview::                    Overview
     34 * Invocation::                  Invocation
     35 * Scripts::                     Linker Scripts
     36 
     37 * Machine Dependent::           Machine Dependent Features
     38 
     39 * BFD::                         BFD
     40 
     41 * Reporting Bugs::              Reporting Bugs
     42 * MRI::                         MRI Compatible Script Files
     43 * GNU Free Documentation License::  GNU Free Documentation License
     44 * LD Index::                       LD Index
     45 
     46 
     47 File: ld.info,  Node: Overview,  Next: Invocation,  Prev: Top,  Up: Top
     48 
     49 1 Overview
     50 **********
     51 
     52 `ld' combines a number of object and archive files, relocates their
     53 data and ties up symbol references. Usually the last step in compiling
     54 a program is to run `ld'.
     55 
     56    `ld' accepts Linker Command Language files written in a superset of
     57 AT&T's Link Editor Command Language syntax, to provide explicit and
     58 total control over the linking process.
     59 
     60    This version of `ld' uses the general purpose BFD libraries to
     61 operate on object files. This allows `ld' to read, combine, and write
     62 object files in many different formats--for example, COFF or `a.out'.
     63 Different formats may be linked together to produce any available kind
     64 of object file.  *Note BFD::, for more information.
     65 
     66    Aside from its flexibility, the GNU linker is more helpful than other
     67 linkers in providing diagnostic information.  Many linkers abandon
     68 execution immediately upon encountering an error; whenever possible,
     69 `ld' continues executing, allowing you to identify other errors (or, in
     70 some cases, to get an output file in spite of the error).
     71 
     72 
     73 File: ld.info,  Node: Invocation,  Next: Scripts,  Prev: Overview,  Up: Top
     74 
     75 2 Invocation
     76 ************
     77 
     78 The GNU linker `ld' is meant to cover a broad range of situations, and
     79 to be as compatible as possible with other linkers.  As a result, you
     80 have many choices to control its behavior.
     81 
     82 * Menu:
     83 
     84 * Options::                     Command Line Options
     85 * Environment::                 Environment Variables
     86 
     87 
     88 File: ld.info,  Node: Options,  Next: Environment,  Up: Invocation
     89 
     90 2.1 Command Line Options
     91 ========================
     92 
     93    The linker supports a plethora of command-line options, but in actual
     94 practice few of them are used in any particular context.  For instance,
     95 a frequent use of `ld' is to link standard Unix object files on a
     96 standard, supported Unix system.  On such a system, to link a file
     97 `hello.o':
     98 
     99      ld -o OUTPUT /lib/crt0.o hello.o -lc
    100 
    101    This tells `ld' to produce a file called OUTPUT as the result of
    102 linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
    103 which will come from the standard search directories.  (See the
    104 discussion of the `-l' option below.)
    105 
    106    Some of the command-line options to `ld' may be specified at any
    107 point in the command line.  However, options which refer to files, such
    108 as `-l' or `-T', cause the file to be read at the point at which the
    109 option appears in the command line, relative to the object files and
    110 other file options.  Repeating non-file options with a different
    111 argument will either have no further effect, or override prior
    112 occurrences (those further to the left on the command line) of that
    113 option.  Options which may be meaningfully specified more than once are
    114 noted in the descriptions below.
    115 
    116    Non-option arguments are object files or archives which are to be
    117 linked together.  They may follow, precede, or be mixed in with
    118 command-line options, except that an object file argument may not be
    119 placed between an option and its argument.
    120 
    121    Usually the linker is invoked with at least one object file, but you
    122 can specify other forms of binary input files using `-l', `-R', and the
    123 script command language.  If _no_ binary input files at all are
    124 specified, the linker does not produce any output, and issues the
    125 message `No input files'.
    126 
    127    If the linker cannot recognize the format of an object file, it will
    128 assume that it is a linker script.  A script specified in this way
    129 augments the main linker script used for the link (either the default
    130 linker script or the one specified by using `-T').  This feature
    131 permits the linker to link against a file which appears to be an object
    132 or an archive, but actually merely defines some symbol values, or uses
    133 `INPUT' or `GROUP' to load other objects.  Specifying a script in this
    134 way merely augments the main linker script, with the extra commands
    135 placed after the main script; use the `-T' option to replace the
    136 default linker script entirely, but note the effect of the `INSERT'
    137 command.  *Note Scripts::.
    138 
    139    For options whose names are a single letter, option arguments must
    140 either follow the option letter without intervening whitespace, or be
    141 given as separate arguments immediately following the option that
    142 requires them.
    143 
    144    For options whose names are multiple letters, either one dash or two
    145 can precede the option name; for example, `-trace-symbol' and
    146 `--trace-symbol' are equivalent.  Note--there is one exception to this
    147 rule.  Multiple letter options that start with a lower case 'o' can
    148 only be preceded by two dashes.  This is to reduce confusion with the
    149 `-o' option.  So for example `-omagic' sets the output file name to
    150 `magic' whereas `--omagic' sets the NMAGIC flag on the output.
    151 
    152    Arguments to multiple-letter options must either be separated from
    153 the option name by an equals sign, or be given as separate arguments
    154 immediately following the option that requires them.  For example,
    155 `--trace-symbol foo' and `--trace-symbol=foo' are equivalent.  Unique
    156 abbreviations of the names of multiple-letter options are accepted.
    157 
    158    Note--if the linker is being invoked indirectly, via a compiler
    159 driver (e.g. `gcc') then all the linker command line options should be
    160 prefixed by `-Wl,' (or whatever is appropriate for the particular
    161 compiler driver) like this:
    162 
    163        gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
    164 
    165    This is important, because otherwise the compiler driver program may
    166 silently drop the linker options, resulting in a bad link.
    167 
    168    Here is a table of the generic command line switches accepted by the
    169 GNU linker:
    170 
    171 `@FILE'
    172      Read command-line options from FILE.  The options read are
    173      inserted in place of the original @FILE option.  If FILE does not
    174      exist, or cannot be read, then the option will be treated
    175      literally, and not removed.
    176 
    177      Options in FILE are separated by whitespace.  A whitespace
    178      character may be included in an option by surrounding the entire
    179      option in either single or double quotes.  Any character
    180      (including a backslash) may be included by prefixing the character
    181      to be included with a backslash.  The FILE may itself contain
    182      additional @FILE options; any such options will be processed
    183      recursively.
    184 
    185 `-aKEYWORD'
    186      This option is supported for HP/UX compatibility.  The KEYWORD
    187      argument must be one of the strings `archive', `shared', or
    188      `default'.  `-aarchive' is functionally equivalent to `-Bstatic',
    189      and the other two keywords are functionally equivalent to
    190      `-Bdynamic'.  This option may be used any number of times.
    191 
    192 `-AARCHITECTURE'
    193 `--architecture=ARCHITECTURE'
    194      In the current release of `ld', this option is useful only for the
    195      Intel 960 family of architectures.  In that `ld' configuration, the
    196      ARCHITECTURE argument identifies the particular architecture in
    197      the 960 family, enabling some safeguards and modifying the
    198      archive-library search path.  *Note `ld' and the Intel 960 family:
    199      i960, for details.
    200 
    201      Future releases of `ld' may support similar functionality for
    202      other architecture families.
    203 
    204 `-b INPUT-FORMAT'
    205 `--format=INPUT-FORMAT'
    206      `ld' may be configured to support more than one kind of object
    207      file.  If your `ld' is configured this way, you can use the `-b'
    208      option to specify the binary format for input object files that
    209      follow this option on the command line.  Even when `ld' is
    210      configured to support alternative object formats, you don't
    211      usually need to specify this, as `ld' should be configured to
    212      expect as a default input format the most usual format on each
    213      machine.  INPUT-FORMAT is a text string, the name of a particular
    214      format supported by the BFD libraries.  (You can list the
    215      available binary formats with `objdump -i'.)  *Note BFD::.
    216 
    217      You may want to use this option if you are linking files with an
    218      unusual binary format.  You can also use `-b' to switch formats
    219      explicitly (when linking object files of different formats), by
    220      including `-b INPUT-FORMAT' before each group of object files in a
    221      particular format.
    222 
    223      The default format is taken from the environment variable
    224      `GNUTARGET'.  *Note Environment::.  You can also define the input
    225      format from a script, using the command `TARGET'; see *note Format
    226      Commands::.
    227 
    228 `-c MRI-COMMANDFILE'
    229 `--mri-script=MRI-COMMANDFILE'
    230      For compatibility with linkers produced by MRI, `ld' accepts script
    231      files written in an alternate, restricted command language,
    232      described in *note MRI Compatible Script Files: MRI.  Introduce
    233      MRI script files with the option `-c'; use the `-T' option to run
    234      linker scripts written in the general-purpose `ld' scripting
    235      language.  If MRI-CMDFILE does not exist, `ld' looks for it in the
    236      directories specified by any `-L' options.
    237 
    238 `-d'
    239 `-dc'
    240 `-dp'
    241      These three options are equivalent; multiple forms are supported
    242      for compatibility with other linkers.  They assign space to common
    243      symbols even if a relocatable output file is specified (with
    244      `-r').  The script command `FORCE_COMMON_ALLOCATION' has the same
    245      effect.  *Note Miscellaneous Commands::.
    246 
    247 `-e ENTRY'
    248 `--entry=ENTRY'
    249      Use ENTRY as the explicit symbol for beginning execution of your
    250      program, rather than the default entry point.  If there is no
    251      symbol named ENTRY, the linker will try to parse ENTRY as a number,
    252      and use that as the entry address (the number will be interpreted
    253      in base 10; you may use a leading `0x' for base 16, or a leading
    254      `0' for base 8).  *Note Entry Point::, for a discussion of defaults
    255      and other ways of specifying the entry point.
    256 
    257 `--exclude-libs LIB,LIB,...'
    258      Specifies a list of archive libraries from which symbols should
    259      not be automatically exported. The library names may be delimited
    260      by commas or colons.  Specifying `--exclude-libs ALL' excludes
    261      symbols in all archive libraries from automatic export.  This
    262      option is available only for the i386 PE targeted port of the
    263      linker and for ELF targeted ports.  For i386 PE, symbols
    264      explicitly listed in a .def file are still exported, regardless of
    265      this option.  For ELF targeted ports, symbols affected by this
    266      option will be treated as hidden.
    267 
    268 `-E'
    269 `--export-dynamic'
    270      When creating a dynamically linked executable, add all symbols to
    271      the dynamic symbol table.  The dynamic symbol table is the set of
    272      symbols which are visible from dynamic objects at run time.
    273 
    274      If you do not use this option, the dynamic symbol table will
    275      normally contain only those symbols which are referenced by some
    276      dynamic object mentioned in the link.
    277 
    278      If you use `dlopen' to load a dynamic object which needs to refer
    279      back to the symbols defined by the program, rather than some other
    280      dynamic object, then you will probably need to use this option when
    281      linking the program itself.
    282 
    283      You can also use the dynamic list to control what symbols should
    284      be added to the dynamic symbol table if the output format supports
    285      it.  See the description of `--dynamic-list'.
    286 
    287 `-EB'
    288      Link big-endian objects.  This affects the default output format.
    289 
    290 `-EL'
    291      Link little-endian objects.  This affects the default output
    292      format.
    293 
    294 `-f'
    295 `--auxiliary NAME'
    296      When creating an ELF shared object, set the internal DT_AUXILIARY
    297      field to the specified name.  This tells the dynamic linker that
    298      the symbol table of the shared object should be used as an
    299      auxiliary filter on the symbol table of the shared object NAME.
    300 
    301      If you later link a program against this filter object, then, when
    302      you run the program, the dynamic linker will see the DT_AUXILIARY
    303      field.  If the dynamic linker resolves any symbols from the filter
    304      object, it will first check whether there is a definition in the
    305      shared object NAME.  If there is one, it will be used instead of
    306      the definition in the filter object.  The shared object NAME need
    307      not exist.  Thus the shared object NAME may be used to provide an
    308      alternative implementation of certain functions, perhaps for
    309      debugging or for machine specific performance.
    310 
    311      This option may be specified more than once.  The DT_AUXILIARY
    312      entries will be created in the order in which they appear on the
    313      command line.
    314 
    315 `-F NAME'
    316 `--filter NAME'
    317      When creating an ELF shared object, set the internal DT_FILTER
    318      field to the specified name.  This tells the dynamic linker that
    319      the symbol table of the shared object which is being created
    320      should be used as a filter on the symbol table of the shared
    321      object NAME.
    322 
    323      If you later link a program against this filter object, then, when
    324      you run the program, the dynamic linker will see the DT_FILTER
    325      field.  The dynamic linker will resolve symbols according to the
    326      symbol table of the filter object as usual, but it will actually
    327      link to the definitions found in the shared object NAME.  Thus the
    328      filter object can be used to select a subset of the symbols
    329      provided by the object NAME.
    330 
    331      Some older linkers used the `-F' option throughout a compilation
    332      toolchain for specifying object-file format for both input and
    333      output object files.  The GNU linker uses other mechanisms for
    334      this purpose: the `-b', `--format', `--oformat' options, the
    335      `TARGET' command in linker scripts, and the `GNUTARGET'
    336      environment variable.  The GNU linker will ignore the `-F' option
    337      when not creating an ELF shared object.
    338 
    339 `-fini NAME'
    340      When creating an ELF executable or shared object, call NAME when
    341      the executable or shared object is unloaded, by setting DT_FINI to
    342      the address of the function.  By default, the linker uses `_fini'
    343      as the function to call.
    344 
    345 `-g'
    346      Ignored.  Provided for compatibility with other tools.
    347 
    348 `-GVALUE'
    349 `--gpsize=VALUE'
    350      Set the maximum size of objects to be optimized using the GP
    351      register to SIZE.  This is only meaningful for object file formats
    352      such as MIPS ECOFF which supports putting large and small objects
    353      into different sections.  This is ignored for other object file
    354      formats.
    355 
    356 `-hNAME'
    357 `-soname=NAME'
    358      When creating an ELF shared object, set the internal DT_SONAME
    359      field to the specified name.  When an executable is linked with a
    360      shared object which has a DT_SONAME field, then when the
    361      executable is run the dynamic linker will attempt to load the
    362      shared object specified by the DT_SONAME field rather than the
    363      using the file name given to the linker.
    364 
    365 `-i'
    366      Perform an incremental link (same as option `-r').
    367 
    368 `-init NAME'
    369      When creating an ELF executable or shared object, call NAME when
    370      the executable or shared object is loaded, by setting DT_INIT to
    371      the address of the function.  By default, the linker uses `_init'
    372      as the function to call.
    373 
    374 `-lNAMESPEC'
    375 `--library=NAMESPEC'
    376      Add the archive or object file specified by NAMESPEC to the list
    377      of files to link.  This option may be used any number of times.
    378      If NAMESPEC is of the form `:FILENAME', `ld' will search the
    379      library path for a file called FILENAME, otherise it will search
    380      the library path for a file called `libNAMESPEC.a'.
    381 
    382      On systems which support shared libraries, `ld' may also search for
    383      files other than `libNAMESPEC.a'.  Specifically, on ELF and SunOS
    384      systems, `ld' will search a directory for a library called
    385      `libNAMESPEC.so' before searching for one called `libNAMESPEC.a'.
    386      (By convention, a `.so' extension indicates a shared library.)
    387      Note that this behavior does not apply to `:FILENAME', which
    388      always specifies a file called FILENAME.
    389 
    390      The linker will search an archive only once, at the location where
    391      it is specified on the command line.  If the archive defines a
    392      symbol which was undefined in some object which appeared before
    393      the archive on the command line, the linker will include the
    394      appropriate file(s) from the archive.  However, an undefined
    395      symbol in an object appearing later on the command line will not
    396      cause the linker to search the archive again.
    397 
    398      See the `-(' option for a way to force the linker to search
    399      archives multiple times.
    400 
    401      You may list the same archive multiple times on the command line.
    402 
    403      This type of archive searching is standard for Unix linkers.
    404      However, if you are using `ld' on AIX, note that it is different
    405      from the behaviour of the AIX linker.
    406 
    407 `-LSEARCHDIR'
    408 `--library-path=SEARCHDIR'
    409      Add path SEARCHDIR to the list of paths that `ld' will search for
    410      archive libraries and `ld' control scripts.  You may use this
    411      option any number of times.  The directories are searched in the
    412      order in which they are specified on the command line.
    413      Directories specified on the command line are searched before the
    414      default directories.  All `-L' options apply to all `-l' options,
    415      regardless of the order in which the options appear.
    416 
    417      If SEARCHDIR begins with `=', then the `=' will be replaced by the
    418      "sysroot prefix", a path specified when the linker is configured.
    419 
    420      The default set of paths searched (without being specified with
    421      `-L') depends on which emulation mode `ld' is using, and in some
    422      cases also on how it was configured.  *Note Environment::.
    423 
    424      The paths can also be specified in a link script with the
    425      `SEARCH_DIR' command.  Directories specified this way are searched
    426      at the point in which the linker script appears in the command
    427      line.
    428 
    429 `-mEMULATION'
    430      Emulate the EMULATION linker.  You can list the available
    431      emulations with the `--verbose' or `-V' options.
    432 
    433      If the `-m' option is not used, the emulation is taken from the
    434      `LDEMULATION' environment variable, if that is defined.
    435 
    436      Otherwise, the default emulation depends upon how the linker was
    437      configured.
    438 
    439 `-M'
    440 `--print-map'
    441      Print a link map to the standard output.  A link map provides
    442      information about the link, including the following:
    443 
    444         * Where object files are mapped into memory.
    445 
    446         * How common symbols are allocated.
    447 
    448         * All archive members included in the link, with a mention of
    449           the symbol which caused the archive member to be brought in.
    450 
    451         * The values assigned to symbols.
    452 
    453           Note - symbols whose values are computed by an expression
    454           which involves a reference to a previous value of the same
    455           symbol may not have correct result displayed in the link map.
    456           This is because the linker discards intermediate results and
    457           only retains the final value of an expression.  Under such
    458           circumstances the linker will display the final value
    459           enclosed by square brackets.  Thus for example a linker
    460           script containing:
    461 
    462                   foo = 1
    463                   foo = foo * 4
    464                   foo = foo + 8
    465 
    466           will produce the following output in the link map if the `-M'
    467           option is used:
    468 
    469                   0x00000001                foo = 0x1
    470                   [0x0000000c]                foo = (foo * 0x4)
    471                   [0x0000000c]                foo = (foo + 0x8)
    472 
    473           See *note Expressions:: for more information about
    474           expressions in linker scripts.
    475 
    476 `-n'
    477 `--nmagic'
    478      Turn off page alignment of sections, and mark the output as
    479      `NMAGIC' if possible.
    480 
    481 `-N'
    482 `--omagic'
    483      Set the text and data sections to be readable and writable.  Also,
    484      do not page-align the data segment, and disable linking against
    485      shared libraries.  If the output format supports Unix style magic
    486      numbers, mark the output as `OMAGIC'. Note: Although a writable
    487      text section is allowed for PE-COFF targets, it does not conform
    488      to the format specification published by Microsoft.
    489 
    490 `--no-omagic'
    491      This option negates most of the effects of the `-N' option.  It
    492      sets the text section to be read-only, and forces the data segment
    493      to be page-aligned.  Note - this option does not enable linking
    494      against shared libraries.  Use `-Bdynamic' for this.
    495 
    496 `-o OUTPUT'
    497 `--output=OUTPUT'
    498      Use OUTPUT as the name for the program produced by `ld'; if this
    499      option is not specified, the name `a.out' is used by default.  The
    500      script command `OUTPUT' can also specify the output file name.
    501 
    502 `-O LEVEL'
    503      If LEVEL is a numeric values greater than zero `ld' optimizes the
    504      output.  This might take significantly longer and therefore
    505      probably should only be enabled for the final binary.  At the
    506      moment this option only affects ELF shared library generation.
    507      Future releases of the linker may make more use of this option.
    508      Also currently there is no difference in the linker's behaviour
    509      for different non-zero values of this option.  Again this may
    510      change with future releases.
    511 
    512 `-q'
    513 `--emit-relocs'
    514      Leave relocation sections and contents in fully linked executables.
    515      Post link analysis and optimization tools may need this
    516      information in order to perform correct modifications of
    517      executables.  This results in larger executables.
    518 
    519      This option is currently only supported on ELF platforms.
    520 
    521 `--force-dynamic'
    522      Force the output file to have dynamic sections.  This option is
    523      specific to VxWorks targets.
    524 
    525 `-r'
    526 `--relocatable'
    527      Generate relocatable output--i.e., generate an output file that
    528      can in turn serve as input to `ld'.  This is often called "partial
    529      linking".  As a side effect, in environments that support standard
    530      Unix magic numbers, this option also sets the output file's magic
    531      number to `OMAGIC'.  If this option is not specified, an absolute
    532      file is produced.  When linking C++ programs, this option _will
    533      not_ resolve references to constructors; to do that, use `-Ur'.
    534 
    535      When an input file does not have the same format as the output
    536      file, partial linking is only supported if that input file does
    537      not contain any relocations.  Different output formats can have
    538      further restrictions; for example some `a.out'-based formats do
    539      not support partial linking with input files in other formats at
    540      all.
    541 
    542      This option does the same thing as `-i'.
    543 
    544 `-R FILENAME'
    545 `--just-symbols=FILENAME'
    546      Read symbol names and their addresses from FILENAME, but do not
    547      relocate it or include it in the output.  This allows your output
    548      file to refer symbolically to absolute locations of memory defined
    549      in other programs.  You may use this option more than once.
    550 
    551      For compatibility with other ELF linkers, if the `-R' option is
    552      followed by a directory name, rather than a file name, it is
    553      treated as the `-rpath' option.
    554 
    555 `-s'
    556 `--strip-all'
    557      Omit all symbol information from the output file.
    558 
    559 `-S'
    560 `--strip-debug'
    561      Omit debugger symbol information (but not all symbols) from the
    562      output file.
    563 
    564 `-t'
    565 `--trace'
    566      Print the names of the input files as `ld' processes them.
    567 
    568 `-T SCRIPTFILE'
    569 `--script=SCRIPTFILE'
    570      Use SCRIPTFILE as the linker script.  This script replaces `ld''s
    571      default linker script (rather than adding to it), so COMMANDFILE
    572      must specify everything necessary to describe the output file.
    573      *Note Scripts::.  If SCRIPTFILE does not exist in the current
    574      directory, `ld' looks for it in the directories specified by any
    575      preceding `-L' options.  Multiple `-T' options accumulate.
    576 
    577 `-dT SCRIPTFILE'
    578 `--default-script=SCRIPTFILE'
    579      Use SCRIPTFILE as the default linker script.  *Note Scripts::.
    580 
    581      This option is similar to the `--script' option except that
    582      processing of the script is delayed until after the rest of the
    583      command line has been processed.  This allows options placed after
    584      the `--default-script' option on the command line to affect the
    585      behaviour of the linker script, which can be important when the
    586      linker command line cannot be directly controlled by the user.
    587      (eg because the command line is being constructed by another tool,
    588      such as `gcc').
    589 
    590 `-u SYMBOL'
    591 `--undefined=SYMBOL'
    592      Force SYMBOL to be entered in the output file as an undefined
    593      symbol.  Doing this may, for example, trigger linking of additional
    594      modules from standard libraries.  `-u' may be repeated with
    595      different option arguments to enter additional undefined symbols.
    596      This option is equivalent to the `EXTERN' linker script command.
    597 
    598 `-Ur'
    599      For anything other than C++ programs, this option is equivalent to
    600      `-r': it generates relocatable output--i.e., an output file that
    601      can in turn serve as input to `ld'.  When linking C++ programs,
    602      `-Ur' _does_ resolve references to constructors, unlike `-r'.  It
    603      does not work to use `-Ur' on files that were themselves linked
    604      with `-Ur'; once the constructor table has been built, it cannot
    605      be added to.  Use `-Ur' only for the last partial link, and `-r'
    606      for the others.
    607 
    608 `--unique[=SECTION]'
    609      Creates a separate output section for every input section matching
    610      SECTION, or if the optional wildcard SECTION argument is missing,
    611      for every orphan input section.  An orphan section is one not
    612      specifically mentioned in a linker script.  You may use this option
    613      multiple times on the command line;  It prevents the normal
    614      merging of input sections with the same name, overriding output
    615      section assignments in a linker script.
    616 
    617 `-v'
    618 `--version'
    619 `-V'
    620      Display the version number for `ld'.  The `-V' option also lists
    621      the supported emulations.
    622 
    623 `-x'
    624 `--discard-all'
    625      Delete all local symbols.
    626 
    627 `-X'
    628 `--discard-locals'
    629      Delete all temporary local symbols.  (These symbols start with
    630      system-specific local label prefixes, typically `.L' for ELF
    631      systems or `L' for traditional a.out systems.)
    632 
    633 `-y SYMBOL'
    634 `--trace-symbol=SYMBOL'
    635      Print the name of each linked file in which SYMBOL appears.  This
    636      option may be given any number of times.  On many systems it is
    637      necessary to prepend an underscore.
    638 
    639      This option is useful when you have an undefined symbol in your
    640      link but don't know where the reference is coming from.
    641 
    642 `-Y PATH'
    643      Add PATH to the default library search path.  This option exists
    644      for Solaris compatibility.
    645 
    646 `-z KEYWORD'
    647      The recognized keywords are:
    648     `combreloc'
    649           Combines multiple reloc sections and sorts them to make
    650           dynamic symbol lookup caching possible.
    651 
    652     `defs'
    653           Disallows undefined symbols in object files.  Undefined
    654           symbols in shared libraries are still allowed.
    655 
    656     `execstack'
    657           Marks the object as requiring executable stack.
    658 
    659     `initfirst'
    660           This option is only meaningful when building a shared object.
    661           It marks the object so that its runtime initialization will
    662           occur before the runtime initialization of any other objects
    663           brought into the process at the same time.  Similarly the
    664           runtime finalization of the object will occur after the
    665           runtime finalization of any other objects.
    666 
    667     `interpose'
    668           Marks the object that its symbol table interposes before all
    669           symbols but the primary executable.
    670 
    671     `lazy'
    672           When generating an executable or shared library, mark it to
    673           tell the dynamic linker to defer function call resolution to
    674           the point when the function is called (lazy binding), rather
    675           than at load time.  Lazy binding is the default.
    676 
    677     `loadfltr'
    678           Marks  the object that its filters be processed immediately at
    679           runtime.
    680 
    681     `muldefs'
    682           Allows multiple definitions.
    683 
    684     `nocombreloc'
    685           Disables multiple reloc sections combining.
    686 
    687     `nocopyreloc'
    688           Disables production of copy relocs.
    689 
    690     `nodefaultlib'
    691           Marks the object that the search for dependencies of this
    692           object will ignore any default library search paths.
    693 
    694     `nodelete'
    695           Marks the object shouldn't be unloaded at runtime.
    696 
    697     `nodlopen'
    698           Marks the object not available to `dlopen'.
    699 
    700     `nodump'
    701           Marks the object can not be dumped by `dldump'.
    702 
    703     `noexecstack'
    704           Marks the object as not requiring executable stack.
    705 
    706     `norelro'
    707           Don't create an ELF `PT_GNU_RELRO' segment header in the
    708           object.
    709 
    710     `now'
    711           When generating an executable or shared library, mark it to
    712           tell the dynamic linker to resolve all symbols when the
    713           program is started, or when the shared library is linked to
    714           using dlopen, instead of deferring function call resolution
    715           to the point when the function is first called.
    716 
    717     `origin'
    718           Marks the object may contain $ORIGIN.
    719 
    720     `relro'
    721           Create an ELF `PT_GNU_RELRO' segment header in the object.
    722 
    723     `max-page-size=VALUE'
    724           Set the emulation maximum page size to VALUE.
    725 
    726     `common-page-size=VALUE'
    727           Set the emulation common page size to VALUE.
    728 
    729 
    730      Other keywords are ignored for Solaris compatibility.
    731 
    732 `-( ARCHIVES -)'
    733 `--start-group ARCHIVES --end-group'
    734      The ARCHIVES should be a list of archive files.  They may be
    735      either explicit file names, or `-l' options.
    736 
    737      The specified archives are searched repeatedly until no new
    738      undefined references are created.  Normally, an archive is
    739      searched only once in the order that it is specified on the
    740      command line.  If a symbol in that archive is needed to resolve an
    741      undefined symbol referred to by an object in an archive that
    742      appears later on the command line, the linker would not be able to
    743      resolve that reference.  By grouping the archives, they all be
    744      searched repeatedly until all possible references are resolved.
    745 
    746      Using this option has a significant performance cost.  It is best
    747      to use it only when there are unavoidable circular references
    748      between two or more archives.
    749 
    750 `--accept-unknown-input-arch'
    751 `--no-accept-unknown-input-arch'
    752      Tells the linker to accept input files whose architecture cannot be
    753      recognised.  The assumption is that the user knows what they are
    754      doing and deliberately wants to link in these unknown input files.
    755      This was the default behaviour of the linker, before release 2.14.
    756      The default behaviour from release 2.14 onwards is to reject such
    757      input files, and so the `--accept-unknown-input-arch' option has
    758      been added to restore the old behaviour.
    759 
    760 `--as-needed'
    761 `--no-as-needed'
    762      This option affects ELF DT_NEEDED tags for dynamic libraries
    763      mentioned on the command line after the `--as-needed' option.
    764      Normally, the linker will add a DT_NEEDED tag for each dynamic
    765      library mentioned on the command line, regardless of whether the
    766      library is actually needed.  `--as-needed' causes DT_NEEDED tags
    767      to only be emitted for libraries that satisfy some symbol
    768      reference from regular objects which is undefined at the point
    769      that the library was linked.  `--no-as-needed' restores the
    770      default behaviour.
    771 
    772 `--add-needed'
    773 `--no-add-needed'
    774      This option affects the treatment of dynamic libraries from ELF
    775      DT_NEEDED tags in dynamic libraries mentioned on the command line
    776      after the `--no-add-needed' option.  Normally, the linker will add
    777      a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
    778      `--no-add-needed' causes DT_NEEDED tags will never be emitted for
    779      those libraries from DT_NEEDED tags. `--add-needed' restores the
    780      default behaviour.
    781 
    782 `-assert KEYWORD'
    783      This option is ignored for SunOS compatibility.
    784 
    785 `-Bdynamic'
    786 `-dy'
    787 `-call_shared'
    788      Link against dynamic libraries.  This is only meaningful on
    789      platforms for which shared libraries are supported.  This option
    790      is normally the default on such platforms.  The different variants
    791      of this option are for compatibility with various systems.  You
    792      may use this option multiple times on the command line: it affects
    793      library searching for `-l' options which follow it.
    794 
    795 `-Bgroup'
    796      Set the `DF_1_GROUP' flag in the `DT_FLAGS_1' entry in the dynamic
    797      section.  This causes the runtime linker to handle lookups in this
    798      object and its dependencies to be performed only inside the group.
    799      `--unresolved-symbols=report-all' is implied.  This option is only
    800      meaningful on ELF platforms which support shared libraries.
    801 
    802 `-Bstatic'
    803 `-dn'
    804 `-non_shared'
    805 `-static'
    806      Do not link against shared libraries.  This is only meaningful on
    807      platforms for which shared libraries are supported.  The different
    808      variants of this option are for compatibility with various
    809      systems.  You may use this option multiple times on the command
    810      line: it affects library searching for `-l' options which follow
    811      it.  This option also implies `--unresolved-symbols=report-all'.
    812      This option can be used with `-shared'.  Doing so means that a
    813      shared library is being created but that all of the library's
    814      external references must be resolved by pulling in entries from
    815      static libraries.
    816 
    817 `-Bsymbolic'
    818      When creating a shared library, bind references to global symbols
    819      to the definition within the shared library, if any.  Normally, it
    820      is possible for a program linked against a shared library to
    821      override the definition within the shared library.  This option is
    822      only meaningful on ELF platforms which support shared libraries.
    823 
    824 `-Bsymbolic-functions'
    825      When creating a shared library, bind references to global function
    826      symbols to the definition within the shared library, if any.  This
    827      option is only meaningful on ELF platforms which support shared
    828      libraries.
    829 
    830 `--dynamic-list=DYNAMIC-LIST-FILE'
    831      Specify the name of a dynamic list file to the linker.  This is
    832      typically used when creating shared libraries to specify a list of
    833      global symbols whose references shouldn't be bound to the
    834      definition within the shared library, or creating dynamically
    835      linked executables to specify a list of symbols which should be
    836      added to the symbol table in the executable.  This option is only
    837      meaningful on ELF platforms which support shared libraries.
    838 
    839      The format of the dynamic list is the same as the version node
    840      without scope and node name.  See *note VERSION:: for more
    841      information.
    842 
    843 `--dynamic-list-data'
    844      Include all global data symbols to the dynamic list.
    845 
    846 `--dynamic-list-cpp-new'
    847      Provide the builtin dynamic list for C++ operator new and delete.
    848      It is mainly useful for building shared libstdc++.
    849 
    850 `--dynamic-list-cpp-typeinfo'
    851      Provide the builtin dynamic list for C++ runtime type
    852      identification.
    853 
    854 `--check-sections'
    855 `--no-check-sections'
    856      Asks the linker _not_ to check section addresses after they have
    857      been assigned to see if there are any overlaps.  Normally the
    858      linker will perform this check, and if it finds any overlaps it
    859      will produce suitable error messages.  The linker does know about,
    860      and does make allowances for sections in overlays.  The default
    861      behaviour can be restored by using the command line switch
    862      `--check-sections'.
    863 
    864 `--cref'
    865      Output a cross reference table.  If a linker map file is being
    866      generated, the cross reference table is printed to the map file.
    867      Otherwise, it is printed on the standard output.
    868 
    869      The format of the table is intentionally simple, so that it may be
    870      easily processed by a script if necessary.  The symbols are
    871      printed out, sorted by name.  For each symbol, a list of file
    872      names is given.  If the symbol is defined, the first file listed
    873      is the location of the definition.  The remaining files contain
    874      references to the symbol.
    875 
    876 `--no-define-common'
    877      This option inhibits the assignment of addresses to common symbols.
    878      The script command `INHIBIT_COMMON_ALLOCATION' has the same effect.
    879      *Note Miscellaneous Commands::.
    880 
    881      The `--no-define-common' option allows decoupling the decision to
    882      assign addresses to Common symbols from the choice of the output
    883      file type; otherwise a non-Relocatable output type forces
    884      assigning addresses to Common symbols.  Using `--no-define-common'
    885      allows Common symbols that are referenced from a shared library to
    886      be assigned addresses only in the main program.  This eliminates
    887      the unused duplicate space in the shared library, and also
    888      prevents any possible confusion over resolving to the wrong
    889      duplicate when there are many dynamic modules with specialized
    890      search paths for runtime symbol resolution.
    891 
    892 `--defsym SYMBOL=EXPRESSION'
    893      Create a global symbol in the output file, containing the absolute
    894      address given by EXPRESSION.  You may use this option as many
    895      times as necessary to define multiple symbols in the command line.
    896      A limited form of arithmetic is supported for the EXPRESSION in
    897      this context: you may give a hexadecimal constant or the name of
    898      an existing symbol, or use `+' and `-' to add or subtract
    899      hexadecimal constants or symbols.  If you need more elaborate
    900      expressions, consider using the linker command language from a
    901      script (*note Assignment: Symbol Definitions: Assignments.).
    902      _Note:_ there should be no white space between SYMBOL, the equals
    903      sign ("<=>"), and EXPRESSION.
    904 
    905 `--demangle[=STYLE]'
    906 `--no-demangle'
    907      These options control whether to demangle symbol names in error
    908      messages and other output.  When the linker is told to demangle,
    909      it tries to present symbol names in a readable fashion: it strips
    910      leading underscores if they are used by the object file format,
    911      and converts C++ mangled symbol names into user readable names.
    912      Different compilers have different mangling styles.  The optional
    913      demangling style argument can be used to choose an appropriate
    914      demangling style for your compiler.  The linker will demangle by
    915      default unless the environment variable `COLLECT_NO_DEMANGLE' is
    916      set.  These options may be used to override the default.
    917 
    918 `--dynamic-linker FILE'
    919      Set the name of the dynamic linker.  This is only meaningful when
    920      generating dynamically linked ELF executables.  The default dynamic
    921      linker is normally correct; don't use this unless you know what
    922      you are doing.
    923 
    924 `--fatal-warnings'
    925 `--no-fatal-warnings'
    926      Treat all warnings as errors.  The default behaviour can be
    927      restored with the option `--no-fatal-warnings'.
    928 
    929 `--force-exe-suffix'
    930      Make sure that an output file has a .exe suffix.
    931 
    932      If a successfully built fully linked output file does not have a
    933      `.exe' or `.dll' suffix, this option forces the linker to copy the
    934      output file to one of the same name with a `.exe' suffix. This
    935      option is useful when using unmodified Unix makefiles on a
    936      Microsoft Windows host, since some versions of Windows won't run
    937      an image unless it ends in a `.exe' suffix.
    938 
    939 `--gc-sections'
    940 `--no-gc-sections'
    941      Enable garbage collection of unused input sections.  It is ignored
    942      on targets that do not support this option.  The default behaviour
    943      (of not performing this garbage collection) can be restored by
    944      specifying `--no-gc-sections' on the command line.
    945 
    946      `--gc-sections' decides which input sections are used by examining
    947      symbols and relocations.  The section containing the entry symbol
    948      and all sections containing symbols undefined on the command-line
    949      will be kept, as will sections containing symbols referenced by
    950      dynamic objects.  Note that when building shared libraries, the
    951      linker must assume that any visible symbol is referenced.  Once
    952      this initial set of sections has been determined, the linker
    953      recursively marks as used any section referenced by their
    954      relocations.  See `--entry' and `--undefined'.
    955 
    956      This option can be set when doing a partial link (enabled with
    957      option `-r').  In this case the root of symbols kept must be
    958      explicitely specified either by an `--entry' or `--undefined'
    959      option or by a `ENTRY' command in the linker script.
    960 
    961 `--print-gc-sections'
    962 `--no-print-gc-sections'
    963      List all sections removed by garbage collection.  The listing is
    964      printed on stderr.  This option is only effective if garbage
    965      collection has been enabled via the `--gc-sections') option.  The
    966      default behaviour (of not listing the sections that are removed)
    967      can be restored by specifying `--no-print-gc-sections' on the
    968      command line.
    969 
    970 `--help'
    971      Print a summary of the command-line options on the standard output
    972      and exit.
    973 
    974 `--target-help'
    975      Print a summary of all target specific options on the standard
    976      output and exit.
    977 
    978 `-Map MAPFILE'
    979      Print a link map to the file MAPFILE.  See the description of the
    980      `-M' option, above.
    981 
    982 `--no-keep-memory'
    983      `ld' normally optimizes for speed over memory usage by caching the
    984      symbol tables of input files in memory.  This option tells `ld' to
    985      instead optimize for memory usage, by rereading the symbol tables
    986      as necessary.  This may be required if `ld' runs out of memory
    987      space while linking a large executable.
    988 
    989 `--no-undefined'
    990 `-z defs'
    991      Report unresolved symbol references from regular object files.
    992      This is done even if the linker is creating a non-symbolic shared
    993      library.  The switch `--[no-]allow-shlib-undefined' controls the
    994      behaviour for reporting unresolved references found in shared
    995      libraries being linked in.
    996 
    997 `--allow-multiple-definition'
    998 `-z muldefs'
    999      Normally when a symbol is defined multiple times, the linker will
   1000      report a fatal error. These options allow multiple definitions and
   1001      the first definition will be used.
   1002 
   1003 `--allow-shlib-undefined'
   1004 `--no-allow-shlib-undefined'
   1005      Allows (the default) or disallows undefined symbols in shared
   1006      libraries.  This switch is similar to `--no-undefined' except that
   1007      it determines the behaviour when the undefined symbols are in a
   1008      shared library rather than a regular object file.  It does not
   1009      affect how undefined symbols in regular object files are handled.
   1010 
   1011      The reason that `--allow-shlib-undefined' is the default is that
   1012      the shared library being specified at link time may not be the
   1013      same as the one that is available at load time, so the symbols
   1014      might actually be resolvable at load time.  Plus there are some
   1015      systems, (eg BeOS) where undefined symbols in shared libraries is
   1016      normal.  (The kernel patches them at load time to select which
   1017      function is most appropriate for the current architecture.  This
   1018      is used for example to dynamically select an appropriate memset
   1019      function).  Apparently it is also normal for HPPA shared libraries
   1020      to have undefined symbols.
   1021 
   1022 `--no-undefined-version'
   1023      Normally when a symbol has an undefined version, the linker will
   1024      ignore it. This option disallows symbols with undefined version
   1025      and a fatal error will be issued instead.
   1026 
   1027 `--default-symver'
   1028      Create and use a default symbol version (the soname) for
   1029      unversioned exported symbols.
   1030 
   1031 `--default-imported-symver'
   1032      Create and use a default symbol version (the soname) for
   1033      unversioned imported symbols.
   1034 
   1035 `--no-warn-mismatch'
   1036      Normally `ld' will give an error if you try to link together input
   1037      files that are mismatched for some reason, perhaps because they
   1038      have been compiled for different processors or for different
   1039      endiannesses.  This option tells `ld' that it should silently
   1040      permit such possible errors.  This option should only be used with
   1041      care, in cases when you have taken some special action that
   1042      ensures that the linker errors are inappropriate.
   1043 
   1044 `--no-warn-search-mismatch'
   1045      Normally `ld' will give a warning if it finds an incompatible
   1046      library during a library search.  This option silences the warning.
   1047 
   1048 `--no-whole-archive'
   1049      Turn off the effect of the `--whole-archive' option for subsequent
   1050      archive files.
   1051 
   1052 `--noinhibit-exec'
   1053      Retain the executable output file whenever it is still usable.
   1054      Normally, the linker will not produce an output file if it
   1055      encounters errors during the link process; it exits without
   1056      writing an output file when it issues any error whatsoever.
   1057 
   1058 `-nostdlib'
   1059      Only search library directories explicitly specified on the
   1060      command line.  Library directories specified in linker scripts
   1061      (including linker scripts specified on the command line) are
   1062      ignored.
   1063 
   1064 `--oformat OUTPUT-FORMAT'
   1065      `ld' may be configured to support more than one kind of object
   1066      file.  If your `ld' is configured this way, you can use the
   1067      `--oformat' option to specify the binary format for the output
   1068      object file.  Even when `ld' is configured to support alternative
   1069      object formats, you don't usually need to specify this, as `ld'
   1070      should be configured to produce as a default output format the most
   1071      usual format on each machine.  OUTPUT-FORMAT is a text string, the
   1072      name of a particular format supported by the BFD libraries.  (You
   1073      can list the available binary formats with `objdump -i'.)  The
   1074      script command `OUTPUT_FORMAT' can also specify the output format,
   1075      but this option overrides it.  *Note BFD::.
   1076 
   1077 `-pie'
   1078 `--pic-executable'
   1079      Create a position independent executable.  This is currently only
   1080      supported on ELF platforms.  Position independent executables are
   1081      similar to shared libraries in that they are relocated by the
   1082      dynamic linker to the virtual address the OS chooses for them
   1083      (which can vary between invocations).  Like normal dynamically
   1084      linked executables they can be executed and symbols defined in the
   1085      executable cannot be overridden by shared libraries.
   1086 
   1087 `-qmagic'
   1088      This option is ignored for Linux compatibility.
   1089 
   1090 `-Qy'
   1091      This option is ignored for SVR4 compatibility.
   1092 
   1093 `--relax'
   1094      An option with machine dependent effects.  This option is only
   1095      supported on a few targets.  *Note `ld' and the H8/300: H8/300.
   1096      *Note `ld' and the Intel 960 family: i960.  *Note `ld' and Xtensa
   1097      Processors: Xtensa.  *Note `ld' and the 68HC11 and 68HC12:
   1098      M68HC11/68HC12.  *Note `ld' and PowerPC 32-bit ELF Support:
   1099      PowerPC ELF32.
   1100 
   1101      On some platforms, the `--relax' option performs global
   1102      optimizations that become possible when the linker resolves
   1103      addressing in the program, such as relaxing address modes and
   1104      synthesizing new instructions in the output object file.
   1105 
   1106      On some platforms these link time global optimizations may make
   1107      symbolic debugging of the resulting executable impossible.  This
   1108      is known to be the case for the Matsushita MN10200 and MN10300
   1109      family of processors.
   1110 
   1111      On platforms where this is not supported, `--relax' is accepted,
   1112      but ignored.
   1113 
   1114 `--retain-symbols-file FILENAME'
   1115      Retain _only_ the symbols listed in the file FILENAME, discarding
   1116      all others.  FILENAME is simply a flat file, with one symbol name
   1117      per line.  This option is especially useful in environments (such
   1118      as VxWorks) where a large global symbol table is accumulated
   1119      gradually, to conserve run-time memory.
   1120 
   1121      `--retain-symbols-file' does _not_ discard undefined symbols, or
   1122      symbols needed for relocations.
   1123 
   1124      You may only specify `--retain-symbols-file' once in the command
   1125      line.  It overrides `-s' and `-S'.
   1126 
   1127 `-rpath DIR'
   1128      Add a directory to the runtime library search path.  This is used
   1129      when linking an ELF executable with shared objects.  All `-rpath'
   1130      arguments are concatenated and passed to the runtime linker, which
   1131      uses them to locate shared objects at runtime.  The `-rpath'
   1132      option is also used when locating shared objects which are needed
   1133      by shared objects explicitly included in the link; see the
   1134      description of the `-rpath-link' option.  If `-rpath' is not used
   1135      when linking an ELF executable, the contents of the environment
   1136      variable `LD_RUN_PATH' will be used if it is defined.
   1137 
   1138      The `-rpath' option may also be used on SunOS.  By default, on
   1139      SunOS, the linker will form a runtime search patch out of all the
   1140      `-L' options it is given.  If a `-rpath' option is used, the
   1141      runtime search path will be formed exclusively using the `-rpath'
   1142      options, ignoring the `-L' options.  This can be useful when using
   1143      gcc, which adds many `-L' options which may be on NFS mounted file
   1144      systems.
   1145 
   1146      For compatibility with other ELF linkers, if the `-R' option is
   1147      followed by a directory name, rather than a file name, it is
   1148      treated as the `-rpath' option.
   1149 
   1150 `-rpath-link DIR'
   1151      When using ELF or SunOS, one shared library may require another.
   1152      This happens when an `ld -shared' link includes a shared library
   1153      as one of the input files.
   1154 
   1155      When the linker encounters such a dependency when doing a
   1156      non-shared, non-relocatable link, it will automatically try to
   1157      locate the required shared library and include it in the link, if
   1158      it is not included explicitly.  In such a case, the `-rpath-link'
   1159      option specifies the first set of directories to search.  The
   1160      `-rpath-link' option may specify a sequence of directory names
   1161      either by specifying a list of names separated by colons, or by
   1162      appearing multiple times.
   1163 
   1164      This option should be used with caution as it overrides the search
   1165      path that may have been hard compiled into a shared library. In
   1166      such a case it is possible to use unintentionally a different
   1167      search path than the runtime linker would do.
   1168 
   1169      The linker uses the following search paths to locate required
   1170      shared libraries:
   1171        1. Any directories specified by `-rpath-link' options.
   1172 
   1173        2. Any directories specified by `-rpath' options.  The difference
   1174           between `-rpath' and `-rpath-link' is that directories
   1175           specified by `-rpath' options are included in the executable
   1176           and used at runtime, whereas the `-rpath-link' option is only
   1177           effective at link time. Searching `-rpath' in this way is
   1178           only supported by native linkers and cross linkers which have
   1179           been configured with the `--with-sysroot' option.
   1180 
   1181        3. On an ELF system, for native linkers, if the `-rpath' and
   1182           `-rpath-link' options were not used, search the contents of
   1183           the environment variable `LD_RUN_PATH'.
   1184 
   1185        4. On SunOS, if the `-rpath' option was not used, search any
   1186           directories specified using `-L' options.
   1187 
   1188        5. For a native linker, the search the contents of the
   1189           environment variable `LD_LIBRARY_PATH'.
   1190 
   1191        6. For a native ELF linker, the directories in `DT_RUNPATH' or
   1192           `DT_RPATH' of a shared library are searched for shared
   1193           libraries needed by it. The `DT_RPATH' entries are ignored if
   1194           `DT_RUNPATH' entries exist.
   1195 
   1196        7. The default directories, normally `/lib' and `/usr/lib'.
   1197 
   1198        8. For a native linker on an ELF system, if the file
   1199           `/etc/ld.so.conf' exists, the list of directories found in
   1200           that file.
   1201 
   1202      If the required shared library is not found, the linker will issue
   1203      a warning and continue with the link.
   1204 
   1205 `-shared'
   1206 `-Bshareable'
   1207      Create a shared library.  This is currently only supported on ELF,
   1208      XCOFF and SunOS platforms.  On SunOS, the linker will
   1209      automatically create a shared library if the `-e' option is not
   1210      used and there are undefined symbols in the link.
   1211 
   1212 `--sort-common [= ascending | descending]'
   1213      This option tells `ld' to sort the common symbols by alignment in
   1214      ascending or descending order when it places them in the
   1215      appropriate output sections.  The symbol alignments considered are
   1216      sixteen-byte or larger, eight-byte, four-byte, two-byte, and
   1217      one-byte. This is to prevent gaps between symbols due to alignment
   1218      constraints.  If no sorting order is specified, then descending
   1219      order is assumed.
   1220 
   1221 `--sort-section name'
   1222      This option will apply `SORT_BY_NAME' to all wildcard section
   1223      patterns in the linker script.
   1224 
   1225 `--sort-section alignment'
   1226      This option will apply `SORT_BY_ALIGNMENT' to all wildcard section
   1227      patterns in the linker script.
   1228 
   1229 `--split-by-file [SIZE]'
   1230      Similar to `--split-by-reloc' but creates a new output section for
   1231      each input file when SIZE is reached.  SIZE defaults to a size of
   1232      1 if not given.
   1233 
   1234 `--split-by-reloc [COUNT]'
   1235      Tries to creates extra sections in the output file so that no
   1236      single output section in the file contains more than COUNT
   1237      relocations.  This is useful when generating huge relocatable
   1238      files for downloading into certain real time kernels with the COFF
   1239      object file format; since COFF cannot represent more than 65535
   1240      relocations in a single section.  Note that this will fail to work
   1241      with object file formats which do not support arbitrary sections.
   1242      The linker will not split up individual input sections for
   1243      redistribution, so if a single input section contains more than
   1244      COUNT relocations one output section will contain that many
   1245      relocations.  COUNT defaults to a value of 32768.
   1246 
   1247 `--stats'
   1248      Compute and display statistics about the operation of the linker,
   1249      such as execution time and memory usage.
   1250 
   1251 `--sysroot=DIRECTORY'
   1252      Use DIRECTORY as the location of the sysroot, overriding the
   1253      configure-time default.  This option is only supported by linkers
   1254      that were configured using `--with-sysroot'.
   1255 
   1256 `--traditional-format'
   1257      For some targets, the output of `ld' is different in some ways from
   1258      the output of some existing linker.  This switch requests `ld' to
   1259      use the traditional format instead.
   1260 
   1261      For example, on SunOS, `ld' combines duplicate entries in the
   1262      symbol string table.  This can reduce the size of an output file
   1263      with full debugging information by over 30 percent.
   1264      Unfortunately, the SunOS `dbx' program can not read the resulting
   1265      program (`gdb' has no trouble).  The `--traditional-format' switch
   1266      tells `ld' to not combine duplicate entries.
   1267 
   1268 `--section-start SECTIONNAME=ORG'
   1269      Locate a section in the output file at the absolute address given
   1270      by ORG.  You may use this option as many times as necessary to
   1271      locate multiple sections in the command line.  ORG must be a
   1272      single hexadecimal integer; for compatibility with other linkers,
   1273      you may omit the leading `0x' usually associated with hexadecimal
   1274      values.  _Note:_ there should be no white space between
   1275      SECTIONNAME, the equals sign ("<=>"), and ORG.
   1276 
   1277 `-Tbss ORG'
   1278 `-Tdata ORG'
   1279 `-Ttext ORG'
   1280      Same as -section-start, with `.bss', `.data' or `.text' as the
   1281      SECTIONNAME.
   1282 
   1283 `--unresolved-symbols=METHOD'
   1284      Determine how to handle unresolved symbols.  There are four
   1285      possible values for `method':
   1286 
   1287     `ignore-all'
   1288           Do not report any unresolved symbols.
   1289 
   1290     `report-all'
   1291           Report all unresolved symbols.  This is the default.
   1292 
   1293     `ignore-in-object-files'
   1294           Report unresolved symbols that are contained in shared
   1295           libraries, but ignore them if they come from regular object
   1296           files.
   1297 
   1298     `ignore-in-shared-libs'
   1299           Report unresolved symbols that come from regular object
   1300           files, but ignore them if they come from shared libraries.
   1301           This can be useful when creating a dynamic binary and it is
   1302           known that all the shared libraries that it should be
   1303           referencing are included on the linker's command line.
   1304 
   1305      The behaviour for shared libraries on their own can also be
   1306      controlled by the `--[no-]allow-shlib-undefined' option.
   1307 
   1308      Normally the linker will generate an error message for each
   1309      reported unresolved symbol but the option
   1310      `--warn-unresolved-symbols' can change this to a warning.
   1311 
   1312 `--dll-verbose'
   1313 `--verbose'
   1314      Display the version number for `ld' and list the linker emulations
   1315      supported.  Display which input files can and cannot be opened.
   1316      Display the linker script being used by the linker.
   1317 
   1318 `--version-script=VERSION-SCRIPTFILE'
   1319      Specify the name of a version script to the linker.  This is
   1320      typically used when creating shared libraries to specify
   1321      additional information about the version hierarchy for the library
   1322      being created.  This option is only meaningful on ELF platforms
   1323      which support shared libraries.  *Note VERSION::.
   1324 
   1325 `--warn-common'
   1326      Warn when a common symbol is combined with another common symbol
   1327      or with a symbol definition.  Unix linkers allow this somewhat
   1328      sloppy practise, but linkers on some other operating systems do
   1329      not.  This option allows you to find potential problems from
   1330      combining global symbols.  Unfortunately, some C libraries use
   1331      this practise, so you may get some warnings about symbols in the
   1332      libraries as well as in your programs.
   1333 
   1334      There are three kinds of global symbols, illustrated here by C
   1335      examples:
   1336 
   1337     `int i = 1;'
   1338           A definition, which goes in the initialized data section of
   1339           the output file.
   1340 
   1341     `extern int i;'
   1342           An undefined reference, which does not allocate space.  There
   1343           must be either a definition or a common symbol for the
   1344           variable somewhere.
   1345 
   1346     `int i;'
   1347           A common symbol.  If there are only (one or more) common
   1348           symbols for a variable, it goes in the uninitialized data
   1349           area of the output file.  The linker merges multiple common
   1350           symbols for the same variable into a single symbol.  If they
   1351           are of different sizes, it picks the largest size.  The
   1352           linker turns a common symbol into a declaration, if there is
   1353           a definition of the same variable.
   1354 
   1355      The `--warn-common' option can produce five kinds of warnings.
   1356      Each warning consists of a pair of lines: the first describes the
   1357      symbol just encountered, and the second describes the previous
   1358      symbol encountered with the same name.  One or both of the two
   1359      symbols will be a common symbol.
   1360 
   1361        1. Turning a common symbol into a reference, because there is
   1362           already a definition for the symbol.
   1363                FILE(SECTION): warning: common of `SYMBOL'
   1364                   overridden by definition
   1365                FILE(SECTION): warning: defined here
   1366 
   1367        2. Turning a common symbol into a reference, because a later
   1368           definition for the symbol is encountered.  This is the same
   1369           as the previous case, except that the symbols are encountered
   1370           in a different order.
   1371                FILE(SECTION): warning: definition of `SYMBOL'
   1372                   overriding common
   1373                FILE(SECTION): warning: common is here
   1374 
   1375        3. Merging a common symbol with a previous same-sized common
   1376           symbol.
   1377                FILE(SECTION): warning: multiple common
   1378                   of `SYMBOL'
   1379                FILE(SECTION): warning: previous common is here
   1380 
   1381        4. Merging a common symbol with a previous larger common symbol.
   1382                FILE(SECTION): warning: common of `SYMBOL'
   1383                   overridden by larger common
   1384                FILE(SECTION): warning: larger common is here
   1385 
   1386        5. Merging a common symbol with a previous smaller common
   1387           symbol.  This is the same as the previous case, except that
   1388           the symbols are encountered in a different order.
   1389                FILE(SECTION): warning: common of `SYMBOL'
   1390                   overriding smaller common
   1391                FILE(SECTION): warning: smaller common is here
   1392 
   1393 `--warn-constructors'
   1394      Warn if any global constructors are used.  This is only useful for
   1395      a few object file formats.  For formats like COFF or ELF, the
   1396      linker can not detect the use of global constructors.
   1397 
   1398 `--warn-multiple-gp'
   1399      Warn if multiple global pointer values are required in the output
   1400      file.  This is only meaningful for certain processors, such as the
   1401      Alpha.  Specifically, some processors put large-valued constants
   1402      in a special section.  A special register (the global pointer)
   1403      points into the middle of this section, so that constants can be
   1404      loaded efficiently via a base-register relative addressing mode.
   1405      Since the offset in base-register relative mode is fixed and
   1406      relatively small (e.g., 16 bits), this limits the maximum size of
   1407      the constant pool.  Thus, in large programs, it is often necessary
   1408      to use multiple global pointer values in order to be able to
   1409      address all possible constants.  This option causes a warning to
   1410      be issued whenever this case occurs.
   1411 
   1412 `--warn-once'
   1413      Only warn once for each undefined symbol, rather than once per
   1414      module which refers to it.
   1415 
   1416 `--warn-section-align'
   1417      Warn if the address of an output section is changed because of
   1418      alignment.  Typically, the alignment will be set by an input
   1419      section.  The address will only be changed if it not explicitly
   1420      specified; that is, if the `SECTIONS' command does not specify a
   1421      start address for the section (*note SECTIONS::).
   1422 
   1423 `--warn-shared-textrel'
   1424      Warn if the linker adds a DT_TEXTREL to a shared object.
   1425 
   1426 `--warn-unresolved-symbols'
   1427      If the linker is going to report an unresolved symbol (see the
   1428      option `--unresolved-symbols') it will normally generate an error.
   1429      This option makes it generate a warning instead.
   1430 
   1431 `--error-unresolved-symbols'
   1432      This restores the linker's default behaviour of generating errors
   1433      when it is reporting unresolved symbols.
   1434 
   1435 `--whole-archive'
   1436      For each archive mentioned on the command line after the
   1437      `--whole-archive' option, include every object file in the archive
   1438      in the link, rather than searching the archive for the required
   1439      object files.  This is normally used to turn an archive file into
   1440      a shared library, forcing every object to be included in the
   1441      resulting shared library.  This option may be used more than once.
   1442 
   1443      Two notes when using this option from gcc: First, gcc doesn't know
   1444      about this option, so you have to use `-Wl,-whole-archive'.
   1445      Second, don't forget to use `-Wl,-no-whole-archive' after your
   1446      list of archives, because gcc will add its own list of archives to
   1447      your link and you may not want this flag to affect those as well.
   1448 
   1449 `--wrap SYMBOL'
   1450      Use a wrapper function for SYMBOL.  Any undefined reference to
   1451      SYMBOL will be resolved to `__wrap_SYMBOL'.  Any undefined
   1452      reference to `__real_SYMBOL' will be resolved to SYMBOL.
   1453 
   1454      This can be used to provide a wrapper for a system function.  The
   1455      wrapper function should be called `__wrap_SYMBOL'.  If it wishes
   1456      to call the system function, it should call `__real_SYMBOL'.
   1457 
   1458      Here is a trivial example:
   1459 
   1460           void *
   1461           __wrap_malloc (size_t c)
   1462           {
   1463             printf ("malloc called with %zu\n", c);
   1464             return __real_malloc (c);
   1465           }
   1466 
   1467      If you link other code with this file using `--wrap malloc', then
   1468      all calls to `malloc' will call the function `__wrap_malloc'
   1469      instead.  The call to `__real_malloc' in `__wrap_malloc' will call
   1470      the real `malloc' function.
   1471 
   1472      You may wish to provide a `__real_malloc' function as well, so that
   1473      links without the `--wrap' option will succeed.  If you do this,
   1474      you should not put the definition of `__real_malloc' in the same
   1475      file as `__wrap_malloc'; if you do, the assembler may resolve the
   1476      call before the linker has a chance to wrap it to `malloc'.
   1477 
   1478 `--eh-frame-hdr'
   1479      Request creation of `.eh_frame_hdr' section and ELF
   1480      `PT_GNU_EH_FRAME' segment header.
   1481 
   1482 `--enable-new-dtags'
   1483 `--disable-new-dtags'
   1484      This linker can create the new dynamic tags in ELF. But the older
   1485      ELF systems may not understand them. If you specify
   1486      `--enable-new-dtags', the dynamic tags will be created as needed.
   1487      If you specify `--disable-new-dtags', no new dynamic tags will be
   1488      created. By default, the new dynamic tags are not created. Note
   1489      that those options are only available for ELF systems.
   1490 
   1491 `--hash-size=NUMBER'
   1492      Set the default size of the linker's hash tables to a prime number
   1493      close to NUMBER.  Increasing this value can reduce the length of
   1494      time it takes the linker to perform its tasks, at the expense of
   1495      increasing the linker's memory requirements.  Similarly reducing
   1496      this value can reduce the memory requirements at the expense of
   1497      speed.
   1498 
   1499 `--hash-style=STYLE'
   1500      Set the type of linker's hash table(s).  STYLE can be either
   1501      `sysv' for classic ELF `.hash' section, `gnu' for new style GNU
   1502      `.gnu.hash' section or `both' for both the classic ELF `.hash' and
   1503      new style GNU `.gnu.hash' hash tables.  The default is `sysv'.
   1504 
   1505 `--reduce-memory-overheads'
   1506      This option reduces memory requirements at ld runtime, at the
   1507      expense of linking speed.  This was introduced to select the old
   1508      O(n^2) algorithm for link map file generation, rather than the new
   1509      O(n) algorithm which uses about 40% more memory for symbol storage.
   1510 
   1511      Another effect of the switch is to set the default hash table size
   1512      to 1021, which again saves memory at the cost of lengthening the
   1513      linker's run time.  This is not done however if the `--hash-size'
   1514      switch has been used.
   1515 
   1516      The `--reduce-memory-overheads' switch may be also be used to
   1517      enable other tradeoffs in future versions of the linker.
   1518 
   1519 `--build-id'
   1520 `--build-id=STYLE'
   1521      Request creation of `.note.gnu.build-id' ELF note section.  The
   1522      contents of the note are unique bits identifying this linked file.
   1523      STYLE can be `uuid' to use 128 random bits, `sha1' to use a
   1524      160-bit SHA1 hash on the normative parts of the output contents,
   1525      `md5' to use a 128-bit MD5 hash on the normative parts of the
   1526      output contents, or `0xHEXSTRING' to use a chosen bit string
   1527      specified as an even number of hexadecimal digits (`-' and `:'
   1528      characters between digit pairs are ignored).  If STYLE is omitted,
   1529      `sha1' is used.
   1530 
   1531      The `md5' and `sha1' styles produces an identifier that is always
   1532      the same in an identical output file, but will be unique among all
   1533      nonidentical output files.  It is not intended to be compared as a
   1534      checksum for the file's contents.  A linked file may be changed
   1535      later by other tools, but the build ID bit string identifying the
   1536      original linked file does not change.
   1537 
   1538      Passing `none' for STYLE disables the setting from any
   1539      `--build-id' options earlier on the command line.
   1540 
   1541 2.1.1 Options Specific to i386 PE Targets
   1542 -----------------------------------------
   1543 
   1544 The i386 PE linker supports the `-shared' option, which causes the
   1545 output to be a dynamically linked library (DLL) instead of a normal
   1546 executable.  You should name the output `*.dll' when you use this
   1547 option.  In addition, the linker fully supports the standard `*.def'
   1548 files, which may be specified on the linker command line like an object
   1549 file (in fact, it should precede archives it exports symbols from, to
   1550 ensure that they get linked in, just like a normal object file).
   1551 
   1552    In addition to the options common to all targets, the i386 PE linker
   1553 support additional command line options that are specific to the i386
   1554 PE target.  Options that take values may be separated from their values
   1555 by either a space or an equals sign.
   1556 
   1557 `--add-stdcall-alias'
   1558      If given, symbols with a stdcall suffix (@NN) will be exported
   1559      as-is and also with the suffix stripped.  [This option is specific
   1560      to the i386 PE targeted port of the linker]
   1561 
   1562 `--base-file FILE'
   1563      Use FILE as the name of a file in which to save the base addresses
   1564      of all the relocations needed for generating DLLs with `dlltool'.
   1565      [This is an i386 PE specific option]
   1566 
   1567 `--dll'
   1568      Create a DLL instead of a regular executable.  You may also use
   1569      `-shared' or specify a `LIBRARY' in a given `.def' file.  [This
   1570      option is specific to the i386 PE targeted port of the linker]
   1571 
   1572 `--enable-stdcall-fixup'
   1573 `--disable-stdcall-fixup'
   1574      If the link finds a symbol that it cannot resolve, it will attempt
   1575      to do "fuzzy linking" by looking for another defined symbol that
   1576      differs only in the format of the symbol name (cdecl vs stdcall)
   1577      and will resolve that symbol by linking to the match.  For
   1578      example, the undefined symbol `_foo' might be linked to the
   1579      function `_foo@12', or the undefined symbol `_bar@16' might be
   1580      linked to the function `_bar'.  When the linker does this, it
   1581      prints a warning, since it normally should have failed to link,
   1582      but sometimes import libraries generated from third-party dlls may
   1583      need this feature to be usable.  If you specify
   1584      `--enable-stdcall-fixup', this feature is fully enabled and
   1585      warnings are not printed.  If you specify
   1586      `--disable-stdcall-fixup', this feature is disabled and such
   1587      mismatches are considered to be errors.  [This option is specific
   1588      to the i386 PE targeted port of the linker]
   1589 
   1590 `--export-all-symbols'
   1591      If given, all global symbols in the objects used to build a DLL
   1592      will be exported by the DLL.  Note that this is the default if
   1593      there otherwise wouldn't be any exported symbols.  When symbols are
   1594      explicitly exported via DEF files or implicitly exported via
   1595      function attributes, the default is to not export anything else
   1596      unless this option is given.  Note that the symbols `DllMain@12',
   1597      `DllEntryPoint@0', `DllMainCRTStartup@12', and `impure_ptr' will
   1598      not be automatically exported.  Also, symbols imported from other
   1599      DLLs will not be re-exported, nor will symbols specifying the
   1600      DLL's internal layout such as those beginning with `_head_' or
   1601      ending with `_iname'.  In addition, no symbols from `libgcc',
   1602      `libstd++', `libmingw32', or `crtX.o' will be exported.  Symbols
   1603      whose names begin with `__rtti_' or `__builtin_' will not be
   1604      exported, to help with C++ DLLs.  Finally, there is an extensive
   1605      list of cygwin-private symbols that are not exported (obviously,
   1606      this applies on when building DLLs for cygwin targets).  These
   1607      cygwin-excludes are: `_cygwin_dll_entry@12',
   1608      `_cygwin_crt0_common@8', `_cygwin_noncygwin_dll_entry@12',
   1609      `_fmode', `_impure_ptr', `cygwin_attach_dll', `cygwin_premain0',
   1610      `cygwin_premain1', `cygwin_premain2', `cygwin_premain3', and
   1611      `environ'.  [This option is specific to the i386 PE targeted port
   1612      of the linker]
   1613 
   1614 `--exclude-symbols SYMBOL,SYMBOL,...'
   1615      Specifies a list of symbols which should not be automatically
   1616      exported.  The symbol names may be delimited by commas or colons.
   1617      [This option is specific to the i386 PE targeted port of the
   1618      linker]
   1619 
   1620 `--file-alignment'
   1621      Specify the file alignment.  Sections in the file will always
   1622      begin at file offsets which are multiples of this number.  This
   1623      defaults to 512.  [This option is specific to the i386 PE targeted
   1624      port of the linker]
   1625 
   1626 `--heap RESERVE'
   1627 `--heap RESERVE,COMMIT'
   1628      Specify the number of bytes of memory to reserve (and optionally
   1629      commit) to be used as heap for this program.  The default is 1Mb
   1630      reserved, 4K committed.  [This option is specific to the i386 PE
   1631      targeted port of the linker]
   1632 
   1633 `--image-base VALUE'
   1634      Use VALUE as the base address of your program or dll.  This is the
   1635      lowest memory location that will be used when your program or dll
   1636      is loaded.  To reduce the need to relocate and improve performance
   1637      of your dlls, each should have a unique base address and not
   1638      overlap any other dlls.  The default is 0x400000 for executables,
   1639      and 0x10000000 for dlls.  [This option is specific to the i386 PE
   1640      targeted port of the linker]
   1641 
   1642 `--kill-at'
   1643      If given, the stdcall suffixes (@NN) will be stripped from symbols
   1644      before they are exported.  [This option is specific to the i386 PE
   1645      targeted port of the linker]
   1646 
   1647 `--large-address-aware'
   1648      If given, the appropriate bit in the "Characteristics" field of
   1649      the COFF header is set to indicate that this executable supports
   1650      virtual addresses greater than 2 gigabytes.  This should be used
   1651      in conjunction with the /3GB or /USERVA=VALUE megabytes switch in
   1652      the "[operating systems]" section of the BOOT.INI.  Otherwise,
   1653      this bit has no effect.  [This option is specific to PE targeted
   1654      ports of the linker]
   1655 
   1656 `--major-image-version VALUE'
   1657      Sets the major number of the "image version".  Defaults to 1.
   1658      [This option is specific to the i386 PE targeted port of the
   1659      linker]
   1660 
   1661 `--major-os-version VALUE'
   1662      Sets the major number of the "os version".  Defaults to 4.  [This
   1663      option is specific to the i386 PE targeted port of the linker]
   1664 
   1665 `--major-subsystem-version VALUE'
   1666      Sets the major number of the "subsystem version".  Defaults to 4.
   1667      [This option is specific to the i386 PE targeted port of the
   1668      linker]
   1669 
   1670 `--minor-image-version VALUE'
   1671      Sets the minor number of the "image version".  Defaults to 0.
   1672      [This option is specific to the i386 PE targeted port of the
   1673      linker]
   1674 
   1675 `--minor-os-version VALUE'
   1676      Sets the minor number of the "os version".  Defaults to 0.  [This
   1677      option is specific to the i386 PE targeted port of the linker]
   1678 
   1679 `--minor-subsystem-version VALUE'
   1680      Sets the minor number of the "subsystem version".  Defaults to 0.
   1681      [This option is specific to the i386 PE targeted port of the
   1682      linker]
   1683 
   1684 `--output-def FILE'
   1685      The linker will create the file FILE which will contain a DEF file
   1686      corresponding to the DLL the linker is generating.  This DEF file
   1687      (which should be called `*.def') may be used to create an import
   1688      library with `dlltool' or may be used as a reference to
   1689      automatically or implicitly exported symbols.  [This option is
   1690      specific to the i386 PE targeted port of the linker]
   1691 
   1692 `--out-implib FILE'
   1693      The linker will create the file FILE which will contain an import
   1694      lib corresponding to the DLL the linker is generating. This import
   1695      lib (which should be called `*.dll.a' or `*.a' may be used to link
   1696      clients against the generated DLL; this behaviour makes it
   1697      possible to skip a separate `dlltool' import library creation step.
   1698      [This option is specific to the i386 PE targeted port of the
   1699      linker]
   1700 
   1701 `--enable-auto-image-base'
   1702      Automatically choose the image base for DLLs, unless one is
   1703      specified using the `--image-base' argument.  By using a hash
   1704      generated from the dllname to create unique image bases for each
   1705      DLL, in-memory collisions and relocations which can delay program
   1706      execution are avoided.  [This option is specific to the i386 PE
   1707      targeted port of the linker]
   1708 
   1709 `--disable-auto-image-base'
   1710      Do not automatically generate a unique image base.  If there is no
   1711      user-specified image base (`--image-base') then use the platform
   1712      default.  [This option is specific to the i386 PE targeted port of
   1713      the linker]
   1714 
   1715 `--dll-search-prefix STRING'
   1716      When linking dynamically to a dll without an import library,
   1717      search for `<string><basename>.dll' in preference to
   1718      `lib<basename>.dll'. This behaviour allows easy distinction
   1719      between DLLs built for the various "subplatforms": native, cygwin,
   1720      uwin, pw, etc.  For instance, cygwin DLLs typically use
   1721      `--dll-search-prefix=cyg'.  [This option is specific to the i386
   1722      PE targeted port of the linker]
   1723 
   1724 `--enable-auto-import'
   1725      Do sophisticated linking of `_symbol' to `__imp__symbol' for DATA
   1726      imports from DLLs, and create the necessary thunking symbols when
   1727      building the import libraries with those DATA exports. Note: Use
   1728      of the 'auto-import' extension will cause the text section of the
   1729      image file to be made writable. This does not conform to the
   1730      PE-COFF format specification published by Microsoft.
   1731 
   1732      Note - use of the 'auto-import' extension will also cause read only
   1733      data which would normally be placed into the .rdata section to be
   1734      placed into the .data section instead.  This is in order to work
   1735      around a problem with consts that is described here:
   1736      http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
   1737 
   1738      Using 'auto-import' generally will 'just work' - but sometimes you
   1739      may see this message:
   1740 
   1741      "variable '<var>' can't be auto-imported. Please read the
   1742      documentation for ld's `--enable-auto-import' for details."
   1743 
   1744      This message occurs when some (sub)expression accesses an address
   1745      ultimately given by the sum of two constants (Win32 import tables
   1746      only allow one).  Instances where this may occur include accesses
   1747      to member fields of struct variables imported from a DLL, as well
   1748      as using a constant index into an array variable imported from a
   1749      DLL.  Any multiword variable (arrays, structs, long long, etc) may
   1750      trigger this error condition.  However, regardless of the exact
   1751      data type of the offending exported variable, ld will always
   1752      detect it, issue the warning, and exit.
   1753 
   1754      There are several ways to address this difficulty, regardless of
   1755      the data type of the exported variable:
   1756 
   1757      One way is to use -enable-runtime-pseudo-reloc switch. This leaves
   1758      the task of adjusting references in your client code for runtime
   1759      environment, so this method works only when runtime environment
   1760      supports this feature.
   1761 
   1762      A second solution is to force one of the 'constants' to be a
   1763      variable - that is, unknown and un-optimizable at compile time.
   1764      For arrays, there are two possibilities: a) make the indexee (the
   1765      array's address) a variable, or b) make the 'constant' index a
   1766      variable.  Thus:
   1767 
   1768           extern type extern_array[];
   1769           extern_array[1] -->
   1770              { volatile type *t=extern_array; t[1] }
   1771 
   1772      or
   1773 
   1774           extern type extern_array[];
   1775           extern_array[1] -->
   1776              { volatile int t=1; extern_array[t] }
   1777 
   1778      For structs (and most other multiword data types) the only option
   1779      is to make the struct itself (or the long long, or the ...)
   1780      variable:
   1781 
   1782           extern struct s extern_struct;
   1783           extern_struct.field -->
   1784              { volatile struct s *t=&extern_struct; t->field }
   1785 
   1786      or
   1787 
   1788           extern long long extern_ll;
   1789           extern_ll -->
   1790             { volatile long long * local_ll=&extern_ll; *local_ll }
   1791 
   1792      A third method of dealing with this difficulty is to abandon
   1793      'auto-import' for the offending symbol and mark it with
   1794      `__declspec(dllimport)'.  However, in practise that requires using
   1795      compile-time #defines to indicate whether you are building a DLL,
   1796      building client code that will link to the DLL, or merely
   1797      building/linking to a static library.   In making the choice
   1798      between the various methods of resolving the 'direct address with
   1799      constant offset' problem, you should consider typical real-world
   1800      usage:
   1801 
   1802      Original:
   1803           --foo.h
   1804           extern int arr[];
   1805           --foo.c
   1806           #include "foo.h"
   1807           void main(int argc, char **argv){
   1808             printf("%d\n",arr[1]);
   1809           }
   1810 
   1811      Solution 1:
   1812           --foo.h
   1813           extern int arr[];
   1814           --foo.c
   1815           #include "foo.h"
   1816           void main(int argc, char **argv){
   1817             /* This workaround is for win32 and cygwin; do not "optimize" */
   1818             volatile int *parr = arr;
   1819             printf("%d\n",parr[1]);
   1820           }
   1821 
   1822      Solution 2:
   1823           --foo.h
   1824           /* Note: auto-export is assumed (no __declspec(dllexport)) */
   1825           #if (defined(_WIN32) || defined(__CYGWIN__)) && \
   1826             !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
   1827           #define FOO_IMPORT __declspec(dllimport)
   1828           #else
   1829           #define FOO_IMPORT
   1830           #endif
   1831           extern FOO_IMPORT int arr[];
   1832           --foo.c
   1833           #include "foo.h"
   1834           void main(int argc, char **argv){
   1835             printf("%d\n",arr[1]);
   1836           }
   1837 
   1838      A fourth way to avoid this problem is to re-code your library to
   1839      use a functional interface rather than a data interface for the
   1840      offending variables (e.g. set_foo() and get_foo() accessor
   1841      functions).  [This option is specific to the i386 PE targeted port
   1842      of the linker]
   1843 
   1844 `--disable-auto-import'
   1845      Do not attempt to do sophisticated linking of `_symbol' to
   1846      `__imp__symbol' for DATA imports from DLLs.  [This option is
   1847      specific to the i386 PE targeted port of the linker]
   1848 
   1849 `--enable-runtime-pseudo-reloc'
   1850      If your code contains expressions described in -enable-auto-import
   1851      section, that is, DATA imports from DLL with non-zero offset, this
   1852      switch will create a vector of 'runtime pseudo relocations' which
   1853      can be used by runtime environment to adjust references to such
   1854      data in your client code.  [This option is specific to the i386 PE
   1855      targeted port of the linker]
   1856 
   1857 `--disable-runtime-pseudo-reloc'
   1858      Do not create pseudo relocations for non-zero offset DATA imports
   1859      from DLLs.  This is the default.  [This option is specific to the
   1860      i386 PE targeted port of the linker]
   1861 
   1862 `--enable-extra-pe-debug'
   1863      Show additional debug info related to auto-import symbol thunking.
   1864      [This option is specific to the i386 PE targeted port of the
   1865      linker]
   1866 
   1867 `--section-alignment'
   1868      Sets the section alignment.  Sections in memory will always begin
   1869      at addresses which are a multiple of this number.  Defaults to
   1870      0x1000.  [This option is specific to the i386 PE targeted port of
   1871      the linker]
   1872 
   1873 `--stack RESERVE'
   1874 `--stack RESERVE,COMMIT'
   1875      Specify the number of bytes of memory to reserve (and optionally
   1876      commit) to be used as stack for this program.  The default is 2Mb
   1877      reserved, 4K committed.  [This option is specific to the i386 PE
   1878      targeted port of the linker]
   1879 
   1880 `--subsystem WHICH'
   1881 `--subsystem WHICH:MAJOR'
   1882 `--subsystem WHICH:MAJOR.MINOR'
   1883      Specifies the subsystem under which your program will execute.  The
   1884      legal values for WHICH are `native', `windows', `console',
   1885      `posix', and `xbox'.  You may optionally set the subsystem version
   1886      also.  Numeric values are also accepted for WHICH.  [This option
   1887      is specific to the i386 PE targeted port of the linker]
   1888 
   1889 
   1890 2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets
   1891 ------------------------------------------------------------
   1892 
   1893 The 68HC11 and 68HC12 linkers support specific options to control the
   1894 memory bank switching mapping and trampoline code generation.
   1895 
   1896 `--no-trampoline'
   1897      This option disables the generation of trampoline. By default a
   1898      trampoline is generated for each far function which is called
   1899      using a `jsr' instruction (this happens when a pointer to a far
   1900      function is taken).
   1901 
   1902 `--bank-window NAME'
   1903      This option indicates to the linker the name of the memory region
   1904      in the `MEMORY' specification that describes the memory bank
   1905      window.  The definition of such region is then used by the linker
   1906      to compute paging and addresses within the memory window.
   1907 
   1908 
   1909 2.1.3 Options specific to Motorola 68K target
   1910 ---------------------------------------------
   1911 
   1912 The following options are supported to control handling of GOT
   1913 generation when linking for 68K targets.
   1914 
   1915 `--got=TYPE'
   1916      This option tells the linker which GOT generation scheme to use.
   1917      TYPE should be one of `single', `negative', `multigot' or
   1918      `target'.  For more information refer to the Info entry for `ld'.
   1919 
   1920 
   1921 
   1922 File: ld.info,  Node: Environment,  Prev: Options,  Up: Invocation
   1923 
   1924 2.2 Environment Variables
   1925 =========================
   1926 
   1927 You can change the behaviour of `ld' with the environment variables
   1928 `GNUTARGET', `LDEMULATION' and `COLLECT_NO_DEMANGLE'.
   1929 
   1930    `GNUTARGET' determines the input-file object format if you don't use
   1931 `-b' (or its synonym `--format').  Its value should be one of the BFD
   1932 names for an input format (*note BFD::).  If there is no `GNUTARGET' in
   1933 the environment, `ld' uses the natural format of the target. If
   1934 `GNUTARGET' is set to `default' then BFD attempts to discover the input
   1935 format by examining binary input files; this method often succeeds, but
   1936 there are potential ambiguities, since there is no method of ensuring
   1937 that the magic number used to specify object-file formats is unique.
   1938 However, the configuration procedure for BFD on each system places the
   1939 conventional format for that system first in the search-list, so
   1940 ambiguities are resolved in favor of convention.
   1941 
   1942    `LDEMULATION' determines the default emulation if you don't use the
   1943 `-m' option.  The emulation can affect various aspects of linker
   1944 behaviour, particularly the default linker script.  You can list the
   1945 available emulations with the `--verbose' or `-V' options.  If the `-m'
   1946 option is not used, and the `LDEMULATION' environment variable is not
   1947 defined, the default emulation depends upon how the linker was
   1948 configured.
   1949 
   1950    Normally, the linker will default to demangling symbols.  However, if
   1951 `COLLECT_NO_DEMANGLE' is set in the environment, then it will default
   1952 to not demangling symbols.  This environment variable is used in a
   1953 similar fashion by the `gcc' linker wrapper program.  The default may
   1954 be overridden by the `--demangle' and `--no-demangle' options.
   1955 
   1956 
   1957 File: ld.info,  Node: Scripts,  Next: Machine Dependent,  Prev: Invocation,  Up: Top
   1958 
   1959 3 Linker Scripts
   1960 ****************
   1961 
   1962 Every link is controlled by a "linker script".  This script is written
   1963 in the linker command language.
   1964 
   1965    The main purpose of the linker script is to describe how the
   1966 sections in the input files should be mapped into the output file, and
   1967 to control the memory layout of the output file.  Most linker scripts
   1968 do nothing more than this.  However, when necessary, the linker script
   1969 can also direct the linker to perform many other operations, using the
   1970 commands described below.
   1971 
   1972    The linker always uses a linker script.  If you do not supply one
   1973 yourself, the linker will use a default script that is compiled into the
   1974 linker executable.  You can use the `--verbose' command line option to
   1975 display the default linker script.  Certain command line options, such
   1976 as `-r' or `-N', will affect the default linker script.
   1977 
   1978    You may supply your own linker script by using the `-T' command line
   1979 option.  When you do this, your linker script will replace the default
   1980 linker script.
   1981 
   1982    You may also use linker scripts implicitly by naming them as input
   1983 files to the linker, as though they were files to be linked.  *Note
   1984 Implicit Linker Scripts::.
   1985 
   1986 * Menu:
   1987 
   1988 * Basic Script Concepts::	Basic Linker Script Concepts
   1989 * Script Format::		Linker Script Format
   1990 * Simple Example::		Simple Linker Script Example
   1991 * Simple Commands::		Simple Linker Script Commands
   1992 * Assignments::			Assigning Values to Symbols
   1993 * SECTIONS::			SECTIONS Command
   1994 * MEMORY::			MEMORY Command
   1995 * PHDRS::			PHDRS Command
   1996 * VERSION::			VERSION Command
   1997 * Expressions::			Expressions in Linker Scripts
   1998 * Implicit Linker Scripts::	Implicit Linker Scripts
   1999 
   2000 
   2001 File: ld.info,  Node: Basic Script Concepts,  Next: Script Format,  Up: Scripts
   2002 
   2003 3.1 Basic Linker Script Concepts
   2004 ================================
   2005 
   2006 We need to define some basic concepts and vocabulary in order to
   2007 describe the linker script language.
   2008 
   2009    The linker combines input files into a single output file.  The
   2010 output file and each input file are in a special data format known as an
   2011 "object file format".  Each file is called an "object file".  The
   2012 output file is often called an "executable", but for our purposes we
   2013 will also call it an object file.  Each object file has, among other
   2014 things, a list of "sections".  We sometimes refer to a section in an
   2015 input file as an "input section"; similarly, a section in the output
   2016 file is an "output section".
   2017 
   2018    Each section in an object file has a name and a size.  Most sections
   2019 also have an associated block of data, known as the "section contents".
   2020 A section may be marked as "loadable", which mean that the contents
   2021 should be loaded into memory when the output file is run.  A section
   2022 with no contents may be "allocatable", which means that an area in
   2023 memory should be set aside, but nothing in particular should be loaded
   2024 there (in some cases this memory must be zeroed out).  A section which
   2025 is neither loadable nor allocatable typically contains some sort of
   2026 debugging information.
   2027 
   2028    Every loadable or allocatable output section has two addresses.  The
   2029 first is the "VMA", or virtual memory address.  This is the address the
   2030 section will have when the output file is run.  The second is the
   2031 "LMA", or load memory address.  This is the address at which the
   2032 section will be loaded.  In most cases the two addresses will be the
   2033 same.  An example of when they might be different is when a data section
   2034 is loaded into ROM, and then copied into RAM when the program starts up
   2035 (this technique is often used to initialize global variables in a ROM
   2036 based system).  In this case the ROM address would be the LMA, and the
   2037 RAM address would be the VMA.
   2038 
   2039    You can see the sections in an object file by using the `objdump'
   2040 program with the `-h' option.
   2041 
   2042    Every object file also has a list of "symbols", known as the "symbol
   2043 table".  A symbol may be defined or undefined.  Each symbol has a name,
   2044 and each defined symbol has an address, among other information.  If
   2045 you compile a C or C++ program into an object file, you will get a
   2046 defined symbol for every defined function and global or static
   2047 variable.  Every undefined function or global variable which is
   2048 referenced in the input file will become an undefined symbol.
   2049 
   2050    You can see the symbols in an object file by using the `nm' program,
   2051 or by using the `objdump' program with the `-t' option.
   2052 
   2053 
   2054 File: ld.info,  Node: Script Format,  Next: Simple Example,  Prev: Basic Script Concepts,  Up: Scripts
   2055 
   2056 3.2 Linker Script Format
   2057 ========================
   2058 
   2059 Linker scripts are text files.
   2060 
   2061    You write a linker script as a series of commands.  Each command is
   2062 either a keyword, possibly followed by arguments, or an assignment to a
   2063 symbol.  You may separate commands using semicolons.  Whitespace is
   2064 generally ignored.
   2065 
   2066    Strings such as file or format names can normally be entered
   2067 directly.  If the file name contains a character such as a comma which
   2068 would otherwise serve to separate file names, you may put the file name
   2069 in double quotes.  There is no way to use a double quote character in a
   2070 file name.
   2071 
   2072    You may include comments in linker scripts just as in C, delimited by
   2073 `/*' and `*/'.  As in C, comments are syntactically equivalent to
   2074 whitespace.
   2075 
   2076 
   2077 File: ld.info,  Node: Simple Example,  Next: Simple Commands,  Prev: Script Format,  Up: Scripts
   2078 
   2079 3.3 Simple Linker Script Example
   2080 ================================
   2081 
   2082 Many linker scripts are fairly simple.
   2083 
   2084    The simplest possible linker script has just one command:
   2085 `SECTIONS'.  You use the `SECTIONS' command to describe the memory
   2086 layout of the output file.
   2087 
   2088    The `SECTIONS' command is a powerful command.  Here we will describe
   2089 a simple use of it.  Let's assume your program consists only of code,
   2090 initialized data, and uninitialized data.  These will be in the
   2091 `.text', `.data', and `.bss' sections, respectively.  Let's assume
   2092 further that these are the only sections which appear in your input
   2093 files.
   2094 
   2095    For this example, let's say that the code should be loaded at address
   2096 0x10000, and that the data should start at address 0x8000000.  Here is a
   2097 linker script which will do that:
   2098      SECTIONS
   2099      {
   2100        . = 0x10000;
   2101        .text : { *(.text) }
   2102        . = 0x8000000;
   2103        .data : { *(.data) }
   2104        .bss : { *(.bss) }
   2105      }
   2106 
   2107    You write the `SECTIONS' command as the keyword `SECTIONS', followed
   2108 by a series of symbol assignments and output section descriptions
   2109 enclosed in curly braces.
   2110 
   2111    The first line inside the `SECTIONS' command of the above example
   2112 sets the value of the special symbol `.', which is the location
   2113 counter.  If you do not specify the address of an output section in some
   2114 other way (other ways are described later), the address is set from the
   2115 current value of the location counter.  The location counter is then
   2116 incremented by the size of the output section.  At the start of the
   2117 `SECTIONS' command, the location counter has the value `0'.
   2118 
   2119    The second line defines an output section, `.text'.  The colon is
   2120 required syntax which may be ignored for now.  Within the curly braces
   2121 after the output section name, you list the names of the input sections
   2122 which should be placed into this output section.  The `*' is a wildcard
   2123 which matches any file name.  The expression `*(.text)' means all
   2124 `.text' input sections in all input files.
   2125 
   2126    Since the location counter is `0x10000' when the output section
   2127 `.text' is defined, the linker will set the address of the `.text'
   2128 section in the output file to be `0x10000'.
   2129 
   2130    The remaining lines define the `.data' and `.bss' sections in the
   2131 output file.  The linker will place the `.data' output section at
   2132 address `0x8000000'.  After the linker places the `.data' output
   2133 section, the value of the location counter will be `0x8000000' plus the
   2134 size of the `.data' output section.  The effect is that the linker will
   2135 place the `.bss' output section immediately after the `.data' output
   2136 section in memory.
   2137 
   2138    The linker will ensure that each output section has the required
   2139 alignment, by increasing the location counter if necessary.  In this
   2140 example, the specified addresses for the `.text' and `.data' sections
   2141 will probably satisfy any alignment constraints, but the linker may
   2142 have to create a small gap between the `.data' and `.bss' sections.
   2143 
   2144    That's it!  That's a simple and complete linker script.
   2145 
   2146 
   2147 File: ld.info,  Node: Simple Commands,  Next: Assignments,  Prev: Simple Example,  Up: Scripts
   2148 
   2149 3.4 Simple Linker Script Commands
   2150 =================================
   2151 
   2152 In this section we describe the simple linker script commands.
   2153 
   2154 * Menu:
   2155 
   2156 * Entry Point::			Setting the entry point
   2157 * File Commands::		Commands dealing with files
   2158 
   2159 * Format Commands::		Commands dealing with object file formats
   2160 
   2161 * Miscellaneous Commands::	Other linker script commands
   2162 
   2163 
   2164 File: ld.info,  Node: Entry Point,  Next: File Commands,  Up: Simple Commands
   2165 
   2166 3.4.1 Setting the Entry Point
   2167 -----------------------------
   2168 
   2169 The first instruction to execute in a program is called the "entry
   2170 point".  You can use the `ENTRY' linker script command to set the entry
   2171 point.  The argument is a symbol name:
   2172      ENTRY(SYMBOL)
   2173 
   2174    There are several ways to set the entry point.  The linker will set
   2175 the entry point by trying each of the following methods in order, and
   2176 stopping when one of them succeeds:
   2177    * the `-e' ENTRY command-line option;
   2178 
   2179    * the `ENTRY(SYMBOL)' command in a linker script;
   2180 
   2181    * the value of the symbol `start', if defined;
   2182 
   2183    * the address of the first byte of the `.text' section, if present;
   2184 
   2185    * The address `0'.
   2186 
   2187 
   2188 File: ld.info,  Node: File Commands,  Next: Format Commands,  Prev: Entry Point,  Up: Simple Commands
   2189 
   2190 3.4.2 Commands Dealing with Files
   2191 ---------------------------------
   2192 
   2193 Several linker script commands deal with files.
   2194 
   2195 `INCLUDE FILENAME'
   2196      Include the linker script FILENAME at this point.  The file will
   2197      be searched for in the current directory, and in any directory
   2198      specified with the `-L' option.  You can nest calls to `INCLUDE'
   2199      up to 10 levels deep.
   2200 
   2201      You can place `INCLUDE' directives at the top level, in `MEMORY' or
   2202      `SECTIONS' commands, or in output section descriptions.
   2203 
   2204 `INPUT(FILE, FILE, ...)'
   2205 `INPUT(FILE FILE ...)'
   2206      The `INPUT' command directs the linker to include the named files
   2207      in the link, as though they were named on the command line.
   2208 
   2209      For example, if you always want to include `subr.o' any time you do
   2210      a link, but you can't be bothered to put it on every link command
   2211      line, then you can put `INPUT (subr.o)' in your linker script.
   2212 
   2213      In fact, if you like, you can list all of your input files in the
   2214      linker script, and then invoke the linker with nothing but a `-T'
   2215      option.
   2216 
   2217      In case a "sysroot prefix" is configured, and the filename starts
   2218      with the `/' character, and the script being processed was located
   2219      inside the "sysroot prefix", the filename will be looked for in
   2220      the "sysroot prefix".  Otherwise, the linker will try to open the
   2221      file in the current directory.  If it is not found, the linker
   2222      will search through the archive library search path.  See the
   2223      description of `-L' in *note Command Line Options: Options.
   2224 
   2225      If you use `INPUT (-lFILE)', `ld' will transform the name to
   2226      `libFILE.a', as with the command line argument `-l'.
   2227 
   2228      When you use the `INPUT' command in an implicit linker script, the
   2229      files will be included in the link at the point at which the linker
   2230      script file is included.  This can affect archive searching.
   2231 
   2232 `GROUP(FILE, FILE, ...)'
   2233 `GROUP(FILE FILE ...)'
   2234      The `GROUP' command is like `INPUT', except that the named files
   2235      should all be archives, and they are searched repeatedly until no
   2236      new undefined references are created.  See the description of `-('
   2237      in *note Command Line Options: Options.
   2238 
   2239 `AS_NEEDED(FILE, FILE, ...)'
   2240 `AS_NEEDED(FILE FILE ...)'
   2241      This construct can appear only inside of the `INPUT' or `GROUP'
   2242      commands, among other filenames.  The files listed will be handled
   2243      as if they appear directly in the `INPUT' or `GROUP' commands,
   2244      with the exception of ELF shared libraries, that will be added only
   2245      when they are actually needed.  This construct essentially enables
   2246      `--as-needed' option for all the files listed inside of it and
   2247      restores previous `--as-needed' resp. `--no-as-needed' setting
   2248      afterwards.
   2249 
   2250 `OUTPUT(FILENAME)'
   2251      The `OUTPUT' command names the output file.  Using
   2252      `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
   2253      FILENAME' on the command line (*note Command Line Options:
   2254      Options.).  If both are used, the command line option takes
   2255      precedence.
   2256 
   2257      You can use the `OUTPUT' command to define a default name for the
   2258      output file other than the usual default of `a.out'.
   2259 
   2260 `SEARCH_DIR(PATH)'
   2261      The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
   2262      looks for archive libraries.  Using `SEARCH_DIR(PATH)' is exactly
   2263      like using `-L PATH' on the command line (*note Command Line
   2264      Options: Options.).  If both are used, then the linker will search
   2265      both paths.  Paths specified using the command line option are
   2266      searched first.
   2267 
   2268 `STARTUP(FILENAME)'
   2269      The `STARTUP' command is just like the `INPUT' command, except
   2270      that FILENAME will become the first input file to be linked, as
   2271      though it were specified first on the command line.  This may be
   2272      useful when using a system in which the entry point is always the
   2273      start of the first file.
   2274 
   2275 
   2276 File: ld.info,  Node: Format Commands,  Next: Miscellaneous Commands,  Prev: File Commands,  Up: Simple Commands
   2277 
   2278 3.4.3 Commands Dealing with Object File Formats
   2279 -----------------------------------------------
   2280 
   2281 A couple of linker script commands deal with object file formats.
   2282 
   2283 `OUTPUT_FORMAT(BFDNAME)'
   2284 `OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
   2285      The `OUTPUT_FORMAT' command names the BFD format to use for the
   2286      output file (*note BFD::).  Using `OUTPUT_FORMAT(BFDNAME)' is
   2287      exactly like using `--oformat BFDNAME' on the command line (*note
   2288      Command Line Options: Options.).  If both are used, the command
   2289      line option takes precedence.
   2290 
   2291      You can use `OUTPUT_FORMAT' with three arguments to use different
   2292      formats based on the `-EB' and `-EL' command line options.  This
   2293      permits the linker script to set the output format based on the
   2294      desired endianness.
   2295 
   2296      If neither `-EB' nor `-EL' are used, then the output format will
   2297      be the first argument, DEFAULT.  If `-EB' is used, the output
   2298      format will be the second argument, BIG.  If `-EL' is used, the
   2299      output format will be the third argument, LITTLE.
   2300 
   2301      For example, the default linker script for the MIPS ELF target
   2302      uses this command:
   2303           OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
   2304      This says that the default format for the output file is
   2305      `elf32-bigmips', but if the user uses the `-EL' command line
   2306      option, the output file will be created in the `elf32-littlemips'
   2307      format.
   2308 
   2309 `TARGET(BFDNAME)'
   2310      The `TARGET' command names the BFD format to use when reading input
   2311      files.  It affects subsequent `INPUT' and `GROUP' commands.  This
   2312      command is like using `-b BFDNAME' on the command line (*note
   2313      Command Line Options: Options.).  If the `TARGET' command is used
   2314      but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
   2315      used to set the format for the output file.  *Note BFD::.
   2316 
   2317 
   2318 File: ld.info,  Node: Miscellaneous Commands,  Prev: Format Commands,  Up: Simple Commands
   2319 
   2320 3.4.4 Other Linker Script Commands
   2321 ----------------------------------
   2322 
   2323 There are a few other linker scripts commands.
   2324 
   2325 `ASSERT(EXP, MESSAGE)'
   2326      Ensure that EXP is non-zero.  If it is zero, then exit the linker
   2327      with an error code, and print MESSAGE.
   2328 
   2329 `EXTERN(SYMBOL SYMBOL ...)'
   2330      Force SYMBOL to be entered in the output file as an undefined
   2331      symbol.  Doing this may, for example, trigger linking of additional
   2332      modules from standard libraries.  You may list several SYMBOLs for
   2333      each `EXTERN', and you may use `EXTERN' multiple times.  This
   2334      command has the same effect as the `-u' command-line option.
   2335 
   2336 `FORCE_COMMON_ALLOCATION'
   2337      This command has the same effect as the `-d' command-line option:
   2338      to make `ld' assign space to common symbols even if a relocatable
   2339      output file is specified (`-r').
   2340 
   2341 `INHIBIT_COMMON_ALLOCATION'
   2342      This command has the same effect as the `--no-define-common'
   2343      command-line option: to make `ld' omit the assignment of addresses
   2344      to common symbols even for a non-relocatable output file.
   2345 
   2346 `INSERT [ AFTER | BEFORE ] OUTPUT_SECTION'
   2347      This command is typically used in a script specified by `-T' to
   2348      augment the default `SECTIONS' with, for example, overlays.  It
   2349      inserts all prior linker script statements after (or before)
   2350      OUTPUT_SECTION, and also causes `-T' to not override the default
   2351      linker script.  The exact insertion point is as for orphan
   2352      sections.  *Note Location Counter::.  The insertion happens after
   2353      the linker has mapped input sections to output sections.  Prior to
   2354      the insertion, since `-T' scripts are parsed before the default
   2355      linker script, statements in the `-T' script occur before the
   2356      default linker script statements in the internal linker
   2357      representation of the script.  In particular, input section
   2358      assignments will be made to `-T' output sections before those in
   2359      the default script.  Here is an example of how a `-T' script using
   2360      `INSERT' might look:
   2361 
   2362           SECTIONS
   2363           {
   2364             OVERLAY :
   2365             {
   2366               .ov1 { ov1*(.text) }
   2367               .ov2 { ov2*(.text) }
   2368             }
   2369           }
   2370           INSERT AFTER .text;
   2371 
   2372 `NOCROSSREFS(SECTION SECTION ...)'
   2373      This command may be used to tell `ld' to issue an error about any
   2374      references among certain output sections.
   2375 
   2376      In certain types of programs, particularly on embedded systems when
   2377      using overlays, when one section is loaded into memory, another
   2378      section will not be.  Any direct references between the two
   2379      sections would be errors.  For example, it would be an error if
   2380      code in one section called a function defined in the other section.
   2381 
   2382      The `NOCROSSREFS' command takes a list of output section names.  If
   2383      `ld' detects any cross references between the sections, it reports
   2384      an error and returns a non-zero exit status.  Note that the
   2385      `NOCROSSREFS' command uses output section names, not input section
   2386      names.
   2387 
   2388 `OUTPUT_ARCH(BFDARCH)'
   2389      Specify a particular output machine architecture.  The argument is
   2390      one of the names used by the BFD library (*note BFD::).  You can
   2391      see the architecture of an object file by using the `objdump'
   2392      program with the `-f' option.
   2393 
   2394 
   2395 File: ld.info,  Node: Assignments,  Next: SECTIONS,  Prev: Simple Commands,  Up: Scripts
   2396 
   2397 3.5 Assigning Values to Symbols
   2398 ===============================
   2399 
   2400 You may assign a value to a symbol in a linker script.  This will define
   2401 the symbol and place it into the symbol table with a global scope.
   2402 
   2403 * Menu:
   2404 
   2405 * Simple Assignments::		Simple Assignments
   2406 * PROVIDE::			PROVIDE
   2407 * PROVIDE_HIDDEN::		PROVIDE_HIDDEN
   2408 * Source Code Reference::	How to use a linker script defined symbol in source code
   2409 
   2410 
   2411 File: ld.info,  Node: Simple Assignments,  Next: PROVIDE,  Up: Assignments
   2412 
   2413 3.5.1 Simple Assignments
   2414 ------------------------
   2415 
   2416 You may assign to a symbol using any of the C assignment operators:
   2417 
   2418 `SYMBOL = EXPRESSION ;'
   2419 `SYMBOL += EXPRESSION ;'
   2420 `SYMBOL -= EXPRESSION ;'
   2421 `SYMBOL *= EXPRESSION ;'
   2422 `SYMBOL /= EXPRESSION ;'
   2423 `SYMBOL <<= EXPRESSION ;'
   2424 `SYMBOL >>= EXPRESSION ;'
   2425 `SYMBOL &= EXPRESSION ;'
   2426 `SYMBOL |= EXPRESSION ;'
   2427 
   2428    The first case will define SYMBOL to the value of EXPRESSION.  In
   2429 the other cases, SYMBOL must already be defined, and the value will be
   2430 adjusted accordingly.
   2431 
   2432    The special symbol name `.' indicates the location counter.  You may
   2433 only use this within a `SECTIONS' command.  *Note Location Counter::.
   2434 
   2435    The semicolon after EXPRESSION is required.
   2436 
   2437    Expressions are defined below; see *note Expressions::.
   2438 
   2439    You may write symbol assignments as commands in their own right, or
   2440 as statements within a `SECTIONS' command, or as part of an output
   2441 section description in a `SECTIONS' command.
   2442 
   2443    The section of the symbol will be set from the section of the
   2444 expression; for more information, see *note Expression Section::.
   2445 
   2446    Here is an example showing the three different places that symbol
   2447 assignments may be used:
   2448 
   2449      floating_point = 0;
   2450      SECTIONS
   2451      {
   2452        .text :
   2453          {
   2454            *(.text)
   2455            _etext = .;
   2456          }
   2457        _bdata = (. + 3) & ~ 3;
   2458        .data : { *(.data) }
   2459      }
   2460    In this example, the symbol `floating_point' will be defined as
   2461 zero.  The symbol `_etext' will be defined as the address following the
   2462 last `.text' input section.  The symbol `_bdata' will be defined as the
   2463 address following the `.text' output section aligned upward to a 4 byte
   2464 boundary.
   2465 
   2466 
   2467 File: ld.info,  Node: PROVIDE,  Next: PROVIDE_HIDDEN,  Prev: Simple Assignments,  Up: Assignments
   2468 
   2469 3.5.2 PROVIDE
   2470 -------------
   2471 
   2472 In some cases, it is desirable for a linker script to define a symbol
   2473 only if it is referenced and is not defined by any object included in
   2474 the link.  For example, traditional linkers defined the symbol `etext'.
   2475 However, ANSI C requires that the user be able to use `etext' as a
   2476 function name without encountering an error.  The `PROVIDE' keyword may
   2477 be used to define a symbol, such as `etext', only if it is referenced
   2478 but not defined.  The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.
   2479 
   2480    Here is an example of using `PROVIDE' to define `etext':
   2481      SECTIONS
   2482      {
   2483        .text :
   2484          {
   2485            *(.text)
   2486            _etext = .;
   2487            PROVIDE(etext = .);
   2488          }
   2489      }
   2490 
   2491    In this example, if the program defines `_etext' (with a leading
   2492 underscore), the linker will give a multiple definition error.  If, on
   2493 the other hand, the program defines `etext' (with no leading
   2494 underscore), the linker will silently use the definition in the program.
   2495 If the program references `etext' but does not define it, the linker
   2496 will use the definition in the linker script.
   2497 
   2498 
   2499 File: ld.info,  Node: PROVIDE_HIDDEN,  Next: Source Code Reference,  Prev: PROVIDE,  Up: Assignments
   2500 
   2501 3.5.3 PROVIDE_HIDDEN
   2502 --------------------
   2503 
   2504 Similar to `PROVIDE'.  For ELF targeted ports, the symbol will be
   2505 hidden and won't be exported.
   2506 
   2507 
   2508 File: ld.info,  Node: Source Code Reference,  Prev: PROVIDE_HIDDEN,  Up: Assignments
   2509 
   2510 3.5.4 Source Code Reference
   2511 ---------------------------
   2512 
   2513 Accessing a linker script defined variable from source code is not
   2514 intuitive.  In particular a linker script symbol is not equivalent to a
   2515 variable declaration in a high level language, it is instead a symbol
   2516 that does not have a value.
   2517 
   2518    Before going further, it is important to note that compilers often
   2519 transform names in the source code into different names when they are
   2520 stored in the symbol table.  For example, Fortran compilers commonly
   2521 prepend or append an underscore, and C++ performs extensive `name
   2522 mangling'.  Therefore there might be a discrepancy between the name of
   2523 a variable as it is used in source code and the name of the same
   2524 variable as it is defined in a linker script.  For example in C a
   2525 linker script variable might be referred to as:
   2526 
   2527        extern int foo;
   2528 
   2529    But in the linker script it might be defined as:
   2530 
   2531        _foo = 1000;
   2532 
   2533    In the remaining examples however it is assumed that no name
   2534 transformation has taken place.
   2535 
   2536    When a symbol is declared in a high level language such as C, two
   2537 things happen.  The first is that the compiler reserves enough space in
   2538 the program's memory to hold the _value_ of the symbol.  The second is
   2539 that the compiler creates an entry in the program's symbol table which
   2540 holds the symbol's _address_.  ie the symbol table contains the address
   2541 of the block of memory holding the symbol's value.  So for example the
   2542 following C declaration, at file scope:
   2543 
   2544        int foo = 1000;
   2545 
   2546    creates a entry called `foo' in the symbol table.  This entry holds
   2547 the address of an `int' sized block of memory where the number 1000 is
   2548 initially stored.
   2549 
   2550    When a program references a symbol the compiler generates code that
   2551 first accesses the symbol table to find the address of the symbol's
   2552 memory block and then code to read the value from that memory block.
   2553 So:
   2554 
   2555        foo = 1;
   2556 
   2557    looks up the symbol `foo' in the symbol table, gets the address
   2558 associated with this symbol and then writes the value 1 into that
   2559 address.  Whereas:
   2560 
   2561        int * a = & foo;
   2562 
   2563    looks up the symbol `foo' in the symbol table, gets it address and
   2564 then copies this address into the block of memory associated with the
   2565 variable `a'.
   2566 
   2567    Linker scripts symbol declarations, by contrast, create an entry in
   2568 the symbol table but do not assign any memory to them.  Thus they are
   2569 an address without a value.  So for example the linker script
   2570 definition:
   2571 
   2572        foo = 1000;
   2573 
   2574    creates an entry in the symbol table called `foo' which holds the
   2575 address of memory location 1000, but nothing special is stored at
   2576 address 1000.  This means that you cannot access the _value_ of a
   2577 linker script defined symbol - it has no value - all you can do is
   2578 access the _address_ of a linker script defined symbol.
   2579 
   2580    Hence when you are using a linker script defined symbol in source
   2581 code you should always take the address of the symbol, and never
   2582 attempt to use its value.  For example suppose you want to copy the
   2583 contents of a section of memory called .ROM into a section called
   2584 .FLASH and the linker script contains these declarations:
   2585 
   2586        start_of_ROM   = .ROM;
   2587        end_of_ROM     = .ROM + sizeof (.ROM) - 1;
   2588        start_of_FLASH = .FLASH;
   2589 
   2590    Then the C source code to perform the copy would be:
   2591 
   2592        extern char start_of_ROM, end_of_ROM, start_of_FLASH;
   2593 
   2594        memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
   2595 
   2596    Note the use of the `&' operators.  These are correct.
   2597 
   2598 
   2599 File: ld.info,  Node: SECTIONS,  Next: MEMORY,  Prev: Assignments,  Up: Scripts
   2600 
   2601 3.6 SECTIONS Command
   2602 ====================
   2603 
   2604 The `SECTIONS' command tells the linker how to map input sections into
   2605 output sections, and how to place the output sections in memory.
   2606 
   2607    The format of the `SECTIONS' command is:
   2608      SECTIONS
   2609      {
   2610        SECTIONS-COMMAND
   2611        SECTIONS-COMMAND
   2612        ...
   2613      }
   2614 
   2615    Each SECTIONS-COMMAND may of be one of the following:
   2616 
   2617    * an `ENTRY' command (*note Entry command: Entry Point.)
   2618 
   2619    * a symbol assignment (*note Assignments::)
   2620 
   2621    * an output section description
   2622 
   2623    * an overlay description
   2624 
   2625    The `ENTRY' command and symbol assignments are permitted inside the
   2626 `SECTIONS' command for convenience in using the location counter in
   2627 those commands.  This can also make the linker script easier to
   2628 understand because you can use those commands at meaningful points in
   2629 the layout of the output file.
   2630 
   2631    Output section descriptions and overlay descriptions are described
   2632 below.
   2633 
   2634    If you do not use a `SECTIONS' command in your linker script, the
   2635 linker will place each input section into an identically named output
   2636 section in the order that the sections are first encountered in the
   2637 input files.  If all input sections are present in the first file, for
   2638 example, the order of sections in the output file will match the order
   2639 in the first input file.  The first section will be at address zero.
   2640 
   2641 * Menu:
   2642 
   2643 * Output Section Description::	Output section description
   2644 * Output Section Name::		Output section name
   2645 * Output Section Address::	Output section address
   2646 * Input Section::		Input section description
   2647 * Output Section Data::		Output section data
   2648 * Output Section Keywords::	Output section keywords
   2649 * Output Section Discarding::	Output section discarding
   2650 * Output Section Attributes::	Output section attributes
   2651 * Overlay Description::		Overlay description
   2652 
   2653 
   2654 File: ld.info,  Node: Output Section Description,  Next: Output Section Name,  Up: SECTIONS
   2655 
   2656 3.6.1 Output Section Description
   2657 --------------------------------
   2658 
   2659 The full description of an output section looks like this:
   2660      SECTION [ADDRESS] [(TYPE)] :
   2661        [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
   2662        {
   2663          OUTPUT-SECTION-COMMAND
   2664          OUTPUT-SECTION-COMMAND
   2665          ...
   2666        } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
   2667 
   2668    Most output sections do not use most of the optional section
   2669 attributes.
   2670 
   2671    The whitespace around SECTION is required, so that the section name
   2672 is unambiguous.  The colon and the curly braces are also required.  The
   2673 line breaks and other white space are optional.
   2674 
   2675    Each OUTPUT-SECTION-COMMAND may be one of the following:
   2676 
   2677    * a symbol assignment (*note Assignments::)
   2678 
   2679    * an input section description (*note Input Section::)
   2680 
   2681    * data values to include directly (*note Output Section Data::)
   2682 
   2683    * a special output section keyword (*note Output Section Keywords::)
   2684 
   2685 
   2686 File: ld.info,  Node: Output Section Name,  Next: Output Section Address,  Prev: Output Section Description,  Up: SECTIONS
   2687 
   2688 3.6.2 Output Section Name
   2689 -------------------------
   2690 
   2691 The name of the output section is SECTION.  SECTION must meet the
   2692 constraints of your output format.  In formats which only support a
   2693 limited number of sections, such as `a.out', the name must be one of
   2694 the names supported by the format (`a.out', for example, allows only
   2695 `.text', `.data' or `.bss'). If the output format supports any number
   2696 of sections, but with numbers and not names (as is the case for Oasys),
   2697 the name should be supplied as a quoted numeric string.  A section name
   2698 may consist of any sequence of characters, but a name which contains
   2699 any unusual characters such as commas must be quoted.
   2700 
   2701    The output section name `/DISCARD/' is special; *note Output Section
   2702 Discarding::.
   2703 
   2704 
   2705 File: ld.info,  Node: Output Section Address,  Next: Input Section,  Prev: Output Section Name,  Up: SECTIONS
   2706 
   2707 3.6.3 Output Section Address
   2708 ----------------------------
   2709 
   2710 The ADDRESS is an expression for the VMA (the virtual memory address)
   2711 of the output section.  If you do not provide ADDRESS, the linker will
   2712 set it based on REGION if present, or otherwise based on the current
   2713 value of the location counter.
   2714 
   2715    If you provide ADDRESS, the address of the output section will be
   2716 set to precisely that.  If you provide neither ADDRESS nor REGION, then
   2717 the address of the output section will be set to the current value of
   2718 the location counter aligned to the alignment requirements of the
   2719 output section.  The alignment requirement of the output section is the
   2720 strictest alignment of any input section contained within the output
   2721 section.
   2722 
   2723    For example,
   2724      .text . : { *(.text) }
   2725    and
   2726      .text : { *(.text) }
   2727    are subtly different.  The first will set the address of the `.text'
   2728 output section to the current value of the location counter.  The
   2729 second will set it to the current value of the location counter aligned
   2730 to the strictest alignment of a `.text' input section.
   2731 
   2732    The ADDRESS may be an arbitrary expression; *note Expressions::.
   2733 For example, if you want to align the section on a 0x10 byte boundary,
   2734 so that the lowest four bits of the section address are zero, you could
   2735 do something like this:
   2736      .text ALIGN(0x10) : { *(.text) }
   2737    This works because `ALIGN' returns the current location counter
   2738 aligned upward to the specified value.
   2739 
   2740    Specifying ADDRESS for a section will change the value of the
   2741 location counter.
   2742 
   2743 
   2744 File: ld.info,  Node: Input Section,  Next: Output Section Data,  Prev: Output Section Address,  Up: SECTIONS
   2745 
   2746 3.6.4 Input Section Description
   2747 -------------------------------
   2748 
   2749 The most common output section command is an input section description.
   2750 
   2751    The input section description is the most basic linker script
   2752 operation.  You use output sections to tell the linker how to lay out
   2753 your program in memory.  You use input section descriptions to tell the
   2754 linker how to map the input files into your memory layout.
   2755 
   2756 * Menu:
   2757 
   2758 * Input Section Basics::	Input section basics
   2759 * Input Section Wildcards::	Input section wildcard patterns
   2760 * Input Section Common::	Input section for common symbols
   2761 * Input Section Keep::		Input section and garbage collection
   2762 * Input Section Example::	Input section example
   2763 
   2764 
   2765 File: ld.info,  Node: Input Section Basics,  Next: Input Section Wildcards,  Up: Input Section
   2766 
   2767 3.6.4.1 Input Section Basics
   2768 ............................
   2769 
   2770 An input section description consists of a file name optionally followed
   2771 by a list of section names in parentheses.
   2772 
   2773    The file name and the section name may be wildcard patterns, which we
   2774 describe further below (*note Input Section Wildcards::).
   2775 
   2776    The most common input section description is to include all input
   2777 sections with a particular name in the output section.  For example, to
   2778 include all input `.text' sections, you would write:
   2779      *(.text)
   2780    Here the `*' is a wildcard which matches any file name.  To exclude
   2781 a list of files from matching the file name wildcard, EXCLUDE_FILE may
   2782 be used to match all files except the ones specified in the
   2783 EXCLUDE_FILE list.  For example:
   2784      *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
   2785    will cause all .ctors sections from all files except `crtend.o' and
   2786 `otherfile.o' to be included.
   2787 
   2788    There are two ways to include more than one section:
   2789      *(.text .rdata)
   2790      *(.text) *(.rdata)
   2791    The difference between these is the order in which the `.text' and
   2792 `.rdata' input sections will appear in the output section.  In the
   2793 first example, they will be intermingled, appearing in the same order as
   2794 they are found in the linker input.  In the second example, all `.text'
   2795 input sections will appear first, followed by all `.rdata' input
   2796 sections.
   2797 
   2798    You can specify a file name to include sections from a particular
   2799 file.  You would do this if one or more of your files contain special
   2800 data that needs to be at a particular location in memory.  For example:
   2801      data.o(.data)
   2802 
   2803    You can also specify files within archives by writing a pattern
   2804 matching the archive, a colon, then the pattern matching the file, with
   2805 no whitespace around the colon.
   2806 
   2807 `archive:file'
   2808      matches file within archive
   2809 
   2810 `archive:'
   2811      matches the whole archive
   2812 
   2813 `:file'
   2814      matches file but not one in an archive
   2815 
   2816    Either one or both of `archive' and `file' can contain shell
   2817 wildcards.  On DOS based file systems, the linker will assume that a
   2818 single letter followed by a colon is a drive specifier, so `c:myfile.o'
   2819 is a simple file specification, not `myfile.o' within an archive called
   2820 `c'.  `archive:file' filespecs may also be used within an
   2821 `EXCLUDE_FILE' list, but may not appear in other linker script
   2822 contexts.  For instance, you cannot extract a file from an archive by
   2823 using `archive:file' in an `INPUT' command.
   2824 
   2825    If you use a file name without a list of sections, then all sections
   2826 in the input file will be included in the output section.  This is not
   2827 commonly done, but it may by useful on occasion.  For example:
   2828      data.o
   2829 
   2830    When you use a file name which is not an `archive:file' specifier
   2831 and does not contain any wild card characters, the linker will first
   2832 see if you also specified the file name on the linker command line or
   2833 in an `INPUT' command.  If you did not, the linker will attempt to open
   2834 the file as an input file, as though it appeared on the command line.
   2835 Note that this differs from an `INPUT' command, because the linker will
   2836 not search for the file in the archive search path.
   2837 
   2838 
   2839 File: ld.info,  Node: Input Section Wildcards,  Next: Input Section Common,  Prev: Input Section Basics,  Up: Input Section
   2840 
   2841 3.6.4.2 Input Section Wildcard Patterns
   2842 .......................................
   2843 
   2844 In an input section description, either the file name or the section
   2845 name or both may be wildcard patterns.
   2846 
   2847    The file name of `*' seen in many examples is a simple wildcard
   2848 pattern for the file name.
   2849 
   2850    The wildcard patterns are like those used by the Unix shell.
   2851 
   2852 `*'
   2853      matches any number of characters
   2854 
   2855 `?'
   2856      matches any single character
   2857 
   2858 `[CHARS]'
   2859      matches a single instance of any of the CHARS; the `-' character
   2860      may be used to specify a range of characters, as in `[a-z]' to
   2861      match any lower case letter
   2862 
   2863 `\'
   2864      quotes the following character
   2865 
   2866    When a file name is matched with a wildcard, the wildcard characters
   2867 will not match a `/' character (used to separate directory names on
   2868 Unix).  A pattern consisting of a single `*' character is an exception;
   2869 it will always match any file name, whether it contains a `/' or not.
   2870 In a section name, the wildcard characters will match a `/' character.
   2871 
   2872    File name wildcard patterns only match files which are explicitly
   2873 specified on the command line or in an `INPUT' command.  The linker
   2874 does not search directories to expand wildcards.
   2875 
   2876    If a file name matches more than one wildcard pattern, or if a file
   2877 name appears explicitly and is also matched by a wildcard pattern, the
   2878 linker will use the first match in the linker script.  For example, this
   2879 sequence of input section descriptions is probably in error, because the
   2880 `data.o' rule will not be used:
   2881      .data : { *(.data) }
   2882      .data1 : { data.o(.data) }
   2883 
   2884    Normally, the linker will place files and sections matched by
   2885 wildcards in the order in which they are seen during the link.  You can
   2886 change this by using the `SORT_BY_NAME' keyword, which appears before a
   2887 wildcard pattern in parentheses (e.g., `SORT_BY_NAME(.text*)').  When
   2888 the `SORT_BY_NAME' keyword is used, the linker will sort the files or
   2889 sections into ascending order by name before placing them in the output
   2890 file.
   2891 
   2892    `SORT_BY_ALIGNMENT' is very similar to `SORT_BY_NAME'. The
   2893 difference is `SORT_BY_ALIGNMENT' will sort sections into ascending
   2894 order by alignment before placing them in the output file.
   2895 
   2896    `SORT' is an alias for `SORT_BY_NAME'.
   2897 
   2898    When there are nested section sorting commands in linker script,
   2899 there can be at most 1 level of nesting for section sorting commands.
   2900 
   2901   1. `SORT_BY_NAME' (`SORT_BY_ALIGNMENT' (wildcard section pattern)).
   2902      It will sort the input sections by name first, then by alignment
   2903      if 2 sections have the same name.
   2904 
   2905   2. `SORT_BY_ALIGNMENT' (`SORT_BY_NAME' (wildcard section pattern)).
   2906      It will sort the input sections by alignment first, then by name
   2907      if 2 sections have the same alignment.
   2908 
   2909   3. `SORT_BY_NAME' (`SORT_BY_NAME' (wildcard section pattern)) is
   2910      treated the same as `SORT_BY_NAME' (wildcard section pattern).
   2911 
   2912   4. `SORT_BY_ALIGNMENT' (`SORT_BY_ALIGNMENT' (wildcard section
   2913      pattern)) is treated the same as `SORT_BY_ALIGNMENT' (wildcard
   2914      section pattern).
   2915 
   2916   5. All other nested section sorting commands are invalid.
   2917 
   2918    When both command line section sorting option and linker script
   2919 section sorting command are used, section sorting command always takes
   2920 precedence over the command line option.
   2921 
   2922    If the section sorting command in linker script isn't nested, the
   2923 command line option will make the section sorting command to be treated
   2924 as nested sorting command.
   2925 
   2926   1. `SORT_BY_NAME' (wildcard section pattern ) with `--sort-sections
   2927      alignment' is equivalent to `SORT_BY_NAME' (`SORT_BY_ALIGNMENT'
   2928      (wildcard section pattern)).
   2929 
   2930   2. `SORT_BY_ALIGNMENT' (wildcard section pattern) with
   2931      `--sort-section name' is equivalent to `SORT_BY_ALIGNMENT'
   2932      (`SORT_BY_NAME' (wildcard section pattern)).
   2933 
   2934    If the section sorting command in linker script is nested, the
   2935 command line option will be ignored.
   2936 
   2937    If you ever get confused about where input sections are going, use
   2938 the `-M' linker option to generate a map file.  The map file shows
   2939 precisely how input sections are mapped to output sections.
   2940 
   2941    This example shows how wildcard patterns might be used to partition
   2942 files.  This linker script directs the linker to place all `.text'
   2943 sections in `.text' and all `.bss' sections in `.bss'.  The linker will
   2944 place the `.data' section from all files beginning with an upper case
   2945 character in `.DATA'; for all other files, the linker will place the
   2946 `.data' section in `.data'.
   2947      SECTIONS {
   2948        .text : { *(.text) }
   2949        .DATA : { [A-Z]*(.data) }
   2950        .data : { *(.data) }
   2951        .bss : { *(.bss) }
   2952      }
   2953 
   2954 
   2955 File: ld.info,  Node: Input Section Common,  Next: Input Section Keep,  Prev: Input Section Wildcards,  Up: Input Section
   2956 
   2957 3.6.4.3 Input Section for Common Symbols
   2958 ........................................
   2959 
   2960 A special notation is needed for common symbols, because in many object
   2961 file formats common symbols do not have a particular input section.  The
   2962 linker treats common symbols as though they are in an input section
   2963 named `COMMON'.
   2964 
   2965    You may use file names with the `COMMON' section just as with any
   2966 other input sections.  You can use this to place common symbols from a
   2967 particular input file in one section while common symbols from other
   2968 input files are placed in another section.
   2969 
   2970    In most cases, common symbols in input files will be placed in the
   2971 `.bss' section in the output file.  For example:
   2972      .bss { *(.bss) *(COMMON) }
   2973 
   2974    Some object file formats have more than one type of common symbol.
   2975 For example, the MIPS ELF object file format distinguishes standard
   2976 common symbols and small common symbols.  In this case, the linker will
   2977 use a different special section name for other types of common symbols.
   2978 In the case of MIPS ELF, the linker uses `COMMON' for standard common
   2979 symbols and `.scommon' for small common symbols.  This permits you to
   2980 map the different types of common symbols into memory at different
   2981 locations.
   2982 
   2983    You will sometimes see `[COMMON]' in old linker scripts.  This
   2984 notation is now considered obsolete.  It is equivalent to `*(COMMON)'.
   2985 
   2986 
   2987 File: ld.info,  Node: Input Section Keep,  Next: Input Section Example,  Prev: Input Section Common,  Up: Input Section
   2988 
   2989 3.6.4.4 Input Section and Garbage Collection
   2990 ............................................
   2991 
   2992 When link-time garbage collection is in use (`--gc-sections'), it is
   2993 often useful to mark sections that should not be eliminated.  This is
   2994 accomplished by surrounding an input section's wildcard entry with
   2995 `KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT_BY_NAME(*)(.ctors))'.
   2996 
   2997 
   2998 File: ld.info,  Node: Input Section Example,  Prev: Input Section Keep,  Up: Input Section
   2999 
   3000 3.6.4.5 Input Section Example
   3001 .............................
   3002 
   3003 The following example is a complete linker script.  It tells the linker
   3004 to read all of the sections from file `all.o' and place them at the
   3005 start of output section `outputa' which starts at location `0x10000'.
   3006 All of section `.input1' from file `foo.o' follows immediately, in the
   3007 same output section.  All of section `.input2' from `foo.o' goes into
   3008 output section `outputb', followed by section `.input1' from `foo1.o'.
   3009 All of the remaining `.input1' and `.input2' sections from any files
   3010 are written to output section `outputc'.
   3011 
   3012      SECTIONS {
   3013        outputa 0x10000 :
   3014          {
   3015          all.o
   3016          foo.o (.input1)
   3017          }
   3018        outputb :
   3019          {
   3020          foo.o (.input2)
   3021          foo1.o (.input1)
   3022          }
   3023        outputc :
   3024          {
   3025          *(.input1)
   3026          *(.input2)
   3027          }
   3028      }
   3029 
   3030 
   3031 File: ld.info,  Node: Output Section Data,  Next: Output Section Keywords,  Prev: Input Section,  Up: SECTIONS
   3032 
   3033 3.6.5 Output Section Data
   3034 -------------------------
   3035 
   3036 You can include explicit bytes of data in an output section by using
   3037 `BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
   3038 command.  Each keyword is followed by an expression in parentheses
   3039 providing the value to store (*note Expressions::).  The value of the
   3040 expression is stored at the current value of the location counter.
   3041 
   3042    The `BYTE', `SHORT', `LONG', and `QUAD' commands store one, two,
   3043 four, and eight bytes (respectively).  After storing the bytes, the
   3044 location counter is incremented by the number of bytes stored.
   3045 
   3046    For example, this will store the byte 1 followed by the four byte
   3047 value of the symbol `addr':
   3048      BYTE(1)
   3049      LONG(addr)
   3050 
   3051    When using a 64 bit host or target, `QUAD' and `SQUAD' are the same;
   3052 they both store an 8 byte, or 64 bit, value.  When both host and target
   3053 are 32 bits, an expression is computed as 32 bits.  In this case `QUAD'
   3054 stores a 32 bit value zero extended to 64 bits, and `SQUAD' stores a 32
   3055 bit value sign extended to 64 bits.
   3056 
   3057    If the object file format of the output file has an explicit
   3058 endianness, which is the normal case, the value will be stored in that
   3059 endianness.  When the object file format does not have an explicit
   3060 endianness, as is true of, for example, S-records, the value will be
   3061 stored in the endianness of the first input object file.
   3062 
   3063    Note--these commands only work inside a section description and not
   3064 between them, so the following will produce an error from the linker:
   3065      SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
   3066    whereas this will work:
   3067      SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }
   3068 
   3069    You may use the `FILL' command to set the fill pattern for the
   3070 current section.  It is followed by an expression in parentheses.  Any
   3071 otherwise unspecified regions of memory within the section (for example,
   3072 gaps left due to the required alignment of input sections) are filled
   3073 with the value of the expression, repeated as necessary.  A `FILL'
   3074 statement covers memory locations after the point at which it occurs in
   3075 the section definition; by including more than one `FILL' statement,
   3076 you can have different fill patterns in different parts of an output
   3077 section.
   3078 
   3079    This example shows how to fill unspecified regions of memory with the
   3080 value `0x90':
   3081      FILL(0x90909090)
   3082 
   3083    The `FILL' command is similar to the `=FILLEXP' output section
   3084 attribute, but it only affects the part of the section following the
   3085 `FILL' command, rather than the entire section.  If both are used, the
   3086 `FILL' command takes precedence.  *Note Output Section Fill::, for
   3087 details on the fill expression.
   3088 
   3089 
   3090 File: ld.info,  Node: Output Section Keywords,  Next: Output Section Discarding,  Prev: Output Section Data,  Up: SECTIONS
   3091 
   3092 3.6.6 Output Section Keywords
   3093 -----------------------------
   3094 
   3095 There are a couple of keywords which can appear as output section
   3096 commands.
   3097 
   3098 `CREATE_OBJECT_SYMBOLS'
   3099      The command tells the linker to create a symbol for each input
   3100      file.  The name of each symbol will be the name of the
   3101      corresponding input file.  The section of each symbol will be the
   3102      output section in which the `CREATE_OBJECT_SYMBOLS' command
   3103      appears.
   3104 
   3105      This is conventional for the a.out object file format.  It is not
   3106      normally used for any other object file format.
   3107 
   3108 `CONSTRUCTORS'
   3109      When linking using the a.out object file format, the linker uses an
   3110      unusual set construct to support C++ global constructors and
   3111      destructors.  When linking object file formats which do not support
   3112      arbitrary sections, such as ECOFF and XCOFF, the linker will
   3113      automatically recognize C++ global constructors and destructors by
   3114      name.  For these object file formats, the `CONSTRUCTORS' command
   3115      tells the linker to place constructor information in the output
   3116      section where the `CONSTRUCTORS' command appears.  The
   3117      `CONSTRUCTORS' command is ignored for other object file formats.
   3118 
   3119      The symbol `__CTOR_LIST__' marks the start of the global
   3120      constructors, and the symbol `__CTOR_END__' marks the end.
   3121      Similarly, `__DTOR_LIST__' and `__DTOR_END__' mark the start and
   3122      end of the global destructors.  The first word in the list is the
   3123      number of entries, followed by the address of each constructor or
   3124      destructor, followed by a zero word.  The compiler must arrange to
   3125      actually run the code.  For these object file formats GNU C++
   3126      normally calls constructors from a subroutine `__main'; a call to
   3127      `__main' is automatically inserted into the startup code for
   3128      `main'.  GNU C++ normally runs destructors either by using
   3129      `atexit', or directly from the function `exit'.
   3130 
   3131      For object file formats such as `COFF' or `ELF' which support
   3132      arbitrary section names, GNU C++ will normally arrange to put the
   3133      addresses of global constructors and destructors into the `.ctors'
   3134      and `.dtors' sections.  Placing the following sequence into your
   3135      linker script will build the sort of table which the GNU C++
   3136      runtime code expects to see.
   3137 
   3138                 __CTOR_LIST__ = .;
   3139                 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
   3140                 *(.ctors)
   3141                 LONG(0)
   3142                 __CTOR_END__ = .;
   3143                 __DTOR_LIST__ = .;
   3144                 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
   3145                 *(.dtors)
   3146                 LONG(0)
   3147                 __DTOR_END__ = .;
   3148 
   3149      If you are using the GNU C++ support for initialization priority,
   3150      which provides some control over the order in which global
   3151      constructors are run, you must sort the constructors at link time
   3152      to ensure that they are executed in the correct order.  When using
   3153      the `CONSTRUCTORS' command, use `SORT_BY_NAME(CONSTRUCTORS)'
   3154      instead.  When using the `.ctors' and `.dtors' sections, use
   3155      `*(SORT_BY_NAME(.ctors))' and `*(SORT_BY_NAME(.dtors))' instead of
   3156      just `*(.ctors)' and `*(.dtors)'.
   3157 
   3158      Normally the compiler and linker will handle these issues
   3159      automatically, and you will not need to concern yourself with
   3160      them.  However, you may need to consider this if you are using C++
   3161      and writing your own linker scripts.
   3162 
   3163 
   3164 
   3165 File: ld.info,  Node: Output Section Discarding,  Next: Output Section Attributes,  Prev: Output Section Keywords,  Up: SECTIONS
   3166 
   3167 3.6.7 Output Section Discarding
   3168 -------------------------------
   3169 
   3170 The linker will not create output sections with no contents.  This is
   3171 for convenience when referring to input sections that may or may not be
   3172 present in any of the input files.  For example:
   3173      .foo : { *(.foo) }
   3174    will only create a `.foo' section in the output file if there is a
   3175 `.foo' section in at least one input file, and if the input sections
   3176 are not all empty.  Other link script directives that allocate space in
   3177 an output section will also create the output section.
   3178 
   3179    The linker will ignore address assignments (*note Output Section
   3180 Address::) on discarded output sections, except when the linker script
   3181 defines symbols in the output section.  In that case the linker will
   3182 obey the address assignments, possibly advancing dot even though the
   3183 section is discarded.
   3184 
   3185    The special output section name `/DISCARD/' may be used to discard
   3186 input sections.  Any input sections which are assigned to an output
   3187 section named `/DISCARD/' are not included in the output file.
   3188 
   3189 
   3190 File: ld.info,  Node: Output Section Attributes,  Next: Overlay Description,  Prev: Output Section Discarding,  Up: SECTIONS
   3191 
   3192 3.6.8 Output Section Attributes
   3193 -------------------------------
   3194 
   3195 We showed above that the full description of an output section looked
   3196 like this:
   3197      SECTION [ADDRESS] [(TYPE)] :
   3198        [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
   3199        {
   3200          OUTPUT-SECTION-COMMAND
   3201          OUTPUT-SECTION-COMMAND
   3202          ...
   3203        } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
   3204 We've already described SECTION, ADDRESS, and OUTPUT-SECTION-COMMAND.
   3205 In this section we will describe the remaining section attributes.
   3206 
   3207 * Menu:
   3208 
   3209 * Output Section Type::		Output section type
   3210 * Output Section LMA::		Output section LMA
   3211 * Forced Output Alignment::	Forced Output Alignment
   3212 * Forced Input Alignment::	Forced Input Alignment
   3213 * Output Section Region::	Output section region
   3214 * Output Section Phdr::		Output section phdr
   3215 * Output Section Fill::		Output section fill
   3216 
   3217 
   3218 File: ld.info,  Node: Output Section Type,  Next: Output Section LMA,  Up: Output Section Attributes
   3219 
   3220 3.6.8.1 Output Section Type
   3221 ...........................
   3222 
   3223 Each output section may have a type.  The type is a keyword in
   3224 parentheses.  The following types are defined:
   3225 
   3226 `NOLOAD'
   3227      The section should be marked as not loadable, so that it will not
   3228      be loaded into memory when the program is run.
   3229 
   3230 `DSECT'
   3231 `COPY'
   3232 `INFO'
   3233 `OVERLAY'
   3234      These type names are supported for backward compatibility, and are
   3235      rarely used.  They all have the same effect: the section should be
   3236      marked as not allocatable, so that no memory is allocated for the
   3237      section when the program is run.
   3238 
   3239    The linker normally sets the attributes of an output section based on
   3240 the input sections which map into it.  You can override this by using
   3241 the section type.  For example, in the script sample below, the `ROM'
   3242 section is addressed at memory location `0' and does not need to be
   3243 loaded when the program is run.  The contents of the `ROM' section will
   3244 appear in the linker output file as usual.
   3245      SECTIONS {
   3246        ROM 0 (NOLOAD) : { ... }
   3247        ...
   3248      }
   3249 
   3250 
   3251 File: ld.info,  Node: Output Section LMA,  Next: Forced Output Alignment,  Prev: Output Section Type,  Up: Output Section Attributes
   3252 
   3253 3.6.8.2 Output Section LMA
   3254 ..........................
   3255 
   3256 Every section has a virtual address (VMA) and a load address (LMA); see
   3257 *note Basic Script Concepts::.  The address expression which may appear
   3258 in an output section description sets the VMA (*note Output Section
   3259 Address::).
   3260 
   3261    The expression LMA that follows the `AT' keyword specifies the load
   3262 address of the section.
   3263 
   3264    Alternatively, with `AT>LMA_REGION' expression, you may specify a
   3265 memory region for the section's load address. *Note MEMORY::.  Note
   3266 that if the section has not had a VMA assigned to it then the linker
   3267 will use the LMA_REGION as the VMA region as well.
   3268 
   3269    If neither `AT' nor `AT>' is specified for an allocatable section,
   3270 the linker will set the LMA such that the difference between VMA and
   3271 LMA for the section is the same as the preceding output section in the
   3272 same region.  If there is no preceding output section or the section is
   3273 not allocatable, the linker will set the LMA equal to the VMA.  *Note
   3274 Output Section Region::.
   3275 
   3276    This feature is designed to make it easy to build a ROM image.  For
   3277 example, the following linker script creates three output sections: one
   3278 called `.text', which starts at `0x1000', one called `.mdata', which is
   3279 loaded at the end of the `.text' section even though its VMA is
   3280 `0x2000', and one called `.bss' to hold uninitialized data at address
   3281 `0x3000'.  The symbol `_data' is defined with the value `0x2000', which
   3282 shows that the location counter holds the VMA value, not the LMA value.
   3283 
   3284      SECTIONS
   3285        {
   3286        .text 0x1000 : { *(.text) _etext = . ; }
   3287        .mdata 0x2000 :
   3288          AT ( ADDR (.text) + SIZEOF (.text) )
   3289          { _data = . ; *(.data); _edata = . ;  }
   3290        .bss 0x3000 :
   3291          { _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;}
   3292      }
   3293 
   3294    The run-time initialization code for use with a program generated
   3295 with this linker script would include something like the following, to
   3296 copy the initialized data from the ROM image to its runtime address.
   3297 Notice how this code takes advantage of the symbols defined by the
   3298 linker script.
   3299 
   3300      extern char _etext, _data, _edata, _bstart, _bend;
   3301      char *src = &_etext;
   3302      char *dst = &_data;
   3303 
   3304      /* ROM has data at end of text; copy it. */
   3305      while (dst < &_edata) {
   3306        *dst++ = *src++;
   3307      }
   3308 
   3309      /* Zero bss */
   3310      for (dst = &_bstart; dst< &_bend; dst++)
   3311        *dst = 0;
   3312 
   3313 
   3314 File: ld.info,  Node: Forced Output Alignment,  Next: Forced Input Alignment,  Prev: Output Section LMA,  Up: Output Section Attributes
   3315 
   3316 3.6.8.3 Forced Output Alignment
   3317 ...............................
   3318 
   3319 You can increase an output section's alignment by using ALIGN.
   3320 
   3321 
   3322 File: ld.info,  Node: Forced Input Alignment,  Next: Output Section Region,  Prev: Forced Output Alignment,  Up: Output Section Attributes
   3323 
   3324 3.6.8.4 Forced Input Alignment
   3325 ..............................
   3326 
   3327 You can force input section alignment within an output section by using
   3328 SUBALIGN.  The value specified overrides any alignment given by input
   3329 sections, whether larger or smaller.
   3330 
   3331 
   3332 File: ld.info,  Node: Output Section Region,  Next: Output Section Phdr,  Prev: Forced Input Alignment,  Up: Output Section Attributes
   3333 
   3334 3.6.8.5 Output Section Region
   3335 .............................
   3336 
   3337 You can assign a section to a previously defined region of memory by
   3338 using `>REGION'.  *Note MEMORY::.
   3339 
   3340    Here is a simple example:
   3341      MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
   3342      SECTIONS { ROM : { *(.text) } >rom }
   3343 
   3344 
   3345 File: ld.info,  Node: Output Section Phdr,  Next: Output Section Fill,  Prev: Output Section Region,  Up: Output Section Attributes
   3346 
   3347 3.6.8.6 Output Section Phdr
   3348 ...........................
   3349 
   3350 You can assign a section to a previously defined program segment by
   3351 using `:PHDR'.  *Note PHDRS::.  If a section is assigned to one or more
   3352 segments, then all subsequent allocated sections will be assigned to
   3353 those segments as well, unless they use an explicitly `:PHDR' modifier.
   3354 You can use `:NONE' to tell the linker to not put the section in any
   3355 segment at all.
   3356 
   3357    Here is a simple example:
   3358      PHDRS { text PT_LOAD ; }
   3359      SECTIONS { .text : { *(.text) } :text }
   3360 
   3361 
   3362 File: ld.info,  Node: Output Section Fill,  Prev: Output Section Phdr,  Up: Output Section Attributes
   3363 
   3364 3.6.8.7 Output Section Fill
   3365 ...........................
   3366 
   3367 You can set the fill pattern for an entire section by using `=FILLEXP'.
   3368 FILLEXP is an expression (*note Expressions::).  Any otherwise
   3369 unspecified regions of memory within the output section (for example,
   3370 gaps left due to the required alignment of input sections) will be
   3371 filled with the value, repeated as necessary.  If the fill expression
   3372 is a simple hex number, ie. a string of hex digit starting with `0x'
   3373 and without a trailing `k' or `M', then an arbitrarily long sequence of
   3374 hex digits can be used to specify the fill pattern;  Leading zeros
   3375 become part of the pattern too.  For all other cases, including extra
   3376 parentheses or a unary `+', the fill pattern is the four least
   3377 significant bytes of the value of the expression.  In all cases, the
   3378 number is big-endian.
   3379 
   3380    You can also change the fill value with a `FILL' command in the
   3381 output section commands; (*note Output Section Data::).
   3382 
   3383    Here is a simple example:
   3384      SECTIONS { .text : { *(.text) } =0x90909090 }
   3385 
   3386 
   3387 File: ld.info,  Node: Overlay Description,  Prev: Output Section Attributes,  Up: SECTIONS
   3388 
   3389 3.6.9 Overlay Description
   3390 -------------------------
   3391 
   3392 An overlay description provides an easy way to describe sections which
   3393 are to be loaded as part of a single memory image but are to be run at
   3394 the same memory address.  At run time, some sort of overlay manager will
   3395 copy the overlaid sections in and out of the runtime memory address as
   3396 required, perhaps by simply manipulating addressing bits.  This approach
   3397 can be useful, for example, when a certain region of memory is faster
   3398 than another.
   3399 
   3400    Overlays are described using the `OVERLAY' command.  The `OVERLAY'
   3401 command is used within a `SECTIONS' command, like an output section
   3402 description.  The full syntax of the `OVERLAY' command is as follows:
   3403      OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
   3404        {
   3405          SECNAME1
   3406            {
   3407              OUTPUT-SECTION-COMMAND
   3408              OUTPUT-SECTION-COMMAND
   3409              ...
   3410            } [:PHDR...] [=FILL]
   3411          SECNAME2
   3412            {
   3413              OUTPUT-SECTION-COMMAND
   3414              OUTPUT-SECTION-COMMAND
   3415              ...
   3416            } [:PHDR...] [=FILL]
   3417          ...
   3418        } [>REGION] [:PHDR...] [=FILL]
   3419 
   3420    Everything is optional except `OVERLAY' (a keyword), and each
   3421 section must have a name (SECNAME1 and SECNAME2 above).  The section
   3422 definitions within the `OVERLAY' construct are identical to those
   3423 within the general `SECTIONS' contruct (*note SECTIONS::), except that
   3424 no addresses and no memory regions may be defined for sections within
   3425 an `OVERLAY'.
   3426 
   3427    The sections are all defined with the same starting address.  The
   3428 load addresses of the sections are arranged such that they are
   3429 consecutive in memory starting at the load address used for the
   3430 `OVERLAY' as a whole (as with normal section definitions, the load
   3431 address is optional, and defaults to the start address; the start
   3432 address is also optional, and defaults to the current value of the
   3433 location counter).
   3434 
   3435    If the `NOCROSSREFS' keyword is used, and there any references among
   3436 the sections, the linker will report an error.  Since the sections all
   3437 run at the same address, it normally does not make sense for one
   3438 section to refer directly to another.  *Note NOCROSSREFS: Miscellaneous
   3439 Commands.
   3440 
   3441    For each section within the `OVERLAY', the linker automatically
   3442 provides two symbols.  The symbol `__load_start_SECNAME' is defined as
   3443 the starting load address of the section.  The symbol
   3444 `__load_stop_SECNAME' is defined as the final load address of the
   3445 section.  Any characters within SECNAME which are not legal within C
   3446 identifiers are removed.  C (or assembler) code may use these symbols
   3447 to move the overlaid sections around as necessary.
   3448 
   3449    At the end of the overlay, the value of the location counter is set
   3450 to the start address of the overlay plus the size of the largest
   3451 section.
   3452 
   3453    Here is an example.  Remember that this would appear inside a
   3454 `SECTIONS' construct.
   3455        OVERLAY 0x1000 : AT (0x4000)
   3456         {
   3457           .text0 { o1/*.o(.text) }
   3458           .text1 { o2/*.o(.text) }
   3459         }
   3460 This will define both `.text0' and `.text1' to start at address 0x1000.
   3461 `.text0' will be loaded at address 0x4000, and `.text1' will be loaded
   3462 immediately after `.text0'.  The following symbols will be defined if
   3463 referenced: `__load_start_text0', `__load_stop_text0',
   3464 `__load_start_text1', `__load_stop_text1'.
   3465 
   3466    C code to copy overlay `.text1' into the overlay area might look
   3467 like the following.
   3468 
   3469        extern char __load_start_text1, __load_stop_text1;
   3470        memcpy ((char *) 0x1000, &__load_start_text1,
   3471                &__load_stop_text1 - &__load_start_text1);
   3472 
   3473    Note that the `OVERLAY' command is just syntactic sugar, since
   3474 everything it does can be done using the more basic commands.  The above
   3475 example could have been written identically as follows.
   3476 
   3477        .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
   3478        PROVIDE (__load_start_text0 = LOADADDR (.text0));
   3479        PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
   3480        .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
   3481        PROVIDE (__load_start_text1 = LOADADDR (.text1));
   3482        PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
   3483        . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
   3484 
   3485 
   3486 File: ld.info,  Node: MEMORY,  Next: PHDRS,  Prev: SECTIONS,  Up: Scripts
   3487 
   3488 3.7 MEMORY Command
   3489 ==================
   3490 
   3491 The linker's default configuration permits allocation of all available
   3492 memory.  You can override this by using the `MEMORY' command.
   3493 
   3494    The `MEMORY' command describes the location and size of blocks of
   3495 memory in the target.  You can use it to describe which memory regions
   3496 may be used by the linker, and which memory regions it must avoid.  You
   3497 can then assign sections to particular memory regions.  The linker will
   3498 set section addresses based on the memory regions, and will warn about
   3499 regions that become too full.  The linker will not shuffle sections
   3500 around to fit into the available regions.
   3501 
   3502    A linker script may contain at most one use of the `MEMORY' command.
   3503 However, you can define as many blocks of memory within it as you wish.
   3504 The syntax is:
   3505      MEMORY
   3506        {
   3507          NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
   3508          ...
   3509        }
   3510 
   3511    The NAME is a name used in the linker script to refer to the region.
   3512 The region name has no meaning outside of the linker script.  Region
   3513 names are stored in a separate name space, and will not conflict with
   3514 symbol names, file names, or section names.  Each memory region must
   3515 have a distinct name.
   3516 
   3517    The ATTR string is an optional list of attributes that specify
   3518 whether to use a particular memory region for an input section which is
   3519 not explicitly mapped in the linker script.  As described in *note
   3520 SECTIONS::, if you do not specify an output section for some input
   3521 section, the linker will create an output section with the same name as
   3522 the input section.  If you define region attributes, the linker will use
   3523 them to select the memory region for the output section that it creates.
   3524 
   3525    The ATTR string must consist only of the following characters:
   3526 `R'
   3527      Read-only section
   3528 
   3529 `W'
   3530      Read/write section
   3531 
   3532 `X'
   3533      Executable section
   3534 
   3535 `A'
   3536      Allocatable section
   3537 
   3538 `I'
   3539      Initialized section
   3540 
   3541 `L'
   3542      Same as `I'
   3543 
   3544 `!'
   3545      Invert the sense of any of the preceding attributes
   3546 
   3547    If a unmapped section matches any of the listed attributes other than
   3548 `!', it will be placed in the memory region.  The `!' attribute
   3549 reverses this test, so that an unmapped section will be placed in the
   3550 memory region only if it does not match any of the listed attributes.
   3551 
   3552    The ORIGIN is an numerical expression for the start address of the
   3553 memory region.  The expression must evaluate to a constant and it
   3554 cannot involve any symbols.  The keyword `ORIGIN' may be abbreviated to
   3555 `org' or `o' (but not, for example, `ORG').
   3556 
   3557    The LEN is an expression for the size in bytes of the memory region.
   3558 As with the ORIGIN expression, the expression must be numerical only
   3559 and must evaluate to a constant.  The keyword `LENGTH' may be
   3560 abbreviated to `len' or `l'.
   3561 
   3562    In the following example, we specify that there are two memory
   3563 regions available for allocation: one starting at `0' for 256 kilobytes,
   3564 and the other starting at `0x40000000' for four megabytes.  The linker
   3565 will place into the `rom' memory region every section which is not
   3566 explicitly mapped into a memory region, and is either read-only or
   3567 executable.  The linker will place other sections which are not
   3568 explicitly mapped into a memory region into the `ram' memory region.
   3569 
   3570      MEMORY
   3571        {
   3572          rom (rx)  : ORIGIN = 0, LENGTH = 256K
   3573          ram (!rx) : org = 0x40000000, l = 4M
   3574        }
   3575 
   3576    Once you define a memory region, you can direct the linker to place
   3577 specific output sections into that memory region by using the `>REGION'
   3578 output section attribute.  For example, if you have a memory region
   3579 named `mem', you would use `>mem' in the output section definition.
   3580 *Note Output Section Region::.  If no address was specified for the
   3581 output section, the linker will set the address to the next available
   3582 address within the memory region.  If the combined output sections
   3583 directed to a memory region are too large for the region, the linker
   3584 will issue an error message.
   3585 
   3586    It is possible to access the origin and length of a memory in an
   3587 expression via the `ORIGIN(MEMORY)' and `LENGTH(MEMORY)' functions:
   3588 
   3589        _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
   3590 
   3591 
   3592 File: ld.info,  Node: PHDRS,  Next: VERSION,  Prev: MEMORY,  Up: Scripts
   3593 
   3594 3.8 PHDRS Command
   3595 =================
   3596 
   3597 The ELF object file format uses "program headers", also knows as
   3598 "segments".  The program headers describe how the program should be
   3599 loaded into memory.  You can print them out by using the `objdump'
   3600 program with the `-p' option.
   3601 
   3602    When you run an ELF program on a native ELF system, the system loader
   3603 reads the program headers in order to figure out how to load the
   3604 program.  This will only work if the program headers are set correctly.
   3605 This manual does not describe the details of how the system loader
   3606 interprets program headers; for more information, see the ELF ABI.
   3607 
   3608    The linker will create reasonable program headers by default.
   3609 However, in some cases, you may need to specify the program headers more
   3610 precisely.  You may use the `PHDRS' command for this purpose.  When the
   3611 linker sees the `PHDRS' command in the linker script, it will not
   3612 create any program headers other than the ones specified.
   3613 
   3614    The linker only pays attention to the `PHDRS' command when
   3615 generating an ELF output file.  In other cases, the linker will simply
   3616 ignore `PHDRS'.
   3617 
   3618    This is the syntax of the `PHDRS' command.  The words `PHDRS',
   3619 `FILEHDR', `AT', and `FLAGS' are keywords.
   3620 
   3621      PHDRS
   3622      {
   3623        NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
   3624              [ FLAGS ( FLAGS ) ] ;
   3625      }
   3626 
   3627    The NAME is used only for reference in the `SECTIONS' command of the
   3628 linker script.  It is not put into the output file.  Program header
   3629 names are stored in a separate name space, and will not conflict with
   3630 symbol names, file names, or section names.  Each program header must
   3631 have a distinct name.
   3632 
   3633    Certain program header types describe segments of memory which the
   3634 system loader will load from the file.  In the linker script, you
   3635 specify the contents of these segments by placing allocatable output
   3636 sections in the segments.  You use the `:PHDR' output section attribute
   3637 to place a section in a particular segment.  *Note Output Section
   3638 Phdr::.
   3639 
   3640    It is normal to put certain sections in more than one segment.  This
   3641 merely implies that one segment of memory contains another.  You may
   3642 repeat `:PHDR', using it once for each segment which should contain the
   3643 section.
   3644 
   3645    If you place a section in one or more segments using `:PHDR', then
   3646 the linker will place all subsequent allocatable sections which do not
   3647 specify `:PHDR' in the same segments.  This is for convenience, since
   3648 generally a whole set of contiguous sections will be placed in a single
   3649 segment.  You can use `:NONE' to override the default segment and tell
   3650 the linker to not put the section in any segment at all.
   3651 
   3652    You may use the `FILEHDR' and `PHDRS' keywords appear after the
   3653 program header type to further describe the contents of the segment.
   3654 The `FILEHDR' keyword means that the segment should include the ELF
   3655 file header.  The `PHDRS' keyword means that the segment should include
   3656 the ELF program headers themselves.
   3657 
   3658    The TYPE may be one of the following.  The numbers indicate the
   3659 value of the keyword.
   3660 
   3661 `PT_NULL' (0)
   3662      Indicates an unused program header.
   3663 
   3664 `PT_LOAD' (1)
   3665      Indicates that this program header describes a segment to be
   3666      loaded from the file.
   3667 
   3668 `PT_DYNAMIC' (2)
   3669      Indicates a segment where dynamic linking information can be found.
   3670 
   3671 `PT_INTERP' (3)
   3672      Indicates a segment where the name of the program interpreter may
   3673      be found.
   3674 
   3675 `PT_NOTE' (4)
   3676      Indicates a segment holding note information.
   3677 
   3678 `PT_SHLIB' (5)
   3679      A reserved program header type, defined but not specified by the
   3680      ELF ABI.
   3681 
   3682 `PT_PHDR' (6)
   3683      Indicates a segment where the program headers may be found.
   3684 
   3685 EXPRESSION
   3686      An expression giving the numeric type of the program header.  This
   3687      may be used for types not defined above.
   3688 
   3689    You can specify that a segment should be loaded at a particular
   3690 address in memory by using an `AT' expression.  This is identical to the
   3691 `AT' command used as an output section attribute (*note Output Section
   3692 LMA::).  The `AT' command for a program header overrides the output
   3693 section attribute.
   3694 
   3695    The linker will normally set the segment flags based on the sections
   3696 which comprise the segment.  You may use the `FLAGS' keyword to
   3697 explicitly specify the segment flags.  The value of FLAGS must be an
   3698 integer.  It is used to set the `p_flags' field of the program header.
   3699 
   3700    Here is an example of `PHDRS'.  This shows a typical set of program
   3701 headers used on a native ELF system.
   3702 
   3703      PHDRS
   3704      {
   3705        headers PT_PHDR PHDRS ;
   3706        interp PT_INTERP ;
   3707        text PT_LOAD FILEHDR PHDRS ;
   3708        data PT_LOAD ;
   3709        dynamic PT_DYNAMIC ;
   3710      }
   3711 
   3712      SECTIONS
   3713      {
   3714        . = SIZEOF_HEADERS;
   3715        .interp : { *(.interp) } :text :interp
   3716        .text : { *(.text) } :text
   3717        .rodata : { *(.rodata) } /* defaults to :text */
   3718        ...
   3719        . = . + 0x1000; /* move to a new page in memory */
   3720        .data : { *(.data) } :data
   3721        .dynamic : { *(.dynamic) } :data :dynamic
   3722        ...
   3723      }
   3724 
   3725 
   3726 File: ld.info,  Node: VERSION,  Next: Expressions,  Prev: PHDRS,  Up: Scripts
   3727 
   3728 3.9 VERSION Command
   3729 ===================
   3730 
   3731 The linker supports symbol versions when using ELF.  Symbol versions are
   3732 only useful when using shared libraries.  The dynamic linker can use
   3733 symbol versions to select a specific version of a function when it runs
   3734 a program that may have been linked against an earlier version of the
   3735 shared library.
   3736 
   3737    You can include a version script directly in the main linker script,
   3738 or you can supply the version script as an implicit linker script.  You
   3739 can also use the `--version-script' linker option.
   3740 
   3741    The syntax of the `VERSION' command is simply
   3742      VERSION { version-script-commands }
   3743 
   3744    The format of the version script commands is identical to that used
   3745 by Sun's linker in Solaris 2.5.  The version script defines a tree of
   3746 version nodes.  You specify the node names and interdependencies in the
   3747 version script.  You can specify which symbols are bound to which
   3748 version nodes, and you can reduce a specified set of symbols to local
   3749 scope so that they are not globally visible outside of the shared
   3750 library.
   3751 
   3752    The easiest way to demonstrate the version script language is with a
   3753 few examples.
   3754 
   3755      VERS_1.1 {
   3756      	 global:
   3757      		 foo1;
   3758      	 local:
   3759      		 old*;
   3760      		 original*;
   3761      		 new*;
   3762      };
   3763 
   3764      VERS_1.2 {
   3765      		 foo2;
   3766      } VERS_1.1;
   3767 
   3768      VERS_2.0 {
   3769      		 bar1; bar2;
   3770      	 extern "C++" {
   3771      		 ns::*;
   3772      		 "int f(int, double)";
   3773               }
   3774      } VERS_1.2;
   3775 
   3776    This example version script defines three version nodes.  The first
   3777 version node defined is `VERS_1.1'; it has no other dependencies.  The
   3778 script binds the symbol `foo1' to `VERS_1.1'.  It reduces a number of
   3779 symbols to local scope so that they are not visible outside of the
   3780 shared library; this is done using wildcard patterns, so that any
   3781 symbol whose name begins with `old', `original', or `new' is matched.
   3782 The wildcard patterns available are the same as those used in the shell
   3783 when matching filenames (also known as "globbing").  However, if you
   3784 specify the symbol name inside double quotes, then the name is treated
   3785 as literal, rather than as a glob pattern.
   3786 
   3787    Next, the version script defines node `VERS_1.2'.  This node depends
   3788 upon `VERS_1.1'.  The script binds the symbol `foo2' to the version
   3789 node `VERS_1.2'.
   3790 
   3791    Finally, the version script defines node `VERS_2.0'.  This node
   3792 depends upon `VERS_1.2'.  The scripts binds the symbols `bar1' and
   3793 `bar2' are bound to the version node `VERS_2.0'.
   3794 
   3795    When the linker finds a symbol defined in a library which is not
   3796 specifically bound to a version node, it will effectively bind it to an
   3797 unspecified base version of the library.  You can bind all otherwise
   3798 unspecified symbols to a given version node by using `global: *;'
   3799 somewhere in the version script.
   3800 
   3801    The names of the version nodes have no specific meaning other than
   3802 what they might suggest to the person reading them.  The `2.0' version
   3803 could just as well have appeared in between `1.1' and `1.2'.  However,
   3804 this would be a confusing way to write a version script.
   3805 
   3806    Node name can be omitted, provided it is the only version node in
   3807 the version script.  Such version script doesn't assign any versions to
   3808 symbols, only selects which symbols will be globally visible out and
   3809 which won't.
   3810 
   3811      { global: foo; bar; local: *; };
   3812 
   3813    When you link an application against a shared library that has
   3814 versioned symbols, the application itself knows which version of each
   3815 symbol it requires, and it also knows which version nodes it needs from
   3816 each shared library it is linked against.  Thus at runtime, the dynamic
   3817 loader can make a quick check to make sure that the libraries you have
   3818 linked against do in fact supply all of the version nodes that the
   3819 application will need to resolve all of the dynamic symbols.  In this
   3820 way it is possible for the dynamic linker to know with certainty that
   3821 all external symbols that it needs will be resolvable without having to
   3822 search for each symbol reference.
   3823 
   3824    The symbol versioning is in effect a much more sophisticated way of
   3825 doing minor version checking that SunOS does.  The fundamental problem
   3826 that is being addressed here is that typically references to external
   3827 functions are bound on an as-needed basis, and are not all bound when
   3828 the application starts up.  If a shared library is out of date, a
   3829 required interface may be missing; when the application tries to use
   3830 that interface, it may suddenly and unexpectedly fail.  With symbol
   3831 versioning, the user will get a warning when they start their program if
   3832 the libraries being used with the application are too old.
   3833 
   3834    There are several GNU extensions to Sun's versioning approach.  The
   3835 first of these is the ability to bind a symbol to a version node in the
   3836 source file where the symbol is defined instead of in the versioning
   3837 script.  This was done mainly to reduce the burden on the library
   3838 maintainer.  You can do this by putting something like:
   3839      __asm__(".symver original_foo,foo (a] VERS_1.1");
   3840    in the C source file.  This renames the function `original_foo' to
   3841 be an alias for `foo' bound to the version node `VERS_1.1'.  The
   3842 `local:' directive can be used to prevent the symbol `original_foo'
   3843 from being exported. A `.symver' directive takes precedence over a
   3844 version script.
   3845 
   3846    The second GNU extension is to allow multiple versions of the same
   3847 function to appear in a given shared library.  In this way you can make
   3848 an incompatible change to an interface without increasing the major
   3849 version number of the shared library, while still allowing applications
   3850 linked against the old interface to continue to function.
   3851 
   3852    To do this, you must use multiple `.symver' directives in the source
   3853 file.  Here is an example:
   3854 
   3855      __asm__(".symver original_foo,foo@");
   3856      __asm__(".symver old_foo,foo (a] VERS_1.1");
   3857      __asm__(".symver old_foo1,foo (a] VERS_1.2");
   3858      __asm__(".symver new_foo,foo@@VERS_2.0");
   3859 
   3860    In this example, `foo@' represents the symbol `foo' bound to the
   3861 unspecified base version of the symbol.  The source file that contains
   3862 this example would define 4 C functions: `original_foo', `old_foo',
   3863 `old_foo1', and `new_foo'.
   3864 
   3865    When you have multiple definitions of a given symbol, there needs to
   3866 be some way to specify a default version to which external references to
   3867 this symbol will be bound.  You can do this with the `foo@@VERS_2.0'
   3868 type of `.symver' directive.  You can only declare one version of a
   3869 symbol as the default in this manner; otherwise you would effectively
   3870 have multiple definitions of the same symbol.
   3871 
   3872    If you wish to bind a reference to a specific version of the symbol
   3873 within the shared library, you can use the aliases of convenience
   3874 (i.e., `old_foo'), or you can use the `.symver' directive to
   3875 specifically bind to an external version of the function in question.
   3876 
   3877    You can also specify the language in the version script:
   3878 
   3879      VERSION extern "lang" { version-script-commands }
   3880 
   3881    The supported `lang's are `C', `C++', and `Java'.  The linker will
   3882 iterate over the list of symbols at the link time and demangle them
   3883 according to `lang' before matching them to the patterns specified in
   3884 `version-script-commands'.
   3885 
   3886    Demangled names may contains spaces and other special characters.  As
   3887 described above, you can use a glob pattern to match demangled names,
   3888 or you can use a double-quoted string to match the string exactly.  In
   3889 the latter case, be aware that minor differences (such as differing
   3890 whitespace) between the version script and the demangler output will
   3891 cause a mismatch.  As the exact string generated by the demangler might
   3892 change in the future, even if the mangled name does not, you should
   3893 check that all of your version directives are behaving as you expect
   3894 when you upgrade.
   3895 
   3896 
   3897 File: ld.info,  Node: Expressions,  Next: Implicit Linker Scripts,  Prev: VERSION,  Up: Scripts
   3898 
   3899 3.10 Expressions in Linker Scripts
   3900 ==================================
   3901 
   3902 The syntax for expressions in the linker script language is identical to
   3903 that of C expressions.  All expressions are evaluated as integers.  All
   3904 expressions are evaluated in the same size, which is 32 bits if both the
   3905 host and target are 32 bits, and is otherwise 64 bits.
   3906 
   3907    You can use and set symbol values in expressions.
   3908 
   3909    The linker defines several special purpose builtin functions for use
   3910 in expressions.
   3911 
   3912 * Menu:
   3913 
   3914 * Constants::			Constants
   3915 * Symbols::			Symbol Names
   3916 * Orphan Sections::		Orphan Sections
   3917 * Location Counter::		The Location Counter
   3918 * Operators::			Operators
   3919 * Evaluation::			Evaluation
   3920 * Expression Section::		The Section of an Expression
   3921 * Builtin Functions::		Builtin Functions
   3922 
   3923 
   3924 File: ld.info,  Node: Constants,  Next: Symbols,  Up: Expressions
   3925 
   3926 3.10.1 Constants
   3927 ----------------
   3928 
   3929 All constants are integers.
   3930 
   3931    As in C, the linker considers an integer beginning with `0' to be
   3932 octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
   3933 The linker considers other integers to be decimal.
   3934 
   3935    In addition, you can use the suffixes `K' and `M' to scale a
   3936 constant by `1024' or `1024*1024' respectively. For example, the
   3937 following all refer to the same quantity:
   3938      _fourk_1 = 4K;
   3939      _fourk_2 = 4096;
   3940      _fourk_3 = 0x1000;
   3941 
   3942 
   3943 File: ld.info,  Node: Symbols,  Next: Orphan Sections,  Prev: Constants,  Up: Expressions
   3944 
   3945 3.10.2 Symbol Names
   3946 -------------------
   3947 
   3948 Unless quoted, symbol names start with a letter, underscore, or period
   3949 and may include letters, digits, underscores, periods, and hyphens.
   3950 Unquoted symbol names must not conflict with any keywords.  You can
   3951 specify a symbol which contains odd characters or has the same name as a
   3952 keyword by surrounding the symbol name in double quotes:
   3953      "SECTION" = 9;
   3954      "with a space" = "also with a space" + 10;
   3955 
   3956    Since symbols can contain many non-alphabetic characters, it is
   3957 safest to delimit symbols with spaces.  For example, `A-B' is one
   3958 symbol, whereas `A - B' is an expression involving subtraction.
   3959 
   3960 
   3961 File: ld.info,  Node: Orphan Sections,  Next: Location Counter,  Prev: Symbols,  Up: Expressions
   3962 
   3963 3.10.3 Orphan Sections
   3964 ----------------------
   3965 
   3966 Orphan sections are sections present in the input files which are not
   3967 explicitly placed into the output file by the linker script.  The
   3968 linker will still copy these sections into the output file, but it has
   3969 to guess as to where they should be placed.  The linker uses a simple
   3970 heuristic to do this.  It attempts to place orphan sections after
   3971 non-orphan sections of the same attribute, such as code vs data,
   3972 loadable vs non-loadable, etc.  If there is not enough room to do this
   3973 then it places at the end of the file.
   3974 
   3975    For ELF targets, the attribute of the section includes section type
   3976 as well as section flag.
   3977 
   3978    If an orphaned section's name is representable as a C identifier then
   3979 the linker will automatically *note PROVIDE:: two symbols:
   3980 __start_SECNAME and __end_SECNAME, where SECNAME is the name of the
   3981 section.  These indicate the start address and end address of the
   3982 orphaned section respectively.  Note: most section names are not
   3983 representable as C identifiers because they contain a `.' character.
   3984 
   3985 
   3986 File: ld.info,  Node: Location Counter,  Next: Operators,  Prev: Orphan Sections,  Up: Expressions
   3987 
   3988 3.10.4 The Location Counter
   3989 ---------------------------
   3990 
   3991 The special linker variable "dot" `.' always contains the current
   3992 output location counter.  Since the `.' always refers to a location in
   3993 an output section, it may only appear in an expression within a
   3994 `SECTIONS' command.  The `.' symbol may appear anywhere that an
   3995 ordinary symbol is allowed in an expression.
   3996 
   3997    Assigning a value to `.' will cause the location counter to be
   3998 moved.  This may be used to create holes in the output section.  The
   3999 location counter may not be moved backwards inside an output section,
   4000 and may not be moved backwards outside of an output section if so doing
   4001 creates areas with overlapping LMAs.
   4002 
   4003      SECTIONS
   4004      {
   4005        output :
   4006          {
   4007            file1(.text)
   4008            . = . + 1000;
   4009            file2(.text)
   4010            . += 1000;
   4011            file3(.text)
   4012          } = 0x12345678;
   4013      }
   4014    In the previous example, the `.text' section from `file1' is located
   4015 at the beginning of the output section `output'.  It is followed by a
   4016 1000 byte gap.  Then the `.text' section from `file2' appears, also
   4017 with a 1000 byte gap following before the `.text' section from `file3'.
   4018 The notation `= 0x12345678' specifies what data to write in the gaps
   4019 (*note Output Section Fill::).
   4020 
   4021    Note: `.' actually refers to the byte offset from the start of the
   4022 current containing object.  Normally this is the `SECTIONS' statement,
   4023 whose start address is 0, hence `.' can be used as an absolute address.
   4024 If `.' is used inside a section description however, it refers to the
   4025 byte offset from the start of that section, not an absolute address.
   4026 Thus in a script like this:
   4027 
   4028      SECTIONS
   4029      {
   4030          . = 0x100
   4031          .text: {
   4032            *(.text)
   4033            . = 0x200
   4034          }
   4035          . = 0x500
   4036          .data: {
   4037            *(.data)
   4038            . += 0x600
   4039          }
   4040      }
   4041 
   4042    The `.text' section will be assigned a starting address of 0x100 and
   4043 a size of exactly 0x200 bytes, even if there is not enough data in the
   4044 `.text' input sections to fill this area.  (If there is too much data,
   4045 an error will be produced because this would be an attempt to move `.'
   4046 backwards).  The `.data' section will start at 0x500 and it will have
   4047 an extra 0x600 bytes worth of space after the end of the values from
   4048 the `.data' input sections and before the end of the `.data' output
   4049 section itself.
   4050 
   4051    Setting symbols to the value of the location counter outside of an
   4052 output section statement can result in unexpected values if the linker
   4053 needs to place orphan sections.  For example, given the following:
   4054 
   4055      SECTIONS
   4056      {
   4057          start_of_text = . ;
   4058          .text: { *(.text) }
   4059          end_of_text = . ;
   4060 
   4061          start_of_data = . ;
   4062          .data: { *(.data) }
   4063          end_of_data = . ;
   4064      }
   4065 
   4066    If the linker needs to place some input section, e.g. `.rodata', not
   4067 mentioned in the script, it might choose to place that section between
   4068 `.text' and `.data'.  You might think the linker should place `.rodata'
   4069 on the blank line in the above script, but blank lines are of no
   4070 particular significance to the linker.  As well, the linker doesn't
   4071 associate the above symbol names with their sections.  Instead, it
   4072 assumes that all assignments or other statements belong to the previous
   4073 output section, except for the special case of an assignment to `.'.
   4074 I.e., the linker will place the orphan `.rodata' section as if the
   4075 script was written as follows:
   4076 
   4077      SECTIONS
   4078      {
   4079          start_of_text = . ;
   4080          .text: { *(.text) }
   4081          end_of_text = . ;
   4082 
   4083          start_of_data = . ;
   4084          .rodata: { *(.rodata) }
   4085          .data: { *(.data) }
   4086          end_of_data = . ;
   4087      }
   4088 
   4089    This may or may not be the script author's intention for the value of
   4090 `start_of_data'.  One way to influence the orphan section placement is
   4091 to assign the location counter to itself, as the linker assumes that an
   4092 assignment to `.' is setting the start address of a following output
   4093 section and thus should be grouped with that section.  So you could
   4094 write:
   4095 
   4096      SECTIONS
   4097      {
   4098          start_of_text = . ;
   4099          .text: { *(.text) }
   4100          end_of_text = . ;
   4101 
   4102          . = . ;
   4103          start_of_data = . ;
   4104          .data: { *(.data) }
   4105          end_of_data = . ;
   4106      }
   4107 
   4108    Now, the orphan `.rodata' section will be placed between
   4109 `end_of_text' and `start_of_data'.
   4110 
   4111 
   4112 File: ld.info,  Node: Operators,  Next: Evaluation,  Prev: Location Counter,  Up: Expressions
   4113 
   4114 3.10.5 Operators
   4115 ----------------
   4116 
   4117 The linker recognizes the standard C set of arithmetic operators, with
   4118 the standard bindings and precedence levels:
   4119      precedence      associativity   Operators                Notes
   4120      (highest)
   4121      1               left            !  -  ~                  (1)
   4122      2               left            *  /  %
   4123      3               left            +  -
   4124      4               left            >>  <<
   4125      5               left            ==  !=  >  <  <=  >=
   4126      6               left            &
   4127      7               left            |
   4128      8               left            &&
   4129      9               left            ||
   4130      10              right           ? :
   4131      11              right           &=  +=  -=  *=  /=       (2)
   4132      (lowest)
   4133    Notes: (1) Prefix operators (2) *Note Assignments::.
   4134 
   4135 
   4136 File: ld.info,  Node: Evaluation,  Next: Expression Section,  Prev: Operators,  Up: Expressions
   4137 
   4138 3.10.6 Evaluation
   4139 -----------------
   4140 
   4141 The linker evaluates expressions lazily.  It only computes the value of
   4142 an expression when absolutely necessary.
   4143 
   4144    The linker needs some information, such as the value of the start
   4145 address of the first section, and the origins and lengths of memory
   4146 regions, in order to do any linking at all.  These values are computed
   4147 as soon as possible when the linker reads in the linker script.
   4148 
   4149    However, other values (such as symbol values) are not known or needed
   4150 until after storage allocation.  Such values are evaluated later, when
   4151 other information (such as the sizes of output sections) is available
   4152 for use in the symbol assignment expression.
   4153 
   4154    The sizes of sections cannot be known until after allocation, so
   4155 assignments dependent upon these are not performed until after
   4156 allocation.
   4157 
   4158    Some expressions, such as those depending upon the location counter
   4159 `.', must be evaluated during section allocation.
   4160 
   4161    If the result of an expression is required, but the value is not
   4162 available, then an error results.  For example, a script like the
   4163 following
   4164      SECTIONS
   4165        {
   4166          .text 9+this_isnt_constant :
   4167            { *(.text) }
   4168        }
   4169 will cause the error message `non constant expression for initial
   4170 address'.
   4171 
   4172 
   4173 File: ld.info,  Node: Expression Section,  Next: Builtin Functions,  Prev: Evaluation,  Up: Expressions
   4174 
   4175 3.10.7 The Section of an Expression
   4176 -----------------------------------
   4177 
   4178 When the linker evaluates an expression, the result is either absolute
   4179 or relative to some section.  A relative expression is expressed as a
   4180 fixed offset from the base of a section.
   4181 
   4182    The position of the expression within the linker script determines
   4183 whether it is absolute or relative.  An expression which appears within
   4184 an output section definition is relative to the base of the output
   4185 section.  An expression which appears elsewhere will be absolute.
   4186 
   4187    A symbol set to a relative expression will be relocatable if you
   4188 request relocatable output using the `-r' option.  That means that a
   4189 further link operation may change the value of the symbol.  The symbol's
   4190 section will be the section of the relative expression.
   4191 
   4192    A symbol set to an absolute expression will retain the same value
   4193 through any further link operation.  The symbol will be absolute, and
   4194 will not have any particular associated section.
   4195 
   4196    You can use the builtin function `ABSOLUTE' to force an expression
   4197 to be absolute when it would otherwise be relative.  For example, to
   4198 create an absolute symbol set to the address of the end of the output
   4199 section `.data':
   4200      SECTIONS
   4201        {
   4202          .data : { *(.data) _edata = ABSOLUTE(.); }
   4203        }
   4204    If `ABSOLUTE' were not used, `_edata' would be relative to the
   4205 `.data' section.
   4206 
   4207 
   4208 File: ld.info,  Node: Builtin Functions,  Prev: Expression Section,  Up: Expressions
   4209 
   4210 3.10.8 Builtin Functions
   4211 ------------------------
   4212 
   4213 The linker script language includes a number of builtin functions for
   4214 use in linker script expressions.
   4215 
   4216 `ABSOLUTE(EXP)'
   4217      Return the absolute (non-relocatable, as opposed to non-negative)
   4218      value of the expression EXP.  Primarily useful to assign an
   4219      absolute value to a symbol within a section definition, where
   4220      symbol values are normally section relative.  *Note Expression
   4221      Section::.
   4222 
   4223 `ADDR(SECTION)'
   4224      Return the absolute address (the VMA) of the named SECTION.  Your
   4225      script must previously have defined the location of that section.
   4226      In the following example, `symbol_1' and `symbol_2' are assigned
   4227      identical values:
   4228           SECTIONS { ...
   4229             .output1 :
   4230               {
   4231               start_of_output_1 = ABSOLUTE(.);
   4232               ...
   4233               }
   4234             .output :
   4235               {
   4236               symbol_1 = ADDR(.output1);
   4237               symbol_2 = start_of_output_1;
   4238               }
   4239           ... }
   4240 
   4241 `ALIGN(ALIGN)'
   4242 `ALIGN(EXP,ALIGN)'
   4243      Return the location counter (`.') or arbitrary expression aligned
   4244      to the next ALIGN boundary.  The single operand `ALIGN' doesn't
   4245      change the value of the location counter--it just does arithmetic
   4246      on it.  The two operand `ALIGN' allows an arbitrary expression to
   4247      be aligned upwards (`ALIGN(ALIGN)' is equivalent to `ALIGN(.,
   4248      ALIGN)').
   4249 
   4250      Here is an example which aligns the output `.data' section to the
   4251      next `0x2000' byte boundary after the preceding section and sets a
   4252      variable within the section to the next `0x8000' boundary after the
   4253      input sections:
   4254           SECTIONS { ...
   4255             .data ALIGN(0x2000): {
   4256               *(.data)
   4257               variable = ALIGN(0x8000);
   4258             }
   4259           ... }
   4260      The first use of `ALIGN' in this example specifies the location of
   4261      a section because it is used as the optional ADDRESS attribute of
   4262      a section definition (*note Output Section Address::).  The second
   4263      use of `ALIGN' is used to defines the value of a symbol.
   4264 
   4265      The builtin function `NEXT' is closely related to `ALIGN'.
   4266 
   4267 `ALIGNOF(SECTION)'
   4268      Return the alignment in bytes of the named SECTION, if that
   4269      section has been allocated.  If the section has not been allocated
   4270      when this is evaluated, the linker will report an error. In the
   4271      following example, the alignment of the `.output' section is
   4272      stored as the first value in that section.
   4273           SECTIONS{ ...
   4274             .output {
   4275               LONG (ALIGNOF (.output))
   4276               ...
   4277               }
   4278           ... }
   4279 
   4280 `BLOCK(EXP)'
   4281      This is a synonym for `ALIGN', for compatibility with older linker
   4282      scripts.  It is most often seen when setting the address of an
   4283      output section.
   4284 
   4285 `DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)'
   4286      This is equivalent to either
   4287           (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1)))
   4288      or
   4289           (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE)))
   4290      depending on whether the latter uses fewer COMMONPAGESIZE sized
   4291      pages for the data segment (area between the result of this
   4292      expression and `DATA_SEGMENT_END') than the former or not.  If the
   4293      latter form is used, it means COMMONPAGESIZE bytes of runtime
   4294      memory will be saved at the expense of up to COMMONPAGESIZE wasted
   4295      bytes in the on-disk file.
   4296 
   4297      This expression can only be used directly in `SECTIONS' commands,
   4298      not in any output section descriptions and only once in the linker
   4299      script.  COMMONPAGESIZE should be less or equal to MAXPAGESIZE and
   4300      should be the system page size the object wants to be optimized
   4301      for (while still working on system page sizes up to MAXPAGESIZE).
   4302 
   4303      Example:
   4304             . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
   4305 
   4306 `DATA_SEGMENT_END(EXP)'
   4307      This defines the end of data segment for `DATA_SEGMENT_ALIGN'
   4308      evaluation purposes.
   4309 
   4310             . = DATA_SEGMENT_END(.);
   4311 
   4312 `DATA_SEGMENT_RELRO_END(OFFSET, EXP)'
   4313      This defines the end of the `PT_GNU_RELRO' segment when `-z relro'
   4314      option is used.  Second argument is returned.  When `-z relro'
   4315      option is not present, `DATA_SEGMENT_RELRO_END' does nothing,
   4316      otherwise `DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is
   4317      aligned to the most commonly used page boundary for particular
   4318      target.  If present in the linker script, it must always come in
   4319      between `DATA_SEGMENT_ALIGN' and `DATA_SEGMENT_END'.
   4320 
   4321             . = DATA_SEGMENT_RELRO_END(24, .);
   4322 
   4323 `DEFINED(SYMBOL)'
   4324      Return 1 if SYMBOL is in the linker global symbol table and is
   4325      defined before the statement using DEFINED in the script, otherwise
   4326      return 0.  You can use this function to provide default values for
   4327      symbols.  For example, the following script fragment shows how to
   4328      set a global symbol `begin' to the first location in the `.text'
   4329      section--but if a symbol called `begin' already existed, its value
   4330      is preserved:
   4331 
   4332           SECTIONS { ...
   4333             .text : {
   4334               begin = DEFINED(begin) ? begin : . ;
   4335               ...
   4336             }
   4337             ...
   4338           }
   4339 
   4340 `LENGTH(MEMORY)'
   4341      Return the length of the memory region named MEMORY.
   4342 
   4343 `LOADADDR(SECTION)'
   4344      Return the absolute LMA of the named SECTION.  This is normally
   4345      the same as `ADDR', but it may be different if the `AT' attribute
   4346      is used in the output section definition (*note Output Section
   4347      LMA::).
   4348 
   4349 `MAX(EXP1, EXP2)'
   4350      Returns the maximum of EXP1 and EXP2.
   4351 
   4352 `MIN(EXP1, EXP2)'
   4353      Returns the minimum of EXP1 and EXP2.
   4354 
   4355 `NEXT(EXP)'
   4356      Return the next unallocated address that is a multiple of EXP.
   4357      This function is closely related to `ALIGN(EXP)'; unless you use
   4358      the `MEMORY' command to define discontinuous memory for the output
   4359      file, the two functions are equivalent.
   4360 
   4361 `ORIGIN(MEMORY)'
   4362      Return the origin of the memory region named MEMORY.
   4363 
   4364 `SEGMENT_START(SEGMENT, DEFAULT)'
   4365      Return the base address of the named SEGMENT.  If an explicit
   4366      value has been given for this segment (with a command-line `-T'
   4367      option) that value will be returned; otherwise the value will be
   4368      DEFAULT.  At present, the `-T' command-line option can only be
   4369      used to set the base address for the "text", "data", and "bss"
   4370      sections, but you use `SEGMENT_START' with any segment name.
   4371 
   4372 `SIZEOF(SECTION)'
   4373      Return the size in bytes of the named SECTION, if that section has
   4374      been allocated.  If the section has not been allocated when this is
   4375      evaluated, the linker will report an error.  In the following
   4376      example, `symbol_1' and `symbol_2' are assigned identical values:
   4377           SECTIONS{ ...
   4378             .output {
   4379               .start = . ;
   4380               ...
   4381               .end = . ;
   4382               }
   4383             symbol_1 = .end - .start ;
   4384             symbol_2 = SIZEOF(.output);
   4385           ... }
   4386 
   4387 `SIZEOF_HEADERS'
   4388 `sizeof_headers'
   4389      Return the size in bytes of the output file's headers.  This is
   4390      information which appears at the start of the output file.  You
   4391      can use this number when setting the start address of the first
   4392      section, if you choose, to facilitate paging.
   4393 
   4394      When producing an ELF output file, if the linker script uses the
   4395      `SIZEOF_HEADERS' builtin function, the linker must compute the
   4396      number of program headers before it has determined all the section
   4397      addresses and sizes.  If the linker later discovers that it needs
   4398      additional program headers, it will report an error `not enough
   4399      room for program headers'.  To avoid this error, you must avoid
   4400      using the `SIZEOF_HEADERS' function, or you must rework your linker
   4401      script to avoid forcing the linker to use additional program
   4402      headers, or you must define the program headers yourself using the
   4403      `PHDRS' command (*note PHDRS::).
   4404 
   4405 
   4406 File: ld.info,  Node: Implicit Linker Scripts,  Prev: Expressions,  Up: Scripts
   4407 
   4408 3.11 Implicit Linker Scripts
   4409 ============================
   4410 
   4411 If you specify a linker input file which the linker can not recognize as
   4412 an object file or an archive file, it will try to read the file as a
   4413 linker script.  If the file can not be parsed as a linker script, the
   4414 linker will report an error.
   4415 
   4416    An implicit linker script will not replace the default linker script.
   4417 
   4418    Typically an implicit linker script would contain only symbol
   4419 assignments, or the `INPUT', `GROUP', or `VERSION' commands.
   4420 
   4421    Any input files read because of an implicit linker script will be
   4422 read at the position in the command line where the implicit linker
   4423 script was read.  This can affect archive searching.
   4424 
   4425 
   4426 File: ld.info,  Node: Machine Dependent,  Next: BFD,  Prev: Scripts,  Up: Top
   4427 
   4428 4 Machine Dependent Features
   4429 ****************************
   4430 
   4431 `ld' has additional features on some platforms; the following sections
   4432 describe them.  Machines where `ld' has no additional functionality are
   4433 not listed.
   4434 
   4435 * Menu:
   4436 
   4437 
   4438 * H8/300::                      `ld' and the H8/300
   4439 
   4440 * i960::                        `ld' and the Intel 960 family
   4441 
   4442 * ARM::				`ld' and the ARM family
   4443 
   4444 * HPPA ELF32::                  `ld' and HPPA 32-bit ELF
   4445 
   4446 * M68K::			`ld' and the Motorola 68K family
   4447 
   4448 * MMIX::			`ld' and MMIX
   4449 
   4450 * MSP430::			`ld' and MSP430
   4451 
   4452 * M68HC11/68HC12::		`ld' and the Motorola 68HC11 and 68HC12 families
   4453 
   4454 * PowerPC ELF32::		`ld' and PowerPC 32-bit ELF Support
   4455 
   4456 * PowerPC64 ELF64::		`ld' and PowerPC64 64-bit ELF Support
   4457 
   4458 * SPU ELF::			`ld' and SPU ELF Support
   4459 
   4460 * TI COFF::                     `ld' and TI COFF
   4461 
   4462 * WIN32::                       `ld' and WIN32 (cygwin/mingw)
   4463 
   4464 * Xtensa::                      `ld' and Xtensa Processors
   4465 
   4466 
   4467 File: ld.info,  Node: H8/300,  Next: i960,  Up: Machine Dependent
   4468 
   4469 4.1 `ld' and the H8/300
   4470 =======================
   4471 
   4472 For the H8/300, `ld' can perform these global optimizations when you
   4473 specify the `--relax' command-line option.
   4474 
   4475 _relaxing address modes_
   4476      `ld' finds all `jsr' and `jmp' instructions whose targets are
   4477      within eight bits, and turns them into eight-bit program-counter
   4478      relative `bsr' and `bra' instructions, respectively.
   4479 
   4480 _synthesizing instructions_
   4481      `ld' finds all `mov.b' instructions which use the sixteen-bit
   4482      absolute address form, but refer to the top page of memory, and
   4483      changes them to use the eight-bit address form.  (That is: the
   4484      linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
   4485      address AA is in the top page of memory).
   4486 
   4487 _bit manipulation instructions_
   4488      `ld' finds all bit manipulation instructions like `band, bclr,
   4489      biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst,
   4490      bxor' which use 32 bit and 16 bit absolute address form, but refer
   4491      to the top page of memory, and changes them to use the 8 bit
   4492      address form.  (That is: the linker turns `bset #xx:3,`@'AA:32'
   4493      into `bset #xx:3,`@'AA:8' whenever the address AA is in the top
   4494      page of memory).
   4495 
   4496 _system control instructions_
   4497      `ld' finds all `ldc.w, stc.w' instructions which use the 32 bit
   4498      absolute address form, but refer to the top page of memory, and
   4499      changes them to use 16 bit address form.  (That is: the linker
   4500      turns `ldc.w `@'AA:32,ccr' into `ldc.w `@'AA:16,ccr' whenever the
   4501      address AA is in the top page of memory).
   4502 
   4503 
   4504 File: ld.info,  Node: i960,  Next: ARM,  Prev: H8/300,  Up: Machine Dependent
   4505 
   4506 4.2 `ld' and the Intel 960 Family
   4507 =================================
   4508 
   4509 You can use the `-AARCHITECTURE' command line option to specify one of
   4510 the two-letter names identifying members of the 960 family; the option
   4511 specifies the desired output target, and warns of any incompatible
   4512 instructions in the input files.  It also modifies the linker's search
   4513 strategy for archive libraries, to support the use of libraries
   4514 specific to each particular architecture, by including in the search
   4515 loop names suffixed with the string identifying the architecture.
   4516 
   4517    For example, if your `ld' command line included `-ACA' as well as
   4518 `-ltry', the linker would look (in its built-in search paths, and in
   4519 any paths you specify with `-L') for a library with the names
   4520 
   4521      try
   4522      libtry.a
   4523      tryca
   4524      libtryca.a
   4525 
   4526 The first two possibilities would be considered in any event; the last
   4527 two are due to the use of `-ACA'.
   4528 
   4529    You can meaningfully use `-A' more than once on a command line, since
   4530 the 960 architecture family allows combination of target architectures;
   4531 each use will add another pair of name variants to search for when `-l'
   4532 specifies a library.
   4533 
   4534    `ld' supports the `--relax' option for the i960 family.  If you
   4535 specify `--relax', `ld' finds all `balx' and `calx' instructions whose
   4536 targets are within 24 bits, and turns them into 24-bit program-counter
   4537 relative `bal' and `cal' instructions, respectively.  `ld' also turns
   4538 `cal' instructions into `bal' instructions when it determines that the
   4539 target subroutine is a leaf routine (that is, the target subroutine does
   4540 not itself call any subroutines).
   4541 
   4542    The `--fix-cortex-a8' switch enables a link-time workaround for an
   4543 erratum in certain Cortex-A8 processors.  The workaround is enabled by
   4544 default if you are targeting the ARM v7-A architecture profile.  It can
   4545 be enabled otherwise by specifying `--fix-cortex-a8', or disabled
   4546 unconditionally by specifying `--no-fix-cortex-a8'.
   4547 
   4548    The erratum only affects Thumb-2 code.  Please contact ARM for
   4549 further details.
   4550 
   4551 
   4552 File: ld.info,  Node: M68HC11/68HC12,  Next: PowerPC ELF32,  Prev: MSP430,  Up: Machine Dependent
   4553 
   4554 4.3 `ld' and the Motorola 68HC11 and 68HC12 families
   4555 ====================================================
   4556 
   4557 4.3.1 Linker Relaxation
   4558 -----------------------
   4559 
   4560 For the Motorola 68HC11, `ld' can perform these global optimizations
   4561 when you specify the `--relax' command-line option.
   4562 
   4563 _relaxing address modes_
   4564      `ld' finds all `jsr' and `jmp' instructions whose targets are
   4565      within eight bits, and turns them into eight-bit program-counter
   4566      relative `bsr' and `bra' instructions, respectively.
   4567 
   4568      `ld' also looks at all 16-bit extended addressing modes and
   4569      transforms them in a direct addressing mode when the address is in
   4570      page 0 (between 0 and 0x0ff).
   4571 
   4572 _relaxing gcc instruction group_
   4573      When `gcc' is called with `-mrelax', it can emit group of
   4574      instructions that the linker can optimize to use a 68HC11 direct
   4575      addressing mode. These instructions consists of `bclr' or `bset'
   4576      instructions.
   4577 
   4578 
   4579 4.3.2 Trampoline Generation
   4580 ---------------------------
   4581 
   4582 For 68HC11 and 68HC12, `ld' can generate trampoline code to call a far
   4583 function using a normal `jsr' instruction. The linker will also change
   4584 the relocation to some far function to use the trampoline address
   4585 instead of the function address. This is typically the case when a
   4586 pointer to a function is taken. The pointer will in fact point to the
   4587 function trampoline.
   4588 
   4589 
   4590 File: ld.info,  Node: ARM,  Next: HPPA ELF32,  Prev: i960,  Up: Machine Dependent
   4591 
   4592 4.4 `ld' and the ARM family
   4593 ===========================
   4594 
   4595 For the ARM, `ld' will generate code stubs to allow functions calls
   4596 between ARM and Thumb code.  These stubs only work with code that has
   4597 been compiled and assembled with the `-mthumb-interwork' command line
   4598 option.  If it is necessary to link with old ARM object files or
   4599 libraries, which have not been compiled with the -mthumb-interwork
   4600 option then the `--support-old-code' command line switch should be
   4601 given to the linker.  This will make it generate larger stub functions
   4602 which will work with non-interworking aware ARM code.  Note, however,
   4603 the linker does not support generating stubs for function calls to
   4604 non-interworking aware Thumb code.
   4605 
   4606    The `--thumb-entry' switch is a duplicate of the generic `--entry'
   4607 switch, in that it sets the program's starting address.  But it also
   4608 sets the bottom bit of the address, so that it can be branched to using
   4609 a BX instruction, and the program will start executing in Thumb mode
   4610 straight away.
   4611 
   4612    The `--be8' switch instructs `ld' to generate BE8 format
   4613 executables.  This option is only valid when linking big-endian objects.
   4614 The resulting image will contain big-endian data and little-endian code.
   4615 
   4616    The `R_ARM_TARGET1' relocation is typically used for entries in the
   4617 `.init_array' section.  It is interpreted as either `R_ARM_REL32' or
   4618 `R_ARM_ABS32', depending on the target.  The `--target1-rel' and
   4619 `--target1-abs' switches override the default.
   4620 
   4621    The `--target2=type' switch overrides the default definition of the
   4622 `R_ARM_TARGET2' relocation.  Valid values for `type', their meanings,
   4623 and target defaults are as follows:
   4624 `rel'
   4625      `R_ARM_REL32' (arm*-*-elf, arm*-*-eabi)
   4626 
   4627 `abs'
   4628      `R_ARM_ABS32' (arm*-*-symbianelf)
   4629 
   4630 `got-rel'
   4631      `R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd)
   4632 
   4633    The `R_ARM_V4BX' relocation (defined by the ARM AAELF specification)
   4634 enables objects compiled for the ARMv4 architecture to be
   4635 interworking-safe when linked with other objects compiled for ARMv4t,
   4636 but also allows pure ARMv4 binaries to be built from the same ARMv4
   4637 objects.
   4638 
   4639    In the latter case, the switch `--fix-v4bx' must be passed to the
   4640 linker, which causes v4t `BX rM' instructions to be rewritten as `MOV
   4641 PC,rM', since v4 processors do not have a `BX' instruction.
   4642 
   4643    In the former case, the switch should not be used, and `R_ARM_V4BX'
   4644 relocations are ignored.
   4645 
   4646    Replace `BX rM' instructions identified by `R_ARM_V4BX' relocations
   4647 with a branch to the following veneer:
   4648 
   4649      TST rM, #1
   4650      MOVEQ PC, rM
   4651      BX Rn
   4652 
   4653    This allows generation of libraries/applications that work on ARMv4
   4654 cores and are still interworking safe.  Note that the above veneer
   4655 clobbers the condition flags, so may cause incorrect progrm behavior in
   4656 rare cases.
   4657 
   4658    The `--use-blx' switch enables the linker to use ARM/Thumb BLX
   4659 instructions (available on ARMv5t and above) in various situations.
   4660 Currently it is used to perform calls via the PLT from Thumb code using
   4661 BLX rather than using BX and a mode-switching stub before each PLT
   4662 entry. This should lead to such calls executing slightly faster.
   4663 
   4664    This option is enabled implicitly for SymbianOS, so there is no need
   4665 to specify it if you are using that target.
   4666 
   4667    The `--vfp11-denorm-fix' switch enables a link-time workaround for a
   4668 bug in certain VFP11 coprocessor hardware, which sometimes allows
   4669 instructions with denorm operands (which must be handled by support
   4670 code) to have those operands overwritten by subsequent instructions
   4671 before the support code can read the intended values.
   4672 
   4673    The bug may be avoided in scalar mode if you allow at least one
   4674 intervening instruction between a VFP11 instruction which uses a
   4675 register and another instruction which writes to the same register, or
   4676 at least two intervening instructions if vector mode is in use. The bug
   4677 only affects full-compliance floating-point mode: you do not need this
   4678 workaround if you are using "runfast" mode. Please contact ARM for
   4679 further details.
   4680 
   4681    If you know you are using buggy VFP11 hardware, you can enable this
   4682 workaround by specifying the linker option `--vfp-denorm-fix=scalar' if
   4683 you are using the VFP11 scalar mode only, or `--vfp-denorm-fix=vector'
   4684 if you are using vector mode (the latter also works for scalar code).
   4685 The default is `--vfp-denorm-fix=none'.
   4686 
   4687    If the workaround is enabled, instructions are scanned for
   4688 potentially-troublesome sequences, and a veneer is created for each
   4689 such sequence which may trigger the erratum. The veneer consists of the
   4690 first instruction of the sequence and a branch back to the subsequent
   4691 instruction. The original instruction is then replaced with a branch to
   4692 the veneer. The extra cycles required to call and return from the veneer
   4693 are sufficient to avoid the erratum in both the scalar and vector cases.
   4694 
   4695    The `--no-enum-size-warning' switch prevents the linker from warning
   4696 when linking object files that specify incompatible EABI enumeration
   4697 size attributes.  For example, with this switch enabled, linking of an
   4698 object file using 32-bit enumeration values with another using
   4699 enumeration values fitted into the smallest possible space will not be
   4700 diagnosed.
   4701 
   4702    The `--no-wchar-size-warning' switch prevents the linker from
   4703 warning when linking object files that specify incompatible EABI
   4704 `wchar_t' size attributes.  For example, with this switch enabled,
   4705 linking of an object file using 32-bit `wchar_t' values with another
   4706 using 16-bit `wchar_t' values will not be diagnosed.
   4707 
   4708    The `--pic-veneer' switch makes the linker use PIC sequences for
   4709 ARM/Thumb interworking veneers, even if the rest of the binary is not
   4710 PIC.  This avoids problems on uClinux targets where `--emit-relocs' is
   4711 used to generate relocatable binaries.
   4712 
   4713    The linker will automatically generate and insert small sequences of
   4714 code into a linked ARM ELF executable whenever an attempt is made to
   4715 perform a function call to a symbol that is too far away.  The
   4716 placement of these sequences of instructions - called stubs - is
   4717 controlled by the command line option `--stub-group-size=N'.  The
   4718 placement is important because a poor choice can create a need for
   4719 duplicate stubs, increasing the code sizw.  The linker will try to
   4720 group stubs together in order to reduce interruptions to the flow of
   4721 code, but it needs guidance as to how big these groups should be and
   4722 where they should be placed.
   4723 
   4724    The value of `N', the parameter to the `--stub-group-size=' option
   4725 controls where the stub groups are placed.  If it is negative then all
   4726 stubs are placed after the first branch that needs them.  If it is
   4727 positive then the stubs can be placed either before or after the
   4728 branches that need them.  If the value of `N' is 1 (either +1 or -1)
   4729 then the linker will choose exactly where to place groups of stubs,
   4730 using its built in heuristics.  A value of `N' greater than 1 (or
   4731 smaller than -1) tells the linker that a single group of stubs can
   4732 service at most `N' bytes from the input sections.
   4733 
   4734    The default, if `--stub-group-size=' is not specified, is `N = +1'.
   4735 
   4736    Farcalls stubs insertion is fully supported for the ARM-EABI target
   4737 only, because it relies on object files properties not present
   4738 otherwise.
   4739 
   4740 
   4741 File: ld.info,  Node: HPPA ELF32,  Next: M68K,  Prev: ARM,  Up: Machine Dependent
   4742 
   4743 4.5 `ld' and HPPA 32-bit ELF Support
   4744 ====================================
   4745 
   4746 When generating a shared library, `ld' will by default generate import
   4747 stubs suitable for use with a single sub-space application.  The
   4748 `--multi-subspace' switch causes `ld' to generate export stubs, and
   4749 different (larger) import stubs suitable for use with multiple
   4750 sub-spaces.
   4751 
   4752    Long branch stubs and import/export stubs are placed by `ld' in stub
   4753 sections located between groups of input sections.  `--stub-group-size'
   4754 specifies the maximum size of a group of input sections handled by one
   4755 stub section.  Since branch offsets are signed, a stub section may
   4756 serve two groups of input sections, one group before the stub section,
   4757 and one group after it.  However, when using conditional branches that
   4758 require stubs, it may be better (for branch prediction) that stub
   4759 sections only serve one group of input sections.  A negative value for
   4760 `N' chooses this scheme, ensuring that branches to stubs always use a
   4761 negative offset.  Two special values of `N' are recognized, `1' and
   4762 `-1'.  These both instruct `ld' to automatically size input section
   4763 groups for the branch types detected, with the same behaviour regarding
   4764 stub placement as other positive or negative values of `N' respectively.
   4765 
   4766    Note that `--stub-group-size' does not split input sections.  A
   4767 single input section larger than the group size specified will of course
   4768 create a larger group (of one section).  If input sections are too
   4769 large, it may not be possible for a branch to reach its stub.
   4770 
   4771 
   4772 File: ld.info,  Node: M68K,  Next: MMIX,  Prev: HPPA ELF32,  Up: Machine Dependent
   4773 
   4774 4.6 `ld' and the Motorola 68K family
   4775 ====================================
   4776 
   4777 The `--got=TYPE' option lets you choose the GOT generation scheme.  The
   4778 choices are `single', `negative', `multigot' and `target'.  When
   4779 `target' is selected the linker chooses the default GOT generation
   4780 scheme for the current target.  `single' tells the linker to generate a
   4781 single GOT with entries only at non-negative offsets.  `negative'
   4782 instructs the linker to generate a single GOT with entries at both
   4783 negative and positive offsets.  Not all environments support such GOTs.
   4784 `multigot' allows the linker to generate several GOTs in the output
   4785 file.  All GOT references from a single input object file access the
   4786 same GOT, but references from different input object files might access
   4787 different GOTs.  Not all environments support such GOTs.
   4788 
   4789 
   4790 File: ld.info,  Node: MMIX,  Next: MSP430,  Prev: M68K,  Up: Machine Dependent
   4791 
   4792 4.7 `ld' and MMIX
   4793 =================
   4794 
   4795 For MMIX, there is a choice of generating `ELF' object files or `mmo'
   4796 object files when linking.  The simulator `mmix' understands the `mmo'
   4797 format.  The binutils `objcopy' utility can translate between the two
   4798 formats.
   4799 
   4800    There is one special section, the `.MMIX.reg_contents' section.
   4801 Contents in this section is assumed to correspond to that of global
   4802 registers, and symbols referring to it are translated to special
   4803 symbols, equal to registers.  In a final link, the start address of the
   4804 `.MMIX.reg_contents' section corresponds to the first allocated global
   4805 register multiplied by 8.  Register `$255' is not included in this
   4806 section; it is always set to the program entry, which is at the symbol
   4807 `Main' for `mmo' files.
   4808 
   4809    Global symbols with the prefix `__.MMIX.start.', for example
   4810 `__.MMIX.start..text' and `__.MMIX.start..data' are special.  The
   4811 default linker script uses these to set the default start address of a
   4812 section.
   4813 
   4814    Initial and trailing multiples of zero-valued 32-bit words in a
   4815 section, are left out from an mmo file.
   4816 
   4817 
   4818 File: ld.info,  Node: MSP430,  Next: M68HC11/68HC12,  Prev: MMIX,  Up: Machine Dependent
   4819 
   4820 4.8 `ld' and MSP430
   4821 ===================
   4822 
   4823 For the MSP430 it is possible to select the MPU architecture.  The flag
   4824 `-m [mpu type]' will select an appropriate linker script for selected
   4825 MPU type.  (To get a list of known MPUs just pass `-m help' option to
   4826 the linker).
   4827 
   4828    The linker will recognize some extra sections which are MSP430
   4829 specific:
   4830 
   4831 ``.vectors''
   4832      Defines a portion of ROM where interrupt vectors located.
   4833 
   4834 ``.bootloader''
   4835      Defines the bootloader portion of the ROM (if applicable).  Any
   4836      code in this section will be uploaded to the MPU.
   4837 
   4838 ``.infomem''
   4839      Defines an information memory section (if applicable).  Any code in
   4840      this section will be uploaded to the MPU.
   4841 
   4842 ``.infomemnobits''
   4843      This is the same as the `.infomem' section except that any code in
   4844      this section will not be uploaded to the MPU.
   4845 
   4846 ``.noinit''
   4847      Denotes a portion of RAM located above `.bss' section.
   4848 
   4849      The last two sections are used by gcc.
   4850 
   4851 
   4852 File: ld.info,  Node: PowerPC ELF32,  Next: PowerPC64 ELF64,  Prev: M68HC11/68HC12,  Up: Machine Dependent
   4853 
   4854 4.9 `ld' and PowerPC 32-bit ELF Support
   4855 =======================================
   4856 
   4857 Branches on PowerPC processors are limited to a signed 26-bit
   4858 displacement, which may result in `ld' giving `relocation truncated to
   4859 fit' errors with very large programs.  `--relax' enables the generation
   4860 of trampolines that can access the entire 32-bit address space.  These
   4861 trampolines are inserted at section boundaries, so may not themselves
   4862 be reachable if an input section exceeds 33M in size.
   4863 
   4864 `--bss-plt'
   4865      Current PowerPC GCC accepts a `-msecure-plt' option that generates
   4866      code capable of using a newer PLT and GOT layout that has the
   4867      security advantage of no executable section ever needing to be
   4868      writable and no writable section ever being executable.  PowerPC
   4869      `ld' will generate this layout, including stubs to access the PLT,
   4870      if all input files (including startup and static libraries) were
   4871      compiled with `-msecure-plt'.  `--bss-plt' forces the old BSS PLT
   4872      (and GOT layout) which can give slightly better performance.
   4873 
   4874 `--secure-plt'
   4875      `ld' will use the new PLT and GOT layout if it is linking new
   4876      `-fpic' or `-fPIC' code, but does not do so automatically when
   4877      linking non-PIC code.  This option requests the new PLT and GOT
   4878      layout.  A warning will be given if some object file requires the
   4879      old style BSS PLT.
   4880 
   4881 `--sdata-got'
   4882      The new secure PLT and GOT are placed differently relative to other
   4883      sections compared to older BSS PLT and GOT placement.  The
   4884      location of `.plt' must change because the new secure PLT is an
   4885      initialized section while the old PLT is uninitialized.  The
   4886      reason for the `.got' change is more subtle:  The new placement
   4887      allows `.got' to be read-only in applications linked with `-z
   4888      relro -z now'.  However, this placement means that `.sdata' cannot
   4889      always be used in shared libraries, because the PowerPC ABI
   4890      accesses `.sdata' in shared libraries from the GOT pointer.
   4891      `--sdata-got' forces the old GOT placement.  PowerPC GCC doesn't
   4892      use `.sdata' in shared libraries, so this option is really only
   4893      useful for other compilers that may do so.
   4894 
   4895 `--emit-stub-syms'
   4896      This option causes `ld' to label linker stubs with a local symbol
   4897      that encodes the stub type and destination.
   4898 
   4899 `--no-tls-optimize'
   4900      PowerPC `ld' normally performs some optimization of code sequences
   4901      used to access Thread-Local Storage.  Use this option to disable
   4902      the optimization.
   4903 
   4904 
   4905 File: ld.info,  Node: PowerPC64 ELF64,  Next: SPU ELF,  Prev: PowerPC ELF32,  Up: Machine Dependent
   4906 
   4907 4.10 `ld' and PowerPC64 64-bit ELF Support
   4908 ==========================================
   4909 
   4910 `--stub-group-size'
   4911      Long branch stubs, PLT call stubs  and TOC adjusting stubs are
   4912      placed by `ld' in stub sections located between groups of input
   4913      sections.  `--stub-group-size' specifies the maximum size of a
   4914      group of input sections handled by one stub section.  Since branch
   4915      offsets are signed, a stub section may serve two groups of input
   4916      sections, one group before the stub section, and one group after
   4917      it.  However, when using conditional branches that require stubs,
   4918      it may be better (for branch prediction) that stub sections only
   4919      serve one group of input sections.  A negative value for `N'
   4920      chooses this scheme, ensuring that branches to stubs always use a
   4921      negative offset.  Two special values of `N' are recognized, `1'
   4922      and `-1'.  These both instruct `ld' to automatically size input
   4923      section groups for the branch types detected, with the same
   4924      behaviour regarding stub placement as other positive or negative
   4925      values of `N' respectively.
   4926 
   4927      Note that `--stub-group-size' does not split input sections.  A
   4928      single input section larger than the group size specified will of
   4929      course create a larger group (of one section).  If input sections
   4930      are too large, it may not be possible for a branch to reach its
   4931      stub.
   4932 
   4933 `--emit-stub-syms'
   4934      This option causes `ld' to label linker stubs with a local symbol
   4935      that encodes the stub type and destination.
   4936 
   4937 `--dotsyms, --no-dotsyms'
   4938      These two options control how `ld' interprets version patterns in
   4939      a version script.  Older PowerPC64 compilers emitted both a
   4940      function descriptor symbol with the same name as the function, and
   4941      a code entry symbol with the name prefixed by a dot (`.').  To
   4942      properly version a function `foo', the version script thus needs
   4943      to control both `foo' and `.foo'.  The option `--dotsyms', on by
   4944      default, automatically adds the required dot-prefixed patterns.
   4945      Use `--no-dotsyms' to disable this feature.
   4946 
   4947 `--no-tls-optimize'
   4948      PowerPC64 `ld' normally performs some optimization of code
   4949      sequences used to access Thread-Local Storage.  Use this option to
   4950      disable the optimization.
   4951 
   4952 `--no-opd-optimize'
   4953      PowerPC64 `ld' normally removes `.opd' section entries
   4954      corresponding to deleted link-once functions, or functions removed
   4955      by the action of `--gc-sections' or linker script `/DISCARD/'.
   4956      Use this option to disable `.opd' optimization.
   4957 
   4958 `--non-overlapping-opd'
   4959      Some PowerPC64 compilers have an option to generate compressed
   4960      `.opd' entries spaced 16 bytes apart, overlapping the third word,
   4961      the static chain pointer (unused in C) with the first word of the
   4962      next entry.  This option expands such entries to the full 24 bytes.
   4963 
   4964 `--no-toc-optimize'
   4965      PowerPC64 `ld' normally removes unused `.toc' section entries.
   4966      Such entries are detected by examining relocations that reference
   4967      the TOC in code sections.  A reloc in a deleted code section marks
   4968      a TOC word as unneeded, while a reloc in a kept code section marks
   4969      a TOC word as needed.  Since the TOC may reference itself, TOC
   4970      relocs are also examined.  TOC words marked as both needed and
   4971      unneeded will of course be kept.  TOC words without any referencing
   4972      reloc are assumed to be part of a multi-word entry, and are kept or
   4973      discarded as per the nearest marked preceding word.  This works
   4974      reliably for compiler generated code, but may be incorrect if
   4975      assembly code is used to insert TOC entries.  Use this option to
   4976      disable the optimization.
   4977 
   4978 `--no-multi-toc'
   4979      By default, PowerPC64 GCC generates code for a TOC model where TOC
   4980      entries are accessed with a 16-bit offset from r2.  This limits the
   4981      total TOC size to 64K.  PowerPC64 `ld' extends this limit by
   4982      grouping code sections such that each group uses less than 64K for
   4983      its TOC entries, then inserts r2 adjusting stubs between
   4984      inter-group calls.  `ld' does not split apart input sections, so
   4985      cannot help if a single input file has a `.toc' section that
   4986      exceeds 64K, most likely from linking multiple files with `ld -r'.
   4987      Use this option to turn off this feature.
   4988 
   4989 
   4990 File: ld.info,  Node: SPU ELF,  Next: TI COFF,  Prev: PowerPC64 ELF64,  Up: Machine Dependent
   4991 
   4992 4.11 `ld' and SPU ELF Support
   4993 =============================
   4994 
   4995 `--plugin'
   4996      This option marks an executable as a PIC plugin module.
   4997 
   4998 `--no-overlays'
   4999      Normally, `ld' recognizes calls to functions within overlay
   5000      regions, and redirects such calls to an overlay manager via a stub.
   5001      `ld' also provides a built-in overlay manager.  This option turns
   5002      off all this special overlay handling.
   5003 
   5004 `--emit-stub-syms'
   5005      This option causes `ld' to label overlay stubs with a local symbol
   5006      that encodes the stub type and destination.
   5007 
   5008 `--extra-overlay-stubs'
   5009      This option causes `ld' to add overlay call stubs on all function
   5010      calls out of overlay regions.  Normally stubs are not added on
   5011      calls to non-overlay regions.
   5012 
   5013 `--local-store=lo:hi'
   5014      `ld' usually checks that a final executable for SPU fits in the
   5015      address range 0 to 256k.  This option may be used to change the
   5016      range.  Disable the check entirely with `--local-store=0:0'.
   5017 
   5018 `--stack-analysis'
   5019      SPU local store space is limited.  Over-allocation of stack space
   5020      unnecessarily limits space available for code and data, while
   5021      under-allocation results in runtime failures.  If given this
   5022      option, `ld' will provide an estimate of maximum stack usage.
   5023      `ld' does this by examining symbols in code sections to determine
   5024      the extents of functions, and looking at function prologues for
   5025      stack adjusting instructions.  A call-graph is created by looking
   5026      for relocations on branch instructions.  The graph is then searched
   5027      for the maximum stack usage path.  Note that this analysis does not
   5028      find calls made via function pointers, and does not handle
   5029      recursion and other cycles in the call graph.  Stack usage may be
   5030      under-estimated if your code makes such calls.  Also, stack usage
   5031      for dynamic allocation, e.g. alloca, will not be detected.  If a
   5032      link map is requested, detailed information about each function's
   5033      stack usage and calls will be given.
   5034 
   5035 `--emit-stack-syms'
   5036      This option, if given along with `--stack-analysis' will result in
   5037      `ld' emitting stack sizing symbols for each function.  These take
   5038      the form `__stack_<function_name>' for global functions, and
   5039      `__stack_<number>_<function_name>' for static functions.
   5040      `<number>' is the section id in hex.  The value of such symbols is
   5041      the stack requirement for the corresponding function.  The symbol
   5042      size will be zero, type `STT_NOTYPE', binding `STB_LOCAL', and
   5043      section `SHN_ABS'.
   5044 
   5045 
   5046 File: ld.info,  Node: TI COFF,  Next: WIN32,  Prev: SPU ELF,  Up: Machine Dependent
   5047 
   5048 4.12 `ld''s Support for Various TI COFF Versions
   5049 ================================================
   5050 
   5051 The `--format' switch allows selection of one of the various TI COFF
   5052 versions.  The latest of this writing is 2; versions 0 and 1 are also
   5053 supported.  The TI COFF versions also vary in header byte-order format;
   5054 `ld' will read any version or byte order, but the output header format
   5055 depends on the default specified by the specific target.
   5056 
   5057 
   5058 File: ld.info,  Node: WIN32,  Next: Xtensa,  Prev: TI COFF,  Up: Machine Dependent
   5059 
   5060 4.13 `ld' and WIN32 (cygwin/mingw)
   5061 ==================================
   5062 
   5063 This section describes some of the win32 specific `ld' issues.  See
   5064 *note Command Line Options: Options. for detailed description of the
   5065 command line options mentioned here.
   5066 
   5067 _import libraries_
   5068      The standard Windows linker creates and uses so-called import
   5069      libraries, which contains information for linking to dll's.  They
   5070      are regular static archives and are handled as any other static
   5071      archive.  The cygwin and mingw ports of `ld' have specific support
   5072      for creating such libraries provided with the `--out-implib'
   5073      command line option.
   5074 
   5075 _exporting DLL symbols_
   5076      The cygwin/mingw `ld' has several ways to export symbols for dll's.
   5077 
   5078     _using auto-export functionality_
   5079           By default `ld' exports symbols with the auto-export
   5080           functionality, which is controlled by the following command
   5081           line options:
   5082 
   5083              * -export-all-symbols   [This is the default]
   5084 
   5085              * -exclude-symbols
   5086 
   5087              * -exclude-libs
   5088 
   5089           If, however, `--export-all-symbols' is not given explicitly
   5090           on the command line, then the default auto-export behavior
   5091           will be _disabled_ if either of the following are true:
   5092 
   5093              * A DEF file is used.
   5094 
   5095              * Any symbol in any object file was marked with the
   5096                __declspec(dllexport) attribute.
   5097 
   5098     _using a DEF file_
   5099           Another way of exporting symbols is using a DEF file.  A DEF
   5100           file is an ASCII file containing definitions of symbols which
   5101           should be exported when a dll is created.  Usually it is
   5102           named `<dll name>.def' and is added as any other object file
   5103           to the linker's command line.  The file's name must end in
   5104           `.def' or `.DEF'.
   5105 
   5106                gcc -o <output> <objectfiles> <dll name>.def
   5107 
   5108           Using a DEF file turns off the normal auto-export behavior,
   5109           unless the `--export-all-symbols' option is also used.
   5110 
   5111           Here is an example of a DEF file for a shared library called
   5112           `xyz.dll':
   5113 
   5114                LIBRARY "xyz.dll" BASE=0x20000000
   5115 
   5116                EXPORTS
   5117                foo
   5118                bar
   5119                _bar = bar
   5120                another_foo = abc.dll.afoo
   5121                var1 DATA
   5122 
   5123           This example defines a DLL with a non-default base address
   5124           and five symbols in the export table. The third exported
   5125           symbol `_bar' is an alias for the second. The fourth symbol,
   5126           `another_foo' is resolved by "forwarding" to another module
   5127           and treating it as an alias for `afoo' exported from the DLL
   5128           `abc.dll'. The final symbol `var1' is declared to be a data
   5129           object.
   5130 
   5131           The optional `LIBRARY <name>' command indicates the _internal_
   5132           name of the output DLL. If `<name>' does not include a suffix,
   5133           the default library suffix, `.DLL' is appended.
   5134 
   5135           When the .DEF file is used to build an application, rather
   5136           than a library, the `NAME <name>' command should be used
   5137           instead of `LIBRARY'. If `<name>' does not include a suffix,
   5138           the default executable suffix, `.EXE' is appended.
   5139 
   5140           With either `LIBRARY <name>' or `NAME <name>' the optional
   5141           specification `BASE = <number>' may be used to specify a
   5142           non-default base address for the image.
   5143 
   5144           If neither `LIBRARY <name>' nor  `NAME <name>' is specified,
   5145           or they specify an empty string, the internal name is the
   5146           same as the filename specified on the command line.
   5147 
   5148           The complete specification of an export symbol is:
   5149 
   5150                EXPORTS
   5151                  ( (  ( <name1> [ = <name2> ] )
   5152                     | ( <name1> = <module-name> . <external-name>))
   5153                  [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
   5154 
   5155           Declares `<name1>' as an exported symbol from the DLL, or
   5156           declares `<name1>' as an exported alias for `<name2>'; or
   5157           declares `<name1>' as a "forward" alias for the symbol
   5158           `<external-name>' in the DLL `<module-name>'.  Optionally,
   5159           the symbol may be exported by the specified ordinal
   5160           `<integer>' alias.
   5161 
   5162           The optional keywords that follow the declaration indicate:
   5163 
   5164           `NONAME': Do not put the symbol name in the DLL's export
   5165           table.  It will still be exported by its ordinal alias
   5166           (either the value specified by the .def specification or,
   5167           otherwise, the value assigned by the linker). The symbol
   5168           name, however, does remain visible in the import library (if
   5169           any), unless `PRIVATE' is also specified.
   5170 
   5171           `DATA': The symbol is a variable or object, rather than a
   5172           function.  The import lib will export only an indirect
   5173           reference to `foo' as the symbol `_imp__foo' (ie, `foo' must
   5174           be resolved as `*_imp__foo').
   5175 
   5176           `CONSTANT': Like `DATA', but put the undecorated `foo' as
   5177           well as `_imp__foo' into the import library. Both refer to the
   5178           read-only import address table's pointer to the variable, not
   5179           to the variable itself. This can be dangerous. If the user
   5180           code fails to add the `dllimport' attribute and also fails to
   5181           explicitly add the extra indirection that the use of the
   5182           attribute enforces, the application will behave unexpectedly.
   5183 
   5184           `PRIVATE': Put the symbol in the DLL's export table, but do
   5185           not put it into the static import library used to resolve
   5186           imports at link time. The symbol can still be imported using
   5187           the `LoadLibrary/GetProcAddress' API at runtime or by by
   5188           using the GNU ld extension of linking directly to the DLL
   5189           without an import library.
   5190 
   5191           See ld/deffilep.y in the binutils sources for the full
   5192           specification of other DEF file statements
   5193 
   5194           While linking a shared dll, `ld' is able to create a DEF file
   5195           with the `--output-def <file>' command line option.
   5196 
   5197     _Using decorations_
   5198           Another way of marking symbols for export is to modify the
   5199           source code itself, so that when building the DLL each symbol
   5200           to be exported is declared as:
   5201 
   5202                __declspec(dllexport) int a_variable
   5203                __declspec(dllexport) void a_function(int with_args)
   5204 
   5205           All such symbols will be exported from the DLL.  If, however,
   5206           any of the object files in the DLL contain symbols decorated
   5207           in this way, then the normal auto-export behavior is
   5208           disabled, unless the `--export-all-symbols' option is also
   5209           used.
   5210 
   5211           Note that object files that wish to access these symbols must
   5212           _not_ decorate them with dllexport.  Instead, they should use
   5213           dllimport, instead:
   5214 
   5215                __declspec(dllimport) int a_variable
   5216                __declspec(dllimport) void a_function(int with_args)
   5217 
   5218           This complicates the structure of library header files,
   5219           because when included by the library itself the header must
   5220           declare the variables and functions as dllexport, but when
   5221           included by client code the header must declare them as
   5222           dllimport.  There are a number of idioms that are typically
   5223           used to do this; often client code can omit the __declspec()
   5224           declaration completely.  See `--enable-auto-import' and
   5225           `automatic data imports' for more information.
   5226 
   5227 _automatic data imports_
   5228      The standard Windows dll format supports data imports from dlls
   5229      only by adding special decorations (dllimport/dllexport), which
   5230      let the compiler produce specific assembler instructions to deal
   5231      with this issue.  This increases the effort necessary to port
   5232      existing Un*x code to these platforms, especially for large c++
   5233      libraries and applications.  The auto-import feature, which was
   5234      initially provided by Paul Sokolovsky, allows one to omit the
   5235      decorations to achieve a behavior that conforms to that on
   5236      POSIX/Un*x platforms. This feature is enabled with the
   5237      `--enable-auto-import' command-line option, although it is enabled
   5238      by default on cygwin/mingw.  The `--enable-auto-import' option
   5239      itself now serves mainly to suppress any warnings that are
   5240      ordinarily emitted when linked objects trigger the feature's use.
   5241 
   5242      auto-import of variables does not always work flawlessly without
   5243      additional assistance.  Sometimes, you will see this message
   5244 
   5245      "variable '<var>' can't be auto-imported. Please read the
   5246      documentation for ld's `--enable-auto-import' for details."
   5247 
   5248      The `--enable-auto-import' documentation explains why this error
   5249      occurs, and several methods that can be used to overcome this
   5250      difficulty.  One of these methods is the _runtime pseudo-relocs_
   5251      feature, described below.
   5252 
   5253      For complex variables imported from DLLs (such as structs or
   5254      classes), object files typically contain a base address for the
   5255      variable and an offset (_addend_) within the variable-to specify a
   5256      particular field or public member, for instance.  Unfortunately,
   5257      the runtime loader used in win32 environments is incapable of
   5258      fixing these references at runtime without the additional
   5259      information supplied by dllimport/dllexport decorations.  The
   5260      standard auto-import feature described above is unable to resolve
   5261      these references.
   5262 
   5263      The `--enable-runtime-pseudo-relocs' switch allows these
   5264      references to be resolved without error, while leaving the task of
   5265      adjusting the references themselves (with their non-zero addends)
   5266      to specialized code provided by the runtime environment.  Recent
   5267      versions of the cygwin and mingw environments and compilers
   5268      provide this runtime support; older versions do not.  However, the
   5269      support is only necessary on the developer's platform; the
   5270      compiled result will run without error on an older system.
   5271 
   5272      `--enable-runtime-pseudo-relocs' is not the default; it must be
   5273      explicitly enabled as needed.
   5274 
   5275 _direct linking to a dll_
   5276      The cygwin/mingw ports of `ld' support the direct linking,
   5277      including data symbols, to a dll without the usage of any import
   5278      libraries.  This is much faster and uses much less memory than
   5279      does the traditional import library method, especially when
   5280      linking large libraries or applications.  When `ld' creates an
   5281      import lib, each function or variable exported from the dll is
   5282      stored in its own bfd, even though a single bfd could contain many
   5283      exports.  The overhead involved in storing, loading, and
   5284      processing so many bfd's is quite large, and explains the
   5285      tremendous time, memory, and storage needed to link against
   5286      particularly large or complex libraries when using import libs.
   5287 
   5288      Linking directly to a dll uses no extra command-line switches
   5289      other than `-L' and `-l', because `ld' already searches for a
   5290      number of names to match each library.  All that is needed from
   5291      the developer's perspective is an understanding of this search, in
   5292      order to force ld to select the dll instead of an import library.
   5293 
   5294      For instance, when ld is called with the argument `-lxxx' it will
   5295      attempt to find, in the first directory of its search path,
   5296 
   5297           libxxx.dll.a
   5298           xxx.dll.a
   5299           libxxx.a
   5300           xxx.lib
   5301           cygxxx.dll (*)
   5302           libxxx.dll
   5303           xxx.dll
   5304 
   5305      before moving on to the next directory in the search path.
   5306 
   5307      (*) Actually, this is not `cygxxx.dll' but in fact is
   5308      `<prefix>xxx.dll', where `<prefix>' is set by the `ld' option
   5309      `--dll-search-prefix=<prefix>'. In the case of cygwin, the
   5310      standard gcc spec file includes `--dll-search-prefix=cyg', so in
   5311      effect we actually search for `cygxxx.dll'.
   5312 
   5313      Other win32-based unix environments, such as mingw or pw32, may
   5314      use other `<prefix>'es, although at present only cygwin makes use
   5315      of this feature.  It was originally intended to help avoid name
   5316      conflicts among dll's built for the various win32/un*x
   5317      environments, so that (for example) two versions of a zlib dll
   5318      could coexist on the same machine.
   5319 
   5320      The generic cygwin/mingw path layout uses a `bin' directory for
   5321      applications and dll's and a `lib' directory for the import
   5322      libraries (using cygwin nomenclature):
   5323 
   5324           bin/
   5325           	cygxxx.dll
   5326           lib/
   5327           	libxxx.dll.a   (in case of dll's)
   5328           	libxxx.a       (in case of static archive)
   5329 
   5330      Linking directly to a dll without using the import library can be
   5331      done two ways:
   5332 
   5333      1. Use the dll directly by adding the `bin' path to the link line
   5334           gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
   5335 
   5336      However, as the dll's often have version numbers appended to their
   5337      names (`cygncurses-5.dll') this will often fail, unless one
   5338      specifies `-L../bin -lncurses-5' to include the version.  Import
   5339      libs are generally not versioned, and do not have this difficulty.
   5340 
   5341      2. Create a symbolic link from the dll to a file in the `lib'
   5342      directory according to the above mentioned search pattern.  This
   5343      should be used to avoid unwanted changes in the tools needed for
   5344      making the app/dll.
   5345 
   5346           ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
   5347 
   5348      Then you can link without any make environment changes.
   5349 
   5350           gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx
   5351 
   5352      This technique also avoids the version number problems, because
   5353      the following is perfectly legal
   5354 
   5355           bin/
   5356           	cygxxx-5.dll
   5357           lib/
   5358           	libxxx.dll.a -> ../bin/cygxxx-5.dll
   5359 
   5360      Linking directly to a dll without using an import lib will work
   5361      even when auto-import features are exercised, and even when
   5362      `--enable-runtime-pseudo-relocs' is used.
   5363 
   5364      Given the improvements in speed and memory usage, one might
   5365      justifiably wonder why import libraries are used at all.  There
   5366      are three reasons:
   5367 
   5368      1. Until recently, the link-directly-to-dll functionality did _not_
   5369      work with auto-imported data.
   5370 
   5371      2. Sometimes it is necessary to include pure static objects within
   5372      the import library (which otherwise contains only bfd's for
   5373      indirection symbols that point to the exports of a dll).  Again,
   5374      the import lib for the cygwin kernel makes use of this ability,
   5375      and it is not possible to do this without an import lib.
   5376 
   5377      3. Symbol aliases can only be resolved using an import lib.  This
   5378      is critical when linking against OS-supplied dll's (eg, the win32
   5379      API) in which symbols are usually exported as undecorated aliases
   5380      of their stdcall-decorated assembly names.
   5381 
   5382      So, import libs are not going away.  But the ability to replace
   5383      true import libs with a simple symbolic link to (or a copy of) a
   5384      dll, in many cases, is a useful addition to the suite of tools
   5385      binutils makes available to the win32 developer.  Given the
   5386      massive improvements in memory requirements during linking, storage
   5387      requirements, and linking speed, we expect that many developers
   5388      will soon begin to use this feature whenever possible.
   5389 
   5390 _symbol aliasing_
   5391 
   5392     _adding additional names_
   5393           Sometimes, it is useful to export symbols with additional
   5394           names.  A symbol `foo' will be exported as `foo', but it can
   5395           also be exported as `_foo' by using special directives in the
   5396           DEF file when creating the dll.  This will affect also the
   5397           optional created import library.  Consider the following DEF
   5398           file:
   5399 
   5400                LIBRARY "xyz.dll" BASE=0x61000000
   5401 
   5402                EXPORTS
   5403                foo
   5404                _foo = foo
   5405 
   5406           The line `_foo = foo' maps the symbol `foo' to `_foo'.
   5407 
   5408           Another method for creating a symbol alias is to create it in
   5409           the source code using the "weak" attribute:
   5410 
   5411                void foo () { /* Do something.  */; }
   5412                void _foo () __attribute__ ((weak, alias ("foo")));
   5413 
   5414           See the gcc manual for more information about attributes and
   5415           weak symbols.
   5416 
   5417     _renaming symbols_
   5418           Sometimes it is useful to rename exports.  For instance, the
   5419           cygwin kernel does this regularly.  A symbol `_foo' can be
   5420           exported as `foo' but not as `_foo' by using special
   5421           directives in the DEF file. (This will also affect the import
   5422           library, if it is created).  In the following example:
   5423 
   5424                LIBRARY "xyz.dll" BASE=0x61000000
   5425 
   5426                EXPORTS
   5427                _foo = foo
   5428 
   5429           The line `_foo = foo' maps the exported symbol `foo' to
   5430           `_foo'.
   5431 
   5432      Note: using a DEF file disables the default auto-export behavior,
   5433      unless the `--export-all-symbols' command line option is used.
   5434      If, however, you are trying to rename symbols, then you should list
   5435      _all_ desired exports in the DEF file, including the symbols that
   5436      are not being renamed, and do _not_ use the `--export-all-symbols'
   5437      option.  If you list only the renamed symbols in the DEF file, and
   5438      use `--export-all-symbols' to handle the other symbols, then the
   5439      both the new names _and_ the original names for the renamed
   5440      symbols will be exported.  In effect, you'd be aliasing those
   5441      symbols, not renaming them, which is probably not what you wanted.
   5442 
   5443 _weak externals_
   5444      The Windows object format, PE, specifies a form of weak symbols
   5445      called weak externals.  When a weak symbol is linked and the
   5446      symbol is not defined, the weak symbol becomes an alias for some
   5447      other symbol.  There are three variants of weak externals:
   5448         * Definition is searched for in objects and libraries,
   5449           historically called lazy externals.
   5450 
   5451         * Definition is searched for only in other objects, not in
   5452           libraries.  This form is not presently implemented.
   5453 
   5454         * No search; the symbol is an alias.  This form is not presently
   5455           implemented.
   5456      As a GNU extension, weak symbols that do not specify an alternate
   5457      symbol are supported.  If the symbol is undefined when linking,
   5458      the symbol uses a default value.
   5459 
   5460 
   5461 File: ld.info,  Node: Xtensa,  Prev: WIN32,  Up: Machine Dependent
   5462 
   5463 4.14 `ld' and Xtensa Processors
   5464 ===============================
   5465 
   5466 The default `ld' behavior for Xtensa processors is to interpret
   5467 `SECTIONS' commands so that lists of explicitly named sections in a
   5468 specification with a wildcard file will be interleaved when necessary to
   5469 keep literal pools within the range of PC-relative load offsets.  For
   5470 example, with the command:
   5471 
   5472      SECTIONS
   5473      {
   5474        .text : {
   5475          *(.literal .text)
   5476        }
   5477      }
   5478 
   5479 `ld' may interleave some of the `.literal' and `.text' sections from
   5480 different object files to ensure that the literal pools are within the
   5481 range of PC-relative load offsets.  A valid interleaving might place
   5482 the `.literal' sections from an initial group of files followed by the
   5483 `.text' sections of that group of files.  Then, the `.literal' sections
   5484 from the rest of the files and the `.text' sections from the rest of
   5485 the files would follow.
   5486 
   5487    Relaxation is enabled by default for the Xtensa version of `ld' and
   5488 provides two important link-time optimizations.  The first optimization
   5489 is to combine identical literal values to reduce code size.  A redundant
   5490 literal will be removed and all the `L32R' instructions that use it
   5491 will be changed to reference an identical literal, as long as the
   5492 location of the replacement literal is within the offset range of all
   5493 the `L32R' instructions.  The second optimization is to remove
   5494 unnecessary overhead from assembler-generated "longcall" sequences of
   5495 `L32R'/`CALLXN' when the target functions are within range of direct
   5496 `CALLN' instructions.
   5497 
   5498    For each of these cases where an indirect call sequence can be
   5499 optimized to a direct call, the linker will change the `CALLXN'
   5500 instruction to a `CALLN' instruction, remove the `L32R' instruction,
   5501 and remove the literal referenced by the `L32R' instruction if it is
   5502 not used for anything else.  Removing the `L32R' instruction always
   5503 reduces code size but can potentially hurt performance by changing the
   5504 alignment of subsequent branch targets.  By default, the linker will
   5505 always preserve alignments, either by switching some instructions
   5506 between 24-bit encodings and the equivalent density instructions or by
   5507 inserting a no-op in place of the `L32R' instruction that was removed.
   5508 If code size is more important than performance, the `--size-opt'
   5509 option can be used to prevent the linker from widening density
   5510 instructions or inserting no-ops, except in a few cases where no-ops
   5511 are required for correctness.
   5512 
   5513    The following Xtensa-specific command-line options can be used to
   5514 control the linker:
   5515 
   5516 `--no-relax'
   5517      Since the Xtensa version of `ld' enables the `--relax' option by
   5518      default, the `--no-relax' option is provided to disable relaxation.
   5519 
   5520 `--size-opt'
   5521      When optimizing indirect calls to direct calls, optimize for code
   5522      size more than performance.  With this option, the linker will not
   5523      insert no-ops or widen density instructions to preserve branch
   5524      target alignment.  There may still be some cases where no-ops are
   5525      required to preserve the correctness of the code.
   5526 
   5527 
   5528 File: ld.info,  Node: BFD,  Next: Reporting Bugs,  Prev: Machine Dependent,  Up: Top
   5529 
   5530 5 BFD
   5531 *****
   5532 
   5533 The linker accesses object and archive files using the BFD libraries.
   5534 These libraries allow the linker to use the same routines to operate on
   5535 object files whatever the object file format.  A different object file
   5536 format can be supported simply by creating a new BFD back end and adding
   5537 it to the library.  To conserve runtime memory, however, the linker and
   5538 associated tools are usually configured to support only a subset of the
   5539 object file formats available.  You can use `objdump -i' (*note
   5540 objdump: (binutils.info)objdump.) to list all the formats available for
   5541 your configuration.
   5542 
   5543    As with most implementations, BFD is a compromise between several
   5544 conflicting requirements. The major factor influencing BFD design was
   5545 efficiency: any time used converting between formats is time which
   5546 would not have been spent had BFD not been involved. This is partly
   5547 offset by abstraction payback; since BFD simplifies applications and
   5548 back ends, more time and care may be spent optimizing algorithms for a
   5549 greater speed.
   5550 
   5551    One minor artifact of the BFD solution which you should bear in mind
   5552 is the potential for information loss.  There are two places where
   5553 useful information can be lost using the BFD mechanism: during
   5554 conversion and during output. *Note BFD information loss::.
   5555 
   5556 * Menu:
   5557 
   5558 * BFD outline::                 How it works: an outline of BFD
   5559 
   5560 
   5561 File: ld.info,  Node: BFD outline,  Up: BFD
   5562 
   5563 5.1 How It Works: An Outline of BFD
   5564 ===================================
   5565 
   5566 When an object file is opened, BFD subroutines automatically determine
   5567 the format of the input object file.  They then build a descriptor in
   5568 memory with pointers to routines that will be used to access elements of
   5569 the object file's data structures.
   5570 
   5571    As different information from the object files is required, BFD
   5572 reads from different sections of the file and processes them.  For
   5573 example, a very common operation for the linker is processing symbol
   5574 tables.  Each BFD back end provides a routine for converting between
   5575 the object file's representation of symbols and an internal canonical
   5576 format. When the linker asks for the symbol table of an object file, it
   5577 calls through a memory pointer to the routine from the relevant BFD
   5578 back end which reads and converts the table into a canonical form.  The
   5579 linker then operates upon the canonical form. When the link is finished
   5580 and the linker writes the output file's symbol table, another BFD back
   5581 end routine is called to take the newly created symbol table and
   5582 convert it into the chosen output format.
   5583 
   5584 * Menu:
   5585 
   5586 * BFD information loss::	Information Loss
   5587 * Canonical format::		The BFD	canonical object-file format
   5588 
   5589 
   5590 File: ld.info,  Node: BFD information loss,  Next: Canonical format,  Up: BFD outline
   5591 
   5592 5.1.1 Information Loss
   5593 ----------------------
   5594 
   5595 _Information can be lost during output._ The output formats supported
   5596 by BFD do not provide identical facilities, and information which can
   5597 be described in one form has nowhere to go in another format. One
   5598 example of this is alignment information in `b.out'. There is nowhere
   5599 in an `a.out' format file to store alignment information on the
   5600 contained data, so when a file is linked from `b.out' and an `a.out'
   5601 image is produced, alignment information will not propagate to the
   5602 output file. (The linker will still use the alignment information
   5603 internally, so the link is performed correctly).
   5604 
   5605    Another example is COFF section names. COFF files may contain an
   5606 unlimited number of sections, each one with a textual section name. If
   5607 the target of the link is a format which does not have many sections
   5608 (e.g., `a.out') or has sections without names (e.g., the Oasys format),
   5609 the link cannot be done simply. You can circumvent this problem by
   5610 describing the desired input-to-output section mapping with the linker
   5611 command language.
   5612 
   5613    _Information can be lost during canonicalization._ The BFD internal
   5614 canonical form of the external formats is not exhaustive; there are
   5615 structures in input formats for which there is no direct representation
   5616 internally.  This means that the BFD back ends cannot maintain all
   5617 possible data richness through the transformation between external to
   5618 internal and back to external formats.
   5619 
   5620    This limitation is only a problem when an application reads one
   5621 format and writes another.  Each BFD back end is responsible for
   5622 maintaining as much data as possible, and the internal BFD canonical
   5623 form has structures which are opaque to the BFD core, and exported only
   5624 to the back ends. When a file is read in one format, the canonical form
   5625 is generated for BFD and the application. At the same time, the back
   5626 end saves away any information which may otherwise be lost. If the data
   5627 is then written back in the same format, the back end routine will be
   5628 able to use the canonical form provided by the BFD core as well as the
   5629 information it prepared earlier.  Since there is a great deal of
   5630 commonality between back ends, there is no information lost when
   5631 linking or copying big endian COFF to little endian COFF, or `a.out' to
   5632 `b.out'.  When a mixture of formats is linked, the information is only
   5633 lost from the files whose format differs from the destination.
   5634 
   5635 
   5636 File: ld.info,  Node: Canonical format,  Prev: BFD information loss,  Up: BFD outline
   5637 
   5638 5.1.2 The BFD canonical object-file format
   5639 ------------------------------------------
   5640 
   5641 The greatest potential for loss of information occurs when there is the
   5642 least overlap between the information provided by the source format,
   5643 that stored by the canonical format, and that needed by the destination
   5644 format. A brief description of the canonical form may help you
   5645 understand which kinds of data you can count on preserving across
   5646 conversions.  
   5647 
   5648 _files_
   5649      Information stored on a per-file basis includes target machine
   5650      architecture, particular implementation format type, a demand
   5651      pageable bit, and a write protected bit.  Information like Unix
   5652      magic numbers is not stored here--only the magic numbers' meaning,
   5653      so a `ZMAGIC' file would have both the demand pageable bit and the
   5654      write protected text bit set.  The byte order of the target is
   5655      stored on a per-file basis, so that big- and little-endian object
   5656      files may be used with one another.
   5657 
   5658 _sections_
   5659      Each section in the input file contains the name of the section,
   5660      the section's original address in the object file, size and
   5661      alignment information, various flags, and pointers into other BFD
   5662      data structures.
   5663 
   5664 _symbols_
   5665      Each symbol contains a pointer to the information for the object
   5666      file which originally defined it, its name, its value, and various
   5667      flag bits.  When a BFD back end reads in a symbol table, it
   5668      relocates all symbols to make them relative to the base of the
   5669      section where they were defined.  Doing this ensures that each
   5670      symbol points to its containing section.  Each symbol also has a
   5671      varying amount of hidden private data for the BFD back end.  Since
   5672      the symbol points to the original file, the private data format
   5673      for that symbol is accessible.  `ld' can operate on a collection
   5674      of symbols of wildly different formats without problems.
   5675 
   5676      Normal global and simple local symbols are maintained on output,
   5677      so an output file (no matter its format) will retain symbols
   5678      pointing to functions and to global, static, and common variables.
   5679      Some symbol information is not worth retaining; in `a.out', type
   5680      information is stored in the symbol table as long symbol names.
   5681      This information would be useless to most COFF debuggers; the
   5682      linker has command line switches to allow users to throw it away.
   5683 
   5684      There is one word of type information within the symbol, so if the
   5685      format supports symbol type information within symbols (for
   5686      example, COFF, IEEE, Oasys) and the type is simple enough to fit
   5687      within one word (nearly everything but aggregates), the
   5688      information will be preserved.
   5689 
   5690 _relocation level_
   5691      Each canonical BFD relocation record contains a pointer to the
   5692      symbol to relocate to, the offset of the data to relocate, the
   5693      section the data is in, and a pointer to a relocation type
   5694      descriptor. Relocation is performed by passing messages through
   5695      the relocation type descriptor and the symbol pointer. Therefore,
   5696      relocations can be performed on output data using a relocation
   5697      method that is only available in one of the input formats. For
   5698      instance, Oasys provides a byte relocation format.  A relocation
   5699      record requesting this relocation type would point indirectly to a
   5700      routine to perform this, so the relocation may be performed on a
   5701      byte being written to a 68k COFF file, even though 68k COFF has no
   5702      such relocation type.
   5703 
   5704 _line numbers_
   5705      Object formats can contain, for debugging purposes, some form of
   5706      mapping between symbols, source line numbers, and addresses in the
   5707      output file.  These addresses have to be relocated along with the
   5708      symbol information.  Each symbol with an associated list of line
   5709      number records points to the first record of the list.  The head
   5710      of a line number list consists of a pointer to the symbol, which
   5711      allows finding out the address of the function whose line number
   5712      is being described. The rest of the list is made up of pairs:
   5713      offsets into the section and line numbers. Any format which can
   5714      simply derive this information can pass it successfully between
   5715      formats (COFF, IEEE and Oasys).
   5716 
   5717 
   5718 File: ld.info,  Node: Reporting Bugs,  Next: MRI,  Prev: BFD,  Up: Top
   5719 
   5720 6 Reporting Bugs
   5721 ****************
   5722 
   5723 Your bug reports play an essential role in making `ld' reliable.
   5724 
   5725    Reporting a bug may help you by bringing a solution to your problem,
   5726 or it may not.  But in any case the principal function of a bug report
   5727 is to help the entire community by making the next version of `ld' work
   5728 better.  Bug reports are your contribution to the maintenance of `ld'.
   5729 
   5730    In order for a bug report to serve its purpose, you must include the
   5731 information that enables us to fix the bug.
   5732 
   5733 * Menu:
   5734 
   5735 * Bug Criteria::                Have you found a bug?
   5736 * Bug Reporting::               How to report bugs
   5737 
   5738 
   5739 File: ld.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: Reporting Bugs
   5740 
   5741 6.1 Have You Found a Bug?
   5742 =========================
   5743 
   5744 If you are not sure whether you have found a bug, here are some
   5745 guidelines:
   5746 
   5747    * If the linker gets a fatal signal, for any input whatever, that is
   5748      a `ld' bug.  Reliable linkers never crash.
   5749 
   5750    * If `ld' produces an error message for valid input, that is a bug.
   5751 
   5752    * If `ld' does not produce an error message for invalid input, that
   5753      may be a bug.  In the general case, the linker can not verify that
   5754      object files are correct.
   5755 
   5756    * If you are an experienced user of linkers, your suggestions for
   5757      improvement of `ld' are welcome in any case.
   5758 
   5759 
   5760 File: ld.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: Reporting Bugs
   5761 
   5762 6.2 How to Report Bugs
   5763 ======================
   5764 
   5765 A number of companies and individuals offer support for GNU products.
   5766 If you obtained `ld' from a support organization, we recommend you
   5767 contact that organization first.
   5768 
   5769    You can find contact information for many support companies and
   5770 individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
   5771 
   5772    Otherwise, send bug reports for `ld' to
   5773 `http://www.sourceware.org/bugzilla/'.
   5774 
   5775    The fundamental principle of reporting bugs usefully is this:
   5776 *report all the facts*.  If you are not sure whether to state a fact or
   5777 leave it out, state it!
   5778 
   5779    Often people omit facts because they think they know what causes the
   5780 problem and assume that some details do not matter.  Thus, you might
   5781 assume that the name of a symbol you use in an example does not matter.
   5782 Well, probably it does not, but one cannot be sure.  Perhaps the bug is
   5783 a stray memory reference which happens to fetch from the location where
   5784 that name is stored in memory; perhaps, if the name were different, the
   5785 contents of that location would fool the linker into doing the right
   5786 thing despite the bug.  Play it safe and give a specific, complete
   5787 example.  That is the easiest thing for you to do, and the most helpful.
   5788 
   5789    Keep in mind that the purpose of a bug report is to enable us to fix
   5790 the bug if it is new to us.  Therefore, always write your bug reports
   5791 on the assumption that the bug has not been reported previously.
   5792 
   5793    Sometimes people give a few sketchy facts and ask, "Does this ring a
   5794 bell?"  This cannot help us fix a bug, so it is basically useless.  We
   5795 respond by asking for enough details to enable us to investigate.  You
   5796 might as well expedite matters by sending them to begin with.
   5797 
   5798    To enable us to fix the bug, you should include all these things:
   5799 
   5800    * The version of `ld'.  `ld' announces it if you start it with the
   5801      `--version' argument.
   5802 
   5803      Without this, we will not know whether there is any point in
   5804      looking for the bug in the current version of `ld'.
   5805 
   5806    * Any patches you may have applied to the `ld' source, including any
   5807      patches made to the `BFD' library.
   5808 
   5809    * The type of machine you are using, and the operating system name
   5810      and version number.
   5811 
   5812    * What compiler (and its version) was used to compile `ld'--e.g.
   5813      "`gcc-2.7'".
   5814 
   5815    * The command arguments you gave the linker to link your example and
   5816      observe the bug.  To guarantee you will not omit something
   5817      important, list them all.  A copy of the Makefile (or the output
   5818      from make) is sufficient.
   5819 
   5820      If we were to try to guess the arguments, we would probably guess
   5821      wrong and then we might not encounter the bug.
   5822 
   5823    * A complete input file, or set of input files, that will reproduce
   5824      the bug.  It is generally most helpful to send the actual object
   5825      files provided that they are reasonably small.  Say no more than
   5826      10K.  For bigger files you can either make them available by FTP
   5827      or HTTP or else state that you are willing to send the object
   5828      file(s) to whomever requests them.  (Note - your email will be
   5829      going to a mailing list, so we do not want to clog it up with
   5830      large attachments).  But small attachments are best.
   5831 
   5832      If the source files were assembled using `gas' or compiled using
   5833      `gcc', then it may be OK to send the source files rather than the
   5834      object files.  In this case, be sure to say exactly what version of
   5835      `gas' or `gcc' was used to produce the object files.  Also say how
   5836      `gas' or `gcc' were configured.
   5837 
   5838    * A description of what behavior you observe that you believe is
   5839      incorrect.  For example, "It gets a fatal signal."
   5840 
   5841      Of course, if the bug is that `ld' gets a fatal signal, then we
   5842      will certainly notice it.  But if the bug is incorrect output, we
   5843      might not notice unless it is glaringly wrong.  You might as well
   5844      not give us a chance to make a mistake.
   5845 
   5846      Even if the problem you experience is a fatal signal, you should
   5847      still say so explicitly.  Suppose something strange is going on,
   5848      such as, your copy of `ld' is out of sync, or you have encountered
   5849      a bug in the C library on your system.  (This has happened!)  Your
   5850      copy might crash and ours would not.  If you told us to expect a
   5851      crash, then when ours fails to crash, we would know that the bug
   5852      was not happening for us.  If you had not told us to expect a
   5853      crash, then we would not be able to draw any conclusion from our
   5854      observations.
   5855 
   5856    * If you wish to suggest changes to the `ld' source, send us context
   5857      diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
   5858      Always send diffs from the old file to the new file.  If you even
   5859      discuss something in the `ld' source, refer to it by context, not
   5860      by line number.
   5861 
   5862      The line numbers in our development sources will not match those
   5863      in your sources.  Your line numbers would convey no useful
   5864      information to us.
   5865 
   5866    Here are some things that are not necessary:
   5867 
   5868    * A description of the envelope of the bug.
   5869 
   5870      Often people who encounter a bug spend a lot of time investigating
   5871      which changes to the input file will make the bug go away and which
   5872      changes will not affect it.
   5873 
   5874      This is often time consuming and not very useful, because the way
   5875      we will find the bug is by running a single example under the
   5876      debugger with breakpoints, not by pure deduction from a series of
   5877      examples.  We recommend that you save your time for something else.
   5878 
   5879      Of course, if you can find a simpler example to report _instead_
   5880      of the original one, that is a convenience for us.  Errors in the
   5881      output will be easier to spot, running under the debugger will take
   5882      less time, and so on.
   5883 
   5884      However, simplification is not vital; if you do not want to do
   5885      this, report the bug anyway and send us the entire test case you
   5886      used.
   5887 
   5888    * A patch for the bug.
   5889 
   5890      A patch for the bug does help us if it is a good one.  But do not
   5891      omit the necessary information, such as the test case, on the
   5892      assumption that a patch is all we need.  We might see problems
   5893      with your patch and decide to fix the problem another way, or we
   5894      might not understand it at all.
   5895 
   5896      Sometimes with a program as complicated as `ld' it is very hard to
   5897      construct an example that will make the program follow a certain
   5898      path through the code.  If you do not send us the example, we will
   5899      not be able to construct one, so we will not be able to verify
   5900      that the bug is fixed.
   5901 
   5902      And if we cannot understand what bug you are trying to fix, or why
   5903      your patch should be an improvement, we will not install it.  A
   5904      test case will help us to understand.
   5905 
   5906    * A guess about what the bug is or what it depends on.
   5907 
   5908      Such guesses are usually wrong.  Even we cannot guess right about
   5909      such things without first using the debugger to find the facts.
   5910 
   5911 
   5912 File: ld.info,  Node: MRI,  Next: GNU Free Documentation License,  Prev: Reporting Bugs,  Up: Top
   5913 
   5914 Appendix A MRI Compatible Script Files
   5915 **************************************
   5916 
   5917 To aid users making the transition to GNU `ld' from the MRI linker,
   5918 `ld' can use MRI compatible linker scripts as an alternative to the
   5919 more general-purpose linker scripting language described in *note
   5920 Scripts::.  MRI compatible linker scripts have a much simpler command
   5921 set than the scripting language otherwise used with `ld'.  GNU `ld'
   5922 supports the most commonly used MRI linker commands; these commands are
   5923 described here.
   5924 
   5925    In general, MRI scripts aren't of much use with the `a.out' object
   5926 file format, since it only has three sections and MRI scripts lack some
   5927 features to make use of them.
   5928 
   5929    You can specify a file containing an MRI-compatible script using the
   5930 `-c' command-line option.
   5931 
   5932    Each command in an MRI-compatible script occupies its own line; each
   5933 command line starts with the keyword that identifies the command (though
   5934 blank lines are also allowed for punctuation).  If a line of an
   5935 MRI-compatible script begins with an unrecognized keyword, `ld' issues
   5936 a warning message, but continues processing the script.
   5937 
   5938    Lines beginning with `*' are comments.
   5939 
   5940    You can write these commands using all upper-case letters, or all
   5941 lower case; for example, `chip' is the same as `CHIP'.  The following
   5942 list shows only the upper-case form of each command.
   5943 
   5944 `ABSOLUTE SECNAME'
   5945 `ABSOLUTE SECNAME, SECNAME, ... SECNAME'
   5946      Normally, `ld' includes in the output file all sections from all
   5947      the input files.  However, in an MRI-compatible script, you can
   5948      use the `ABSOLUTE' command to restrict the sections that will be
   5949      present in your output program.  If the `ABSOLUTE' command is used
   5950      at all in a script, then only the sections named explicitly in
   5951      `ABSOLUTE' commands will appear in the linker output.  You can
   5952      still use other input sections (whatever you select on the command
   5953      line, or using `LOAD') to resolve addresses in the output file.
   5954 
   5955 `ALIAS OUT-SECNAME, IN-SECNAME'
   5956      Use this command to place the data from input section IN-SECNAME
   5957      in a section called OUT-SECNAME in the linker output file.
   5958 
   5959      IN-SECNAME may be an integer.
   5960 
   5961 `ALIGN SECNAME = EXPRESSION'
   5962      Align the section called SECNAME to EXPRESSION.  The EXPRESSION
   5963      should be a power of two.
   5964 
   5965 `BASE EXPRESSION'
   5966      Use the value of EXPRESSION as the lowest address (other than
   5967      absolute addresses) in the output file.
   5968 
   5969 `CHIP EXPRESSION'
   5970 `CHIP EXPRESSION, EXPRESSION'
   5971      This command does nothing; it is accepted only for compatibility.
   5972 
   5973 `END'
   5974      This command does nothing whatever; it's only accepted for
   5975      compatibility.
   5976 
   5977 `FORMAT OUTPUT-FORMAT'
   5978      Similar to the `OUTPUT_FORMAT' command in the more general linker
   5979      language, but restricted to one of these output formats:
   5980 
   5981        1. S-records, if OUTPUT-FORMAT is `S'
   5982 
   5983        2. IEEE, if OUTPUT-FORMAT is `IEEE'
   5984 
   5985        3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
   5986           `COFF'
   5987 
   5988 `LIST ANYTHING...'
   5989      Print (to the standard output file) a link map, as produced by the
   5990      `ld' command-line option `-M'.
   5991 
   5992      The keyword `LIST' may be followed by anything on the same line,
   5993      with no change in its effect.
   5994 
   5995 `LOAD FILENAME'
   5996 `LOAD FILENAME, FILENAME, ... FILENAME'
   5997      Include one or more object file FILENAME in the link; this has the
   5998      same effect as specifying FILENAME directly on the `ld' command
   5999      line.
   6000 
   6001 `NAME OUTPUT-NAME'
   6002      OUTPUT-NAME is the name for the program produced by `ld'; the
   6003      MRI-compatible command `NAME' is equivalent to the command-line
   6004      option `-o' or the general script language command `OUTPUT'.
   6005 
   6006 `ORDER SECNAME, SECNAME, ... SECNAME'
   6007 `ORDER SECNAME SECNAME SECNAME'
   6008      Normally, `ld' orders the sections in its output file in the order
   6009      in which they first appear in the input files.  In an
   6010      MRI-compatible script, you can override this ordering with the
   6011      `ORDER' command.  The sections you list with `ORDER' will appear
   6012      first in your output file, in the order specified.
   6013 
   6014 `PUBLIC NAME=EXPRESSION'
   6015 `PUBLIC NAME,EXPRESSION'
   6016 `PUBLIC NAME EXPRESSION'
   6017      Supply a value (EXPRESSION) for external symbol NAME used in the
   6018      linker input files.
   6019 
   6020 `SECT SECNAME, EXPRESSION'
   6021 `SECT SECNAME=EXPRESSION'
   6022 `SECT SECNAME EXPRESSION'
   6023      You can use any of these three forms of the `SECT' command to
   6024      specify the start address (EXPRESSION) for section SECNAME.  If
   6025      you have more than one `SECT' statement for the same SECNAME, only
   6026      the _first_ sets the start address.
   6027 
   6028 
   6029 File: ld.info,  Node: GNU Free Documentation License,  Next: LD Index,  Prev: MRI,  Up: Top
   6030 
   6031 Appendix B GNU Free Documentation License
   6032 *****************************************
   6033 
   6034                         Version 1.1, March 2000
   6035 
   6036      Copyright (C) 2000, 2003 Free Software Foundation, Inc.
   6037      51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
   6038 
   6039      Everyone is permitted to copy and distribute verbatim copies
   6040      of this license document, but changing it is not allowed.
   6041 
   6042 
   6043   0. PREAMBLE
   6044 
   6045      The purpose of this License is to make a manual, textbook, or other
   6046      written document "free" in the sense of freedom: to assure everyone
   6047      the effective freedom to copy and redistribute it, with or without
   6048      modifying it, either commercially or noncommercially.  Secondarily,
   6049      this License preserves for the author and publisher a way to get
   6050      credit for their work, while not being considered responsible for
   6051      modifications made by others.
   6052 
   6053      This License is a kind of "copyleft", which means that derivative
   6054      works of the document must themselves be free in the same sense.
   6055      It complements the GNU General Public License, which is a copyleft
   6056      license designed for free software.
   6057 
   6058      We have designed this License in order to use it for manuals for
   6059      free software, because free software needs free documentation: a
   6060      free program should come with manuals providing the same freedoms
   6061      that the software does.  But this License is not limited to
   6062      software manuals; it can be used for any textual work, regardless
   6063      of subject matter or whether it is published as a printed book.
   6064      We recommend this License principally for works whose purpose is
   6065      instruction or reference.
   6066 
   6067 
   6068   1. APPLICABILITY AND DEFINITIONS
   6069 
   6070      This License applies to any manual or other work that contains a
   6071      notice placed by the copyright holder saying it can be distributed
   6072      under the terms of this License.  The "Document", below, refers to
   6073      any such manual or work.  Any member of the public is a licensee,
   6074      and is addressed as "you."
   6075 
   6076      A "Modified Version" of the Document means any work containing the
   6077      Document or a portion of it, either copied verbatim, or with
   6078      modifications and/or translated into another language.
   6079 
   6080      A "Secondary Section" is a named appendix or a front-matter
   6081      section of the Document that deals exclusively with the
   6082      relationship of the publishers or authors of the Document to the
   6083      Document's overall subject (or to related matters) and contains
   6084      nothing that could fall directly within that overall subject.
   6085      (For example, if the Document is in part a textbook of
   6086      mathematics, a Secondary Section may not explain any mathematics.)
   6087      The relationship could be a matter of historical connection with
   6088      the subject or with related matters, or of legal, commercial,
   6089      philosophical, ethical or political position regarding them.
   6090 
   6091      The "Invariant Sections" are certain Secondary Sections whose
   6092      titles are designated, as being those of Invariant Sections, in
   6093      the notice that says that the Document is released under this
   6094      License.
   6095 
   6096      The "Cover Texts" are certain short passages of text that are
   6097      listed, as Front-Cover Texts or Back-Cover Texts, in the notice
   6098      that says that the Document is released under this License.
   6099 
   6100      A "Transparent" copy of the Document means a machine-readable copy,
   6101      represented in a format whose specification is available to the
   6102      general public, whose contents can be viewed and edited directly
   6103      and straightforwardly with generic text editors or (for images
   6104      composed of pixels) generic paint programs or (for drawings) some
   6105      widely available drawing editor, and that is suitable for input to
   6106      text formatters or for automatic translation to a variety of
   6107      formats suitable for input to text formatters.  A copy made in an
   6108      otherwise Transparent file format whose markup has been designed
   6109      to thwart or discourage subsequent modification by readers is not
   6110      Transparent.  A copy that is not "Transparent" is called "Opaque."
   6111 
   6112      Examples of suitable formats for Transparent copies include plain
   6113      ASCII without markup, Texinfo input format, LaTeX input format,
   6114      SGML or XML using a publicly available DTD, and
   6115      standard-conforming simple HTML designed for human modification.
   6116      Opaque formats include PostScript, PDF, proprietary formats that
   6117      can be read and edited only by proprietary word processors, SGML
   6118      or XML for which the DTD and/or processing tools are not generally
   6119      available, and the machine-generated HTML produced by some word
   6120      processors for output purposes only.
   6121 
   6122      The "Title Page" means, for a printed book, the title page itself,
   6123      plus such following pages as are needed to hold, legibly, the
   6124      material this License requires to appear in the title page.  For
   6125      works in formats which do not have any title page as such, "Title
   6126      Page" means the text near the most prominent appearance of the
   6127      work's title, preceding the beginning of the body of the text.
   6128 
   6129   2. VERBATIM COPYING
   6130 
   6131      You may copy and distribute the Document in any medium, either
   6132      commercially or noncommercially, provided that this License, the
   6133      copyright notices, and the license notice saying this License
   6134      applies to the Document are reproduced in all copies, and that you
   6135      add no other conditions whatsoever to those of this License.  You
   6136      may not use technical measures to obstruct or control the reading
   6137      or further copying of the copies you make or distribute.  However,
   6138      you may accept compensation in exchange for copies.  If you
   6139      distribute a large enough number of copies you must also follow
   6140      the conditions in section 3.
   6141 
   6142      You may also lend copies, under the same conditions stated above,
   6143      and you may publicly display copies.
   6144 
   6145   3. COPYING IN QUANTITY
   6146 
   6147      If you publish printed copies of the Document numbering more than
   6148      100, and the Document's license notice requires Cover Texts, you
   6149      must enclose the copies in covers that carry, clearly and legibly,
   6150      all these Cover Texts: Front-Cover Texts on the front cover, and
   6151      Back-Cover Texts on the back cover.  Both covers must also clearly
   6152      and legibly identify you as the publisher of these copies.  The
   6153      front cover must present the full title with all words of the
   6154      title equally prominent and visible.  You may add other material
   6155      on the covers in addition.  Copying with changes limited to the
   6156      covers, as long as they preserve the title of the Document and
   6157      satisfy these conditions, can be treated as verbatim copying in
   6158      other respects.
   6159 
   6160      If the required texts for either cover are too voluminous to fit
   6161      legibly, you should put the first ones listed (as many as fit
   6162      reasonably) on the actual cover, and continue the rest onto
   6163      adjacent pages.
   6164 
   6165      If you publish or distribute Opaque copies of the Document
   6166      numbering more than 100, you must either include a
   6167      machine-readable Transparent copy along with each Opaque copy, or
   6168      state in or with each Opaque copy a publicly-accessible
   6169      computer-network location containing a complete Transparent copy
   6170      of the Document, free of added material, which the general
   6171      network-using public has access to download anonymously at no
   6172      charge using public-standard network protocols.  If you use the
   6173      latter option, you must take reasonably prudent steps, when you
   6174      begin distribution of Opaque copies in quantity, to ensure that
   6175      this Transparent copy will remain thus accessible at the stated
   6176      location until at least one year after the last time you
   6177      distribute an Opaque copy (directly or through your agents or
   6178      retailers) of that edition to the public.
   6179 
   6180      It is requested, but not required, that you contact the authors of
   6181      the Document well before redistributing any large number of
   6182      copies, to give them a chance to provide you with an updated
   6183      version of the Document.
   6184 
   6185   4. MODIFICATIONS
   6186 
   6187      You may copy and distribute a Modified Version of the Document
   6188      under the conditions of sections 2 and 3 above, provided that you
   6189      release the Modified Version under precisely this License, with
   6190      the Modified Version filling the role of the Document, thus
   6191      licensing distribution and modification of the Modified Version to
   6192      whoever possesses a copy of it.  In addition, you must do these
   6193      things in the Modified Version:
   6194 
   6195      A. Use in the Title Page (and on the covers, if any) a title
   6196      distinct    from that of the Document, and from those of previous
   6197      versions    (which should, if there were any, be listed in the
   6198      History section    of the Document).  You may use the same title
   6199      as a previous version    if the original publisher of that version
   6200      gives permission.
   6201      B. List on the Title Page, as authors, one or more persons or
   6202      entities    responsible for authorship of the modifications in the
   6203      Modified    Version, together with at least five of the principal
   6204      authors of the    Document (all of its principal authors, if it
   6205      has less than five).
   6206      C. State on the Title page the name of the publisher of the
   6207      Modified Version, as the publisher.
   6208      D. Preserve all the copyright notices of the Document.
   6209      E. Add an appropriate copyright notice for your modifications
   6210      adjacent to the other copyright notices.
   6211      F. Include, immediately after the copyright notices, a license
   6212      notice    giving the public permission to use the Modified Version
   6213      under the    terms of this License, in the form shown in the
   6214      Addendum below.
   6215      G. Preserve in that license notice the full lists of Invariant
   6216      Sections    and required Cover Texts given in the Document's
   6217      license notice.
   6218      H. Include an unaltered copy of this License.
   6219      I. Preserve the section entitled "History", and its title, and add
   6220      to    it an item stating at least the title, year, new authors, and
   6221        publisher of the Modified Version as given on the Title Page.  If
   6222        there is no section entitled "History" in the Document, create
   6223      one    stating the title, year, authors, and publisher of the
   6224      Document as    given on its Title Page, then add an item
   6225      describing the Modified    Version as stated in the previous
   6226      sentence.
   6227      J. Preserve the network location, if any, given in the Document for
   6228        public access to a Transparent copy of the Document, and likewise
   6229        the network locations given in the Document for previous versions
   6230        it was based on.  These may be placed in the "History" section.
   6231        You may omit a network location for a work that was published at
   6232        least four years before the Document itself, or if the original
   6233       publisher of the version it refers to gives permission.
   6234      K. In any section entitled "Acknowledgements" or "Dedications",
   6235      preserve the section's title, and preserve in the section all the
   6236       substance and tone of each of the contributor acknowledgements
   6237      and/or dedications given therein.
   6238      L. Preserve all the Invariant Sections of the Document,
   6239      unaltered in their text and in their titles.  Section numbers
   6240      or the equivalent are not considered part of the section titles.
   6241      M. Delete any section entitled "Endorsements."  Such a section
   6242      may not be included in the Modified Version.
   6243      N. Do not retitle any existing section as "Endorsements"    or to
   6244      conflict in title with any Invariant Section.
   6245 
   6246      If the Modified Version includes new front-matter sections or
   6247      appendices that qualify as Secondary Sections and contain no
   6248      material copied from the Document, you may at your option
   6249      designate some or all of these sections as invariant.  To do this,
   6250      add their titles to the list of Invariant Sections in the Modified
   6251      Version's license notice.  These titles must be distinct from any
   6252      other section titles.
   6253 
   6254      You may add a section entitled "Endorsements", provided it contains
   6255      nothing but endorsements of your Modified Version by various
   6256      parties-for example, statements of peer review or that the text has
   6257      been approved by an organization as the authoritative definition
   6258      of a standard.
   6259 
   6260      You may add a passage of up to five words as a Front-Cover Text,
   6261      and a passage of up to 25 words as a Back-Cover Text, to the end
   6262      of the list of Cover Texts in the Modified Version.  Only one
   6263      passage of Front-Cover Text and one of Back-Cover Text may be
   6264      added by (or through arrangements made by) any one entity.  If the
   6265      Document already includes a cover text for the same cover,
   6266      previously added by you or by arrangement made by the same entity
   6267      you are acting on behalf of, you may not add another; but you may
   6268      replace the old one, on explicit permission from the previous
   6269      publisher that added the old one.
   6270 
   6271      The author(s) and publisher(s) of the Document do not by this
   6272      License give permission to use their names for publicity for or to
   6273      assert or imply endorsement of any Modified Version.
   6274 
   6275   5. COMBINING DOCUMENTS
   6276 
   6277      You may combine the Document with other documents released under
   6278      this License, under the terms defined in section 4 above for
   6279      modified versions, provided that you include in the combination
   6280      all of the Invariant Sections of all of the original documents,
   6281      unmodified, and list them all as Invariant Sections of your
   6282      combined work in its license notice.
   6283 
   6284      The combined work need only contain one copy of this License, and
   6285      multiple identical Invariant Sections may be replaced with a single
   6286      copy.  If there are multiple Invariant Sections with the same name
   6287      but different contents, make the title of each such section unique
   6288      by adding at the end of it, in parentheses, the name of the
   6289      original author or publisher of that section if known, or else a
   6290      unique number.  Make the same adjustment to the section titles in
   6291      the list of Invariant Sections in the license notice of the
   6292      combined work.
   6293 
   6294      In the combination, you must combine any sections entitled
   6295      "History" in the various original documents, forming one section
   6296      entitled "History"; likewise combine any sections entitled
   6297      "Acknowledgements", and any sections entitled "Dedications."  You
   6298      must delete all sections entitled "Endorsements."
   6299 
   6300   6. COLLECTIONS OF DOCUMENTS
   6301 
   6302      You may make a collection consisting of the Document and other
   6303      documents released under this License, and replace the individual
   6304      copies of this License in the various documents with a single copy
   6305      that is included in the collection, provided that you follow the
   6306      rules of this License for verbatim copying of each of the
   6307      documents in all other respects.
   6308 
   6309      You may extract a single document from such a collection, and
   6310      distribute it individually under this License, provided you insert
   6311      a copy of this License into the extracted document, and follow
   6312      this License in all other respects regarding verbatim copying of
   6313      that document.
   6314 
   6315   7. AGGREGATION WITH INDEPENDENT WORKS
   6316 
   6317      A compilation of the Document or its derivatives with other
   6318      separate and independent documents or works, in or on a volume of
   6319      a storage or distribution medium, does not as a whole count as a
   6320      Modified Version of the Document, provided no compilation
   6321      copyright is claimed for the compilation.  Such a compilation is
   6322      called an "aggregate", and this License does not apply to the
   6323      other self-contained works thus compiled with the Document, on
   6324      account of their being thus compiled, if they are not themselves
   6325      derivative works of the Document.
   6326 
   6327      If the Cover Text requirement of section 3 is applicable to these
   6328      copies of the Document, then if the Document is less than one
   6329      quarter of the entire aggregate, the Document's Cover Texts may be
   6330      placed on covers that surround only the Document within the
   6331      aggregate.  Otherwise they must appear on covers around the whole
   6332      aggregate.
   6333 
   6334   8. TRANSLATION
   6335 
   6336      Translation is considered a kind of modification, so you may
   6337      distribute translations of the Document under the terms of section
   6338      4.  Replacing Invariant Sections with translations requires special
   6339      permission from their copyright holders, but you may include
   6340      translations of some or all Invariant Sections in addition to the
   6341      original versions of these Invariant Sections.  You may include a
   6342      translation of this License provided that you also include the
   6343      original English version of this License.  In case of a
   6344      disagreement between the translation and the original English
   6345      version of this License, the original English version will prevail.
   6346 
   6347   9. TERMINATION
   6348 
   6349      You may not copy, modify, sublicense, or distribute the Document
   6350      except as expressly provided for under this License.  Any other
   6351      attempt to copy, modify, sublicense or distribute the Document is
   6352      void, and will automatically terminate your rights under this
   6353      License.  However, parties who have received copies, or rights,
   6354      from you under this License will not have their licenses
   6355      terminated so long as such parties remain in full compliance.
   6356 
   6357  10. FUTURE REVISIONS OF THIS LICENSE
   6358 
   6359      The Free Software Foundation may publish new, revised versions of
   6360      the GNU Free Documentation License from time to time.  Such new
   6361      versions will be similar in spirit to the present version, but may
   6362      differ in detail to address new problems or concerns.  See
   6363      http://www.gnu.org/copyleft/.
   6364 
   6365      Each version of the License is given a distinguishing version
   6366      number.  If the Document specifies that a particular numbered
   6367      version of this License "or any later version" applies to it, you
   6368      have the option of following the terms and conditions either of
   6369      that specified version or of any later version that has been
   6370      published (not as a draft) by the Free Software Foundation.  If
   6371      the Document does not specify a version number of this License,
   6372      you may choose any version ever published (not as a draft) by the
   6373      Free Software Foundation.
   6374 
   6375 
   6376 ADDENDUM: How to use this License for your documents
   6377 ====================================================
   6378 
   6379 To use this License in a document you have written, include a copy of
   6380 the License in the document and put the following copyright and license
   6381 notices just after the title page:
   6382 
   6383      Copyright (C)  YEAR  YOUR NAME.
   6384      Permission is granted to copy, distribute and/or modify this document
   6385      under the terms of the GNU Free Documentation License, Version 1.1
   6386      or any later version published by the Free Software Foundation;
   6387      with the Invariant Sections being LIST THEIR TITLES, with the
   6388      Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
   6389      A copy of the license is included in the section entitled "GNU
   6390      Free Documentation License."
   6391 
   6392    If you have no Invariant Sections, write "with no Invariant Sections"
   6393 instead of saying which ones are invariant.  If you have no Front-Cover
   6394 Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
   6395 LIST"; likewise for Back-Cover Texts.
   6396 
   6397    If your document contains nontrivial examples of program code, we
   6398 recommend releasing these examples in parallel under your choice of
   6399 free software license, such as the GNU General Public License, to
   6400 permit their use in free software.
   6401 
   6402 
   6403 File: ld.info,  Node: LD Index,  Prev: GNU Free Documentation License,  Up: Top
   6404 
   6405 LD Index
   6406 ********
   6407 
   6408 [index]
   6409 * Menu:
   6410 
   6411 * ":                                     Symbols.            (line    6)
   6412 * -(:                                    Options.            (line  645)
   6413 * --accept-unknown-input-arch:           Options.            (line  663)
   6414 * --add-needed:                          Options.            (line  685)
   6415 * --add-stdcall-alias:                   Options.            (line 1470)
   6416 * --allow-multiple-definition:           Options.            (line  910)
   6417 * --allow-shlib-undefined:               Options.            (line  916)
   6418 * --architecture=ARCH:                   Options.            (line  106)
   6419 * --as-needed:                           Options.            (line  673)
   6420 * --auxiliary:                           Options.            (line  207)
   6421 * --bank-window:                         Options.            (line 1815)
   6422 * --base-file:                           Options.            (line 1475)
   6423 * --be8:                                 ARM.                (line   23)
   6424 * --bss-plt:                             PowerPC ELF32.      (line   13)
   6425 * --build-id:                            Options.            (line 1432)
   6426 * --build-id=STYLE:                      Options.            (line 1432)
   6427 * --check-sections:                      Options.            (line  767)
   6428 * --cref:                                Options.            (line  777)
   6429 * --default-imported-symver:             Options.            (line  944)
   6430 * --default-script=SCRIPT:               Options.            (line  490)
   6431 * --default-symver:                      Options.            (line  940)
   6432 * --defsym SYMBOL=EXP:                   Options.            (line  805)
   6433 * --demangle[=STYLE]:                    Options.            (line  818)
   6434 * --disable-auto-image-base:             Options.            (line 1622)
   6435 * --disable-auto-import:                 Options.            (line 1757)
   6436 * --disable-new-dtags:                   Options.            (line 1395)
   6437 * --disable-runtime-pseudo-reloc:        Options.            (line 1770)
   6438 * --disable-stdcall-fixup:               Options.            (line 1485)
   6439 * --discard-all:                         Options.            (line  536)
   6440 * --discard-locals:                      Options.            (line  540)
   6441 * --dll:                                 Options.            (line 1480)
   6442 * --dll-search-prefix:                   Options.            (line 1628)
   6443 * --dotsyms:                             PowerPC64 ELF64.    (line   33)
   6444 * --dynamic-linker FILE:                 Options.            (line  831)
   6445 * --dynamic-list-cpp-new:                Options.            (line  759)
   6446 * --dynamic-list-cpp-typeinfo:           Options.            (line  763)
   6447 * --dynamic-list-data:                   Options.            (line  756)
   6448 * --dynamic-list=DYNAMIC-LIST-FILE:      Options.            (line  743)
   6449 * --eh-frame-hdr:                        Options.            (line 1391)
   6450 * --emit-relocs:                         Options.            (line  425)
   6451 * --emit-stack-syms:                     SPU ELF.            (line   46)
   6452 * --emit-stub-syms <1>:                  SPU ELF.            (line   15)
   6453 * --emit-stub-syms <2>:                  PowerPC64 ELF64.    (line   29)
   6454 * --emit-stub-syms:                      PowerPC ELF32.      (line   44)
   6455 * --enable-auto-image-base:              Options.            (line 1614)
   6456 * --enable-auto-import:                  Options.            (line 1637)
   6457 * --enable-extra-pe-debug:               Options.            (line 1775)
   6458 * --enable-new-dtags:                    Options.            (line 1395)
   6459 * --enable-runtime-pseudo-reloc:         Options.            (line 1762)
   6460 * --enable-stdcall-fixup:                Options.            (line 1485)
   6461 * --entry=ENTRY:                         Options.            (line  160)
   6462 * --error-unresolved-symbols:            Options.            (line 1344)
   6463 * --exclude-libs:                        Options.            (line  170)
   6464 * --exclude-symbols:                     Options.            (line 1527)
   6465 * --export-all-symbols:                  Options.            (line 1503)
   6466 * --export-dynamic:                      Options.            (line  181)
   6467 * --extra-overlay-stubs:                 SPU ELF.            (line   19)
   6468 * --fatal-warnings:                      Options.            (line  837)
   6469 * --file-alignment:                      Options.            (line 1533)
   6470 * --filter:                              Options.            (line  228)
   6471 * --fix-cortex-a8:                       i960.               (line   39)
   6472 * --fix-v4bx:                            ARM.                (line   44)
   6473 * --fix-v4bx-interworking:               ARM.                (line   57)
   6474 * --force-dynamic:                       Options.            (line  434)
   6475 * --force-exe-suffix:                    Options.            (line  842)
   6476 * --format=FORMAT:                       Options.            (line  117)
   6477 * --format=VERSION:                      TI COFF.            (line    6)
   6478 * --gc-sections:                         Options.            (line  852)
   6479 * --got:                                 Options.            (line 1828)
   6480 * --got=TYPE:                            M68K.               (line    6)
   6481 * --gpsize:                              Options.            (line  261)
   6482 * --hash-size=NUMBER:                    Options.            (line 1404)
   6483 * --hash-style=STYLE:                    Options.            (line 1412)
   6484 * --heap:                                Options.            (line 1539)
   6485 * --help:                                Options.            (line  883)
   6486 * --image-base:                          Options.            (line 1546)
   6487 * --just-symbols=FILE:                   Options.            (line  457)
   6488 * --kill-at:                             Options.            (line 1555)
   6489 * --large-address-aware:                 Options.            (line 1560)
   6490 * --library-path=DIR:                    Options.            (line  320)
   6491 * --library=NAMESPEC:                    Options.            (line  287)
   6492 * --local-store=lo:hi:                   SPU ELF.            (line   24)
   6493 * --major-image-version:                 Options.            (line 1569)
   6494 * --major-os-version:                    Options.            (line 1574)
   6495 * --major-subsystem-version:             Options.            (line 1578)
   6496 * --minor-image-version:                 Options.            (line 1583)
   6497 * --minor-os-version:                    Options.            (line 1588)
   6498 * --minor-subsystem-version:             Options.            (line 1592)
   6499 * --mri-script=MRI-CMDFILE:              Options.            (line  141)
   6500 * --multi-subspace:                      HPPA ELF32.         (line    6)
   6501 * --nmagic:                              Options.            (line  389)
   6502 * --no-accept-unknown-input-arch:        Options.            (line  663)
   6503 * --no-add-needed:                       Options.            (line  685)
   6504 * --no-allow-shlib-undefined:            Options.            (line  916)
   6505 * --no-as-needed:                        Options.            (line  673)
   6506 * --no-check-sections:                   Options.            (line  767)
   6507 * --no-define-common:                    Options.            (line  789)
   6508 * --no-demangle:                         Options.            (line  818)
   6509 * --no-dotsyms:                          PowerPC64 ELF64.    (line   33)
   6510 * --no-enum-size-warning:                ARM.                (line  106)
   6511 * --no-fatal-warnings:                   Options.            (line  837)
   6512 * --no-fix-cortex-a8:                    i960.               (line   39)
   6513 * --no-gc-sections:                      Options.            (line  852)
   6514 * --no-keep-memory:                      Options.            (line  895)
   6515 * --no-multi-toc:                        PowerPC64 ELF64.    (line   74)
   6516 * --no-omagic:                           Options.            (line  403)
   6517 * --no-opd-optimize:                     PowerPC64 ELF64.    (line   48)
   6518 * --no-overlays:                         SPU ELF.            (line    9)
   6519 * --no-print-gc-sections:                Options.            (line  874)
   6520 * --no-relax:                            Xtensa.             (line   56)
   6521 * --no-tls-optimize <1>:                 PowerPC64 ELF64.    (line   43)
   6522 * --no-tls-optimize:                     PowerPC ELF32.      (line   48)
   6523 * --no-toc-optimize:                     PowerPC64 ELF64.    (line   60)
   6524 * --no-trampoline:                       Options.            (line 1809)
   6525 * --no-undefined:                        Options.            (line  902)
   6526 * --no-undefined-version:                Options.            (line  935)
   6527 * --no-warn-mismatch:                    Options.            (line  948)
   6528 * --no-warn-search-mismatch:             Options.            (line  957)
   6529 * --no-wchar-size-warning:               ARM.                (line  113)
   6530 * --no-whole-archive:                    Options.            (line  961)
   6531 * --noinhibit-exec:                      Options.            (line  965)
   6532 * --non-overlapping-opd:                 PowerPC64 ELF64.    (line   54)
   6533 * --oformat:                             Options.            (line  977)
   6534 * --omagic:                              Options.            (line  394)
   6535 * --out-implib:                          Options.            (line 1605)
   6536 * --output-def:                          Options.            (line 1597)
   6537 * --output=OUTPUT:                       Options.            (line  409)
   6538 * --pic-executable:                      Options.            (line  990)
   6539 * --pic-veneer:                          ARM.                (line  119)
   6540 * --plugin:                              SPU ELF.            (line    6)
   6541 * --print-gc-sections:                   Options.            (line  874)
   6542 * --print-map:                           Options.            (line  352)
   6543 * --reduce-memory-overheads:             Options.            (line 1418)
   6544 * --relax:                               Options.            (line 1006)
   6545 * --relax on i960:                       i960.               (line   31)
   6546 * --relax on PowerPC:                    PowerPC ELF32.      (line    6)
   6547 * --relax on Xtensa:                     Xtensa.             (line   27)
   6548 * --relocatable:                         Options.            (line  438)
   6549 * --script=SCRIPT:                       Options.            (line  481)
   6550 * --sdata-got:                           PowerPC ELF32.      (line   30)
   6551 * --section-alignment:                   Options.            (line 1780)
   6552 * --section-start SECTIONNAME=ORG:       Options.            (line 1181)
   6553 * --secure-plt:                          PowerPC ELF32.      (line   23)
   6554 * --sort-common:                         Options.            (line 1126)
   6555 * --sort-section alignment:              Options.            (line 1138)
   6556 * --sort-section name:                   Options.            (line 1134)
   6557 * --split-by-file:                       Options.            (line 1142)
   6558 * --split-by-reloc:                      Options.            (line 1147)
   6559 * --stack:                               Options.            (line 1786)
   6560 * --stack-analysis:                      SPU ELF.            (line   29)
   6561 * --stats:                               Options.            (line 1160)
   6562 * --strip-all:                           Options.            (line  468)
   6563 * --strip-debug:                         Options.            (line  472)
   6564 * --stub-group-size:                     PowerPC64 ELF64.    (line    6)
   6565 * --stub-group-size=N <1>:               HPPA ELF32.         (line   12)
   6566 * --stub-group-size=N:                   ARM.                (line  124)
   6567 * --subsystem:                           Options.            (line 1793)
   6568 * --support-old-code:                    ARM.                (line    6)
   6569 * --sysroot:                             Options.            (line 1164)
   6570 * --target-help:                         Options.            (line  887)
   6571 * --target1-abs:                         ARM.                (line   27)
   6572 * --target1-rel:                         ARM.                (line   27)
   6573 * --target2=TYPE:                        ARM.                (line   32)
   6574 * --thumb-entry=ENTRY:                   ARM.                (line   17)
   6575 * --trace:                               Options.            (line  477)
   6576 * --trace-symbol=SYMBOL:                 Options.            (line  546)
   6577 * --traditional-format:                  Options.            (line 1169)
   6578 * --undefined=SYMBOL:                    Options.            (line  503)
   6579 * --unique[=SECTION]:                    Options.            (line  521)
   6580 * --unresolved-symbols:                  Options.            (line 1196)
   6581 * --use-blx:                             ARM.                (line   69)
   6582 * --verbose:                             Options.            (line 1225)
   6583 * --version:                             Options.            (line  530)
   6584 * --version-script=VERSION-SCRIPTFILE:   Options.            (line 1231)
   6585 * --vfp11-denorm-fix:                    ARM.                (line   78)
   6586 * --warn-common:                         Options.            (line 1238)
   6587 * --warn-constructors:                   Options.            (line 1306)
   6588 * --warn-multiple-gp:                    Options.            (line 1311)
   6589 * --warn-once:                           Options.            (line 1325)
   6590 * --warn-section-align:                  Options.            (line 1329)
   6591 * --warn-shared-textrel:                 Options.            (line 1336)
   6592 * --warn-unresolved-symbols:             Options.            (line 1339)
   6593 * --whole-archive:                       Options.            (line 1348)
   6594 * --wrap:                                Options.            (line 1362)
   6595 * -AARCH:                                Options.            (line  105)
   6596 * -aKEYWORD:                             Options.            (line   98)
   6597 * -assert KEYWORD:                       Options.            (line  695)
   6598 * -b FORMAT:                             Options.            (line  117)
   6599 * -Bdynamic:                             Options.            (line  698)
   6600 * -Bgroup:                               Options.            (line  708)
   6601 * -Bshareable:                           Options.            (line 1118)
   6602 * -Bstatic:                              Options.            (line  715)
   6603 * -Bsymbolic:                            Options.            (line  730)
   6604 * -Bsymbolic-functions:                  Options.            (line  737)
   6605 * -c MRI-CMDFILE:                        Options.            (line  141)
   6606 * -call_shared:                          Options.            (line  698)
   6607 * -d:                                    Options.            (line  151)
   6608 * -dc:                                   Options.            (line  151)
   6609 * -dn:                                   Options.            (line  715)
   6610 * -dp:                                   Options.            (line  151)
   6611 * -dT SCRIPT:                            Options.            (line  490)
   6612 * -dy:                                   Options.            (line  698)
   6613 * -E:                                    Options.            (line  181)
   6614 * -e ENTRY:                              Options.            (line  160)
   6615 * -EB:                                   Options.            (line  200)
   6616 * -EL:                                   Options.            (line  203)
   6617 * -F:                                    Options.            (line  228)
   6618 * -f:                                    Options.            (line  207)
   6619 * -fini:                                 Options.            (line  252)
   6620 * -G:                                    Options.            (line  261)
   6621 * -g:                                    Options.            (line  258)
   6622 * -hNAME:                                Options.            (line  269)
   6623 * -i:                                    Options.            (line  278)
   6624 * -IFILE:                                Options.            (line  831)
   6625 * -init:                                 Options.            (line  281)
   6626 * -LDIR:                                 Options.            (line  320)
   6627 * -lNAMESPEC:                            Options.            (line  287)
   6628 * -M:                                    Options.            (line  352)
   6629 * -m EMULATION:                          Options.            (line  342)
   6630 * -Map:                                  Options.            (line  891)
   6631 * -N:                                    Options.            (line  394)
   6632 * -n:                                    Options.            (line  389)
   6633 * -non_shared:                           Options.            (line  715)
   6634 * -nostdlib:                             Options.            (line  971)
   6635 * -O LEVEL:                              Options.            (line  415)
   6636 * -o OUTPUT:                             Options.            (line  409)
   6637 * -pie:                                  Options.            (line  990)
   6638 * -q:                                    Options.            (line  425)
   6639 * -qmagic:                               Options.            (line 1000)
   6640 * -Qy:                                   Options.            (line 1003)
   6641 * -r:                                    Options.            (line  438)
   6642 * -R FILE:                               Options.            (line  457)
   6643 * -rpath:                                Options.            (line 1041)
   6644 * -rpath-link:                           Options.            (line 1063)
   6645 * -S:                                    Options.            (line  472)
   6646 * -s:                                    Options.            (line  468)
   6647 * -shared:                               Options.            (line 1118)
   6648 * -soname=NAME:                          Options.            (line  269)
   6649 * -static:                               Options.            (line  715)
   6650 * -t:                                    Options.            (line  477)
   6651 * -T SCRIPT:                             Options.            (line  481)
   6652 * -Tbss ORG:                             Options.            (line 1190)
   6653 * -Tdata ORG:                            Options.            (line 1190)
   6654 * -Ttext ORG:                            Options.            (line 1190)
   6655 * -u SYMBOL:                             Options.            (line  503)
   6656 * -Ur:                                   Options.            (line  511)
   6657 * -V:                                    Options.            (line  530)
   6658 * -v:                                    Options.            (line  530)
   6659 * -X:                                    Options.            (line  540)
   6660 * -x:                                    Options.            (line  536)
   6661 * -Y PATH:                               Options.            (line  555)
   6662 * -y SYMBOL:                             Options.            (line  546)
   6663 * -z defs:                               Options.            (line  902)
   6664 * -z KEYWORD:                            Options.            (line  559)
   6665 * -z muldefs:                            Options.            (line  910)
   6666 * .:                                     Location Counter.   (line    6)
   6667 * /DISCARD/:                             Output Section Discarding.
   6668                                                              (line   21)
   6669 * :PHDR:                                 Output Section Phdr.
   6670                                                              (line    6)
   6671 * =FILLEXP:                              Output Section Fill.
   6672                                                              (line    6)
   6673 * >REGION:                               Output Section Region.
   6674                                                              (line    6)
   6675 * [COMMON]:                              Input Section Common.
   6676                                                              (line   29)
   6677 * ABSOLUTE (MRI):                        MRI.                (line   33)
   6678 * absolute and relocatable symbols:      Expression Section. (line    6)
   6679 * absolute expressions:                  Expression Section. (line    6)
   6680 * ABSOLUTE(EXP):                         Builtin Functions.  (line   10)
   6681 * ADDR(SECTION):                         Builtin Functions.  (line   17)
   6682 * address, section:                      Output Section Address.
   6683                                                              (line    6)
   6684 * ALIAS (MRI):                           MRI.                (line   44)
   6685 * ALIGN (MRI):                           MRI.                (line   50)
   6686 * align expression:                      Builtin Functions.  (line   36)
   6687 * align location counter:                Builtin Functions.  (line   36)
   6688 * ALIGN(ALIGN):                          Builtin Functions.  (line   36)
   6689 * ALIGN(EXP,ALIGN):                      Builtin Functions.  (line   36)
   6690 * ALIGN(SECTION_ALIGN):                  Forced Output Alignment.
   6691                                                              (line    6)
   6692 * ALIGNOF(SECTION):                      Builtin Functions.  (line   61)
   6693 * allocating memory:                     MEMORY.             (line    6)
   6694 * architecture:                          Miscellaneous Commands.
   6695                                                              (line   72)
   6696 * architectures:                         Options.            (line  105)
   6697 * archive files, from cmd line:          Options.            (line  287)
   6698 * archive search path in linker script:  File Commands.      (line   74)
   6699 * arithmetic:                            Expressions.        (line    6)
   6700 * arithmetic operators:                  Operators.          (line    6)
   6701 * ARM interworking support:              ARM.                (line    6)
   6702 * AS_NEEDED(FILES):                      File Commands.      (line   54)
   6703 * ASSERT:                                Miscellaneous Commands.
   6704                                                              (line    9)
   6705 * assertion in linker script:            Miscellaneous Commands.
   6706                                                              (line    9)
   6707 * assignment in scripts:                 Assignments.        (line    6)
   6708 * AT(LMA):                               Output Section LMA. (line    6)
   6709 * AT>LMA_REGION:                         Output Section LMA. (line    6)
   6710 * automatic data imports:                WIN32.              (line  170)
   6711 * back end:                              BFD.                (line    6)
   6712 * BASE (MRI):                            MRI.                (line   54)
   6713 * BE8:                                   ARM.                (line   23)
   6714 * BFD canonical format:                  Canonical format.   (line   11)
   6715 * BFD requirements:                      BFD.                (line   16)
   6716 * big-endian objects:                    Options.            (line  200)
   6717 * binary input format:                   Options.            (line  117)
   6718 * BLOCK(EXP):                            Builtin Functions.  (line   74)
   6719 * bug criteria:                          Bug Criteria.       (line    6)
   6720 * bug reports:                           Bug Reporting.      (line    6)
   6721 * bugs in ld:                            Reporting Bugs.     (line    6)
   6722 * BYTE(EXPRESSION):                      Output Section Data.
   6723                                                              (line    6)
   6724 * C++ constructors, arranging in link:   Output Section Keywords.
   6725                                                              (line   19)
   6726 * CHIP (MRI):                            MRI.                (line   58)
   6727 * COLLECT_NO_DEMANGLE:                   Environment.        (line   29)
   6728 * combining symbols, warnings on:        Options.            (line 1238)
   6729 * command files:                         Scripts.            (line    6)
   6730 * command line:                          Options.            (line    6)
   6731 * common allocation:                     Options.            (line  151)
   6732 * common allocation in linker script:    Miscellaneous Commands.
   6733                                                              (line   20)
   6734 * common symbol placement:               Input Section Common.
   6735                                                              (line    6)
   6736 * compatibility, MRI:                    Options.            (line  141)
   6737 * constants in linker scripts:           Constants.          (line    6)
   6738 * CONSTRUCTORS:                          Output Section Keywords.
   6739                                                              (line   19)
   6740 * constructors:                          Options.            (line  511)
   6741 * constructors, arranging in link:       Output Section Keywords.
   6742                                                              (line   19)
   6743 * Cortex-A8 erratum workaround:          i960.               (line   39)
   6744 * crash of linker:                       Bug Criteria.       (line    9)
   6745 * CREATE_OBJECT_SYMBOLS:                 Output Section Keywords.
   6746                                                              (line    9)
   6747 * creating a DEF file:                   WIN32.              (line  137)
   6748 * cross reference table:                 Options.            (line  777)
   6749 * cross references:                      Miscellaneous Commands.
   6750                                                              (line   56)
   6751 * current output location:               Location Counter.   (line    6)
   6752 * data:                                  Output Section Data.
   6753                                                              (line    6)
   6754 * DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions.
   6755                                                              (line   79)
   6756 * DATA_SEGMENT_END(EXP):                 Builtin Functions.  (line  100)
   6757 * DATA_SEGMENT_RELRO_END(OFFSET, EXP):   Builtin Functions.  (line  106)
   6758 * dbx:                                   Options.            (line 1174)
   6759 * DEF files, creating:                   Options.            (line 1597)
   6760 * default emulation:                     Environment.        (line   21)
   6761 * default input format:                  Environment.        (line    9)
   6762 * DEFINED(SYMBOL):                       Builtin Functions.  (line  117)
   6763 * deleting local symbols:                Options.            (line  536)
   6764 * demangling, default:                   Environment.        (line   29)
   6765 * demangling, from command line:         Options.            (line  818)
   6766 * direct linking to a dll:               WIN32.              (line  218)
   6767 * discarding sections:                   Output Section Discarding.
   6768                                                              (line    6)
   6769 * discontinuous memory:                  MEMORY.             (line    6)
   6770 * DLLs, creating:                        Options.            (line 1503)
   6771 * DLLs, linking to:                      Options.            (line 1628)
   6772 * dot:                                   Location Counter.   (line    6)
   6773 * dot inside sections:                   Location Counter.   (line   36)
   6774 * dot outside sections:                  Location Counter.   (line   66)
   6775 * dynamic linker, from command line:     Options.            (line  831)
   6776 * dynamic symbol table:                  Options.            (line  181)
   6777 * ELF program headers:                   PHDRS.              (line    6)
   6778 * emulation:                             Options.            (line  342)
   6779 * emulation, default:                    Environment.        (line   21)
   6780 * END (MRI):                             MRI.                (line   62)
   6781 * endianness:                            Options.            (line  200)
   6782 * entry point:                           Entry Point.        (line    6)
   6783 * entry point, from command line:        Options.            (line  160)
   6784 * entry point, thumb:                    ARM.                (line   17)
   6785 * ENTRY(SYMBOL):                         Entry Point.        (line    6)
   6786 * error on valid input:                  Bug Criteria.       (line   12)
   6787 * example of linker script:              Simple Example.     (line    6)
   6788 * exporting DLL symbols:                 WIN32.              (line   19)
   6789 * expression evaluation order:           Evaluation.         (line    6)
   6790 * expression sections:                   Expression Section. (line    6)
   6791 * expression, absolute:                  Builtin Functions.  (line   10)
   6792 * expressions:                           Expressions.        (line    6)
   6793 * EXTERN:                                Miscellaneous Commands.
   6794                                                              (line   13)
   6795 * fatal signal:                          Bug Criteria.       (line    9)
   6796 * file name wildcard patterns:           Input Section Wildcards.
   6797                                                              (line    6)
   6798 * FILEHDR:                               PHDRS.              (line   61)
   6799 * filename symbols:                      Output Section Keywords.
   6800                                                              (line    9)
   6801 * fill pattern, entire section:          Output Section Fill.
   6802                                                              (line    6)
   6803 * FILL(EXPRESSION):                      Output Section Data.
   6804                                                              (line   39)
   6805 * finalization function:                 Options.            (line  252)
   6806 * first input file:                      File Commands.      (line   82)
   6807 * first instruction:                     Entry Point.        (line    6)
   6808 * FIX_V4BX:                              ARM.                (line   44)
   6809 * FIX_V4BX_INTERWORKING:                 ARM.                (line   57)
   6810 * FORCE_COMMON_ALLOCATION:               Miscellaneous Commands.
   6811                                                              (line   20)
   6812 * forcing input section alignment:       Forced Input Alignment.
   6813                                                              (line    6)
   6814 * forcing output section alignment:      Forced Output Alignment.
   6815                                                              (line    6)
   6816 * forcing the creation of dynamic sections: Options.         (line  434)
   6817 * FORMAT (MRI):                          MRI.                (line   66)
   6818 * functions in expressions:              Builtin Functions.  (line    6)
   6819 * garbage collection <1>:                Input Section Keep. (line    6)
   6820 * garbage collection:                    Options.            (line  852)
   6821 * generating optimized output:           Options.            (line  415)
   6822 * GNU linker:                            Overview.           (line    6)
   6823 * GNUTARGET:                             Environment.        (line    9)
   6824 * GROUP(FILES):                          File Commands.      (line   47)
   6825 * grouping input files:                  File Commands.      (line   47)
   6826 * groups of archives:                    Options.            (line  645)
   6827 * H8/300 support:                        H8/300.             (line    6)
   6828 * header size:                           Builtin Functions.  (line  182)
   6829 * heap size:                             Options.            (line 1539)
   6830 * help:                                  Options.            (line  883)
   6831 * holes:                                 Location Counter.   (line   12)
   6832 * holes, filling:                        Output Section Data.
   6833                                                              (line   39)
   6834 * HPPA multiple sub-space stubs:         HPPA ELF32.         (line    6)
   6835 * HPPA stub grouping:                    HPPA ELF32.         (line   12)
   6836 * i960 support:                          i960.               (line    6)
   6837 * image base:                            Options.            (line 1546)
   6838 * implicit linker scripts:               Implicit Linker Scripts.
   6839                                                              (line    6)
   6840 * import libraries:                      WIN32.              (line   10)
   6841 * INCLUDE FILENAME:                      File Commands.      (line    9)
   6842 * including a linker script:             File Commands.      (line    9)
   6843 * including an entire archive:           Options.            (line 1348)
   6844 * incremental link:                      Options.            (line  278)
   6845 * INHIBIT_COMMON_ALLOCATION:             Miscellaneous Commands.
   6846                                                              (line   25)
   6847 * initialization function:               Options.            (line  281)
   6848 * initialized data in ROM:               Output Section LMA. (line   26)
   6849 * input file format in linker script:    Format Commands.    (line   35)
   6850 * input filename symbols:                Output Section Keywords.
   6851                                                              (line    9)
   6852 * input files in linker scripts:         File Commands.      (line   19)
   6853 * input files, displaying:               Options.            (line  477)
   6854 * input format:                          Options.            (line  117)
   6855 * input object files in linker scripts:  File Commands.      (line   19)
   6856 * input section alignment:               Forced Input Alignment.
   6857                                                              (line    6)
   6858 * input section basics:                  Input Section Basics.
   6859                                                              (line    6)
   6860 * input section wildcards:               Input Section Wildcards.
   6861                                                              (line    6)
   6862 * input sections:                        Input Section.      (line    6)
   6863 * INPUT(FILES):                          File Commands.      (line   19)
   6864 * INSERT:                                Miscellaneous Commands.
   6865                                                              (line   30)
   6866 * insert user script into default script: Miscellaneous Commands.
   6867                                                              (line   30)
   6868 * integer notation:                      Constants.          (line    6)
   6869 * integer suffixes:                      Constants.          (line   12)
   6870 * internal object-file format:           Canonical format.   (line   11)
   6871 * invalid input:                         Bug Criteria.       (line   14)
   6872 * K and M integer suffixes:              Constants.          (line   12)
   6873 * KEEP:                                  Input Section Keep. (line    6)
   6874 * l =:                                   MEMORY.             (line   72)
   6875 * lazy evaluation:                       Evaluation.         (line    6)
   6876 * ld bugs, reporting:                    Bug Reporting.      (line    6)
   6877 * LDEMULATION:                           Environment.        (line   21)
   6878 * len =:                                 MEMORY.             (line   72)
   6879 * LENGTH =:                              MEMORY.             (line   72)
   6880 * LENGTH(MEMORY):                        Builtin Functions.  (line  134)
   6881 * library search path in linker script:  File Commands.      (line   74)
   6882 * link map:                              Options.            (line  352)
   6883 * link-time runtime library search path: Options.            (line 1063)
   6884 * linker crash:                          Bug Criteria.       (line    9)
   6885 * linker script concepts:                Basic Script Concepts.
   6886                                                              (line    6)
   6887 * linker script example:                 Simple Example.     (line    6)
   6888 * linker script file commands:           File Commands.      (line    6)
   6889 * linker script format:                  Script Format.      (line    6)
   6890 * linker script input object files:      File Commands.      (line   19)
   6891 * linker script simple commands:         Simple Commands.    (line    6)
   6892 * linker scripts:                        Scripts.            (line    6)
   6893 * LIST (MRI):                            MRI.                (line   77)
   6894 * little-endian objects:                 Options.            (line  203)
   6895 * LOAD (MRI):                            MRI.                (line   84)
   6896 * load address:                          Output Section LMA. (line    6)
   6897 * LOADADDR(SECTION):                     Builtin Functions.  (line  137)
   6898 * loading, preventing:                   Output Section Type.
   6899                                                              (line   22)
   6900 * local symbols, deleting:               Options.            (line  540)
   6901 * location counter:                      Location Counter.   (line    6)
   6902 * LONG(EXPRESSION):                      Output Section Data.
   6903                                                              (line    6)
   6904 * M and K integer suffixes:              Constants.          (line   12)
   6905 * M68HC11 and 68HC12 support:            M68HC11/68HC12.     (line    6)
   6906 * machine architecture:                  Miscellaneous Commands.
   6907                                                              (line   72)
   6908 * machine dependencies:                  Machine Dependent.  (line    6)
   6909 * mapping input sections to output sections: Input Section.  (line    6)
   6910 * MAX:                                   Builtin Functions.  (line  142)
   6911 * MEMORY:                                MEMORY.             (line    6)
   6912 * memory region attributes:              MEMORY.             (line   32)
   6913 * memory regions:                        MEMORY.             (line    6)
   6914 * memory regions and sections:           Output Section Region.
   6915                                                              (line    6)
   6916 * memory usage:                          Options.            (line  895)
   6917 * MIN:                                   Builtin Functions.  (line  145)
   6918 * Motorola 68K GOT generation:           M68K.               (line    6)
   6919 * MRI compatibility:                     MRI.                (line    6)
   6920 * MSP430 extra sections:                 MSP430.             (line   11)
   6921 * NAME (MRI):                            MRI.                (line   90)
   6922 * name, section:                         Output Section Name.
   6923                                                              (line    6)
   6924 * names:                                 Symbols.            (line    6)
   6925 * naming the output file:                Options.            (line  409)
   6926 * NEXT(EXP):                             Builtin Functions.  (line  149)
   6927 * NMAGIC:                                Options.            (line  389)
   6928 * NO_ENUM_SIZE_WARNING:                  ARM.                (line  106)
   6929 * NO_WCHAR_SIZE_WARNING:                 ARM.                (line  113)
   6930 * NOCROSSREFS(SECTIONS):                 Miscellaneous Commands.
   6931                                                              (line   56)
   6932 * NOLOAD:                                Output Section Type.
   6933                                                              (line   22)
   6934 * not enough room for program headers:   Builtin Functions.  (line  187)
   6935 * o =:                                   MEMORY.             (line   67)
   6936 * objdump -i:                            BFD.                (line    6)
   6937 * object file management:                BFD.                (line    6)
   6938 * object files:                          Options.            (line   29)
   6939 * object formats available:              BFD.                (line    6)
   6940 * object size:                           Options.            (line  261)
   6941 * OMAGIC:                                Options.            (line  394)
   6942 * opening object files:                  BFD outline.        (line    6)
   6943 * operators for arithmetic:              Operators.          (line    6)
   6944 * options:                               Options.            (line    6)
   6945 * ORDER (MRI):                           MRI.                (line   95)
   6946 * org =:                                 MEMORY.             (line   67)
   6947 * ORIGIN =:                              MEMORY.             (line   67)
   6948 * ORIGIN(MEMORY):                        Builtin Functions.  (line  155)
   6949 * orphan:                                Orphan Sections.    (line    6)
   6950 * output file after errors:              Options.            (line  965)
   6951 * output file format in linker script:   Format Commands.    (line   10)
   6952 * output file name in linker script:     File Commands.      (line   64)
   6953 * output section alignment:              Forced Output Alignment.
   6954                                                              (line    6)
   6955 * output section attributes:             Output Section Attributes.
   6956                                                              (line    6)
   6957 * output section data:                   Output Section Data.
   6958                                                              (line    6)
   6959 * OUTPUT(FILENAME):                      File Commands.      (line   64)
   6960 * OUTPUT_ARCH(BFDARCH):                  Miscellaneous Commands.
   6961                                                              (line   72)
   6962 * OUTPUT_FORMAT(BFDNAME):                Format Commands.    (line   10)
   6963 * OVERLAY:                               Overlay Description.
   6964                                                              (line    6)
   6965 * overlays:                              Overlay Description.
   6966                                                              (line    6)
   6967 * partial link:                          Options.            (line  438)
   6968 * PHDRS:                                 PHDRS.              (line    6)
   6969 * PIC_VENEER:                            ARM.                (line  119)
   6970 * position independent executables:      Options.            (line  992)
   6971 * PowerPC ELF32 options:                 PowerPC ELF32.      (line   13)
   6972 * PowerPC GOT:                           PowerPC ELF32.      (line   30)
   6973 * PowerPC long branches:                 PowerPC ELF32.      (line    6)
   6974 * PowerPC PLT:                           PowerPC ELF32.      (line   13)
   6975 * PowerPC stub symbols:                  PowerPC ELF32.      (line   44)
   6976 * PowerPC TLS optimization:              PowerPC ELF32.      (line   48)
   6977 * PowerPC64 dot symbols:                 PowerPC64 ELF64.    (line   33)
   6978 * PowerPC64 ELF64 options:               PowerPC64 ELF64.    (line    6)
   6979 * PowerPC64 multi-TOC:                   PowerPC64 ELF64.    (line   74)
   6980 * PowerPC64 OPD optimization:            PowerPC64 ELF64.    (line   48)
   6981 * PowerPC64 OPD spacing:                 PowerPC64 ELF64.    (line   54)
   6982 * PowerPC64 stub grouping:               PowerPC64 ELF64.    (line    6)
   6983 * PowerPC64 stub symbols:                PowerPC64 ELF64.    (line   29)
   6984 * PowerPC64 TLS optimization:            PowerPC64 ELF64.    (line   43)
   6985 * PowerPC64 TOC optimization:            PowerPC64 ELF64.    (line   60)
   6986 * precedence in expressions:             Operators.          (line    6)
   6987 * prevent unnecessary loading:           Output Section Type.
   6988                                                              (line   22)
   6989 * program headers:                       PHDRS.              (line    6)
   6990 * program headers and sections:          Output Section Phdr.
   6991                                                              (line    6)
   6992 * program headers, not enough room:      Builtin Functions.  (line  187)
   6993 * program segments:                      PHDRS.              (line    6)
   6994 * PROVIDE:                               PROVIDE.            (line    6)
   6995 * PROVIDE_HIDDEN:                        PROVIDE_HIDDEN.     (line    6)
   6996 * PUBLIC (MRI):                          MRI.                (line  103)
   6997 * QUAD(EXPRESSION):                      Output Section Data.
   6998                                                              (line    6)
   6999 * quoted symbol names:                   Symbols.            (line    6)
   7000 * read-only text:                        Options.            (line  389)
   7001 * read/write from cmd line:              Options.            (line  394)
   7002 * regions of memory:                     MEMORY.             (line    6)
   7003 * relative expressions:                  Expression Section. (line    6)
   7004 * relaxing addressing modes:             Options.            (line 1006)
   7005 * relaxing on H8/300:                    H8/300.             (line    9)
   7006 * relaxing on i960:                      i960.               (line   31)
   7007 * relaxing on M68HC11:                   M68HC11/68HC12.     (line   12)
   7008 * relaxing on Xtensa:                    Xtensa.             (line   27)
   7009 * relocatable and absolute symbols:      Expression Section. (line    6)
   7010 * relocatable output:                    Options.            (line  438)
   7011 * removing sections:                     Output Section Discarding.
   7012                                                              (line    6)
   7013 * reporting bugs in ld:                  Reporting Bugs.     (line    6)
   7014 * requirements for BFD:                  BFD.                (line   16)
   7015 * retain relocations in final executable: Options.           (line  425)
   7016 * retaining specified symbols:           Options.            (line 1027)
   7017 * ROM initialized data:                  Output Section LMA. (line   26)
   7018 * round up expression:                   Builtin Functions.  (line   36)
   7019 * round up location counter:             Builtin Functions.  (line   36)
   7020 * runtime library name:                  Options.            (line  269)
   7021 * runtime library search path:           Options.            (line 1041)
   7022 * runtime pseudo-relocation:             WIN32.              (line  196)
   7023 * scaled integers:                       Constants.          (line   12)
   7024 * scommon section:                       Input Section Common.
   7025                                                              (line   20)
   7026 * script files:                          Options.            (line  481)
   7027 * scripts:                               Scripts.            (line    6)
   7028 * search directory, from cmd line:       Options.            (line  320)
   7029 * search path in linker script:          File Commands.      (line   74)
   7030 * SEARCH_DIR(PATH):                      File Commands.      (line   74)
   7031 * SECT (MRI):                            MRI.                (line  109)
   7032 * section address:                       Output Section Address.
   7033                                                              (line    6)
   7034 * section address in expression:         Builtin Functions.  (line   17)
   7035 * section alignment:                     Builtin Functions.  (line   61)
   7036 * section alignment, warnings on:        Options.            (line 1329)
   7037 * section data:                          Output Section Data.
   7038                                                              (line    6)
   7039 * section fill pattern:                  Output Section Fill.
   7040                                                              (line    6)
   7041 * section load address:                  Output Section LMA. (line    6)
   7042 * section load address in expression:    Builtin Functions.  (line  137)
   7043 * section name:                          Output Section Name.
   7044                                                              (line    6)
   7045 * section name wildcard patterns:        Input Section Wildcards.
   7046                                                              (line    6)
   7047 * section size:                          Builtin Functions.  (line  166)
   7048 * section, assigning to memory region:   Output Section Region.
   7049                                                              (line    6)
   7050 * section, assigning to program header:  Output Section Phdr.
   7051                                                              (line    6)
   7052 * SECTIONS:                              SECTIONS.           (line    6)
   7053 * sections, discarding:                  Output Section Discarding.
   7054                                                              (line    6)
   7055 * segment origins, cmd line:             Options.            (line 1190)
   7056 * SEGMENT_START(SEGMENT, DEFAULT):       Builtin Functions.  (line  158)
   7057 * segments, ELF:                         PHDRS.              (line    6)
   7058 * shared libraries:                      Options.            (line 1120)
   7059 * SHORT(EXPRESSION):                     Output Section Data.
   7060                                                              (line    6)
   7061 * SIZEOF(SECTION):                       Builtin Functions.  (line  166)
   7062 * SIZEOF_HEADERS:                        Builtin Functions.  (line  182)
   7063 * small common symbols:                  Input Section Common.
   7064                                                              (line   20)
   7065 * SORT:                                  Input Section Wildcards.
   7066                                                              (line   58)
   7067 * SORT_BY_ALIGNMENT:                     Input Section Wildcards.
   7068                                                              (line   54)
   7069 * SORT_BY_NAME:                          Input Section Wildcards.
   7070                                                              (line   46)
   7071 * SPU:                                   SPU ELF.            (line   29)
   7072 * SPU ELF options:                       SPU ELF.            (line    6)
   7073 * SPU extra overlay stubs:               SPU ELF.            (line   19)
   7074 * SPU local store size:                  SPU ELF.            (line   24)
   7075 * SPU overlay stub symbols:              SPU ELF.            (line   15)
   7076 * SPU overlays:                          SPU ELF.            (line    9)
   7077 * SPU plugins:                           SPU ELF.            (line    6)
   7078 * SQUAD(EXPRESSION):                     Output Section Data.
   7079                                                              (line    6)
   7080 * stack size:                            Options.            (line 1786)
   7081 * standard Unix system:                  Options.            (line    7)
   7082 * start of execution:                    Entry Point.        (line    6)
   7083 * STARTUP(FILENAME):                     File Commands.      (line   82)
   7084 * strip all symbols:                     Options.            (line  468)
   7085 * strip debugger symbols:                Options.            (line  472)
   7086 * stripping all but some symbols:        Options.            (line 1027)
   7087 * STUB_GROUP_SIZE:                       ARM.                (line  124)
   7088 * SUBALIGN(SUBSECTION_ALIGN):            Forced Input Alignment.
   7089                                                              (line    6)
   7090 * suffixes for integers:                 Constants.          (line   12)
   7091 * symbol defaults:                       Builtin Functions.  (line  117)
   7092 * symbol definition, scripts:            Assignments.        (line    6)
   7093 * symbol names:                          Symbols.            (line    6)
   7094 * symbol tracing:                        Options.            (line  546)
   7095 * symbol versions:                       VERSION.            (line    6)
   7096 * symbol-only input:                     Options.            (line  457)
   7097 * symbols, from command line:            Options.            (line  805)
   7098 * symbols, relocatable and absolute:     Expression Section. (line    6)
   7099 * symbols, retaining selectively:        Options.            (line 1027)
   7100 * synthesizing linker:                   Options.            (line 1006)
   7101 * synthesizing on H8/300:                H8/300.             (line   14)
   7102 * TARGET(BFDNAME):                       Format Commands.    (line   35)
   7103 * TARGET1:                               ARM.                (line   27)
   7104 * TARGET2:                               ARM.                (line   32)
   7105 * thumb entry point:                     ARM.                (line   17)
   7106 * TI COFF versions:                      TI COFF.            (line    6)
   7107 * traditional format:                    Options.            (line 1169)
   7108 * trampoline generation on M68HC11:      M68HC11/68HC12.     (line   31)
   7109 * trampoline generation on M68HC12:      M68HC11/68HC12.     (line   31)
   7110 * unallocated address, next:             Builtin Functions.  (line  149)
   7111 * undefined symbol:                      Options.            (line  503)
   7112 * undefined symbol in linker script:     Miscellaneous Commands.
   7113                                                              (line   13)
   7114 * undefined symbols, warnings on:        Options.            (line 1325)
   7115 * uninitialized data placement:          Input Section Common.
   7116                                                              (line    6)
   7117 * unspecified memory:                    Output Section Data.
   7118                                                              (line   39)
   7119 * usage:                                 Options.            (line  883)
   7120 * USE_BLX:                               ARM.                (line   69)
   7121 * using a DEF file:                      WIN32.              (line   42)
   7122 * using auto-export functionality:       WIN32.              (line   22)
   7123 * Using decorations:                     WIN32.              (line  141)
   7124 * variables, defining:                   Assignments.        (line    6)
   7125 * verbose:                               Options.            (line 1225)
   7126 * version:                               Options.            (line  530)
   7127 * version script:                        VERSION.            (line    6)
   7128 * version script, symbol versions:       Options.            (line 1231)
   7129 * VERSION {script text}:                 VERSION.            (line    6)
   7130 * versions of symbols:                   VERSION.            (line    6)
   7131 * VFP11_DENORM_FIX:                      ARM.                (line   78)
   7132 * warnings, on combining symbols:        Options.            (line 1238)
   7133 * warnings, on section alignment:        Options.            (line 1329)
   7134 * warnings, on undefined symbols:        Options.            (line 1325)
   7135 * weak externals:                        WIN32.              (line  386)
   7136 * what is this?:                         Overview.           (line    6)
   7137 * wildcard file name patterns:           Input Section Wildcards.
   7138                                                              (line    6)
   7139 * Xtensa options:                        Xtensa.             (line   56)
   7140 * Xtensa processors:                     Xtensa.             (line    6)
   7141 
   7142 
   7143 
   7144 Tag Table:
   7145 Node: Top830
   7146 Node: Overview1601
   7147 Node: Invocation2715
   7148 Node: Options3123
   7149 Node: Environment85587
   7150 Node: Scripts87347
   7151 Node: Basic Script Concepts89081
   7152 Node: Script Format91788
   7153 Node: Simple Example92651
   7154 Node: Simple Commands95747
   7155 Node: Entry Point96198
   7156 Node: File Commands96957
   7157 Node: Format Commands100958
   7158 Node: Miscellaneous Commands102924
   7159 Node: Assignments106303
   7160 Node: Simple Assignments106794
   7161 Node: PROVIDE108530
   7162 Node: PROVIDE_HIDDEN109735
   7163 Node: Source Code Reference109979
   7164 Node: SECTIONS113559
   7165 Node: Output Section Description115450
   7166 Node: Output Section Name116503
   7167 Node: Output Section Address117379
   7168 Node: Input Section119028
   7169 Node: Input Section Basics119829
   7170 Node: Input Section Wildcards123047
   7171 Node: Input Section Common127780
   7172 Node: Input Section Keep129262
   7173 Node: Input Section Example129752
   7174 Node: Output Section Data130720
   7175 Node: Output Section Keywords133497
   7176 Node: Output Section Discarding137066
   7177 Node: Output Section Attributes138247
   7178 Node: Output Section Type139250
   7179 Node: Output Section LMA140404
   7180 Node: Forced Output Alignment142917
   7181 Node: Forced Input Alignment143185
   7182 Node: Output Section Region143570
   7183 Node: Output Section Phdr144000
   7184 Node: Output Section Fill144664
   7185 Node: Overlay Description145806
   7186 Node: MEMORY150108
   7187 Node: PHDRS154307
   7188 Node: VERSION159346
   7189 Node: Expressions167138
   7190 Node: Constants168016
   7191 Node: Symbols168577
   7192 Node: Orphan Sections169315
   7193 Node: Location Counter170479
   7194 Node: Operators174915
   7195 Node: Evaluation175837
   7196 Node: Expression Section177201
   7197 Node: Builtin Functions178690
   7198 Node: Implicit Linker Scripts186652
   7199 Node: Machine Dependent187427
   7200 Node: H8/300188443
   7201 Node: i960190068
   7202 Node: M68HC11/68HC12192169
   7203 Node: ARM193623
   7204 Node: HPPA ELF32200872
   7205 Node: M68K202495
   7206 Node: MMIX203404
   7207 Node: MSP430204569
   7208 Node: PowerPC ELF32205618
   7209 Node: PowerPC64 ELF64208232
   7210 Node: SPU ELF212648
   7211 Node: TI COFF215280
   7212 Node: WIN32215806
   7213 Node: Xtensa234163
   7214 Node: BFD237285
   7215 Node: BFD outline238740
   7216 Node: BFD information loss240026
   7217 Node: Canonical format242543
   7218 Node: Reporting Bugs246900
   7219 Node: Bug Criteria247594
   7220 Node: Bug Reporting248293
   7221 Node: MRI255332
   7222 Node: GNU Free Documentation License259975
   7223 Node: LD Index279680
   7224 
   7225 End Tag Table
   7226