+++ /dev/null
-This is ld.info, produced by makeinfo version 4.8 from ld.texinfo.
-
-START-INFO-DIR-ENTRY
-* Ld: (ld). The GNU linker.
-END-INFO-DIR-ENTRY
-
- This file documents the GNU linker LD (GNU Binutils) version 2.17.90.
-
- Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
-\1f
-File: ld.info, Node: Top, Next: Overview, Up: (dir)
-
-LD
-**
-
-This file documents the GNU linker ld (GNU Binutils) version 2.17.90.
-
- This document is distributed under the terms of the GNU Free
-Documentation License. A copy of the license is included in the
-section entitled "GNU Free Documentation License".
-
-* Menu:
-
-* Overview:: Overview
-* Invocation:: Invocation
-* Scripts:: Linker Scripts
-
-* Machine Dependent:: Machine Dependent Features
-
-* BFD:: BFD
-
-* Reporting Bugs:: Reporting Bugs
-* MRI:: MRI Compatible Script Files
-* GNU Free Documentation License:: GNU Free Documentation License
-* LD Index:: LD Index
-
-\1f
-File: ld.info, Node: Overview, Next: Invocation, Prev: Top, Up: Top
-
-1 Overview
-**********
-
-`ld' combines a number of object and archive files, relocates their
-data and ties up symbol references. Usually the last step in compiling
-a program is to run `ld'.
-
- `ld' accepts Linker Command Language files written in a superset of
-AT&T's Link Editor Command Language syntax, to provide explicit and
-total control over the linking process.
-
- This version of `ld' uses the general purpose BFD libraries to
-operate on object files. This allows `ld' to read, combine, and write
-object files in many different formats--for example, COFF or `a.out'.
-Different formats may be linked together to produce any available kind
-of object file. *Note BFD::, for more information.
-
- Aside from its flexibility, the GNU linker is more helpful than other
-linkers in providing diagnostic information. Many linkers abandon
-execution immediately upon encountering an error; whenever possible,
-`ld' continues executing, allowing you to identify other errors (or, in
-some cases, to get an output file in spite of the error).
-
-\1f
-File: ld.info, Node: Invocation, Next: Scripts, Prev: Overview, Up: Top
-
-2 Invocation
-************
-
-The GNU linker `ld' is meant to cover a broad range of situations, and
-to be as compatible as possible with other linkers. As a result, you
-have many choices to control its behavior.
-
-* Menu:
-
-* Options:: Command Line Options
-* Environment:: Environment Variables
-
-\1f
-File: ld.info, Node: Options, Next: Environment, Up: Invocation
-
-2.1 Command Line Options
-========================
-
- The linker supports a plethora of command-line options, but in actual
-practice few of them are used in any particular context. For instance,
-a frequent use of `ld' is to link standard Unix object files on a
-standard, supported Unix system. On such a system, to link a file
-`hello.o':
-
- ld -o OUTPUT /lib/crt0.o hello.o -lc
-
- This tells `ld' to produce a file called OUTPUT as the result of
-linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
-which will come from the standard search directories. (See the
-discussion of the `-l' option below.)
-
- Some of the command-line options to `ld' may be specified at any
-point in the command line. However, options which refer to files, such
-as `-l' or `-T', cause the file to be read at the point at which the
-option appears in the command line, relative to the object files and
-other file options. Repeating non-file options with a different
-argument will either have no further effect, or override prior
-occurrences (those further to the left on the command line) of that
-option. Options which may be meaningfully specified more than once are
-noted in the descriptions below.
-
- Non-option arguments are object files or archives which are to be
-linked together. They may follow, precede, or be mixed in with
-command-line options, except that an object file argument may not be
-placed between an option and its argument.
-
- Usually the linker is invoked with at least one object file, but you
-can specify other forms of binary input files using `-l', `-R', and the
-script command language. If _no_ binary input files at all are
-specified, the linker does not produce any output, and issues the
-message `No input files'.
-
- If the linker cannot recognize the format of an object file, it will
-assume that it is a linker script. A script specified in this way
-augments the main linker script used for the link (either the default
-linker script or the one specified by using `-T'). This feature
-permits the linker to link against a file which appears to be an object
-or an archive, but actually merely defines some symbol values, or uses
-`INPUT' or `GROUP' to load other objects. Note that specifying a
-script in this way merely augments the main linker script; use the `-T'
-option to replace the default linker script entirely. *Note Scripts::.
-
- For options whose names are a single letter, option arguments must
-either follow the option letter without intervening whitespace, or be
-given as separate arguments immediately following the option that
-requires them.
-
- For options whose names are multiple letters, either one dash or two
-can precede the option name; for example, `-trace-symbol' and
-`--trace-symbol' are equivalent. Note--there is one exception to this
-rule. Multiple letter options that start with a lower case 'o' can
-only be preceded by two dashes. This is to reduce confusion with the
-`-o' option. So for example `-omagic' sets the output file name to
-`magic' whereas `--omagic' sets the NMAGIC flag on the output.
-
- Arguments to multiple-letter options must either be separated from
-the option name by an equals sign, or be given as separate arguments
-immediately following the option that requires them. For example,
-`--trace-symbol foo' and `--trace-symbol=foo' are equivalent. Unique
-abbreviations of the names of multiple-letter options are accepted.
-
- Note--if the linker is being invoked indirectly, via a compiler
-driver (e.g. `gcc') then all the linker command line options should be
-prefixed by `-Wl,' (or whatever is appropriate for the particular
-compiler driver) like this:
-
- gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
-
- This is important, because otherwise the compiler driver program may
-silently drop the linker options, resulting in a bad link.
-
- Here is a table of the generic command line switches accepted by the
-GNU linker:
-
-`@FILE'
- Read command-line options from FILE. The options read are
- inserted in place of the original @FILE option. If FILE does not
- exist, or cannot be read, then the option will be treated
- literally, and not removed.
-
- Options in FILE are separated by whitespace. A whitespace
- character may be included in an option by surrounding the entire
- option in either single or double quotes. Any character
- (including a backslash) may be included by prefixing the character
- to be included with a backslash. The FILE may itself contain
- additional @FILE options; any such options will be processed
- recursively.
-
-`-aKEYWORD'
- This option is supported for HP/UX compatibility. The KEYWORD
- argument must be one of the strings `archive', `shared', or
- `default'. `-aarchive' is functionally equivalent to `-Bstatic',
- and the other two keywords are functionally equivalent to
- `-Bdynamic'. This option may be used any number of times.
-
-`-AARCHITECTURE'
-`--architecture=ARCHITECTURE'
- In the current release of `ld', this option is useful only for the
- Intel 960 family of architectures. In that `ld' configuration, the
- ARCHITECTURE argument identifies the particular architecture in
- the 960 family, enabling some safeguards and modifying the
- archive-library search path. *Note `ld' and the Intel 960 family:
- i960, for details.
-
- Future releases of `ld' may support similar functionality for
- other architecture families.
-
-`-b INPUT-FORMAT'
-`--format=INPUT-FORMAT'
- `ld' may be configured to support more than one kind of object
- file. If your `ld' is configured this way, you can use the `-b'
- option to specify the binary format for input object files that
- follow this option on the command line. Even when `ld' is
- configured to support alternative object formats, you don't
- usually need to specify this, as `ld' should be configured to
- expect as a default input format the most usual format on each
- machine. INPUT-FORMAT is a text string, the name of a particular
- format supported by the BFD libraries. (You can list the
- available binary formats with `objdump -i'.) *Note BFD::.
-
- You may want to use this option if you are linking files with an
- unusual binary format. You can also use `-b' to switch formats
- explicitly (when linking object files of different formats), by
- including `-b INPUT-FORMAT' before each group of object files in a
- particular format.
-
- The default format is taken from the environment variable
- `GNUTARGET'. *Note Environment::. You can also define the input
- format from a script, using the command `TARGET'; see *Note Format
- Commands::.
-
-`-c MRI-COMMANDFILE'
-`--mri-script=MRI-COMMANDFILE'
- For compatibility with linkers produced by MRI, `ld' accepts script
- files written in an alternate, restricted command language,
- described in *Note MRI Compatible Script Files: MRI. Introduce
- MRI script files with the option `-c'; use the `-T' option to run
- linker scripts written in the general-purpose `ld' scripting
- language. If MRI-CMDFILE does not exist, `ld' looks for it in the
- directories specified by any `-L' options.
-
-`-d'
-`-dc'
-`-dp'
- These three options are equivalent; multiple forms are supported
- for compatibility with other linkers. They assign space to common
- symbols even if a relocatable output file is specified (with
- `-r'). The script command `FORCE_COMMON_ALLOCATION' has the same
- effect. *Note Miscellaneous Commands::.
-
-`-e ENTRY'
-`--entry=ENTRY'
- Use ENTRY as the explicit symbol for beginning execution of your
- program, rather than the default entry point. If there is no
- symbol named ENTRY, the linker will try to parse ENTRY as a number,
- and use that as the entry address (the number will be interpreted
- in base 10; you may use a leading `0x' for base 16, or a leading
- `0' for base 8). *Note Entry Point::, for a discussion of defaults
- and other ways of specifying the entry point.
-
-`--exclude-libs LIB,LIB,...'
- Specifies a list of archive libraries from which symbols should
- not be automatically exported. The library names may be delimited
- by commas or colons. Specifying `--exclude-libs ALL' excludes
- symbols in all archive libraries from automatic export. This
- option is available only for the i386 PE targeted port of the
- linker and for ELF targeted ports. For i386 PE, symbols
- explicitly listed in a .def file are still exported, regardless of
- this option. For ELF targeted ports, symbols affected by this
- option will be treated as hidden.
-
-`-E'
-`--export-dynamic'
- When creating a dynamically linked executable, add all symbols to
- the dynamic symbol table. The dynamic symbol table is the set of
- symbols which are visible from dynamic objects at run time.
-
- If you do not use this option, the dynamic symbol table will
- normally contain only those symbols which are referenced by some
- dynamic object mentioned in the link.
-
- If you use `dlopen' to load a dynamic object which needs to refer
- back to the symbols defined by the program, rather than some other
- dynamic object, then you will probably need to use this option when
- linking the program itself.
-
- You can also use the dynamic list to control what symbols should
- be added to the dynamic symbol table if the output format supports
- it. See the description of `--dynamic-list'.
-
-`-EB'
- Link big-endian objects. This affects the default output format.
-
-`-EL'
- Link little-endian objects. This affects the default output
- format.
-
-`-f'
-`--auxiliary NAME'
- When creating an ELF shared object, set the internal DT_AUXILIARY
- field to the specified name. This tells the dynamic linker that
- the symbol table of the shared object should be used as an
- auxiliary filter on the symbol table of the shared object NAME.
-
- If you later link a program against this filter object, then, when
- you run the program, the dynamic linker will see the DT_AUXILIARY
- field. If the dynamic linker resolves any symbols from the filter
- object, it will first check whether there is a definition in the
- shared object NAME. If there is one, it will be used instead of
- the definition in the filter object. The shared object NAME need
- not exist. Thus the shared object NAME may be used to provide an
- alternative implementation of certain functions, perhaps for
- debugging or for machine specific performance.
-
- This option may be specified more than once. The DT_AUXILIARY
- entries will be created in the order in which they appear on the
- command line.
-
-`-F NAME'
-`--filter NAME'
- When creating an ELF shared object, set the internal DT_FILTER
- field to the specified name. This tells the dynamic linker that
- the symbol table of the shared object which is being created
- should be used as a filter on the symbol table of the shared
- object NAME.
-
- If you later link a program against this filter object, then, when
- you run the program, the dynamic linker will see the DT_FILTER
- field. The dynamic linker will resolve symbols according to the
- symbol table of the filter object as usual, but it will actually
- link to the definitions found in the shared object NAME. Thus the
- filter object can be used to select a subset of the symbols
- provided by the object NAME.
-
- Some older linkers used the `-F' option throughout a compilation
- toolchain for specifying object-file format for both input and
- output object files. The GNU linker uses other mechanisms for
- this purpose: the `-b', `--format', `--oformat' options, the
- `TARGET' command in linker scripts, and the `GNUTARGET'
- environment variable. The GNU linker will ignore the `-F' option
- when not creating an ELF shared object.
-
-`-fini NAME'
- When creating an ELF executable or shared object, call NAME when
- the executable or shared object is unloaded, by setting DT_FINI to
- the address of the function. By default, the linker uses `_fini'
- as the function to call.
-
-`-g'
- Ignored. Provided for compatibility with other tools.
-
-`-GVALUE'
-`--gpsize=VALUE'
- Set the maximum size of objects to be optimized using the GP
- register to SIZE. This is only meaningful for object file formats
- such as MIPS ECOFF which supports putting large and small objects
- into different sections. This is ignored for other object file
- formats.
-
-`-hNAME'
-`-soname=NAME'
- When creating an ELF shared object, set the internal DT_SONAME
- field to the specified name. When an executable is linked with a
- shared object which has a DT_SONAME field, then when the
- executable is run the dynamic linker will attempt to load the
- shared object specified by the DT_SONAME field rather than the
- using the file name given to the linker.
-
-`-i'
- Perform an incremental link (same as option `-r').
-
-`-init NAME'
- When creating an ELF executable or shared object, call NAME when
- the executable or shared object is loaded, by setting DT_INIT to
- the address of the function. By default, the linker uses `_init'
- as the function to call.
-
-`-lNAMESPEC'
-`--library=NAMESPEC'
- Add the archive or object file specified by NAMESPEC to the list
- of files to link. This option may be used any number of times.
- If NAMESPEC is of the form `:FILENAME', `ld' will search the
- library path for a file called FILENAME, otherise it will search
- the library path for a file called `libNAMESPEC.a'.
-
- On systems which support shared libraries, `ld' may also search for
- files other than `libNAMESPEC.a'. Specifically, on ELF and SunOS
- systems, `ld' will search a directory for a library called
- `libNAMESPEC.so' before searching for one called `libNAMESPEC.a'.
- (By convention, a `.so' extension indicates a shared library.)
- Note that this behavior does not apply to `:FILENAME', which
- always specifies a file called FILENAME.
-
- The linker will search an archive only once, at the location where
- it is specified on the command line. If the archive defines a
- symbol which was undefined in some object which appeared before
- the archive on the command line, the linker will include the
- appropriate file(s) from the archive. However, an undefined
- symbol in an object appearing later on the command line will not
- cause the linker to search the archive again.
-
- See the `-(' option for a way to force the linker to search
- archives multiple times.
-
- You may list the same archive multiple times on the command line.
-
- This type of archive searching is standard for Unix linkers.
- However, if you are using `ld' on AIX, note that it is different
- from the behaviour of the AIX linker.
-
-`-LSEARCHDIR'
-`--library-path=SEARCHDIR'
- Add path SEARCHDIR to the list of paths that `ld' will search for
- archive libraries and `ld' control scripts. You may use this
- option any number of times. The directories are searched in the
- order in which they are specified on the command line.
- Directories specified on the command line are searched before the
- default directories. All `-L' options apply to all `-l' options,
- regardless of the order in which the options appear.
-
- If SEARCHDIR begins with `=', then the `=' will be replaced by the
- "sysroot prefix", a path specified when the linker is configured.
-
- The default set of paths searched (without being specified with
- `-L') depends on which emulation mode `ld' is using, and in some
- cases also on how it was configured. *Note Environment::.
-
- The paths can also be specified in a link script with the
- `SEARCH_DIR' command. Directories specified this way are searched
- at the point in which the linker script appears in the command
- line.
-
-`-mEMULATION'
- Emulate the EMULATION linker. You can list the available
- emulations with the `--verbose' or `-V' options.
-
- If the `-m' option is not used, the emulation is taken from the
- `LDEMULATION' environment variable, if that is defined.
-
- Otherwise, the default emulation depends upon how the linker was
- configured.
-
-`-M'
-`--print-map'
- Print a link map to the standard output. A link map provides
- information about the link, including the following:
-
- * Where object files are mapped into memory.
-
- * How common symbols are allocated.
-
- * All archive members included in the link, with a mention of
- the symbol which caused the archive member to be brought in.
-
- * The values assigned to symbols.
-
- Note - symbols whose values are computed by an expression
- which involves a reference to a previous value of the same
- symbol may not have correct result displayed in the link map.
- This is because the linker discards intermediate results and
- only retains the final value of an expression. Under such
- circumstances the linker will display the final value
- enclosed by square brackets. Thus for example a linker
- script containing:
-
- foo = 1
- foo = foo * 4
- foo = foo + 8
-
- will produce the following output in the link map if the `-M'
- option is used:
-
- 0x00000001 foo = 0x1
- [0x0000000c] foo = (foo * 0x4)
- [0x0000000c] foo = (foo + 0x8)
-
- See *Note Expressions:: for more information about
- expressions in linker scripts.
-
-`-n'
-`--nmagic'
- Turn off page alignment of sections, and mark the output as
- `NMAGIC' if possible.
-
-`-N'
-`--omagic'
- Set the text and data sections to be readable and writable. Also,
- do not page-align the data segment, and disable linking against
- shared libraries. If the output format supports Unix style magic
- numbers, mark the output as `OMAGIC'. Note: Although a writable
- text section is allowed for PE-COFF targets, it does not conform
- to the format specification published by Microsoft.
-
-`--no-omagic'
- This option negates most of the effects of the `-N' option. It
- sets the text section to be read-only, and forces the data segment
- to be page-aligned. Note - this option does not enable linking
- against shared libraries. Use `-Bdynamic' for this.
-
-`-o OUTPUT'
-`--output=OUTPUT'
- Use OUTPUT as the name for the program produced by `ld'; if this
- option is not specified, the name `a.out' is used by default. The
- script command `OUTPUT' can also specify the output file name.
-
-`-O LEVEL'
- If LEVEL is a numeric values greater than zero `ld' optimizes the
- output. This might take significantly longer and therefore
- probably should only be enabled for the final binary. At the
- moment this option only affects ELF shared library generation.
- Future releases of the linker may make more use of this option.
- Also currently there is no difference in the linker's behaviour
- for different non-zero values of this option. Again this may
- change with future releases.
-
-`-q'
-`--emit-relocs'
- Leave relocation sections and contents in fully linked executables.
- Post link analysis and optimization tools may need this
- information in order to perform correct modifications of
- executables. This results in larger executables.
-
- This option is currently only supported on ELF platforms.
-
-`--force-dynamic'
- Force the output file to have dynamic sections. This option is
- specific to VxWorks targets.
-
-`-r'
-`--relocatable'
- Generate relocatable output--i.e., generate an output file that
- can in turn serve as input to `ld'. This is often called "partial
- linking". As a side effect, in environments that support standard
- Unix magic numbers, this option also sets the output file's magic
- number to `OMAGIC'. If this option is not specified, an absolute
- file is produced. When linking C++ programs, this option _will
- not_ resolve references to constructors; to do that, use `-Ur'.
-
- When an input file does not have the same format as the output
- file, partial linking is only supported if that input file does
- not contain any relocations. Different output formats can have
- further restrictions; for example some `a.out'-based formats do
- not support partial linking with input files in other formats at
- all.
-
- This option does the same thing as `-i'.
-
-`-R FILENAME'
-`--just-symbols=FILENAME'
- Read symbol names and their addresses from FILENAME, but do not
- relocate it or include it in the output. This allows your output
- file to refer symbolically to absolute locations of memory defined
- in other programs. You may use this option more than once.
-
- For compatibility with other ELF linkers, if the `-R' option is
- followed by a directory name, rather than a file name, it is
- treated as the `-rpath' option.
-
-`-s'
-`--strip-all'
- Omit all symbol information from the output file.
-
-`-S'
-`--strip-debug'
- Omit debugger symbol information (but not all symbols) from the
- output file.
-
-`-t'
-`--trace'
- Print the names of the input files as `ld' processes them.
-
-`-T SCRIPTFILE'
-`--script=SCRIPTFILE'
- Use SCRIPTFILE as the linker script. This script replaces `ld''s
- default linker script (rather than adding to it), so COMMANDFILE
- must specify everything necessary to describe the output file.
- *Note Scripts::. If SCRIPTFILE does not exist in the current
- directory, `ld' looks for it in the directories specified by any
- preceding `-L' options. Multiple `-T' options accumulate.
-
-`-dT SCRIPTFILE'
-`--default-script=SCRIPTFILE'
- Use SCRIPTFILE as the default linker script. *Note Scripts::.
-
- This option is similar to the `--script' option except that
- processing of the script is delayed until after the rest of the
- command line has been processed. This allows options placed after
- the `--default-script' option on the command line to affect the
- behaviour of the linker script, which can be important when the
- linker command line cannot be directly controlled by the user.
- (eg because the command line is being constructed by another tool,
- such as `gcc').
-
-`-u SYMBOL'
-`--undefined=SYMBOL'
- Force SYMBOL to be entered in the output file as an undefined
- symbol. Doing this may, for example, trigger linking of additional
- modules from standard libraries. `-u' may be repeated with
- different option arguments to enter additional undefined symbols.
- This option is equivalent to the `EXTERN' linker script command.
-
-`-Ur'
- For anything other than C++ programs, this option is equivalent to
- `-r': it generates relocatable output--i.e., an output file that
- can in turn serve as input to `ld'. When linking C++ programs,
- `-Ur' _does_ resolve references to constructors, unlike `-r'. It
- does not work to use `-Ur' on files that were themselves linked
- with `-Ur'; once the constructor table has been built, it cannot
- be added to. Use `-Ur' only for the last partial link, and `-r'
- for the others.
-
-`--unique[=SECTION]'
- Creates a separate output section for every input section matching
- SECTION, or if the optional wildcard SECTION argument is missing,
- for every orphan input section. An orphan section is one not
- specifically mentioned in a linker script. You may use this option
- multiple times on the command line; It prevents the normal
- merging of input sections with the same name, overriding output
- section assignments in a linker script.
-
-`-v'
-`--version'
-`-V'
- Display the version number for `ld'. The `-V' option also lists
- the supported emulations.
-
-`-x'
-`--discard-all'
- Delete all local symbols.
-
-`-X'
-`--discard-locals'
- Delete all temporary local symbols. (These symbols start with
- system-specific local label prefixes, typically `.L' for ELF
- systems or `L' for traditional a.out systems.)
-
-`-y SYMBOL'
-`--trace-symbol=SYMBOL'
- Print the name of each linked file in which SYMBOL appears. This
- option may be given any number of times. On many systems it is
- necessary to prepend an underscore.
-
- This option is useful when you have an undefined symbol in your
- link but don't know where the reference is coming from.
-
-`-Y PATH'
- Add PATH to the default library search path. This option exists
- for Solaris compatibility.
-
-`-z KEYWORD'
- The recognized keywords are:
- `combreloc'
- Combines multiple reloc sections and sorts them to make
- dynamic symbol lookup caching possible.
-
- `defs'
- Disallows undefined symbols in object files. Undefined
- symbols in shared libraries are still allowed.
-
- `execstack'
- Marks the object as requiring executable stack.
-
- `initfirst'
- This option is only meaningful when building a shared object.
- It marks the object so that its runtime initialization will
- occur before the runtime initialization of any other objects
- brought into the process at the same time. Similarly the
- runtime finalization of the object will occur after the
- runtime finalization of any other objects.
-
- `interpose'
- Marks the object that its symbol table interposes before all
- symbols but the primary executable.
-
- `lazy'
- When generating an executable or shared library, mark it to
- tell the dynamic linker to defer function call resolution to
- the point when the function is called (lazy binding), rather
- than at load time. Lazy binding is the default.
-
- `loadfltr'
- Marks the object that its filters be processed immediately at
- runtime.
-
- `muldefs'
- Allows multiple definitions.
-
- `nocombreloc'
- Disables multiple reloc sections combining.
-
- `nocopyreloc'
- Disables production of copy relocs.
-
- `nodefaultlib'
- Marks the object that the search for dependencies of this
- object will ignore any default library search paths.
-
- `nodelete'
- Marks the object shouldn't be unloaded at runtime.
-
- `nodlopen'
- Marks the object not available to `dlopen'.
-
- `nodump'
- Marks the object can not be dumped by `dldump'.
-
- `noexecstack'
- Marks the object as not requiring executable stack.
-
- `norelro'
- Don't create an ELF `PT_GNU_RELRO' segment header in the
- object.
-
- `now'
- When generating an executable or shared library, mark it to
- tell the dynamic linker to resolve all symbols when the
- program is started, or when the shared library is linked to
- using dlopen, instead of deferring function call resolution
- to the point when the function is first called.
-
- `origin'
- Marks the object may contain $ORIGIN.
-
- `relro'
- Create an ELF `PT_GNU_RELRO' segment header in the object.
-
- `max-page-size=VALUE'
- Set the emulation maximum page size to VALUE.
-
- `common-page-size=VALUE'
- Set the emulation common page size to VALUE.
-
-
- Other keywords are ignored for Solaris compatibility.
-
-`-( ARCHIVES -)'
-`--start-group ARCHIVES --end-group'
- The ARCHIVES should be a list of archive files. They may be
- either explicit file names, or `-l' options.
-
- The specified archives are searched repeatedly until no new
- undefined references are created. Normally, an archive is
- searched only once in the order that it is specified on the
- command line. If a symbol in that archive is needed to resolve an
- undefined symbol referred to by an object in an archive that
- appears later on the command line, the linker would not be able to
- resolve that reference. By grouping the archives, they all be
- searched repeatedly until all possible references are resolved.
-
- Using this option has a significant performance cost. It is best
- to use it only when there are unavoidable circular references
- between two or more archives.
-
-`--accept-unknown-input-arch'
-`--no-accept-unknown-input-arch'
- Tells the linker to accept input files whose architecture cannot be
- recognised. The assumption is that the user knows what they are
- doing and deliberately wants to link in these unknown input files.
- This was the default behaviour of the linker, before release
- 2.14. The default behaviour from release 2.14 onwards is to
- reject such input files, and so the `--accept-unknown-input-arch'
- option has been added to restore the old behaviour.
-
-`--as-needed'
-`--no-as-needed'
- This option affects ELF DT_NEEDED tags for dynamic libraries
- mentioned on the command line after the `--as-needed' option.
- Normally, the linker will add a DT_NEEDED tag for each dynamic
- library mentioned on the command line, regardless of whether the
- library is actually needed. `--as-needed' causes DT_NEEDED tags
- to only be emitted for libraries that satisfy some symbol
- reference from regular objects which is undefined at the point
- that the library was linked. `--no-as-needed' restores the
- default behaviour.
-
-`--add-needed'
-`--no-add-needed'
- This option affects the treatment of dynamic libraries from ELF
- DT_NEEDED tags in dynamic libraries mentioned on the command line
- after the `--no-add-needed' option. Normally, the linker will add
- a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
- `--no-add-needed' causes DT_NEEDED tags will never be emitted for
- those libraries from DT_NEEDED tags. `--add-needed' restores the
- default behaviour.
-
-`-assert KEYWORD'
- This option is ignored for SunOS compatibility.
-
-`-Bdynamic'
-`-dy'
-`-call_shared'
- Link against dynamic libraries. This is only meaningful on
- platforms for which shared libraries are supported. This option
- is normally the default on such platforms. The different variants
- of this option are for compatibility with various systems. You
- may use this option multiple times on the command line: it affects
- library searching for `-l' options which follow it.
-
-`-Bgroup'
- Set the `DF_1_GROUP' flag in the `DT_FLAGS_1' entry in the dynamic
- section. This causes the runtime linker to handle lookups in this
- object and its dependencies to be performed only inside the group.
- `--unresolved-symbols=report-all' is implied. This option is only
- meaningful on ELF platforms which support shared libraries.
-
-`-Bstatic'
-`-dn'
-`-non_shared'
-`-static'
- Do not link against shared libraries. This is only meaningful on
- platforms for which shared libraries are supported. The different
- variants of this option are for compatibility with various
- systems. You may use this option multiple times on the command
- line: it affects library searching for `-l' options which follow
- it. This option also implies `--unresolved-symbols=report-all'.
- This option can be used with `-shared'. Doing so means that a
- shared library is being created but that all of the library's
- external references must be resolved by pulling in entries from
- static libraries.
-
-`-Bsymbolic'
- When creating a shared library, bind references to global symbols
- to the definition within the shared library, if any. Normally, it
- is possible for a program linked against a shared library to
- override the definition within the shared library. This option is
- only meaningful on ELF platforms which support shared libraries.
-
-`-Bsymbolic-functions'
- When creating a shared library, bind references to global function
- symbols to the definition within the shared library, if any. This
- option is only meaningful on ELF platforms which support shared
- libraries.
-
-`--dynamic-list=DYNAMIC-LIST-FILE'
- Specify the name of a dynamic list file to the linker. This is
- typically used when creating shared libraries to specify a list of
- global symbols whose references shouldn't be bound to the
- definition within the shared library, or creating dynamically
- linked executables to specify a list of symbols which should be
- added to the symbol table in the executable. This option is only
- meaningful on ELF platforms which support shared libraries.
-
- The format of the dynamic list is the same as the version node
- without scope and node name. See *Note VERSION:: for more
- information.
-
-`--dynamic-list-data'
- Include all global data symbols to the dynamic list.
-
-`--dynamic-list-cpp-new'
- Provide the builtin dynamic list for C++ operator new and delete.
- It is mainly useful for building shared libstdc++.
-
-`--dynamic-list-cpp-typeinfo'
- Provide the builtin dynamic list for C++ runtime type
- identification.
-
-`--check-sections'
-`--no-check-sections'
- Asks the linker _not_ to check section addresses after they have
- been assigned to see if there are any overlaps. Normally the
- linker will perform this check, and if it finds any overlaps it
- will produce suitable error messages. The linker does know about,
- and does make allowances for sections in overlays. The default
- behaviour can be restored by using the command line switch
- `--check-sections'.
-
-`--cref'
- Output a cross reference table. If a linker map file is being
- generated, the cross reference table is printed to the map file.
- Otherwise, it is printed on the standard output.
-
- The format of the table is intentionally simple, so that it may be
- easily processed by a script if necessary. The symbols are
- printed out, sorted by name. For each symbol, a list of file
- names is given. If the symbol is defined, the first file listed
- is the location of the definition. The remaining files contain
- references to the symbol.
-
-`--no-define-common'
- This option inhibits the assignment of addresses to common symbols.
- The script command `INHIBIT_COMMON_ALLOCATION' has the same effect.
- *Note Miscellaneous Commands::.
-
- The `--no-define-common' option allows decoupling the decision to
- assign addresses to Common symbols from the choice of the output
- file type; otherwise a non-Relocatable output type forces
- assigning addresses to Common symbols. Using `--no-define-common'
- allows Common symbols that are referenced from a shared library to
- be assigned addresses only in the main program. This eliminates
- the unused duplicate space in the shared library, and also
- prevents any possible confusion over resolving to the wrong
- duplicate when there are many dynamic modules with specialized
- search paths for runtime symbol resolution.
-
-`--defsym SYMBOL=EXPRESSION'
- Create a global symbol in the output file, containing the absolute
- address given by EXPRESSION. You may use this option as many
- times as necessary to define multiple symbols in the command line.
- A limited form of arithmetic is supported for the EXPRESSION in
- this context: you may give a hexadecimal constant or the name of
- an existing symbol, or use `+' and `-' to add or subtract
- hexadecimal constants or symbols. If you need more elaborate
- expressions, consider using the linker command language from a
- script (*note Assignment: Symbol Definitions: Assignments.).
- _Note:_ there should be no white space between SYMBOL, the equals
- sign ("<=>"), and EXPRESSION.
-
-`--demangle[=STYLE]'
-`--no-demangle'
- These options control whether to demangle symbol names in error
- messages and other output. When the linker is told to demangle,
- it tries to present symbol names in a readable fashion: it strips
- leading underscores if they are used by the object file format,
- and converts C++ mangled symbol names into user readable names.
- Different compilers have different mangling styles. The optional
- demangling style argument can be used to choose an appropriate
- demangling style for your compiler. The linker will demangle by
- default unless the environment variable `COLLECT_NO_DEMANGLE' is
- set. These options may be used to override the default.
-
-`--dynamic-linker FILE'
- Set the name of the dynamic linker. This is only meaningful when
- generating dynamically linked ELF executables. The default dynamic
- linker is normally correct; don't use this unless you know what
- you are doing.
-
-`--fatal-warnings'
- Treat all warnings as errors.
-
-`--force-exe-suffix'
- Make sure that an output file has a .exe suffix.
-
- If a successfully built fully linked output file does not have a
- `.exe' or `.dll' suffix, this option forces the linker to copy the
- output file to one of the same name with a `.exe' suffix. This
- option is useful when using unmodified Unix makefiles on a
- Microsoft Windows host, since some versions of Windows won't run
- an image unless it ends in a `.exe' suffix.
-
-`--gc-sections'
-`--no-gc-sections'
- Enable garbage collection of unused input sections. It is ignored
- on targets that do not support this option. This option is not
- compatible with `-r' or `--emit-relocs'. The default behaviour (of
- not performing this garbage collection) can be restored by
- specifying `--no-gc-sections' on the command line.
-
-`--print-gc-sections'
-`--no-print-gc-sections'
- List all sections removed by garbage collection. The listing is
- printed on stderr. This option is only effective if garbage
- collection has been enabled via the `--gc-sections') option. The
- default behaviour (of not listing the sections that are removed)
- can be restored by specifying `--no-print-gc-sections' on the
- command line.
-
-`--help'
- Print a summary of the command-line options on the standard output
- and exit.
-
-`--target-help'
- Print a summary of all target specific options on the standard
- output and exit.
-
-`-Map MAPFILE'
- Print a link map to the file MAPFILE. See the description of the
- `-M' option, above.
-
-`--no-keep-memory'
- `ld' normally optimizes for speed over memory usage by caching the
- symbol tables of input files in memory. This option tells `ld' to
- instead optimize for memory usage, by rereading the symbol tables
- as necessary. This may be required if `ld' runs out of memory
- space while linking a large executable.
-
-`--no-undefined'
-`-z defs'
- Report unresolved symbol references from regular object files.
- This is done even if the linker is creating a non-symbolic shared
- library. The switch `--[no-]allow-shlib-undefined' controls the
- behaviour for reporting unresolved references found in shared
- libraries being linked in.
-
-`--allow-multiple-definition'
-`-z muldefs'
- Normally when a symbol is defined multiple times, the linker will
- report a fatal error. These options allow multiple definitions and
- the first definition will be used.
-
-`--allow-shlib-undefined'
-`--no-allow-shlib-undefined'
- Allows (the default) or disallows undefined symbols in shared
- libraries. This switch is similar to `--no-undefined' except that
- it determines the behaviour when the undefined symbols are in a
- shared library rather than a regular object file. It does not
- affect how undefined symbols in regular object files are handled.
-
- The reason that `--allow-shlib-undefined' is the default is that
- the shared library being specified at link time may not be the
- same as the one that is available at load time, so the symbols
- might actually be resolvable at load time. Plus there are some
- systems, (eg BeOS) where undefined symbols in shared libraries is
- normal. (The kernel patches them at load time to select which
- function is most appropriate for the current architecture. This
- is used for example to dynamically select an appropriate memset
- function). Apparently it is also normal for HPPA shared libraries
- to have undefined symbols.
-
-`--no-undefined-version'
- Normally when a symbol has an undefined version, the linker will
- ignore it. This option disallows symbols with undefined version
- and a fatal error will be issued instead.
-
-`--default-symver'
- Create and use a default symbol version (the soname) for
- unversioned exported symbols.
-
-`--default-imported-symver'
- Create and use a default symbol version (the soname) for
- unversioned imported symbols.
-
-`--no-warn-mismatch'
- Normally `ld' will give an error if you try to link together input
- files that are mismatched for some reason, perhaps because they
- have been compiled for different processors or for different
- endiannesses. This option tells `ld' that it should silently
- permit such possible errors. This option should only be used with
- care, in cases when you have taken some special action that
- ensures that the linker errors are inappropriate.
-
-`--no-warn-search-mismatch'
- Normally `ld' will give a warning if it finds an incompatible
- library during a library search. This option silences the warning.
-
-`--no-whole-archive'
- Turn off the effect of the `--whole-archive' option for subsequent
- archive files.
-
-`--noinhibit-exec'
- Retain the executable output file whenever it is still usable.
- Normally, the linker will not produce an output file if it
- encounters errors during the link process; it exits without
- writing an output file when it issues any error whatsoever.
-
-`-nostdlib'
- Only search library directories explicitly specified on the
- command line. Library directories specified in linker scripts
- (including linker scripts specified on the command line) are
- ignored.
-
-`--oformat OUTPUT-FORMAT'
- `ld' may be configured to support more than one kind of object
- file. If your `ld' is configured this way, you can use the
- `--oformat' option to specify the binary format for the output
- object file. Even when `ld' is configured to support alternative
- object formats, you don't usually need to specify this, as `ld'
- should be configured to produce as a default output format the most
- usual format on each machine. OUTPUT-FORMAT is a text string, the
- name of a particular format supported by the BFD libraries. (You
- can list the available binary formats with `objdump -i'.) The
- script command `OUTPUT_FORMAT' can also specify the output format,
- but this option overrides it. *Note BFD::.
-
-`-pie'
-`--pic-executable'
- Create a position independent executable. This is currently only
- supported on ELF platforms. Position independent executables are
- similar to shared libraries in that they are relocated by the
- dynamic linker to the virtual address the OS chooses for them
- (which can vary between invocations). Like normal dynamically
- linked executables they can be executed and symbols defined in the
- executable cannot be overridden by shared libraries.
-
-`-qmagic'
- This option is ignored for Linux compatibility.
-
-`-Qy'
- This option is ignored for SVR4 compatibility.
-
-`--relax'
- An option with machine dependent effects. This option is only
- supported on a few targets. *Note `ld' and the H8/300: H8/300.
- *Note `ld' and the Intel 960 family: i960. *Note `ld' and Xtensa
- Processors: Xtensa. *Note `ld' and the 68HC11 and 68HC12:
- M68HC11/68HC12. *Note `ld' and PowerPC 32-bit ELF Support:
- PowerPC ELF32.
-
- On some platforms, the `--relax' option performs global
- optimizations that become possible when the linker resolves
- addressing in the program, such as relaxing address modes and
- synthesizing new instructions in the output object file.
-
- On some platforms these link time global optimizations may make
- symbolic debugging of the resulting executable impossible. This
- is known to be the case for the Matsushita MN10200 and MN10300
- family of processors.
-
- On platforms where this is not supported, `--relax' is accepted,
- but ignored.
-
-`--retain-symbols-file FILENAME'
- Retain _only_ the symbols listed in the file FILENAME, discarding
- all others. FILENAME is simply a flat file, with one symbol name
- per line. This option is especially useful in environments (such
- as VxWorks) where a large global symbol table is accumulated
- gradually, to conserve run-time memory.
-
- `--retain-symbols-file' does _not_ discard undefined symbols, or
- symbols needed for relocations.
-
- You may only specify `--retain-symbols-file' once in the command
- line. It overrides `-s' and `-S'.
-
-`-rpath DIR'
- Add a directory to the runtime library search path. This is used
- when linking an ELF executable with shared objects. All `-rpath'
- arguments are concatenated and passed to the runtime linker, which
- uses them to locate shared objects at runtime. The `-rpath'
- option is also used when locating shared objects which are needed
- by shared objects explicitly included in the link; see the
- description of the `-rpath-link' option. If `-rpath' is not used
- when linking an ELF executable, the contents of the environment
- variable `LD_RUN_PATH' will be used if it is defined.
-
- The `-rpath' option may also be used on SunOS. By default, on
- SunOS, the linker will form a runtime search patch out of all the
- `-L' options it is given. If a `-rpath' option is used, the
- runtime search path will be formed exclusively using the `-rpath'
- options, ignoring the `-L' options. This can be useful when using
- gcc, which adds many `-L' options which may be on NFS mounted file
- systems.
-
- For compatibility with other ELF linkers, if the `-R' option is
- followed by a directory name, rather than a file name, it is
- treated as the `-rpath' option.
-
-`-rpath-link DIR'
- When using ELF or SunOS, one shared library may require another.
- This happens when an `ld -shared' link includes a shared library
- as one of the input files.
-
- When the linker encounters such a dependency when doing a
- non-shared, non-relocatable link, it will automatically try to
- locate the required shared library and include it in the link, if
- it is not included explicitly. In such a case, the `-rpath-link'
- option specifies the first set of directories to search. The
- `-rpath-link' option may specify a sequence of directory names
- either by specifying a list of names separated by colons, or by
- appearing multiple times.
-
- This option should be used with caution as it overrides the search
- path that may have been hard compiled into a shared library. In
- such a case it is possible to use unintentionally a different
- search path than the runtime linker would do.
-
- The linker uses the following search paths to locate required
- shared libraries:
- 1. Any directories specified by `-rpath-link' options.
-
- 2. Any directories specified by `-rpath' options. The difference
- between `-rpath' and `-rpath-link' is that directories
- specified by `-rpath' options are included in the executable
- and used at runtime, whereas the `-rpath-link' option is only
- effective at link time. Searching `-rpath' in this way is
- only supported by native linkers and cross linkers which have
- been configured with the `--with-sysroot' option.
-
- 3. On an ELF system, if the `-rpath' and `rpath-link' options
- were not used, search the contents of the environment variable
- `LD_RUN_PATH'. It is for the native linker only.
-
- 4. On SunOS, if the `-rpath' option was not used, search any
- directories specified using `-L' options.
-
- 5. For a native linker, the contents of the environment variable
- `LD_LIBRARY_PATH'.
-
- 6. For a native ELF linker, the directories in `DT_RUNPATH' or
- `DT_RPATH' of a shared library are searched for shared
- libraries needed by it. The `DT_RPATH' entries are ignored if
- `DT_RUNPATH' entries exist.
-
- 7. The default directories, normally `/lib' and `/usr/lib'.
-
- 8. For a native linker on an ELF system, if the file
- `/etc/ld.so.conf' exists, the list of directories found in
- that file.
-
- If the required shared library is not found, the linker will issue
- a warning and continue with the link.
-
-`-shared'
-`-Bshareable'
- Create a shared library. This is currently only supported on ELF,
- XCOFF and SunOS platforms. On SunOS, the linker will
- automatically create a shared library if the `-e' option is not
- used and there are undefined symbols in the link.
-
-`--sort-common'
- This option tells `ld' to sort the common symbols by size when it
- places them in the appropriate output sections. First come all
- the one byte symbols, then all the two byte, then all the four
- byte, and then everything else. This is to prevent gaps between
- symbols due to alignment constraints.
-
-`--sort-section name'
- This option will apply `SORT_BY_NAME' to all wildcard section
- patterns in the linker script.
-
-`--sort-section alignment'
- This option will apply `SORT_BY_ALIGNMENT' to all wildcard section
- patterns in the linker script.
-
-`--split-by-file [SIZE]'
- Similar to `--split-by-reloc' but creates a new output section for
- each input file when SIZE is reached. SIZE defaults to a size of
- 1 if not given.
-
-`--split-by-reloc [COUNT]'
- Tries to creates extra sections in the output file so that no
- single output section in the file contains more than COUNT
- relocations. This is useful when generating huge relocatable
- files for downloading into certain real time kernels with the COFF
- object file format; since COFF cannot represent more than 65535
- relocations in a single section. Note that this will fail to work
- with object file formats which do not support arbitrary sections.
- The linker will not split up individual input sections for
- redistribution, so if a single input section contains more than
- COUNT relocations one output section will contain that many
- relocations. COUNT defaults to a value of 32768.
-
-`--stats'
- Compute and display statistics about the operation of the linker,
- such as execution time and memory usage.
-
-`--sysroot=DIRECTORY'
- Use DIRECTORY as the location of the sysroot, overriding the
- configure-time default. This option is only supported by linkers
- that were configured using `--with-sysroot'.
-
-`--traditional-format'
- For some targets, the output of `ld' is different in some ways from
- the output of some existing linker. This switch requests `ld' to
- use the traditional format instead.
-
- For example, on SunOS, `ld' combines duplicate entries in the
- symbol string table. This can reduce the size of an output file
- with full debugging information by over 30 percent.
- Unfortunately, the SunOS `dbx' program can not read the resulting
- program (`gdb' has no trouble). The `--traditional-format' switch
- tells `ld' to not combine duplicate entries.
-
-`--section-start SECTIONNAME=ORG'
- Locate a section in the output file at the absolute address given
- by ORG. You may use this option as many times as necessary to
- locate multiple sections in the command line. ORG must be a
- single hexadecimal integer; for compatibility with other linkers,
- you may omit the leading `0x' usually associated with hexadecimal
- values. _Note:_ there should be no white space between
- SECTIONNAME, the equals sign ("<=>"), and ORG.
-
-`-Tbss ORG'
-`-Tdata ORG'
-`-Ttext ORG'
- Same as -section-start, with `.bss', `.data' or `.text' as the
- SECTIONNAME.
-
-`--unresolved-symbols=METHOD'
- Determine how to handle unresolved symbols. There are four
- possible values for `method':
-
- `ignore-all'
- Do not report any unresolved symbols.
-
- `report-all'
- Report all unresolved symbols. This is the default.
-
- `ignore-in-object-files'
- Report unresolved symbols that are contained in shared
- libraries, but ignore them if they come from regular object
- files.
-
- `ignore-in-shared-libs'
- Report unresolved symbols that come from regular object
- files, but ignore them if they come from shared libraries.
- This can be useful when creating a dynamic binary and it is
- known that all the shared libraries that it should be
- referencing are included on the linker's command line.
-
- The behaviour for shared libraries on their own can also be
- controlled by the `--[no-]allow-shlib-undefined' option.
-
- Normally the linker will generate an error message for each
- reported unresolved symbol but the option
- `--warn-unresolved-symbols' can change this to a warning.
-
-`--dll-verbose'
-`--verbose'
- Display the version number for `ld' and list the linker emulations
- supported. Display which input files can and cannot be opened.
- Display the linker script being used by the linker.
-
-`--version-script=VERSION-SCRIPTFILE'
- Specify the name of a version script to the linker. This is
- typically used when creating shared libraries to specify
- additional information about the version hierarchy for the library
- being created. This option is only meaningful on ELF platforms
- which support shared libraries. *Note VERSION::.
-
-`--warn-common'
- Warn when a common symbol is combined with another common symbol
- or with a symbol definition. Unix linkers allow this somewhat
- sloppy practise, but linkers on some other operating systems do
- not. This option allows you to find potential problems from
- combining global symbols. Unfortunately, some C libraries use
- this practise, so you may get some warnings about symbols in the
- libraries as well as in your programs.
-
- There are three kinds of global symbols, illustrated here by C
- examples:
-
- `int i = 1;'
- A definition, which goes in the initialized data section of
- the output file.
-
- `extern int i;'
- An undefined reference, which does not allocate space. There
- must be either a definition or a common symbol for the
- variable somewhere.
-
- `int i;'
- A common symbol. If there are only (one or more) common
- symbols for a variable, it goes in the uninitialized data
- area of the output file. The linker merges multiple common
- symbols for the same variable into a single symbol. If they
- are of different sizes, it picks the largest size. The
- linker turns a common symbol into a declaration, if there is
- a definition of the same variable.
-
- The `--warn-common' option can produce five kinds of warnings.
- Each warning consists of a pair of lines: the first describes the
- symbol just encountered, and the second describes the previous
- symbol encountered with the same name. One or both of the two
- symbols will be a common symbol.
-
- 1. Turning a common symbol into a reference, because there is
- already a definition for the symbol.
- FILE(SECTION): warning: common of `SYMBOL'
- overridden by definition
- FILE(SECTION): warning: defined here
-
- 2. Turning a common symbol into a reference, because a later
- definition for the symbol is encountered. This is the same
- as the previous case, except that the symbols are encountered
- in a different order.
- FILE(SECTION): warning: definition of `SYMBOL'
- overriding common
- FILE(SECTION): warning: common is here
-
- 3. Merging a common symbol with a previous same-sized common
- symbol.
- FILE(SECTION): warning: multiple common
- of `SYMBOL'
- FILE(SECTION): warning: previous common is here
-
- 4. Merging a common symbol with a previous larger common symbol.
- FILE(SECTION): warning: common of `SYMBOL'
- overridden by larger common
- FILE(SECTION): warning: larger common is here
-
- 5. Merging a common symbol with a previous smaller common
- symbol. This is the same as the previous case, except that
- the symbols are encountered in a different order.
- FILE(SECTION): warning: common of `SYMBOL'
- overriding smaller common
- FILE(SECTION): warning: smaller common is here
-
-`--warn-constructors'
- Warn if any global constructors are used. This is only useful for
- a few object file formats. For formats like COFF or ELF, the
- linker can not detect the use of global constructors.
-
-`--warn-multiple-gp'
- Warn if multiple global pointer values are required in the output
- file. This is only meaningful for certain processors, such as the
- Alpha. Specifically, some processors put large-valued constants
- in a special section. A special register (the global pointer)
- points into the middle of this section, so that constants can be
- loaded efficiently via a base-register relative addressing mode.
- Since the offset in base-register relative mode is fixed and
- relatively small (e.g., 16 bits), this limits the maximum size of
- the constant pool. Thus, in large programs, it is often necessary
- to use multiple global pointer values in order to be able to
- address all possible constants. This option causes a warning to
- be issued whenever this case occurs.
-
-`--warn-once'
- Only warn once for each undefined symbol, rather than once per
- module which refers to it.
-
-`--warn-section-align'
- Warn if the address of an output section is changed because of
- alignment. Typically, the alignment will be set by an input
- section. The address will only be changed if it not explicitly
- specified; that is, if the `SECTIONS' command does not specify a
- start address for the section (*note SECTIONS::).
-
-`--warn-shared-textrel'
- Warn if the linker adds a DT_TEXTREL to a shared object.
-
-`--warn-unresolved-symbols'
- If the linker is going to report an unresolved symbol (see the
- option `--unresolved-symbols') it will normally generate an error.
- This option makes it generate a warning instead.
-
-`--error-unresolved-symbols'
- This restores the linker's default behaviour of generating errors
- when it is reporting unresolved symbols.
-
-`--whole-archive'
- For each archive mentioned on the command line after the
- `--whole-archive' option, include every object file in the archive
- in the link, rather than searching the archive for the required
- object files. This is normally used to turn an archive file into
- a shared library, forcing every object to be included in the
- resulting shared library. This option may be used more than once.
-
- Two notes when using this option from gcc: First, gcc doesn't know
- about this option, so you have to use `-Wl,-whole-archive'.
- Second, don't forget to use `-Wl,-no-whole-archive' after your
- list of archives, because gcc will add its own list of archives to
- your link and you may not want this flag to affect those as well.
-
-`--wrap SYMBOL'
- Use a wrapper function for SYMBOL. Any undefined reference to
- SYMBOL will be resolved to `__wrap_SYMBOL'. Any undefined
- reference to `__real_SYMBOL' will be resolved to SYMBOL.
-
- This can be used to provide a wrapper for a system function. The
- wrapper function should be called `__wrap_SYMBOL'. If it wishes
- to call the system function, it should call `__real_SYMBOL'.
-
- Here is a trivial example:
-
- void *
- __wrap_malloc (size_t c)
- {
- printf ("malloc called with %zu\n", c);
- return __real_malloc (c);
- }
-
- If you link other code with this file using `--wrap malloc', then
- all calls to `malloc' will call the function `__wrap_malloc'
- instead. The call to `__real_malloc' in `__wrap_malloc' will call
- the real `malloc' function.
-
- You may wish to provide a `__real_malloc' function as well, so that
- links without the `--wrap' option will succeed. If you do this,
- you should not put the definition of `__real_malloc' in the same
- file as `__wrap_malloc'; if you do, the assembler may resolve the
- call before the linker has a chance to wrap it to `malloc'.
-
-`--eh-frame-hdr'
- Request creation of `.eh_frame_hdr' section and ELF
- `PT_GNU_EH_FRAME' segment header.
-
-`--enable-new-dtags'
-`--disable-new-dtags'
- This linker can create the new dynamic tags in ELF. But the older
- ELF systems may not understand them. If you specify
- `--enable-new-dtags', the dynamic tags will be created as needed.
- If you specify `--disable-new-dtags', no new dynamic tags will be
- created. By default, the new dynamic tags are not created. Note
- that those options are only available for ELF systems.
-
-`--hash-size=NUMBER'
- Set the default size of the linker's hash tables to a prime number
- close to NUMBER. Increasing this value can reduce the length of
- time it takes the linker to perform its tasks, at the expense of
- increasing the linker's memory requirements. Similarly reducing
- this value can reduce the memory requirements at the expense of
- speed.
-
-`--hash-style=STYLE'
- Set the type of linker's hash table(s). STYLE can be either
- `sysv' for classic ELF `.hash' section, `gnu' for new style GNU
- `.gnu.hash' section or `both' for both the classic ELF `.hash' and
- new style GNU `.gnu.hash' hash tables. The default is `sysv'.
-
-`--reduce-memory-overheads'
- This option reduces memory requirements at ld runtime, at the
- expense of linking speed. This was introduced to select the old
- O(n^2) algorithm for link map file generation, rather than the new
- O(n) algorithm which uses about 40% more memory for symbol storage.
-
- Another effect of the switch is to set the default hash table size
- to 1021, which again saves memory at the cost of lengthening the
- linker's run time. This is not done however if the `--hash-size'
- switch has been used.
-
- The `--reduce-memory-overheads' switch may be also be used to
- enable other tradeoffs in future versions of the linker.
-
-`--build-id'
-`--build-id=STYLE'
- Request creation of `.note.gnu.build-id' ELF note section. The
- contents of the note are unique bits identifying this linked file.
- STYLE can be `uuid' to use 128 random bits, `sha1' to use a
- 160-bit SHA1 hash on the normative parts of the output contents,
- `md5' to use a 128-bit MD5 hash on the normative parts of the
- output contents, or `0xHEXSTRING' to use a chosen bit string
- specified as an even number of hexadecimal digits (`-' and `:'
- characters between digit pairs are ignored). If STYLE is omitted,
- `sha1' is used.
-
- The `md5' and `sha1' styles produces an identifier that is always
- the same in an identical output file, but will be unique among all
- nonidentical output files. It is not intended to be compared as a
- checksum for the file's contents. A linked file may be changed
- later by other tools, but the build ID bit string identifying the
- original linked file does not change.
-
- Passing `none' for STYLE disables the setting from any
- `--build-id' options earlier on the command line.
-
-2.1.1 Options Specific to i386 PE Targets
------------------------------------------
-
-The i386 PE linker supports the `-shared' option, which causes the
-output to be a dynamically linked library (DLL) instead of a normal
-executable. You should name the output `*.dll' when you use this
-option. In addition, the linker fully supports the standard `*.def'
-files, which may be specified on the linker command line like an object
-file (in fact, it should precede archives it exports symbols from, to
-ensure that they get linked in, just like a normal object file).
-
- In addition to the options common to all targets, the i386 PE linker
-support additional command line options that are specific to the i386
-PE target. Options that take values may be separated from their values
-by either a space or an equals sign.
-
-`--add-stdcall-alias'
- If given, symbols with a stdcall suffix (@NN) will be exported
- as-is and also with the suffix stripped. [This option is specific
- to the i386 PE targeted port of the linker]
-
-`--base-file FILE'
- Use FILE as the name of a file in which to save the base addresses
- of all the relocations needed for generating DLLs with `dlltool'.
- [This is an i386 PE specific option]
-
-`--dll'
- Create a DLL instead of a regular executable. You may also use
- `-shared' or specify a `LIBRARY' in a given `.def' file. [This
- option is specific to the i386 PE targeted port of the linker]
-
-`--enable-stdcall-fixup'
-`--disable-stdcall-fixup'
- If the link finds a symbol that it cannot resolve, it will attempt
- to do "fuzzy linking" by looking for another defined symbol that
- differs only in the format of the symbol name (cdecl vs stdcall)
- and will resolve that symbol by linking to the match. For
- example, the undefined symbol `_foo' might be linked to the
- function `_foo@12', or the undefined symbol `_bar@16' might be
- linked to the function `_bar'. When the linker does this, it
- prints a warning, since it normally should have failed to link,
- but sometimes import libraries generated from third-party dlls may
- need this feature to be usable. If you specify
- `--enable-stdcall-fixup', this feature is fully enabled and
- warnings are not printed. If you specify
- `--disable-stdcall-fixup', this feature is disabled and such
- mismatches are considered to be errors. [This option is specific
- to the i386 PE targeted port of the linker]
-
-`--export-all-symbols'
- If given, all global symbols in the objects used to build a DLL
- will be exported by the DLL. Note that this is the default if
- there otherwise wouldn't be any exported symbols. When symbols are
- explicitly exported via DEF files or implicitly exported via
- function attributes, the default is to not export anything else
- unless this option is given. Note that the symbols `DllMain@12',
- `DllEntryPoint@0', `DllMainCRTStartup@12', and `impure_ptr' will
- not be automatically exported. Also, symbols imported from other
- DLLs will not be re-exported, nor will symbols specifying the
- DLL's internal layout such as those beginning with `_head_' or
- ending with `_iname'. In addition, no symbols from `libgcc',
- `libstd++', `libmingw32', or `crtX.o' will be exported. Symbols
- whose names begin with `__rtti_' or `__builtin_' will not be
- exported, to help with C++ DLLs. Finally, there is an extensive
- list of cygwin-private symbols that are not exported (obviously,
- this applies on when building DLLs for cygwin targets). These
- cygwin-excludes are: `_cygwin_dll_entry@12',
- `_cygwin_crt0_common@8', `_cygwin_noncygwin_dll_entry@12',
- `_fmode', `_impure_ptr', `cygwin_attach_dll', `cygwin_premain0',
- `cygwin_premain1', `cygwin_premain2', `cygwin_premain3', and
- `environ'. [This option is specific to the i386 PE targeted port
- of the linker]
-
-`--exclude-symbols SYMBOL,SYMBOL,...'
- Specifies a list of symbols which should not be automatically
- exported. The symbol names may be delimited by commas or colons.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--file-alignment'
- Specify the file alignment. Sections in the file will always
- begin at file offsets which are multiples of this number. This
- defaults to 512. [This option is specific to the i386 PE targeted
- port of the linker]
-
-`--heap RESERVE'
-`--heap RESERVE,COMMIT'
- Specify the number of bytes of memory to reserve (and optionally
- commit) to be used as heap for this program. The default is 1Mb
- reserved, 4K committed. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--image-base VALUE'
- Use VALUE as the base address of your program or dll. This is the
- lowest memory location that will be used when your program or dll
- is loaded. To reduce the need to relocate and improve performance
- of your dlls, each should have a unique base address and not
- overlap any other dlls. The default is 0x400000 for executables,
- and 0x10000000 for dlls. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--kill-at'
- If given, the stdcall suffixes (@NN) will be stripped from symbols
- before they are exported. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--large-address-aware'
- If given, the appropriate bit in the "Characteristics" field of
- the COFF header is set to indicate that this executable supports
- virtual addresses greater than 2 gigabytes. This should be used
- in conjunction with the /3GB or /USERVA=VALUE megabytes switch in
- the "[operating systems]" section of the BOOT.INI. Otherwise,
- this bit has no effect. [This option is specific to PE targeted
- ports of the linker]
-
-`--major-image-version VALUE'
- Sets the major number of the "image version". Defaults to 1.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--major-os-version VALUE'
- Sets the major number of the "os version". Defaults to 4. [This
- option is specific to the i386 PE targeted port of the linker]
-
-`--major-subsystem-version VALUE'
- Sets the major number of the "subsystem version". Defaults to 4.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--minor-image-version VALUE'
- Sets the minor number of the "image version". Defaults to 0.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--minor-os-version VALUE'
- Sets the minor number of the "os version". Defaults to 0. [This
- option is specific to the i386 PE targeted port of the linker]
-
-`--minor-subsystem-version VALUE'
- Sets the minor number of the "subsystem version". Defaults to 0.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--output-def FILE'
- The linker will create the file FILE which will contain a DEF file
- corresponding to the DLL the linker is generating. This DEF file
- (which should be called `*.def') may be used to create an import
- library with `dlltool' or may be used as a reference to
- automatically or implicitly exported symbols. [This option is
- specific to the i386 PE targeted port of the linker]
-
-`--out-implib FILE'
- The linker will create the file FILE which will contain an import
- lib corresponding to the DLL the linker is generating. This import
- lib (which should be called `*.dll.a' or `*.a' may be used to link
- clients against the generated DLL; this behaviour makes it
- possible to skip a separate `dlltool' import library creation step.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--enable-auto-image-base'
- Automatically choose the image base for DLLs, unless one is
- specified using the `--image-base' argument. By using a hash
- generated from the dllname to create unique image bases for each
- DLL, in-memory collisions and relocations which can delay program
- execution are avoided. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--disable-auto-image-base'
- Do not automatically generate a unique image base. If there is no
- user-specified image base (`--image-base') then use the platform
- default. [This option is specific to the i386 PE targeted port of
- the linker]
-
-`--dll-search-prefix STRING'
- When linking dynamically to a dll without an import library,
- search for `<string><basename>.dll' in preference to
- `lib<basename>.dll'. This behaviour allows easy distinction
- between DLLs built for the various "subplatforms": native, cygwin,
- uwin, pw, etc. For instance, cygwin DLLs typically use
- `--dll-search-prefix=cyg'. [This option is specific to the i386
- PE targeted port of the linker]
-
-`--enable-auto-import'
- Do sophisticated linking of `_symbol' to `__imp__symbol' for DATA
- imports from DLLs, and create the necessary thunking symbols when
- building the import libraries with those DATA exports. Note: Use
- of the 'auto-import' extension will cause the text section of the
- image file to be made writable. This does not conform to the
- PE-COFF format specification published by Microsoft.
-
- Using 'auto-import' generally will 'just work' - but sometimes you
- may see this message:
-
- "variable '<var>' can't be auto-imported. Please read the
- documentation for ld's `--enable-auto-import' for details."
-
- This message occurs when some (sub)expression accesses an address
- ultimately given by the sum of two constants (Win32 import tables
- only allow one). Instances where this may occur include accesses
- to member fields of struct variables imported from a DLL, as well
- as using a constant index into an array variable imported from a
- DLL. Any multiword variable (arrays, structs, long long, etc) may
- trigger this error condition. However, regardless of the exact
- data type of the offending exported variable, ld will always
- detect it, issue the warning, and exit.
-
- There are several ways to address this difficulty, regardless of
- the data type of the exported variable:
-
- One way is to use -enable-runtime-pseudo-reloc switch. This leaves
- the task of adjusting references in your client code for runtime
- environment, so this method works only when runtime environment
- supports this feature.
-
- A second solution is to force one of the 'constants' to be a
- variable - that is, unknown and un-optimizable at compile time.
- For arrays, there are two possibilities: a) make the indexee (the
- array's address) a variable, or b) make the 'constant' index a
- variable. Thus:
-
- extern type extern_array[];
- extern_array[1] -->
- { volatile type *t=extern_array; t[1] }
-
- or
-
- extern type extern_array[];
- extern_array[1] -->
- { volatile int t=1; extern_array[t] }
-
- For structs (and most other multiword data types) the only option
- is to make the struct itself (or the long long, or the ...)
- variable:
-
- extern struct s extern_struct;
- extern_struct.field -->
- { volatile struct s *t=&extern_struct; t->field }
-
- or
-
- extern long long extern_ll;
- extern_ll -->
- { volatile long long * local_ll=&extern_ll; *local_ll }
-
- A third method of dealing with this difficulty is to abandon
- 'auto-import' for the offending symbol and mark it with
- `__declspec(dllimport)'. However, in practise that requires using
- compile-time #defines to indicate whether you are building a DLL,
- building client code that will link to the DLL, or merely
- building/linking to a static library. In making the choice
- between the various methods of resolving the 'direct address with
- constant offset' problem, you should consider typical real-world
- usage:
-
- Original:
- --foo.h
- extern int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- printf("%d\n",arr[1]);
- }
-
- Solution 1:
- --foo.h
- extern int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- /* This workaround is for win32 and cygwin; do not "optimize" */
- volatile int *parr = arr;
- printf("%d\n",parr[1]);
- }
-
- Solution 2:
- --foo.h
- /* Note: auto-export is assumed (no __declspec(dllexport)) */
- #if (defined(_WIN32) || defined(__CYGWIN__)) && \
- !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
- #define FOO_IMPORT __declspec(dllimport)
- #else
- #define FOO_IMPORT
- #endif
- extern FOO_IMPORT int arr[];
- --foo.c
- #include "foo.h"
- void main(int argc, char **argv){
- printf("%d\n",arr[1]);
- }
-
- A fourth way to avoid this problem is to re-code your library to
- use a functional interface rather than a data interface for the
- offending variables (e.g. set_foo() and get_foo() accessor
- functions). [This option is specific to the i386 PE targeted port
- of the linker]
-
-`--disable-auto-import'
- Do not attempt to do sophisticated linking of `_symbol' to
- `__imp__symbol' for DATA imports from DLLs. [This option is
- specific to the i386 PE targeted port of the linker]
-
-`--enable-runtime-pseudo-reloc'
- If your code contains expressions described in -enable-auto-import
- section, that is, DATA imports from DLL with non-zero offset, this
- switch will create a vector of 'runtime pseudo relocations' which
- can be used by runtime environment to adjust references to such
- data in your client code. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--disable-runtime-pseudo-reloc'
- Do not create pseudo relocations for non-zero offset DATA imports
- from DLLs. This is the default. [This option is specific to the
- i386 PE targeted port of the linker]
-
-`--enable-extra-pe-debug'
- Show additional debug info related to auto-import symbol thunking.
- [This option is specific to the i386 PE targeted port of the
- linker]
-
-`--section-alignment'
- Sets the section alignment. Sections in memory will always begin
- at addresses which are a multiple of this number. Defaults to
- 0x1000. [This option is specific to the i386 PE targeted port of
- the linker]
-
-`--stack RESERVE'
-`--stack RESERVE,COMMIT'
- Specify the number of bytes of memory to reserve (and optionally
- commit) to be used as stack for this program. The default is 2Mb
- reserved, 4K committed. [This option is specific to the i386 PE
- targeted port of the linker]
-
-`--subsystem WHICH'
-`--subsystem WHICH:MAJOR'
-`--subsystem WHICH:MAJOR.MINOR'
- Specifies the subsystem under which your program will execute. The
- legal values for WHICH are `native', `windows', `console',
- `posix', and `xbox'. You may optionally set the subsystem version
- also. Numeric values are also accepted for WHICH. [This option
- is specific to the i386 PE targeted port of the linker]
-
-
-2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets
-------------------------------------------------------------
-
-The 68HC11 and 68HC12 linkers support specific options to control the
-memory bank switching mapping and trampoline code generation.
-
-`--no-trampoline'
- This option disables the generation of trampoline. By default a
- trampoline is generated for each far function which is called
- using a `jsr' instruction (this happens when a pointer to a far
- function is taken).
-
-`--bank-window NAME'
- This option indicates to the linker the name of the memory region
- in the `MEMORY' specification that describes the memory bank
- window. The definition of such region is then used by the linker
- to compute paging and addresses within the memory window.
-
-
-\1f
-File: ld.info, Node: Environment, Prev: Options, Up: Invocation
-
-2.2 Environment Variables
-=========================
-
-You can change the behaviour of `ld' with the environment variables
-`GNUTARGET', `LDEMULATION' and `COLLECT_NO_DEMANGLE'.
-
- `GNUTARGET' determines the input-file object format if you don't use
-`-b' (or its synonym `--format'). Its value should be one of the BFD
-names for an input format (*note BFD::). If there is no `GNUTARGET' in
-the environment, `ld' uses the natural format of the target. If
-`GNUTARGET' is set to `default' then BFD attempts to discover the input
-format by examining binary input files; this method often succeeds, but
-there are potential ambiguities, since there is no method of ensuring
-that the magic number used to specify object-file formats is unique.
-However, the configuration procedure for BFD on each system places the
-conventional format for that system first in the search-list, so
-ambiguities are resolved in favor of convention.
-
- `LDEMULATION' determines the default emulation if you don't use the
-`-m' option. The emulation can affect various aspects of linker
-behaviour, particularly the default linker script. You can list the
-available emulations with the `--verbose' or `-V' options. If the `-m'
-option is not used, and the `LDEMULATION' environment variable is not
-defined, the default emulation depends upon how the linker was
-configured.
-
- Normally, the linker will default to demangling symbols. However, if
-`COLLECT_NO_DEMANGLE' is set in the environment, then it will default
-to not demangling symbols. This environment variable is used in a
-similar fashion by the `gcc' linker wrapper program. The default may
-be overridden by the `--demangle' and `--no-demangle' options.
-
-\1f
-File: ld.info, Node: Scripts, Next: Machine Dependent, Prev: Invocation, Up: Top
-
-3 Linker Scripts
-****************
-
-Every link is controlled by a "linker script". This script is written
-in the linker command language.
-
- The main purpose of the linker script is to describe how the
-sections in the input files should be mapped into the output file, and
-to control the memory layout of the output file. Most linker scripts
-do nothing more than this. However, when necessary, the linker script
-can also direct the linker to perform many other operations, using the
-commands described below.
-
- The linker always uses a linker script. If you do not supply one
-yourself, the linker will use a default script that is compiled into the
-linker executable. You can use the `--verbose' command line option to
-display the default linker script. Certain command line options, such
-as `-r' or `-N', will affect the default linker script.
-
- You may supply your own linker script by using the `-T' command line
-option. When you do this, your linker script will replace the default
-linker script.
-
- You may also use linker scripts implicitly by naming them as input
-files to the linker, as though they were files to be linked. *Note
-Implicit Linker Scripts::.
-
-* Menu:
-
-* Basic Script Concepts:: Basic Linker Script Concepts
-* Script Format:: Linker Script Format
-* Simple Example:: Simple Linker Script Example
-* Simple Commands:: Simple Linker Script Commands
-* Assignments:: Assigning Values to Symbols
-* SECTIONS:: SECTIONS Command
-* MEMORY:: MEMORY Command
-* PHDRS:: PHDRS Command
-* VERSION:: VERSION Command
-* Expressions:: Expressions in Linker Scripts
-* Implicit Linker Scripts:: Implicit Linker Scripts
-
-\1f
-File: ld.info, Node: Basic Script Concepts, Next: Script Format, Up: Scripts
-
-3.1 Basic Linker Script Concepts
-================================
-
-We need to define some basic concepts and vocabulary in order to
-describe the linker script language.
-
- The linker combines input files into a single output file. The
-output file and each input file are in a special data format known as an
-"object file format". Each file is called an "object file". The
-output file is often called an "executable", but for our purposes we
-will also call it an object file. Each object file has, among other
-things, a list of "sections". We sometimes refer to a section in an
-input file as an "input section"; similarly, a section in the output
-file is an "output section".
-
- Each section in an object file has a name and a size. Most sections
-also have an associated block of data, known as the "section contents".
-A section may be marked as "loadable", which mean that the contents
-should be loaded into memory when the output file is run. A section
-with no contents may be "allocatable", which means that an area in
-memory should be set aside, but nothing in particular should be loaded
-there (in some cases this memory must be zeroed out). A section which
-is neither loadable nor allocatable typically contains some sort of
-debugging information.
-
- Every loadable or allocatable output section has two addresses. The
-first is the "VMA", or virtual memory address. This is the address the
-section will have when the output file is run. The second is the
-"LMA", or load memory address. This is the address at which the
-section will be loaded. In most cases the two addresses will be the
-same. An example of when they might be different is when a data section
-is loaded into ROM, and then copied into RAM when the program starts up
-(this technique is often used to initialize global variables in a ROM
-based system). In this case the ROM address would be the LMA, and the
-RAM address would be the VMA.
-
- You can see the sections in an object file by using the `objdump'
-program with the `-h' option.
-
- Every object file also has a list of "symbols", known as the "symbol
-table". A symbol may be defined or undefined. Each symbol has a name,
-and each defined symbol has an address, among other information. If
-you compile a C or C++ program into an object file, you will get a
-defined symbol for every defined function and global or static
-variable. Every undefined function or global variable which is
-referenced in the input file will become an undefined symbol.
-
- You can see the symbols in an object file by using the `nm' program,
-or by using the `objdump' program with the `-t' option.
-
-\1f
-File: ld.info, Node: Script Format, Next: Simple Example, Prev: Basic Script Concepts, Up: Scripts
-
-3.2 Linker Script Format
-========================
-
-Linker scripts are text files.
-
- You write a linker script as a series of commands. Each command is
-either a keyword, possibly followed by arguments, or an assignment to a
-symbol. You may separate commands using semicolons. Whitespace is
-generally ignored.
-
- Strings such as file or format names can normally be entered
-directly. If the file name contains a character such as a comma which
-would otherwise serve to separate file names, you may put the file name
-in double quotes. There is no way to use a double quote character in a
-file name.
-
- You may include comments in linker scripts just as in C, delimited by
-`/*' and `*/'. As in C, comments are syntactically equivalent to
-whitespace.
-
-\1f
-File: ld.info, Node: Simple Example, Next: Simple Commands, Prev: Script Format, Up: Scripts
-
-3.3 Simple Linker Script Example
-================================
-
-Many linker scripts are fairly simple.
-
- The simplest possible linker script has just one command:
-`SECTIONS'. You use the `SECTIONS' command to describe the memory
-layout of the output file.
-
- The `SECTIONS' command is a powerful command. Here we will describe
-a simple use of it. Let's assume your program consists only of code,
-initialized data, and uninitialized data. These will be in the
-`.text', `.data', and `.bss' sections, respectively. Let's assume
-further that these are the only sections which appear in your input
-files.
-
- For this example, let's say that the code should be loaded at address
-0x10000, and that the data should start at address 0x8000000. Here is a
-linker script which will do that:
- SECTIONS
- {
- . = 0x10000;
- .text : { *(.text) }
- . = 0x8000000;
- .data : { *(.data) }
- .bss : { *(.bss) }
- }
-
- You write the `SECTIONS' command as the keyword `SECTIONS', followed
-by a series of symbol assignments and output section descriptions
-enclosed in curly braces.
-
- The first line inside the `SECTIONS' command of the above example
-sets the value of the special symbol `.', which is the location
-counter. If you do not specify the address of an output section in some
-other way (other ways are described later), the address is set from the
-current value of the location counter. The location counter is then
-incremented by the size of the output section. At the start of the
-`SECTIONS' command, the location counter has the value `0'.
-
- The second line defines an output section, `.text'. The colon is
-required syntax which may be ignored for now. Within the curly braces
-after the output section name, you list the names of the input sections
-which should be placed into this output section. The `*' is a wildcard
-which matches any file name. The expression `*(.text)' means all
-`.text' input sections in all input files.
-
- Since the location counter is `0x10000' when the output section
-`.text' is defined, the linker will set the address of the `.text'
-section in the output file to be `0x10000'.
-
- The remaining lines define the `.data' and `.bss' sections in the
-output file. The linker will place the `.data' output section at
-address `0x8000000'. After the linker places the `.data' output
-section, the value of the location counter will be `0x8000000' plus the
-size of the `.data' output section. The effect is that the linker will
-place the `.bss' output section immediately after the `.data' output
-section in memory.
-
- The linker will ensure that each output section has the required
-alignment, by increasing the location counter if necessary. In this
-example, the specified addresses for the `.text' and `.data' sections
-will probably satisfy any alignment constraints, but the linker may
-have to create a small gap between the `.data' and `.bss' sections.
-
- That's it! That's a simple and complete linker script.
-
-\1f
-File: ld.info, Node: Simple Commands, Next: Assignments, Prev: Simple Example, Up: Scripts
-
-3.4 Simple Linker Script Commands
-=================================
-
-In this section we describe the simple linker script commands.
-
-* Menu:
-
-* Entry Point:: Setting the entry point
-* File Commands:: Commands dealing with files
-
-* Format Commands:: Commands dealing with object file formats
-
-* Miscellaneous Commands:: Other linker script commands
-
-\1f
-File: ld.info, Node: Entry Point, Next: File Commands, Up: Simple Commands
-
-3.4.1 Setting the Entry Point
------------------------------
-
-The first instruction to execute in a program is called the "entry
-point". You can use the `ENTRY' linker script command to set the entry
-point. The argument is a symbol name:
- ENTRY(SYMBOL)
-
- There are several ways to set the entry point. The linker will set
-the entry point by trying each of the following methods in order, and
-stopping when one of them succeeds:
- * the `-e' ENTRY command-line option;
-
- * the `ENTRY(SYMBOL)' command in a linker script;
-
- * the value of the symbol `start', if defined;
-
- * the address of the first byte of the `.text' section, if present;
-
- * The address `0'.
-
-\1f
-File: ld.info, Node: File Commands, Next: Format Commands, Prev: Entry Point, Up: Simple Commands
-
-3.4.2 Commands Dealing with Files
----------------------------------
-
-Several linker script commands deal with files.
-
-`INCLUDE FILENAME'
- Include the linker script FILENAME at this point. The file will
- be searched for in the current directory, and in any directory
- specified with the `-L' option. You can nest calls to `INCLUDE'
- up to 10 levels deep.
-
-`INPUT(FILE, FILE, ...)'
-`INPUT(FILE FILE ...)'
- The `INPUT' command directs the linker to include the named files
- in the link, as though they were named on the command line.
-
- For example, if you always want to include `subr.o' any time you do
- a link, but you can't be bothered to put it on every link command
- line, then you can put `INPUT (subr.o)' in your linker script.
-
- In fact, if you like, you can list all of your input files in the
- linker script, and then invoke the linker with nothing but a `-T'
- option.
-
- In case a "sysroot prefix" is configured, and the filename starts
- with the `/' character, and the script being processed was located
- inside the "sysroot prefix", the filename will be looked for in
- the "sysroot prefix". Otherwise, the linker will try to open the
- file in the current directory. If it is not found, the linker
- will search through the archive library search path. See the
- description of `-L' in *Note Command Line Options: Options.
-
- If you use `INPUT (-lFILE)', `ld' will transform the name to
- `libFILE.a', as with the command line argument `-l'.
-
- When you use the `INPUT' command in an implicit linker script, the
- files will be included in the link at the point at which the linker
- script file is included. This can affect archive searching.
-
-`GROUP(FILE, FILE, ...)'
-`GROUP(FILE FILE ...)'
- The `GROUP' command is like `INPUT', except that the named files
- should all be archives, and they are searched repeatedly until no
- new undefined references are created. See the description of `-('
- in *Note Command Line Options: Options.
-
-`AS_NEEDED(FILE, FILE, ...)'
-`AS_NEEDED(FILE FILE ...)'
- This construct can appear only inside of the `INPUT' or `GROUP'
- commands, among other filenames. The files listed will be handled
- as if they appear directly in the `INPUT' or `GROUP' commands,
- with the exception of ELF shared libraries, that will be added only
- when they are actually needed. This construct essentially enables
- `--as-needed' option for all the files listed inside of it and
- restores previous `--as-needed' resp. `--no-as-needed' setting
- afterwards.
-
-`OUTPUT(FILENAME)'
- The `OUTPUT' command names the output file. Using
- `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
- FILENAME' on the command line (*note Command Line Options:
- Options.). If both are used, the command line option takes
- precedence.
-
- You can use the `OUTPUT' command to define a default name for the
- output file other than the usual default of `a.out'.
-
-`SEARCH_DIR(PATH)'
- The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
- looks for archive libraries. Using `SEARCH_DIR(PATH)' is exactly
- like using `-L PATH' on the command line (*note Command Line
- Options: Options.). If both are used, then the linker will search
- both paths. Paths specified using the command line option are
- searched first.
-
-`STARTUP(FILENAME)'
- The `STARTUP' command is just like the `INPUT' command, except
- that FILENAME will become the first input file to be linked, as
- though it were specified first on the command line. This may be
- useful when using a system in which the entry point is always the
- start of the first file.
-
-\1f
-File: ld.info, Node: Format Commands, Next: Miscellaneous Commands, Prev: File Commands, Up: Simple Commands
-
-3.4.3 Commands Dealing with Object File Formats
------------------------------------------------
-
-A couple of linker script commands deal with object file formats.
-
-`OUTPUT_FORMAT(BFDNAME)'
-`OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
- The `OUTPUT_FORMAT' command names the BFD format to use for the
- output file (*note BFD::). Using `OUTPUT_FORMAT(BFDNAME)' is
- exactly like using `--oformat BFDNAME' on the command line (*note
- Command Line Options: Options.). If both are used, the command
- line option takes precedence.
-
- You can use `OUTPUT_FORMAT' with three arguments to use different
- formats based on the `-EB' and `-EL' command line options. This
- permits the linker script to set the output format based on the
- desired endianness.
-
- If neither `-EB' nor `-EL' are used, then the output format will
- be the first argument, DEFAULT. If `-EB' is used, the output
- format will be the second argument, BIG. If `-EL' is used, the
- output format will be the third argument, LITTLE.
-
- For example, the default linker script for the MIPS ELF target
- uses this command:
- OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
- This says that the default format for the output file is
- `elf32-bigmips', but if the user uses the `-EL' command line
- option, the output file will be created in the `elf32-littlemips'
- format.
-
-`TARGET(BFDNAME)'
- The `TARGET' command names the BFD format to use when reading input
- files. It affects subsequent `INPUT' and `GROUP' commands. This
- command is like using `-b BFDNAME' on the command line (*note
- Command Line Options: Options.). If the `TARGET' command is used
- but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
- used to set the format for the output file. *Note BFD::.
-
-\1f
-File: ld.info, Node: Miscellaneous Commands, Prev: Format Commands, Up: Simple Commands
-
-3.4.4 Other Linker Script Commands
-----------------------------------
-
-There are a few other linker scripts commands.
-
-`ASSERT(EXP, MESSAGE)'
- Ensure that EXP is non-zero. If it is zero, then exit the linker
- with an error code, and print MESSAGE.
-
-`EXTERN(SYMBOL SYMBOL ...)'
- Force SYMBOL to be entered in the output file as an undefined
- symbol. Doing this may, for example, trigger linking of additional
- modules from standard libraries. You may list several SYMBOLs for
- each `EXTERN', and you may use `EXTERN' multiple times. This
- command has the same effect as the `-u' command-line option.
-
-`FORCE_COMMON_ALLOCATION'
- This command has the same effect as the `-d' command-line option:
- to make `ld' assign space to common symbols even if a relocatable
- output file is specified (`-r').
-
-`INHIBIT_COMMON_ALLOCATION'
- This command has the same effect as the `--no-define-common'
- command-line option: to make `ld' omit the assignment of addresses
- to common symbols even for a non-relocatable output file.
-
-`NOCROSSREFS(SECTION SECTION ...)'
- This command may be used to tell `ld' to issue an error about any
- references among certain output sections.
-
- In certain types of programs, particularly on embedded systems when
- using overlays, when one section is loaded into memory, another
- section will not be. Any direct references between the two
- sections would be errors. For example, it would be an error if
- code in one section called a function defined in the other section.
-
- The `NOCROSSREFS' command takes a list of output section names. If
- `ld' detects any cross references between the sections, it reports
- an error and returns a non-zero exit status. Note that the
- `NOCROSSREFS' command uses output section names, not input section
- names.
-
-`OUTPUT_ARCH(BFDARCH)'
- Specify a particular output machine architecture. The argument is
- one of the names used by the BFD library (*note BFD::). You can
- see the architecture of an object file by using the `objdump'
- program with the `-f' option.
-
-\1f
-File: ld.info, Node: Assignments, Next: SECTIONS, Prev: Simple Commands, Up: Scripts
-
-3.5 Assigning Values to Symbols
-===============================
-
-You may assign a value to a symbol in a linker script. This will define
-the symbol and place it into the symbol table with a global scope.
-
-* Menu:
-
-* Simple Assignments:: Simple Assignments
-* PROVIDE:: PROVIDE
-* PROVIDE_HIDDEN:: PROVIDE_HIDDEN
-* Source Code Reference:: How to use a linker script defined symbol in source code
-
-\1f
-File: ld.info, Node: Simple Assignments, Next: PROVIDE, Up: Assignments
-
-3.5.1 Simple Assignments
-------------------------
-
-You may assign to a symbol using any of the C assignment operators:
-
-`SYMBOL = EXPRESSION ;'
-`SYMBOL += EXPRESSION ;'
-`SYMBOL -= EXPRESSION ;'
-`SYMBOL *= EXPRESSION ;'
-`SYMBOL /= EXPRESSION ;'
-`SYMBOL <<= EXPRESSION ;'
-`SYMBOL >>= EXPRESSION ;'
-`SYMBOL &= EXPRESSION ;'
-`SYMBOL |= EXPRESSION ;'
-
- The first case will define SYMBOL to the value of EXPRESSION. In
-the other cases, SYMBOL must already be defined, and the value will be
-adjusted accordingly.
-
- The special symbol name `.' indicates the location counter. You may
-only use this within a `SECTIONS' command. *Note Location Counter::.
-
- The semicolon after EXPRESSION is required.
-
- Expressions are defined below; see *Note Expressions::.
-
- You may write symbol assignments as commands in their own right, or
-as statements within a `SECTIONS' command, or as part of an output
-section description in a `SECTIONS' command.
-
- The section of the symbol will be set from the section of the
-expression; for more information, see *Note Expression Section::.
-
- Here is an example showing the three different places that symbol
-assignments may be used:
-
- floating_point = 0;
- SECTIONS
- {
- .text :
- {
- *(.text)
- _etext = .;
- }
- _bdata = (. + 3) & ~ 3;
- .data : { *(.data) }
- }
- In this example, the symbol `floating_point' will be defined as
-zero. The symbol `_etext' will be defined as the address following the
-last `.text' input section. The symbol `_bdata' will be defined as the
-address following the `.text' output section aligned upward to a 4 byte
-boundary.
-
-\1f
-File: ld.info, Node: PROVIDE, Next: PROVIDE_HIDDEN, Prev: Simple Assignments, Up: Assignments
-
-3.5.2 PROVIDE
--------------
-
-In some cases, it is desirable for a linker script to define a symbol
-only if it is referenced and is not defined by any object included in
-the link. For example, traditional linkers defined the symbol `etext'.
-However, ANSI C requires that the user be able to use `etext' as a
-function name without encountering an error. The `PROVIDE' keyword may
-be used to define a symbol, such as `etext', only if it is referenced
-but not defined. The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.
-
- Here is an example of using `PROVIDE' to define `etext':
- SECTIONS
- {
- .text :
- {
- *(.text)
- _etext = .;
- PROVIDE(etext = .);
- }
- }
-
- In this example, if the program defines `_etext' (with a leading
-underscore), the linker will give a multiple definition error. If, on
-the other hand, the program defines `etext' (with no leading
-underscore), the linker will silently use the definition in the program.
-If the program references `etext' but does not define it, the linker
-will use the definition in the linker script.
-
-\1f
-File: ld.info, Node: PROVIDE_HIDDEN, Next: Source Code Reference, Prev: PROVIDE, Up: Assignments
-
-3.5.3 PROVIDE_HIDDEN
---------------------
-
-Similar to `PROVIDE'. For ELF targeted ports, the symbol will be
-hidden and won't be exported.
-
-\1f
-File: ld.info, Node: Source Code Reference, Prev: PROVIDE_HIDDEN, Up: Assignments
-
-3.5.4 Source Code Reference
----------------------------
-
-Accessing a linker script defined variable from source code is not
-intuitive. In particular a linker script symbol is not equivalent to a
-variable declaration in a high level language, it is instead a symbol
-that does not have a value.
-
- Before going further, it is important to note that compilers often
-transform names in the source code into different names when they are
-stored in the symbol table. For example, Fortran compilers commonly
-prepend or append an underscore, and C++ performs extensive `name
-mangling'. Therefore there might be a discrepancy between the name of
-a variable as it is used in source code and the name of the same
-variable as it is defined in a linker script. For example in C a
-linker script variable might be referred to as:
-
- extern int foo;
-
- But in the linker script it might be defined as:
-
- _foo = 1000;
-
- In the remaining examples however it is assumed that no name
-transformation has taken place.
-
- When a symbol is declared in a high level language such as C, two
-things happen. The first is that the compiler reserves enough space in
-the program's memory to hold the _value_ of the symbol. The second is
-that the compiler creates an entry in the program's symbol table which
-holds the symbol's _address_. ie the symbol table contains the address
-of the block of memory holding the symbol's value. So for example the
-following C declaration, at file scope:
-
- int foo = 1000;
-
- creates a entry called `foo' in the symbol table. This entry holds
-the address of an `int' sized block of memory where the number 1000 is
-initially stored.
-
- When a program references a symbol the compiler generates code that
-first accesses the symbol table to find the address of the symbol's
-memory block and then code to read the value from that memory block.
-So:
-
- foo = 1;
-
- looks up the symbol `foo' in the symbol table, gets the address
-associated with this symbol and then writes the value 1 into that
-address. Whereas:
-
- int * a = & foo;
-
- looks up the symbol `foo' in the symbol table, gets it address and
-then copies this address into the block of memory associated with the
-variable `a'.
-
- Linker scripts symbol declarations, by contrast, create an entry in
-the symbol table but do not assign any memory to them. Thus they are
-an address without a value. So for example the linker script
-definition:
-
- foo = 1000;
-
- creates an entry in the symbol table called `foo' which holds the
-address of memory location 1000, but nothing special is stored at
-address 1000. This means that you cannot access the _value_ of a
-linker script defined symbol - it has no value - all you can do is
-access the _address_ of a linker script defined symbol.
-
- Hence when you are using a linker script defined symbol in source
-code you should always take the address of the symbol, and never
-attempt to use its value. For example suppose you want to copy the
-contents of a section of memory called .ROM into a section called
-.FLASH and the linker script contains these declarations:
-
- start_of_ROM = .ROM;
- end_of_ROM = .ROM + sizeof (.ROM) - 1;
- start_of_FLASH = .FLASH;
-
- Then the C source code to perform the copy would be:
-
- extern char start_of_ROM, end_of_ROM, start_of_FLASH;
-
- memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
-
- Note the use of the `&' operators. These are correct.
-
-\1f
-File: ld.info, Node: SECTIONS, Next: MEMORY, Prev: Assignments, Up: Scripts
-
-3.6 SECTIONS Command
-====================
-
-The `SECTIONS' command tells the linker how to map input sections into
-output sections, and how to place the output sections in memory.
-
- The format of the `SECTIONS' command is:
- SECTIONS
- {
- SECTIONS-COMMAND
- SECTIONS-COMMAND
- ...
- }
-
- Each SECTIONS-COMMAND may of be one of the following:
-
- * an `ENTRY' command (*note Entry command: Entry Point.)
-
- * a symbol assignment (*note Assignments::)
-
- * an output section description
-
- * an overlay description
-
- The `ENTRY' command and symbol assignments are permitted inside the
-`SECTIONS' command for convenience in using the location counter in
-those commands. This can also make the linker script easier to
-understand because you can use those commands at meaningful points in
-the layout of the output file.
-
- Output section descriptions and overlay descriptions are described
-below.
-
- If you do not use a `SECTIONS' command in your linker script, the
-linker will place each input section into an identically named output
-section in the order that the sections are first encountered in the
-input files. If all input sections are present in the first file, for
-example, the order of sections in the output file will match the order
-in the first input file. The first section will be at address zero.
-
-* Menu:
-
-* Output Section Description:: Output section description
-* Output Section Name:: Output section name
-* Output Section Address:: Output section address
-* Input Section:: Input section description
-* Output Section Data:: Output section data
-* Output Section Keywords:: Output section keywords
-* Output Section Discarding:: Output section discarding
-* Output Section Attributes:: Output section attributes
-* Overlay Description:: Overlay description
-
-\1f
-File: ld.info, Node: Output Section Description, Next: Output Section Name, Up: SECTIONS
-
-3.6.1 Output Section Description
---------------------------------
-
-The full description of an output section looks like this:
- SECTION [ADDRESS] [(TYPE)] :
- [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
- {
- OUTPUT-SECTION-COMMAND
- OUTPUT-SECTION-COMMAND
- ...
- } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
-
- Most output sections do not use most of the optional section
-attributes.
-
- The whitespace around SECTION is required, so that the section name
-is unambiguous. The colon and the curly braces are also required. The
-line breaks and other white space are optional.
-
- Each OUTPUT-SECTION-COMMAND may be one of the following:
-
- * a symbol assignment (*note Assignments::)
-
- * an input section description (*note Input Section::)
-
- * data values to include directly (*note Output Section Data::)
-
- * a special output section keyword (*note Output Section Keywords::)
-
-\1f
-File: ld.info, Node: Output Section Name, Next: Output Section Address, Prev: Output Section Description, Up: SECTIONS
-
-3.6.2 Output Section Name
--------------------------
-
-The name of the output section is SECTION. SECTION must meet the
-constraints of your output format. In formats which only support a
-limited number of sections, such as `a.out', the name must be one of
-the names supported by the format (`a.out', for example, allows only
-`.text', `.data' or `.bss'). If the output format supports any number
-of sections, but with numbers and not names (as is the case for Oasys),
-the name should be supplied as a quoted numeric string. A section name
-may consist of any sequence of characters, but a name which contains
-any unusual characters such as commas must be quoted.
-
- The output section name `/DISCARD/' is special; *Note Output Section
-Discarding::.
-
-\1f
-File: ld.info, Node: Output Section Address, Next: Input Section, Prev: Output Section Name, Up: SECTIONS
-
-3.6.3 Output Section Address
-----------------------------
-
-The ADDRESS is an expression for the VMA (the virtual memory address)
-of the output section. If you do not provide ADDRESS, the linker will
-set it based on REGION if present, or otherwise based on the current
-value of the location counter.
-
- If you provide ADDRESS, the address of the output section will be
-set to precisely that. If you provide neither ADDRESS nor REGION, then
-the address of the output section will be set to the current value of
-the location counter aligned to the alignment requirements of the
-output section. The alignment requirement of the output section is the
-strictest alignment of any input section contained within the output
-section.
-
- For example,
- .text . : { *(.text) }
- and
- .text : { *(.text) }
- are subtly different. The first will set the address of the `.text'
-output section to the current value of the location counter. The
-second will set it to the current value of the location counter aligned
-to the strictest alignment of a `.text' input section.
-
- The ADDRESS may be an arbitrary expression; *Note Expressions::.
-For example, if you want to align the section on a 0x10 byte boundary,
-so that the lowest four bits of the section address are zero, you could
-do something like this:
- .text ALIGN(0x10) : { *(.text) }
- This works because `ALIGN' returns the current location counter
-aligned upward to the specified value.
-
- Specifying ADDRESS for a section will change the value of the
-location counter.
-
-\1f
-File: ld.info, Node: Input Section, Next: Output Section Data, Prev: Output Section Address, Up: SECTIONS
-
-3.6.4 Input Section Description
--------------------------------
-
-The most common output section command is an input section description.
-
- The input section description is the most basic linker script
-operation. You use output sections to tell the linker how to lay out
-your program in memory. You use input section descriptions to tell the
-linker how to map the input files into your memory layout.
-
-* Menu:
-
-* Input Section Basics:: Input section basics
-* Input Section Wildcards:: Input section wildcard patterns
-* Input Section Common:: Input section for common symbols
-* Input Section Keep:: Input section and garbage collection
-* Input Section Example:: Input section example
-
-\1f
-File: ld.info, Node: Input Section Basics, Next: Input Section Wildcards, Up: Input Section
-
-3.6.4.1 Input Section Basics
-............................
-
-An input section description consists of a file name optionally followed
-by a list of section names in parentheses.
-
- The file name and the section name may be wildcard patterns, which we
-describe further below (*note Input Section Wildcards::).
-
- The most common input section description is to include all input
-sections with a particular name in the output section. For example, to
-include all input `.text' sections, you would write:
- *(.text)
- Here the `*' is a wildcard which matches any file name. To exclude
-a list of files from matching the file name wildcard, EXCLUDE_FILE may
-be used to match all files except the ones specified in the
-EXCLUDE_FILE list. For example:
- *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
- will cause all .ctors sections from all files except `crtend.o' and
-`otherfile.o' to be included.
-
- There are two ways to include more than one section:
- *(.text .rdata)
- *(.text) *(.rdata)
- The difference between these is the order in which the `.text' and
-`.rdata' input sections will appear in the output section. In the
-first example, they will be intermingled, appearing in the same order as
-they are found in the linker input. In the second example, all `.text'
-input sections will appear first, followed by all `.rdata' input
-sections.
-
- You can specify a file name to include sections from a particular
-file. You would do this if one or more of your files contain special
-data that needs to be at a particular location in memory. For example:
- data.o(.data)
-
- If you use a file name without a list of sections, then all sections
-in the input file will be included in the output section. This is not
-commonly done, but it may by useful on occasion. For example:
- data.o
-
- When you use a file name which does not contain any wild card
-characters, the linker will first see if you also specified the file
-name on the linker command line or in an `INPUT' command. If you did
-not, the linker will attempt to open the file as an input file, as
-though it appeared on the command line. Note that this differs from an
-`INPUT' command, because the linker will not search for the file in the
-archive search path.
-
-\1f
-File: ld.info, Node: Input Section Wildcards, Next: Input Section Common, Prev: Input Section Basics, Up: Input Section
-
-3.6.4.2 Input Section Wildcard Patterns
-.......................................
-
-In an input section description, either the file name or the section
-name or both may be wildcard patterns.
-
- The file name of `*' seen in many examples is a simple wildcard
-pattern for the file name.
-
- The wildcard patterns are like those used by the Unix shell.
-
-`*'
- matches any number of characters
-
-`?'
- matches any single character
-
-`[CHARS]'
- matches a single instance of any of the CHARS; the `-' character
- may be used to specify a range of characters, as in `[a-z]' to
- match any lower case letter
-
-`\'
- quotes the following character
-
- When a file name is matched with a wildcard, the wildcard characters
-will not match a `/' character (used to separate directory names on
-Unix). A pattern consisting of a single `*' character is an exception;
-it will always match any file name, whether it contains a `/' or not.
-In a section name, the wildcard characters will match a `/' character.
-
- File name wildcard patterns only match files which are explicitly
-specified on the command line or in an `INPUT' command. The linker
-does not search directories to expand wildcards.
-
- If a file name matches more than one wildcard pattern, or if a file
-name appears explicitly and is also matched by a wildcard pattern, the
-linker will use the first match in the linker script. For example, this
-sequence of input section descriptions is probably in error, because the
-`data.o' rule will not be used:
- .data : { *(.data) }
- .data1 : { data.o(.data) }
-
- Normally, the linker will place files and sections matched by
-wildcards in the order in which they are seen during the link. You can
-change this by using the `SORT_BY_NAME' keyword, which appears before a
-wildcard pattern in parentheses (e.g., `SORT_BY_NAME(.text*)'). When
-the `SORT_BY_NAME' keyword is used, the linker will sort the files or
-sections into ascending order by name before placing them in the output
-file.
-
- `SORT_BY_ALIGNMENT' is very similar to `SORT_BY_NAME'. The
-difference is `SORT_BY_ALIGNMENT' will sort sections into ascending
-order by alignment before placing them in the output file.
-
- `SORT' is an alias for `SORT_BY_NAME'.
-
- When there are nested section sorting commands in linker script,
-there can be at most 1 level of nesting for section sorting commands.
-
- 1. `SORT_BY_NAME' (`SORT_BY_ALIGNMENT' (wildcard section pattern)).
- It will sort the input sections by name first, then by alignment
- if 2 sections have the same name.
-
- 2. `SORT_BY_ALIGNMENT' (`SORT_BY_NAME' (wildcard section pattern)).
- It will sort the input sections by alignment first, then by name
- if 2 sections have the same alignment.
-
- 3. `SORT_BY_NAME' (`SORT_BY_NAME' (wildcard section pattern)) is
- treated the same as `SORT_BY_NAME' (wildcard section pattern).
-
- 4. `SORT_BY_ALIGNMENT' (`SORT_BY_ALIGNMENT' (wildcard section
- pattern)) is treated the same as `SORT_BY_ALIGNMENT' (wildcard
- section pattern).
-
- 5. All other nested section sorting commands are invalid.
-
- When both command line section sorting option and linker script
-section sorting command are used, section sorting command always takes
-precedence over the command line option.
-
- If the section sorting command in linker script isn't nested, the
-command line option will make the section sorting command to be treated
-as nested sorting command.
-
- 1. `SORT_BY_NAME' (wildcard section pattern ) with `--sort-sections
- alignment' is equivalent to `SORT_BY_NAME' (`SORT_BY_ALIGNMENT'
- (wildcard section pattern)).
-
- 2. `SORT_BY_ALIGNMENT' (wildcard section pattern) with
- `--sort-section name' is equivalent to `SORT_BY_ALIGNMENT'
- (`SORT_BY_NAME' (wildcard section pattern)).
-
- If the section sorting command in linker script is nested, the
-command line option will be ignored.
-
- If you ever get confused about where input sections are going, use
-the `-M' linker option to generate a map file. The map file shows
-precisely how input sections are mapped to output sections.
-
- This example shows how wildcard patterns might be used to partition
-files. This linker script directs the linker to place all `.text'
-sections in `.text' and all `.bss' sections in `.bss'. The linker will
-place the `.data' section from all files beginning with an upper case
-character in `.DATA'; for all other files, the linker will place the
-`.data' section in `.data'.
- SECTIONS {
- .text : { *(.text) }
- .DATA : { [A-Z]*(.data) }
- .data : { *(.data) }
- .bss : { *(.bss) }
- }
-
-\1f
-File: ld.info, Node: Input Section Common, Next: Input Section Keep, Prev: Input Section Wildcards, Up: Input Section
-
-3.6.4.3 Input Section for Common Symbols
-........................................
-
-A special notation is needed for common symbols, because in many object
-file formats common symbols do not have a particular input section. The
-linker treats common symbols as though they are in an input section
-named `COMMON'.
-
- You may use file names with the `COMMON' section just as with any
-other input sections. You can use this to place common symbols from a
-particular input file in one section while common symbols from other
-input files are placed in another section.
-
- In most cases, common symbols in input files will be placed in the
-`.bss' section in the output file. For example:
- .bss { *(.bss) *(COMMON) }
-
- Some object file formats have more than one type of common symbol.
-For example, the MIPS ELF object file format distinguishes standard
-common symbols and small common symbols. In this case, the linker will
-use a different special section name for other types of common symbols.
-In the case of MIPS ELF, the linker uses `COMMON' for standard common
-symbols and `.scommon' for small common symbols. This permits you to
-map the different types of common symbols into memory at different
-locations.
-
- You will sometimes see `[COMMON]' in old linker scripts. This
-notation is now considered obsolete. It is equivalent to `*(COMMON)'.
-
-\1f
-File: ld.info, Node: Input Section Keep, Next: Input Section Example, Prev: Input Section Common, Up: Input Section
-
-3.6.4.4 Input Section and Garbage Collection
-............................................
-
-When link-time garbage collection is in use (`--gc-sections'), it is
-often useful to mark sections that should not be eliminated. This is
-accomplished by surrounding an input section's wildcard entry with
-`KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT_BY_NAME(*)(.ctors))'.
-
-\1f
-File: ld.info, Node: Input Section Example, Prev: Input Section Keep, Up: Input Section
-
-3.6.4.5 Input Section Example
-.............................
-
-The following example is a complete linker script. It tells the linker
-to read all of the sections from file `all.o' and place them at the
-start of output section `outputa' which starts at location `0x10000'.
-All of section `.input1' from file `foo.o' follows immediately, in the
-same output section. All of section `.input2' from `foo.o' goes into
-output section `outputb', followed by section `.input1' from `foo1.o'.
-All of the remaining `.input1' and `.input2' sections from any files
-are written to output section `outputc'.
-
- SECTIONS {
- outputa 0x10000 :
- {
- all.o
- foo.o (.input1)
- }
- outputb :
- {
- foo.o (.input2)
- foo1.o (.input1)
- }
- outputc :
- {
- *(.input1)
- *(.input2)
- }
- }
-
-\1f
-File: ld.info, Node: Output Section Data, Next: Output Section Keywords, Prev: Input Section, Up: SECTIONS
-
-3.6.5 Output Section Data
--------------------------
-
-You can include explicit bytes of data in an output section by using
-`BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
-command. Each keyword is followed by an expression in parentheses
-providing the value to store (*note Expressions::). The value of the
-expression is stored at the current value of the location counter.
-
- The `BYTE', `SHORT', `LONG', and `QUAD' commands store one, two,
-four, and eight bytes (respectively). After storing the bytes, the
-location counter is incremented by the number of bytes stored.
-
- For example, this will store the byte 1 followed by the four byte
-value of the symbol `addr':
- BYTE(1)
- LONG(addr)
-
- When using a 64 bit host or target, `QUAD' and `SQUAD' are the same;
-they both store an 8 byte, or 64 bit, value. When both host and target
-are 32 bits, an expression is computed as 32 bits. In this case `QUAD'
-stores a 32 bit value zero extended to 64 bits, and `SQUAD' stores a 32
-bit value sign extended to 64 bits.
-
- If the object file format of the output file has an explicit
-endianness, which is the normal case, the value will be stored in that
-endianness. When the object file format does not have an explicit
-endianness, as is true of, for example, S-records, the value will be
-stored in the endianness of the first input object file.
-
- Note--these commands only work inside a section description and not
-between them, so the following will produce an error from the linker:
- SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
- whereas this will work:
- SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }
-
- You may use the `FILL' command to set the fill pattern for the
-current section. It is followed by an expression in parentheses. Any
-otherwise unspecified regions of memory within the section (for example,
-gaps left due to the required alignment of input sections) are filled
-with the value of the expression, repeated as necessary. A `FILL'
-statement covers memory locations after the point at which it occurs in
-the section definition; by including more than one `FILL' statement,
-you can have different fill patterns in different parts of an output
-section.
-
- This example shows how to fill unspecified regions of memory with the
-value `0x90':
- FILL(0x90909090)
-
- The `FILL' command is similar to the `=FILLEXP' output section
-attribute, but it only affects the part of the section following the
-`FILL' command, rather than the entire section. If both are used, the
-`FILL' command takes precedence. *Note Output Section Fill::, for
-details on the fill expression.
-
-\1f
-File: ld.info, Node: Output Section Keywords, Next: Output Section Discarding, Prev: Output Section Data, Up: SECTIONS
-
-3.6.6 Output Section Keywords
------------------------------
-
-There are a couple of keywords which can appear as output section
-commands.
-
-`CREATE_OBJECT_SYMBOLS'
- The command tells the linker to create a symbol for each input
- file. The name of each symbol will be the name of the
- corresponding input file. The section of each symbol will be the
- output section in which the `CREATE_OBJECT_SYMBOLS' command
- appears.
-
- This is conventional for the a.out object file format. It is not
- normally used for any other object file format.
-
-`CONSTRUCTORS'
- When linking using the a.out object file format, the linker uses an
- unusual set construct to support C++ global constructors and
- destructors. When linking object file formats which do not support
- arbitrary sections, such as ECOFF and XCOFF, the linker will
- automatically recognize C++ global constructors and destructors by
- name. For these object file formats, the `CONSTRUCTORS' command
- tells the linker to place constructor information in the output
- section where the `CONSTRUCTORS' command appears. The
- `CONSTRUCTORS' command is ignored for other object file formats.
-
- The symbol `__CTOR_LIST__' marks the start of the global
- constructors, and the symbol `__CTOR_END__' marks the end.
- Similarly, `__DTOR_LIST__' and `__DTOR_END__' mark the start and
- end of the global destructors. The first word in the list is the
- number of entries, followed by the address of each constructor or
- destructor, followed by a zero word. The compiler must arrange to
- actually run the code. For these object file formats GNU C++
- normally calls constructors from a subroutine `__main'; a call to
- `__main' is automatically inserted into the startup code for
- `main'. GNU C++ normally runs destructors either by using
- `atexit', or directly from the function `exit'.
-
- For object file formats such as `COFF' or `ELF' which support
- arbitrary section names, GNU C++ will normally arrange to put the
- addresses of global constructors and destructors into the `.ctors'
- and `.dtors' sections. Placing the following sequence into your
- linker script will build the sort of table which the GNU C++
- runtime code expects to see.
-
- __CTOR_LIST__ = .;
- LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
- *(.ctors)
- LONG(0)
- __CTOR_END__ = .;
- __DTOR_LIST__ = .;
- LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
- *(.dtors)
- LONG(0)
- __DTOR_END__ = .;
-
- If you are using the GNU C++ support for initialization priority,
- which provides some control over the order in which global
- constructors are run, you must sort the constructors at link time
- to ensure that they are executed in the correct order. When using
- the `CONSTRUCTORS' command, use `SORT_BY_NAME(CONSTRUCTORS)'
- instead. When using the `.ctors' and `.dtors' sections, use
- `*(SORT_BY_NAME(.ctors))' and `*(SORT_BY_NAME(.dtors))' instead of
- just `*(.ctors)' and `*(.dtors)'.
-
- Normally the compiler and linker will handle these issues
- automatically, and you will not need to concern yourself with
- them. However, you may need to consider this if you are using C++
- and writing your own linker scripts.
-
-
-\1f
-File: ld.info, Node: Output Section Discarding, Next: Output Section Attributes, Prev: Output Section Keywords, Up: SECTIONS
-
-3.6.7 Output Section Discarding
--------------------------------
-
-The linker will not create output sections with no contents. This is
-for convenience when referring to input sections that may or may not be
-present in any of the input files. For example:
- .foo : { *(.foo) }
- will only create a `.foo' section in the output file if there is a
-`.foo' section in at least one input file, and if the input sections
-are not all empty. Other link script directives that allocate space in
-an output section will also create the output section.
-
- The linker will ignore address assignments (*note Output Section
-Address::) on discarded output sections, except when the linker script
-defines symbols in the output section. In that case the linker will
-obey the address assignments, possibly advancing dot even though the
-section is discarded.
-
- The special output section name `/DISCARD/' may be used to discard
-input sections. Any input sections which are assigned to an output
-section named `/DISCARD/' are not included in the output file.
-
-\1f
-File: ld.info, Node: Output Section Attributes, Next: Overlay Description, Prev: Output Section Discarding, Up: SECTIONS
-
-3.6.8 Output Section Attributes
--------------------------------
-
-We showed above that the full description of an output section looked
-like this:
- SECTION [ADDRESS] [(TYPE)] :
- [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
- {
- OUTPUT-SECTION-COMMAND
- OUTPUT-SECTION-COMMAND
- ...
- } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
-We've already described SECTION, ADDRESS, and
-OUTPUT-SECTION-COMMAND. In this section we will describe the remaining
-section attributes.
-
-* Menu:
-
-* Output Section Type:: Output section type
-* Output Section LMA:: Output section LMA
-* Forced Output Alignment:: Forced Output Alignment
-* Forced Input Alignment:: Forced Input Alignment
-* Output Section Region:: Output section region
-* Output Section Phdr:: Output section phdr
-* Output Section Fill:: Output section fill
-
-\1f
-File: ld.info, Node: Output Section Type, Next: Output Section LMA, Up: Output Section Attributes
-
-3.6.8.1 Output Section Type
-...........................
-
-Each output section may have a type. The type is a keyword in
-parentheses. The following types are defined:
-
-`NOLOAD'
- The section should be marked as not loadable, so that it will not
- be loaded into memory when the program is run.
-
-`DSECT'
-`COPY'
-`INFO'
-`OVERLAY'
- These type names are supported for backward compatibility, and are
- rarely used. They all have the same effect: the section should be
- marked as not allocatable, so that no memory is allocated for the
- section when the program is run.
-
- The linker normally sets the attributes of an output section based on
-the input sections which map into it. You can override this by using
-the section type. For example, in the script sample below, the `ROM'
-section is addressed at memory location `0' and does not need to be
-loaded when the program is run. The contents of the `ROM' section will
-appear in the linker output file as usual.
- SECTIONS {
- ROM 0 (NOLOAD) : { ... }
- ...
- }
-
-\1f
-File: ld.info, Node: Output Section LMA, Next: Forced Output Alignment, Prev: Output Section Type, Up: Output Section Attributes
-
-3.6.8.2 Output Section LMA
-..........................
-
-Every section has a virtual address (VMA) and a load address (LMA); see
-*Note Basic Script Concepts::. The address expression which may appear
-in an output section description sets the VMA (*note Output Section
-Address::).
-
- The expression LMA that follows the `AT' keyword specifies the load
-address of the section.
-
- Alternatively, with `AT>LMA_REGION' expression, you may specify a
-memory region for the section's load address. *Note MEMORY::. Note
-that if the section has not had a VMA assigned to it then the linker
-will use the LMA_REGION as the VMA region as well.
-
- If neither `AT' nor `AT>' is specified for an allocatable section,
-the linker will set the LMA such that the difference between VMA and
-LMA for the section is the same as the preceding output section in the
-same region. If there is no preceding output section or the section is
-not allocatable, the linker will set the LMA equal to the VMA. *Note
-Output Section Region::.
-
- This feature is designed to make it easy to build a ROM image. For
-example, the following linker script creates three output sections: one
-called `.text', which starts at `0x1000', one called `.mdata', which is
-loaded at the end of the `.text' section even though its VMA is
-`0x2000', and one called `.bss' to hold uninitialized data at address
-`0x3000'. The symbol `_data' is defined with the value `0x2000', which
-shows that the location counter holds the VMA value, not the LMA value.
-
- SECTIONS
- {
- .text 0x1000 : { *(.text) _etext = . ; }
- .mdata 0x2000 :
- AT ( ADDR (.text) + SIZEOF (.text) )
- { _data = . ; *(.data); _edata = . ; }
- .bss 0x3000 :
- { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;}
- }
-
- The run-time initialization code for use with a program generated
-with this linker script would include something like the following, to
-copy the initialized data from the ROM image to its runtime address.
-Notice how this code takes advantage of the symbols defined by the
-linker script.
-
- extern char _etext, _data, _edata, _bstart, _bend;
- char *src = &_etext;
- char *dst = &_data;
-
- /* ROM has data at end of text; copy it. */
- while (dst < &_edata) {
- *dst++ = *src++;
- }
-
- /* Zero bss */
- for (dst = &_bstart; dst< &_bend; dst++)
- *dst = 0;
-
-\1f
-File: ld.info, Node: Forced Output Alignment, Next: Forced Input Alignment, Prev: Output Section LMA, Up: Output Section Attributes
-
-3.6.8.3 Forced Output Alignment
-...............................
-
-You can increase an output section's alignment by using ALIGN.
-
-\1f
-File: ld.info, Node: Forced Input Alignment, Next: Output Section Region, Prev: Forced Output Alignment, Up: Output Section Attributes
-
-3.6.8.4 Forced Input Alignment
-..............................
-
-You can force input section alignment within an output section by using
-SUBALIGN. The value specified overrides any alignment given by input
-sections, whether larger or smaller.
-
-\1f
-File: ld.info, Node: Output Section Region, Next: Output Section Phdr, Prev: Forced Input Alignment, Up: Output Section Attributes
-
-3.6.8.5 Output Section Region
-.............................
-
-You can assign a section to a previously defined region of memory by
-using `>REGION'. *Note MEMORY::.
-
- Here is a simple example:
- MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
- SECTIONS { ROM : { *(.text) } >rom }
-
-\1f
-File: ld.info, Node: Output Section Phdr, Next: Output Section Fill, Prev: Output Section Region, Up: Output Section Attributes
-
-3.6.8.6 Output Section Phdr
-...........................
-
-You can assign a section to a previously defined program segment by
-using `:PHDR'. *Note PHDRS::. If a section is assigned to one or more
-segments, then all subsequent allocated sections will be assigned to
-those segments as well, unless they use an explicitly `:PHDR' modifier.
-You can use `:NONE' to tell the linker to not put the section in any
-segment at all.
-
- Here is a simple example:
- PHDRS { text PT_LOAD ; }
- SECTIONS { .text : { *(.text) } :text }
-
-\1f
-File: ld.info, Node: Output Section Fill, Prev: Output Section Phdr, Up: Output Section Attributes
-
-3.6.8.7 Output Section Fill
-...........................
-
-You can set the fill pattern for an entire section by using `=FILLEXP'.
-FILLEXP is an expression (*note Expressions::). Any otherwise
-unspecified regions of memory within the output section (for example,
-gaps left due to the required alignment of input sections) will be
-filled with the value, repeated as necessary. If the fill expression
-is a simple hex number, ie. a string of hex digit starting with `0x'
-and without a trailing `k' or `M', then an arbitrarily long sequence of
-hex digits can be used to specify the fill pattern; Leading zeros
-become part of the pattern too. For all other cases, including extra
-parentheses or a unary `+', the fill pattern is the four least
-significant bytes of the value of the expression. In all cases, the
-number is big-endian.
-
- You can also change the fill value with a `FILL' command in the
-output section commands; (*note Output Section Data::).
-
- Here is a simple example:
- SECTIONS { .text : { *(.text) } =0x90909090 }
-
-\1f
-File: ld.info, Node: Overlay Description, Prev: Output Section Attributes, Up: SECTIONS
-
-3.6.9 Overlay Description
--------------------------
-
-An overlay description provides an easy way to describe sections which
-are to be loaded as part of a single memory image but are to be run at
-the same memory address. At run time, some sort of overlay manager will
-copy the overlaid sections in and out of the runtime memory address as
-required, perhaps by simply manipulating addressing bits. This approach
-can be useful, for example, when a certain region of memory is faster
-than another.
-
- Overlays are described using the `OVERLAY' command. The `OVERLAY'
-command is used within a `SECTIONS' command, like an output section
-description. The full syntax of the `OVERLAY' command is as follows:
- OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
- {
- SECNAME1
- {
- OUTPUT-SECTION-COMMAND
- OUTPUT-SECTION-COMMAND
- ...
- } [:PHDR...] [=FILL]
- SECNAME2
- {
- OUTPUT-SECTION-COMMAND
- OUTPUT-SECTION-COMMAND
- ...
- } [:PHDR...] [=FILL]
- ...
- } [>REGION] [:PHDR...] [=FILL]
-
- Everything is optional except `OVERLAY' (a keyword), and each
-section must have a name (SECNAME1 and SECNAME2 above). The section
-definitions within the `OVERLAY' construct are identical to those
-within the general `SECTIONS' contruct (*note SECTIONS::), except that
-no addresses and no memory regions may be defined for sections within
-an `OVERLAY'.
-
- The sections are all defined with the same starting address. The
-load addresses of the sections are arranged such that they are
-consecutive in memory starting at the load address used for the
-`OVERLAY' as a whole (as with normal section definitions, the load
-address is optional, and defaults to the start address; the start
-address is also optional, and defaults to the current value of the
-location counter).
-
- If the `NOCROSSREFS' keyword is used, and there any references among
-the sections, the linker will report an error. Since the sections all
-run at the same address, it normally does not make sense for one
-section to refer directly to another. *Note NOCROSSREFS: Miscellaneous
-Commands.
-
- For each section within the `OVERLAY', the linker automatically
-provides two symbols. The symbol `__load_start_SECNAME' is defined as
-the starting load address of the section. The symbol
-`__load_stop_SECNAME' is defined as the final load address of the
-section. Any characters within SECNAME which are not legal within C
-identifiers are removed. C (or assembler) code may use these symbols
-to move the overlaid sections around as necessary.
-
- At the end of the overlay, the value of the location counter is set
-to the start address of the overlay plus the size of the largest
-section.
-
- Here is an example. Remember that this would appear inside a
-`SECTIONS' construct.
- OVERLAY 0x1000 : AT (0x4000)
- {
- .text0 { o1/*.o(.text) }
- .text1 { o2/*.o(.text) }
- }
-This will define both `.text0' and `.text1' to start at address
-0x1000. `.text0' will be loaded at address 0x4000, and `.text1' will
-be loaded immediately after `.text0'. The following symbols will be
-defined if referenced: `__load_start_text0', `__load_stop_text0',
-`__load_start_text1', `__load_stop_text1'.
-
- C code to copy overlay `.text1' into the overlay area might look
-like the following.
-
- extern char __load_start_text1, __load_stop_text1;
- memcpy ((char *) 0x1000, &__load_start_text1,
- &__load_stop_text1 - &__load_start_text1);
-
- Note that the `OVERLAY' command is just syntactic sugar, since
-everything it does can be done using the more basic commands. The above
-example could have been written identically as follows.
-
- .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
- PROVIDE (__load_start_text0 = LOADADDR (.text0));
- PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
- .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
- PROVIDE (__load_start_text1 = LOADADDR (.text1));
- PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
- . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
-
-\1f
-File: ld.info, Node: MEMORY, Next: PHDRS, Prev: SECTIONS, Up: Scripts
-
-3.7 MEMORY Command
-==================
-
-The linker's default configuration permits allocation of all available
-memory. You can override this by using the `MEMORY' command.
-
- The `MEMORY' command describes the location and size of blocks of
-memory in the target. You can use it to describe which memory regions
-may be used by the linker, and which memory regions it must avoid. You
-can then assign sections to particular memory regions. The linker will
-set section addresses based on the memory regions, and will warn about
-regions that become too full. The linker will not shuffle sections
-around to fit into the available regions.
-
- A linker script may contain at most one use of the `MEMORY' command.
-However, you can define as many blocks of memory within it as you
-wish. The syntax is:
- MEMORY
- {
- NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
- ...
- }
-
- The NAME is a name used in the linker script to refer to the region.
-The region name has no meaning outside of the linker script. Region
-names are stored in a separate name space, and will not conflict with
-symbol names, file names, or section names. Each memory region must
-have a distinct name.
-
- The ATTR string is an optional list of attributes that specify
-whether to use a particular memory region for an input section which is
-not explicitly mapped in the linker script. As described in *Note
-SECTIONS::, if you do not specify an output section for some input
-section, the linker will create an output section with the same name as
-the input section. If you define region attributes, the linker will use
-them to select the memory region for the output section that it creates.
-
- The ATTR string must consist only of the following characters:
-`R'
- Read-only section
-
-`W'
- Read/write section
-
-`X'
- Executable section
-
-`A'
- Allocatable section
-
-`I'
- Initialized section
-
-`L'
- Same as `I'
-
-`!'
- Invert the sense of any of the preceding attributes
-
- If a unmapped section matches any of the listed attributes other than
-`!', it will be placed in the memory region. The `!' attribute
-reverses this test, so that an unmapped section will be placed in the
-memory region only if it does not match any of the listed attributes.
-
- The ORIGIN is an numerical expression for the start address of the
-memory region. The expression must evaluate to a constant and it
-cannot involve any symbols. The keyword `ORIGIN' may be abbreviated to
-`org' or `o' (but not, for example, `ORG').
-
- The LEN is an expression for the size in bytes of the memory region.
-As with the ORIGIN expression, the expression must be numerical only
-and must evaluate to a constant. The keyword `LENGTH' may be
-abbreviated to `len' or `l'.
-
- In the following example, we specify that there are two memory
-regions available for allocation: one starting at `0' for 256 kilobytes,
-and the other starting at `0x40000000' for four megabytes. The linker
-will place into the `rom' memory region every section which is not
-explicitly mapped into a memory region, and is either read-only or
-executable. The linker will place other sections which are not
-explicitly mapped into a memory region into the `ram' memory region.
-
- MEMORY
- {
- rom (rx) : ORIGIN = 0, LENGTH = 256K
- ram (!rx) : org = 0x40000000, l = 4M
- }
-
- Once you define a memory region, you can direct the linker to place
-specific output sections into that memory region by using the `>REGION'
-output section attribute. For example, if you have a memory region
-named `mem', you would use `>mem' in the output section definition.
-*Note Output Section Region::. If no address was specified for the
-output section, the linker will set the address to the next available
-address within the memory region. If the combined output sections
-directed to a memory region are too large for the region, the linker
-will issue an error message.
-
- It is possible to access the origin and length of a memory in an
-expression via the `ORIGIN(MEMORY)' and `LENGTH(MEMORY)' functions:
-
- _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
-
-\1f
-File: ld.info, Node: PHDRS, Next: VERSION, Prev: MEMORY, Up: Scripts
-
-3.8 PHDRS Command
-=================
-
-The ELF object file format uses "program headers", also knows as
-"segments". The program headers describe how the program should be
-loaded into memory. You can print them out by using the `objdump'
-program with the `-p' option.
-
- When you run an ELF program on a native ELF system, the system loader
-reads the program headers in order to figure out how to load the
-program. This will only work if the program headers are set correctly.
-This manual does not describe the details of how the system loader
-interprets program headers; for more information, see the ELF ABI.
-
- The linker will create reasonable program headers by default.
-However, in some cases, you may need to specify the program headers more
-precisely. You may use the `PHDRS' command for this purpose. When the
-linker sees the `PHDRS' command in the linker script, it will not
-create any program headers other than the ones specified.
-
- The linker only pays attention to the `PHDRS' command when
-generating an ELF output file. In other cases, the linker will simply
-ignore `PHDRS'.
-
- This is the syntax of the `PHDRS' command. The words `PHDRS',
-`FILEHDR', `AT', and `FLAGS' are keywords.
-
- PHDRS
- {
- NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
- [ FLAGS ( FLAGS ) ] ;
- }
-
- The NAME is used only for reference in the `SECTIONS' command of the
-linker script. It is not put into the output file. Program header
-names are stored in a separate name space, and will not conflict with
-symbol names, file names, or section names. Each program header must
-have a distinct name.
-
- Certain program header types describe segments of memory which the
-system loader will load from the file. In the linker script, you
-specify the contents of these segments by placing allocatable output
-sections in the segments. You use the `:PHDR' output section attribute
-to place a section in a particular segment. *Note Output Section
-Phdr::.
-
- It is normal to put certain sections in more than one segment. This
-merely implies that one segment of memory contains another. You may
-repeat `:PHDR', using it once for each segment which should contain the
-section.
-
- If you place a section in one or more segments using `:PHDR', then
-the linker will place all subsequent allocatable sections which do not
-specify `:PHDR' in the same segments. This is for convenience, since
-generally a whole set of contiguous sections will be placed in a single
-segment. You can use `:NONE' to override the default segment and tell
-the linker to not put the section in any segment at all.
-
- You may use the `FILEHDR' and `PHDRS' keywords appear after the
-program header type to further describe the contents of the segment.
-The `FILEHDR' keyword means that the segment should include the ELF
-file header. The `PHDRS' keyword means that the segment should include
-the ELF program headers themselves.
-
- The TYPE may be one of the following. The numbers indicate the
-value of the keyword.
-
-`PT_NULL' (0)
- Indicates an unused program header.
-
-`PT_LOAD' (1)
- Indicates that this program header describes a segment to be
- loaded from the file.
-
-`PT_DYNAMIC' (2)
- Indicates a segment where dynamic linking information can be found.
-
-`PT_INTERP' (3)
- Indicates a segment where the name of the program interpreter may
- be found.
-
-`PT_NOTE' (4)
- Indicates a segment holding note information.
-
-`PT_SHLIB' (5)
- A reserved program header type, defined but not specified by the
- ELF ABI.
-
-`PT_PHDR' (6)
- Indicates a segment where the program headers may be found.
-
-EXPRESSION
- An expression giving the numeric type of the program header. This
- may be used for types not defined above.
-
- You can specify that a segment should be loaded at a particular
-address in memory by using an `AT' expression. This is identical to the
-`AT' command used as an output section attribute (*note Output Section
-LMA::). The `AT' command for a program header overrides the output
-section attribute.
-
- The linker will normally set the segment flags based on the sections
-which comprise the segment. You may use the `FLAGS' keyword to
-explicitly specify the segment flags. The value of FLAGS must be an
-integer. It is used to set the `p_flags' field of the program header.
-
- Here is an example of `PHDRS'. This shows a typical set of program
-headers used on a native ELF system.
-
- PHDRS
- {
- headers PT_PHDR PHDRS ;
- interp PT_INTERP ;
- text PT_LOAD FILEHDR PHDRS ;
- data PT_LOAD ;
- dynamic PT_DYNAMIC ;
- }
-
- SECTIONS
- {
- . = SIZEOF_HEADERS;
- .interp : { *(.interp) } :text :interp
- .text : { *(.text) } :text
- .rodata : { *(.rodata) } /* defaults to :text */
- ...
- . = . + 0x1000; /* move to a new page in memory */
- .data : { *(.data) } :data
- .dynamic : { *(.dynamic) } :data :dynamic
- ...
- }
-
-\1f
-File: ld.info, Node: VERSION, Next: Expressions, Prev: PHDRS, Up: Scripts
-
-3.9 VERSION Command
-===================
-
-The linker supports symbol versions when using ELF. Symbol versions are
-only useful when using shared libraries. The dynamic linker can use
-symbol versions to select a specific version of a function when it runs
-a program that may have been linked against an earlier version of the
-shared library.
-
- You can include a version script directly in the main linker script,
-or you can supply the version script as an implicit linker script. You
-can also use the `--version-script' linker option.
-
- The syntax of the `VERSION' command is simply
- VERSION { version-script-commands }
-
- The format of the version script commands is identical to that used
-by Sun's linker in Solaris 2.5. The version script defines a tree of
-version nodes. You specify the node names and interdependencies in the
-version script. You can specify which symbols are bound to which
-version nodes, and you can reduce a specified set of symbols to local
-scope so that they are not globally visible outside of the shared
-library.
-
- The easiest way to demonstrate the version script language is with a
-few examples.
-
- VERS_1.1 {
- global:
- foo1;
- local:
- old*;
- original*;
- new*;
- };
-
- VERS_1.2 {
- foo2;
- } VERS_1.1;
-
- VERS_2.0 {
- bar1; bar2;
- extern "C++" {
- ns::*;
- "int f(int, double)";
- }
- } VERS_1.2;
-
- This example version script defines three version nodes. The first
-version node defined is `VERS_1.1'; it has no other dependencies. The
-script binds the symbol `foo1' to `VERS_1.1'. It reduces a number of
-symbols to local scope so that they are not visible outside of the
-shared library; this is done using wildcard patterns, so that any
-symbol whose name begins with `old', `original', or `new' is matched.
-The wildcard patterns available are the same as those used in the shell
-when matching filenames (also known as "globbing"). However, if you
-specify the symbol name inside double quotes, then the name is treated
-as literal, rather than as a glob pattern.
-
- Next, the version script defines node `VERS_1.2'. This node depends
-upon `VERS_1.1'. The script binds the symbol `foo2' to the version
-node `VERS_1.2'.
-
- Finally, the version script defines node `VERS_2.0'. This node
-depends upon `VERS_1.2'. The scripts binds the symbols `bar1' and
-`bar2' are bound to the version node `VERS_2.0'.
-
- When the linker finds a symbol defined in a library which is not
-specifically bound to a version node, it will effectively bind it to an
-unspecified base version of the library. You can bind all otherwise
-unspecified symbols to a given version node by using `global: *;'
-somewhere in the version script.
-
- The names of the version nodes have no specific meaning other than
-what they might suggest to the person reading them. The `2.0' version
-could just as well have appeared in between `1.1' and `1.2'. However,
-this would be a confusing way to write a version script.
-
- Node name can be omitted, provided it is the only version node in
-the version script. Such version script doesn't assign any versions to
-symbols, only selects which symbols will be globally visible out and
-which won't.
-
- { global: foo; bar; local: *; };
-
- When you link an application against a shared library that has
-versioned symbols, the application itself knows which version of each
-symbol it requires, and it also knows which version nodes it needs from
-each shared library it is linked against. Thus at runtime, the dynamic
-loader can make a quick check to make sure that the libraries you have
-linked against do in fact supply all of the version nodes that the
-application will need to resolve all of the dynamic symbols. In this
-way it is possible for the dynamic linker to know with certainty that
-all external symbols that it needs will be resolvable without having to
-search for each symbol reference.
-
- The symbol versioning is in effect a much more sophisticated way of
-doing minor version checking that SunOS does. The fundamental problem
-that is being addressed here is that typically references to external
-functions are bound on an as-needed basis, and are not all bound when
-the application starts up. If a shared library is out of date, a
-required interface may be missing; when the application tries to use
-that interface, it may suddenly and unexpectedly fail. With symbol
-versioning, the user will get a warning when they start their program if
-the libraries being used with the application are too old.
-
- There are several GNU extensions to Sun's versioning approach. The
-first of these is the ability to bind a symbol to a version node in the
-source file where the symbol is defined instead of in the versioning
-script. This was done mainly to reduce the burden on the library
-maintainer. You can do this by putting something like:
- __asm__(".symver original_foo,foo@VERS_1.1");
- in the C source file. This renames the function `original_foo' to
-be an alias for `foo' bound to the version node `VERS_1.1'. The
-`local:' directive can be used to prevent the symbol `original_foo'
-from being exported. A `.symver' directive takes precedence over a
-version script.
-
- The second GNU extension is to allow multiple versions of the same
-function to appear in a given shared library. In this way you can make
-an incompatible change to an interface without increasing the major
-version number of the shared library, while still allowing applications
-linked against the old interface to continue to function.
-
- To do this, you must use multiple `.symver' directives in the source
-file. Here is an example:
-
- __asm__(".symver original_foo,foo@");
- __asm__(".symver old_foo,foo@VERS_1.1");
- __asm__(".symver old_foo1,foo@VERS_1.2");
- __asm__(".symver new_foo,foo@@VERS_2.0");
-
- In this example, `foo@' represents the symbol `foo' bound to the
-unspecified base version of the symbol. The source file that contains
-this example would define 4 C functions: `original_foo', `old_foo',
-`old_foo1', and `new_foo'.
-
- When you have multiple definitions of a given symbol, there needs to
-be some way to specify a default version to which external references to
-this symbol will be bound. You can do this with the `foo@@VERS_2.0'
-type of `.symver' directive. You can only declare one version of a
-symbol as the default in this manner; otherwise you would effectively
-have multiple definitions of the same symbol.
-
- If you wish to bind a reference to a specific version of the symbol
-within the shared library, you can use the aliases of convenience
-(i.e., `old_foo'), or you can use the `.symver' directive to
-specifically bind to an external version of the function in question.
-
- You can also specify the language in the version script:
-
- VERSION extern "lang" { version-script-commands }
-
- The supported `lang's are `C', `C++', and `Java'. The linker will
-iterate over the list of symbols at the link time and demangle them
-according to `lang' before matching them to the patterns specified in
-`version-script-commands'.
-
- Demangled names may contains spaces and other special characters. As
-described above, you can use a glob pattern to match demangled names,
-or you can use a double-quoted string to match the string exactly. In
-the latter case, be aware that minor differences (such as differing
-whitespace) between the version script and the demangler output will
-cause a mismatch. As the exact string generated by the demangler might
-change in the future, even if the mangled name does not, you should
-check that all of your version directives are behaving as you expect
-when you upgrade.
-
-\1f
-File: ld.info, Node: Expressions, Next: Implicit Linker Scripts, Prev: VERSION, Up: Scripts
-
-3.10 Expressions in Linker Scripts
-==================================
-
-The syntax for expressions in the linker script language is identical to
-that of C expressions. All expressions are evaluated as integers. All
-expressions are evaluated in the same size, which is 32 bits if both the
-host and target are 32 bits, and is otherwise 64 bits.
-
- You can use and set symbol values in expressions.
-
- The linker defines several special purpose builtin functions for use
-in expressions.
-
-* Menu:
-
-* Constants:: Constants
-* Symbols:: Symbol Names
-* Orphan Sections:: Orphan Sections
-* Location Counter:: The Location Counter
-* Operators:: Operators
-* Evaluation:: Evaluation
-* Expression Section:: The Section of an Expression
-* Builtin Functions:: Builtin Functions
-
-\1f
-File: ld.info, Node: Constants, Next: Symbols, Up: Expressions
-
-3.10.1 Constants
-----------------
-
-All constants are integers.
-
- As in C, the linker considers an integer beginning with `0' to be
-octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
-The linker considers other integers to be decimal.
-
- In addition, you can use the suffixes `K' and `M' to scale a
-constant by `1024' or `1024*1024' respectively. For example, the
-following all refer to the same quantity:
- _fourk_1 = 4K;
- _fourk_2 = 4096;
- _fourk_3 = 0x1000;
-
-\1f
-File: ld.info, Node: Symbols, Next: Orphan Sections, Prev: Constants, Up: Expressions
-
-3.10.2 Symbol Names
--------------------
-
-Unless quoted, symbol names start with a letter, underscore, or period
-and may include letters, digits, underscores, periods, and hyphens.
-Unquoted symbol names must not conflict with any keywords. You can
-specify a symbol which contains odd characters or has the same name as a
-keyword by surrounding the symbol name in double quotes:
- "SECTION" = 9;
- "with a space" = "also with a space" + 10;
-
- Since symbols can contain many non-alphabetic characters, it is
-safest to delimit symbols with spaces. For example, `A-B' is one
-symbol, whereas `A - B' is an expression involving subtraction.
-
-\1f
-File: ld.info, Node: Orphan Sections, Next: Location Counter, Prev: Symbols, Up: Expressions
-
-3.10.3 Orphan Sections
-----------------------
-
-Orphan sections are sections present in the input files which are not
-explicitly placed into the output file by the linker script. The
-linker will still copy these sections into the output file, but it has
-to guess as to where they should be placed. The linker uses a simple
-heuristic to do this. It attempts to place orphan sections after
-non-orphan sections of the same attribute, such as code vs data,
-loadable vs non-loadable, etc. If there is not enough room to do this
-then it places at the end of the file.
-
- For ELF targets, the attribute of the section includes section type
-as well as section flag.
-
-\1f
-File: ld.info, Node: Location Counter, Next: Operators, Prev: Orphan Sections, Up: Expressions
-
-3.10.4 The Location Counter
----------------------------
-
-The special linker variable "dot" `.' always contains the current
-output location counter. Since the `.' always refers to a location in
-an output section, it may only appear in an expression within a
-`SECTIONS' command. The `.' symbol may appear anywhere that an
-ordinary symbol is allowed in an expression.
-
- Assigning a value to `.' will cause the location counter to be
-moved. This may be used to create holes in the output section. The
-location counter may not be moved backwards inside an output section,
-and may not be moved backwards outside of an output section if so doing
-creates areas with overlapping LMAs.
-
- SECTIONS
- {
- output :
- {
- file1(.text)
- . = . + 1000;
- file2(.text)
- . += 1000;
- file3(.text)
- } = 0x12345678;
- }
- In the previous example, the `.text' section from `file1' is located
-at the beginning of the output section `output'. It is followed by a
-1000 byte gap. Then the `.text' section from `file2' appears, also
-with a 1000 byte gap following before the `.text' section from `file3'.
-The notation `= 0x12345678' specifies what data to write in the gaps
-(*note Output Section Fill::).
-
- Note: `.' actually refers to the byte offset from the start of the
-current containing object. Normally this is the `SECTIONS' statement,
-whose start address is 0, hence `.' can be used as an absolute address.
-If `.' is used inside a section description however, it refers to the
-byte offset from the start of that section, not an absolute address.
-Thus in a script like this:
-
- SECTIONS
- {
- . = 0x100
- .text: {
- *(.text)
- . = 0x200
- }
- . = 0x500
- .data: {
- *(.data)
- . += 0x600
- }
- }
-
- The `.text' section will be assigned a starting address of 0x100 and
-a size of exactly 0x200 bytes, even if there is not enough data in the
-`.text' input sections to fill this area. (If there is too much data,
-an error will be produced because this would be an attempt to move `.'
-backwards). The `.data' section will start at 0x500 and it will have
-an extra 0x600 bytes worth of space after the end of the values from
-the `.data' input sections and before the end of the `.data' output
-section itself.
-
- Setting symbols to the value of the location counter outside of an
-output section statement can result in unexpected values if the linker
-needs to place orphan sections. For example, given the following:
-
- SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
-
- start_of_data = . ;
- .data: { *(.data) }
- end_of_data = . ;
- }
-
- If the linker needs to place some input section, e.g. `.rodata', not
-mentioned in the script, it might choose to place that section between
-`.text' and `.data'. You might think the linker should place `.rodata'
-on the blank line in the above script, but blank lines are of no
-particular significance to the linker. As well, the linker doesn't
-associate the above symbol names with their sections. Instead, it
-assumes that all assignments or other statements belong to the previous
-output section, except for the special case of an assignment to `.'.
-I.e., the linker will place the orphan `.rodata' section as if the
-script was written as follows:
-
- SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
-
- start_of_data = . ;
- .rodata: { *(.rodata) }
- .data: { *(.data) }
- end_of_data = . ;
- }
-
- This may or may not be the script author's intention for the value of
-`start_of_data'. One way to influence the orphan section placement is
-to assign the location counter to itself, as the linker assumes that an
-assignment to `.' is setting the start address of a following output
-section and thus should be grouped with that section. So you could
-write:
-
- SECTIONS
- {
- start_of_text = . ;
- .text: { *(.text) }
- end_of_text = . ;
-
- . = . ;
- start_of_data = . ;
- .data: { *(.data) }
- end_of_data = . ;
- }
-
- Now, the orphan `.rodata' section will be placed between
-`end_of_text' and `start_of_data'.
-
-\1f
-File: ld.info, Node: Operators, Next: Evaluation, Prev: Location Counter, Up: Expressions
-
-3.10.5 Operators
-----------------
-
-The linker recognizes the standard C set of arithmetic operators, with
-the standard bindings and precedence levels:
- precedence associativity Operators Notes
- (highest)
- 1 left ! - ~ (1)
- 2 left * / %
- 3 left + -
- 4 left >> <<
- 5 left == != > < <= >=
- 6 left &
- 7 left |
- 8 left &&
- 9 left ||
- 10 right ? :
- 11 right &= += -= *= /= (2)
- (lowest)
- Notes: (1) Prefix operators (2) *Note Assignments::.
-
-\1f
-File: ld.info, Node: Evaluation, Next: Expression Section, Prev: Operators, Up: Expressions
-
-3.10.6 Evaluation
------------------
-
-The linker evaluates expressions lazily. It only computes the value of
-an expression when absolutely necessary.
-
- The linker needs some information, such as the value of the start
-address of the first section, and the origins and lengths of memory
-regions, in order to do any linking at all. These values are computed
-as soon as possible when the linker reads in the linker script.
-
- However, other values (such as symbol values) are not known or needed
-until after storage allocation. Such values are evaluated later, when
-other information (such as the sizes of output sections) is available
-for use in the symbol assignment expression.
-
- The sizes of sections cannot be known until after allocation, so
-assignments dependent upon these are not performed until after
-allocation.
-
- Some expressions, such as those depending upon the location counter
-`.', must be evaluated during section allocation.
-
- If the result of an expression is required, but the value is not
-available, then an error results. For example, a script like the
-following
- SECTIONS
- {
- .text 9+this_isnt_constant :
- { *(.text) }
- }
-will cause the error message `non constant expression for initial
-address'.
-
-\1f
-File: ld.info, Node: Expression Section, Next: Builtin Functions, Prev: Evaluation, Up: Expressions
-
-3.10.7 The Section of an Expression
------------------------------------
-
-When the linker evaluates an expression, the result is either absolute
-or relative to some section. A relative expression is expressed as a
-fixed offset from the base of a section.
-
- The position of the expression within the linker script determines
-whether it is absolute or relative. An expression which appears within
-an output section definition is relative to the base of the output
-section. An expression which appears elsewhere will be absolute.
-
- A symbol set to a relative expression will be relocatable if you
-request relocatable output using the `-r' option. That means that a
-further link operation may change the value of the symbol. The symbol's
-section will be the section of the relative expression.
-
- A symbol set to an absolute expression will retain the same value
-through any further link operation. The symbol will be absolute, and
-will not have any particular associated section.
-
- You can use the builtin function `ABSOLUTE' to force an expression
-to be absolute when it would otherwise be relative. For example, to
-create an absolute symbol set to the address of the end of the output
-section `.data':
- SECTIONS
- {
- .data : { *(.data) _edata = ABSOLUTE(.); }
- }
- If `ABSOLUTE' were not used, `_edata' would be relative to the
-`.data' section.
-
-\1f
-File: ld.info, Node: Builtin Functions, Prev: Expression Section, Up: Expressions
-
-3.10.8 Builtin Functions
-------------------------
-
-The linker script language includes a number of builtin functions for
-use in linker script expressions.
-
-`ABSOLUTE(EXP)'
- Return the absolute (non-relocatable, as opposed to non-negative)
- value of the expression EXP. Primarily useful to assign an
- absolute value to a symbol within a section definition, where
- symbol values are normally section relative. *Note Expression
- Section::.
-
-`ADDR(SECTION)'
- Return the absolute address (the VMA) of the named SECTION. Your
- script must previously have defined the location of that section.
- In the following example, `symbol_1' and `symbol_2' are assigned
- identical values:
- SECTIONS { ...
- .output1 :
- {
- start_of_output_1 = ABSOLUTE(.);
- ...
- }
- .output :
- {
- symbol_1 = ADDR(.output1);
- symbol_2 = start_of_output_1;
- }
- ... }
-
-`ALIGN(ALIGN)'
-`ALIGN(EXP,ALIGN)'
- Return the location counter (`.') or arbitrary expression aligned
- to the next ALIGN boundary. The single operand `ALIGN' doesn't
- change the value of the location counter--it just does arithmetic
- on it. The two operand `ALIGN' allows an arbitrary expression to
- be aligned upwards (`ALIGN(ALIGN)' is equivalent to `ALIGN(.,
- ALIGN)').
-
- Here is an example which aligns the output `.data' section to the
- next `0x2000' byte boundary after the preceding section and sets a
- variable within the section to the next `0x8000' boundary after the
- input sections:
- SECTIONS { ...
- .data ALIGN(0x2000): {
- *(.data)
- variable = ALIGN(0x8000);
- }
- ... }
- The first use of `ALIGN' in this example specifies the
- location of a section because it is used as the optional ADDRESS
- attribute of a section definition (*note Output Section
- Address::). The second use of `ALIGN' is used to defines the
- value of a symbol.
-
- The builtin function `NEXT' is closely related to `ALIGN'.
-
-`ALIGNOF(SECTION)'
- Return the alignment in bytes of the named SECTION, if that
- section has been allocated. If the section has not been allocated
- when this is evaluated, the linker will report an error. In the
- following example, the alignment of the `.output' section is
- stored as the first value in that section.
- SECTIONS{ ...
- .output {
- LONG (ALIGNOF (.output))
- ...
- }
- ... }
-
-`BLOCK(EXP)'
- This is a synonym for `ALIGN', for compatibility with older linker
- scripts. It is most often seen when setting the address of an
- output section.
-
-`DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)'
- This is equivalent to either
- (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1)))
- or
- (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE)))
- depending on whether the latter uses fewer COMMONPAGESIZE sized
- pages for the data segment (area between the result of this
- expression and `DATA_SEGMENT_END') than the former or not. If the
- latter form is used, it means COMMONPAGESIZE bytes of runtime
- memory will be saved at the expense of up to COMMONPAGESIZE wasted
- bytes in the on-disk file.
-
- This expression can only be used directly in `SECTIONS' commands,
- not in any output section descriptions and only once in the linker
- script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and
- should be the system page size the object wants to be optimized
- for (while still working on system page sizes up to MAXPAGESIZE).
-
- Example:
- . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
-
-`DATA_SEGMENT_END(EXP)'
- This defines the end of data segment for `DATA_SEGMENT_ALIGN'
- evaluation purposes.
-
- . = DATA_SEGMENT_END(.);
-
-`DATA_SEGMENT_RELRO_END(OFFSET, EXP)'
- This defines the end of the `PT_GNU_RELRO' segment when `-z relro'
- option is used. Second argument is returned. When `-z relro'
- option is not present, `DATA_SEGMENT_RELRO_END' does nothing,
- otherwise `DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is
- aligned to the most commonly used page boundary for particular
- target. If present in the linker script, it must always come in
- between `DATA_SEGMENT_ALIGN' and `DATA_SEGMENT_END'.
-
- . = DATA_SEGMENT_RELRO_END(24, .);
-
-`DEFINED(SYMBOL)'
- Return 1 if SYMBOL is in the linker global symbol table and is
- defined before the statement using DEFINED in the script, otherwise
- return 0. You can use this function to provide default values for
- symbols. For example, the following script fragment shows how to
- set a global symbol `begin' to the first location in the `.text'
- section--but if a symbol called `begin' already existed, its value
- is preserved:
-
- SECTIONS { ...
- .text : {
- begin = DEFINED(begin) ? begin : . ;
- ...
- }
- ...
- }
-
-`LENGTH(MEMORY)'
- Return the length of the memory region named MEMORY.
-
-`LOADADDR(SECTION)'
- Return the absolute LMA of the named SECTION. This is normally
- the same as `ADDR', but it may be different if the `AT' attribute
- is used in the output section definition (*note Output Section
- LMA::).
-
-`MAX(EXP1, EXP2)'
- Returns the maximum of EXP1 and EXP2.
-
-`MIN(EXP1, EXP2)'
- Returns the minimum of EXP1 and EXP2.
-
-`NEXT(EXP)'
- Return the next unallocated address that is a multiple of EXP.
- This function is closely related to `ALIGN(EXP)'; unless you use
- the `MEMORY' command to define discontinuous memory for the output
- file, the two functions are equivalent.
-
-`ORIGIN(MEMORY)'
- Return the origin of the memory region named MEMORY.
-
-`SEGMENT_START(SEGMENT, DEFAULT)'
- Return the base address of the named SEGMENT. If an explicit
- value has been given for this segment (with a command-line `-T'
- option) that value will be returned; otherwise the value will be
- DEFAULT. At present, the `-T' command-line option can only be
- used to set the base address for the "text", "data", and "bss"
- sections, but you use `SEGMENT_START' with any segment name.
-
-`SIZEOF(SECTION)'
- Return the size in bytes of the named SECTION, if that section has
- been allocated. If the section has not been allocated when this is
- evaluated, the linker will report an error. In the following
- example, `symbol_1' and `symbol_2' are assigned identical values:
- SECTIONS{ ...
- .output {
- .start = . ;
- ...
- .end = . ;
- }
- symbol_1 = .end - .start ;
- symbol_2 = SIZEOF(.output);
- ... }
-
-`SIZEOF_HEADERS'
-`sizeof_headers'
- Return the size in bytes of the output file's headers. This is
- information which appears at the start of the output file. You
- can use this number when setting the start address of the first
- section, if you choose, to facilitate paging.
-
- When producing an ELF output file, if the linker script uses the
- `SIZEOF_HEADERS' builtin function, the linker must compute the
- number of program headers before it has determined all the section
- addresses and sizes. If the linker later discovers that it needs
- additional program headers, it will report an error `not enough
- room for program headers'. To avoid this error, you must avoid
- using the `SIZEOF_HEADERS' function, or you must rework your linker
- script to avoid forcing the linker to use additional program
- headers, or you must define the program headers yourself using the
- `PHDRS' command (*note PHDRS::).
-
-\1f
-File: ld.info, Node: Implicit Linker Scripts, Prev: Expressions, Up: Scripts
-
-3.11 Implicit Linker Scripts
-============================
-
-If you specify a linker input file which the linker can not recognize as
-an object file or an archive file, it will try to read the file as a
-linker script. If the file can not be parsed as a linker script, the
-linker will report an error.
-
- An implicit linker script will not replace the default linker script.
-
- Typically an implicit linker script would contain only symbol
-assignments, or the `INPUT', `GROUP', or `VERSION' commands.
-
- Any input files read because of an implicit linker script will be
-read at the position in the command line where the implicit linker
-script was read. This can affect archive searching.
-
-\1f
-File: ld.info, Node: Machine Dependent, Next: BFD, Prev: Scripts, Up: Top
-
-4 Machine Dependent Features
-****************************
-
-`ld' has additional features on some platforms; the following sections
-describe them. Machines where `ld' has no additional functionality are
-not listed.
-
-* Menu:
-
-
-* H8/300:: `ld' and the H8/300
-
-* i960:: `ld' and the Intel 960 family
-
-* ARM:: `ld' and the ARM family
-
-* HPPA ELF32:: `ld' and HPPA 32-bit ELF
-
-* MMIX:: `ld' and MMIX
-
-* MSP430:: `ld' and MSP430
-
-* M68HC11/68HC12:: `ld' and the Motorola 68HC11 and 68HC12 families
-
-* PowerPC ELF32:: `ld' and PowerPC 32-bit ELF Support
-
-* PowerPC64 ELF64:: `ld' and PowerPC64 64-bit ELF Support
-
-* SPU ELF:: `ld' and SPU ELF Support
-
-* TI COFF:: `ld' and TI COFF
-
-* WIN32:: `ld' and WIN32 (cygwin/mingw)
-
-* Xtensa:: `ld' and Xtensa Processors
-
-\1f
-File: ld.info, Node: H8/300, Next: i960, Up: Machine Dependent
-
-4.1 `ld' and the H8/300
-=======================
-
-For the H8/300, `ld' can perform these global optimizations when you
-specify the `--relax' command-line option.
-
-_relaxing address modes_
- `ld' finds all `jsr' and `jmp' instructions whose targets are
- within eight bits, and turns them into eight-bit program-counter
- relative `bsr' and `bra' instructions, respectively.
-
-_synthesizing instructions_
- `ld' finds all `mov.b' instructions which use the sixteen-bit
- absolute address form, but refer to the top page of memory, and
- changes them to use the eight-bit address form. (That is: the
- linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
- address AA is in the top page of memory).
-
-_bit manipulation instructions_
- `ld' finds all bit manipulation instructions like `band, bclr,
- biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst,
- bxor' which use 32 bit and 16 bit absolute address form, but refer
- to the top page of memory, and changes them to use the 8 bit
- address form. (That is: the linker turns `bset #xx:3,`@'AA:32'
- into `bset #xx:3,`@'AA:8' whenever the address AA is in the top
- page of memory).
-
-_system control instructions_
- `ld' finds all `ldc.w, stc.w' instructions which use the 32 bit
- absolute address form, but refer to the top page of memory, and
- changes them to use 16 bit address form. (That is: the linker
- turns `ldc.w `@'AA:32,ccr' into `ldc.w `@'AA:16,ccr' whenever the
- address AA is in the top page of memory).
-
-\1f
-File: ld.info, Node: i960, Next: ARM, Prev: H8/300, Up: Machine Dependent
-
-4.2 `ld' and the Intel 960 Family
-=================================
-
-You can use the `-AARCHITECTURE' command line option to specify one of
-the two-letter names identifying members of the 960 family; the option
-specifies the desired output target, and warns of any incompatible
-instructions in the input files. It also modifies the linker's search
-strategy for archive libraries, to support the use of libraries
-specific to each particular architecture, by including in the search
-loop names suffixed with the string identifying the architecture.
-
- For example, if your `ld' command line included `-ACA' as well as
-`-ltry', the linker would look (in its built-in search paths, and in
-any paths you specify with `-L') for a library with the names
-
- try
- libtry.a
- tryca
- libtryca.a
-
-The first two possibilities would be considered in any event; the last
-two are due to the use of `-ACA'.
-
- You can meaningfully use `-A' more than once on a command line, since
-the 960 architecture family allows combination of target architectures;
-each use will add another pair of name variants to search for when `-l'
-specifies a library.
-
- `ld' supports the `--relax' option for the i960 family. If you
-specify `--relax', `ld' finds all `balx' and `calx' instructions whose
-targets are within 24 bits, and turns them into 24-bit program-counter
-relative `bal' and `cal' instructions, respectively. `ld' also turns
-`cal' instructions into `bal' instructions when it determines that the
-target subroutine is a leaf routine (that is, the target subroutine does
-not itself call any subroutines).
-
-\1f
-File: ld.info, Node: M68HC11/68HC12, Next: PowerPC ELF32, Prev: MSP430, Up: Machine Dependent
-
-4.3 `ld' and the Motorola 68HC11 and 68HC12 families
-====================================================
-
-4.3.1 Linker Relaxation
------------------------
-
-For the Motorola 68HC11, `ld' can perform these global optimizations
-when you specify the `--relax' command-line option.
-
-_relaxing address modes_
- `ld' finds all `jsr' and `jmp' instructions whose targets are
- within eight bits, and turns them into eight-bit program-counter
- relative `bsr' and `bra' instructions, respectively.
-
- `ld' also looks at all 16-bit extended addressing modes and
- transforms them in a direct addressing mode when the address is in
- page 0 (between 0 and 0x0ff).
-
-_relaxing gcc instruction group_
- When `gcc' is called with `-mrelax', it can emit group of
- instructions that the linker can optimize to use a 68HC11 direct
- addressing mode. These instructions consists of `bclr' or `bset'
- instructions.
-
-
-4.3.2 Trampoline Generation
----------------------------
-
-For 68HC11 and 68HC12, `ld' can generate trampoline code to call a far
-function using a normal `jsr' instruction. The linker will also change
-the relocation to some far function to use the trampoline address
-instead of the function address. This is typically the case when a
-pointer to a function is taken. The pointer will in fact point to the
-function trampoline.
-
- The `--pic-veneer' switch makes the linker use PIC sequences for
-ARM/Thumb interworking veneers, even if the rest of the binary is not
-PIC. This avoids problems on uClinux targets where `--emit-relocs' is
-used to generate relocatable binaries.
-
-\1f
-File: ld.info, Node: ARM, Next: HPPA ELF32, Prev: i960, Up: Machine Dependent
-
-4.4 `ld' and the ARM family
-===========================
-
-For the ARM, `ld' will generate code stubs to allow functions calls
-between ARM and Thumb code. These stubs only work with code that has
-been compiled and assembled with the `-mthumb-interwork' command line
-option. If it is necessary to link with old ARM object files or
-libraries, which have not been compiled with the -mthumb-interwork
-option then the `--support-old-code' command line switch should be
-given to the linker. This will make it generate larger stub functions
-which will work with non-interworking aware ARM code. Note, however,
-the linker does not support generating stubs for function calls to
-non-interworking aware Thumb code.
-
- The `--thumb-entry' switch is a duplicate of the generic `--entry'
-switch, in that it sets the program's starting address. But it also
-sets the bottom bit of the address, so that it can be branched to using
-a BX instruction, and the program will start executing in Thumb mode
-straight away.
-
- The `--be8' switch instructs `ld' to generate BE8 format
-executables. This option is only valid when linking big-endian objects.
-The resulting image will contain big-endian data and little-endian code.
-
- The `R_ARM_TARGET1' relocation is typically used for entries in the
-`.init_array' section. It is interpreted as either `R_ARM_REL32' or
-`R_ARM_ABS32', depending on the target. The `--target1-rel' and
-`--target1-abs' switches override the default.
-
- The `--target2=type' switch overrides the default definition of the
-`R_ARM_TARGET2' relocation. Valid values for `type', their meanings,
-and target defaults are as follows:
-`rel'
- `R_ARM_REL32' (arm*-*-elf, arm*-*-eabi)
-
-`abs'
- `R_ARM_ABS32' (arm*-*-symbianelf)
-
-`got-rel'
- `R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd)
-
- The `R_ARM_V4BX' relocation (defined by the ARM AAELF specification)
-enables objects compiled for the ARMv4 architecture to be
-interworking-safe when linked with other objects compiled for ARMv4t,
-but also allows pure ARMv4 binaries to be built from the same ARMv4
-objects.
-
- In the latter case, the switch `--fix-v4bx' must be passed to the
-linker, which causes v4t `BX rM' instructions to be rewritten as `MOV
-PC,rM', since v4 processors do not have a `BX' instruction.
-
- In the former case, the switch should not be used, and `R_ARM_V4BX'
-relocations are ignored.
-
- The `--use-blx' switch enables the linker to use ARM/Thumb BLX
-instructions (available on ARMv5t and above) in various situations.
-Currently it is used to perform calls via the PLT from Thumb code using
-BLX rather than using BX and a mode-switching stub before each PLT
-entry. This should lead to such calls executing slightly faster.
-
- This option is enabled implicitly for SymbianOS, so there is no need
-to specify it if you are using that target.
-
- The `--vfp11-denorm-fix' switch enables a link-time workaround for a
-bug in certain VFP11 coprocessor hardware, which sometimes allows
-instructions with denorm operands (which must be handled by support
-code) to have those operands overwritten by subsequent instructions
-before the support code can read the intended values.
-
- The bug may be avoided in scalar mode if you allow at least one
-intervening instruction between a VFP11 instruction which uses a
-register and another instruction which writes to the same register, or
-at least two intervening instructions if vector mode is in use. The bug
-only affects full-compliance floating-point mode: you do not need this
-workaround if you are using "runfast" mode. Please contact ARM for
-further details.
-
- If you know you are using buggy VFP11 hardware, you can enable this
-workaround by specifying the linker option `--vfp-denorm-fix=scalar' if
-you are using the VFP11 scalar mode only, or `--vfp-denorm-fix=vector'
-if you are using vector mode (the latter also works for scalar code).
-The default is `--vfp-denorm-fix=none'.
-
- If the workaround is enabled, instructions are scanned for
-potentially-troublesome sequences, and a veneer is created for each
-such sequence which may trigger the erratum. The veneer consists of the
-first instruction of the sequence and a branch back to the subsequent
-instruction. The original instruction is then replaced with a branch to
-the veneer. The extra cycles required to call and return from the veneer
-are sufficient to avoid the erratum in both the scalar and vector cases.
-
- The `--no-enum-size-warning' switch prevents the linker from warning
-when linking object files that specify incompatible EABI enumeration
-size attributes. For example, with this switch enabled, linking of an
-object file using 32-bit enumeration values with another using
-enumeration values fitted into the smallest possible space will not be
-diagnosed.
-
-\1f
-File: ld.info, Node: HPPA ELF32, Next: MMIX, Prev: ARM, Up: Machine Dependent
-
-4.5 `ld' and HPPA 32-bit ELF Support
-====================================
-
-When generating a shared library, `ld' will by default generate import
-stubs suitable for use with a single sub-space application. The
-`--multi-subspace' switch causes `ld' to generate export stubs, and
-different (larger) import stubs suitable for use with multiple
-sub-spaces.
-
- Long branch stubs and import/export stubs are placed by `ld' in stub
-sections located between groups of input sections. `--stub-group-size'
-specifies the maximum size of a group of input sections handled by one
-stub section. Since branch offsets are signed, a stub section may
-serve two groups of input sections, one group before the stub section,
-and one group after it. However, when using conditional branches that
-require stubs, it may be better (for branch prediction) that stub
-sections only serve one group of input sections. A negative value for
-`N' chooses this scheme, ensuring that branches to stubs always use a
-negative offset. Two special values of `N' are recognized, `1' and
-`-1'. These both instruct `ld' to automatically size input section
-groups for the branch types detected, with the same behaviour regarding
-stub placement as other positive or negative values of `N' respectively.
-
- Note that `--stub-group-size' does not split input sections. A
-single input section larger than the group size specified will of course
-create a larger group (of one section). If input sections are too
-large, it may not be possible for a branch to reach its stub.
-
-\1f
-File: ld.info, Node: MMIX, Next: MSP430, Prev: HPPA ELF32, Up: Machine Dependent
-
-4.6 `ld' and MMIX
-=================
-
-For MMIX, there is a choice of generating `ELF' object files or `mmo'
-object files when linking. The simulator `mmix' understands the `mmo'
-format. The binutils `objcopy' utility can translate between the two
-formats.
-
- There is one special section, the `.MMIX.reg_contents' section.
-Contents in this section is assumed to correspond to that of global
-registers, and symbols referring to it are translated to special
-symbols, equal to registers. In a final link, the start address of the
-`.MMIX.reg_contents' section corresponds to the first allocated global
-register multiplied by 8. Register `$255' is not included in this
-section; it is always set to the program entry, which is at the symbol
-`Main' for `mmo' files.
-
- Symbols with the prefix `__.MMIX.start.', for example
-`__.MMIX.start..text' and `__.MMIX.start..data' are special; there must
-be only one each, even if they are local. The default linker script
-uses these to set the default start address of a section.
-
- Initial and trailing multiples of zero-valued 32-bit words in a
-section, are left out from an mmo file.
-
-\1f
-File: ld.info, Node: MSP430, Next: M68HC11/68HC12, Prev: MMIX, Up: Machine Dependent
-
-4.7 `ld' and MSP430
-===================
-
-For the MSP430 it is possible to select the MPU architecture. The flag
-`-m [mpu type]' will select an appropriate linker script for selected
-MPU type. (To get a list of known MPUs just pass `-m help' option to
-the linker).
-
- The linker will recognize some extra sections which are MSP430
-specific:
-
-``.vectors''
- Defines a portion of ROM where interrupt vectors located.
-
-``.bootloader''
- Defines the bootloader portion of the ROM (if applicable). Any
- code in this section will be uploaded to the MPU.
-
-``.infomem''
- Defines an information memory section (if applicable). Any code in
- this section will be uploaded to the MPU.
-
-``.infomemnobits''
- This is the same as the `.infomem' section except that any code in
- this section will not be uploaded to the MPU.
-
-``.noinit''
- Denotes a portion of RAM located above `.bss' section.
-
- The last two sections are used by gcc.
-
-\1f
-File: ld.info, Node: PowerPC ELF32, Next: PowerPC64 ELF64, Prev: M68HC11/68HC12, Up: Machine Dependent
-
-4.8 `ld' and PowerPC 32-bit ELF Support
-=======================================
-
-Branches on PowerPC processors are limited to a signed 26-bit
-displacement, which may result in `ld' giving `relocation truncated to
-fit' errors with very large programs. `--relax' enables the generation
-of trampolines that can access the entire 32-bit address space. These
-trampolines are inserted at section boundaries, so may not themselves
-be reachable if an input section exceeds 33M in size.
-
-`--bss-plt'
- Current PowerPC GCC accepts a `-msecure-plt' option that generates
- code capable of using a newer PLT and GOT layout that has the
- security advantage of no executable section ever needing to be
- writable and no writable section ever being executable. PowerPC
- `ld' will generate this layout, including stubs to access the PLT,
- if all input files (including startup and static libraries) were
- compiled with `-msecure-plt'. `--bss-plt' forces the old BSS PLT
- (and GOT layout) which can give slightly better performance.
-
-`--secure-plt'
- `ld' will use the new PLT and GOT layout if it is linking new
- `-fpic' or `-fPIC' code, but does not do so automatically when
- linking non-PIC code. This option requests the new PLT and GOT
- layout. A warning will be given if some object file requires the
- old style BSS PLT.
-
-`--sdata-got'
- The new secure PLT and GOT are placed differently relative to other
- sections compared to older BSS PLT and GOT placement. The
- location of `.plt' must change because the new secure PLT is an
- initialized section while the old PLT is uninitialized. The
- reason for the `.got' change is more subtle: The new placement
- allows `.got' to be read-only in applications linked with `-z
- relro -z now'. However, this placement means that `.sdata' cannot
- always be used in shared libraries, because the PowerPC ABI
- accesses `.sdata' in shared libraries from the GOT pointer.
- `--sdata-got' forces the old GOT placement. PowerPC GCC doesn't
- use `.sdata' in shared libraries, so this option is really only
- useful for other compilers that may do so.
-
-`--emit-stub-syms'
- This option causes `ld' to label linker stubs with a local symbol
- that encodes the stub type and destination.
-
-`--no-tls-optimize'
- PowerPC `ld' normally performs some optimization of code sequences
- used to access Thread-Local Storage. Use this option to disable
- the optimization.
-
-\1f
-File: ld.info, Node: PowerPC64 ELF64, Next: SPU ELF, Prev: PowerPC ELF32, Up: Machine Dependent
-
-4.9 `ld' and PowerPC64 64-bit ELF Support
-=========================================
-
-`--stub-group-size'
- Long branch stubs, PLT call stubs and TOC adjusting stubs are
- placed by `ld' in stub sections located between groups of input
- sections. `--stub-group-size' specifies the maximum size of a
- group of input sections handled by one stub section. Since branch
- offsets are signed, a stub section may serve two groups of input
- sections, one group before the stub section, and one group after
- it. However, when using conditional branches that require stubs,
- it may be better (for branch prediction) that stub sections only
- serve one group of input sections. A negative value for `N'
- chooses this scheme, ensuring that branches to stubs always use a
- negative offset. Two special values of `N' are recognized, `1'
- and `-1'. These both instruct `ld' to automatically size input
- section groups for the branch types detected, with the same
- behaviour regarding stub placement as other positive or negative
- values of `N' respectively.
-
- Note that `--stub-group-size' does not split input sections. A
- single input section larger than the group size specified will of
- course create a larger group (of one section). If input sections
- are too large, it may not be possible for a branch to reach its
- stub.
-
-`--emit-stub-syms'
- This option causes `ld' to label linker stubs with a local symbol
- that encodes the stub type and destination.
-
-`--dotsyms, --no-dotsyms'
- These two options control how `ld' interprets version patterns in
- a version script. Older PowerPC64 compilers emitted both a
- function descriptor symbol with the same name as the function, and
- a code entry symbol with the name prefixed by a dot (`.'). To
- properly version a function `foo', the version script thus needs
- to control both `foo' and `.foo'. The option `--dotsyms', on by
- default, automatically adds the required dot-prefixed patterns.
- Use `--no-dotsyms' to disable this feature.
-
-`--no-tls-optimize'
- PowerPC64 `ld' normally performs some optimization of code
- sequences used to access Thread-Local Storage. Use this option to
- disable the optimization.
-
-`--no-opd-optimize'
- PowerPC64 `ld' normally removes `.opd' section entries
- corresponding to deleted link-once functions, or functions removed
- by the action of `--gc-sections' or linker scrip `/DISCARD/'. Use
- this option to disable `.opd' optimization.
-
-`--non-overlapping-opd'
- Some PowerPC64 compilers have an option to generate compressed
- `.opd' entries spaced 16 bytes apart, overlapping the third word,
- the static chain pointer (unused in C) with the first word of the
- next entry. This option expands such entries to the full 24 bytes.
-
-`--no-toc-optimize'
- PowerPC64 `ld' normally removes unused `.toc' section entries.
- Such entries are detected by examining relocations that reference
- the TOC in code sections. A reloc in a deleted code section marks
- a TOC word as unneeded, while a reloc in a kept code section marks
- a TOC word as needed. Since the TOC may reference itself, TOC
- relocs are also examined. TOC words marked as both needed and
- unneeded will of course be kept. TOC words without any referencing
- reloc are assumed to be part of a multi-word entry, and are kept or
- discarded as per the nearest marked preceding word. This works
- reliably for compiler generated code, but may be incorrect if
- assembly code is used to insert TOC entries. Use this option to
- disable the optimization.
-
-`--no-multi-toc'
- By default, PowerPC64 GCC generates code for a TOC model where TOC
- entries are accessed with a 16-bit offset from r2. This limits the
- total TOC size to 64K. PowerPC64 `ld' extends this limit by
- grouping code sections such that each group uses less than 64K for
- its TOC entries, then inserts r2 adjusting stubs between
- inter-group calls. `ld' does not split apart input sections, so
- cannot help if a single input file has a `.toc' section that
- exceeds 64K, most likely from linking multiple files with `ld -r'.
- Use this option to turn off this feature.
-
-\1f
-File: ld.info, Node: SPU ELF, Next: TI COFF, Prev: PowerPC64 ELF64, Up: Machine Dependent
-
-4.10 `ld' and SPU ELF Support
-=============================
-
-`--plugin'
- This option marks an executable as a PIC plugin module.
-
-`--no-overlays'
- Normally, `ld' recognizes calls to functions within overlay
- regions, and redirects such calls to an overlay manager via a stub.
- `ld' also provides a built-in overlay manager. This option turns
- off all this special overlay handling.
-
-`--emit-stub-syms'
- This option causes `ld' to label overlay stubs with a local symbol
- that encodes the stub type and destination.
-
-`--extra-overlay-stubs'
- This option causes `ld' to add overlay call stubs on all function
- calls out of overlay regions. Normally stubs are not added on
- calls to non-overlay regions.
-
-`--local-store=lo:hi'
- `ld' usually checks that a final executable for SPU fits in the
- address range 0 to 256k. This option may be used to change the
- range. Disable the check entirely with `--local-store=0:0'.
-
-`--stack-analysis'
- SPU local store space is limited. Over-allocation of stack space
- unnecessarily limits space available for code and data, while
- under-allocation results in runtime failures. If given this
- option, `ld' will provide an estimate of maximum stack usage.
- `ld' does this by examining symbols in code sections to determine
- the extents of functions, and looking at function prologues for
- stack adjusting instructions. A call-graph is created by looking
- for relocations on branch instructions. The graph is then searched
- for the maximum stack usage path. Note that this analysis does not
- find calls made via function pointers, and does not handle
- recursion and other cycles in the call graph. Stack usage may be
- under-estimated if your code makes such calls. Also, stack usage
- for dynamic allocation, e.g. alloca, will not be detected. If a
- link map is requested, detailed information about each function's
- stack usage and calls will be given.
-
-`--emit-stack-syms'
- This option, if given along with `--stack-analysis' will result in
- `ld' emitting stack sizing symbols for each function. These take
- the form `__stack_<function_name>' for global functions, and
- `__stack_<number>_<function_name>' for static functions.
- `<number>' is the section id in hex. The value of such symbols is
- the stack requirement for the corresponding function. The symbol
- size will be zero, type `STT_NOTYPE', binding `STB_LOCAL', and
- section `SHN_ABS'.
-
-\1f
-File: ld.info, Node: TI COFF, Next: WIN32, Prev: SPU ELF, Up: Machine Dependent
-
-4.11 `ld''s Support for Various TI COFF Versions
-================================================
-
-The `--format' switch allows selection of one of the various TI COFF
-versions. The latest of this writing is 2; versions 0 and 1 are also
-supported. The TI COFF versions also vary in header byte-order format;
-`ld' will read any version or byte order, but the output header format
-depends on the default specified by the specific target.
-
-\1f
-File: ld.info, Node: WIN32, Next: Xtensa, Prev: TI COFF, Up: Machine Dependent
-
-4.12 `ld' and WIN32 (cygwin/mingw)
-==================================
-
-This section describes some of the win32 specific `ld' issues. See
-*Note Command Line Options: Options. for detailed description of the
-command line options mentioned here.
-
-_import libraries_
- The standard Windows linker creates and uses so-called import
- libraries, which contains information for linking to dll's. They
- are regular static archives and are handled as any other static
- archive. The cygwin and mingw ports of `ld' have specific support
- for creating such libraries provided with the `--out-implib'
- command line option.
-
-_exporting DLL symbols_
- The cygwin/mingw `ld' has several ways to export symbols for dll's.
-
- _using auto-export functionality_
- By default `ld' exports symbols with the auto-export
- functionality, which is controlled by the following command
- line options:
-
- * -export-all-symbols [This is the default]
-
- * -exclude-symbols
-
- * -exclude-libs
-
- If, however, `--export-all-symbols' is not given explicitly
- on the command line, then the default auto-export behavior
- will be _disabled_ if either of the following are true:
-
- * A DEF file is used.
-
- * Any symbol in any object file was marked with the
- __declspec(dllexport) attribute.
-
- _using a DEF file_
- Another way of exporting symbols is using a DEF file. A DEF
- file is an ASCII file containing definitions of symbols which
- should be exported when a dll is created. Usually it is
- named `<dll name>.def' and is added as any other object file
- to the linker's command line. The file's name must end in
- `.def' or `.DEF'.
-
- gcc -o <output> <objectfiles> <dll name>.def
-
- Using a DEF file turns off the normal auto-export behavior,
- unless the `--export-all-symbols' option is also used.
-
- Here is an example of a DEF file for a shared library called
- `xyz.dll':
-
- LIBRARY "xyz.dll" BASE=0x20000000
-
- EXPORTS
- foo
- bar
- _bar = bar
- another_foo = abc.dll.afoo
- var1 DATA
-
- This example defines a DLL with a non-default base address
- and five symbols in the export table. The third exported
- symbol `_bar' is an alias for the second. The fourth symbol,
- `another_foo' is resolved by "forwarding" to another module
- and treating it as an alias for `afoo' exported from the DLL
- `abc.dll'. The final symbol `var1' is declared to be a data
- object.
-
- The optional `LIBRARY <name>' command indicates the _internal_
- name of the output DLL. If `<name>' does not include a suffix,
- the default library suffix, `.DLL' is appended.
-
- When the .DEF file is used to build an application, rather
- than a library, the `NAME <name>' command should be used
- instead of `LIBRARY'. If `<name>' does not include a suffix,
- the default executable suffix, `.EXE' is appended.
-
- With either `LIBRARY <name>' or `NAME <name>' the optional
- specification `BASE = <number>' may be used to specify a
- non-default base address for the image.
-
- If neither `LIBRARY <name>' nor `NAME <name>' is specified,
- or they specify an empty string, the internal name is the
- same as the filename specified on the command line.
-
- The complete specification of an export symbol is:
-
- EXPORTS
- ( ( ( <name1> [ = <name2> ] )
- | ( <name1> = <module-name> . <external-name>))
- [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
-
- Declares `<name1>' as an exported symbol from the DLL, or
- declares `<name1>' as an exported alias for `<name2>'; or
- declares `<name1>' as a "forward" alias for the symbol
- `<external-name>' in the DLL `<module-name>'. Optionally,
- the symbol may be exported by the specified ordinal
- `<integer>' alias.
-
- The optional keywords that follow the declaration indicate:
-
- `NONAME': Do not put the symbol name in the DLL's export
- table. It will still be exported by its ordinal alias
- (either the value specified by the .def specification or,
- otherwise, the value assigned by the linker). The symbol
- name, however, does remain visible in the import library (if
- any), unless `PRIVATE' is also specified.
-
- `DATA': The symbol is a variable or object, rather than a
- function. The import lib will export only an indirect
- reference to `foo' as the symbol `_imp__foo' (ie, `foo' must
- be resolved as `*_imp__foo').
-
- `CONSTANT': Like `DATA', but put the undecorated `foo' as
- well as `_imp__foo' into the import library. Both refer to the
- read-only import address table's pointer to the variable, not
- to the variable itself. This can be dangerous. If the user
- code fails to add the `dllimport' attribute and also fails to
- explicitly add the extra indirection that the use of the
- attribute enforces, the application will behave unexpectedly.
-
- `PRIVATE': Put the symbol in the DLL's export table, but do
- not put it into the static import library used to resolve
- imports at link time. The symbol can still be imported using
- the `LoadLibrary/GetProcAddress' API at runtime or by by
- using the GNU ld extension of linking directly to the DLL
- without an import library.
-
- See ld/deffilep.y in the binutils sources for the full
- specification of other DEF file statements
-
- While linking a shared dll, `ld' is able to create a DEF file
- with the `--output-def <file>' command line option.
-
- _Using decorations_
- Another way of marking symbols for export is to modify the
- source code itself, so that when building the DLL each symbol
- to be exported is declared as:
-
- __declspec(dllexport) int a_variable
- __declspec(dllexport) void a_function(int with_args)
-
- All such symbols will be exported from the DLL. If, however,
- any of the object files in the DLL contain symbols decorated
- in this way, then the normal auto-export behavior is
- disabled, unless the `--export-all-symbols' option is also
- used.
-
- Note that object files that wish to access these symbols must
- _not_ decorate them with dllexport. Instead, they should use
- dllimport, instead:
-
- __declspec(dllimport) int a_variable
- __declspec(dllimport) void a_function(int with_args)
-
- This complicates the structure of library header files,
- because when included by the library itself the header must
- declare the variables and functions as dllexport, but when
- included by client code the header must declare them as
- dllimport. There are a number of idioms that are typically
- used to do this; often client code can omit the __declspec()
- declaration completely. See `--enable-auto-import' and
- `automatic data imports' for more information.
-
-_automatic data imports_
- The standard Windows dll format supports data imports from dlls
- only by adding special decorations (dllimport/dllexport), which
- let the compiler produce specific assembler instructions to deal
- with this issue. This increases the effort necessary to port
- existing Un*x code to these platforms, especially for large c++
- libraries and applications. The auto-import feature, which was
- initially provided by Paul Sokolovsky, allows one to omit the
- decorations to achieve a behavior that conforms to that on
- POSIX/Un*x platforms. This feature is enabled with the
- `--enable-auto-import' command-line option, although it is enabled
- by default on cygwin/mingw. The `--enable-auto-import' option
- itself now serves mainly to suppress any warnings that are
- ordinarily emitted when linked objects trigger the feature's use.
-
- auto-import of variables does not always work flawlessly without
- additional assistance. Sometimes, you will see this message
-
- "variable '<var>' can't be auto-imported. Please read the
- documentation for ld's `--enable-auto-import' for details."
-
- The `--enable-auto-import' documentation explains why this error
- occurs, and several methods that can be used to overcome this
- difficulty. One of these methods is the _runtime pseudo-relocs_
- feature, described below.
-
- For complex variables imported from DLLs (such as structs or
- classes), object files typically contain a base address for the
- variable and an offset (_addend_) within the variable-to specify a
- particular field or public member, for instance. Unfortunately,
- the runtime loader used in win32 environments is incapable of
- fixing these references at runtime without the additional
- information supplied by dllimport/dllexport decorations. The
- standard auto-import feature described above is unable to resolve
- these references.
-
- The `--enable-runtime-pseudo-relocs' switch allows these
- references to be resolved without error, while leaving the task of
- adjusting the references themselves (with their non-zero addends)
- to specialized code provided by the runtime environment. Recent
- versions of the cygwin and mingw environments and compilers
- provide this runtime support; older versions do not. However, the
- support is only necessary on the developer's platform; the
- compiled result will run without error on an older system.
-
- `--enable-runtime-pseudo-relocs' is not the default; it must be
- explicitly enabled as needed.
-
-_direct linking to a dll_
- The cygwin/mingw ports of `ld' support the direct linking,
- including data symbols, to a dll without the usage of any import
- libraries. This is much faster and uses much less memory than
- does the traditional import library method, especially when
- linking large libraries or applications. When `ld' creates an
- import lib, each function or variable exported from the dll is
- stored in its own bfd, even though a single bfd could contain many
- exports. The overhead involved in storing, loading, and
- processing so many bfd's is quite large, and explains the
- tremendous time, memory, and storage needed to link against
- particularly large or complex libraries when using import libs.
-
- Linking directly to a dll uses no extra command-line switches
- other than `-L' and `-l', because `ld' already searches for a
- number of names to match each library. All that is needed from
- the developer's perspective is an understanding of this search, in
- order to force ld to select the dll instead of an import library.
-
- For instance, when ld is called with the argument `-lxxx' it will
- attempt to find, in the first directory of its search path,
-
- libxxx.dll.a
- xxx.dll.a
- libxxx.a
- xxx.lib
- cygxxx.dll (*)
- libxxx.dll
- xxx.dll
-
- before moving on to the next directory in the search path.
-
- (*) Actually, this is not `cygxxx.dll' but in fact is
- `<prefix>xxx.dll', where `<prefix>' is set by the `ld' option
- `--dll-search-prefix=<prefix>'. In the case of cygwin, the
- standard gcc spec file includes `--dll-search-prefix=cyg', so in
- effect we actually search for `cygxxx.dll'.
-
- Other win32-based unix environments, such as mingw or pw32, may
- use other `<prefix>'es, although at present only cygwin makes use
- of this feature. It was originally intended to help avoid name
- conflicts among dll's built for the various win32/un*x
- environments, so that (for example) two versions of a zlib dll
- could coexist on the same machine.
-
- The generic cygwin/mingw path layout uses a `bin' directory for
- applications and dll's and a `lib' directory for the import
- libraries (using cygwin nomenclature):
-
- bin/
- cygxxx.dll
- lib/
- libxxx.dll.a (in case of dll's)
- libxxx.a (in case of static archive)
-
- Linking directly to a dll without using the import library can be
- done two ways:
-
- 1. Use the dll directly by adding the `bin' path to the link line
- gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
-
- However, as the dll's often have version numbers appended to their
- names (`cygncurses-5.dll') this will often fail, unless one
- specifies `-L../bin -lncurses-5' to include the version. Import
- libs are generally not versioned, and do not have this difficulty.
-
- 2. Create a symbolic link from the dll to a file in the `lib'
- directory according to the above mentioned search pattern. This
- should be used to avoid unwanted changes in the tools needed for
- making the app/dll.
-
- ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
-
- Then you can link without any make environment changes.
-
- gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
-
- This technique also avoids the version number problems, because
- the following is perfectly legal
-
- bin/
- cygxxx-5.dll
- lib/
- libxxx.dll.a -> ../bin/cygxxx-5.dll
-
- Linking directly to a dll without using an import lib will work
- even when auto-import features are exercised, and even when
- `--enable-runtime-pseudo-relocs' is used.
-
- Given the improvements in speed and memory usage, one might
- justifiably wonder why import libraries are used at all. There
- are three reasons:
-
- 1. Until recently, the link-directly-to-dll functionality did _not_
- work with auto-imported data.
-
- 2. Sometimes it is necessary to include pure static objects within
- the import library (which otherwise contains only bfd's for
- indirection symbols that point to the exports of a dll). Again,
- the import lib for the cygwin kernel makes use of this ability,
- and it is not possible to do this without an import lib.
-
- 3. Symbol aliases can only be resolved using an import lib. This
- is critical when linking against OS-supplied dll's (eg, the win32
- API) in which symbols are usually exported as undecorated aliases
- of their stdcall-decorated assembly names.
-
- So, import libs are not going away. But the ability to replace
- true import libs with a simple symbolic link to (or a copy of) a
- dll, in many cases, is a useful addition to the suite of tools
- binutils makes available to the win32 developer. Given the
- massive improvements in memory requirements during linking, storage
- requirements, and linking speed, we expect that many developers
- will soon begin to use this feature whenever possible.
-
-_symbol aliasing_
-
- _adding additional names_
- Sometimes, it is useful to export symbols with additional
- names. A symbol `foo' will be exported as `foo', but it can
- also be exported as `_foo' by using special directives in the
- DEF file when creating the dll. This will affect also the
- optional created import library. Consider the following DEF
- file:
-
- LIBRARY "xyz.dll" BASE=0x61000000
-
- EXPORTS
- foo
- _foo = foo
-
- The line `_foo = foo' maps the symbol `foo' to `_foo'.
-
- Another method for creating a symbol alias is to create it in
- the source code using the "weak" attribute:
-
- void foo () { /* Do something. */; }
- void _foo () __attribute__ ((weak, alias ("foo")));
-
- See the gcc manual for more information about attributes and
- weak symbols.
-
- _renaming symbols_
- Sometimes it is useful to rename exports. For instance, the
- cygwin kernel does this regularly. A symbol `_foo' can be
- exported as `foo' but not as `_foo' by using special
- directives in the DEF file. (This will also affect the import
- library, if it is created). In the following example:
-
- LIBRARY "xyz.dll" BASE=0x61000000
-
- EXPORTS
- _foo = foo
-
- The line `_foo = foo' maps the exported symbol `foo' to
- `_foo'.
-
- Note: using a DEF file disables the default auto-export behavior,
- unless the `--export-all-symbols' command line option is used.
- If, however, you are trying to rename symbols, then you should list
- _all_ desired exports in the DEF file, including the symbols that
- are not being renamed, and do _not_ use the `--export-all-symbols'
- option. If you list only the renamed symbols in the DEF file, and
- use `--export-all-symbols' to handle the other symbols, then the
- both the new names _and_ the original names for the renamed
- symbols will be exported. In effect, you'd be aliasing those
- symbols, not renaming them, which is probably not what you wanted.
-
-_weak externals_
- The Windows object format, PE, specifies a form of weak symbols
- called weak externals. When a weak symbol is linked and the
- symbol is not defined, the weak symbol becomes an alias for some
- other symbol. There are three variants of weak externals:
- * Definition is searched for in objects and libraries,
- historically called lazy externals.
-
- * Definition is searched for only in other objects, not in
- libraries. This form is not presently implemented.
-
- * No search; the symbol is an alias. This form is not presently
- implemented.
- As a GNU extension, weak symbols that do not specify an alternate
- symbol are supported. If the symbol is undefined when linking,
- the symbol uses a default value.
-
-\1f
-File: ld.info, Node: Xtensa, Prev: WIN32, Up: Machine Dependent
-
-4.13 `ld' and Xtensa Processors
-===============================
-
-The default `ld' behavior for Xtensa processors is to interpret
-`SECTIONS' commands so that lists of explicitly named sections in a
-specification with a wildcard file will be interleaved when necessary to
-keep literal pools within the range of PC-relative load offsets. For
-example, with the command:
-
- SECTIONS
- {
- .text : {
- *(.literal .text)
- }
- }
-
-`ld' may interleave some of the `.literal' and `.text' sections from
-different object files to ensure that the literal pools are within the
-range of PC-relative load offsets. A valid interleaving might place
-the `.literal' sections from an initial group of files followed by the
-`.text' sections of that group of files. Then, the `.literal' sections
-from the rest of the files and the `.text' sections from the rest of
-the files would follow.
-
- Relaxation is enabled by default for the Xtensa version of `ld' and
-provides two important link-time optimizations. The first optimization
-is to combine identical literal values to reduce code size. A redundant
-literal will be removed and all the `L32R' instructions that use it
-will be changed to reference an identical literal, as long as the
-location of the replacement literal is within the offset range of all
-the `L32R' instructions. The second optimization is to remove
-unnecessary overhead from assembler-generated "longcall" sequences of
-`L32R'/`CALLXN' when the target functions are within range of direct
-`CALLN' instructions.
-
- For each of these cases where an indirect call sequence can be
-optimized to a direct call, the linker will change the `CALLXN'
-instruction to a `CALLN' instruction, remove the `L32R' instruction,
-and remove the literal referenced by the `L32R' instruction if it is
-not used for anything else. Removing the `L32R' instruction always
-reduces code size but can potentially hurt performance by changing the
-alignment of subsequent branch targets. By default, the linker will
-always preserve alignments, either by switching some instructions
-between 24-bit encodings and the equivalent density instructions or by
-inserting a no-op in place of the `L32R' instruction that was removed.
-If code size is more important than performance, the `--size-opt'
-option can be used to prevent the linker from widening density
-instructions or inserting no-ops, except in a few cases where no-ops
-are required for correctness.
-
- The following Xtensa-specific command-line options can be used to
-control the linker:
-
-`--no-relax'
- Since the Xtensa version of `ld' enables the `--relax' option by
- default, the `--no-relax' option is provided to disable relaxation.
-
-`--size-opt'
- When optimizing indirect calls to direct calls, optimize for code
- size more than performance. With this option, the linker will not
- insert no-ops or widen density instructions to preserve branch
- target alignment. There may still be some cases where no-ops are
- required to preserve the correctness of the code.
-
-\1f
-File: ld.info, Node: BFD, Next: Reporting Bugs, Prev: Machine Dependent, Up: Top
-
-5 BFD
-*****
-
-The linker accesses object and archive files using the BFD libraries.
-These libraries allow the linker to use the same routines to operate on
-object files whatever the object file format. A different object file
-format can be supported simply by creating a new BFD back end and adding
-it to the library. To conserve runtime memory, however, the linker and
-associated tools are usually configured to support only a subset of the
-object file formats available. You can use `objdump -i' (*note
-objdump: (binutils.info)objdump.) to list all the formats available for
-your configuration.
-
- As with most implementations, BFD is a compromise between several
-conflicting requirements. The major factor influencing BFD design was
-efficiency: any time used converting between formats is time which
-would not have been spent had BFD not been involved. This is partly
-offset by abstraction payback; since BFD simplifies applications and
-back ends, more time and care may be spent optimizing algorithms for a
-greater speed.
-
- One minor artifact of the BFD solution which you should bear in mind
-is the potential for information loss. There are two places where
-useful information can be lost using the BFD mechanism: during
-conversion and during output. *Note BFD information loss::.
-
-* Menu:
-
-* BFD outline:: How it works: an outline of BFD
-
-\1f
-File: ld.info, Node: BFD outline, Up: BFD
-
-5.1 How It Works: An Outline of BFD
-===================================
-
-When an object file is opened, BFD subroutines automatically determine
-the format of the input object file. They then build a descriptor in
-memory with pointers to routines that will be used to access elements of
-the object file's data structures.
-
- As different information from the object files is required, BFD
-reads from different sections of the file and processes them. For
-example, a very common operation for the linker is processing symbol
-tables. Each BFD back end provides a routine for converting between
-the object file's representation of symbols and an internal canonical
-format. When the linker asks for the symbol table of an object file, it
-calls through a memory pointer to the routine from the relevant BFD
-back end which reads and converts the table into a canonical form. The
-linker then operates upon the canonical form. When the link is finished
-and the linker writes the output file's symbol table, another BFD back
-end routine is called to take the newly created symbol table and
-convert it into the chosen output format.
-
-* Menu:
-
-* BFD information loss:: Information Loss
-* Canonical format:: The BFD canonical object-file format
-
-\1f
-File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline
-
-5.1.1 Information Loss
-----------------------
-
-_Information can be lost during output._ The output formats supported
-by BFD do not provide identical facilities, and information which can
-be described in one form has nowhere to go in another format. One
-example of this is alignment information in `b.out'. There is nowhere
-in an `a.out' format file to store alignment information on the
-contained data, so when a file is linked from `b.out' and an `a.out'
-image is produced, alignment information will not propagate to the
-output file. (The linker will still use the alignment information
-internally, so the link is performed correctly).
-
- Another example is COFF section names. COFF files may contain an
-unlimited number of sections, each one with a textual section name. If
-the target of the link is a format which does not have many sections
-(e.g., `a.out') or has sections without names (e.g., the Oasys format),
-the link cannot be done simply. You can circumvent this problem by
-describing the desired input-to-output section mapping with the linker
-command language.
-
- _Information can be lost during canonicalization._ The BFD internal
-canonical form of the external formats is not exhaustive; there are
-structures in input formats for which there is no direct representation
-internally. This means that the BFD back ends cannot maintain all
-possible data richness through the transformation between external to
-internal and back to external formats.
-
- This limitation is only a problem when an application reads one
-format and writes another. Each BFD back end is responsible for
-maintaining as much data as possible, and the internal BFD canonical
-form has structures which are opaque to the BFD core, and exported only
-to the back ends. When a file is read in one format, the canonical form
-is generated for BFD and the application. At the same time, the back
-end saves away any information which may otherwise be lost. If the data
-is then written back in the same format, the back end routine will be
-able to use the canonical form provided by the BFD core as well as the
-information it prepared earlier. Since there is a great deal of
-commonality between back ends, there is no information lost when
-linking or copying big endian COFF to little endian COFF, or `a.out' to
-`b.out'. When a mixture of formats is linked, the information is only
-lost from the files whose format differs from the destination.
-
-\1f
-File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline
-
-5.1.2 The BFD canonical object-file format
-------------------------------------------
-
-The greatest potential for loss of information occurs when there is the
-least overlap between the information provided by the source format,
-that stored by the canonical format, and that needed by the destination
-format. A brief description of the canonical form may help you
-understand which kinds of data you can count on preserving across
-conversions.
-
-_files_
- Information stored on a per-file basis includes target machine
- architecture, particular implementation format type, a demand
- pageable bit, and a write protected bit. Information like Unix
- magic numbers is not stored here--only the magic numbers' meaning,
- so a `ZMAGIC' file would have both the demand pageable bit and the
- write protected text bit set. The byte order of the target is
- stored on a per-file basis, so that big- and little-endian object
- files may be used with one another.
-
-_sections_
- Each section in the input file contains the name of the section,
- the section's original address in the object file, size and
- alignment information, various flags, and pointers into other BFD
- data structures.
-
-_symbols_
- Each symbol contains a pointer to the information for the object
- file which originally defined it, its name, its value, and various
- flag bits. When a BFD back end reads in a symbol table, it
- relocates all symbols to make them relative to the base of the
- section where they were defined. Doing this ensures that each
- symbol points to its containing section. Each symbol also has a
- varying amount of hidden private data for the BFD back end. Since
- the symbol points to the original file, the private data format
- for that symbol is accessible. `ld' can operate on a collection
- of symbols of wildly different formats without problems.
-
- Normal global and simple local symbols are maintained on output,
- so an output file (no matter its format) will retain symbols
- pointing to functions and to global, static, and common variables.
- Some symbol information is not worth retaining; in `a.out', type
- information is stored in the symbol table as long symbol names.
- This information would be useless to most COFF debuggers; the
- linker has command line switches to allow users to throw it away.
-
- There is one word of type information within the symbol, so if the
- format supports symbol type information within symbols (for
- example, COFF, IEEE, Oasys) and the type is simple enough to fit
- within one word (nearly everything but aggregates), the
- information will be preserved.
-
-_relocation level_
- Each canonical BFD relocation record contains a pointer to the
- symbol to relocate to, the offset of the data to relocate, the
- section the data is in, and a pointer to a relocation type
- descriptor. Relocation is performed by passing messages through
- the relocation type descriptor and the symbol pointer. Therefore,
- relocations can be performed on output data using a relocation
- method that is only available in one of the input formats. For
- instance, Oasys provides a byte relocation format. A relocation
- record requesting this relocation type would point indirectly to a
- routine to perform this, so the relocation may be performed on a
- byte being written to a 68k COFF file, even though 68k COFF has no
- such relocation type.
-
-_line numbers_
- Object formats can contain, for debugging purposes, some form of
- mapping between symbols, source line numbers, and addresses in the
- output file. These addresses have to be relocated along with the
- symbol information. Each symbol with an associated list of line
- number records points to the first record of the list. The head
- of a line number list consists of a pointer to the symbol, which
- allows finding out the address of the function whose line number
- is being described. The rest of the list is made up of pairs:
- offsets into the section and line numbers. Any format which can
- simply derive this information can pass it successfully between
- formats (COFF, IEEE and Oasys).
-
-\1f
-File: ld.info, Node: Reporting Bugs, Next: MRI, Prev: BFD, Up: Top
-
-6 Reporting Bugs
-****************
-
-Your bug reports play an essential role in making `ld' reliable.
-
- Reporting a bug may help you by bringing a solution to your problem,
-or it may not. But in any case the principal function of a bug report
-is to help the entire community by making the next version of `ld' work
-better. Bug reports are your contribution to the maintenance of `ld'.
-
- In order for a bug report to serve its purpose, you must include the
-information that enables us to fix the bug.
-
-* Menu:
-
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-
-\1f
-File: ld.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
-
-6.1 Have You Found a Bug?
-=========================
-
-If you are not sure whether you have found a bug, here are some
-guidelines:
-
- * If the linker gets a fatal signal, for any input whatever, that is
- a `ld' bug. Reliable linkers never crash.
-
- * If `ld' produces an error message for valid input, that is a bug.
-
- * If `ld' does not produce an error message for invalid input, that
- may be a bug. In the general case, the linker can not verify that
- object files are correct.
-
- * If you are an experienced user of linkers, your suggestions for
- improvement of `ld' are welcome in any case.
-
-\1f
-File: ld.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
-
-6.2 How to Report Bugs
-======================
-
-A number of companies and individuals offer support for GNU products.
-If you obtained `ld' from a support organization, we recommend you
-contact that organization first.
-
- You can find contact information for many support companies and
-individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
-
- Otherwise, send bug reports for `ld' to
-`http://www.sourceware.org/bugzilla/'.
-
- The fundamental principle of reporting bugs usefully is this:
-*report all the facts*. If you are not sure whether to state a fact or
-leave it out, state it!
-
- Often people omit facts because they think they know what causes the
-problem and assume that some details do not matter. Thus, you might
-assume that the name of a symbol you use in an example does not matter.
-Well, probably it does not, but one cannot be sure. Perhaps the bug
-is a stray memory reference which happens to fetch from the location
-where that name is stored in memory; perhaps, if the name were
-different, the contents of that location would fool the linker into
-doing the right thing despite the bug. Play it safe and give a
-specific, complete example. That is the easiest thing for you to do,
-and the most helpful.
-
- Keep in mind that the purpose of a bug report is to enable us to fix
-the bug if it is new to us. Therefore, always write your bug reports
-on the assumption that the bug has not been reported previously.
-
- Sometimes people give a few sketchy facts and ask, "Does this ring a
-bell?" This cannot help us fix a bug, so it is basically useless. We
-respond by asking for enough details to enable us to investigate. You
-might as well expedite matters by sending them to begin with.
-
- To enable us to fix the bug, you should include all these things:
-
- * The version of `ld'. `ld' announces it if you start it with the
- `--version' argument.
-
- Without this, we will not know whether there is any point in
- looking for the bug in the current version of `ld'.
-
- * Any patches you may have applied to the `ld' source, including any
- patches made to the `BFD' library.
-
- * The type of machine you are using, and the operating system name
- and version number.
-
- * What compiler (and its version) was used to compile `ld'--e.g.
- "`gcc-2.7'".
-
- * The command arguments you gave the linker to link your example and
- observe the bug. To guarantee you will not omit something
- important, list them all. A copy of the Makefile (or the output
- from make) is sufficient.
-
- If we were to try to guess the arguments, we would probably guess
- wrong and then we might not encounter the bug.
-
- * A complete input file, or set of input files, that will reproduce
- the bug. It is generally most helpful to send the actual object
- files provided that they are reasonably small. Say no more than
- 10K. For bigger files you can either make them available by FTP
- or HTTP or else state that you are willing to send the object
- file(s) to whomever requests them. (Note - your email will be
- going to a mailing list, so we do not want to clog it up with
- large attachments). But small attachments are best.
-
- If the source files were assembled using `gas' or compiled using
- `gcc', then it may be OK to send the source files rather than the
- object files. In this case, be sure to say exactly what version of
- `gas' or `gcc' was used to produce the object files. Also say how
- `gas' or `gcc' were configured.
-
- * A description of what behavior you observe that you believe is
- incorrect. For example, "It gets a fatal signal."
-
- Of course, if the bug is that `ld' gets a fatal signal, then we
- will certainly notice it. But if the bug is incorrect output, we
- might not notice unless it is glaringly wrong. You might as well
- not give us a chance to make a mistake.
-
- Even if the problem you experience is a fatal signal, you should
- still say so explicitly. Suppose something strange is going on,
- such as, your copy of `ld' is out of sync, or you have encountered
- a bug in the C library on your system. (This has happened!) Your
- copy might crash and ours would not. If you told us to expect a
- crash, then when ours fails to crash, we would know that the bug
- was not happening for us. If you had not told us to expect a
- crash, then we would not be able to draw any conclusion from our
- observations.
-
- * If you wish to suggest changes to the `ld' source, send us context
- diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
- Always send diffs from the old file to the new file. If you even
- discuss something in the `ld' source, refer to it by context, not
- by line number.
-
- The line numbers in our development sources will not match those
- in your sources. Your line numbers would convey no useful
- information to us.
-
- Here are some things that are not necessary:
-
- * A description of the envelope of the bug.
-
- Often people who encounter a bug spend a lot of time investigating
- which changes to the input file will make the bug go away and which
- changes will not affect it.
-
- This is often time consuming and not very useful, because the way
- we will find the bug is by running a single example under the
- debugger with breakpoints, not by pure deduction from a series of
- examples. We recommend that you save your time for something else.
-
- Of course, if you can find a simpler example to report _instead_
- of the original one, that is a convenience for us. Errors in the
- output will be easier to spot, running under the debugger will take
- less time, and so on.
-
- However, simplification is not vital; if you do not want to do
- this, report the bug anyway and send us the entire test case you
- used.
-
- * A patch for the bug.
-
- A patch for the bug does help us if it is a good one. But do not
- omit the necessary information, such as the test case, on the
- assumption that a patch is all we need. We might see problems
- with your patch and decide to fix the problem another way, or we
- might not understand it at all.
-
- Sometimes with a program as complicated as `ld' it is very hard to
- construct an example that will make the program follow a certain
- path through the code. If you do not send us the example, we will
- not be able to construct one, so we will not be able to verify
- that the bug is fixed.
-
- And if we cannot understand what bug you are trying to fix, or why
- your patch should be an improvement, we will not install it. A
- test case will help us to understand.
-
- * A guess about what the bug is or what it depends on.
-
- Such guesses are usually wrong. Even we cannot guess right about
- such things without first using the debugger to find the facts.
-
-\1f
-File: ld.info, Node: MRI, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top
-
-Appendix A MRI Compatible Script Files
-**************************************
-
-To aid users making the transition to GNU `ld' from the MRI linker,
-`ld' can use MRI compatible linker scripts as an alternative to the
-more general-purpose linker scripting language described in *Note
-Scripts::. MRI compatible linker scripts have a much simpler command
-set than the scripting language otherwise used with `ld'. GNU `ld'
-supports the most commonly used MRI linker commands; these commands are
-described here.
-
- In general, MRI scripts aren't of much use with the `a.out' object
-file format, since it only has three sections and MRI scripts lack some
-features to make use of them.
-
- You can specify a file containing an MRI-compatible script using the
-`-c' command-line option.
-
- Each command in an MRI-compatible script occupies its own line; each
-command line starts with the keyword that identifies the command (though
-blank lines are also allowed for punctuation). If a line of an
-MRI-compatible script begins with an unrecognized keyword, `ld' issues
-a warning message, but continues processing the script.
-
- Lines beginning with `*' are comments.
-
- You can write these commands using all upper-case letters, or all
-lower case; for example, `chip' is the same as `CHIP'. The following
-list shows only the upper-case form of each command.
-
-`ABSOLUTE SECNAME'
-`ABSOLUTE SECNAME, SECNAME, ... SECNAME'
- Normally, `ld' includes in the output file all sections from all
- the input files. However, in an MRI-compatible script, you can
- use the `ABSOLUTE' command to restrict the sections that will be
- present in your output program. If the `ABSOLUTE' command is used
- at all in a script, then only the sections named explicitly in
- `ABSOLUTE' commands will appear in the linker output. You can
- still use other input sections (whatever you select on the command
- line, or using `LOAD') to resolve addresses in the output file.
-
-`ALIAS OUT-SECNAME, IN-SECNAME'
- Use this command to place the data from input section IN-SECNAME
- in a section called OUT-SECNAME in the linker output file.
-
- IN-SECNAME may be an integer.
-
-`ALIGN SECNAME = EXPRESSION'
- Align the section called SECNAME to EXPRESSION. The EXPRESSION
- should be a power of two.
-
-`BASE EXPRESSION'
- Use the value of EXPRESSION as the lowest address (other than
- absolute addresses) in the output file.
-
-`CHIP EXPRESSION'
-`CHIP EXPRESSION, EXPRESSION'
- This command does nothing; it is accepted only for compatibility.
-
-`END'
- This command does nothing whatever; it's only accepted for
- compatibility.
-
-`FORMAT OUTPUT-FORMAT'
- Similar to the `OUTPUT_FORMAT' command in the more general linker
- language, but restricted to one of these output formats:
-
- 1. S-records, if OUTPUT-FORMAT is `S'
-
- 2. IEEE, if OUTPUT-FORMAT is `IEEE'
-
- 3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
- `COFF'
-
-`LIST ANYTHING...'
- Print (to the standard output file) a link map, as produced by the
- `ld' command-line option `-M'.
-
- The keyword `LIST' may be followed by anything on the same line,
- with no change in its effect.
-
-`LOAD FILENAME'
-`LOAD FILENAME, FILENAME, ... FILENAME'
- Include one or more object file FILENAME in the link; this has the
- same effect as specifying FILENAME directly on the `ld' command
- line.
-
-`NAME OUTPUT-NAME'
- OUTPUT-NAME is the name for the program produced by `ld'; the
- MRI-compatible command `NAME' is equivalent to the command-line
- option `-o' or the general script language command `OUTPUT'.
-
-`ORDER SECNAME, SECNAME, ... SECNAME'
-`ORDER SECNAME SECNAME SECNAME'
- Normally, `ld' orders the sections in its output file in the order
- in which they first appear in the input files. In an
- MRI-compatible script, you can override this ordering with the
- `ORDER' command. The sections you list with `ORDER' will appear
- first in your output file, in the order specified.
-
-`PUBLIC NAME=EXPRESSION'
-`PUBLIC NAME,EXPRESSION'
-`PUBLIC NAME EXPRESSION'
- Supply a value (EXPRESSION) for external symbol NAME used in the
- linker input files.
-
-`SECT SECNAME, EXPRESSION'
-`SECT SECNAME=EXPRESSION'
-`SECT SECNAME EXPRESSION'
- You can use any of these three forms of the `SECT' command to
- specify the start address (EXPRESSION) for section SECNAME. If
- you have more than one `SECT' statement for the same SECNAME, only
- the _first_ sets the start address.
-
-\1f
-File: ld.info, Node: GNU Free Documentation License, Next: LD Index, Prev: MRI, Up: Top
-
-Appendix B GNU Free Documentation License
-*****************************************
-
- Version 1.1, March 2000
-
- Copyright (C) 2000, 2003 Free Software Foundation, Inc.
- 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft
- license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same freedoms
- that the software does. But this License is not limited to
- software manuals; it can be used for any textual work, regardless
- of subject matter or whether it is published as a printed book.
- We recommend this License principally for works whose purpose is
- instruction or reference.
-
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed
- under the terms of this License. The "Document", below, refers to
- any such manual or work. Any member of the public is a licensee,
- and is addressed as "you."
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any mathematics.)
- The relationship could be a matter of historical connection with
- the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque."
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that
- can be read and edited only by proprietary word processors, SGML
- or XML for which the DTD and/or processing tools are not generally
- available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the
- material this License requires to appear in the title page. For
- works in formats which do not have any title page as such, "Title
- Page" means the text near the most prominent appearance of the
- work's title, preceding the beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You
- may not use technical measures to obstruct or control the reading
- or further copying of the copies you make or distribute. However,
- you may accept compensation in exchange for copies. If you
- distribute a large enough number of copies you must also follow
- the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you
- must enclose the copies in covers that carry, clearly and legibly,
- all these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also clearly
- and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the
- title equally prominent and visible. You may add other material
- on the covers in addition. Copying with changes limited to the
- covers, as long as they preserve the title of the Document and
- satisfy these conditions, can be treated as verbatim copying in
- other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy, or
- state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you
- release the Modified Version under precisely this License, with
- the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version to
- whoever possesses a copy of it. In addition, you must do these
- things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title
- as a previous version if the original publisher of that version
- gives permission.
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it
- has less than five).
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- D. Preserve all the copyright notices of the Document.
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- H. Include an unaltered copy of this License.
- I. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document,
- create one stating the title, year, authors, and publisher of
- the Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- J. Preserve the network location, if any, given in the Document for
- public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in the
- "History" section. You may omit a network location for a work
- that was published at least four years before the Document
- itself, or if the original publisher of the version it refers
- to gives permission.
- K. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements
- and/or dedications given therein.
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section numbers
- or the equivalent are not considered part of the section titles.
- M. Delete any section entitled "Endorsements." Such a section
- may not be included in the Modified Version.
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do this,
- add their titles to the list of Invariant Sections in the Modified
- Version's license notice. These titles must be distinct from any
- other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties-for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition
- of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If the
- Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same entity
- you are acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the
- combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgements", and any sections entitled "Dedications." You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert
- a copy of this License into the extracted document, and follow
- this License in all other respects regarding verbatim copying of
- that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of
- a storage or distribution medium, does not as a whole count as a
- Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may be
- placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section
- 4. Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case of a
- disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-====================================================
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright (C) YEAR YOUR NAME.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.1
- or any later version published by the Free Software Foundation;
- with the Invariant Sections being LIST THEIR TITLES, with the
- Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
- A copy of the license is included in the section entitled "GNU
- Free Documentation License."
-
- If you have no Invariant Sections, write "with no Invariant Sections"
-instead of saying which ones are invariant. If you have no Front-Cover
-Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
-LIST"; likewise for Back-Cover Texts.
-
- If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License, to
-permit their use in free software.
-
-\1f
-File: ld.info, Node: LD Index, Prev: GNU Free Documentation License, Up: Top
-
-LD Index
-********
-
-\0\b[index\0\b]
-* Menu:
-
-* ": Symbols. (line 6)
-* -(: Options. (line 643)
-* --accept-unknown-input-arch: Options. (line 661)
-* --add-needed: Options. (line 683)
-* --add-stdcall-alias: Options. (line 1450)
-* --allow-multiple-definition: Options. (line 892)
-* --allow-shlib-undefined: Options. (line 898)
-* --architecture=ARCH: Options. (line 104)
-* --as-needed: Options. (line 671)
-* --auxiliary: Options. (line 205)
-* --bank-window: Options. (line 1789)
-* --base-file: Options. (line 1455)
-* --be8: ARM. (line 23)
-* --bss-plt: PowerPC ELF32. (line 13)
-* --build-id: Options. (line 1412)
-* --build-id=STYLE: Options. (line 1412)
-* --check-sections: Options. (line 765)
-* --cref: Options. (line 775)
-* --default-imported-symver: Options. (line 926)
-* --default-script=SCRIPT: Options. (line 488)
-* --default-symver: Options. (line 922)
-* --defsym SYMBOL=EXP: Options. (line 803)
-* --demangle[=STYLE]: Options. (line 816)
-* --disable-auto-image-base: Options. (line 1602)
-* --disable-auto-import: Options. (line 1731)
-* --disable-new-dtags: Options. (line 1375)
-* --disable-runtime-pseudo-reloc: Options. (line 1744)
-* --disable-stdcall-fixup: Options. (line 1465)
-* --discard-all: Options. (line 534)
-* --discard-locals: Options. (line 538)
-* --dll: Options. (line 1460)
-* --dll-search-prefix: Options. (line 1608)
-* --dotsyms: PowerPC64 ELF64. (line 33)
-* --dynamic-linker FILE: Options. (line 829)
-* --dynamic-list-cpp-new: Options. (line 757)
-* --dynamic-list-cpp-typeinfo: Options. (line 761)
-* --dynamic-list-data: Options. (line 754)
-* --dynamic-list=DYNAMIC-LIST-FILE: Options. (line 741)
-* --eh-frame-hdr: Options. (line 1371)
-* --emit-relocs: Options. (line 423)
-* --emit-stack-syms: SPU ELF. (line 46)
-* --emit-stub-syms <1>: SPU ELF. (line 15)
-* --emit-stub-syms <2>: PowerPC64 ELF64. (line 29)
-* --emit-stub-syms: PowerPC ELF32. (line 44)
-* --enable-auto-image-base: Options. (line 1594)
-* --enable-auto-import: Options. (line 1617)
-* --enable-extra-pe-debug: Options. (line 1749)
-* --enable-new-dtags: Options. (line 1375)
-* --enable-runtime-pseudo-reloc: Options. (line 1736)
-* --enable-stdcall-fixup: Options. (line 1465)
-* --entry=ENTRY: Options. (line 158)
-* --error-unresolved-symbols: Options. (line 1324)
-* --exclude-libs: Options. (line 168)
-* --exclude-symbols: Options. (line 1507)
-* --export-all-symbols: Options. (line 1483)
-* --export-dynamic: Options. (line 179)
-* --extra-overlay-stubs: SPU ELF. (line 19)
-* --fatal-warnings: Options. (line 835)
-* --file-alignment: Options. (line 1513)
-* --filter: Options. (line 226)
-* --fix-v4bx: ARM. (line 44)
-* --force-dynamic: Options. (line 432)
-* --force-exe-suffix: Options. (line 838)
-* --format=FORMAT: Options. (line 115)
-* --format=VERSION: TI COFF. (line 6)
-* --gc-sections: Options. (line 848)
-* --gpsize: Options. (line 259)
-* --hash-size=NUMBER: Options. (line 1384)
-* --hash-style=STYLE: Options. (line 1392)
-* --heap: Options. (line 1519)
-* --help: Options. (line 865)
-* --image-base: Options. (line 1526)
-* --just-symbols=FILE: Options. (line 455)
-* --kill-at: Options. (line 1535)
-* --large-address-aware: Options. (line 1540)
-* --library-path=DIR: Options. (line 318)
-* --library=NAMESPEC: Options. (line 285)
-* --local-store=lo:hi: SPU ELF. (line 24)
-* --major-image-version: Options. (line 1549)
-* --major-os-version: Options. (line 1554)
-* --major-subsystem-version: Options. (line 1558)
-* --minor-image-version: Options. (line 1563)
-* --minor-os-version: Options. (line 1568)
-* --minor-subsystem-version: Options. (line 1572)
-* --mri-script=MRI-CMDFILE: Options. (line 139)
-* --multi-subspace: HPPA ELF32. (line 6)
-* --nmagic: Options. (line 387)
-* --no-accept-unknown-input-arch: Options. (line 661)
-* --no-add-needed: Options. (line 683)
-* --no-allow-shlib-undefined: Options. (line 898)
-* --no-as-needed: Options. (line 671)
-* --no-check-sections: Options. (line 765)
-* --no-define-common: Options. (line 787)
-* --no-demangle: Options. (line 816)
-* --no-dotsyms: PowerPC64 ELF64. (line 33)
-* --no-enum-size-warning: ARM. (line 94)
-* --no-gc-sections: Options. (line 848)
-* --no-keep-memory: Options. (line 877)
-* --no-multi-toc: PowerPC64 ELF64. (line 74)
-* --no-omagic: Options. (line 401)
-* --no-opd-optimize: PowerPC64 ELF64. (line 48)
-* --no-overlays: SPU ELF. (line 9)
-* --no-print-gc-sections: Options. (line 856)
-* --no-relax: Xtensa. (line 56)
-* --no-tls-optimize <1>: PowerPC64 ELF64. (line 43)
-* --no-tls-optimize: PowerPC ELF32. (line 48)
-* --no-toc-optimize: PowerPC64 ELF64. (line 60)
-* --no-trampoline: Options. (line 1783)
-* --no-undefined: Options. (line 884)
-* --no-undefined-version: Options. (line 917)
-* --no-warn-mismatch: Options. (line 930)
-* --no-warn-search-mismatch: Options. (line 939)
-* --no-whole-archive: Options. (line 943)
-* --noinhibit-exec: Options. (line 947)
-* --non-overlapping-opd: PowerPC64 ELF64. (line 54)
-* --oformat: Options. (line 959)
-* --omagic: Options. (line 392)
-* --out-implib: Options. (line 1585)
-* --output-def: Options. (line 1577)
-* --output=OUTPUT: Options. (line 407)
-* --pic-executable: Options. (line 972)
-* --pic-veneer: M68HC11/68HC12. (line 38)
-* --plugin: SPU ELF. (line 6)
-* --print-gc-sections: Options. (line 856)
-* --print-map: Options. (line 350)
-* --reduce-memory-overheads: Options. (line 1398)
-* --relax: Options. (line 988)
-* --relax on i960: i960. (line 31)
-* --relax on PowerPC: PowerPC ELF32. (line 6)
-* --relax on Xtensa: Xtensa. (line 27)
-* --relocatable: Options. (line 436)
-* --script=SCRIPT: Options. (line 479)
-* --sdata-got: PowerPC ELF32. (line 30)
-* --section-alignment: Options. (line 1754)
-* --section-start SECTIONNAME=ORG: Options. (line 1161)
-* --secure-plt: PowerPC ELF32. (line 23)
-* --sort-common: Options. (line 1108)
-* --sort-section alignment: Options. (line 1118)
-* --sort-section name: Options. (line 1114)
-* --split-by-file: Options. (line 1122)
-* --split-by-reloc: Options. (line 1127)
-* --stack: Options. (line 1760)
-* --stack-analysis: SPU ELF. (line 29)
-* --stats: Options. (line 1140)
-* --strip-all: Options. (line 466)
-* --strip-debug: Options. (line 470)
-* --stub-group-size: PowerPC64 ELF64. (line 6)
-* --stub-group-size=N: HPPA ELF32. (line 12)
-* --subsystem: Options. (line 1767)
-* --support-old-code: ARM. (line 6)
-* --sysroot: Options. (line 1144)
-* --target-help: Options. (line 869)
-* --target1-abs: ARM. (line 27)
-* --target1-rel: ARM. (line 27)
-* --target2=TYPE: ARM. (line 32)
-* --thumb-entry=ENTRY: ARM. (line 17)
-* --trace: Options. (line 475)
-* --trace-symbol=SYMBOL: Options. (line 544)
-* --traditional-format: Options. (line 1149)
-* --undefined=SYMBOL: Options. (line 501)
-* --unique[=SECTION]: Options. (line 519)
-* --unresolved-symbols: Options. (line 1176)
-* --use-blx: ARM. (line 57)
-* --verbose: Options. (line 1205)
-* --version: Options. (line 528)
-* --version-script=VERSION-SCRIPTFILE: Options. (line 1211)
-* --vfp11-denorm-fix: ARM. (line 66)
-* --warn-common: Options. (line 1218)
-* --warn-constructors: Options. (line 1286)
-* --warn-multiple-gp: Options. (line 1291)
-* --warn-once: Options. (line 1305)
-* --warn-section-align: Options. (line 1309)
-* --warn-shared-textrel: Options. (line 1316)
-* --warn-unresolved-symbols: Options. (line 1319)
-* --whole-archive: Options. (line 1328)
-* --wrap: Options. (line 1342)
-* -AARCH: Options. (line 103)
-* -aKEYWORD: Options. (line 96)
-* -assert KEYWORD: Options. (line 693)
-* -b FORMAT: Options. (line 115)
-* -Bdynamic: Options. (line 696)
-* -Bgroup: Options. (line 706)
-* -Bshareable: Options. (line 1100)
-* -Bstatic: Options. (line 713)
-* -Bsymbolic: Options. (line 728)
-* -Bsymbolic-functions: Options. (line 735)
-* -c MRI-CMDFILE: Options. (line 139)
-* -call_shared: Options. (line 696)
-* -d: Options. (line 149)
-* -dc: Options. (line 149)
-* -dn: Options. (line 713)
-* -dp: Options. (line 149)
-* -dT SCRIPT: Options. (line 488)
-* -dy: Options. (line 696)
-* -E: Options. (line 179)
-* -e ENTRY: Options. (line 158)
-* -EB: Options. (line 198)
-* -EL: Options. (line 201)
-* -F: Options. (line 226)
-* -f: Options. (line 205)
-* -fini: Options. (line 250)
-* -G: Options. (line 259)
-* -g: Options. (line 256)
-* -hNAME: Options. (line 267)
-* -i: Options. (line 276)
-* -IFILE: Options. (line 829)
-* -init: Options. (line 279)
-* -LDIR: Options. (line 318)
-* -lNAMESPEC: Options. (line 285)
-* -M: Options. (line 350)
-* -m EMULATION: Options. (line 340)
-* -Map: Options. (line 873)
-* -N: Options. (line 392)
-* -n: Options. (line 387)
-* -non_shared: Options. (line 713)
-* -nostdlib: Options. (line 953)
-* -O LEVEL: Options. (line 413)
-* -o OUTPUT: Options. (line 407)
-* -pie: Options. (line 972)
-* -q: Options. (line 423)
-* -qmagic: Options. (line 982)
-* -Qy: Options. (line 985)
-* -r: Options. (line 436)
-* -R FILE: Options. (line 455)
-* -rpath: Options. (line 1023)
-* -rpath-link: Options. (line 1045)
-* -S: Options. (line 470)
-* -s: Options. (line 466)
-* -shared: Options. (line 1100)
-* -soname=NAME: Options. (line 267)
-* -static: Options. (line 713)
-* -t: Options. (line 475)
-* -T SCRIPT: Options. (line 479)
-* -Tbss ORG: Options. (line 1170)
-* -Tdata ORG: Options. (line 1170)
-* -Ttext ORG: Options. (line 1170)
-* -u SYMBOL: Options. (line 501)
-* -Ur: Options. (line 509)
-* -V: Options. (line 528)
-* -v: Options. (line 528)
-* -X: Options. (line 538)
-* -x: Options. (line 534)
-* -Y PATH: Options. (line 553)
-* -y SYMBOL: Options. (line 544)
-* -z defs: Options. (line 884)
-* -z KEYWORD: Options. (line 557)
-* -z muldefs: Options. (line 892)
-* .: Location Counter. (line 6)
-* /DISCARD/: Output Section Discarding.
- (line 21)
-* :PHDR: Output Section Phdr.
- (line 6)
-* =FILLEXP: Output Section Fill.
- (line 6)
-* >REGION: Output Section Region.
- (line 6)
-* [COMMON]: Input Section Common.
- (line 29)
-* ABSOLUTE (MRI): MRI. (line 33)
-* absolute and relocatable symbols: Expression Section. (line 6)
-* absolute expressions: Expression Section. (line 6)
-* ABSOLUTE(EXP): Builtin Functions. (line 10)
-* ADDR(SECTION): Builtin Functions. (line 17)
-* address, section: Output Section Address.
- (line 6)
-* ALIAS (MRI): MRI. (line 44)
-* ALIGN (MRI): MRI. (line 50)
-* align expression: Builtin Functions. (line 36)
-* align location counter: Builtin Functions. (line 36)
-* ALIGN(ALIGN): Builtin Functions. (line 36)
-* ALIGN(EXP,ALIGN): Builtin Functions. (line 36)
-* ALIGN(SECTION_ALIGN): Forced Output Alignment.
- (line 6)
-* ALIGNOF(SECTION): Builtin Functions. (line 62)
-* allocating memory: MEMORY. (line 6)
-* architecture: Miscellaneous Commands.
- (line 46)
-* architectures: Options. (line 103)
-* archive files, from cmd line: Options. (line 285)
-* archive search path in linker script: File Commands. (line 71)
-* arithmetic: Expressions. (line 6)
-* arithmetic operators: Operators. (line 6)
-* ARM interworking support: ARM. (line 6)
-* AS_NEEDED(FILES): File Commands. (line 51)
-* ASSERT: Miscellaneous Commands.
- (line 9)
-* assertion in linker script: Miscellaneous Commands.
- (line 9)
-* assignment in scripts: Assignments. (line 6)
-* AT(LMA): Output Section LMA. (line 6)
-* AT>LMA_REGION: Output Section LMA. (line 6)
-* automatic data imports: WIN32. (line 170)
-* back end: BFD. (line 6)
-* BASE (MRI): MRI. (line 54)
-* BE8: ARM. (line 23)
-* BFD canonical format: Canonical format. (line 11)
-* BFD requirements: BFD. (line 16)
-* big-endian objects: Options. (line 198)
-* binary input format: Options. (line 115)
-* BLOCK(EXP): Builtin Functions. (line 75)
-* bug criteria: Bug Criteria. (line 6)
-* bug reports: Bug Reporting. (line 6)
-* bugs in ld: Reporting Bugs. (line 6)
-* BYTE(EXPRESSION): Output Section Data.
- (line 6)
-* C++ constructors, arranging in link: Output Section Keywords.
- (line 19)
-* CHIP (MRI): MRI. (line 58)
-* COLLECT_NO_DEMANGLE: Environment. (line 29)
-* combining symbols, warnings on: Options. (line 1218)
-* command files: Scripts. (line 6)
-* command line: Options. (line 6)
-* common allocation: Options. (line 149)
-* common allocation in linker script: Miscellaneous Commands.
- (line 20)
-* common symbol placement: Input Section Common.
- (line 6)
-* compatibility, MRI: Options. (line 139)
-* constants in linker scripts: Constants. (line 6)
-* CONSTRUCTORS: Output Section Keywords.
- (line 19)
-* constructors: Options. (line 509)
-* constructors, arranging in link: Output Section Keywords.
- (line 19)
-* crash of linker: Bug Criteria. (line 9)
-* CREATE_OBJECT_SYMBOLS: Output Section Keywords.
- (line 9)
-* creating a DEF file: WIN32. (line 137)
-* cross reference table: Options. (line 775)
-* cross references: Miscellaneous Commands.
- (line 30)
-* current output location: Location Counter. (line 6)
-* data: Output Section Data.
- (line 6)
-* DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions.
- (line 80)
-* DATA_SEGMENT_END(EXP): Builtin Functions. (line 101)
-* DATA_SEGMENT_RELRO_END(OFFSET, EXP): Builtin Functions. (line 107)
-* dbx: Options. (line 1154)
-* DEF files, creating: Options. (line 1577)
-* default emulation: Environment. (line 21)
-* default input format: Environment. (line 9)
-* DEFINED(SYMBOL): Builtin Functions. (line 118)
-* deleting local symbols: Options. (line 534)
-* demangling, default: Environment. (line 29)
-* demangling, from command line: Options. (line 816)
-* direct linking to a dll: WIN32. (line 218)
-* discarding sections: Output Section Discarding.
- (line 6)
-* discontinuous memory: MEMORY. (line 6)
-* DLLs, creating: Options. (line 1483)
-* DLLs, linking to: Options. (line 1608)
-* dot: Location Counter. (line 6)
-* dot inside sections: Location Counter. (line 36)
-* dot outside sections: Location Counter. (line 66)
-* dynamic linker, from command line: Options. (line 829)
-* dynamic symbol table: Options. (line 179)
-* ELF program headers: PHDRS. (line 6)
-* emulation: Options. (line 340)
-* emulation, default: Environment. (line 21)
-* END (MRI): MRI. (line 62)
-* endianness: Options. (line 198)
-* entry point: Entry Point. (line 6)
-* entry point, from command line: Options. (line 158)
-* entry point, thumb: ARM. (line 17)
-* ENTRY(SYMBOL): Entry Point. (line 6)
-* error on valid input: Bug Criteria. (line 12)
-* example of linker script: Simple Example. (line 6)
-* exporting DLL symbols: WIN32. (line 19)
-* expression evaluation order: Evaluation. (line 6)
-* expression sections: Expression Section. (line 6)
-* expression, absolute: Builtin Functions. (line 10)
-* expressions: Expressions. (line 6)
-* EXTERN: Miscellaneous Commands.
- (line 13)
-* fatal signal: Bug Criteria. (line 9)
-* file name wildcard patterns: Input Section Wildcards.
- (line 6)
-* FILEHDR: PHDRS. (line 61)
-* filename symbols: Output Section Keywords.
- (line 9)
-* fill pattern, entire section: Output Section Fill.
- (line 6)
-* FILL(EXPRESSION): Output Section Data.
- (line 39)
-* finalization function: Options. (line 250)
-* first input file: File Commands. (line 79)
-* first instruction: Entry Point. (line 6)
-* FIX_V4BX: ARM. (line 44)
-* FORCE_COMMON_ALLOCATION: Miscellaneous Commands.
- (line 20)
-* forcing input section alignment: Forced Input Alignment.
- (line 6)
-* forcing output section alignment: Forced Output Alignment.
- (line 6)
-* forcing the creation of dynamic sections: Options. (line 432)
-* FORMAT (MRI): MRI. (line 66)
-* functions in expressions: Builtin Functions. (line 6)
-* garbage collection <1>: Input Section Keep. (line 6)
-* garbage collection: Options. (line 848)
-* generating optimized output: Options. (line 413)
-* GNU linker: Overview. (line 6)
-* GNUTARGET: Environment. (line 9)
-* GROUP(FILES): File Commands. (line 44)
-* grouping input files: File Commands. (line 44)
-* groups of archives: Options. (line 643)
-* H8/300 support: H8/300. (line 6)
-* header size: Builtin Functions. (line 183)
-* heap size: Options. (line 1519)
-* help: Options. (line 865)
-* holes: Location Counter. (line 12)
-* holes, filling: Output Section Data.
- (line 39)
-* HPPA multiple sub-space stubs: HPPA ELF32. (line 6)
-* HPPA stub grouping: HPPA ELF32. (line 12)
-* i960 support: i960. (line 6)
-* image base: Options. (line 1526)
-* implicit linker scripts: Implicit Linker Scripts.
- (line 6)
-* import libraries: WIN32. (line 10)
-* INCLUDE FILENAME: File Commands. (line 9)
-* including a linker script: File Commands. (line 9)
-* including an entire archive: Options. (line 1328)
-* incremental link: Options. (line 276)
-* INHIBIT_COMMON_ALLOCATION: Miscellaneous Commands.
- (line 25)
-* initialization function: Options. (line 279)
-* initialized data in ROM: Output Section LMA. (line 26)
-* input file format in linker script: Format Commands. (line 35)
-* input filename symbols: Output Section Keywords.
- (line 9)
-* input files in linker scripts: File Commands. (line 16)
-* input files, displaying: Options. (line 475)
-* input format: Options. (line 115)
-* input object files in linker scripts: File Commands. (line 16)
-* input section alignment: Forced Input Alignment.
- (line 6)
-* input section basics: Input Section Basics.
- (line 6)
-* input section wildcards: Input Section Wildcards.
- (line 6)
-* input sections: Input Section. (line 6)
-* INPUT(FILES): File Commands. (line 16)
-* integer notation: Constants. (line 6)
-* integer suffixes: Constants. (line 12)
-* internal object-file format: Canonical format. (line 11)
-* invalid input: Bug Criteria. (line 14)
-* K and M integer suffixes: Constants. (line 12)
-* KEEP: Input Section Keep. (line 6)
-* l =: MEMORY. (line 72)
-* lazy evaluation: Evaluation. (line 6)
-* ld bugs, reporting: Bug Reporting. (line 6)
-* LDEMULATION: Environment. (line 21)
-* len =: MEMORY. (line 72)
-* LENGTH =: MEMORY. (line 72)
-* LENGTH(MEMORY): Builtin Functions. (line 135)
-* library search path in linker script: File Commands. (line 71)
-* link map: Options. (line 350)
-* link-time runtime library search path: Options. (line 1045)
-* linker crash: Bug Criteria. (line 9)
-* linker script concepts: Basic Script Concepts.
- (line 6)
-* linker script example: Simple Example. (line 6)
-* linker script file commands: File Commands. (line 6)
-* linker script format: Script Format. (line 6)
-* linker script input object files: File Commands. (line 16)
-* linker script simple commands: Simple Commands. (line 6)
-* linker scripts: Scripts. (line 6)
-* LIST (MRI): MRI. (line 77)
-* little-endian objects: Options. (line 201)
-* LOAD (MRI): MRI. (line 84)
-* load address: Output Section LMA. (line 6)
-* LOADADDR(SECTION): Builtin Functions. (line 138)
-* loading, preventing: Output Section Type.
- (line 22)
-* local symbols, deleting: Options. (line 538)
-* location counter: Location Counter. (line 6)
-* LONG(EXPRESSION): Output Section Data.
- (line 6)
-* M and K integer suffixes: Constants. (line 12)
-* M68HC11 and 68HC12 support: M68HC11/68HC12. (line 6)
-* machine architecture: Miscellaneous Commands.
- (line 46)
-* machine dependencies: Machine Dependent. (line 6)
-* mapping input sections to output sections: Input Section. (line 6)
-* MAX: Builtin Functions. (line 143)
-* MEMORY: MEMORY. (line 6)
-* memory region attributes: MEMORY. (line 32)
-* memory regions: MEMORY. (line 6)
-* memory regions and sections: Output Section Region.
- (line 6)
-* memory usage: Options. (line 877)
-* MIN: Builtin Functions. (line 146)
-* MRI compatibility: MRI. (line 6)
-* MSP430 extra sections: MSP430. (line 11)
-* NAME (MRI): MRI. (line 90)
-* name, section: Output Section Name.
- (line 6)
-* names: Symbols. (line 6)
-* naming the output file: Options. (line 407)
-* NEXT(EXP): Builtin Functions. (line 150)
-* NMAGIC: Options. (line 387)
-* NO_ENUM_SIZE_WARNING: ARM. (line 94)
-* NOCROSSREFS(SECTIONS): Miscellaneous Commands.
- (line 30)
-* NOLOAD: Output Section Type.
- (line 22)
-* not enough room for program headers: Builtin Functions. (line 188)
-* o =: MEMORY. (line 67)
-* objdump -i: BFD. (line 6)
-* object file management: BFD. (line 6)
-* object files: Options. (line 29)
-* object formats available: BFD. (line 6)
-* object size: Options. (line 259)
-* OMAGIC: Options. (line 392)
-* opening object files: BFD outline. (line 6)
-* operators for arithmetic: Operators. (line 6)
-* options: Options. (line 6)
-* ORDER (MRI): MRI. (line 95)
-* org =: MEMORY. (line 67)
-* ORIGIN =: MEMORY. (line 67)
-* ORIGIN(MEMORY): Builtin Functions. (line 156)
-* orphan: Orphan Sections. (line 6)
-* output file after errors: Options. (line 947)
-* output file format in linker script: Format Commands. (line 10)
-* output file name in linker script: File Commands. (line 61)
-* output section alignment: Forced Output Alignment.
- (line 6)
-* output section attributes: Output Section Attributes.
- (line 6)
-* output section data: Output Section Data.
- (line 6)
-* OUTPUT(FILENAME): File Commands. (line 61)
-* OUTPUT_ARCH(BFDARCH): Miscellaneous Commands.
- (line 46)
-* OUTPUT_FORMAT(BFDNAME): Format Commands. (line 10)
-* OVERLAY: Overlay Description.
- (line 6)
-* overlays: Overlay Description.
- (line 6)
-* partial link: Options. (line 436)
-* PHDRS: PHDRS. (line 6)
-* PIC_VENEER: M68HC11/68HC12. (line 38)
-* position independent executables: Options. (line 974)
-* PowerPC ELF32 options: PowerPC ELF32. (line 13)
-* PowerPC GOT: PowerPC ELF32. (line 30)
-* PowerPC long branches: PowerPC ELF32. (line 6)
-* PowerPC PLT: PowerPC ELF32. (line 13)
-* PowerPC stub symbols: PowerPC ELF32. (line 44)
-* PowerPC TLS optimization: PowerPC ELF32. (line 48)
-* PowerPC64 dot symbols: PowerPC64 ELF64. (line 33)
-* PowerPC64 ELF64 options: PowerPC64 ELF64. (line 6)
-* PowerPC64 multi-TOC: PowerPC64 ELF64. (line 74)
-* PowerPC64 OPD optimization: PowerPC64 ELF64. (line 48)
-* PowerPC64 OPD spacing: PowerPC64 ELF64. (line 54)
-* PowerPC64 stub grouping: PowerPC64 ELF64. (line 6)
-* PowerPC64 stub symbols: PowerPC64 ELF64. (line 29)
-* PowerPC64 TLS optimization: PowerPC64 ELF64. (line 43)
-* PowerPC64 TOC optimization: PowerPC64 ELF64. (line 60)
-* precedence in expressions: Operators. (line 6)
-* prevent unnecessary loading: Output Section Type.
- (line 22)
-* program headers: PHDRS. (line 6)
-* program headers and sections: Output Section Phdr.
- (line 6)
-* program headers, not enough room: Builtin Functions. (line 188)
-* program segments: PHDRS. (line 6)
-* PROVIDE: PROVIDE. (line 6)
-* PROVIDE_HIDDEN: PROVIDE_HIDDEN. (line 6)
-* PUBLIC (MRI): MRI. (line 103)
-* QUAD(EXPRESSION): Output Section Data.
- (line 6)
-* quoted symbol names: Symbols. (line 6)
-* read-only text: Options. (line 387)
-* read/write from cmd line: Options. (line 392)
-* regions of memory: MEMORY. (line 6)
-* relative expressions: Expression Section. (line 6)
-* relaxing addressing modes: Options. (line 988)
-* relaxing on H8/300: H8/300. (line 9)
-* relaxing on i960: i960. (line 31)
-* relaxing on M68HC11: M68HC11/68HC12. (line 12)
-* relaxing on Xtensa: Xtensa. (line 27)
-* relocatable and absolute symbols: Expression Section. (line 6)
-* relocatable output: Options. (line 436)
-* removing sections: Output Section Discarding.
- (line 6)
-* reporting bugs in ld: Reporting Bugs. (line 6)
-* requirements for BFD: BFD. (line 16)
-* retain relocations in final executable: Options. (line 423)
-* retaining specified symbols: Options. (line 1009)
-* ROM initialized data: Output Section LMA. (line 26)
-* round up expression: Builtin Functions. (line 36)
-* round up location counter: Builtin Functions. (line 36)
-* runtime library name: Options. (line 267)
-* runtime library search path: Options. (line 1023)
-* runtime pseudo-relocation: WIN32. (line 196)
-* scaled integers: Constants. (line 12)
-* scommon section: Input Section Common.
- (line 20)
-* script files: Options. (line 479)
-* scripts: Scripts. (line 6)
-* search directory, from cmd line: Options. (line 318)
-* search path in linker script: File Commands. (line 71)
-* SEARCH_DIR(PATH): File Commands. (line 71)
-* SECT (MRI): MRI. (line 109)
-* section address: Output Section Address.
- (line 6)
-* section address in expression: Builtin Functions. (line 17)
-* section alignment: Builtin Functions. (line 62)
-* section alignment, warnings on: Options. (line 1309)
-* section data: Output Section Data.
- (line 6)
-* section fill pattern: Output Section Fill.
- (line 6)
-* section load address: Output Section LMA. (line 6)
-* section load address in expression: Builtin Functions. (line 138)
-* section name: Output Section Name.
- (line 6)
-* section name wildcard patterns: Input Section Wildcards.
- (line 6)
-* section size: Builtin Functions. (line 167)
-* section, assigning to memory region: Output Section Region.
- (line 6)
-* section, assigning to program header: Output Section Phdr.
- (line 6)
-* SECTIONS: SECTIONS. (line 6)
-* sections, discarding: Output Section Discarding.
- (line 6)
-* segment origins, cmd line: Options. (line 1170)
-* SEGMENT_START(SEGMENT, DEFAULT): Builtin Functions. (line 159)
-* segments, ELF: PHDRS. (line 6)
-* shared libraries: Options. (line 1102)
-* SHORT(EXPRESSION): Output Section Data.
- (line 6)
-* SIZEOF(SECTION): Builtin Functions. (line 167)
-* SIZEOF_HEADERS: Builtin Functions. (line 183)
-* small common symbols: Input Section Common.
- (line 20)
-* SORT: Input Section Wildcards.
- (line 58)
-* SORT_BY_ALIGNMENT: Input Section Wildcards.
- (line 54)
-* SORT_BY_NAME: Input Section Wildcards.
- (line 46)
-* SPU: SPU ELF. (line 29)
-* SPU ELF options: SPU ELF. (line 6)
-* SPU extra overlay stubs: SPU ELF. (line 19)
-* SPU local store size: SPU ELF. (line 24)
-* SPU overlay stub symbols: SPU ELF. (line 15)
-* SPU overlays: SPU ELF. (line 9)
-* SPU plugins: SPU ELF. (line 6)
-* SQUAD(EXPRESSION): Output Section Data.
- (line 6)
-* stack size: Options. (line 1760)
-* standard Unix system: Options. (line 7)
-* start of execution: Entry Point. (line 6)
-* STARTUP(FILENAME): File Commands. (line 79)
-* strip all symbols: Options. (line 466)
-* strip debugger symbols: Options. (line 470)
-* stripping all but some symbols: Options. (line 1009)
-* SUBALIGN(SUBSECTION_ALIGN): Forced Input Alignment.
- (line 6)
-* suffixes for integers: Constants. (line 12)
-* symbol defaults: Builtin Functions. (line 118)
-* symbol definition, scripts: Assignments. (line 6)
-* symbol names: Symbols. (line 6)
-* symbol tracing: Options. (line 544)
-* symbol versions: VERSION. (line 6)
-* symbol-only input: Options. (line 455)
-* symbols, from command line: Options. (line 803)
-* symbols, relocatable and absolute: Expression Section. (line 6)
-* symbols, retaining selectively: Options. (line 1009)
-* synthesizing linker: Options. (line 988)
-* synthesizing on H8/300: H8/300. (line 14)
-* TARGET(BFDNAME): Format Commands. (line 35)
-* TARGET1: ARM. (line 27)
-* TARGET2: ARM. (line 32)
-* thumb entry point: ARM. (line 17)
-* TI COFF versions: TI COFF. (line 6)
-* traditional format: Options. (line 1149)
-* trampoline generation on M68HC11: M68HC11/68HC12. (line 31)
-* trampoline generation on M68HC12: M68HC11/68HC12. (line 31)
-* unallocated address, next: Builtin Functions. (line 150)
-* undefined symbol: Options. (line 501)
-* undefined symbol in linker script: Miscellaneous Commands.
- (line 13)
-* undefined symbols, warnings on: Options. (line 1305)
-* uninitialized data placement: Input Section Common.
- (line 6)
-* unspecified memory: Output Section Data.
- (line 39)
-* usage: Options. (line 865)
-* USE_BLX: ARM. (line 57)
-* using a DEF file: WIN32. (line 42)
-* using auto-export functionality: WIN32. (line 22)
-* Using decorations: WIN32. (line 141)
-* variables, defining: Assignments. (line 6)
-* verbose: Options. (line 1205)
-* version: Options. (line 528)
-* version script: VERSION. (line 6)
-* version script, symbol versions: Options. (line 1211)
-* VERSION {script text}: VERSION. (line 6)
-* versions of symbols: VERSION. (line 6)
-* VFP11_DENORM_FIX: ARM. (line 66)
-* warnings, on combining symbols: Options. (line 1218)
-* warnings, on section alignment: Options. (line 1309)
-* warnings, on undefined symbols: Options. (line 1305)
-* weak externals: WIN32. (line 386)
-* what is this?: Overview. (line 6)
-* wildcard file name patterns: Input Section Wildcards.
- (line 6)
-* Xtensa options: Xtensa. (line 56)
-* Xtensa processors: Xtensa. (line 6)
-
-
-\1f
-Tag Table:
-Node: Top\7f750
-Node: Overview\7f1524
-Node: Invocation\7f2638
-Node: Options\7f3046
-Node: Environment\7f83631
-Node: Scripts\7f85391
-Node: Basic Script Concepts\7f87125
-Node: Script Format\7f89832
-Node: Simple Example\7f90695
-Node: Simple Commands\7f93791
-Node: Entry Point\7f94242
-Node: File Commands\7f95001
-Node: Format Commands\7f98867
-Node: Miscellaneous Commands\7f100833
-Node: Assignments\7f103063
-Node: Simple Assignments\7f103554
-Node: PROVIDE\7f105290
-Node: PROVIDE_HIDDEN\7f106495
-Node: Source Code Reference\7f106739
-Node: SECTIONS\7f110319
-Node: Output Section Description\7f112210
-Node: Output Section Name\7f113263
-Node: Output Section Address\7f114139
-Node: Input Section\7f115788
-Node: Input Section Basics\7f116589
-Node: Input Section Wildcards\7f118939
-Node: Input Section Common\7f123672
-Node: Input Section Keep\7f125154
-Node: Input Section Example\7f125644
-Node: Output Section Data\7f126612
-Node: Output Section Keywords\7f129389
-Node: Output Section Discarding\7f132958
-Node: Output Section Attributes\7f134139
-Node: Output Section Type\7f135143
-Node: Output Section LMA\7f136297
-Node: Forced Output Alignment\7f138810
-Node: Forced Input Alignment\7f139078
-Node: Output Section Region\7f139463
-Node: Output Section Phdr\7f139893
-Node: Output Section Fill\7f140557
-Node: Overlay Description\7f141699
-Node: MEMORY\7f146002
-Node: PHDRS\7f150202
-Node: VERSION\7f155241
-Node: Expressions\7f163033
-Node: Constants\7f163911
-Node: Symbols\7f164472
-Node: Orphan Sections\7f165210
-Node: Location Counter\7f165973
-Node: Operators\7f170409
-Node: Evaluation\7f171331
-Node: Expression Section\7f172695
-Node: Builtin Functions\7f174184
-Node: Implicit Linker Scripts\7f182151
-Node: Machine Dependent\7f182926
-Node: H8/300\7f183897
-Node: i960\7f185522
-Node: M68HC11/68HC12\7f187207
-Node: ARM\7f188910
-Node: HPPA ELF32\7f193760
-Node: MMIX\7f195383
-Node: MSP430\7f196600
-Node: PowerPC ELF32\7f197649
-Node: PowerPC64 ELF64\7f200263
-Node: SPU ELF\7f204677
-Node: TI COFF\7f207309
-Node: WIN32\7f207835
-Node: Xtensa\7f226192
-Node: BFD\7f229314
-Node: BFD outline\7f230769
-Node: BFD information loss\7f232055
-Node: Canonical format\7f234572
-Node: Reporting Bugs\7f238929
-Node: Bug Criteria\7f239623
-Node: Bug Reporting\7f240322
-Node: MRI\7f247361
-Node: GNU Free Documentation License\7f252004
-Node: LD Index\7f271721
-\1f
-End Tag Table
projects / msp430-binutils.git / blobdiff