X-Git-Url: https://oss.titaniummirror.com/gitweb?p=msp430-binutils.git;a=blobdiff_plain;f=ld%2Fld.info;fp=ld%2Fld.info;h=0000000000000000000000000000000000000000;hp=28646e94c7eb756568315f3b171a08ded76dff82;hb=2535b36b22dedcdea35e497d38a1c9c735961d28;hpb=47f73751c91775676bb03af53e83c7f49dfda44f diff --git a/ld/ld.info b/ld/ld.info deleted file mode 100644 index 28646e9..0000000 --- a/ld/ld.info +++ /dev/null @@ -1,7041 +0,0 @@ -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". - - -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 - - -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). - - -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 - - -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 `.dll' in preference to - `lib.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 '' 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. - - - -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. - - -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 - - -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. - - -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. - - -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. - - -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 - - -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'. - - -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. - - -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::. - - -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. - - -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 - - -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. - - -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. - - -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. - - -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. - - -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 - - -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::) - - -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::. - - -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. - - -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 - - -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. - - -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) } - } - - -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)'. - - -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))'. - - -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) - } - } - - -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. - - -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. - - - -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. - - -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 - - -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) : { ... } - ... - } - - -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; - - -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. - - -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. - - -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 } - - -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 } - - -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 } - - -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)); - - -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; - - -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 - ... - } - - -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. - - -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 - - -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; - - -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. - - -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. - - -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'. - - -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::. - - -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'. - - -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. - - -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::). - - -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. - - -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 - - -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). - - -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). - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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_' for global functions, and - `__stack__' for static functions. - `' 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'. - - -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. - - -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 `.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 .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 ' command indicates the _internal_ - name of the output DLL. If `' 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 ' command should be used - instead of `LIBRARY'. If `' does not include a suffix, - the default executable suffix, `.EXE' is appended. - - With either `LIBRARY ' or `NAME ' the optional - specification `BASE = ' may be used to specify a - non-default base address for the image. - - If neither `LIBRARY ' nor `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 - ( ( ( [ = ] ) - | ( = . )) - [ @ ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * - - Declares `' as an exported symbol from the DLL, or - declares `' as an exported alias for `'; or - declares `' as a "forward" alias for the symbol - `' in the DLL `'. Optionally, - the symbol may be exported by the specified ordinal - `' 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 ' 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 '' 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 - `xxx.dll', where `' is set by the `ld' option - `--dll-search-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 `'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. - - -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. - - -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 - - -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 - - -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. - - -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). - - -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 - - -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. - - -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. - - -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. - - -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. - - -File: ld.info, Node: LD Index, Prev: GNU Free Documentation License, Up: Top - -LD Index -******** - -[index] -* 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) - - - -Tag Table: -Node: Top750 -Node: Overview1524 -Node: Invocation2638 -Node: Options3046 -Node: Environment83631 -Node: Scripts85391 -Node: Basic Script Concepts87125 -Node: Script Format89832 -Node: Simple Example90695 -Node: Simple Commands93791 -Node: Entry Point94242 -Node: File Commands95001 -Node: Format Commands98867 -Node: Miscellaneous Commands100833 -Node: Assignments103063 -Node: Simple Assignments103554 -Node: PROVIDE105290 -Node: PROVIDE_HIDDEN106495 -Node: Source Code Reference106739 -Node: SECTIONS110319 -Node: Output Section Description112210 -Node: Output Section Name113263 -Node: Output Section Address114139 -Node: Input Section115788 -Node: Input Section Basics116589 -Node: Input Section Wildcards118939 -Node: Input Section Common123672 -Node: Input Section Keep125154 -Node: Input Section Example125644 -Node: Output Section Data126612 -Node: Output Section Keywords129389 -Node: Output Section Discarding132958 -Node: Output Section Attributes134139 -Node: Output Section Type135143 -Node: Output Section LMA136297 -Node: Forced Output Alignment138810 -Node: Forced Input Alignment139078 -Node: Output Section Region139463 -Node: Output Section Phdr139893 -Node: Output Section Fill140557 -Node: Overlay Description141699 -Node: MEMORY146002 -Node: PHDRS150202 -Node: VERSION155241 -Node: Expressions163033 -Node: Constants163911 -Node: Symbols164472 -Node: Orphan Sections165210 -Node: Location Counter165973 -Node: Operators170409 -Node: Evaluation171331 -Node: Expression Section172695 -Node: Builtin Functions174184 -Node: Implicit Linker Scripts182151 -Node: Machine Dependent182926 -Node: H8/300183897 -Node: i960185522 -Node: M68HC11/68HC12187207 -Node: ARM188910 -Node: HPPA ELF32193760 -Node: MMIX195383 -Node: MSP430196600 -Node: PowerPC ELF32197649 -Node: PowerPC64 ELF64200263 -Node: SPU ELF204677 -Node: TI COFF207309 -Node: WIN32207835 -Node: Xtensa226192 -Node: BFD229314 -Node: BFD outline230769 -Node: BFD information loss232055 -Node: Canonical format234572 -Node: Reporting Bugs238929 -Node: Bug Criteria239623 -Node: Bug Reporting240322 -Node: MRI247361 -Node: GNU Free Documentation License252004 -Node: LD Index271721 - -End Tag Table