| This is ld.info, produced by makeinfo version 4.8 from ld.texinfo. |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Ld: (ld). The GNU linker. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU linker LD (GNU Binutils) version 2.23.91. |
| |
| Copyright (C) 1991-2013 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.3 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.23.91. |
| |
| This document is distributed under the terms of the GNU Free |
| Documentation License version 1.3. 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. Specifying a script in this |
| way merely augments the main linker script, with the extra commands |
| placed after the main script; use the `-T' option to replace the |
| default linker script entirely, but note the effect of the `INSERT' |
| command. *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,--start-group foo.o bar.o -Wl,--end-group |
| |
| This is important, because otherwise the compiler driver program may |
| silently drop the linker options, resulting in a bad link. Confusion |
| may also arise when passing options that require values through a |
| driver, as the use of a space between option and argument acts as a |
| separator, and causes the driver to pass only the option to the linker |
| and the argument to the compiler. In this case, it is simplest to use |
| the joined forms of both single- and multiple-letter options, such as: |
| |
| gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map |
| |
| 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. |
| |
| `-a KEYWORD' |
| 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. |
| |
| `--audit AUDITLIB' |
| Adds AUDITLIB to the `DT_AUDIT' entry of the dynamic section. |
| AUDITLIB is not checked for existence, nor will it use the |
| DT_SONAME specified in the library. If specified multiple times |
| `DT_AUDIT' will contain a colon separated list of audit interfaces |
| to use. If the linker finds an object with an audit entry while |
| searching for shared libraries, it will add a corresponding |
| `DT_DEPAUDIT' entry in the output file. This option is only |
| meaningful on ELF platforms supporting the rtld-audit interface. |
| |
| `-A ARCHITECTURE' |
| `--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::. |
| |
| `--depaudit AUDITLIB' |
| `-P AUDITLIB' |
| Adds AUDITLIB to the `DT_DEPAUDIT' entry of the dynamic section. |
| AUDITLIB is not checked for existence, nor will it use the |
| DT_SONAME specified in the library. If specified multiple times |
| `DT_DEPAUDIT' will contain a colon separated list of audit |
| interfaces to use. This option is only meaningful on ELF |
| platforms supporting the rtld-audit interface. The -P option is |
| provided for Solaris compatibility. |
| |
| `-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. |
| |
| `--exclude-modules-for-implib MODULE,MODULE,...' |
| Specifies a list of object files or archive members, from which |
| symbols should not be automatically exported, but which should be |
| copied wholesale into the import library being generated during |
| the link. The module names may be delimited by commas or colons, |
| and must match exactly the filenames used by `ld' to open the |
| files; for archive members, this is simply the member name, but |
| for object files the name listed must include and match precisely |
| any path used to specify the input file on the linker's |
| command-line. This option is available only for the i386 PE |
| targeted port of the linker. Symbols explicitly listed in a .def |
| file are still exported, regardless of this option. |
| |
| `-E' |
| `--export-dynamic' |
| `--no-export-dynamic' |
| When creating a dynamically linked executable, using the `-E' |
| option or the `--export-dynamic' option causes the linker to 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 either of these options (or use the |
| `--no-export-dynamic' option to restore the default behavior), 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'. |
| |
| Note that this option is specific to ELF targeted ports. PE |
| targets support a similar function to export all symbols from a |
| DLL or EXE; see the description of `--export-all-symbols' below. |
| |
| `-EB' |
| Link big-endian objects. This affects the default output format. |
| |
| `-EL' |
| Link little-endian objects. This affects the default output |
| format. |
| |
| `-f NAME' |
| `--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. |
| |
| `-G VALUE' |
| `--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 ELF that support putting large and small objects into |
| different sections. This is ignored for other object file formats. |
| |
| `-h NAME' |
| `-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. |
| |
| `-l NAMESPEC' |
| `--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, otherwise 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. |
| |
| `-L SEARCHDIR' |
| `--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. `-L' options |
| do not affect how `ld' searches for a linker script unless `-T' |
| option is specified. |
| |
| 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. |
| |
| `-m EMULATION' |
| 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 disable linking against |
| shared libraries. If the output format supports Unix style magic |
| numbers, mark the output as `NMAGIC'. |
| |
| `-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. |
| |
| `global' |
| This option is only meaningful when building a shared object. |
| It makes the symbols defined by this shared object available |
| for symbol resolution of subsequently loaded libraries. |
| |
| `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. |
| |
| `stack-size=VALUE' |
| Specify a stack size for in an ELF `PT_GNU_STACK' segment. |
| Specifying zero will override any default non-zero sized |
| `PT_GNU_STACK' segment creation. |
| |
| |
| 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 or not. `--as-needed' causes a |
| DT_NEEDED tag to only be emitted for a library that _at that point |
| in the link_ satisfies a non-weak undefined symbol reference from |
| a regular object file or, if the library is not found in the |
| DT_NEEDED lists of other libraries, a non-weak undefined symbol |
| reference from another dynamic library. Object files or libraries |
| appearing on the command line _after_ the library in question do |
| not affect whether the library is seen as needed. This is similar |
| to the rules for extraction of object files from archives. |
| `--no-as-needed' restores the default behaviour. |
| |
| `--add-needed' |
| `--no-add-needed' |
| These two options have been deprecated because of the similarity of |
| their names to the `--as-needed' and `--no-as-needed' options. |
| They have been replaced by `--copy-dt-needed-entries' and |
| `--no-copy-dt-needed-entries'. |
| |
| `-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'. Section overlap is not usually checked for |
| relocatable links. You can force checking in that case by using |
| the `--check-sections' option. |
| |
| `--copy-dt-needed-entries' |
| `--no-copy-dt-needed-entries' |
| This option affects the treatment of dynamic libraries referred to |
| by DT_NEEDED tags _inside_ ELF dynamic libraries mentioned on the |
| command line. Normally the linker won't add a DT_NEEDED tag to the |
| output binary for each library mentioned in a DT_NEEDED tag in an |
| input dynamic library. With `--copy-dt-needed-entries' specified |
| on the command line however any dynamic libraries that follow it |
| will have their DT_NEEDED entries added. The default behaviour |
| can be restored with `--no-copy-dt-needed-entries'. |
| |
| This option also has an effect on the resolution of symbols in |
| dynamic libraries. With `--copy-dt-needed-entries' dynamic |
| libraries mentioned on the command line will be recursively |
| searched, following their DT_NEEDED tags to other libraries, in |
| order to resolve symbols required by the output binary. With the |
| default setting however the searching of dynamic libraries that |
| follow it will stop with the dynamic library itself. No DT_NEEDED |
| links will be traversed to resolve symbols. |
| |
| `--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. If the symbol is defined as a |
| common value then any files where this happens appear next. |
| Finally any files that reference the symbol are listed. |
| |
| `--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. |
| |
| `-IFILE' |
| `--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' |
| `--no-fatal-warnings' |
| Treat all warnings as errors. The default behaviour can be |
| restored with the option `--no-fatal-warnings'. |
| |
| `--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. The default behaviour |
| (of not performing this garbage collection) can be restored by |
| specifying `--no-gc-sections' on the command line. |
| |
| `--gc-sections' decides which input sections are used by examining |
| symbols and relocations. The section containing the entry symbol |
| and all sections containing symbols undefined on the command-line |
| will be kept, as will sections containing symbols referenced by |
| dynamic objects. Note that when building shared libraries, the |
| linker must assume that any visible symbol is referenced. Once |
| this initial set of sections has been determined, the linker |
| recursively marks as used any section referenced by their |
| relocations. See `--entry' and `--undefined'. |
| |
| This option can be set when doing a partial link (enabled with |
| option `-r'). In this case the root of symbols kept must be |
| explicitly specified either by an `--entry' or `--undefined' |
| option or by a `ENTRY' command in the linker script. |
| |
| `--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. |
| |
| `--print-output-format' |
| Print the name of the default output format (perhaps influenced by |
| other command-line options). This is the string that would appear |
| in an `OUTPUT_FORMAT' linker script command (*note File |
| Commands::). |
| |
| `--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 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 default behaviour is to report errors for any undefined symbols |
| referenced in shared libraries if the linker is being used to |
| create an executable, but to allow them if the linker is being |
| used to create a shared library. |
| |
| The reasons for allowing undefined symbol references in shared |
| libraries specified at link time are that: |
| |
| * A shared library specified at link time may not be the same |
| as the one that is available at load time, so the symbol |
| might actually be resolvable at load time. |
| |
| * There are some operating systems, eg BeOS and HPPA, where |
| undefined symbols in shared libraries are normal. |
| |
| The BeOS kernel for example patches shared libraries at load |
| time to select whichever function is most appropriate for the |
| current architecture. This is used, for example, to |
| dynamically select an appropriate memset function. |
| |
| `--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' |
| `--no-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 target specific, |
| global optimizations that become possible when the linker resolves |
| addressing in the program, such as relaxing address modes, |
| synthesizing new instructions, selecting shorter version of current |
| instructions, and combining constant values. |
| |
| 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. |
| |
| On platforms where `--relax' is accepted the option `--no-relax' |
| can be used to disable the feature. |
| |
| `--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, for native linkers, if the `-rpath' and |
| `-rpath-link' options were not used, search the contents of |
| the environment variable `LD_RUN_PATH'. |
| |
| 4. On SunOS, if the `-rpath' option was not used, search any |
| directories specified using `-L' options. |
| |
| 5. For a native linker, search 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' |
| `--sort-common=ascending' |
| `--sort-common=descending' |
| This option tells `ld' to sort the common symbols by alignment in |
| ascending or descending order when it places them in the |
| appropriate output sections. The symbol alignments considered are |
| sixteen-byte or larger, eight-byte, four-byte, two-byte, and |
| one-byte. This is to prevent gaps between symbols due to alignment |
| constraints. If no sorting order is specified, then descending |
| order is assumed. |
| |
| `--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. |
| |
| `-Ttext-segment=ORG' |
| When creating an ELF executable or shared object, it will set the |
| address of the first byte of the text segment. |
| |
| `-Trodata-segment=ORG' |
| When creating an ELF executable or shared object for a target where |
| the read-only data is in its own segment separate from the |
| executable text, it will set the address of the first byte of the |
| read-only data segment. |
| |
| `-Tldata-segment=ORG' |
| When creating an ELF executable or shared object for x86-64 medium |
| memory model, it will set the address of the first byte of the |
| ldata segment. |
| |
| `--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[=NUMBER]' |
| 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. If the |
| optional NUMBER argument > 1, plugin symbol status will also be |
| displayed. |
| |
| `--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 fully supported on ELF |
| platforms which support shared libraries; see *Note VERSION::. It |
| is partially supported on PE platforms, which can use version |
| scripts to filter symbol visibility in auto-export mode: any |
| symbols marked `local' in the version script will not be exported. |
| *Note WIN32::. |
| |
| `--warn-common' |
| Warn when a common symbol is combined with another common symbol |
| or with a symbol definition. Unix linkers allow this somewhat |
| sloppy practice, 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 practice, 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-alternate-em' |
| Warn if an object has alternate ELF machine code. |
| |
| `--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. |
| |
| `--no-ld-generated-unwind-info' |
| Request creation of `.eh_frame' unwind info for linker generated |
| code sections like PLT. This option is on by default if linker |
| generated unwind info is supported. |
| |
| `--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 new dynamic tags will be created as |
| needed and older dynamic tags will be omitted. 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-long-section-names' |
| `--disable-long-section-names' |
| The PE variants of the Coff object format add an extension that |
| permits the use of section names longer than eight characters, the |
| normal limit for Coff. By default, these names are only allowed |
| in object files, as fully-linked executable images do not carry |
| the Coff string table required to support the longer names. As a |
| GNU extension, it is possible to allow their use in executable |
| images as well, or to (probably pointlessly!) disallow it in |
| object files, by using these two options. Executable images |
| generated with these long section names are slightly non-standard, |
| carrying as they do a string table, and may generate confusing |
| output when examined with non-GNU PE-aware tools, such as file |
| viewers and dumpers. However, GDB relies on the use of PE long |
| section names to find Dwarf-2 debug information sections in an |
| executable image at runtime, and so if neither option is specified |
| on the command-line, `ld' will enable long section names, |
| overriding the default and technically correct behaviour, when it |
| finds the presence of debug information while linking an executable |
| image and not stripping symbols. [This option is valid for all PE |
| targeted ports 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] |
| |
| `--leading-underscore' |
| `--no-leading-underscore' |
| For most targets default symbol-prefix is an underscore and is |
| defined in target's description. By this option it is possible to |
| disable/enable the default underscore symbol-prefix. |
| |
| `--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] |
| |
| `--exclude-all-symbols' |
| Specifies no symbols should be automatically exported. [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] |
| |
| `--disable-large-address-aware' |
| Reverts the effect of a previous `--large-address-aware' option. |
| This is useful if `--large-address-aware' is always set by the |
| compiler driver (e.g. Cygwin gcc) and the executable does not |
| support virtual addresses greater than 2 gigabytes. [This option |
| is specific to PE targeted ports of the linker] |
| |
| `--major-image-version VALUE' |
| Sets the major number of the "image version". Defaults to 1. |
| [This option is specific to the i386 PE targeted port of the |
| linker] |
| |
| `--major-os-version VALUE' |
| Sets the major number of the "os version". Defaults to 4. [This |
| option is specific to the i386 PE targeted port of the linker] |
| |
| `--major-subsystem-version VALUE' |
| Sets the major number of the "subsystem version". Defaults to 4. |
| [This option is specific to the i386 PE targeted port of the |
| linker] |
| |
| `--minor-image-version VALUE' |
| Sets the minor number of the "image version". Defaults to 0. |
| [This option is specific to the i386 PE targeted port of the |
| linker] |
| |
| `--minor-os-version VALUE' |
| Sets the minor number of the "os version". Defaults to 0. [This |
| option is specific to the i386 PE targeted port of the linker] |
| |
| `--minor-subsystem-version VALUE' |
| Sets the minor number of the "subsystem version". Defaults to 0. |
| [This option is specific to the i386 PE targeted port of the |
| linker] |
| |
| `--output-def FILE' |
| The linker will create the file FILE which will contain a DEF file |
| corresponding to the DLL the linker is generating. This DEF file |
| (which should be called `*.def') may be used to create an import |
| library with `dlltool' or may be used as a reference to |
| automatically or implicitly exported symbols. [This option is |
| specific to the i386 PE targeted port of the linker] |
| |
| `--out-implib FILE' |
| The linker will create the file FILE which will contain an import |
| lib corresponding to the DLL the linker is generating. This import |
| lib (which should be called `*.dll.a' or `*.a' may be used to link |
| clients against the generated DLL; this behaviour makes it |
| possible to skip a separate `dlltool' import library creation step. |
| [This option is specific to the i386 PE targeted port of the |
| linker] |
| |
| `--enable-auto-image-base' |
| Automatically choose the image base for DLLs, unless one is |
| specified using the `--image-base' argument. By using a hash |
| generated from the dllname to create unique image bases for each |
| DLL, in-memory collisions and relocations which can delay program |
| execution are avoided. [This option is specific to the i386 PE |
| targeted port of the linker] |
| |
| `--disable-auto-image-base' |
| Do not automatically generate a unique image base. If there is no |
| user-specified image base (`--image-base') then use the platform |
| default. [This option is specific to the i386 PE targeted port of |
| the linker] |
| |
| `--dll-search-prefix STRING' |
| When linking dynamically to a dll without an import library, |
| search for `<string><basename>.dll' in preference to |
| `lib<basename>.dll'. This behaviour allows easy distinction |
| between DLLs built for the various "subplatforms": native, cygwin, |
| uwin, pw, etc. For instance, cygwin DLLs typically use |
| `--dll-search-prefix=cyg'. [This option is specific to the i386 |
| PE targeted port of the linker] |
| |
| `--enable-auto-import' |
| Do sophisticated linking of `_symbol' to `__imp__symbol' for DATA |
| imports from DLLs, and create the necessary thunking symbols when |
| building the import libraries with those DATA exports. Note: Use |
| of the 'auto-import' extension will cause the text section of the |
| image file to be made writable. This does not conform to the |
| PE-COFF format specification published by Microsoft. |
| |
| Note - use of the 'auto-import' extension will also cause read only |
| data which would normally be placed into the .rdata section to be |
| placed into the .data section instead. This is in order to work |
| around a problem with consts that is described here: |
| http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html |
| |
| Using 'auto-import' generally will 'just work' - but sometimes you |
| may see this message: |
| |
| "variable '<var>' can't be auto-imported. Please read the |
| documentation for ld's `--enable-auto-import' for details." |
| |
| This message occurs when some (sub)expression accesses an address |
| ultimately given by the sum of two constants (Win32 import tables |
| only allow one). Instances where this may occur include accesses |
| to member fields of struct variables imported from a DLL, as well |
| as using a constant index into an array variable imported from a |
| DLL. Any multiword variable (arrays, structs, long long, etc) may |
| trigger this error condition. However, regardless of the exact |
| data type of the offending exported variable, ld will always |
| detect it, issue the warning, and exit. |
| |
| There are several ways to address this difficulty, regardless of |
| the data type of the exported variable: |
| |
| One way is to use -enable-runtime-pseudo-reloc switch. This leaves |
| the task of adjusting references in your client code for runtime |
| environment, so this method works only when runtime environment |
| supports this feature. |
| |
| A second solution is to force one of the 'constants' to be a |
| variable - that is, unknown and un-optimizable at compile time. |
| For arrays, there are two possibilities: a) make the indexee (the |
| array's address) a variable, or b) make the 'constant' index a |
| variable. Thus: |
| |
| extern type extern_array[]; |
| extern_array[1] --> |
| { volatile type *t=extern_array; t[1] } |
| |
| or |
| |
| extern type extern_array[]; |
| extern_array[1] --> |
| { volatile int t=1; extern_array[t] } |
| |
| For structs (and most other multiword data types) the only option |
| is to make the struct itself (or the long long, or the ...) |
| variable: |
| |
| extern struct s extern_struct; |
| extern_struct.field --> |
| { volatile struct s *t=&extern_struct; t->field } |
| |
| or |
| |
| extern long long extern_ll; |
| extern_ll --> |
| { volatile long long * local_ll=&extern_ll; *local_ll } |
| |
| A third method of dealing with this difficulty is to abandon |
| 'auto-import' for the offending symbol and mark it with |
| `__declspec(dllimport)'. However, in practice 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 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] |
| |
| The following options set flags in the `DllCharacteristics' field |
| of the PE file header: [These options are specific to PE targeted |
| ports of the linker] |
| |
| `--dynamicbase' |
| The image base address may be relocated using address space layout |
| randomization (ASLR). This feature was introduced with MS Windows |
| Vista for i386 PE targets. |
| |
| `--forceinteg' |
| Code integrity checks are enforced. |
| |
| `--nxcompat' |
| The image is compatible with the Data Execution Prevention. This |
| feature was introduced with MS Windows XP SP2 for i386 PE targets. |
| |
| `--no-isolation' |
| Although the image understands isolation, do not isolate the image. |
| |
| `--no-seh' |
| The image does not use SEH. No SE handler may be called from this |
| image. |
| |
| `--no-bind' |
| Do not bind this image. |
| |
| `--wdmdriver' |
| The driver uses the MS Windows Driver Model. |
| |
| `--tsaware' |
| The image is Terminal Server aware. |
| |
| `--insert-timestamp' |
| Insert a real timestamp into the image, rather than the default |
| value of zero. This will result in a slightly different results |
| with each invocation, which could be helpful for distributing |
| unique images. |
| |
| 2.1.2 Options specific to C6X uClinux targets |
| --------------------------------------------- |
| |
| The C6X uClinux target uses a binary format called DSBT to support |
| shared libraries. Each shared library in the system needs to have a |
| unique index; all executables use an index of 0. |
| |
| `--dsbt-size SIZE' |
| This option sets the number of entires in the DSBT of the current |
| executable or shared library to SIZE. The default is to create a |
| table with 64 entries. |
| |
| `--dsbt-index INDEX' |
| This option sets the DSBT index of the current executable or |
| shared library to INDEX. The default is 0, which is appropriate |
| for generating executables. If a shared library is generated with |
| a DSBT index of 0, the `R_C6000_DSBT_INDEX' relocs are copied into |
| the output file. |
| |
| The `--no-merge-exidx-entries' switch disables the merging of |
| adjacent exidx entries in frame unwind info. |
| |
| |
| 2.1.3 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. |
| |
| |
| 2.1.4 Options specific to Motorola 68K target |
| --------------------------------------------- |
| |
| The following options are supported to control handling of GOT |
| generation when linking for 68K targets. |
| |
| `--got=TYPE' |
| This option tells the linker which GOT generation scheme to use. |
| TYPE should be one of `single', `negative', `multigot' or |
| `target'. For more information refer to the Info entry for `ld'. |
| |
| |
| 2.1.5 Options specific to MIPS targets |
| -------------------------------------- |
| |
| The following options are supported to control microMIPS instruction |
| generation when linking for MIPS targets. |
| |
| `--insn32' |
| `--no-insn32' |
| These options control the choice of microMIPS instructions used in |
| code generated by the linker, such as that in the PLT or lazy |
| binding stubs, or in relaxation. If `--insn32' is used, then the |
| linker only uses 32-bit instruction encodings. By default or if |
| `--no-insn32' is used, all instruction encodings are used, |
| including 16-bit ones where possible. |
| |
| |
| |
| 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 means 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 |
| |
| * REGION_ALIAS:: Assign alias names to memory regions |
| * 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 a target specific symbol, if it is defined; For many |
| targets this is `start', but PE and BeOS based systems for example |
| check a list of possible entry symbols, matching the first one |
| found. |
| |
| * 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. |
| |
| You can place `INCLUDE' directives at the top level, in `MEMORY' or |
| `SECTIONS' commands, or in output section descriptions. |
| |
| `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: REGION_ALIAS, 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: REGION_ALIAS, Next: Miscellaneous Commands, Prev: Format Commands, Up: Simple Commands |
| |
| 3.4.4 Assign alias names to memory regions |
| ------------------------------------------ |
| |
| Alias names can be added to existing memory regions created with the |
| *Note MEMORY:: command. Each name corresponds to at most one memory |
| region. |
| |
| REGION_ALIAS(ALIAS, REGION) |
| |
| The `REGION_ALIAS' function creates an alias name ALIAS for the |
| memory region REGION. This allows a flexible mapping of output sections |
| to memory regions. An example follows. |
| |
| Suppose we have an application for embedded systems which come with |
| various memory storage devices. All have a general purpose, volatile |
| memory `RAM' that allows code execution or data storage. Some may have |
| a read-only, non-volatile memory `ROM' that allows code execution and |
| read-only data access. The last variant is a read-only, non-volatile |
| memory `ROM2' with read-only data access and no code execution |
| capability. We have four output sections: |
| |
| * `.text' program code; |
| |
| * `.rodata' read-only data; |
| |
| * `.data' read-write initialized data; |
| |
| * `.bss' read-write zero initialized data. |
| |
| The goal is to provide a linker command file that contains a system |
| independent part defining the output sections and a system dependent |
| part mapping the output sections to the memory regions available on the |
| system. Our embedded systems come with three different memory setups |
| `A', `B' and `C': |
| Section Variant A Variant B Variant C |
| .text RAM ROM ROM |
| .rodata RAM ROM ROM2 |
| .data RAM RAM/ROM RAM/ROM2 |
| .bss RAM RAM RAM |
| The notation `RAM/ROM' or `RAM/ROM2' means that this section is |
| loaded into region `ROM' or `ROM2' respectively. Please note that the |
| load address of the `.data' section starts in all three variants at the |
| end of the `.rodata' section. |
| |
| The base linker script that deals with the output sections follows. |
| It includes the system dependent `linkcmds.memory' file that describes |
| the memory layout: |
| INCLUDE linkcmds.memory |
| |
| SECTIONS |
| { |
| .text : |
| { |
| *(.text) |
| } > REGION_TEXT |
| .rodata : |
| { |
| *(.rodata) |
| rodata_end = .; |
| } > REGION_RODATA |
| .data : AT (rodata_end) |
| { |
| data_start = .; |
| *(.data) |
| } > REGION_DATA |
| data_size = SIZEOF(.data); |
| data_load_start = LOADADDR(.data); |
| .bss : |
| { |
| *(.bss) |
| } > REGION_BSS |
| } |
| |
| Now we need three different `linkcmds.memory' files to define memory |
| regions and alias names. The content of `linkcmds.memory' for the three |
| variants `A', `B' and `C': |
| `A' |
| Here everything goes into the `RAM'. |
| MEMORY |
| { |
| RAM : ORIGIN = 0, LENGTH = 4M |
| } |
| |
| REGION_ALIAS("REGION_TEXT", RAM); |
| REGION_ALIAS("REGION_RODATA", RAM); |
| REGION_ALIAS("REGION_DATA", RAM); |
| REGION_ALIAS("REGION_BSS", RAM); |
| |
| `B' |
| Program code and read-only data go into the `ROM'. Read-write |
| data goes into the `RAM'. An image of the initialized data is |
| loaded into the `ROM' and will be copied during system start into |
| the `RAM'. |
| MEMORY |
| { |
| ROM : ORIGIN = 0, LENGTH = 3M |
| RAM : ORIGIN = 0x10000000, LENGTH = 1M |
| } |
| |
| REGION_ALIAS("REGION_TEXT", ROM); |
| REGION_ALIAS("REGION_RODATA", ROM); |
| REGION_ALIAS("REGION_DATA", RAM); |
| REGION_ALIAS("REGION_BSS", RAM); |
| |
| `C' |
| Program code goes into the `ROM'. Read-only data goes into the |
| `ROM2'. Read-write data goes into the `RAM'. An image of the |
| initialized data is loaded into the `ROM2' and will be copied |
| during system start into the `RAM'. |
| MEMORY |
| { |
| ROM : ORIGIN = 0, LENGTH = 2M |
| ROM2 : ORIGIN = 0x10000000, LENGTH = 1M |
| RAM : ORIGIN = 0x20000000, LENGTH = 1M |
| } |
| |
| REGION_ALIAS("REGION_TEXT", ROM); |
| REGION_ALIAS("REGION_RODATA", ROM2); |
| REGION_ALIAS("REGION_DATA", RAM); |
| REGION_ALIAS("REGION_BSS", RAM); |
| |
| It is possible to write a common system initialization routine to |
| copy the `.data' section from `ROM' or `ROM2' into the `RAM' if |
| necessary: |
| #include <string.h> |
| |
| extern char data_start []; |
| extern char data_size []; |
| extern char data_load_start []; |
| |
| void copy_data(void) |
| { |
| if (data_start != data_load_start) |
| { |
| memcpy(data_start, data_load_start, (size_t) data_size); |
| } |
| } |
| |
| |
| File: ld.info, Node: Miscellaneous Commands, Prev: REGION_ALIAS, Up: Simple Commands |
| |
| 3.4.5 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. |
| |
| `INSERT [ AFTER | BEFORE ] OUTPUT_SECTION' |
| This command is typically used in a script specified by `-T' to |
| augment the default `SECTIONS' with, for example, overlays. It |
| inserts all prior linker script statements after (or before) |
| OUTPUT_SECTION, and also causes `-T' to not override the default |
| linker script. The exact insertion point is as for orphan |
| sections. *Note Location Counter::. The insertion happens after |
| the linker has mapped input sections to output sections. Prior to |
| the insertion, since `-T' scripts are parsed before the default |
| linker script, statements in the `-T' script occur before the |
| default linker script statements in the internal linker |
| representation of the script. In particular, input section |
| assignments will be made to `-T' output sections before those in |
| the default script. Here is an example of how a `-T' script using |
| `INSERT' might look: |
| |
| SECTIONS |
| { |
| OVERLAY : |
| { |
| .ov1 { ov1*(.text) } |
| .ov2 { ov2*(.text) } |
| } |
| } |
| INSERT AFTER .text; |
| |
| `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. |
| |
| `LD_FEATURE(STRING)' |
| This command may be used to modify `ld' behavior. If STRING is |
| `"SANE_EXPR"' then absolute symbols and numbers in a script are |
| simply treated as numbers everywhere. *Note Expression Section::. |
| |
| |
| 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 |
| * HIDDEN:: HIDDEN |
| * 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: HIDDEN, 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: HIDDEN, Next: PROVIDE, Prev: Simple Assignments, Up: Assignments |
| |
| 3.5.2 HIDDEN |
| ------------ |
| |
| For ELF targeted ports, define a symbol that will be hidden and won't be |
| exported. The syntax is `HIDDEN(SYMBOL = EXPRESSION)'. |
| |
| Here is the example from *Note Simple Assignments::, rewritten to use |
| `HIDDEN': |
| |
| HIDDEN(floating_point = 0); |
| SECTIONS |
| { |
| .text : |
| { |
| *(.text) |
| HIDDEN(_etext = .); |
| } |
| HIDDEN(_bdata = (. + 3) & ~ 3); |
| .data : { *(.data) } |
| } |
| In this case none of the three symbols will be visible outside this |
| module. |
| |
| |
| File: ld.info, Node: PROVIDE, Next: PROVIDE_HIDDEN, Prev: HIDDEN, Up: Assignments |
| |
| 3.5.3 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.4 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.5 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 an 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 its 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) | ALIGN_WITH_INPUT] |
| [SUBALIGN(SUBSECTION_ALIGN)] |
| [CONSTRAINT] |
| { |
| 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. This address is optional, but if it is provided |
| then the output address will be set exactly as specified. |
| |
| If the output address is not specified then one will be chosen for |
| the section, based on the heuristic below. This address will be |
| adjusted to fit the alignment requirement of the output section. The |
| alignment requirement is the strictest alignment of any input section |
| contained within the output section. |
| |
| The output section address heuristic is as follows: |
| |
| * If an output memory REGION is set for the section then it is added |
| to this region and its address will be the next free address in |
| that region. |
| |
| * If the MEMORY command has been used to create a list of memory |
| regions then the first region which has attributes compatible with |
| the section is selected to contain it. The section's output |
| address will be the next free address in that region; *Note |
| MEMORY::. |
| |
| * If no memory regions were specified, or none match the section then |
| the output address will be based on the current value of the |
| location counter. |
| |
| 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 any of the `.text' input sections. |
| |
| 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, provided that the section is non-empty. (Empty |
| sections are ignored). |
| |
| |
| 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) |
| |
| To refine the sections that are included based on the section flags |
| of an input section, INPUT_SECTION_FLAGS may be used. |
| |
| Here is a simple example for using Section header flags for ELF |
| sections: |
| |
| SECTIONS { |
| .text : { INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) } |
| .text2 : { INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) } |
| } |
| |
| In this example, the output section `.text' will be comprised of any |
| input section matching the name *(.text) whose section header flags |
| `SHF_MERGE' and `SHF_STRINGS' are set. The output section `.text2' |
| will be comprised of any input section matching the name *(.text) whose |
| section header flag `SHF_WRITE' is clear. |
| |
| You can also specify files within archives by writing a pattern |
| matching the archive, a colon, then the pattern matching the file, with |
| no whitespace around the colon. |
| |
| `archive:file' |
| matches file within archive |
| |
| `archive:' |
| matches the whole archive |
| |
| `:file' |
| matches file but not one in an archive |
| |
| Either one or both of `archive' and `file' can contain shell |
| wildcards. On DOS based file systems, the linker will assume that a |
| single letter followed by a colon is a drive specifier, so `c:myfile.o' |
| is a simple file specification, not `myfile.o' within an archive called |
| `c'. `archive:file' filespecs may also be used within an |
| `EXCLUDE_FILE' list, but may not appear in other linker script |
| contexts. For instance, you cannot extract a file from an archive by |
| using `archive:file' in an `INPUT' command. |
| |
| 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 is not an `archive:file' specifier |
| and 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 descending |
| order by alignment before placing them in the output file. Larger |
| alignments are placed before smaller alignments in order to reduce the |
| amount of padding necessary. |
| |
| `SORT_BY_INIT_PRIORITY' is very similar to `SORT_BY_NAME'. The |
| difference is `SORT_BY_INIT_PRIORITY' will sort sections into ascending |
| order by numerical value of the GCC init_priority attribute encoded in |
| the section name 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 two 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 two 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. |
| |
| `SORT_NONE' disables section sorting by ignoring the command line |
| section sorting option. |
| |
| 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)] |
| [CONSTRAINT] |
| { |
| 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 Constraint:: Output section constraint |
| * 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. |
| 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 virtual address is specified by the |
| *note Output Section Address:: described earlier. The load address is |
| specified by the `AT' or `AT>' keywords. Specifying a load address is |
| optional. |
| |
| The `AT' keyword takes an expression as an argument. This specifies |
| the exact load address of the section. The `AT>' keyword takes the |
| name of a memory region as an argument. *Note MEMORY::. The load |
| address of the section is set to the next free address in the region, |
| aligned to the section's alignment requirements. |
| |
| If neither `AT' nor `AT>' is specified for an allocatable section, |
| the linker will use the following heuristic to determine the load |
| address: |
| |
| * If the section has a specific VMA address, then this is used as |
| the LMA address as well. |
| |
| * If the section is not allocatable then its LMA is set to its VMA. |
| |
| * Otherwise if a memory region can be found that is compatible with |
| the current section, and this region contains at least one |
| section, then the LMA is set so the difference between the VMA and |
| LMA is the same as the difference between the VMA and LMA of the |
| last section in the located region. |
| |
| * If no memory regions have been declared then a default region that |
| covers the entire address space is used in the previous step. |
| |
| * If no suitable region could be found, or there was no previous |
| section then the LMA is set equal to the VMA. |
| |
| 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. As an |
| alternative you can force the output section alignment to the maximum |
| alignment of all its input sections with ALIGN_WITH_INPUT. The |
| alignment forced by ALIGN_WITH_INPUT is used even in case the load and |
| virtual memory regions are different. |
| |
| |
| File: ld.info, Node: Forced Input Alignment, Next: Output Section Constraint, 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 Constraint, Next: Output Section Region, Prev: Forced Input Alignment, Up: Output Section Attributes |
| |
| 3.6.8.5 Output Section Constraint |
| ................................. |
| |
| You can specify that an output section should only be created if all of |
| its input sections are read-only or all of its input sections are |
| read-write by using the keyword `ONLY_IF_RO' and `ONLY_IF_RW' |
| respectively. |
| |
| |
| File: ld.info, Node: Output Section Region, Next: Output Section Phdr, Prev: Output Section Constraint, Up: Output Section Attributes |
| |
| 3.6.8.6 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.7 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.8 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' construct (*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 are 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 within the `MEMORY' command. However you can add |
| later alias names to existing memory regions with the *Note |
| REGION_ALIAS:: command. |
| |
| 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 attributes that follow |
| |
| 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. The headers are processed in order and it is |
| usual for them to map to sections in ascending load address order. |
| |
| 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 |
|