1 This is ld.info, produced by makeinfo version 4.8 from ld.texinfo.
4 * Ld: (ld). The GNU linker.
7 This file documents the GNU linker LD (GNU Binutils) version 2.17.90.
9 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
10 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.1 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
16 Texts. A copy of the license is included in the section entitled "GNU
17 Free Documentation License".
20 File: ld.info, Node: Top, Next: Overview, Up: (dir)
25 This file documents the GNU linker ld (GNU Binutils) version 2.17.90.
27 This document is distributed under the terms of the GNU Free
28 Documentation License. A copy of the license is included in the
29 section entitled "GNU Free Documentation License".
34 * Invocation:: Invocation
35 * Scripts:: Linker Scripts
37 * Machine Dependent:: Machine Dependent Features
41 * Reporting Bugs:: Reporting Bugs
42 * MRI:: MRI Compatible Script Files
43 * GNU Free Documentation License:: GNU Free Documentation License
47 File: ld.info, Node: Overview, Next: Invocation, Prev: Top, Up: Top
52 `ld' combines a number of object and archive files, relocates their
53 data and ties up symbol references. Usually the last step in compiling
54 a program is to run `ld'.
56 `ld' accepts Linker Command Language files written in a superset of
57 AT&T's Link Editor Command Language syntax, to provide explicit and
58 total control over the linking process.
60 This version of `ld' uses the general purpose BFD libraries to
61 operate on object files. This allows `ld' to read, combine, and write
62 object files in many different formats--for example, COFF or `a.out'.
63 Different formats may be linked together to produce any available kind
64 of object file. *Note BFD::, for more information.
66 Aside from its flexibility, the GNU linker is more helpful than other
67 linkers in providing diagnostic information. Many linkers abandon
68 execution immediately upon encountering an error; whenever possible,
69 `ld' continues executing, allowing you to identify other errors (or, in
70 some cases, to get an output file in spite of the error).
73 File: ld.info, Node: Invocation, Next: Scripts, Prev: Overview, Up: Top
78 The GNU linker `ld' is meant to cover a broad range of situations, and
79 to be as compatible as possible with other linkers. As a result, you
80 have many choices to control its behavior.
84 * Options:: Command Line Options
85 * Environment:: Environment Variables
88 File: ld.info, Node: Options, Next: Environment, Up: Invocation
90 2.1 Command Line Options
91 ========================
93 The linker supports a plethora of command-line options, but in actual
94 practice few of them are used in any particular context. For instance,
95 a frequent use of `ld' is to link standard Unix object files on a
96 standard, supported Unix system. On such a system, to link a file
99 ld -o OUTPUT /lib/crt0.o hello.o -lc
101 This tells `ld' to produce a file called OUTPUT as the result of
102 linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
103 which will come from the standard search directories. (See the
104 discussion of the `-l' option below.)
106 Some of the command-line options to `ld' may be specified at any
107 point in the command line. However, options which refer to files, such
108 as `-l' or `-T', cause the file to be read at the point at which the
109 option appears in the command line, relative to the object files and
110 other file options. Repeating non-file options with a different
111 argument will either have no further effect, or override prior
112 occurrences (those further to the left on the command line) of that
113 option. Options which may be meaningfully specified more than once are
114 noted in the descriptions below.
116 Non-option arguments are object files or archives which are to be
117 linked together. They may follow, precede, or be mixed in with
118 command-line options, except that an object file argument may not be
119 placed between an option and its argument.
121 Usually the linker is invoked with at least one object file, but you
122 can specify other forms of binary input files using `-l', `-R', and the
123 script command language. If _no_ binary input files at all are
124 specified, the linker does not produce any output, and issues the
125 message `No input files'.
127 If the linker cannot recognize the format of an object file, it will
128 assume that it is a linker script. A script specified in this way
129 augments the main linker script used for the link (either the default
130 linker script or the one specified by using `-T'). This feature
131 permits the linker to link against a file which appears to be an object
132 or an archive, but actually merely defines some symbol values, or uses
133 `INPUT' or `GROUP' to load other objects. Note that specifying a
134 script in this way merely augments the main linker script; use the `-T'
135 option to replace the default linker script entirely. *Note Scripts::.
137 For options whose names are a single letter, option arguments must
138 either follow the option letter without intervening whitespace, or be
139 given as separate arguments immediately following the option that
142 For options whose names are multiple letters, either one dash or two
143 can precede the option name; for example, `-trace-symbol' and
144 `--trace-symbol' are equivalent. Note--there is one exception to this
145 rule. Multiple letter options that start with a lower case 'o' can
146 only be preceded by two dashes. This is to reduce confusion with the
147 `-o' option. So for example `-omagic' sets the output file name to
148 `magic' whereas `--omagic' sets the NMAGIC flag on the output.
150 Arguments to multiple-letter options must either be separated from
151 the option name by an equals sign, or be given as separate arguments
152 immediately following the option that requires them. For example,
153 `--trace-symbol foo' and `--trace-symbol=foo' are equivalent. Unique
154 abbreviations of the names of multiple-letter options are accepted.
156 Note--if the linker is being invoked indirectly, via a compiler
157 driver (e.g. `gcc') then all the linker command line options should be
158 prefixed by `-Wl,' (or whatever is appropriate for the particular
159 compiler driver) like this:
161 gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
163 This is important, because otherwise the compiler driver program may
164 silently drop the linker options, resulting in a bad link.
166 Here is a table of the generic command line switches accepted by the
170 Read command-line options from FILE. The options read are
171 inserted in place of the original @FILE option. If FILE does not
172 exist, or cannot be read, then the option will be treated
173 literally, and not removed.
175 Options in FILE are separated by whitespace. A whitespace
176 character may be included in an option by surrounding the entire
177 option in either single or double quotes. Any character
178 (including a backslash) may be included by prefixing the character
179 to be included with a backslash. The FILE may itself contain
180 additional @FILE options; any such options will be processed
184 This option is supported for HP/UX compatibility. The KEYWORD
185 argument must be one of the strings `archive', `shared', or
186 `default'. `-aarchive' is functionally equivalent to `-Bstatic',
187 and the other two keywords are functionally equivalent to
188 `-Bdynamic'. This option may be used any number of times.
191 `--architecture=ARCHITECTURE'
192 In the current release of `ld', this option is useful only for the
193 Intel 960 family of architectures. In that `ld' configuration, the
194 ARCHITECTURE argument identifies the particular architecture in
195 the 960 family, enabling some safeguards and modifying the
196 archive-library search path. *Note `ld' and the Intel 960 family:
199 Future releases of `ld' may support similar functionality for
200 other architecture families.
203 `--format=INPUT-FORMAT'
204 `ld' may be configured to support more than one kind of object
205 file. If your `ld' is configured this way, you can use the `-b'
206 option to specify the binary format for input object files that
207 follow this option on the command line. Even when `ld' is
208 configured to support alternative object formats, you don't
209 usually need to specify this, as `ld' should be configured to
210 expect as a default input format the most usual format on each
211 machine. INPUT-FORMAT is a text string, the name of a particular
212 format supported by the BFD libraries. (You can list the
213 available binary formats with `objdump -i'.) *Note BFD::.
215 You may want to use this option if you are linking files with an
216 unusual binary format. You can also use `-b' to switch formats
217 explicitly (when linking object files of different formats), by
218 including `-b INPUT-FORMAT' before each group of object files in a
221 The default format is taken from the environment variable
222 `GNUTARGET'. *Note Environment::. You can also define the input
223 format from a script, using the command `TARGET'; see *Note Format
227 `--mri-script=MRI-COMMANDFILE'
228 For compatibility with linkers produced by MRI, `ld' accepts script
229 files written in an alternate, restricted command language,
230 described in *Note MRI Compatible Script Files: MRI. Introduce
231 MRI script files with the option `-c'; use the `-T' option to run
232 linker scripts written in the general-purpose `ld' scripting
233 language. If MRI-CMDFILE does not exist, `ld' looks for it in the
234 directories specified by any `-L' options.
239 These three options are equivalent; multiple forms are supported
240 for compatibility with other linkers. They assign space to common
241 symbols even if a relocatable output file is specified (with
242 `-r'). The script command `FORCE_COMMON_ALLOCATION' has the same
243 effect. *Note Miscellaneous Commands::.
247 Use ENTRY as the explicit symbol for beginning execution of your
248 program, rather than the default entry point. If there is no
249 symbol named ENTRY, the linker will try to parse ENTRY as a number,
250 and use that as the entry address (the number will be interpreted
251 in base 10; you may use a leading `0x' for base 16, or a leading
252 `0' for base 8). *Note Entry Point::, for a discussion of defaults
253 and other ways of specifying the entry point.
255 `--exclude-libs LIB,LIB,...'
256 Specifies a list of archive libraries from which symbols should
257 not be automatically exported. The library names may be delimited
258 by commas or colons. Specifying `--exclude-libs ALL' excludes
259 symbols in all archive libraries from automatic export. This
260 option is available only for the i386 PE targeted port of the
261 linker and for ELF targeted ports. For i386 PE, symbols
262 explicitly listed in a .def file are still exported, regardless of
263 this option. For ELF targeted ports, symbols affected by this
264 option will be treated as hidden.
268 When creating a dynamically linked executable, add all symbols to
269 the dynamic symbol table. The dynamic symbol table is the set of
270 symbols which are visible from dynamic objects at run time.
272 If you do not use this option, the dynamic symbol table will
273 normally contain only those symbols which are referenced by some
274 dynamic object mentioned in the link.
276 If you use `dlopen' to load a dynamic object which needs to refer
277 back to the symbols defined by the program, rather than some other
278 dynamic object, then you will probably need to use this option when
279 linking the program itself.
281 You can also use the dynamic list to control what symbols should
282 be added to the dynamic symbol table if the output format supports
283 it. See the description of `--dynamic-list'.
286 Link big-endian objects. This affects the default output format.
289 Link little-endian objects. This affects the default output
294 When creating an ELF shared object, set the internal DT_AUXILIARY
295 field to the specified name. This tells the dynamic linker that
296 the symbol table of the shared object should be used as an
297 auxiliary filter on the symbol table of the shared object NAME.
299 If you later link a program against this filter object, then, when
300 you run the program, the dynamic linker will see the DT_AUXILIARY
301 field. If the dynamic linker resolves any symbols from the filter
302 object, it will first check whether there is a definition in the
303 shared object NAME. If there is one, it will be used instead of
304 the definition in the filter object. The shared object NAME need
305 not exist. Thus the shared object NAME may be used to provide an
306 alternative implementation of certain functions, perhaps for
307 debugging or for machine specific performance.
309 This option may be specified more than once. The DT_AUXILIARY
310 entries will be created in the order in which they appear on the
315 When creating an ELF shared object, set the internal DT_FILTER
316 field to the specified name. This tells the dynamic linker that
317 the symbol table of the shared object which is being created
318 should be used as a filter on the symbol table of the shared
321 If you later link a program against this filter object, then, when
322 you run the program, the dynamic linker will see the DT_FILTER
323 field. The dynamic linker will resolve symbols according to the
324 symbol table of the filter object as usual, but it will actually
325 link to the definitions found in the shared object NAME. Thus the
326 filter object can be used to select a subset of the symbols
327 provided by the object NAME.
329 Some older linkers used the `-F' option throughout a compilation
330 toolchain for specifying object-file format for both input and
331 output object files. The GNU linker uses other mechanisms for
332 this purpose: the `-b', `--format', `--oformat' options, the
333 `TARGET' command in linker scripts, and the `GNUTARGET'
334 environment variable. The GNU linker will ignore the `-F' option
335 when not creating an ELF shared object.
338 When creating an ELF executable or shared object, call NAME when
339 the executable or shared object is unloaded, by setting DT_FINI to
340 the address of the function. By default, the linker uses `_fini'
341 as the function to call.
344 Ignored. Provided for compatibility with other tools.
348 Set the maximum size of objects to be optimized using the GP
349 register to SIZE. This is only meaningful for object file formats
350 such as MIPS ECOFF which supports putting large and small objects
351 into different sections. This is ignored for other object file
356 When creating an ELF shared object, set the internal DT_SONAME
357 field to the specified name. When an executable is linked with a
358 shared object which has a DT_SONAME field, then when the
359 executable is run the dynamic linker will attempt to load the
360 shared object specified by the DT_SONAME field rather than the
361 using the file name given to the linker.
364 Perform an incremental link (same as option `-r').
367 When creating an ELF executable or shared object, call NAME when
368 the executable or shared object is loaded, by setting DT_INIT to
369 the address of the function. By default, the linker uses `_init'
370 as the function to call.
374 Add the archive or object file specified by NAMESPEC to the list
375 of files to link. This option may be used any number of times.
376 If NAMESPEC is of the form `:FILENAME', `ld' will search the
377 library path for a file called FILENAME, otherise it will search
378 the library path for a file called `libNAMESPEC.a'.
380 On systems which support shared libraries, `ld' may also search for
381 files other than `libNAMESPEC.a'. Specifically, on ELF and SunOS
382 systems, `ld' will search a directory for a library called
383 `libNAMESPEC.so' before searching for one called `libNAMESPEC.a'.
384 (By convention, a `.so' extension indicates a shared library.)
385 Note that this behavior does not apply to `:FILENAME', which
386 always specifies a file called FILENAME.
388 The linker will search an archive only once, at the location where
389 it is specified on the command line. If the archive defines a
390 symbol which was undefined in some object which appeared before
391 the archive on the command line, the linker will include the
392 appropriate file(s) from the archive. However, an undefined
393 symbol in an object appearing later on the command line will not
394 cause the linker to search the archive again.
396 See the `-(' option for a way to force the linker to search
397 archives multiple times.
399 You may list the same archive multiple times on the command line.
401 This type of archive searching is standard for Unix linkers.
402 However, if you are using `ld' on AIX, note that it is different
403 from the behaviour of the AIX linker.
406 `--library-path=SEARCHDIR'
407 Add path SEARCHDIR to the list of paths that `ld' will search for
408 archive libraries and `ld' control scripts. You may use this
409 option any number of times. The directories are searched in the
410 order in which they are specified on the command line.
411 Directories specified on the command line are searched before the
412 default directories. All `-L' options apply to all `-l' options,
413 regardless of the order in which the options appear.
415 If SEARCHDIR begins with `=', then the `=' will be replaced by the
416 "sysroot prefix", a path specified when the linker is configured.
418 The default set of paths searched (without being specified with
419 `-L') depends on which emulation mode `ld' is using, and in some
420 cases also on how it was configured. *Note Environment::.
422 The paths can also be specified in a link script with the
423 `SEARCH_DIR' command. Directories specified this way are searched
424 at the point in which the linker script appears in the command
428 Emulate the EMULATION linker. You can list the available
429 emulations with the `--verbose' or `-V' options.
431 If the `-m' option is not used, the emulation is taken from the
432 `LDEMULATION' environment variable, if that is defined.
434 Otherwise, the default emulation depends upon how the linker was
439 Print a link map to the standard output. A link map provides
440 information about the link, including the following:
442 * Where object files are mapped into memory.
444 * How common symbols are allocated.
446 * All archive members included in the link, with a mention of
447 the symbol which caused the archive member to be brought in.
449 * The values assigned to symbols.
451 Note - symbols whose values are computed by an expression
452 which involves a reference to a previous value of the same
453 symbol may not have correct result displayed in the link map.
454 This is because the linker discards intermediate results and
455 only retains the final value of an expression. Under such
456 circumstances the linker will display the final value
457 enclosed by square brackets. Thus for example a linker
464 will produce the following output in the link map if the `-M'
468 [0x0000000c] foo = (foo * 0x4)
469 [0x0000000c] foo = (foo + 0x8)
471 See *Note Expressions:: for more information about
472 expressions in linker scripts.
476 Turn off page alignment of sections, and mark the output as
477 `NMAGIC' if possible.
481 Set the text and data sections to be readable and writable. Also,
482 do not page-align the data segment, and disable linking against
483 shared libraries. If the output format supports Unix style magic
484 numbers, mark the output as `OMAGIC'. Note: Although a writable
485 text section is allowed for PE-COFF targets, it does not conform
486 to the format specification published by Microsoft.
489 This option negates most of the effects of the `-N' option. It
490 sets the text section to be read-only, and forces the data segment
491 to be page-aligned. Note - this option does not enable linking
492 against shared libraries. Use `-Bdynamic' for this.
496 Use OUTPUT as the name for the program produced by `ld'; if this
497 option is not specified, the name `a.out' is used by default. The
498 script command `OUTPUT' can also specify the output file name.
501 If LEVEL is a numeric values greater than zero `ld' optimizes the
502 output. This might take significantly longer and therefore
503 probably should only be enabled for the final binary. At the
504 moment this option only affects ELF shared library generation.
505 Future releases of the linker may make more use of this option.
506 Also currently there is no difference in the linker's behaviour
507 for different non-zero values of this option. Again this may
508 change with future releases.
512 Leave relocation sections and contents in fully linked executables.
513 Post link analysis and optimization tools may need this
514 information in order to perform correct modifications of
515 executables. This results in larger executables.
517 This option is currently only supported on ELF platforms.
520 Force the output file to have dynamic sections. This option is
521 specific to VxWorks targets.
525 Generate relocatable output--i.e., generate an output file that
526 can in turn serve as input to `ld'. This is often called "partial
527 linking". As a side effect, in environments that support standard
528 Unix magic numbers, this option also sets the output file's magic
529 number to `OMAGIC'. If this option is not specified, an absolute
530 file is produced. When linking C++ programs, this option _will
531 not_ resolve references to constructors; to do that, use `-Ur'.
533 When an input file does not have the same format as the output
534 file, partial linking is only supported if that input file does
535 not contain any relocations. Different output formats can have
536 further restrictions; for example some `a.out'-based formats do
537 not support partial linking with input files in other formats at
540 This option does the same thing as `-i'.
543 `--just-symbols=FILENAME'
544 Read symbol names and their addresses from FILENAME, but do not
545 relocate it or include it in the output. This allows your output
546 file to refer symbolically to absolute locations of memory defined
547 in other programs. You may use this option more than once.
549 For compatibility with other ELF linkers, if the `-R' option is
550 followed by a directory name, rather than a file name, it is
551 treated as the `-rpath' option.
555 Omit all symbol information from the output file.
559 Omit debugger symbol information (but not all symbols) from the
564 Print the names of the input files as `ld' processes them.
567 `--script=SCRIPTFILE'
568 Use SCRIPTFILE as the linker script. This script replaces `ld''s
569 default linker script (rather than adding to it), so COMMANDFILE
570 must specify everything necessary to describe the output file.
571 *Note Scripts::. If SCRIPTFILE does not exist in the current
572 directory, `ld' looks for it in the directories specified by any
573 preceding `-L' options. Multiple `-T' options accumulate.
576 `--default-script=SCRIPTFILE'
577 Use SCRIPTFILE as the default linker script. *Note Scripts::.
579 This option is similar to the `--script' option except that
580 processing of the script is delayed until after the rest of the
581 command line has been processed. This allows options placed after
582 the `--default-script' option on the command line to affect the
583 behaviour of the linker script, which can be important when the
584 linker command line cannot be directly controlled by the user.
585 (eg because the command line is being constructed by another tool,
590 Force SYMBOL to be entered in the output file as an undefined
591 symbol. Doing this may, for example, trigger linking of additional
592 modules from standard libraries. `-u' may be repeated with
593 different option arguments to enter additional undefined symbols.
594 This option is equivalent to the `EXTERN' linker script command.
597 For anything other than C++ programs, this option is equivalent to
598 `-r': it generates relocatable output--i.e., an output file that
599 can in turn serve as input to `ld'. When linking C++ programs,
600 `-Ur' _does_ resolve references to constructors, unlike `-r'. It
601 does not work to use `-Ur' on files that were themselves linked
602 with `-Ur'; once the constructor table has been built, it cannot
603 be added to. Use `-Ur' only for the last partial link, and `-r'
607 Creates a separate output section for every input section matching
608 SECTION, or if the optional wildcard SECTION argument is missing,
609 for every orphan input section. An orphan section is one not
610 specifically mentioned in a linker script. You may use this option
611 multiple times on the command line; It prevents the normal
612 merging of input sections with the same name, overriding output
613 section assignments in a linker script.
618 Display the version number for `ld'. The `-V' option also lists
619 the supported emulations.
623 Delete all local symbols.
627 Delete all temporary local symbols. (These symbols start with
628 system-specific local label prefixes, typically `.L' for ELF
629 systems or `L' for traditional a.out systems.)
632 `--trace-symbol=SYMBOL'
633 Print the name of each linked file in which SYMBOL appears. This
634 option may be given any number of times. On many systems it is
635 necessary to prepend an underscore.
637 This option is useful when you have an undefined symbol in your
638 link but don't know where the reference is coming from.
641 Add PATH to the default library search path. This option exists
642 for Solaris compatibility.
645 The recognized keywords are:
647 Combines multiple reloc sections and sorts them to make
648 dynamic symbol lookup caching possible.
651 Disallows undefined symbols in object files. Undefined
652 symbols in shared libraries are still allowed.
655 Marks the object as requiring executable stack.
658 This option is only meaningful when building a shared object.
659 It marks the object so that its runtime initialization will
660 occur before the runtime initialization of any other objects
661 brought into the process at the same time. Similarly the
662 runtime finalization of the object will occur after the
663 runtime finalization of any other objects.
666 Marks the object that its symbol table interposes before all
667 symbols but the primary executable.
670 When generating an executable or shared library, mark it to
671 tell the dynamic linker to defer function call resolution to
672 the point when the function is called (lazy binding), rather
673 than at load time. Lazy binding is the default.
676 Marks the object that its filters be processed immediately at
680 Allows multiple definitions.
683 Disables multiple reloc sections combining.
686 Disables production of copy relocs.
689 Marks the object that the search for dependencies of this
690 object will ignore any default library search paths.
693 Marks the object shouldn't be unloaded at runtime.
696 Marks the object not available to `dlopen'.
699 Marks the object can not be dumped by `dldump'.
702 Marks the object as not requiring executable stack.
705 Don't create an ELF `PT_GNU_RELRO' segment header in the
709 When generating an executable or shared library, mark it to
710 tell the dynamic linker to resolve all symbols when the
711 program is started, or when the shared library is linked to
712 using dlopen, instead of deferring function call resolution
713 to the point when the function is first called.
716 Marks the object may contain $ORIGIN.
719 Create an ELF `PT_GNU_RELRO' segment header in the object.
721 `max-page-size=VALUE'
722 Set the emulation maximum page size to VALUE.
724 `common-page-size=VALUE'
725 Set the emulation common page size to VALUE.
728 Other keywords are ignored for Solaris compatibility.
731 `--start-group ARCHIVES --end-group'
732 The ARCHIVES should be a list of archive files. They may be
733 either explicit file names, or `-l' options.
735 The specified archives are searched repeatedly until no new
736 undefined references are created. Normally, an archive is
737 searched only once in the order that it is specified on the
738 command line. If a symbol in that archive is needed to resolve an
739 undefined symbol referred to by an object in an archive that
740 appears later on the command line, the linker would not be able to
741 resolve that reference. By grouping the archives, they all be
742 searched repeatedly until all possible references are resolved.
744 Using this option has a significant performance cost. It is best
745 to use it only when there are unavoidable circular references
746 between two or more archives.
748 `--accept-unknown-input-arch'
749 `--no-accept-unknown-input-arch'
750 Tells the linker to accept input files whose architecture cannot be
751 recognised. The assumption is that the user knows what they are
752 doing and deliberately wants to link in these unknown input files.
753 This was the default behaviour of the linker, before release
754 2.14. The default behaviour from release 2.14 onwards is to
755 reject such input files, and so the `--accept-unknown-input-arch'
756 option has been added to restore the old behaviour.
760 This option affects ELF DT_NEEDED tags for dynamic libraries
761 mentioned on the command line after the `--as-needed' option.
762 Normally, the linker will add a DT_NEEDED tag for each dynamic
763 library mentioned on the command line, regardless of whether the
764 library is actually needed. `--as-needed' causes DT_NEEDED tags
765 to only be emitted for libraries that satisfy some symbol
766 reference from regular objects which is undefined at the point
767 that the library was linked. `--no-as-needed' restores the
772 This option affects the treatment of dynamic libraries from ELF
773 DT_NEEDED tags in dynamic libraries mentioned on the command line
774 after the `--no-add-needed' option. Normally, the linker will add
775 a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
776 `--no-add-needed' causes DT_NEEDED tags will never be emitted for
777 those libraries from DT_NEEDED tags. `--add-needed' restores the
781 This option is ignored for SunOS compatibility.
786 Link against dynamic libraries. This is only meaningful on
787 platforms for which shared libraries are supported. This option
788 is normally the default on such platforms. The different variants
789 of this option are for compatibility with various systems. You
790 may use this option multiple times on the command line: it affects
791 library searching for `-l' options which follow it.
794 Set the `DF_1_GROUP' flag in the `DT_FLAGS_1' entry in the dynamic
795 section. This causes the runtime linker to handle lookups in this
796 object and its dependencies to be performed only inside the group.
797 `--unresolved-symbols=report-all' is implied. This option is only
798 meaningful on ELF platforms which support shared libraries.
804 Do not link against shared libraries. This is only meaningful on
805 platforms for which shared libraries are supported. The different
806 variants of this option are for compatibility with various
807 systems. You may use this option multiple times on the command
808 line: it affects library searching for `-l' options which follow
809 it. This option also implies `--unresolved-symbols=report-all'.
810 This option can be used with `-shared'. Doing so means that a
811 shared library is being created but that all of the library's
812 external references must be resolved by pulling in entries from
816 When creating a shared library, bind references to global symbols
817 to the definition within the shared library, if any. Normally, it
818 is possible for a program linked against a shared library to
819 override the definition within the shared library. This option is
820 only meaningful on ELF platforms which support shared libraries.
822 `-Bsymbolic-functions'
823 When creating a shared library, bind references to global function
824 symbols to the definition within the shared library, if any. This
825 option is only meaningful on ELF platforms which support shared
828 `--dynamic-list=DYNAMIC-LIST-FILE'
829 Specify the name of a dynamic list file to the linker. This is
830 typically used when creating shared libraries to specify a list of
831 global symbols whose references shouldn't be bound to the
832 definition within the shared library, or creating dynamically
833 linked executables to specify a list of symbols which should be
834 added to the symbol table in the executable. This option is only
835 meaningful on ELF platforms which support shared libraries.
837 The format of the dynamic list is the same as the version node
838 without scope and node name. See *Note VERSION:: for more
841 `--dynamic-list-data'
842 Include all global data symbols to the dynamic list.
844 `--dynamic-list-cpp-new'
845 Provide the builtin dynamic list for C++ operator new and delete.
846 It is mainly useful for building shared libstdc++.
848 `--dynamic-list-cpp-typeinfo'
849 Provide the builtin dynamic list for C++ runtime type
853 `--no-check-sections'
854 Asks the linker _not_ to check section addresses after they have
855 been assigned to see if there are any overlaps. Normally the
856 linker will perform this check, and if it finds any overlaps it
857 will produce suitable error messages. The linker does know about,
858 and does make allowances for sections in overlays. The default
859 behaviour can be restored by using the command line switch
863 Output a cross reference table. If a linker map file is being
864 generated, the cross reference table is printed to the map file.
865 Otherwise, it is printed on the standard output.
867 The format of the table is intentionally simple, so that it may be
868 easily processed by a script if necessary. The symbols are
869 printed out, sorted by name. For each symbol, a list of file
870 names is given. If the symbol is defined, the first file listed
871 is the location of the definition. The remaining files contain
872 references to the symbol.
875 This option inhibits the assignment of addresses to common symbols.
876 The script command `INHIBIT_COMMON_ALLOCATION' has the same effect.
877 *Note Miscellaneous Commands::.
879 The `--no-define-common' option allows decoupling the decision to
880 assign addresses to Common symbols from the choice of the output
881 file type; otherwise a non-Relocatable output type forces
882 assigning addresses to Common symbols. Using `--no-define-common'
883 allows Common symbols that are referenced from a shared library to
884 be assigned addresses only in the main program. This eliminates
885 the unused duplicate space in the shared library, and also
886 prevents any possible confusion over resolving to the wrong
887 duplicate when there are many dynamic modules with specialized
888 search paths for runtime symbol resolution.
890 `--defsym SYMBOL=EXPRESSION'
891 Create a global symbol in the output file, containing the absolute
892 address given by EXPRESSION. You may use this option as many
893 times as necessary to define multiple symbols in the command line.
894 A limited form of arithmetic is supported for the EXPRESSION in
895 this context: you may give a hexadecimal constant or the name of
896 an existing symbol, or use `+' and `-' to add or subtract
897 hexadecimal constants or symbols. If you need more elaborate
898 expressions, consider using the linker command language from a
899 script (*note Assignment: Symbol Definitions: Assignments.).
900 _Note:_ there should be no white space between SYMBOL, the equals
901 sign ("<=>"), and EXPRESSION.
905 These options control whether to demangle symbol names in error
906 messages and other output. When the linker is told to demangle,
907 it tries to present symbol names in a readable fashion: it strips
908 leading underscores if they are used by the object file format,
909 and converts C++ mangled symbol names into user readable names.
910 Different compilers have different mangling styles. The optional
911 demangling style argument can be used to choose an appropriate
912 demangling style for your compiler. The linker will demangle by
913 default unless the environment variable `COLLECT_NO_DEMANGLE' is
914 set. These options may be used to override the default.
916 `--dynamic-linker FILE'
917 Set the name of the dynamic linker. This is only meaningful when
918 generating dynamically linked ELF executables. The default dynamic
919 linker is normally correct; don't use this unless you know what
923 Treat all warnings as errors.
926 Make sure that an output file has a .exe suffix.
928 If a successfully built fully linked output file does not have a
929 `.exe' or `.dll' suffix, this option forces the linker to copy the
930 output file to one of the same name with a `.exe' suffix. This
931 option is useful when using unmodified Unix makefiles on a
932 Microsoft Windows host, since some versions of Windows won't run
933 an image unless it ends in a `.exe' suffix.
937 Enable garbage collection of unused input sections. It is ignored
938 on targets that do not support this option. This option is not
939 compatible with `-r' or `--emit-relocs'. The default behaviour (of
940 not performing this garbage collection) can be restored by
941 specifying `--no-gc-sections' on the command line.
943 `--print-gc-sections'
944 `--no-print-gc-sections'
945 List all sections removed by garbage collection. The listing is
946 printed on stderr. This option is only effective if garbage
947 collection has been enabled via the `--gc-sections') option. The
948 default behaviour (of not listing the sections that are removed)
949 can be restored by specifying `--no-print-gc-sections' on the
953 Print a summary of the command-line options on the standard output
957 Print a summary of all target specific options on the standard
961 Print a link map to the file MAPFILE. See the description of the
965 `ld' normally optimizes for speed over memory usage by caching the
966 symbol tables of input files in memory. This option tells `ld' to
967 instead optimize for memory usage, by rereading the symbol tables
968 as necessary. This may be required if `ld' runs out of memory
969 space while linking a large executable.
973 Report unresolved symbol references from regular object files.
974 This is done even if the linker is creating a non-symbolic shared
975 library. The switch `--[no-]allow-shlib-undefined' controls the
976 behaviour for reporting unresolved references found in shared
977 libraries being linked in.
979 `--allow-multiple-definition'
981 Normally when a symbol is defined multiple times, the linker will
982 report a fatal error. These options allow multiple definitions and
983 the first definition will be used.
985 `--allow-shlib-undefined'
986 `--no-allow-shlib-undefined'
987 Allows (the default) or disallows undefined symbols in shared
988 libraries. This switch is similar to `--no-undefined' except that
989 it determines the behaviour when the undefined symbols are in a
990 shared library rather than a regular object file. It does not
991 affect how undefined symbols in regular object files are handled.
993 The reason that `--allow-shlib-undefined' is the default is that
994 the shared library being specified at link time may not be the
995 same as the one that is available at load time, so the symbols
996 might actually be resolvable at load time. Plus there are some
997 systems, (eg BeOS) where undefined symbols in shared libraries is
998 normal. (The kernel patches them at load time to select which
999 function is most appropriate for the current architecture. This
1000 is used for example to dynamically select an appropriate memset
1001 function). Apparently it is also normal for HPPA shared libraries
1002 to have undefined symbols.
1004 `--no-undefined-version'
1005 Normally when a symbol has an undefined version, the linker will
1006 ignore it. This option disallows symbols with undefined version
1007 and a fatal error will be issued instead.
1010 Create and use a default symbol version (the soname) for
1011 unversioned exported symbols.
1013 `--default-imported-symver'
1014 Create and use a default symbol version (the soname) for
1015 unversioned imported symbols.
1017 `--no-warn-mismatch'
1018 Normally `ld' will give an error if you try to link together input
1019 files that are mismatched for some reason, perhaps because they
1020 have been compiled for different processors or for different
1021 endiannesses. This option tells `ld' that it should silently
1022 permit such possible errors. This option should only be used with
1023 care, in cases when you have taken some special action that
1024 ensures that the linker errors are inappropriate.
1026 `--no-warn-search-mismatch'
1027 Normally `ld' will give a warning if it finds an incompatible
1028 library during a library search. This option silences the warning.
1030 `--no-whole-archive'
1031 Turn off the effect of the `--whole-archive' option for subsequent
1035 Retain the executable output file whenever it is still usable.
1036 Normally, the linker will not produce an output file if it
1037 encounters errors during the link process; it exits without
1038 writing an output file when it issues any error whatsoever.
1041 Only search library directories explicitly specified on the
1042 command line. Library directories specified in linker scripts
1043 (including linker scripts specified on the command line) are
1046 `--oformat OUTPUT-FORMAT'
1047 `ld' may be configured to support more than one kind of object
1048 file. If your `ld' is configured this way, you can use the
1049 `--oformat' option to specify the binary format for the output
1050 object file. Even when `ld' is configured to support alternative
1051 object formats, you don't usually need to specify this, as `ld'
1052 should be configured to produce as a default output format the most
1053 usual format on each machine. OUTPUT-FORMAT is a text string, the
1054 name of a particular format supported by the BFD libraries. (You
1055 can list the available binary formats with `objdump -i'.) The
1056 script command `OUTPUT_FORMAT' can also specify the output format,
1057 but this option overrides it. *Note BFD::.
1061 Create a position independent executable. This is currently only
1062 supported on ELF platforms. Position independent executables are
1063 similar to shared libraries in that they are relocated by the
1064 dynamic linker to the virtual address the OS chooses for them
1065 (which can vary between invocations). Like normal dynamically
1066 linked executables they can be executed and symbols defined in the
1067 executable cannot be overridden by shared libraries.
1070 This option is ignored for Linux compatibility.
1073 This option is ignored for SVR4 compatibility.
1076 An option with machine dependent effects. This option is only
1077 supported on a few targets. *Note `ld' and the H8/300: H8/300.
1078 *Note `ld' and the Intel 960 family: i960. *Note `ld' and Xtensa
1079 Processors: Xtensa. *Note `ld' and the 68HC11 and 68HC12:
1080 M68HC11/68HC12. *Note `ld' and PowerPC 32-bit ELF Support:
1083 On some platforms, the `--relax' option performs global
1084 optimizations that become possible when the linker resolves
1085 addressing in the program, such as relaxing address modes and
1086 synthesizing new instructions in the output object file.
1088 On some platforms these link time global optimizations may make
1089 symbolic debugging of the resulting executable impossible. This
1090 is known to be the case for the Matsushita MN10200 and MN10300
1091 family of processors.
1093 On platforms where this is not supported, `--relax' is accepted,
1096 `--retain-symbols-file FILENAME'
1097 Retain _only_ the symbols listed in the file FILENAME, discarding
1098 all others. FILENAME is simply a flat file, with one symbol name
1099 per line. This option is especially useful in environments (such
1100 as VxWorks) where a large global symbol table is accumulated
1101 gradually, to conserve run-time memory.
1103 `--retain-symbols-file' does _not_ discard undefined symbols, or
1104 symbols needed for relocations.
1106 You may only specify `--retain-symbols-file' once in the command
1107 line. It overrides `-s' and `-S'.
1110 Add a directory to the runtime library search path. This is used
1111 when linking an ELF executable with shared objects. All `-rpath'
1112 arguments are concatenated and passed to the runtime linker, which
1113 uses them to locate shared objects at runtime. The `-rpath'
1114 option is also used when locating shared objects which are needed
1115 by shared objects explicitly included in the link; see the
1116 description of the `-rpath-link' option. If `-rpath' is not used
1117 when linking an ELF executable, the contents of the environment
1118 variable `LD_RUN_PATH' will be used if it is defined.
1120 The `-rpath' option may also be used on SunOS. By default, on
1121 SunOS, the linker will form a runtime search patch out of all the
1122 `-L' options it is given. If a `-rpath' option is used, the
1123 runtime search path will be formed exclusively using the `-rpath'
1124 options, ignoring the `-L' options. This can be useful when using
1125 gcc, which adds many `-L' options which may be on NFS mounted file
1128 For compatibility with other ELF linkers, if the `-R' option is
1129 followed by a directory name, rather than a file name, it is
1130 treated as the `-rpath' option.
1133 When using ELF or SunOS, one shared library may require another.
1134 This happens when an `ld -shared' link includes a shared library
1135 as one of the input files.
1137 When the linker encounters such a dependency when doing a
1138 non-shared, non-relocatable link, it will automatically try to
1139 locate the required shared library and include it in the link, if
1140 it is not included explicitly. In such a case, the `-rpath-link'
1141 option specifies the first set of directories to search. The
1142 `-rpath-link' option may specify a sequence of directory names
1143 either by specifying a list of names separated by colons, or by
1144 appearing multiple times.
1146 This option should be used with caution as it overrides the search
1147 path that may have been hard compiled into a shared library. In
1148 such a case it is possible to use unintentionally a different
1149 search path than the runtime linker would do.
1151 The linker uses the following search paths to locate required
1153 1. Any directories specified by `-rpath-link' options.
1155 2. Any directories specified by `-rpath' options. The difference
1156 between `-rpath' and `-rpath-link' is that directories
1157 specified by `-rpath' options are included in the executable
1158 and used at runtime, whereas the `-rpath-link' option is only
1159 effective at link time. Searching `-rpath' in this way is
1160 only supported by native linkers and cross linkers which have
1161 been configured with the `--with-sysroot' option.
1163 3. On an ELF system, if the `-rpath' and `rpath-link' options
1164 were not used, search the contents of the environment variable
1165 `LD_RUN_PATH'. It is for the native linker only.
1167 4. On SunOS, if the `-rpath' option was not used, search any
1168 directories specified using `-L' options.
1170 5. For a native linker, the contents of the environment variable
1173 6. For a native ELF linker, the directories in `DT_RUNPATH' or
1174 `DT_RPATH' of a shared library are searched for shared
1175 libraries needed by it. The `DT_RPATH' entries are ignored if
1176 `DT_RUNPATH' entries exist.
1178 7. The default directories, normally `/lib' and `/usr/lib'.
1180 8. For a native linker on an ELF system, if the file
1181 `/etc/ld.so.conf' exists, the list of directories found in
1184 If the required shared library is not found, the linker will issue
1185 a warning and continue with the link.
1189 Create a shared library. This is currently only supported on ELF,
1190 XCOFF and SunOS platforms. On SunOS, the linker will
1191 automatically create a shared library if the `-e' option is not
1192 used and there are undefined symbols in the link.
1195 This option tells `ld' to sort the common symbols by size when it
1196 places them in the appropriate output sections. First come all
1197 the one byte symbols, then all the two byte, then all the four
1198 byte, and then everything else. This is to prevent gaps between
1199 symbols due to alignment constraints.
1201 `--sort-section name'
1202 This option will apply `SORT_BY_NAME' to all wildcard section
1203 patterns in the linker script.
1205 `--sort-section alignment'
1206 This option will apply `SORT_BY_ALIGNMENT' to all wildcard section
1207 patterns in the linker script.
1209 `--split-by-file [SIZE]'
1210 Similar to `--split-by-reloc' but creates a new output section for
1211 each input file when SIZE is reached. SIZE defaults to a size of
1214 `--split-by-reloc [COUNT]'
1215 Tries to creates extra sections in the output file so that no
1216 single output section in the file contains more than COUNT
1217 relocations. This is useful when generating huge relocatable
1218 files for downloading into certain real time kernels with the COFF
1219 object file format; since COFF cannot represent more than 65535
1220 relocations in a single section. Note that this will fail to work
1221 with object file formats which do not support arbitrary sections.
1222 The linker will not split up individual input sections for
1223 redistribution, so if a single input section contains more than
1224 COUNT relocations one output section will contain that many
1225 relocations. COUNT defaults to a value of 32768.
1228 Compute and display statistics about the operation of the linker,
1229 such as execution time and memory usage.
1231 `--sysroot=DIRECTORY'
1232 Use DIRECTORY as the location of the sysroot, overriding the
1233 configure-time default. This option is only supported by linkers
1234 that were configured using `--with-sysroot'.
1236 `--traditional-format'
1237 For some targets, the output of `ld' is different in some ways from
1238 the output of some existing linker. This switch requests `ld' to
1239 use the traditional format instead.
1241 For example, on SunOS, `ld' combines duplicate entries in the
1242 symbol string table. This can reduce the size of an output file
1243 with full debugging information by over 30 percent.
1244 Unfortunately, the SunOS `dbx' program can not read the resulting
1245 program (`gdb' has no trouble). The `--traditional-format' switch
1246 tells `ld' to not combine duplicate entries.
1248 `--section-start SECTIONNAME=ORG'
1249 Locate a section in the output file at the absolute address given
1250 by ORG. You may use this option as many times as necessary to
1251 locate multiple sections in the command line. ORG must be a
1252 single hexadecimal integer; for compatibility with other linkers,
1253 you may omit the leading `0x' usually associated with hexadecimal
1254 values. _Note:_ there should be no white space between
1255 SECTIONNAME, the equals sign ("<=>"), and ORG.
1260 Same as -section-start, with `.bss', `.data' or `.text' as the
1263 `--unresolved-symbols=METHOD'
1264 Determine how to handle unresolved symbols. There are four
1265 possible values for `method':
1268 Do not report any unresolved symbols.
1271 Report all unresolved symbols. This is the default.
1273 `ignore-in-object-files'
1274 Report unresolved symbols that are contained in shared
1275 libraries, but ignore them if they come from regular object
1278 `ignore-in-shared-libs'
1279 Report unresolved symbols that come from regular object
1280 files, but ignore them if they come from shared libraries.
1281 This can be useful when creating a dynamic binary and it is
1282 known that all the shared libraries that it should be
1283 referencing are included on the linker's command line.
1285 The behaviour for shared libraries on their own can also be
1286 controlled by the `--[no-]allow-shlib-undefined' option.
1288 Normally the linker will generate an error message for each
1289 reported unresolved symbol but the option
1290 `--warn-unresolved-symbols' can change this to a warning.
1294 Display the version number for `ld' and list the linker emulations
1295 supported. Display which input files can and cannot be opened.
1296 Display the linker script being used by the linker.
1298 `--version-script=VERSION-SCRIPTFILE'
1299 Specify the name of a version script to the linker. This is
1300 typically used when creating shared libraries to specify
1301 additional information about the version hierarchy for the library
1302 being created. This option is only meaningful on ELF platforms
1303 which support shared libraries. *Note VERSION::.
1306 Warn when a common symbol is combined with another common symbol
1307 or with a symbol definition. Unix linkers allow this somewhat
1308 sloppy practise, but linkers on some other operating systems do
1309 not. This option allows you to find potential problems from
1310 combining global symbols. Unfortunately, some C libraries use
1311 this practise, so you may get some warnings about symbols in the
1312 libraries as well as in your programs.
1314 There are three kinds of global symbols, illustrated here by C
1318 A definition, which goes in the initialized data section of
1322 An undefined reference, which does not allocate space. There
1323 must be either a definition or a common symbol for the
1327 A common symbol. If there are only (one or more) common
1328 symbols for a variable, it goes in the uninitialized data
1329 area of the output file. The linker merges multiple common
1330 symbols for the same variable into a single symbol. If they
1331 are of different sizes, it picks the largest size. The
1332 linker turns a common symbol into a declaration, if there is
1333 a definition of the same variable.
1335 The `--warn-common' option can produce five kinds of warnings.
1336 Each warning consists of a pair of lines: the first describes the
1337 symbol just encountered, and the second describes the previous
1338 symbol encountered with the same name. One or both of the two
1339 symbols will be a common symbol.
1341 1. Turning a common symbol into a reference, because there is
1342 already a definition for the symbol.
1343 FILE(SECTION): warning: common of `SYMBOL'
1344 overridden by definition
1345 FILE(SECTION): warning: defined here
1347 2. Turning a common symbol into a reference, because a later
1348 definition for the symbol is encountered. This is the same
1349 as the previous case, except that the symbols are encountered
1350 in a different order.
1351 FILE(SECTION): warning: definition of `SYMBOL'
1353 FILE(SECTION): warning: common is here
1355 3. Merging a common symbol with a previous same-sized common
1357 FILE(SECTION): warning: multiple common
1359 FILE(SECTION): warning: previous common is here
1361 4. Merging a common symbol with a previous larger common symbol.
1362 FILE(SECTION): warning: common of `SYMBOL'
1363 overridden by larger common
1364 FILE(SECTION): warning: larger common is here
1366 5. Merging a common symbol with a previous smaller common
1367 symbol. This is the same as the previous case, except that
1368 the symbols are encountered in a different order.
1369 FILE(SECTION): warning: common of `SYMBOL'
1370 overriding smaller common
1371 FILE(SECTION): warning: smaller common is here
1373 `--warn-constructors'
1374 Warn if any global constructors are used. This is only useful for
1375 a few object file formats. For formats like COFF or ELF, the
1376 linker can not detect the use of global constructors.
1378 `--warn-multiple-gp'
1379 Warn if multiple global pointer values are required in the output
1380 file. This is only meaningful for certain processors, such as the
1381 Alpha. Specifically, some processors put large-valued constants
1382 in a special section. A special register (the global pointer)
1383 points into the middle of this section, so that constants can be
1384 loaded efficiently via a base-register relative addressing mode.
1385 Since the offset in base-register relative mode is fixed and
1386 relatively small (e.g., 16 bits), this limits the maximum size of
1387 the constant pool. Thus, in large programs, it is often necessary
1388 to use multiple global pointer values in order to be able to
1389 address all possible constants. This option causes a warning to
1390 be issued whenever this case occurs.
1393 Only warn once for each undefined symbol, rather than once per
1394 module which refers to it.
1396 `--warn-section-align'
1397 Warn if the address of an output section is changed because of
1398 alignment. Typically, the alignment will be set by an input
1399 section. The address will only be changed if it not explicitly
1400 specified; that is, if the `SECTIONS' command does not specify a
1401 start address for the section (*note SECTIONS::).
1403 `--warn-shared-textrel'
1404 Warn if the linker adds a DT_TEXTREL to a shared object.
1406 `--warn-unresolved-symbols'
1407 If the linker is going to report an unresolved symbol (see the
1408 option `--unresolved-symbols') it will normally generate an error.
1409 This option makes it generate a warning instead.
1411 `--error-unresolved-symbols'
1412 This restores the linker's default behaviour of generating errors
1413 when it is reporting unresolved symbols.
1416 For each archive mentioned on the command line after the
1417 `--whole-archive' option, include every object file in the archive
1418 in the link, rather than searching the archive for the required
1419 object files. This is normally used to turn an archive file into
1420 a shared library, forcing every object to be included in the
1421 resulting shared library. This option may be used more than once.
1423 Two notes when using this option from gcc: First, gcc doesn't know
1424 about this option, so you have to use `-Wl,-whole-archive'.
1425 Second, don't forget to use `-Wl,-no-whole-archive' after your
1426 list of archives, because gcc will add its own list of archives to
1427 your link and you may not want this flag to affect those as well.
1430 Use a wrapper function for SYMBOL. Any undefined reference to
1431 SYMBOL will be resolved to `__wrap_SYMBOL'. Any undefined
1432 reference to `__real_SYMBOL' will be resolved to SYMBOL.
1434 This can be used to provide a wrapper for a system function. The
1435 wrapper function should be called `__wrap_SYMBOL'. If it wishes
1436 to call the system function, it should call `__real_SYMBOL'.
1438 Here is a trivial example:
1441 __wrap_malloc (size_t c)
1443 printf ("malloc called with %zu\n", c);
1444 return __real_malloc (c);
1447 If you link other code with this file using `--wrap malloc', then
1448 all calls to `malloc' will call the function `__wrap_malloc'
1449 instead. The call to `__real_malloc' in `__wrap_malloc' will call
1450 the real `malloc' function.
1452 You may wish to provide a `__real_malloc' function as well, so that
1453 links without the `--wrap' option will succeed. If you do this,
1454 you should not put the definition of `__real_malloc' in the same
1455 file as `__wrap_malloc'; if you do, the assembler may resolve the
1456 call before the linker has a chance to wrap it to `malloc'.
1459 Request creation of `.eh_frame_hdr' section and ELF
1460 `PT_GNU_EH_FRAME' segment header.
1462 `--enable-new-dtags'
1463 `--disable-new-dtags'
1464 This linker can create the new dynamic tags in ELF. But the older
1465 ELF systems may not understand them. If you specify
1466 `--enable-new-dtags', the dynamic tags will be created as needed.
1467 If you specify `--disable-new-dtags', no new dynamic tags will be
1468 created. By default, the new dynamic tags are not created. Note
1469 that those options are only available for ELF systems.
1471 `--hash-size=NUMBER'
1472 Set the default size of the linker's hash tables to a prime number
1473 close to NUMBER. Increasing this value can reduce the length of
1474 time it takes the linker to perform its tasks, at the expense of
1475 increasing the linker's memory requirements. Similarly reducing
1476 this value can reduce the memory requirements at the expense of
1479 `--hash-style=STYLE'
1480 Set the type of linker's hash table(s). STYLE can be either
1481 `sysv' for classic ELF `.hash' section, `gnu' for new style GNU
1482 `.gnu.hash' section or `both' for both the classic ELF `.hash' and
1483 new style GNU `.gnu.hash' hash tables. The default is `sysv'.
1485 `--reduce-memory-overheads'
1486 This option reduces memory requirements at ld runtime, at the
1487 expense of linking speed. This was introduced to select the old
1488 O(n^2) algorithm for link map file generation, rather than the new
1489 O(n) algorithm which uses about 40% more memory for symbol storage.
1491 Another effect of the switch is to set the default hash table size
1492 to 1021, which again saves memory at the cost of lengthening the
1493 linker's run time. This is not done however if the `--hash-size'
1494 switch has been used.
1496 The `--reduce-memory-overheads' switch may be also be used to
1497 enable other tradeoffs in future versions of the linker.
1501 Request creation of `.note.gnu.build-id' ELF note section. The
1502 contents of the note are unique bits identifying this linked file.
1503 STYLE can be `uuid' to use 128 random bits, `sha1' to use a
1504 160-bit SHA1 hash on the normative parts of the output contents,
1505 `md5' to use a 128-bit MD5 hash on the normative parts of the
1506 output contents, or `0xHEXSTRING' to use a chosen bit string
1507 specified as an even number of hexadecimal digits (`-' and `:'
1508 characters between digit pairs are ignored). If STYLE is omitted,
1511 The `md5' and `sha1' styles produces an identifier that is always
1512 the same in an identical output file, but will be unique among all
1513 nonidentical output files. It is not intended to be compared as a
1514 checksum for the file's contents. A linked file may be changed
1515 later by other tools, but the build ID bit string identifying the
1516 original linked file does not change.
1518 Passing `none' for STYLE disables the setting from any
1519 `--build-id' options earlier on the command line.
1521 2.1.1 Options Specific to i386 PE Targets
1522 -----------------------------------------
1524 The i386 PE linker supports the `-shared' option, which causes the
1525 output to be a dynamically linked library (DLL) instead of a normal
1526 executable. You should name the output `*.dll' when you use this
1527 option. In addition, the linker fully supports the standard `*.def'
1528 files, which may be specified on the linker command line like an object
1529 file (in fact, it should precede archives it exports symbols from, to
1530 ensure that they get linked in, just like a normal object file).
1532 In addition to the options common to all targets, the i386 PE linker
1533 support additional command line options that are specific to the i386
1534 PE target. Options that take values may be separated from their values
1535 by either a space or an equals sign.
1537 `--add-stdcall-alias'
1538 If given, symbols with a stdcall suffix (@NN) will be exported
1539 as-is and also with the suffix stripped. [This option is specific
1540 to the i386 PE targeted port of the linker]
1543 Use FILE as the name of a file in which to save the base addresses
1544 of all the relocations needed for generating DLLs with `dlltool'.
1545 [This is an i386 PE specific option]
1548 Create a DLL instead of a regular executable. You may also use
1549 `-shared' or specify a `LIBRARY' in a given `.def' file. [This
1550 option is specific to the i386 PE targeted port of the linker]
1552 `--enable-stdcall-fixup'
1553 `--disable-stdcall-fixup'
1554 If the link finds a symbol that it cannot resolve, it will attempt
1555 to do "fuzzy linking" by looking for another defined symbol that
1556 differs only in the format of the symbol name (cdecl vs stdcall)
1557 and will resolve that symbol by linking to the match. For
1558 example, the undefined symbol `_foo' might be linked to the
1559 function `_foo@12', or the undefined symbol `_bar@16' might be
1560 linked to the function `_bar'. When the linker does this, it
1561 prints a warning, since it normally should have failed to link,
1562 but sometimes import libraries generated from third-party dlls may
1563 need this feature to be usable. If you specify
1564 `--enable-stdcall-fixup', this feature is fully enabled and
1565 warnings are not printed. If you specify
1566 `--disable-stdcall-fixup', this feature is disabled and such
1567 mismatches are considered to be errors. [This option is specific
1568 to the i386 PE targeted port of the linker]
1570 `--export-all-symbols'
1571 If given, all global symbols in the objects used to build a DLL
1572 will be exported by the DLL. Note that this is the default if
1573 there otherwise wouldn't be any exported symbols. When symbols are
1574 explicitly exported via DEF files or implicitly exported via
1575 function attributes, the default is to not export anything else
1576 unless this option is given. Note that the symbols `DllMain@12',
1577 `DllEntryPoint@0', `DllMainCRTStartup@12', and `impure_ptr' will
1578 not be automatically exported. Also, symbols imported from other
1579 DLLs will not be re-exported, nor will symbols specifying the
1580 DLL's internal layout such as those beginning with `_head_' or
1581 ending with `_iname'. In addition, no symbols from `libgcc',
1582 `libstd++', `libmingw32', or `crtX.o' will be exported. Symbols
1583 whose names begin with `__rtti_' or `__builtin_' will not be
1584 exported, to help with C++ DLLs. Finally, there is an extensive
1585 list of cygwin-private symbols that are not exported (obviously,
1586 this applies on when building DLLs for cygwin targets). These
1587 cygwin-excludes are: `_cygwin_dll_entry@12',
1588 `_cygwin_crt0_common@8', `_cygwin_noncygwin_dll_entry@12',
1589 `_fmode', `_impure_ptr', `cygwin_attach_dll', `cygwin_premain0',
1590 `cygwin_premain1', `cygwin_premain2', `cygwin_premain3', and
1591 `environ'. [This option is specific to the i386 PE targeted port
1594 `--exclude-symbols SYMBOL,SYMBOL,...'
1595 Specifies a list of symbols which should not be automatically
1596 exported. The symbol names may be delimited by commas or colons.
1597 [This option is specific to the i386 PE targeted port of the
1601 Specify the file alignment. Sections in the file will always
1602 begin at file offsets which are multiples of this number. This
1603 defaults to 512. [This option is specific to the i386 PE targeted
1607 `--heap RESERVE,COMMIT'
1608 Specify the number of bytes of memory to reserve (and optionally
1609 commit) to be used as heap for this program. The default is 1Mb
1610 reserved, 4K committed. [This option is specific to the i386 PE
1611 targeted port of the linker]
1613 `--image-base VALUE'
1614 Use VALUE as the base address of your program or dll. This is the
1615 lowest memory location that will be used when your program or dll
1616 is loaded. To reduce the need to relocate and improve performance
1617 of your dlls, each should have a unique base address and not
1618 overlap any other dlls. The default is 0x400000 for executables,
1619 and 0x10000000 for dlls. [This option is specific to the i386 PE
1620 targeted port of the linker]
1623 If given, the stdcall suffixes (@NN) will be stripped from symbols
1624 before they are exported. [This option is specific to the i386 PE
1625 targeted port of the linker]
1627 `--large-address-aware'
1628 If given, the appropriate bit in the "Characteristics" field of
1629 the COFF header is set to indicate that this executable supports
1630 virtual addresses greater than 2 gigabytes. This should be used
1631 in conjunction with the /3GB or /USERVA=VALUE megabytes switch in
1632 the "[operating systems]" section of the BOOT.INI. Otherwise,
1633 this bit has no effect. [This option is specific to PE targeted
1634 ports of the linker]
1636 `--major-image-version VALUE'
1637 Sets the major number of the "image version". Defaults to 1.
1638 [This option is specific to the i386 PE targeted port of the
1641 `--major-os-version VALUE'
1642 Sets the major number of the "os version". Defaults to 4. [This
1643 option is specific to the i386 PE targeted port of the linker]
1645 `--major-subsystem-version VALUE'
1646 Sets the major number of the "subsystem version". Defaults to 4.
1647 [This option is specific to the i386 PE targeted port of the
1650 `--minor-image-version VALUE'
1651 Sets the minor number of the "image version". Defaults to 0.
1652 [This option is specific to the i386 PE targeted port of the
1655 `--minor-os-version VALUE'
1656 Sets the minor number of the "os version". Defaults to 0. [This
1657 option is specific to the i386 PE targeted port of the linker]
1659 `--minor-subsystem-version VALUE'
1660 Sets the minor number of the "subsystem version". Defaults to 0.
1661 [This option is specific to the i386 PE targeted port of the
1665 The linker will create the file FILE which will contain a DEF file
1666 corresponding to the DLL the linker is generating. This DEF file
1667 (which should be called `*.def') may be used to create an import
1668 library with `dlltool' or may be used as a reference to
1669 automatically or implicitly exported symbols. [This option is
1670 specific to the i386 PE targeted port of the linker]
1673 The linker will create the file FILE which will contain an import
1674 lib corresponding to the DLL the linker is generating. This import
1675 lib (which should be called `*.dll.a' or `*.a' may be used to link
1676 clients against the generated DLL; this behaviour makes it
1677 possible to skip a separate `dlltool' import library creation step.
1678 [This option is specific to the i386 PE targeted port of the
1681 `--enable-auto-image-base'
1682 Automatically choose the image base for DLLs, unless one is
1683 specified using the `--image-base' argument. By using a hash
1684 generated from the dllname to create unique image bases for each
1685 DLL, in-memory collisions and relocations which can delay program
1686 execution are avoided. [This option is specific to the i386 PE
1687 targeted port of the linker]
1689 `--disable-auto-image-base'
1690 Do not automatically generate a unique image base. If there is no
1691 user-specified image base (`--image-base') then use the platform
1692 default. [This option is specific to the i386 PE targeted port of
1695 `--dll-search-prefix STRING'
1696 When linking dynamically to a dll without an import library,
1697 search for `<string><basename>.dll' in preference to
1698 `lib<basename>.dll'. This behaviour allows easy distinction
1699 between DLLs built for the various "subplatforms": native, cygwin,
1700 uwin, pw, etc. For instance, cygwin DLLs typically use
1701 `--dll-search-prefix=cyg'. [This option is specific to the i386
1702 PE targeted port of the linker]
1704 `--enable-auto-import'
1705 Do sophisticated linking of `_symbol' to `__imp__symbol' for DATA
1706 imports from DLLs, and create the necessary thunking symbols when
1707 building the import libraries with those DATA exports. Note: Use
1708 of the 'auto-import' extension will cause the text section of the
1709 image file to be made writable. This does not conform to the
1710 PE-COFF format specification published by Microsoft.
1712 Using 'auto-import' generally will 'just work' - but sometimes you
1713 may see this message:
1715 "variable '<var>' can't be auto-imported. Please read the
1716 documentation for ld's `--enable-auto-import' for details."
1718 This message occurs when some (sub)expression accesses an address
1719 ultimately given by the sum of two constants (Win32 import tables
1720 only allow one). Instances where this may occur include accesses
1721 to member fields of struct variables imported from a DLL, as well
1722 as using a constant index into an array variable imported from a
1723 DLL. Any multiword variable (arrays, structs, long long, etc) may
1724 trigger this error condition. However, regardless of the exact
1725 data type of the offending exported variable, ld will always
1726 detect it, issue the warning, and exit.
1728 There are several ways to address this difficulty, regardless of
1729 the data type of the exported variable:
1731 One way is to use -enable-runtime-pseudo-reloc switch. This leaves
1732 the task of adjusting references in your client code for runtime
1733 environment, so this method works only when runtime environment
1734 supports this feature.
1736 A second solution is to force one of the 'constants' to be a
1737 variable - that is, unknown and un-optimizable at compile time.
1738 For arrays, there are two possibilities: a) make the indexee (the
1739 array's address) a variable, or b) make the 'constant' index a
1742 extern type extern_array[];
1744 { volatile type *t=extern_array; t[1] }
1748 extern type extern_array[];
1750 { volatile int t=1; extern_array[t] }
1752 For structs (and most other multiword data types) the only option
1753 is to make the struct itself (or the long long, or the ...)
1756 extern struct s extern_struct;
1757 extern_struct.field -->
1758 { volatile struct s *t=&extern_struct; t->field }
1762 extern long long extern_ll;
1764 { volatile long long * local_ll=&extern_ll; *local_ll }
1766 A third method of dealing with this difficulty is to abandon
1767 'auto-import' for the offending symbol and mark it with
1768 `__declspec(dllimport)'. However, in practise that requires using
1769 compile-time #defines to indicate whether you are building a DLL,
1770 building client code that will link to the DLL, or merely
1771 building/linking to a static library. In making the choice
1772 between the various methods of resolving the 'direct address with
1773 constant offset' problem, you should consider typical real-world
1781 void main(int argc, char **argv){
1782 printf("%d\n",arr[1]);
1790 void main(int argc, char **argv){
1791 /* This workaround is for win32 and cygwin; do not "optimize" */
1792 volatile int *parr = arr;
1793 printf("%d\n",parr[1]);
1798 /* Note: auto-export is assumed (no __declspec(dllexport)) */
1799 #if (defined(_WIN32) || defined(__CYGWIN__)) && \
1800 !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
1801 #define FOO_IMPORT __declspec(dllimport)
1805 extern FOO_IMPORT int arr[];
1808 void main(int argc, char **argv){
1809 printf("%d\n",arr[1]);
1812 A fourth way to avoid this problem is to re-code your library to
1813 use a functional interface rather than a data interface for the
1814 offending variables (e.g. set_foo() and get_foo() accessor
1815 functions). [This option is specific to the i386 PE targeted port
1818 `--disable-auto-import'
1819 Do not attempt to do sophisticated linking of `_symbol' to
1820 `__imp__symbol' for DATA imports from DLLs. [This option is
1821 specific to the i386 PE targeted port of the linker]
1823 `--enable-runtime-pseudo-reloc'
1824 If your code contains expressions described in -enable-auto-import
1825 section, that is, DATA imports from DLL with non-zero offset, this
1826 switch will create a vector of 'runtime pseudo relocations' which
1827 can be used by runtime environment to adjust references to such
1828 data in your client code. [This option is specific to the i386 PE
1829 targeted port of the linker]
1831 `--disable-runtime-pseudo-reloc'
1832 Do not create pseudo relocations for non-zero offset DATA imports
1833 from DLLs. This is the default. [This option is specific to the
1834 i386 PE targeted port of the linker]
1836 `--enable-extra-pe-debug'
1837 Show additional debug info related to auto-import symbol thunking.
1838 [This option is specific to the i386 PE targeted port of the
1841 `--section-alignment'
1842 Sets the section alignment. Sections in memory will always begin
1843 at addresses which are a multiple of this number. Defaults to
1844 0x1000. [This option is specific to the i386 PE targeted port of
1848 `--stack RESERVE,COMMIT'
1849 Specify the number of bytes of memory to reserve (and optionally
1850 commit) to be used as stack for this program. The default is 2Mb
1851 reserved, 4K committed. [This option is specific to the i386 PE
1852 targeted port of the linker]
1855 `--subsystem WHICH:MAJOR'
1856 `--subsystem WHICH:MAJOR.MINOR'
1857 Specifies the subsystem under which your program will execute. The
1858 legal values for WHICH are `native', `windows', `console',
1859 `posix', and `xbox'. You may optionally set the subsystem version
1860 also. Numeric values are also accepted for WHICH. [This option
1861 is specific to the i386 PE targeted port of the linker]
1864 2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets
1865 ------------------------------------------------------------
1867 The 68HC11 and 68HC12 linkers support specific options to control the
1868 memory bank switching mapping and trampoline code generation.
1871 This option disables the generation of trampoline. By default a
1872 trampoline is generated for each far function which is called
1873 using a `jsr' instruction (this happens when a pointer to a far
1876 `--bank-window NAME'
1877 This option indicates to the linker the name of the memory region
1878 in the `MEMORY' specification that describes the memory bank
1879 window. The definition of such region is then used by the linker
1880 to compute paging and addresses within the memory window.
1884 File: ld.info, Node: Environment, Prev: Options, Up: Invocation
1886 2.2 Environment Variables
1887 =========================
1889 You can change the behaviour of `ld' with the environment variables
1890 `GNUTARGET', `LDEMULATION' and `COLLECT_NO_DEMANGLE'.
1892 `GNUTARGET' determines the input-file object format if you don't use
1893 `-b' (or its synonym `--format'). Its value should be one of the BFD
1894 names for an input format (*note BFD::). If there is no `GNUTARGET' in
1895 the environment, `ld' uses the natural format of the target. If
1896 `GNUTARGET' is set to `default' then BFD attempts to discover the input
1897 format by examining binary input files; this method often succeeds, but
1898 there are potential ambiguities, since there is no method of ensuring
1899 that the magic number used to specify object-file formats is unique.
1900 However, the configuration procedure for BFD on each system places the
1901 conventional format for that system first in the search-list, so
1902 ambiguities are resolved in favor of convention.
1904 `LDEMULATION' determines the default emulation if you don't use the
1905 `-m' option. The emulation can affect various aspects of linker
1906 behaviour, particularly the default linker script. You can list the
1907 available emulations with the `--verbose' or `-V' options. If the `-m'
1908 option is not used, and the `LDEMULATION' environment variable is not
1909 defined, the default emulation depends upon how the linker was
1912 Normally, the linker will default to demangling symbols. However, if
1913 `COLLECT_NO_DEMANGLE' is set in the environment, then it will default
1914 to not demangling symbols. This environment variable is used in a
1915 similar fashion by the `gcc' linker wrapper program. The default may
1916 be overridden by the `--demangle' and `--no-demangle' options.
1919 File: ld.info, Node: Scripts, Next: Machine Dependent, Prev: Invocation, Up: Top
1924 Every link is controlled by a "linker script". This script is written
1925 in the linker command language.
1927 The main purpose of the linker script is to describe how the
1928 sections in the input files should be mapped into the output file, and
1929 to control the memory layout of the output file. Most linker scripts
1930 do nothing more than this. However, when necessary, the linker script
1931 can also direct the linker to perform many other operations, using the
1932 commands described below.
1934 The linker always uses a linker script. If you do not supply one
1935 yourself, the linker will use a default script that is compiled into the
1936 linker executable. You can use the `--verbose' command line option to
1937 display the default linker script. Certain command line options, such
1938 as `-r' or `-N', will affect the default linker script.
1940 You may supply your own linker script by using the `-T' command line
1941 option. When you do this, your linker script will replace the default
1944 You may also use linker scripts implicitly by naming them as input
1945 files to the linker, as though they were files to be linked. *Note
1946 Implicit Linker Scripts::.
1950 * Basic Script Concepts:: Basic Linker Script Concepts
1951 * Script Format:: Linker Script Format
1952 * Simple Example:: Simple Linker Script Example
1953 * Simple Commands:: Simple Linker Script Commands
1954 * Assignments:: Assigning Values to Symbols
1955 * SECTIONS:: SECTIONS Command
1956 * MEMORY:: MEMORY Command
1957 * PHDRS:: PHDRS Command
1958 * VERSION:: VERSION Command
1959 * Expressions:: Expressions in Linker Scripts
1960 * Implicit Linker Scripts:: Implicit Linker Scripts
1963 File: ld.info, Node: Basic Script Concepts, Next: Script Format, Up: Scripts
1965 3.1 Basic Linker Script Concepts
1966 ================================
1968 We need to define some basic concepts and vocabulary in order to
1969 describe the linker script language.
1971 The linker combines input files into a single output file. The
1972 output file and each input file are in a special data format known as an
1973 "object file format". Each file is called an "object file". The
1974 output file is often called an "executable", but for our purposes we
1975 will also call it an object file. Each object file has, among other
1976 things, a list of "sections". We sometimes refer to a section in an
1977 input file as an "input section"; similarly, a section in the output
1978 file is an "output section".
1980 Each section in an object file has a name and a size. Most sections
1981 also have an associated block of data, known as the "section contents".
1982 A section may be marked as "loadable", which mean that the contents
1983 should be loaded into memory when the output file is run. A section
1984 with no contents may be "allocatable", which means that an area in
1985 memory should be set aside, but nothing in particular should be loaded
1986 there (in some cases this memory must be zeroed out). A section which
1987 is neither loadable nor allocatable typically contains some sort of
1988 debugging information.
1990 Every loadable or allocatable output section has two addresses. The
1991 first is the "VMA", or virtual memory address. This is the address the
1992 section will have when the output file is run. The second is the
1993 "LMA", or load memory address. This is the address at which the
1994 section will be loaded. In most cases the two addresses will be the
1995 same. An example of when they might be different is when a data section
1996 is loaded into ROM, and then copied into RAM when the program starts up
1997 (this technique is often used to initialize global variables in a ROM
1998 based system). In this case the ROM address would be the LMA, and the
1999 RAM address would be the VMA.
2001 You can see the sections in an object file by using the `objdump'
2002 program with the `-h' option.
2004 Every object file also has a list of "symbols", known as the "symbol
2005 table". A symbol may be defined or undefined. Each symbol has a name,
2006 and each defined symbol has an address, among other information. If
2007 you compile a C or C++ program into an object file, you will get a
2008 defined symbol for every defined function and global or static
2009 variable. Every undefined function or global variable which is
2010 referenced in the input file will become an undefined symbol.
2012 You can see the symbols in an object file by using the `nm' program,
2013 or by using the `objdump' program with the `-t' option.
2016 File: ld.info, Node: Script Format, Next: Simple Example, Prev: Basic Script Concepts, Up: Scripts
2018 3.2 Linker Script Format
2019 ========================
2021 Linker scripts are text files.
2023 You write a linker script as a series of commands. Each command is
2024 either a keyword, possibly followed by arguments, or an assignment to a
2025 symbol. You may separate commands using semicolons. Whitespace is
2028 Strings such as file or format names can normally be entered
2029 directly. If the file name contains a character such as a comma which
2030 would otherwise serve to separate file names, you may put the file name
2031 in double quotes. There is no way to use a double quote character in a
2034 You may include comments in linker scripts just as in C, delimited by
2035 `/*' and `*/'. As in C, comments are syntactically equivalent to
2039 File: ld.info, Node: Simple Example, Next: Simple Commands, Prev: Script Format, Up: Scripts
2041 3.3 Simple Linker Script Example
2042 ================================
2044 Many linker scripts are fairly simple.
2046 The simplest possible linker script has just one command:
2047 `SECTIONS'. You use the `SECTIONS' command to describe the memory
2048 layout of the output file.
2050 The `SECTIONS' command is a powerful command. Here we will describe
2051 a simple use of it. Let's assume your program consists only of code,
2052 initialized data, and uninitialized data. These will be in the
2053 `.text', `.data', and `.bss' sections, respectively. Let's assume
2054 further that these are the only sections which appear in your input
2057 For this example, let's say that the code should be loaded at address
2058 0x10000, and that the data should start at address 0x8000000. Here is a
2059 linker script which will do that:
2063 .text : { *(.text) }
2065 .data : { *(.data) }
2069 You write the `SECTIONS' command as the keyword `SECTIONS', followed
2070 by a series of symbol assignments and output section descriptions
2071 enclosed in curly braces.
2073 The first line inside the `SECTIONS' command of the above example
2074 sets the value of the special symbol `.', which is the location
2075 counter. If you do not specify the address of an output section in some
2076 other way (other ways are described later), the address is set from the
2077 current value of the location counter. The location counter is then
2078 incremented by the size of the output section. At the start of the
2079 `SECTIONS' command, the location counter has the value `0'.
2081 The second line defines an output section, `.text'. The colon is
2082 required syntax which may be ignored for now. Within the curly braces
2083 after the output section name, you list the names of the input sections
2084 which should be placed into this output section. The `*' is a wildcard
2085 which matches any file name. The expression `*(.text)' means all
2086 `.text' input sections in all input files.
2088 Since the location counter is `0x10000' when the output section
2089 `.text' is defined, the linker will set the address of the `.text'
2090 section in the output file to be `0x10000'.
2092 The remaining lines define the `.data' and `.bss' sections in the
2093 output file. The linker will place the `.data' output section at
2094 address `0x8000000'. After the linker places the `.data' output
2095 section, the value of the location counter will be `0x8000000' plus the
2096 size of the `.data' output section. The effect is that the linker will
2097 place the `.bss' output section immediately after the `.data' output
2100 The linker will ensure that each output section has the required
2101 alignment, by increasing the location counter if necessary. In this
2102 example, the specified addresses for the `.text' and `.data' sections
2103 will probably satisfy any alignment constraints, but the linker may
2104 have to create a small gap between the `.data' and `.bss' sections.
2106 That's it! That's a simple and complete linker script.
2109 File: ld.info, Node: Simple Commands, Next: Assignments, Prev: Simple Example, Up: Scripts
2111 3.4 Simple Linker Script Commands
2112 =================================
2114 In this section we describe the simple linker script commands.
2118 * Entry Point:: Setting the entry point
2119 * File Commands:: Commands dealing with files
2121 * Format Commands:: Commands dealing with object file formats
2123 * Miscellaneous Commands:: Other linker script commands
2126 File: ld.info, Node: Entry Point, Next: File Commands, Up: Simple Commands
2128 3.4.1 Setting the Entry Point
2129 -----------------------------
2131 The first instruction to execute in a program is called the "entry
2132 point". You can use the `ENTRY' linker script command to set the entry
2133 point. The argument is a symbol name:
2136 There are several ways to set the entry point. The linker will set
2137 the entry point by trying each of the following methods in order, and
2138 stopping when one of them succeeds:
2139 * the `-e' ENTRY command-line option;
2141 * the `ENTRY(SYMBOL)' command in a linker script;
2143 * the value of the symbol `start', if defined;
2145 * the address of the first byte of the `.text' section, if present;
2150 File: ld.info, Node: File Commands, Next: Format Commands, Prev: Entry Point, Up: Simple Commands
2152 3.4.2 Commands Dealing with Files
2153 ---------------------------------
2155 Several linker script commands deal with files.
2158 Include the linker script FILENAME at this point. The file will
2159 be searched for in the current directory, and in any directory
2160 specified with the `-L' option. You can nest calls to `INCLUDE'
2161 up to 10 levels deep.
2163 `INPUT(FILE, FILE, ...)'
2164 `INPUT(FILE FILE ...)'
2165 The `INPUT' command directs the linker to include the named files
2166 in the link, as though they were named on the command line.
2168 For example, if you always want to include `subr.o' any time you do
2169 a link, but you can't be bothered to put it on every link command
2170 line, then you can put `INPUT (subr.o)' in your linker script.
2172 In fact, if you like, you can list all of your input files in the
2173 linker script, and then invoke the linker with nothing but a `-T'
2176 In case a "sysroot prefix" is configured, and the filename starts
2177 with the `/' character, and the script being processed was located
2178 inside the "sysroot prefix", the filename will be looked for in
2179 the "sysroot prefix". Otherwise, the linker will try to open the
2180 file in the current directory. If it is not found, the linker
2181 will search through the archive library search path. See the
2182 description of `-L' in *Note Command Line Options: Options.
2184 If you use `INPUT (-lFILE)', `ld' will transform the name to
2185 `libFILE.a', as with the command line argument `-l'.
2187 When you use the `INPUT' command in an implicit linker script, the
2188 files will be included in the link at the point at which the linker
2189 script file is included. This can affect archive searching.
2191 `GROUP(FILE, FILE, ...)'
2192 `GROUP(FILE FILE ...)'
2193 The `GROUP' command is like `INPUT', except that the named files
2194 should all be archives, and they are searched repeatedly until no
2195 new undefined references are created. See the description of `-('
2196 in *Note Command Line Options: Options.
2198 `AS_NEEDED(FILE, FILE, ...)'
2199 `AS_NEEDED(FILE FILE ...)'
2200 This construct can appear only inside of the `INPUT' or `GROUP'
2201 commands, among other filenames. The files listed will be handled
2202 as if they appear directly in the `INPUT' or `GROUP' commands,
2203 with the exception of ELF shared libraries, that will be added only
2204 when they are actually needed. This construct essentially enables
2205 `--as-needed' option for all the files listed inside of it and
2206 restores previous `--as-needed' resp. `--no-as-needed' setting
2210 The `OUTPUT' command names the output file. Using
2211 `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
2212 FILENAME' on the command line (*note Command Line Options:
2213 Options.). If both are used, the command line option takes
2216 You can use the `OUTPUT' command to define a default name for the
2217 output file other than the usual default of `a.out'.
2220 The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
2221 looks for archive libraries. Using `SEARCH_DIR(PATH)' is exactly
2222 like using `-L PATH' on the command line (*note Command Line
2223 Options: Options.). If both are used, then the linker will search
2224 both paths. Paths specified using the command line option are
2228 The `STARTUP' command is just like the `INPUT' command, except
2229 that FILENAME will become the first input file to be linked, as
2230 though it were specified first on the command line. This may be
2231 useful when using a system in which the entry point is always the
2232 start of the first file.
2235 File: ld.info, Node: Format Commands, Next: Miscellaneous Commands, Prev: File Commands, Up: Simple Commands
2237 3.4.3 Commands Dealing with Object File Formats
2238 -----------------------------------------------
2240 A couple of linker script commands deal with object file formats.
2242 `OUTPUT_FORMAT(BFDNAME)'
2243 `OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
2244 The `OUTPUT_FORMAT' command names the BFD format to use for the
2245 output file (*note BFD::). Using `OUTPUT_FORMAT(BFDNAME)' is
2246 exactly like using `--oformat BFDNAME' on the command line (*note
2247 Command Line Options: Options.). If both are used, the command
2248 line option takes precedence.
2250 You can use `OUTPUT_FORMAT' with three arguments to use different
2251 formats based on the `-EB' and `-EL' command line options. This
2252 permits the linker script to set the output format based on the
2255 If neither `-EB' nor `-EL' are used, then the output format will
2256 be the first argument, DEFAULT. If `-EB' is used, the output
2257 format will be the second argument, BIG. If `-EL' is used, the
2258 output format will be the third argument, LITTLE.
2260 For example, the default linker script for the MIPS ELF target
2262 OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
2263 This says that the default format for the output file is
2264 `elf32-bigmips', but if the user uses the `-EL' command line
2265 option, the output file will be created in the `elf32-littlemips'
2269 The `TARGET' command names the BFD format to use when reading input
2270 files. It affects subsequent `INPUT' and `GROUP' commands. This
2271 command is like using `-b BFDNAME' on the command line (*note
2272 Command Line Options: Options.). If the `TARGET' command is used
2273 but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
2274 used to set the format for the output file. *Note BFD::.
2277 File: ld.info, Node: Miscellaneous Commands, Prev: Format Commands, Up: Simple Commands
2279 3.4.4 Other Linker Script Commands
2280 ----------------------------------
2282 There are a few other linker scripts commands.
2284 `ASSERT(EXP, MESSAGE)'
2285 Ensure that EXP is non-zero. If it is zero, then exit the linker
2286 with an error code, and print MESSAGE.
2288 `EXTERN(SYMBOL SYMBOL ...)'
2289 Force SYMBOL to be entered in the output file as an undefined
2290 symbol. Doing this may, for example, trigger linking of additional
2291 modules from standard libraries. You may list several SYMBOLs for
2292 each `EXTERN', and you may use `EXTERN' multiple times. This
2293 command has the same effect as the `-u' command-line option.
2295 `FORCE_COMMON_ALLOCATION'
2296 This command has the same effect as the `-d' command-line option:
2297 to make `ld' assign space to common symbols even if a relocatable
2298 output file is specified (`-r').
2300 `INHIBIT_COMMON_ALLOCATION'
2301 This command has the same effect as the `--no-define-common'
2302 command-line option: to make `ld' omit the assignment of addresses
2303 to common symbols even for a non-relocatable output file.
2305 `NOCROSSREFS(SECTION SECTION ...)'
2306 This command may be used to tell `ld' to issue an error about any
2307 references among certain output sections.
2309 In certain types of programs, particularly on embedded systems when
2310 using overlays, when one section is loaded into memory, another
2311 section will not be. Any direct references between the two
2312 sections would be errors. For example, it would be an error if
2313 code in one section called a function defined in the other section.
2315 The `NOCROSSREFS' command takes a list of output section names. If
2316 `ld' detects any cross references between the sections, it reports
2317 an error and returns a non-zero exit status. Note that the
2318 `NOCROSSREFS' command uses output section names, not input section
2321 `OUTPUT_ARCH(BFDARCH)'
2322 Specify a particular output machine architecture. The argument is
2323 one of the names used by the BFD library (*note BFD::). You can
2324 see the architecture of an object file by using the `objdump'
2325 program with the `-f' option.
2328 File: ld.info, Node: Assignments, Next: SECTIONS, Prev: Simple Commands, Up: Scripts
2330 3.5 Assigning Values to Symbols
2331 ===============================
2333 You may assign a value to a symbol in a linker script. This will define
2334 the symbol and place it into the symbol table with a global scope.
2338 * Simple Assignments:: Simple Assignments
2340 * PROVIDE_HIDDEN:: PROVIDE_HIDDEN
2341 * Source Code Reference:: How to use a linker script defined symbol in source code
2344 File: ld.info, Node: Simple Assignments, Next: PROVIDE, Up: Assignments
2346 3.5.1 Simple Assignments
2347 ------------------------
2349 You may assign to a symbol using any of the C assignment operators:
2351 `SYMBOL = EXPRESSION ;'
2352 `SYMBOL += EXPRESSION ;'
2353 `SYMBOL -= EXPRESSION ;'
2354 `SYMBOL *= EXPRESSION ;'
2355 `SYMBOL /= EXPRESSION ;'
2356 `SYMBOL <<= EXPRESSION ;'
2357 `SYMBOL >>= EXPRESSION ;'
2358 `SYMBOL &= EXPRESSION ;'
2359 `SYMBOL |= EXPRESSION ;'
2361 The first case will define SYMBOL to the value of EXPRESSION. In
2362 the other cases, SYMBOL must already be defined, and the value will be
2363 adjusted accordingly.
2365 The special symbol name `.' indicates the location counter. You may
2366 only use this within a `SECTIONS' command. *Note Location Counter::.
2368 The semicolon after EXPRESSION is required.
2370 Expressions are defined below; see *Note Expressions::.
2372 You may write symbol assignments as commands in their own right, or
2373 as statements within a `SECTIONS' command, or as part of an output
2374 section description in a `SECTIONS' command.
2376 The section of the symbol will be set from the section of the
2377 expression; for more information, see *Note Expression Section::.
2379 Here is an example showing the three different places that symbol
2380 assignments may be used:
2390 _bdata = (. + 3) & ~ 3;
2391 .data : { *(.data) }
2393 In this example, the symbol `floating_point' will be defined as
2394 zero. The symbol `_etext' will be defined as the address following the
2395 last `.text' input section. The symbol `_bdata' will be defined as the
2396 address following the `.text' output section aligned upward to a 4 byte
2400 File: ld.info, Node: PROVIDE, Next: PROVIDE_HIDDEN, Prev: Simple Assignments, Up: Assignments
2405 In some cases, it is desirable for a linker script to define a symbol
2406 only if it is referenced and is not defined by any object included in
2407 the link. For example, traditional linkers defined the symbol `etext'.
2408 However, ANSI C requires that the user be able to use `etext' as a
2409 function name without encountering an error. The `PROVIDE' keyword may
2410 be used to define a symbol, such as `etext', only if it is referenced
2411 but not defined. The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.
2413 Here is an example of using `PROVIDE' to define `etext':
2424 In this example, if the program defines `_etext' (with a leading
2425 underscore), the linker will give a multiple definition error. If, on
2426 the other hand, the program defines `etext' (with no leading
2427 underscore), the linker will silently use the definition in the program.
2428 If the program references `etext' but does not define it, the linker
2429 will use the definition in the linker script.
2432 File: ld.info, Node: PROVIDE_HIDDEN, Next: Source Code Reference, Prev: PROVIDE, Up: Assignments
2434 3.5.3 PROVIDE_HIDDEN
2435 --------------------
2437 Similar to `PROVIDE'. For ELF targeted ports, the symbol will be
2438 hidden and won't be exported.
2441 File: ld.info, Node: Source Code Reference, Prev: PROVIDE_HIDDEN, Up: Assignments
2443 3.5.4 Source Code Reference
2444 ---------------------------
2446 Accessing a linker script defined variable from source code is not
2447 intuitive. In particular a linker script symbol is not equivalent to a
2448 variable declaration in a high level language, it is instead a symbol
2449 that does not have a value.
2451 Before going further, it is important to note that compilers often
2452 transform names in the source code into different names when they are
2453 stored in the symbol table. For example, Fortran compilers commonly
2454 prepend or append an underscore, and C++ performs extensive `name
2455 mangling'. Therefore there might be a discrepancy between the name of
2456 a variable as it is used in source code and the name of the same
2457 variable as it is defined in a linker script. For example in C a
2458 linker script variable might be referred to as:
2462 But in the linker script it might be defined as:
2466 In the remaining examples however it is assumed that no name
2467 transformation has taken place.
2469 When a symbol is declared in a high level language such as C, two
2470 things happen. The first is that the compiler reserves enough space in
2471 the program's memory to hold the _value_ of the symbol. The second is
2472 that the compiler creates an entry in the program's symbol table which
2473 holds the symbol's _address_. ie the symbol table contains the address
2474 of the block of memory holding the symbol's value. So for example the
2475 following C declaration, at file scope:
2479 creates a entry called `foo' in the symbol table. This entry holds
2480 the address of an `int' sized block of memory where the number 1000 is
2483 When a program references a symbol the compiler generates code that
2484 first accesses the symbol table to find the address of the symbol's
2485 memory block and then code to read the value from that memory block.
2490 looks up the symbol `foo' in the symbol table, gets the address
2491 associated with this symbol and then writes the value 1 into that
2496 looks up the symbol `foo' in the symbol table, gets it address and
2497 then copies this address into the block of memory associated with the
2500 Linker scripts symbol declarations, by contrast, create an entry in
2501 the symbol table but do not assign any memory to them. Thus they are
2502 an address without a value. So for example the linker script
2507 creates an entry in the symbol table called `foo' which holds the
2508 address of memory location 1000, but nothing special is stored at
2509 address 1000. This means that you cannot access the _value_ of a
2510 linker script defined symbol - it has no value - all you can do is
2511 access the _address_ of a linker script defined symbol.
2513 Hence when you are using a linker script defined symbol in source
2514 code you should always take the address of the symbol, and never
2515 attempt to use its value. For example suppose you want to copy the
2516 contents of a section of memory called .ROM into a section called
2517 .FLASH and the linker script contains these declarations:
2519 start_of_ROM = .ROM;
2520 end_of_ROM = .ROM + sizeof (.ROM) - 1;
2521 start_of_FLASH = .FLASH;
2523 Then the C source code to perform the copy would be:
2525 extern char start_of_ROM, end_of_ROM, start_of_FLASH;
2527 memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
2529 Note the use of the `&' operators. These are correct.
2532 File: ld.info, Node: SECTIONS, Next: MEMORY, Prev: Assignments, Up: Scripts
2534 3.6 SECTIONS Command
2535 ====================
2537 The `SECTIONS' command tells the linker how to map input sections into
2538 output sections, and how to place the output sections in memory.
2540 The format of the `SECTIONS' command is:
2548 Each SECTIONS-COMMAND may of be one of the following:
2550 * an `ENTRY' command (*note Entry command: Entry Point.)
2552 * a symbol assignment (*note Assignments::)
2554 * an output section description
2556 * an overlay description
2558 The `ENTRY' command and symbol assignments are permitted inside the
2559 `SECTIONS' command for convenience in using the location counter in
2560 those commands. This can also make the linker script easier to
2561 understand because you can use those commands at meaningful points in
2562 the layout of the output file.
2564 Output section descriptions and overlay descriptions are described
2567 If you do not use a `SECTIONS' command in your linker script, the
2568 linker will place each input section into an identically named output
2569 section in the order that the sections are first encountered in the
2570 input files. If all input sections are present in the first file, for
2571 example, the order of sections in the output file will match the order
2572 in the first input file. The first section will be at address zero.
2576 * Output Section Description:: Output section description
2577 * Output Section Name:: Output section name
2578 * Output Section Address:: Output section address
2579 * Input Section:: Input section description
2580 * Output Section Data:: Output section data
2581 * Output Section Keywords:: Output section keywords
2582 * Output Section Discarding:: Output section discarding
2583 * Output Section Attributes:: Output section attributes
2584 * Overlay Description:: Overlay description
2587 File: ld.info, Node: Output Section Description, Next: Output Section Name, Up: SECTIONS
2589 3.6.1 Output Section Description
2590 --------------------------------
2592 The full description of an output section looks like this:
2593 SECTION [ADDRESS] [(TYPE)] :
2594 [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
2596 OUTPUT-SECTION-COMMAND
2597 OUTPUT-SECTION-COMMAND
2599 } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
2601 Most output sections do not use most of the optional section
2604 The whitespace around SECTION is required, so that the section name
2605 is unambiguous. The colon and the curly braces are also required. The
2606 line breaks and other white space are optional.
2608 Each OUTPUT-SECTION-COMMAND may be one of the following:
2610 * a symbol assignment (*note Assignments::)
2612 * an input section description (*note Input Section::)
2614 * data values to include directly (*note Output Section Data::)
2616 * a special output section keyword (*note Output Section Keywords::)
2619 File: ld.info, Node: Output Section Name, Next: Output Section Address, Prev: Output Section Description, Up: SECTIONS
2621 3.6.2 Output Section Name
2622 -------------------------
2624 The name of the output section is SECTION. SECTION must meet the
2625 constraints of your output format. In formats which only support a
2626 limited number of sections, such as `a.out', the name must be one of
2627 the names supported by the format (`a.out', for example, allows only
2628 `.text', `.data' or `.bss'). If the output format supports any number
2629 of sections, but with numbers and not names (as is the case for Oasys),
2630 the name should be supplied as a quoted numeric string. A section name
2631 may consist of any sequence of characters, but a name which contains
2632 any unusual characters such as commas must be quoted.
2634 The output section name `/DISCARD/' is special; *Note Output Section
2638 File: ld.info, Node: Output Section Address, Next: Input Section, Prev: Output Section Name, Up: SECTIONS
2640 3.6.3 Output Section Address
2641 ----------------------------
2643 The ADDRESS is an expression for the VMA (the virtual memory address)
2644 of the output section. If you do not provide ADDRESS, the linker will
2645 set it based on REGION if present, or otherwise based on the current
2646 value of the location counter.
2648 If you provide ADDRESS, the address of the output section will be
2649 set to precisely that. If you provide neither ADDRESS nor REGION, then
2650 the address of the output section will be set to the current value of
2651 the location counter aligned to the alignment requirements of the
2652 output section. The alignment requirement of the output section is the
2653 strictest alignment of any input section contained within the output
2657 .text . : { *(.text) }
2659 .text : { *(.text) }
2660 are subtly different. The first will set the address of the `.text'
2661 output section to the current value of the location counter. The
2662 second will set it to the current value of the location counter aligned
2663 to the strictest alignment of a `.text' input section.
2665 The ADDRESS may be an arbitrary expression; *Note Expressions::.
2666 For example, if you want to align the section on a 0x10 byte boundary,
2667 so that the lowest four bits of the section address are zero, you could
2668 do something like this:
2669 .text ALIGN(0x10) : { *(.text) }
2670 This works because `ALIGN' returns the current location counter
2671 aligned upward to the specified value.
2673 Specifying ADDRESS for a section will change the value of the
2677 File: ld.info, Node: Input Section, Next: Output Section Data, Prev: Output Section Address, Up: SECTIONS
2679 3.6.4 Input Section Description
2680 -------------------------------
2682 The most common output section command is an input section description.
2684 The input section description is the most basic linker script
2685 operation. You use output sections to tell the linker how to lay out
2686 your program in memory. You use input section descriptions to tell the
2687 linker how to map the input files into your memory layout.
2691 * Input Section Basics:: Input section basics
2692 * Input Section Wildcards:: Input section wildcard patterns
2693 * Input Section Common:: Input section for common symbols
2694 * Input Section Keep:: Input section and garbage collection
2695 * Input Section Example:: Input section example
2698 File: ld.info, Node: Input Section Basics, Next: Input Section Wildcards, Up: Input Section
2700 3.6.4.1 Input Section Basics
2701 ............................
2703 An input section description consists of a file name optionally followed
2704 by a list of section names in parentheses.
2706 The file name and the section name may be wildcard patterns, which we
2707 describe further below (*note Input Section Wildcards::).
2709 The most common input section description is to include all input
2710 sections with a particular name in the output section. For example, to
2711 include all input `.text' sections, you would write:
2713 Here the `*' is a wildcard which matches any file name. To exclude
2714 a list of files from matching the file name wildcard, EXCLUDE_FILE may
2715 be used to match all files except the ones specified in the
2716 EXCLUDE_FILE list. For example:
2717 *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
2718 will cause all .ctors sections from all files except `crtend.o' and
2719 `otherfile.o' to be included.
2721 There are two ways to include more than one section:
2724 The difference between these is the order in which the `.text' and
2725 `.rdata' input sections will appear in the output section. In the
2726 first example, they will be intermingled, appearing in the same order as
2727 they are found in the linker input. In the second example, all `.text'
2728 input sections will appear first, followed by all `.rdata' input
2731 You can specify a file name to include sections from a particular
2732 file. You would do this if one or more of your files contain special
2733 data that needs to be at a particular location in memory. For example:
2736 If you use a file name without a list of sections, then all sections
2737 in the input file will be included in the output section. This is not
2738 commonly done, but it may by useful on occasion. For example:
2741 When you use a file name which does not contain any wild card
2742 characters, the linker will first see if you also specified the file
2743 name on the linker command line or in an `INPUT' command. If you did
2744 not, the linker will attempt to open the file as an input file, as
2745 though it appeared on the command line. Note that this differs from an
2746 `INPUT' command, because the linker will not search for the file in the
2747 archive search path.
2750 File: ld.info, Node: Input Section Wildcards, Next: Input Section Common, Prev: Input Section Basics, Up: Input Section
2752 3.6.4.2 Input Section Wildcard Patterns
2753 .......................................
2755 In an input section description, either the file name or the section
2756 name or both may be wildcard patterns.
2758 The file name of `*' seen in many examples is a simple wildcard
2759 pattern for the file name.
2761 The wildcard patterns are like those used by the Unix shell.
2764 matches any number of characters
2767 matches any single character
2770 matches a single instance of any of the CHARS; the `-' character
2771 may be used to specify a range of characters, as in `[a-z]' to
2772 match any lower case letter
2775 quotes the following character
2777 When a file name is matched with a wildcard, the wildcard characters
2778 will not match a `/' character (used to separate directory names on
2779 Unix). A pattern consisting of a single `*' character is an exception;
2780 it will always match any file name, whether it contains a `/' or not.
2781 In a section name, the wildcard characters will match a `/' character.
2783 File name wildcard patterns only match files which are explicitly
2784 specified on the command line or in an `INPUT' command. The linker
2785 does not search directories to expand wildcards.
2787 If a file name matches more than one wildcard pattern, or if a file
2788 name appears explicitly and is also matched by a wildcard pattern, the
2789 linker will use the first match in the linker script. For example, this
2790 sequence of input section descriptions is probably in error, because the
2791 `data.o' rule will not be used:
2792 .data : { *(.data) }
2793 .data1 : { data.o(.data) }
2795 Normally, the linker will place files and sections matched by
2796 wildcards in the order in which they are seen during the link. You can
2797 change this by using the `SORT_BY_NAME' keyword, which appears before a
2798 wildcard pattern in parentheses (e.g., `SORT_BY_NAME(.text*)'). When
2799 the `SORT_BY_NAME' keyword is used, the linker will sort the files or
2800 sections into ascending order by name before placing them in the output
2803 `SORT_BY_ALIGNMENT' is very similar to `SORT_BY_NAME'. The
2804 difference is `SORT_BY_ALIGNMENT' will sort sections into ascending
2805 order by alignment before placing them in the output file.
2807 `SORT' is an alias for `SORT_BY_NAME'.
2809 When there are nested section sorting commands in linker script,
2810 there can be at most 1 level of nesting for section sorting commands.
2812 1. `SORT_BY_NAME' (`SORT_BY_ALIGNMENT' (wildcard section pattern)).
2813 It will sort the input sections by name first, then by alignment
2814 if 2 sections have the same name.
2816 2. `SORT_BY_ALIGNMENT' (`SORT_BY_NAME' (wildcard section pattern)).
2817 It will sort the input sections by alignment first, then by name
2818 if 2 sections have the same alignment.
2820 3. `SORT_BY_NAME' (`SORT_BY_NAME' (wildcard section pattern)) is
2821 treated the same as `SORT_BY_NAME' (wildcard section pattern).
2823 4. `SORT_BY_ALIGNMENT' (`SORT_BY_ALIGNMENT' (wildcard section
2824 pattern)) is treated the same as `SORT_BY_ALIGNMENT' (wildcard
2827 5. All other nested section sorting commands are invalid.
2829 When both command line section sorting option and linker script
2830 section sorting command are used, section sorting command always takes
2831 precedence over the command line option.
2833 If the section sorting command in linker script isn't nested, the
2834 command line option will make the section sorting command to be treated
2835 as nested sorting command.
2837 1. `SORT_BY_NAME' (wildcard section pattern ) with `--sort-sections
2838 alignment' is equivalent to `SORT_BY_NAME' (`SORT_BY_ALIGNMENT'
2839 (wildcard section pattern)).
2841 2. `SORT_BY_ALIGNMENT' (wildcard section pattern) with
2842 `--sort-section name' is equivalent to `SORT_BY_ALIGNMENT'
2843 (`SORT_BY_NAME' (wildcard section pattern)).
2845 If the section sorting command in linker script is nested, the
2846 command line option will be ignored.
2848 If you ever get confused about where input sections are going, use
2849 the `-M' linker option to generate a map file. The map file shows
2850 precisely how input sections are mapped to output sections.
2852 This example shows how wildcard patterns might be used to partition
2853 files. This linker script directs the linker to place all `.text'
2854 sections in `.text' and all `.bss' sections in `.bss'. The linker will
2855 place the `.data' section from all files beginning with an upper case
2856 character in `.DATA'; for all other files, the linker will place the
2857 `.data' section in `.data'.
2859 .text : { *(.text) }
2860 .DATA : { [A-Z]*(.data) }
2861 .data : { *(.data) }
2866 File: ld.info, Node: Input Section Common, Next: Input Section Keep, Prev: Input Section Wildcards, Up: Input Section
2868 3.6.4.3 Input Section for Common Symbols
2869 ........................................
2871 A special notation is needed for common symbols, because in many object
2872 file formats common symbols do not have a particular input section. The
2873 linker treats common symbols as though they are in an input section
2876 You may use file names with the `COMMON' section just as with any
2877 other input sections. You can use this to place common symbols from a
2878 particular input file in one section while common symbols from other
2879 input files are placed in another section.
2881 In most cases, common symbols in input files will be placed in the
2882 `.bss' section in the output file. For example:
2883 .bss { *(.bss) *(COMMON) }
2885 Some object file formats have more than one type of common symbol.
2886 For example, the MIPS ELF object file format distinguishes standard
2887 common symbols and small common symbols. In this case, the linker will
2888 use a different special section name for other types of common symbols.
2889 In the case of MIPS ELF, the linker uses `COMMON' for standard common
2890 symbols and `.scommon' for small common symbols. This permits you to
2891 map the different types of common symbols into memory at different
2894 You will sometimes see `[COMMON]' in old linker scripts. This
2895 notation is now considered obsolete. It is equivalent to `*(COMMON)'.
2898 File: ld.info, Node: Input Section Keep, Next: Input Section Example, Prev: Input Section Common, Up: Input Section
2900 3.6.4.4 Input Section and Garbage Collection
2901 ............................................
2903 When link-time garbage collection is in use (`--gc-sections'), it is
2904 often useful to mark sections that should not be eliminated. This is
2905 accomplished by surrounding an input section's wildcard entry with
2906 `KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT_BY_NAME(*)(.ctors))'.
2909 File: ld.info, Node: Input Section Example, Prev: Input Section Keep, Up: Input Section
2911 3.6.4.5 Input Section Example
2912 .............................
2914 The following example is a complete linker script. It tells the linker
2915 to read all of the sections from file `all.o' and place them at the
2916 start of output section `outputa' which starts at location `0x10000'.
2917 All of section `.input1' from file `foo.o' follows immediately, in the
2918 same output section. All of section `.input2' from `foo.o' goes into
2919 output section `outputb', followed by section `.input1' from `foo1.o'.
2920 All of the remaining `.input1' and `.input2' sections from any files
2921 are written to output section `outputc'.
2942 File: ld.info, Node: Output Section Data, Next: Output Section Keywords, Prev: Input Section, Up: SECTIONS
2944 3.6.5 Output Section Data
2945 -------------------------
2947 You can include explicit bytes of data in an output section by using
2948 `BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
2949 command. Each keyword is followed by an expression in parentheses
2950 providing the value to store (*note Expressions::). The value of the
2951 expression is stored at the current value of the location counter.
2953 The `BYTE', `SHORT', `LONG', and `QUAD' commands store one, two,
2954 four, and eight bytes (respectively). After storing the bytes, the
2955 location counter is incremented by the number of bytes stored.
2957 For example, this will store the byte 1 followed by the four byte
2958 value of the symbol `addr':
2962 When using a 64 bit host or target, `QUAD' and `SQUAD' are the same;
2963 they both store an 8 byte, or 64 bit, value. When both host and target
2964 are 32 bits, an expression is computed as 32 bits. In this case `QUAD'
2965 stores a 32 bit value zero extended to 64 bits, and `SQUAD' stores a 32
2966 bit value sign extended to 64 bits.
2968 If the object file format of the output file has an explicit
2969 endianness, which is the normal case, the value will be stored in that
2970 endianness. When the object file format does not have an explicit
2971 endianness, as is true of, for example, S-records, the value will be
2972 stored in the endianness of the first input object file.
2974 Note--these commands only work inside a section description and not
2975 between them, so the following will produce an error from the linker:
2976 SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
2977 whereas this will work:
2978 SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }
2980 You may use the `FILL' command to set the fill pattern for the
2981 current section. It is followed by an expression in parentheses. Any
2982 otherwise unspecified regions of memory within the section (for example,
2983 gaps left due to the required alignment of input sections) are filled
2984 with the value of the expression, repeated as necessary. A `FILL'
2985 statement covers memory locations after the point at which it occurs in
2986 the section definition; by including more than one `FILL' statement,
2987 you can have different fill patterns in different parts of an output
2990 This example shows how to fill unspecified regions of memory with the
2994 The `FILL' command is similar to the `=FILLEXP' output section
2995 attribute, but it only affects the part of the section following the
2996 `FILL' command, rather than the entire section. If both are used, the
2997 `FILL' command takes precedence. *Note Output Section Fill::, for
2998 details on the fill expression.
3001 File: ld.info, Node: Output Section Keywords, Next: Output Section Discarding, Prev: Output Section Data, Up: SECTIONS
3003 3.6.6 Output Section Keywords
3004 -----------------------------
3006 There are a couple of keywords which can appear as output section
3009 `CREATE_OBJECT_SYMBOLS'
3010 The command tells the linker to create a symbol for each input
3011 file. The name of each symbol will be the name of the
3012 corresponding input file. The section of each symbol will be the
3013 output section in which the `CREATE_OBJECT_SYMBOLS' command
3016 This is conventional for the a.out object file format. It is not
3017 normally used for any other object file format.
3020 When linking using the a.out object file format, the linker uses an
3021 unusual set construct to support C++ global constructors and
3022 destructors. When linking object file formats which do not support
3023 arbitrary sections, such as ECOFF and XCOFF, the linker will
3024 automatically recognize C++ global constructors and destructors by
3025 name. For these object file formats, the `CONSTRUCTORS' command
3026 tells the linker to place constructor information in the output
3027 section where the `CONSTRUCTORS' command appears. The
3028 `CONSTRUCTORS' command is ignored for other object file formats.
3030 The symbol `__CTOR_LIST__' marks the start of the global
3031 constructors, and the symbol `__CTOR_END__' marks the end.
3032 Similarly, `__DTOR_LIST__' and `__DTOR_END__' mark the start and
3033 end of the global destructors. The first word in the list is the
3034 number of entries, followed by the address of each constructor or
3035 destructor, followed by a zero word. The compiler must arrange to
3036 actually run the code. For these object file formats GNU C++
3037 normally calls constructors from a subroutine `__main'; a call to
3038 `__main' is automatically inserted into the startup code for
3039 `main'. GNU C++ normally runs destructors either by using
3040 `atexit', or directly from the function `exit'.
3042 For object file formats such as `COFF' or `ELF' which support
3043 arbitrary section names, GNU C++ will normally arrange to put the
3044 addresses of global constructors and destructors into the `.ctors'
3045 and `.dtors' sections. Placing the following sequence into your
3046 linker script will build the sort of table which the GNU C++
3047 runtime code expects to see.
3050 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
3055 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
3060 If you are using the GNU C++ support for initialization priority,
3061 which provides some control over the order in which global
3062 constructors are run, you must sort the constructors at link time
3063 to ensure that they are executed in the correct order. When using
3064 the `CONSTRUCTORS' command, use `SORT_BY_NAME(CONSTRUCTORS)'
3065 instead. When using the `.ctors' and `.dtors' sections, use
3066 `*(SORT_BY_NAME(.ctors))' and `*(SORT_BY_NAME(.dtors))' instead of
3067 just `*(.ctors)' and `*(.dtors)'.
3069 Normally the compiler and linker will handle these issues
3070 automatically, and you will not need to concern yourself with
3071 them. However, you may need to consider this if you are using C++
3072 and writing your own linker scripts.
3076 File: ld.info, Node: Output Section Discarding, Next: Output Section Attributes, Prev: Output Section Keywords, Up: SECTIONS
3078 3.6.7 Output Section Discarding
3079 -------------------------------
3081 The linker will not create output sections with no contents. This is
3082 for convenience when referring to input sections that may or may not be
3083 present in any of the input files. For example:
3085 will only create a `.foo' section in the output file if there is a
3086 `.foo' section in at least one input file, and if the input sections
3087 are not all empty. Other link script directives that allocate space in
3088 an output section will also create the output section.
3090 The linker will ignore address assignments (*note Output Section
3091 Address::) on discarded output sections, except when the linker script
3092 defines symbols in the output section. In that case the linker will
3093 obey the address assignments, possibly advancing dot even though the
3094 section is discarded.
3096 The special output section name `/DISCARD/' may be used to discard
3097 input sections. Any input sections which are assigned to an output
3098 section named `/DISCARD/' are not included in the output file.
3101 File: ld.info, Node: Output Section Attributes, Next: Overlay Description, Prev: Output Section Discarding, Up: SECTIONS
3103 3.6.8 Output Section Attributes
3104 -------------------------------
3106 We showed above that the full description of an output section looked
3108 SECTION [ADDRESS] [(TYPE)] :
3109 [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)]
3111 OUTPUT-SECTION-COMMAND
3112 OUTPUT-SECTION-COMMAND
3114 } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
3115 We've already described SECTION, ADDRESS, and
3116 OUTPUT-SECTION-COMMAND. In this section we will describe the remaining
3121 * Output Section Type:: Output section type
3122 * Output Section LMA:: Output section LMA
3123 * Forced Output Alignment:: Forced Output Alignment
3124 * Forced Input Alignment:: Forced Input Alignment
3125 * Output Section Region:: Output section region
3126 * Output Section Phdr:: Output section phdr
3127 * Output Section Fill:: Output section fill
3130 File: ld.info, Node: Output Section Type, Next: Output Section LMA, Up: Output Section Attributes
3132 3.6.8.1 Output Section Type
3133 ...........................
3135 Each output section may have a type. The type is a keyword in
3136 parentheses. The following types are defined:
3139 The section should be marked as not loadable, so that it will not
3140 be loaded into memory when the program is run.
3146 These type names are supported for backward compatibility, and are
3147 rarely used. They all have the same effect: the section should be
3148 marked as not allocatable, so that no memory is allocated for the
3149 section when the program is run.
3151 The linker normally sets the attributes of an output section based on
3152 the input sections which map into it. You can override this by using
3153 the section type. For example, in the script sample below, the `ROM'
3154 section is addressed at memory location `0' and does not need to be
3155 loaded when the program is run. The contents of the `ROM' section will
3156 appear in the linker output file as usual.
3158 ROM 0 (NOLOAD) : { ... }
3163 File: ld.info, Node: Output Section LMA, Next: Forced Output Alignment, Prev: Output Section Type, Up: Output Section Attributes
3165 3.6.8.2 Output Section LMA
3166 ..........................
3168 Every section has a virtual address (VMA) and a load address (LMA); see
3169 *Note Basic Script Concepts::. The address expression which may appear
3170 in an output section description sets the VMA (*note Output Section
3173 The expression LMA that follows the `AT' keyword specifies the load
3174 address of the section.
3176 Alternatively, with `AT>LMA_REGION' expression, you may specify a
3177 memory region for the section's load address. *Note MEMORY::. Note
3178 that if the section has not had a VMA assigned to it then the linker
3179 will use the LMA_REGION as the VMA region as well.
3181 If neither `AT' nor `AT>' is specified for an allocatable section,
3182 the linker will set the LMA such that the difference between VMA and
3183 LMA for the section is the same as the preceding output section in the
3184 same region. If there is no preceding output section or the section is
3185 not allocatable, the linker will set the LMA equal to the VMA. *Note
3186 Output Section Region::.
3188 This feature is designed to make it easy to build a ROM image. For
3189 example, the following linker script creates three output sections: one
3190 called `.text', which starts at `0x1000', one called `.mdata', which is
3191 loaded at the end of the `.text' section even though its VMA is
3192 `0x2000', and one called `.bss' to hold uninitialized data at address
3193 `0x3000'. The symbol `_data' is defined with the value `0x2000', which
3194 shows that the location counter holds the VMA value, not the LMA value.
3198 .text 0x1000 : { *(.text) _etext = . ; }
3200 AT ( ADDR (.text) + SIZEOF (.text) )
3201 { _data = . ; *(.data); _edata = . ; }
3203 { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;}
3206 The run-time initialization code for use with a program generated
3207 with this linker script would include something like the following, to
3208 copy the initialized data from the ROM image to its runtime address.
3209 Notice how this code takes advantage of the symbols defined by the
3212 extern char _etext, _data, _edata, _bstart, _bend;
3213 char *src = &_etext;
3216 /* ROM has data at end of text; copy it. */
3217 while (dst < &_edata) {
3222 for (dst = &_bstart; dst< &_bend; dst++)
3226 File: ld.info, Node: Forced Output Alignment, Next: Forced Input Alignment, Prev: Output Section LMA, Up: Output Section Attributes
3228 3.6.8.3 Forced Output Alignment
3229 ...............................
3231 You can increase an output section's alignment by using ALIGN.
3234 File: ld.info, Node: Forced Input Alignment, Next: Output Section Region, Prev: Forced Output Alignment, Up: Output Section Attributes
3236 3.6.8.4 Forced Input Alignment
3237 ..............................
3239 You can force input section alignment within an output section by using
3240 SUBALIGN. The value specified overrides any alignment given by input
3241 sections, whether larger or smaller.
3244 File: ld.info, Node: Output Section Region, Next: Output Section Phdr, Prev: Forced Input Alignment, Up: Output Section Attributes
3246 3.6.8.5 Output Section Region
3247 .............................
3249 You can assign a section to a previously defined region of memory by
3250 using `>REGION'. *Note MEMORY::.
3252 Here is a simple example:
3253 MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
3254 SECTIONS { ROM : { *(.text) } >rom }
3257 File: ld.info, Node: Output Section Phdr, Next: Output Section Fill, Prev: Output Section Region, Up: Output Section Attributes
3259 3.6.8.6 Output Section Phdr
3260 ...........................
3262 You can assign a section to a previously defined program segment by
3263 using `:PHDR'. *Note PHDRS::. If a section is assigned to one or more
3264 segments, then all subsequent allocated sections will be assigned to
3265 those segments as well, unless they use an explicitly `:PHDR' modifier.
3266 You can use `:NONE' to tell the linker to not put the section in any
3269 Here is a simple example:
3270 PHDRS { text PT_LOAD ; }
3271 SECTIONS { .text : { *(.text) } :text }
3274 File: ld.info, Node: Output Section Fill, Prev: Output Section Phdr, Up: Output Section Attributes
3276 3.6.8.7 Output Section Fill
3277 ...........................
3279 You can set the fill pattern for an entire section by using `=FILLEXP'.
3280 FILLEXP is an expression (*note Expressions::). Any otherwise
3281 unspecified regions of memory within the output section (for example,
3282 gaps left due to the required alignment of input sections) will be
3283 filled with the value, repeated as necessary. If the fill expression
3284 is a simple hex number, ie. a string of hex digit starting with `0x'
3285 and without a trailing `k' or `M', then an arbitrarily long sequence of
3286 hex digits can be used to specify the fill pattern; Leading zeros
3287 become part of the pattern too. For all other cases, including extra
3288 parentheses or a unary `+', the fill pattern is the four least
3289 significant bytes of the value of the expression. In all cases, the
3290 number is big-endian.
3292 You can also change the fill value with a `FILL' command in the
3293 output section commands; (*note Output Section Data::).
3295 Here is a simple example:
3296 SECTIONS { .text : { *(.text) } =0x90909090 }
3299 File: ld.info, Node: Overlay Description, Prev: Output Section Attributes, Up: SECTIONS
3301 3.6.9 Overlay Description
3302 -------------------------
3304 An overlay description provides an easy way to describe sections which
3305 are to be loaded as part of a single memory image but are to be run at
3306 the same memory address. At run time, some sort of overlay manager will
3307 copy the overlaid sections in and out of the runtime memory address as
3308 required, perhaps by simply manipulating addressing bits. This approach
3309 can be useful, for example, when a certain region of memory is faster
3312 Overlays are described using the `OVERLAY' command. The `OVERLAY'
3313 command is used within a `SECTIONS' command, like an output section
3314 description. The full syntax of the `OVERLAY' command is as follows:
3315 OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
3319 OUTPUT-SECTION-COMMAND
3320 OUTPUT-SECTION-COMMAND
3322 } [:PHDR...] [=FILL]
3325 OUTPUT-SECTION-COMMAND
3326 OUTPUT-SECTION-COMMAND
3328 } [:PHDR...] [=FILL]
3330 } [>REGION] [:PHDR...] [=FILL]
3332 Everything is optional except `OVERLAY' (a keyword), and each
3333 section must have a name (SECNAME1 and SECNAME2 above). The section
3334 definitions within the `OVERLAY' construct are identical to those
3335 within the general `SECTIONS' contruct (*note SECTIONS::), except that
3336 no addresses and no memory regions may be defined for sections within
3339 The sections are all defined with the same starting address. The
3340 load addresses of the sections are arranged such that they are
3341 consecutive in memory starting at the load address used for the
3342 `OVERLAY' as a whole (as with normal section definitions, the load
3343 address is optional, and defaults to the start address; the start
3344 address is also optional, and defaults to the current value of the
3347 If the `NOCROSSREFS' keyword is used, and there any references among
3348 the sections, the linker will report an error. Since the sections all
3349 run at the same address, it normally does not make sense for one
3350 section to refer directly to another. *Note NOCROSSREFS: Miscellaneous
3353 For each section within the `OVERLAY', the linker automatically
3354 provides two symbols. The symbol `__load_start_SECNAME' is defined as
3355 the starting load address of the section. The symbol
3356 `__load_stop_SECNAME' is defined as the final load address of the
3357 section. Any characters within SECNAME which are not legal within C
3358 identifiers are removed. C (or assembler) code may use these symbols
3359 to move the overlaid sections around as necessary.
3361 At the end of the overlay, the value of the location counter is set
3362 to the start address of the overlay plus the size of the largest
3365 Here is an example. Remember that this would appear inside a
3366 `SECTIONS' construct.
3367 OVERLAY 0x1000 : AT (0x4000)
3369 .text0 { o1/*.o(.text) }
3370 .text1 { o2/*.o(.text) }
3372 This will define both `.text0' and `.text1' to start at address
3373 0x1000. `.text0' will be loaded at address 0x4000, and `.text1' will
3374 be loaded immediately after `.text0'. The following symbols will be
3375 defined if referenced: `__load_start_text0', `__load_stop_text0',
3376 `__load_start_text1', `__load_stop_text1'.
3378 C code to copy overlay `.text1' into the overlay area might look
3381 extern char __load_start_text1, __load_stop_text1;
3382 memcpy ((char *) 0x1000, &__load_start_text1,
3383 &__load_stop_text1 - &__load_start_text1);
3385 Note that the `OVERLAY' command is just syntactic sugar, since
3386 everything it does can be done using the more basic commands. The above
3387 example could have been written identically as follows.
3389 .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
3390 PROVIDE (__load_start_text0 = LOADADDR (.text0));
3391 PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
3392 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
3393 PROVIDE (__load_start_text1 = LOADADDR (.text1));
3394 PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
3395 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
3398 File: ld.info, Node: MEMORY, Next: PHDRS, Prev: SECTIONS, Up: Scripts
3403 The linker's default configuration permits allocation of all available
3404 memory. You can override this by using the `MEMORY' command.
3406 The `MEMORY' command describes the location and size of blocks of
3407 memory in the target. You can use it to describe which memory regions
3408 may be used by the linker, and which memory regions it must avoid. You
3409 can then assign sections to particular memory regions. The linker will
3410 set section addresses based on the memory regions, and will warn about
3411 regions that become too full. The linker will not shuffle sections
3412 around to fit into the available regions.
3414 A linker script may contain at most one use of the `MEMORY' command.
3415 However, you can define as many blocks of memory within it as you
3416 wish. The syntax is:
3419 NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
3423 The NAME is a name used in the linker script to refer to the region.
3424 The region name has no meaning outside of the linker script. Region
3425 names are stored in a separate name space, and will not conflict with
3426 symbol names, file names, or section names. Each memory region must
3427 have a distinct name.
3429 The ATTR string is an optional list of attributes that specify
3430 whether to use a particular memory region for an input section which is
3431 not explicitly mapped in the linker script. As described in *Note
3432 SECTIONS::, if you do not specify an output section for some input
3433 section, the linker will create an output section with the same name as
3434 the input section. If you define region attributes, the linker will use
3435 them to select the memory region for the output section that it creates.
3437 The ATTR string must consist only of the following characters:
3457 Invert the sense of any of the preceding attributes
3459 If a unmapped section matches any of the listed attributes other than
3460 `!', it will be placed in the memory region. The `!' attribute
3461 reverses this test, so that an unmapped section will be placed in the
3462 memory region only if it does not match any of the listed attributes.
3464 The ORIGIN is an numerical expression for the start address of the
3465 memory region. The expression must evaluate to a constant and it
3466 cannot involve any symbols. The keyword `ORIGIN' may be abbreviated to
3467 `org' or `o' (but not, for example, `ORG').
3469 The LEN is an expression for the size in bytes of the memory region.
3470 As with the ORIGIN expression, the expression must be numerical only
3471 and must evaluate to a constant. The keyword `LENGTH' may be
3472 abbreviated to `len' or `l'.
3474 In the following example, we specify that there are two memory
3475 regions available for allocation: one starting at `0' for 256 kilobytes,
3476 and the other starting at `0x40000000' for four megabytes. The linker
3477 will place into the `rom' memory region every section which is not
3478 explicitly mapped into a memory region, and is either read-only or
3479 executable. The linker will place other sections which are not
3480 explicitly mapped into a memory region into the `ram' memory region.
3484 rom (rx) : ORIGIN = 0, LENGTH = 256K
3485 ram (!rx) : org = 0x40000000, l = 4M
3488 Once you define a memory region, you can direct the linker to place
3489 specific output sections into that memory region by using the `>REGION'
3490 output section attribute. For example, if you have a memory region
3491 named `mem', you would use `>mem' in the output section definition.
3492 *Note Output Section Region::. If no address was specified for the
3493 output section, the linker will set the address to the next available
3494 address within the memory region. If the combined output sections
3495 directed to a memory region are too large for the region, the linker
3496 will issue an error message.
3498 It is possible to access the origin and length of a memory in an
3499 expression via the `ORIGIN(MEMORY)' and `LENGTH(MEMORY)' functions:
3501 _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
3504 File: ld.info, Node: PHDRS, Next: VERSION, Prev: MEMORY, Up: Scripts
3509 The ELF object file format uses "program headers", also knows as
3510 "segments". The program headers describe how the program should be
3511 loaded into memory. You can print them out by using the `objdump'
3512 program with the `-p' option.
3514 When you run an ELF program on a native ELF system, the system loader
3515 reads the program headers in order to figure out how to load the
3516 program. This will only work if the program headers are set correctly.
3517 This manual does not describe the details of how the system loader
3518 interprets program headers; for more information, see the ELF ABI.
3520 The linker will create reasonable program headers by default.
3521 However, in some cases, you may need to specify the program headers more
3522 precisely. You may use the `PHDRS' command for this purpose. When the
3523 linker sees the `PHDRS' command in the linker script, it will not
3524 create any program headers other than the ones specified.
3526 The linker only pays attention to the `PHDRS' command when
3527 generating an ELF output file. In other cases, the linker will simply
3530 This is the syntax of the `PHDRS' command. The words `PHDRS',
3531 `FILEHDR', `AT', and `FLAGS' are keywords.
3535 NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
3536 [ FLAGS ( FLAGS ) ] ;
3539 The NAME is used only for reference in the `SECTIONS' command of the
3540 linker script. It is not put into the output file. Program header
3541 names are stored in a separate name space, and will not conflict with
3542 symbol names, file names, or section names. Each program header must
3543 have a distinct name.
3545 Certain program header types describe segments of memory which the
3546 system loader will load from the file. In the linker script, you
3547 specify the contents of these segments by placing allocatable output
3548 sections in the segments. You use the `:PHDR' output section attribute
3549 to place a section in a particular segment. *Note Output Section
3552 It is normal to put certain sections in more than one segment. This
3553 merely implies that one segment of memory contains another. You may
3554 repeat `:PHDR', using it once for each segment which should contain the
3557 If you place a section in one or more segments using `:PHDR', then
3558 the linker will place all subsequent allocatable sections which do not
3559 specify `:PHDR' in the same segments. This is for convenience, since
3560 generally a whole set of contiguous sections will be placed in a single
3561 segment. You can use `:NONE' to override the default segment and tell
3562 the linker to not put the section in any segment at all.
3564 You may use the `FILEHDR' and `PHDRS' keywords appear after the
3565 program header type to further describe the contents of the segment.
3566 The `FILEHDR' keyword means that the segment should include the ELF
3567 file header. The `PHDRS' keyword means that the segment should include
3568 the ELF program headers themselves.
3570 The TYPE may be one of the following. The numbers indicate the
3571 value of the keyword.
3574 Indicates an unused program header.
3577 Indicates that this program header describes a segment to be
3578 loaded from the file.
3581 Indicates a segment where dynamic linking information can be found.
3584 Indicates a segment where the name of the program interpreter may
3588 Indicates a segment holding note information.
3591 A reserved program header type, defined but not specified by the
3595 Indicates a segment where the program headers may be found.
3598 An expression giving the numeric type of the program header. This
3599 may be used for types not defined above.
3601 You can specify that a segment should be loaded at a particular
3602 address in memory by using an `AT' expression. This is identical to the
3603 `AT' command used as an output section attribute (*note Output Section
3604 LMA::). The `AT' command for a program header overrides the output
3607 The linker will normally set the segment flags based on the sections
3608 which comprise the segment. You may use the `FLAGS' keyword to
3609 explicitly specify the segment flags. The value of FLAGS must be an
3610 integer. It is used to set the `p_flags' field of the program header.
3612 Here is an example of `PHDRS'. This shows a typical set of program
3613 headers used on a native ELF system.
3617 headers PT_PHDR PHDRS ;
3619 text PT_LOAD FILEHDR PHDRS ;
3621 dynamic PT_DYNAMIC ;
3627 .interp : { *(.interp) } :text :interp
3628 .text : { *(.text) } :text
3629 .rodata : { *(.rodata) } /* defaults to :text */
3631 . = . + 0x1000; /* move to a new page in memory */
3632 .data : { *(.data) } :data
3633 .dynamic : { *(.dynamic) } :data :dynamic
3638 File: ld.info, Node: VERSION, Next: Expressions, Prev: PHDRS, Up: Scripts
3643 The linker supports symbol versions when using ELF. Symbol versions are
3644 only useful when using shared libraries. The dynamic linker can use
3645 symbol versions to select a specific version of a function when it runs
3646 a program that may have been linked against an earlier version of the
3649 You can include a version script directly in the main linker script,
3650 or you can supply the version script as an implicit linker script. You
3651 can also use the `--version-script' linker option.
3653 The syntax of the `VERSION' command is simply
3654 VERSION { version-script-commands }
3656 The format of the version script commands is identical to that used
3657 by Sun's linker in Solaris 2.5. The version script defines a tree of
3658 version nodes. You specify the node names and interdependencies in the
3659 version script. You can specify which symbols are bound to which
3660 version nodes, and you can reduce a specified set of symbols to local
3661 scope so that they are not globally visible outside of the shared
3664 The easiest way to demonstrate the version script language is with a
3684 "int f(int, double)";
3688 This example version script defines three version nodes. The first
3689 version node defined is `VERS_1.1'; it has no other dependencies. The
3690 script binds the symbol `foo1' to `VERS_1.1'. It reduces a number of
3691 symbols to local scope so that they are not visible outside of the
3692 shared library; this is done using wildcard patterns, so that any
3693 symbol whose name begins with `old', `original', or `new' is matched.
3694 The wildcard patterns available are the same as those used in the shell
3695 when matching filenames (also known as "globbing"). However, if you
3696 specify the symbol name inside double quotes, then the name is treated
3697 as literal, rather than as a glob pattern.
3699 Next, the version script defines node `VERS_1.2'. This node depends
3700 upon `VERS_1.1'. The script binds the symbol `foo2' to the version
3703 Finally, the version script defines node `VERS_2.0'. This node
3704 depends upon `VERS_1.2'. The scripts binds the symbols `bar1' and
3705 `bar2' are bound to the version node `VERS_2.0'.
3707 When the linker finds a symbol defined in a library which is not
3708 specifically bound to a version node, it will effectively bind it to an
3709 unspecified base version of the library. You can bind all otherwise
3710 unspecified symbols to a given version node by using `global: *;'
3711 somewhere in the version script.
3713 The names of the version nodes have no specific meaning other than
3714 what they might suggest to the person reading them. The `2.0' version
3715 could just as well have appeared in between `1.1' and `1.2'. However,
3716 this would be a confusing way to write a version script.
3718 Node name can be omitted, provided it is the only version node in
3719 the version script. Such version script doesn't assign any versions to
3720 symbols, only selects which symbols will be globally visible out and
3723 { global: foo; bar; local: *; };
3725 When you link an application against a shared library that has
3726 versioned symbols, the application itself knows which version of each
3727 symbol it requires, and it also knows which version nodes it needs from
3728 each shared library it is linked against. Thus at runtime, the dynamic
3729 loader can make a quick check to make sure that the libraries you have
3730 linked against do in fact supply all of the version nodes that the
3731 application will need to resolve all of the dynamic symbols. In this
3732 way it is possible for the dynamic linker to know with certainty that
3733 all external symbols that it needs will be resolvable without having to
3734 search for each symbol reference.
3736 The symbol versioning is in effect a much more sophisticated way of
3737 doing minor version checking that SunOS does. The fundamental problem
3738 that is being addressed here is that typically references to external
3739 functions are bound on an as-needed basis, and are not all bound when
3740 the application starts up. If a shared library is out of date, a
3741 required interface may be missing; when the application tries to use
3742 that interface, it may suddenly and unexpectedly fail. With symbol
3743 versioning, the user will get a warning when they start their program if
3744 the libraries being used with the application are too old.
3746 There are several GNU extensions to Sun's versioning approach. The
3747 first of these is the ability to bind a symbol to a version node in the
3748 source file where the symbol is defined instead of in the versioning
3749 script. This was done mainly to reduce the burden on the library
3750 maintainer. You can do this by putting something like:
3751 __asm__(".symver original_foo,foo@VERS_1.1");
3752 in the C source file. This renames the function `original_foo' to
3753 be an alias for `foo' bound to the version node `VERS_1.1'. The
3754 `local:' directive can be used to prevent the symbol `original_foo'
3755 from being exported. A `.symver' directive takes precedence over a
3758 The second GNU extension is to allow multiple versions of the same
3759 function to appear in a given shared library. In this way you can make
3760 an incompatible change to an interface without increasing the major
3761 version number of the shared library, while still allowing applications
3762 linked against the old interface to continue to function.
3764 To do this, you must use multiple `.symver' directives in the source
3765 file. Here is an example:
3767 __asm__(".symver original_foo,foo@");
3768 __asm__(".symver old_foo,foo@VERS_1.1");
3769 __asm__(".symver old_foo1,foo@VERS_1.2");
3770 __asm__(".symver new_foo,foo@@VERS_2.0");
3772 In this example, `foo@' represents the symbol `foo' bound to the
3773 unspecified base version of the symbol. The source file that contains
3774 this example would define 4 C functions: `original_foo', `old_foo',
3775 `old_foo1', and `new_foo'.
3777 When you have multiple definitions of a given symbol, there needs to
3778 be some way to specify a default version to which external references to
3779 this symbol will be bound. You can do this with the `foo@@VERS_2.0'
3780 type of `.symver' directive. You can only declare one version of a
3781 symbol as the default in this manner; otherwise you would effectively
3782 have multiple definitions of the same symbol.
3784 If you wish to bind a reference to a specific version of the symbol
3785 within the shared library, you can use the aliases of convenience
3786 (i.e., `old_foo'), or you can use the `.symver' directive to
3787 specifically bind to an external version of the function in question.
3789 You can also specify the language in the version script:
3791 VERSION extern "lang" { version-script-commands }
3793 The supported `lang's are `C', `C++', and `Java'. The linker will
3794 iterate over the list of symbols at the link time and demangle them
3795 according to `lang' before matching them to the patterns specified in
3796 `version-script-commands'.
3798 Demangled names may contains spaces and other special characters. As
3799 described above, you can use a glob pattern to match demangled names,
3800 or you can use a double-quoted string to match the string exactly. In
3801 the latter case, be aware that minor differences (such as differing
3802 whitespace) between the version script and the demangler output will
3803 cause a mismatch. As the exact string generated by the demangler might
3804 change in the future, even if the mangled name does not, you should
3805 check that all of your version directives are behaving as you expect
3809 File: ld.info, Node: Expressions, Next: Implicit Linker Scripts, Prev: VERSION, Up: Scripts
3811 3.10 Expressions in Linker Scripts
3812 ==================================
3814 The syntax for expressions in the linker script language is identical to
3815 that of C expressions. All expressions are evaluated as integers. All
3816 expressions are evaluated in the same size, which is 32 bits if both the
3817 host and target are 32 bits, and is otherwise 64 bits.
3819 You can use and set symbol values in expressions.
3821 The linker defines several special purpose builtin functions for use
3826 * Constants:: Constants
3827 * Symbols:: Symbol Names
3828 * Orphan Sections:: Orphan Sections
3829 * Location Counter:: The Location Counter
3830 * Operators:: Operators
3831 * Evaluation:: Evaluation
3832 * Expression Section:: The Section of an Expression
3833 * Builtin Functions:: Builtin Functions
3836 File: ld.info, Node: Constants, Next: Symbols, Up: Expressions
3841 All constants are integers.
3843 As in C, the linker considers an integer beginning with `0' to be
3844 octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
3845 The linker considers other integers to be decimal.
3847 In addition, you can use the suffixes `K' and `M' to scale a
3848 constant by `1024' or `1024*1024' respectively. For example, the
3849 following all refer to the same quantity:
3855 File: ld.info, Node: Symbols, Next: Orphan Sections, Prev: Constants, Up: Expressions
3860 Unless quoted, symbol names start with a letter, underscore, or period
3861 and may include letters, digits, underscores, periods, and hyphens.
3862 Unquoted symbol names must not conflict with any keywords. You can
3863 specify a symbol which contains odd characters or has the same name as a
3864 keyword by surrounding the symbol name in double quotes:
3866 "with a space" = "also with a space" + 10;
3868 Since symbols can contain many non-alphabetic characters, it is
3869 safest to delimit symbols with spaces. For example, `A-B' is one
3870 symbol, whereas `A - B' is an expression involving subtraction.
3873 File: ld.info, Node: Orphan Sections, Next: Location Counter, Prev: Symbols, Up: Expressions
3875 3.10.3 Orphan Sections
3876 ----------------------
3878 Orphan sections are sections present in the input files which are not
3879 explicitly placed into the output file by the linker script. The
3880 linker will still copy these sections into the output file, but it has
3881 to guess as to where they should be placed. The linker uses a simple
3882 heuristic to do this. It attempts to place orphan sections after
3883 non-orphan sections of the same attribute, such as code vs data,
3884 loadable vs non-loadable, etc. If there is not enough room to do this
3885 then it places at the end of the file.
3887 For ELF targets, the attribute of the section includes section type
3888 as well as section flag.
3891 File: ld.info, Node: Location Counter, Next: Operators, Prev: Orphan Sections, Up: Expressions
3893 3.10.4 The Location Counter
3894 ---------------------------
3896 The special linker variable "dot" `.' always contains the current
3897 output location counter. Since the `.' always refers to a location in
3898 an output section, it may only appear in an expression within a
3899 `SECTIONS' command. The `.' symbol may appear anywhere that an
3900 ordinary symbol is allowed in an expression.
3902 Assigning a value to `.' will cause the location counter to be
3903 moved. This may be used to create holes in the output section. The
3904 location counter may not be moved backwards inside an output section,
3905 and may not be moved backwards outside of an output section if so doing
3906 creates areas with overlapping LMAs.
3919 In the previous example, the `.text' section from `file1' is located
3920 at the beginning of the output section `output'. It is followed by a
3921 1000 byte gap. Then the `.text' section from `file2' appears, also
3922 with a 1000 byte gap following before the `.text' section from `file3'.
3923 The notation `= 0x12345678' specifies what data to write in the gaps
3924 (*note Output Section Fill::).
3926 Note: `.' actually refers to the byte offset from the start of the
3927 current containing object. Normally this is the `SECTIONS' statement,
3928 whose start address is 0, hence `.' can be used as an absolute address.
3929 If `.' is used inside a section description however, it refers to the
3930 byte offset from the start of that section, not an absolute address.
3931 Thus in a script like this:
3947 The `.text' section will be assigned a starting address of 0x100 and
3948 a size of exactly 0x200 bytes, even if there is not enough data in the
3949 `.text' input sections to fill this area. (If there is too much data,
3950 an error will be produced because this would be an attempt to move `.'
3951 backwards). The `.data' section will start at 0x500 and it will have
3952 an extra 0x600 bytes worth of space after the end of the values from
3953 the `.data' input sections and before the end of the `.data' output
3956 Setting symbols to the value of the location counter outside of an
3957 output section statement can result in unexpected values if the linker
3958 needs to place orphan sections. For example, given the following:
3971 If the linker needs to place some input section, e.g. `.rodata', not
3972 mentioned in the script, it might choose to place that section between
3973 `.text' and `.data'. You might think the linker should place `.rodata'
3974 on the blank line in the above script, but blank lines are of no
3975 particular significance to the linker. As well, the linker doesn't
3976 associate the above symbol names with their sections. Instead, it
3977 assumes that all assignments or other statements belong to the previous
3978 output section, except for the special case of an assignment to `.'.
3979 I.e., the linker will place the orphan `.rodata' section as if the
3980 script was written as follows:
3989 .rodata: { *(.rodata) }
3994 This may or may not be the script author's intention for the value of
3995 `start_of_data'. One way to influence the orphan section placement is
3996 to assign the location counter to itself, as the linker assumes that an
3997 assignment to `.' is setting the start address of a following output
3998 section and thus should be grouped with that section. So you could
4013 Now, the orphan `.rodata' section will be placed between
4014 `end_of_text' and `start_of_data'.
4017 File: ld.info, Node: Operators, Next: Evaluation, Prev: Location Counter, Up: Expressions
4022 The linker recognizes the standard C set of arithmetic operators, with
4023 the standard bindings and precedence levels:
4024 precedence associativity Operators Notes
4030 5 left == != > < <= >=
4036 11 right &= += -= *= /= (2)
4038 Notes: (1) Prefix operators (2) *Note Assignments::.
4041 File: ld.info, Node: Evaluation, Next: Expression Section, Prev: Operators, Up: Expressions
4046 The linker evaluates expressions lazily. It only computes the value of
4047 an expression when absolutely necessary.
4049 The linker needs some information, such as the value of the start
4050 address of the first section, and the origins and lengths of memory
4051 regions, in order to do any linking at all. These values are computed
4052 as soon as possible when the linker reads in the linker script.
4054 However, other values (such as symbol values) are not known or needed
4055 until after storage allocation. Such values are evaluated later, when
4056 other information (such as the sizes of output sections) is available
4057 for use in the symbol assignment expression.
4059 The sizes of sections cannot be known until after allocation, so
4060 assignments dependent upon these are not performed until after
4063 Some expressions, such as those depending upon the location counter
4064 `.', must be evaluated during section allocation.
4066 If the result of an expression is required, but the value is not
4067 available, then an error results. For example, a script like the
4071 .text 9+this_isnt_constant :
4074 will cause the error message `non constant expression for initial
4078 File: ld.info, Node: Expression Section, Next: Builtin Functions, Prev: Evaluation, Up: Expressions
4080 3.10.7 The Section of an Expression
4081 -----------------------------------
4083 When the linker evaluates an expression, the result is either absolute
4084 or relative to some section. A relative expression is expressed as a
4085 fixed offset from the base of a section.
4087 The position of the expression within the linker script determines
4088 whether it is absolute or relative. An expression which appears within
4089 an output section definition is relative to the base of the output
4090 section. An expression which appears elsewhere will be absolute.
4092 A symbol set to a relative expression will be relocatable if you
4093 request relocatable output using the `-r' option. That means that a
4094 further link operation may change the value of the symbol. The symbol's
4095 section will be the section of the relative expression.
4097 A symbol set to an absolute expression will retain the same value
4098 through any further link operation. The symbol will be absolute, and
4099 will not have any particular associated section.
4101 You can use the builtin function `ABSOLUTE' to force an expression
4102 to be absolute when it would otherwise be relative. For example, to
4103 create an absolute symbol set to the address of the end of the output
4107 .data : { *(.data) _edata = ABSOLUTE(.); }
4109 If `ABSOLUTE' were not used, `_edata' would be relative to the
4113 File: ld.info, Node: Builtin Functions, Prev: Expression Section, Up: Expressions
4115 3.10.8 Builtin Functions
4116 ------------------------
4118 The linker script language includes a number of builtin functions for
4119 use in linker script expressions.
4122 Return the absolute (non-relocatable, as opposed to non-negative)
4123 value of the expression EXP. Primarily useful to assign an
4124 absolute value to a symbol within a section definition, where
4125 symbol values are normally section relative. *Note Expression
4129 Return the absolute address (the VMA) of the named SECTION. Your
4130 script must previously have defined the location of that section.
4131 In the following example, `symbol_1' and `symbol_2' are assigned
4136 start_of_output_1 = ABSOLUTE(.);
4141 symbol_1 = ADDR(.output1);
4142 symbol_2 = start_of_output_1;
4148 Return the location counter (`.') or arbitrary expression aligned
4149 to the next ALIGN boundary. The single operand `ALIGN' doesn't
4150 change the value of the location counter--it just does arithmetic
4151 on it. The two operand `ALIGN' allows an arbitrary expression to
4152 be aligned upwards (`ALIGN(ALIGN)' is equivalent to `ALIGN(.,
4155 Here is an example which aligns the output `.data' section to the
4156 next `0x2000' byte boundary after the preceding section and sets a
4157 variable within the section to the next `0x8000' boundary after the
4160 .data ALIGN(0x2000): {
4162 variable = ALIGN(0x8000);
4165 The first use of `ALIGN' in this example specifies the
4166 location of a section because it is used as the optional ADDRESS
4167 attribute of a section definition (*note Output Section
4168 Address::). The second use of `ALIGN' is used to defines the
4171 The builtin function `NEXT' is closely related to `ALIGN'.
4174 Return the alignment in bytes of the named SECTION, if that
4175 section has been allocated. If the section has not been allocated
4176 when this is evaluated, the linker will report an error. In the
4177 following example, the alignment of the `.output' section is
4178 stored as the first value in that section.
4181 LONG (ALIGNOF (.output))
4187 This is a synonym for `ALIGN', for compatibility with older linker
4188 scripts. It is most often seen when setting the address of an
4191 `DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)'
4192 This is equivalent to either
4193 (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1)))
4195 (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE)))
4196 depending on whether the latter uses fewer COMMONPAGESIZE sized
4197 pages for the data segment (area between the result of this
4198 expression and `DATA_SEGMENT_END') than the former or not. If the
4199 latter form is used, it means COMMONPAGESIZE bytes of runtime
4200 memory will be saved at the expense of up to COMMONPAGESIZE wasted
4201 bytes in the on-disk file.
4203 This expression can only be used directly in `SECTIONS' commands,
4204 not in any output section descriptions and only once in the linker
4205 script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and
4206 should be the system page size the object wants to be optimized
4207 for (while still working on system page sizes up to MAXPAGESIZE).
4210 . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
4212 `DATA_SEGMENT_END(EXP)'
4213 This defines the end of data segment for `DATA_SEGMENT_ALIGN'
4214 evaluation purposes.
4216 . = DATA_SEGMENT_END(.);
4218 `DATA_SEGMENT_RELRO_END(OFFSET, EXP)'
4219 This defines the end of the `PT_GNU_RELRO' segment when `-z relro'
4220 option is used. Second argument is returned. When `-z relro'
4221 option is not present, `DATA_SEGMENT_RELRO_END' does nothing,
4222 otherwise `DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is
4223 aligned to the most commonly used page boundary for particular
4224 target. If present in the linker script, it must always come in
4225 between `DATA_SEGMENT_ALIGN' and `DATA_SEGMENT_END'.
4227 . = DATA_SEGMENT_RELRO_END(24, .);
4230 Return 1 if SYMBOL is in the linker global symbol table and is
4231 defined before the statement using DEFINED in the script, otherwise
4232 return 0. You can use this function to provide default values for
4233 symbols. For example, the following script fragment shows how to
4234 set a global symbol `begin' to the first location in the `.text'
4235 section--but if a symbol called `begin' already existed, its value
4240 begin = DEFINED(begin) ? begin : . ;
4247 Return the length of the memory region named MEMORY.
4250 Return the absolute LMA of the named SECTION. This is normally
4251 the same as `ADDR', but it may be different if the `AT' attribute
4252 is used in the output section definition (*note Output Section
4256 Returns the maximum of EXP1 and EXP2.
4259 Returns the minimum of EXP1 and EXP2.
4262 Return the next unallocated address that is a multiple of EXP.
4263 This function is closely related to `ALIGN(EXP)'; unless you use
4264 the `MEMORY' command to define discontinuous memory for the output
4265 file, the two functions are equivalent.
4268 Return the origin of the memory region named MEMORY.
4270 `SEGMENT_START(SEGMENT, DEFAULT)'
4271 Return the base address of the named SEGMENT. If an explicit
4272 value has been given for this segment (with a command-line `-T'
4273 option) that value will be returned; otherwise the value will be
4274 DEFAULT. At present, the `-T' command-line option can only be
4275 used to set the base address for the "text", "data", and "bss"
4276 sections, but you use `SEGMENT_START' with any segment name.
4279 Return the size in bytes of the named SECTION, if that section has
4280 been allocated. If the section has not been allocated when this is
4281 evaluated, the linker will report an error. In the following
4282 example, `symbol_1' and `symbol_2' are assigned identical values:
4289 symbol_1 = .end - .start ;
4290 symbol_2 = SIZEOF(.output);
4295 Return the size in bytes of the output file's headers. This is
4296 information which appears at the start of the output file. You
4297 can use this number when setting the start address of the first
4298 section, if you choose, to facilitate paging.
4300 When producing an ELF output file, if the linker script uses the
4301 `SIZEOF_HEADERS' builtin function, the linker must compute the
4302 number of program headers before it has determined all the section
4303 addresses and sizes. If the linker later discovers that it needs
4304 additional program headers, it will report an error `not enough
4305 room for program headers'. To avoid this error, you must avoid
4306 using the `SIZEOF_HEADERS' function, or you must rework your linker
4307 script to avoid forcing the linker to use additional program
4308 headers, or you must define the program headers yourself using the
4309 `PHDRS' command (*note PHDRS::).
4312 File: ld.info, Node: Implicit Linker Scripts, Prev: Expressions, Up: Scripts
4314 3.11 Implicit Linker Scripts
4315 ============================
4317 If you specify a linker input file which the linker can not recognize as
4318 an object file or an archive file, it will try to read the file as a
4319 linker script. If the file can not be parsed as a linker script, the
4320 linker will report an error.
4322 An implicit linker script will not replace the default linker script.
4324 Typically an implicit linker script would contain only symbol
4325 assignments, or the `INPUT', `GROUP', or `VERSION' commands.
4327 Any input files read because of an implicit linker script will be
4328 read at the position in the command line where the implicit linker
4329 script was read. This can affect archive searching.
4332 File: ld.info, Node: Machine Dependent, Next: BFD, Prev: Scripts, Up: Top
4334 4 Machine Dependent Features
4335 ****************************
4337 `ld' has additional features on some platforms; the following sections
4338 describe them. Machines where `ld' has no additional functionality are
4344 * H8/300:: `ld' and the H8/300
4346 * i960:: `ld' and the Intel 960 family
4348 * ARM:: `ld' and the ARM family
4350 * HPPA ELF32:: `ld' and HPPA 32-bit ELF
4352 * MMIX:: `ld' and MMIX
4354 * MSP430:: `ld' and MSP430
4356 * M68HC11/68HC12:: `ld' and the Motorola 68HC11 and 68HC12 families
4358 * PowerPC ELF32:: `ld' and PowerPC 32-bit ELF Support
4360 * PowerPC64 ELF64:: `ld' and PowerPC64 64-bit ELF Support
4362 * SPU ELF:: `ld' and SPU ELF Support
4364 * TI COFF:: `ld' and TI COFF
4366 * WIN32:: `ld' and WIN32 (cygwin/mingw)
4368 * Xtensa:: `ld' and Xtensa Processors
4371 File: ld.info, Node: H8/300, Next: i960, Up: Machine Dependent
4373 4.1 `ld' and the H8/300
4374 =======================
4376 For the H8/300, `ld' can perform these global optimizations when you
4377 specify the `--relax' command-line option.
4379 _relaxing address modes_
4380 `ld' finds all `jsr' and `jmp' instructions whose targets are
4381 within eight bits, and turns them into eight-bit program-counter
4382 relative `bsr' and `bra' instructions, respectively.
4384 _synthesizing instructions_
4385 `ld' finds all `mov.b' instructions which use the sixteen-bit
4386 absolute address form, but refer to the top page of memory, and
4387 changes them to use the eight-bit address form. (That is: the
4388 linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
4389 address AA is in the top page of memory).
4391 _bit manipulation instructions_
4392 `ld' finds all bit manipulation instructions like `band, bclr,
4393 biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst,
4394 bxor' which use 32 bit and 16 bit absolute address form, but refer
4395 to the top page of memory, and changes them to use the 8 bit
4396 address form. (That is: the linker turns `bset #xx:3,`@'AA:32'
4397 into `bset #xx:3,`@'AA:8' whenever the address AA is in the top
4400 _system control instructions_
4401 `ld' finds all `ldc.w, stc.w' instructions which use the 32 bit
4402 absolute address form, but refer to the top page of memory, and
4403 changes them to use 16 bit address form. (That is: the linker
4404 turns `ldc.w `@'AA:32,ccr' into `ldc.w `@'AA:16,ccr' whenever the
4405 address AA is in the top page of memory).
4408 File: ld.info, Node: i960, Next: ARM, Prev: H8/300, Up: Machine Dependent
4410 4.2 `ld' and the Intel 960 Family
4411 =================================
4413 You can use the `-AARCHITECTURE' command line option to specify one of
4414 the two-letter names identifying members of the 960 family; the option
4415 specifies the desired output target, and warns of any incompatible
4416 instructions in the input files. It also modifies the linker's search
4417 strategy for archive libraries, to support the use of libraries
4418 specific to each particular architecture, by including in the search
4419 loop names suffixed with the string identifying the architecture.
4421 For example, if your `ld' command line included `-ACA' as well as
4422 `-ltry', the linker would look (in its built-in search paths, and in
4423 any paths you specify with `-L') for a library with the names
4430 The first two possibilities would be considered in any event; the last
4431 two are due to the use of `-ACA'.
4433 You can meaningfully use `-A' more than once on a command line, since
4434 the 960 architecture family allows combination of target architectures;
4435 each use will add another pair of name variants to search for when `-l'
4436 specifies a library.
4438 `ld' supports the `--relax' option for the i960 family. If you
4439 specify `--relax', `ld' finds all `balx' and `calx' instructions whose
4440 targets are within 24 bits, and turns them into 24-bit program-counter
4441 relative `bal' and `cal' instructions, respectively. `ld' also turns
4442 `cal' instructions into `bal' instructions when it determines that the
4443 target subroutine is a leaf routine (that is, the target subroutine does
4444 not itself call any subroutines).
4447 File: ld.info, Node: M68HC11/68HC12, Next: PowerPC ELF32, Prev: MSP430, Up: Machine Dependent
4449 4.3 `ld' and the Motorola 68HC11 and 68HC12 families
4450 ====================================================
4452 4.3.1 Linker Relaxation
4453 -----------------------
4455 For the Motorola 68HC11, `ld' can perform these global optimizations
4456 when you specify the `--relax' command-line option.
4458 _relaxing address modes_
4459 `ld' finds all `jsr' and `jmp' instructions whose targets are
4460 within eight bits, and turns them into eight-bit program-counter
4461 relative `bsr' and `bra' instructions, respectively.
4463 `ld' also looks at all 16-bit extended addressing modes and
4464 transforms them in a direct addressing mode when the address is in
4465 page 0 (between 0 and 0x0ff).
4467 _relaxing gcc instruction group_
4468 When `gcc' is called with `-mrelax', it can emit group of
4469 instructions that the linker can optimize to use a 68HC11 direct
4470 addressing mode. These instructions consists of `bclr' or `bset'
4474 4.3.2 Trampoline Generation
4475 ---------------------------
4477 For 68HC11 and 68HC12, `ld' can generate trampoline code to call a far
4478 function using a normal `jsr' instruction. The linker will also change
4479 the relocation to some far function to use the trampoline address
4480 instead of the function address. This is typically the case when a
4481 pointer to a function is taken. The pointer will in fact point to the
4482 function trampoline.
4484 The `--pic-veneer' switch makes the linker use PIC sequences for
4485 ARM/Thumb interworking veneers, even if the rest of the binary is not
4486 PIC. This avoids problems on uClinux targets where `--emit-relocs' is
4487 used to generate relocatable binaries.
4490 File: ld.info, Node: ARM, Next: HPPA ELF32, Prev: i960, Up: Machine Dependent
4492 4.4 `ld' and the ARM family
4493 ===========================
4495 For the ARM, `ld' will generate code stubs to allow functions calls
4496 between ARM and Thumb code. These stubs only work with code that has
4497 been compiled and assembled with the `-mthumb-interwork' command line
4498 option. If it is necessary to link with old ARM object files or
4499 libraries, which have not been compiled with the -mthumb-interwork
4500 option then the `--support-old-code' command line switch should be
4501 given to the linker. This will make it generate larger stub functions
4502 which will work with non-interworking aware ARM code. Note, however,
4503 the linker does not support generating stubs for function calls to
4504 non-interworking aware Thumb code.
4506 The `--thumb-entry' switch is a duplicate of the generic `--entry'
4507 switch, in that it sets the program's starting address. But it also
4508 sets the bottom bit of the address, so that it can be branched to using
4509 a BX instruction, and the program will start executing in Thumb mode
4512 The `--be8' switch instructs `ld' to generate BE8 format
4513 executables. This option is only valid when linking big-endian objects.
4514 The resulting image will contain big-endian data and little-endian code.
4516 The `R_ARM_TARGET1' relocation is typically used for entries in the
4517 `.init_array' section. It is interpreted as either `R_ARM_REL32' or
4518 `R_ARM_ABS32', depending on the target. The `--target1-rel' and
4519 `--target1-abs' switches override the default.
4521 The `--target2=type' switch overrides the default definition of the
4522 `R_ARM_TARGET2' relocation. Valid values for `type', their meanings,
4523 and target defaults are as follows:
4525 `R_ARM_REL32' (arm*-*-elf, arm*-*-eabi)
4528 `R_ARM_ABS32' (arm*-*-symbianelf)
4531 `R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd)
4533 The `R_ARM_V4BX' relocation (defined by the ARM AAELF specification)
4534 enables objects compiled for the ARMv4 architecture to be
4535 interworking-safe when linked with other objects compiled for ARMv4t,
4536 but also allows pure ARMv4 binaries to be built from the same ARMv4
4539 In the latter case, the switch `--fix-v4bx' must be passed to the
4540 linker, which causes v4t `BX rM' instructions to be rewritten as `MOV
4541 PC,rM', since v4 processors do not have a `BX' instruction.
4543 In the former case, the switch should not be used, and `R_ARM_V4BX'
4544 relocations are ignored.
4546 The `--use-blx' switch enables the linker to use ARM/Thumb BLX
4547 instructions (available on ARMv5t and above) in various situations.
4548 Currently it is used to perform calls via the PLT from Thumb code using
4549 BLX rather than using BX and a mode-switching stub before each PLT
4550 entry. This should lead to such calls executing slightly faster.
4552 This option is enabled implicitly for SymbianOS, so there is no need
4553 to specify it if you are using that target.
4555 The `--vfp11-denorm-fix' switch enables a link-time workaround for a
4556 bug in certain VFP11 coprocessor hardware, which sometimes allows
4557 instructions with denorm operands (which must be handled by support
4558 code) to have those operands overwritten by subsequent instructions
4559 before the support code can read the intended values.
4561 The bug may be avoided in scalar mode if you allow at least one
4562 intervening instruction between a VFP11 instruction which uses a
4563 register and another instruction which writes to the same register, or
4564 at least two intervening instructions if vector mode is in use. The bug
4565 only affects full-compliance floating-point mode: you do not need this
4566 workaround if you are using "runfast" mode. Please contact ARM for
4569 If you know you are using buggy VFP11 hardware, you can enable this
4570 workaround by specifying the linker option `--vfp-denorm-fix=scalar' if
4571 you are using the VFP11 scalar mode only, or `--vfp-denorm-fix=vector'
4572 if you are using vector mode (the latter also works for scalar code).
4573 The default is `--vfp-denorm-fix=none'.
4575 If the workaround is enabled, instructions are scanned for
4576 potentially-troublesome sequences, and a veneer is created for each
4577 such sequence which may trigger the erratum. The veneer consists of the
4578 first instruction of the sequence and a branch back to the subsequent
4579 instruction. The original instruction is then replaced with a branch to
4580 the veneer. The extra cycles required to call and return from the veneer
4581 are sufficient to avoid the erratum in both the scalar and vector cases.
4583 The `--no-enum-size-warning' switch prevents the linker from warning
4584 when linking object files that specify incompatible EABI enumeration
4585 size attributes. For example, with this switch enabled, linking of an
4586 object file using 32-bit enumeration values with another using
4587 enumeration values fitted into the smallest possible space will not be
4591 File: ld.info, Node: HPPA ELF32, Next: MMIX, Prev: ARM, Up: Machine Dependent
4593 4.5 `ld' and HPPA 32-bit ELF Support
4594 ====================================
4596 When generating a shared library, `ld' will by default generate import
4597 stubs suitable for use with a single sub-space application. The
4598 `--multi-subspace' switch causes `ld' to generate export stubs, and
4599 different (larger) import stubs suitable for use with multiple
4602 Long branch stubs and import/export stubs are placed by `ld' in stub
4603 sections located between groups of input sections. `--stub-group-size'
4604 specifies the maximum size of a group of input sections handled by one
4605 stub section. Since branch offsets are signed, a stub section may
4606 serve two groups of input sections, one group before the stub section,
4607 and one group after it. However, when using conditional branches that
4608 require stubs, it may be better (for branch prediction) that stub
4609 sections only serve one group of input sections. A negative value for
4610 `N' chooses this scheme, ensuring that branches to stubs always use a
4611 negative offset. Two special values of `N' are recognized, `1' and
4612 `-1'. These both instruct `ld' to automatically size input section
4613 groups for the branch types detected, with the same behaviour regarding
4614 stub placement as other positive or negative values of `N' respectively.
4616 Note that `--stub-group-size' does not split input sections. A
4617 single input section larger than the group size specified will of course
4618 create a larger group (of one section). If input sections are too
4619 large, it may not be possible for a branch to reach its stub.
4622 File: ld.info, Node: MMIX, Next: MSP430, Prev: HPPA ELF32, Up: Machine Dependent
4627 For MMIX, there is a choice of generating `ELF' object files or `mmo'
4628 object files when linking. The simulator `mmix' understands the `mmo'
4629 format. The binutils `objcopy' utility can translate between the two
4632 There is one special section, the `.MMIX.reg_contents' section.
4633 Contents in this section is assumed to correspond to that of global
4634 registers, and symbols referring to it are translated to special
4635 symbols, equal to registers. In a final link, the start address of the
4636 `.MMIX.reg_contents' section corresponds to the first allocated global
4637 register multiplied by 8. Register `$255' is not included in this
4638 section; it is always set to the program entry, which is at the symbol
4639 `Main' for `mmo' files.
4641 Symbols with the prefix `__.MMIX.start.', for example
4642 `__.MMIX.start..text' and `__.MMIX.start..data' are special; there must
4643 be only one each, even if they are local. The default linker script
4644 uses these to set the default start address of a section.
4646 Initial and trailing multiples of zero-valued 32-bit words in a
4647 section, are left out from an mmo file.
4650 File: ld.info, Node: MSP430, Next: M68HC11/68HC12, Prev: MMIX, Up: Machine Dependent
4655 For the MSP430 it is possible to select the MPU architecture. The flag
4656 `-m [mpu type]' will select an appropriate linker script for selected
4657 MPU type. (To get a list of known MPUs just pass `-m help' option to
4660 The linker will recognize some extra sections which are MSP430
4664 Defines a portion of ROM where interrupt vectors located.
4667 Defines the bootloader portion of the ROM (if applicable). Any
4668 code in this section will be uploaded to the MPU.
4671 Defines an information memory section (if applicable). Any code in
4672 this section will be uploaded to the MPU.
4675 This is the same as the `.infomem' section except that any code in
4676 this section will not be uploaded to the MPU.
4679 Denotes a portion of RAM located above `.bss' section.
4681 The last two sections are used by gcc.
4684 File: ld.info, Node: PowerPC ELF32, Next: PowerPC64 ELF64, Prev: M68HC11/68HC12, Up: Machine Dependent
4686 4.8 `ld' and PowerPC 32-bit ELF Support
4687 =======================================
4689 Branches on PowerPC processors are limited to a signed 26-bit
4690 displacement, which may result in `ld' giving `relocation truncated to
4691 fit' errors with very large programs. `--relax' enables the generation
4692 of trampolines that can access the entire 32-bit address space. These
4693 trampolines are inserted at section boundaries, so may not themselves
4694 be reachable if an input section exceeds 33M in size.
4697 Current PowerPC GCC accepts a `-msecure-plt' option that generates
4698 code capable of using a newer PLT and GOT layout that has the
4699 security advantage of no executable section ever needing to be
4700 writable and no writable section ever being executable. PowerPC
4701 `ld' will generate this layout, including stubs to access the PLT,
4702 if all input files (including startup and static libraries) were
4703 compiled with `-msecure-plt'. `--bss-plt' forces the old BSS PLT
4704 (and GOT layout) which can give slightly better performance.
4707 `ld' will use the new PLT and GOT layout if it is linking new
4708 `-fpic' or `-fPIC' code, but does not do so automatically when
4709 linking non-PIC code. This option requests the new PLT and GOT
4710 layout. A warning will be given if some object file requires the
4714 The new secure PLT and GOT are placed differently relative to other
4715 sections compared to older BSS PLT and GOT placement. The
4716 location of `.plt' must change because the new secure PLT is an
4717 initialized section while the old PLT is uninitialized. The
4718 reason for the `.got' change is more subtle: The new placement
4719 allows `.got' to be read-only in applications linked with `-z
4720 relro -z now'. However, this placement means that `.sdata' cannot
4721 always be used in shared libraries, because the PowerPC ABI
4722 accesses `.sdata' in shared libraries from the GOT pointer.
4723 `--sdata-got' forces the old GOT placement. PowerPC GCC doesn't
4724 use `.sdata' in shared libraries, so this option is really only
4725 useful for other compilers that may do so.
4728 This option causes `ld' to label linker stubs with a local symbol
4729 that encodes the stub type and destination.
4732 PowerPC `ld' normally performs some optimization of code sequences
4733 used to access Thread-Local Storage. Use this option to disable
4737 File: ld.info, Node: PowerPC64 ELF64, Next: SPU ELF, Prev: PowerPC ELF32, Up: Machine Dependent
4739 4.9 `ld' and PowerPC64 64-bit ELF Support
4740 =========================================
4743 Long branch stubs, PLT call stubs and TOC adjusting stubs are
4744 placed by `ld' in stub sections located between groups of input
4745 sections. `--stub-group-size' specifies the maximum size of a
4746 group of input sections handled by one stub section. Since branch
4747 offsets are signed, a stub section may serve two groups of input
4748 sections, one group before the stub section, and one group after
4749 it. However, when using conditional branches that require stubs,
4750 it may be better (for branch prediction) that stub sections only
4751 serve one group of input sections. A negative value for `N'
4752 chooses this scheme, ensuring that branches to stubs always use a
4753 negative offset. Two special values of `N' are recognized, `1'
4754 and `-1'. These both instruct `ld' to automatically size input
4755 section groups for the branch types detected, with the same
4756 behaviour regarding stub placement as other positive or negative
4757 values of `N' respectively.
4759 Note that `--stub-group-size' does not split input sections. A
4760 single input section larger than the group size specified will of
4761 course create a larger group (of one section). If input sections
4762 are too large, it may not be possible for a branch to reach its
4766 This option causes `ld' to label linker stubs with a local symbol
4767 that encodes the stub type and destination.
4769 `--dotsyms, --no-dotsyms'
4770 These two options control how `ld' interprets version patterns in
4771 a version script. Older PowerPC64 compilers emitted both a
4772 function descriptor symbol with the same name as the function, and
4773 a code entry symbol with the name prefixed by a dot (`.'). To
4774 properly version a function `foo', the version script thus needs
4775 to control both `foo' and `.foo'. The option `--dotsyms', on by
4776 default, automatically adds the required dot-prefixed patterns.
4777 Use `--no-dotsyms' to disable this feature.
4780 PowerPC64 `ld' normally performs some optimization of code
4781 sequences used to access Thread-Local Storage. Use this option to
4782 disable the optimization.
4785 PowerPC64 `ld' normally removes `.opd' section entries
4786 corresponding to deleted link-once functions, or functions removed
4787 by the action of `--gc-sections' or linker scrip `/DISCARD/'. Use
4788 this option to disable `.opd' optimization.
4790 `--non-overlapping-opd'
4791 Some PowerPC64 compilers have an option to generate compressed
4792 `.opd' entries spaced 16 bytes apart, overlapping the third word,
4793 the static chain pointer (unused in C) with the first word of the
4794 next entry. This option expands such entries to the full 24 bytes.
4797 PowerPC64 `ld' normally removes unused `.toc' section entries.
4798 Such entries are detected by examining relocations that reference
4799 the TOC in code sections. A reloc in a deleted code section marks
4800 a TOC word as unneeded, while a reloc in a kept code section marks
4801 a TOC word as needed. Since the TOC may reference itself, TOC
4802 relocs are also examined. TOC words marked as both needed and
4803 unneeded will of course be kept. TOC words without any referencing
4804 reloc are assumed to be part of a multi-word entry, and are kept or
4805 discarded as per the nearest marked preceding word. This works
4806 reliably for compiler generated code, but may be incorrect if
4807 assembly code is used to insert TOC entries. Use this option to
4808 disable the optimization.
4811 By default, PowerPC64 GCC generates code for a TOC model where TOC
4812 entries are accessed with a 16-bit offset from r2. This limits the
4813 total TOC size to 64K. PowerPC64 `ld' extends this limit by
4814 grouping code sections such that each group uses less than 64K for
4815 its TOC entries, then inserts r2 adjusting stubs between
4816 inter-group calls. `ld' does not split apart input sections, so
4817 cannot help if a single input file has a `.toc' section that
4818 exceeds 64K, most likely from linking multiple files with `ld -r'.
4819 Use this option to turn off this feature.
4822 File: ld.info, Node: SPU ELF, Next: TI COFF, Prev: PowerPC64 ELF64, Up: Machine Dependent
4824 4.10 `ld' and SPU ELF Support
4825 =============================
4828 This option marks an executable as a PIC plugin module.
4831 Normally, `ld' recognizes calls to functions within overlay
4832 regions, and redirects such calls to an overlay manager via a stub.
4833 `ld' also provides a built-in overlay manager. This option turns
4834 off all this special overlay handling.
4837 This option causes `ld' to label overlay stubs with a local symbol
4838 that encodes the stub type and destination.
4840 `--extra-overlay-stubs'
4841 This option causes `ld' to add overlay call stubs on all function
4842 calls out of overlay regions. Normally stubs are not added on
4843 calls to non-overlay regions.
4845 `--local-store=lo:hi'
4846 `ld' usually checks that a final executable for SPU fits in the
4847 address range 0 to 256k. This option may be used to change the
4848 range. Disable the check entirely with `--local-store=0:0'.
4851 SPU local store space is limited. Over-allocation of stack space
4852 unnecessarily limits space available for code and data, while
4853 under-allocation results in runtime failures. If given this
4854 option, `ld' will provide an estimate of maximum stack usage.
4855 `ld' does this by examining symbols in code sections to determine
4856 the extents of functions, and looking at function prologues for
4857 stack adjusting instructions. A call-graph is created by looking
4858 for relocations on branch instructions. The graph is then searched
4859 for the maximum stack usage path. Note that this analysis does not
4860 find calls made via function pointers, and does not handle
4861 recursion and other cycles in the call graph. Stack usage may be
4862 under-estimated if your code makes such calls. Also, stack usage
4863 for dynamic allocation, e.g. alloca, will not be detected. If a
4864 link map is requested, detailed information about each function's
4865 stack usage and calls will be given.
4868 This option, if given along with `--stack-analysis' will result in
4869 `ld' emitting stack sizing symbols for each function. These take
4870 the form `__stack_<function_name>' for global functions, and
4871 `__stack_<number>_<function_name>' for static functions.
4872 `<number>' is the section id in hex. The value of such symbols is
4873 the stack requirement for the corresponding function. The symbol
4874 size will be zero, type `STT_NOTYPE', binding `STB_LOCAL', and
4878 File: ld.info, Node: TI COFF, Next: WIN32, Prev: SPU ELF, Up: Machine Dependent
4880 4.11 `ld''s Support for Various TI COFF Versions
4881 ================================================
4883 The `--format' switch allows selection of one of the various TI COFF
4884 versions. The latest of this writing is 2; versions 0 and 1 are also
4885 supported. The TI COFF versions also vary in header byte-order format;
4886 `ld' will read any version or byte order, but the output header format
4887 depends on the default specified by the specific target.
4890 File: ld.info, Node: WIN32, Next: Xtensa, Prev: TI COFF, Up: Machine Dependent
4892 4.12 `ld' and WIN32 (cygwin/mingw)
4893 ==================================
4895 This section describes some of the win32 specific `ld' issues. See
4896 *Note Command Line Options: Options. for detailed description of the
4897 command line options mentioned here.
4900 The standard Windows linker creates and uses so-called import
4901 libraries, which contains information for linking to dll's. They
4902 are regular static archives and are handled as any other static
4903 archive. The cygwin and mingw ports of `ld' have specific support
4904 for creating such libraries provided with the `--out-implib'
4905 command line option.
4907 _exporting DLL symbols_
4908 The cygwin/mingw `ld' has several ways to export symbols for dll's.
4910 _using auto-export functionality_
4911 By default `ld' exports symbols with the auto-export
4912 functionality, which is controlled by the following command
4915 * -export-all-symbols [This is the default]
4921 If, however, `--export-all-symbols' is not given explicitly
4922 on the command line, then the default auto-export behavior
4923 will be _disabled_ if either of the following are true:
4925 * A DEF file is used.
4927 * Any symbol in any object file was marked with the
4928 __declspec(dllexport) attribute.
4931 Another way of exporting symbols is using a DEF file. A DEF
4932 file is an ASCII file containing definitions of symbols which
4933 should be exported when a dll is created. Usually it is
4934 named `<dll name>.def' and is added as any other object file
4935 to the linker's command line. The file's name must end in
4938 gcc -o <output> <objectfiles> <dll name>.def
4940 Using a DEF file turns off the normal auto-export behavior,
4941 unless the `--export-all-symbols' option is also used.
4943 Here is an example of a DEF file for a shared library called
4946 LIBRARY "xyz.dll" BASE=0x20000000
4952 another_foo = abc.dll.afoo
4955 This example defines a DLL with a non-default base address
4956 and five symbols in the export table. The third exported
4957 symbol `_bar' is an alias for the second. The fourth symbol,
4958 `another_foo' is resolved by "forwarding" to another module
4959 and treating it as an alias for `afoo' exported from the DLL
4960 `abc.dll'. The final symbol `var1' is declared to be a data
4963 The optional `LIBRARY <name>' command indicates the _internal_
4964 name of the output DLL. If `<name>' does not include a suffix,
4965 the default library suffix, `.DLL' is appended.
4967 When the .DEF file is used to build an application, rather
4968 than a library, the `NAME <name>' command should be used
4969 instead of `LIBRARY'. If `<name>' does not include a suffix,
4970 the default executable suffix, `.EXE' is appended.
4972 With either `LIBRARY <name>' or `NAME <name>' the optional
4973 specification `BASE = <number>' may be used to specify a
4974 non-default base address for the image.
4976 If neither `LIBRARY <name>' nor `NAME <name>' is specified,
4977 or they specify an empty string, the internal name is the
4978 same as the filename specified on the command line.
4980 The complete specification of an export symbol is:
4983 ( ( ( <name1> [ = <name2> ] )
4984 | ( <name1> = <module-name> . <external-name>))
4985 [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
4987 Declares `<name1>' as an exported symbol from the DLL, or
4988 declares `<name1>' as an exported alias for `<name2>'; or
4989 declares `<name1>' as a "forward" alias for the symbol
4990 `<external-name>' in the DLL `<module-name>'. Optionally,
4991 the symbol may be exported by the specified ordinal
4994 The optional keywords that follow the declaration indicate:
4996 `NONAME': Do not put the symbol name in the DLL's export
4997 table. It will still be exported by its ordinal alias
4998 (either the value specified by the .def specification or,
4999 otherwise, the value assigned by the linker). The symbol
5000 name, however, does remain visible in the import library (if
5001 any), unless `PRIVATE' is also specified.
5003 `DATA': The symbol is a variable or object, rather than a
5004 function. The import lib will export only an indirect
5005 reference to `foo' as the symbol `_imp__foo' (ie, `foo' must
5006 be resolved as `*_imp__foo').
5008 `CONSTANT': Like `DATA', but put the undecorated `foo' as
5009 well as `_imp__foo' into the import library. Both refer to the
5010 read-only import address table's pointer to the variable, not
5011 to the variable itself. This can be dangerous. If the user
5012 code fails to add the `dllimport' attribute and also fails to
5013 explicitly add the extra indirection that the use of the
5014 attribute enforces, the application will behave unexpectedly.
5016 `PRIVATE': Put the symbol in the DLL's export table, but do
5017 not put it into the static import library used to resolve
5018 imports at link time. The symbol can still be imported using
5019 the `LoadLibrary/GetProcAddress' API at runtime or by by
5020 using the GNU ld extension of linking directly to the DLL
5021 without an import library.
5023 See ld/deffilep.y in the binutils sources for the full
5024 specification of other DEF file statements
5026 While linking a shared dll, `ld' is able to create a DEF file
5027 with the `--output-def <file>' command line option.
5030 Another way of marking symbols for export is to modify the
5031 source code itself, so that when building the DLL each symbol
5032 to be exported is declared as:
5034 __declspec(dllexport) int a_variable
5035 __declspec(dllexport) void a_function(int with_args)
5037 All such symbols will be exported from the DLL. If, however,
5038 any of the object files in the DLL contain symbols decorated
5039 in this way, then the normal auto-export behavior is
5040 disabled, unless the `--export-all-symbols' option is also
5043 Note that object files that wish to access these symbols must
5044 _not_ decorate them with dllexport. Instead, they should use
5047 __declspec(dllimport) int a_variable
5048 __declspec(dllimport) void a_function(int with_args)
5050 This complicates the structure of library header files,
5051 because when included by the library itself the header must
5052 declare the variables and functions as dllexport, but when
5053 included by client code the header must declare them as
5054 dllimport. There are a number of idioms that are typically
5055 used to do this; often client code can omit the __declspec()
5056 declaration completely. See `--enable-auto-import' and
5057 `automatic data imports' for more information.
5059 _automatic data imports_
5060 The standard Windows dll format supports data imports from dlls
5061 only by adding special decorations (dllimport/dllexport), which
5062 let the compiler produce specific assembler instructions to deal
5063 with this issue. This increases the effort necessary to port
5064 existing Un*x code to these platforms, especially for large c++
5065 libraries and applications. The auto-import feature, which was
5066 initially provided by Paul Sokolovsky, allows one to omit the
5067 decorations to achieve a behavior that conforms to that on
5068 POSIX/Un*x platforms. This feature is enabled with the
5069 `--enable-auto-import' command-line option, although it is enabled
5070 by default on cygwin/mingw. The `--enable-auto-import' option
5071 itself now serves mainly to suppress any warnings that are
5072 ordinarily emitted when linked objects trigger the feature's use.
5074 auto-import of variables does not always work flawlessly without
5075 additional assistance. Sometimes, you will see this message
5077 "variable '<var>' can't be auto-imported. Please read the
5078 documentation for ld's `--enable-auto-import' for details."
5080 The `--enable-auto-import' documentation explains why this error
5081 occurs, and several methods that can be used to overcome this
5082 difficulty. One of these methods is the _runtime pseudo-relocs_
5083 feature, described below.
5085 For complex variables imported from DLLs (such as structs or
5086 classes), object files typically contain a base address for the
5087 variable and an offset (_addend_) within the variable-to specify a
5088 particular field or public member, for instance. Unfortunately,
5089 the runtime loader used in win32 environments is incapable of
5090 fixing these references at runtime without the additional
5091 information supplied by dllimport/dllexport decorations. The
5092 standard auto-import feature described above is unable to resolve
5095 The `--enable-runtime-pseudo-relocs' switch allows these
5096 references to be resolved without error, while leaving the task of
5097 adjusting the references themselves (with their non-zero addends)
5098 to specialized code provided by the runtime environment. Recent
5099 versions of the cygwin and mingw environments and compilers
5100 provide this runtime support; older versions do not. However, the
5101 support is only necessary on the developer's platform; the
5102 compiled result will run without error on an older system.
5104 `--enable-runtime-pseudo-relocs' is not the default; it must be
5105 explicitly enabled as needed.
5107 _direct linking to a dll_
5108 The cygwin/mingw ports of `ld' support the direct linking,
5109 including data symbols, to a dll without the usage of any import
5110 libraries. This is much faster and uses much less memory than
5111 does the traditional import library method, especially when
5112 linking large libraries or applications. When `ld' creates an
5113 import lib, each function or variable exported from the dll is
5114 stored in its own bfd, even though a single bfd could contain many
5115 exports. The overhead involved in storing, loading, and
5116 processing so many bfd's is quite large, and explains the
5117 tremendous time, memory, and storage needed to link against
5118 particularly large or complex libraries when using import libs.
5120 Linking directly to a dll uses no extra command-line switches
5121 other than `-L' and `-l', because `ld' already searches for a
5122 number of names to match each library. All that is needed from
5123 the developer's perspective is an understanding of this search, in
5124 order to force ld to select the dll instead of an import library.
5126 For instance, when ld is called with the argument `-lxxx' it will
5127 attempt to find, in the first directory of its search path,
5137 before moving on to the next directory in the search path.
5139 (*) Actually, this is not `cygxxx.dll' but in fact is
5140 `<prefix>xxx.dll', where `<prefix>' is set by the `ld' option
5141 `--dll-search-prefix=<prefix>'. In the case of cygwin, the
5142 standard gcc spec file includes `--dll-search-prefix=cyg', so in
5143 effect we actually search for `cygxxx.dll'.
5145 Other win32-based unix environments, such as mingw or pw32, may
5146 use other `<prefix>'es, although at present only cygwin makes use
5147 of this feature. It was originally intended to help avoid name
5148 conflicts among dll's built for the various win32/un*x
5149 environments, so that (for example) two versions of a zlib dll
5150 could coexist on the same machine.
5152 The generic cygwin/mingw path layout uses a `bin' directory for
5153 applications and dll's and a `lib' directory for the import
5154 libraries (using cygwin nomenclature):
5159 libxxx.dll.a (in case of dll's)
5160 libxxx.a (in case of static archive)
5162 Linking directly to a dll without using the import library can be
5165 1. Use the dll directly by adding the `bin' path to the link line
5166 gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
5168 However, as the dll's often have version numbers appended to their
5169 names (`cygncurses-5.dll') this will often fail, unless one
5170 specifies `-L../bin -lncurses-5' to include the version. Import
5171 libs are generally not versioned, and do not have this difficulty.
5173 2. Create a symbolic link from the dll to a file in the `lib'
5174 directory according to the above mentioned search pattern. This
5175 should be used to avoid unwanted changes in the tools needed for
5178 ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
5180 Then you can link without any make environment changes.
5182 gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
5184 This technique also avoids the version number problems, because
5185 the following is perfectly legal
5190 libxxx.dll.a -> ../bin/cygxxx-5.dll
5192 Linking directly to a dll without using an import lib will work
5193 even when auto-import features are exercised, and even when
5194 `--enable-runtime-pseudo-relocs' is used.
5196 Given the improvements in speed and memory usage, one might
5197 justifiably wonder why import libraries are used at all. There
5200 1. Until recently, the link-directly-to-dll functionality did _not_
5201 work with auto-imported data.
5203 2. Sometimes it is necessary to include pure static objects within
5204 the import library (which otherwise contains only bfd's for
5205 indirection symbols that point to the exports of a dll). Again,
5206 the import lib for the cygwin kernel makes use of this ability,
5207 and it is not possible to do this without an import lib.
5209 3. Symbol aliases can only be resolved using an import lib. This
5210 is critical when linking against OS-supplied dll's (eg, the win32
5211 API) in which symbols are usually exported as undecorated aliases
5212 of their stdcall-decorated assembly names.
5214 So, import libs are not going away. But the ability to replace
5215 true import libs with a simple symbolic link to (or a copy of) a
5216 dll, in many cases, is a useful addition to the suite of tools
5217 binutils makes available to the win32 developer. Given the
5218 massive improvements in memory requirements during linking, storage
5219 requirements, and linking speed, we expect that many developers
5220 will soon begin to use this feature whenever possible.
5224 _adding additional names_
5225 Sometimes, it is useful to export symbols with additional
5226 names. A symbol `foo' will be exported as `foo', but it can
5227 also be exported as `_foo' by using special directives in the
5228 DEF file when creating the dll. This will affect also the
5229 optional created import library. Consider the following DEF
5232 LIBRARY "xyz.dll" BASE=0x61000000
5238 The line `_foo = foo' maps the symbol `foo' to `_foo'.
5240 Another method for creating a symbol alias is to create it in
5241 the source code using the "weak" attribute:
5243 void foo () { /* Do something. */; }
5244 void _foo () __attribute__ ((weak, alias ("foo")));
5246 See the gcc manual for more information about attributes and
5250 Sometimes it is useful to rename exports. For instance, the
5251 cygwin kernel does this regularly. A symbol `_foo' can be
5252 exported as `foo' but not as `_foo' by using special
5253 directives in the DEF file. (This will also affect the import
5254 library, if it is created). In the following example:
5256 LIBRARY "xyz.dll" BASE=0x61000000
5261 The line `_foo = foo' maps the exported symbol `foo' to
5264 Note: using a DEF file disables the default auto-export behavior,
5265 unless the `--export-all-symbols' command line option is used.
5266 If, however, you are trying to rename symbols, then you should list
5267 _all_ desired exports in the DEF file, including the symbols that
5268 are not being renamed, and do _not_ use the `--export-all-symbols'
5269 option. If you list only the renamed symbols in the DEF file, and
5270 use `--export-all-symbols' to handle the other symbols, then the
5271 both the new names _and_ the original names for the renamed
5272 symbols will be exported. In effect, you'd be aliasing those
5273 symbols, not renaming them, which is probably not what you wanted.
5276 The Windows object format, PE, specifies a form of weak symbols
5277 called weak externals. When a weak symbol is linked and the
5278 symbol is not defined, the weak symbol becomes an alias for some
5279 other symbol. There are three variants of weak externals:
5280 * Definition is searched for in objects and libraries,
5281 historically called lazy externals.
5283 * Definition is searched for only in other objects, not in
5284 libraries. This form is not presently implemented.
5286 * No search; the symbol is an alias. This form is not presently
5288 As a GNU extension, weak symbols that do not specify an alternate
5289 symbol are supported. If the symbol is undefined when linking,
5290 the symbol uses a default value.
5293 File: ld.info, Node: Xtensa, Prev: WIN32, Up: Machine Dependent
5295 4.13 `ld' and Xtensa Processors
5296 ===============================
5298 The default `ld' behavior for Xtensa processors is to interpret
5299 `SECTIONS' commands so that lists of explicitly named sections in a
5300 specification with a wildcard file will be interleaved when necessary to
5301 keep literal pools within the range of PC-relative load offsets. For
5302 example, with the command:
5311 `ld' may interleave some of the `.literal' and `.text' sections from
5312 different object files to ensure that the literal pools are within the
5313 range of PC-relative load offsets. A valid interleaving might place
5314 the `.literal' sections from an initial group of files followed by the
5315 `.text' sections of that group of files. Then, the `.literal' sections
5316 from the rest of the files and the `.text' sections from the rest of
5317 the files would follow.
5319 Relaxation is enabled by default for the Xtensa version of `ld' and
5320 provides two important link-time optimizations. The first optimization
5321 is to combine identical literal values to reduce code size. A redundant
5322 literal will be removed and all the `L32R' instructions that use it
5323 will be changed to reference an identical literal, as long as the
5324 location of the replacement literal is within the offset range of all
5325 the `L32R' instructions. The second optimization is to remove
5326 unnecessary overhead from assembler-generated "longcall" sequences of
5327 `L32R'/`CALLXN' when the target functions are within range of direct
5328 `CALLN' instructions.
5330 For each of these cases where an indirect call sequence can be
5331 optimized to a direct call, the linker will change the `CALLXN'
5332 instruction to a `CALLN' instruction, remove the `L32R' instruction,
5333 and remove the literal referenced by the `L32R' instruction if it is
5334 not used for anything else. Removing the `L32R' instruction always
5335 reduces code size but can potentially hurt performance by changing the
5336 alignment of subsequent branch targets. By default, the linker will
5337 always preserve alignments, either by switching some instructions
5338 between 24-bit encodings and the equivalent density instructions or by
5339 inserting a no-op in place of the `L32R' instruction that was removed.
5340 If code size is more important than performance, the `--size-opt'
5341 option can be used to prevent the linker from widening density
5342 instructions or inserting no-ops, except in a few cases where no-ops
5343 are required for correctness.
5345 The following Xtensa-specific command-line options can be used to
5349 Since the Xtensa version of `ld' enables the `--relax' option by
5350 default, the `--no-relax' option is provided to disable relaxation.
5353 When optimizing indirect calls to direct calls, optimize for code
5354 size more than performance. With this option, the linker will not
5355 insert no-ops or widen density instructions to preserve branch
5356 target alignment. There may still be some cases where no-ops are
5357 required to preserve the correctness of the code.
5360 File: ld.info, Node: BFD, Next: Reporting Bugs, Prev: Machine Dependent, Up: Top
5365 The linker accesses object and archive files using the BFD libraries.
5366 These libraries allow the linker to use the same routines to operate on
5367 object files whatever the object file format. A different object file
5368 format can be supported simply by creating a new BFD back end and adding
5369 it to the library. To conserve runtime memory, however, the linker and
5370 associated tools are usually configured to support only a subset of the
5371 object file formats available. You can use `objdump -i' (*note
5372 objdump: (binutils.info)objdump.) to list all the formats available for
5375 As with most implementations, BFD is a compromise between several
5376 conflicting requirements. The major factor influencing BFD design was
5377 efficiency: any time used converting between formats is time which
5378 would not have been spent had BFD not been involved. This is partly
5379 offset by abstraction payback; since BFD simplifies applications and
5380 back ends, more time and care may be spent optimizing algorithms for a
5383 One minor artifact of the BFD solution which you should bear in mind
5384 is the potential for information loss. There are two places where
5385 useful information can be lost using the BFD mechanism: during
5386 conversion and during output. *Note BFD information loss::.
5390 * BFD outline:: How it works: an outline of BFD
5393 File: ld.info, Node: BFD outline, Up: BFD
5395 5.1 How It Works: An Outline of BFD
5396 ===================================
5398 When an object file is opened, BFD subroutines automatically determine
5399 the format of the input object file. They then build a descriptor in
5400 memory with pointers to routines that will be used to access elements of
5401 the object file's data structures.
5403 As different information from the object files is required, BFD
5404 reads from different sections of the file and processes them. For
5405 example, a very common operation for the linker is processing symbol
5406 tables. Each BFD back end provides a routine for converting between
5407 the object file's representation of symbols and an internal canonical
5408 format. When the linker asks for the symbol table of an object file, it
5409 calls through a memory pointer to the routine from the relevant BFD
5410 back end which reads and converts the table into a canonical form. The
5411 linker then operates upon the canonical form. When the link is finished
5412 and the linker writes the output file's symbol table, another BFD back
5413 end routine is called to take the newly created symbol table and
5414 convert it into the chosen output format.
5418 * BFD information loss:: Information Loss
5419 * Canonical format:: The BFD canonical object-file format
5422 File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline
5424 5.1.1 Information Loss
5425 ----------------------
5427 _Information can be lost during output._ The output formats supported
5428 by BFD do not provide identical facilities, and information which can
5429 be described in one form has nowhere to go in another format. One
5430 example of this is alignment information in `b.out'. There is nowhere
5431 in an `a.out' format file to store alignment information on the
5432 contained data, so when a file is linked from `b.out' and an `a.out'
5433 image is produced, alignment information will not propagate to the
5434 output file. (The linker will still use the alignment information
5435 internally, so the link is performed correctly).
5437 Another example is COFF section names. COFF files may contain an
5438 unlimited number of sections, each one with a textual section name. If
5439 the target of the link is a format which does not have many sections
5440 (e.g., `a.out') or has sections without names (e.g., the Oasys format),
5441 the link cannot be done simply. You can circumvent this problem by
5442 describing the desired input-to-output section mapping with the linker
5445 _Information can be lost during canonicalization._ The BFD internal
5446 canonical form of the external formats is not exhaustive; there are
5447 structures in input formats for which there is no direct representation
5448 internally. This means that the BFD back ends cannot maintain all
5449 possible data richness through the transformation between external to
5450 internal and back to external formats.
5452 This limitation is only a problem when an application reads one
5453 format and writes another. Each BFD back end is responsible for
5454 maintaining as much data as possible, and the internal BFD canonical
5455 form has structures which are opaque to the BFD core, and exported only
5456 to the back ends. When a file is read in one format, the canonical form
5457 is generated for BFD and the application. At the same time, the back
5458 end saves away any information which may otherwise be lost. If the data
5459 is then written back in the same format, the back end routine will be
5460 able to use the canonical form provided by the BFD core as well as the
5461 information it prepared earlier. Since there is a great deal of
5462 commonality between back ends, there is no information lost when
5463 linking or copying big endian COFF to little endian COFF, or `a.out' to
5464 `b.out'. When a mixture of formats is linked, the information is only
5465 lost from the files whose format differs from the destination.
5468 File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline
5470 5.1.2 The BFD canonical object-file format
5471 ------------------------------------------
5473 The greatest potential for loss of information occurs when there is the
5474 least overlap between the information provided by the source format,
5475 that stored by the canonical format, and that needed by the destination
5476 format. A brief description of the canonical form may help you
5477 understand which kinds of data you can count on preserving across
5481 Information stored on a per-file basis includes target machine
5482 architecture, particular implementation format type, a demand
5483 pageable bit, and a write protected bit. Information like Unix
5484 magic numbers is not stored here--only the magic numbers' meaning,
5485 so a `ZMAGIC' file would have both the demand pageable bit and the
5486 write protected text bit set. The byte order of the target is
5487 stored on a per-file basis, so that big- and little-endian object
5488 files may be used with one another.
5491 Each section in the input file contains the name of the section,
5492 the section's original address in the object file, size and
5493 alignment information, various flags, and pointers into other BFD
5497 Each symbol contains a pointer to the information for the object
5498 file which originally defined it, its name, its value, and various
5499 flag bits. When a BFD back end reads in a symbol table, it
5500 relocates all symbols to make them relative to the base of the
5501 section where they were defined. Doing this ensures that each
5502 symbol points to its containing section. Each symbol also has a
5503 varying amount of hidden private data for the BFD back end. Since
5504 the symbol points to the original file, the private data format
5505 for that symbol is accessible. `ld' can operate on a collection
5506 of symbols of wildly different formats without problems.
5508 Normal global and simple local symbols are maintained on output,
5509 so an output file (no matter its format) will retain symbols
5510 pointing to functions and to global, static, and common variables.
5511 Some symbol information is not worth retaining; in `a.out', type
5512 information is stored in the symbol table as long symbol names.
5513 This information would be useless to most COFF debuggers; the
5514 linker has command line switches to allow users to throw it away.
5516 There is one word of type information within the symbol, so if the
5517 format supports symbol type information within symbols (for
5518 example, COFF, IEEE, Oasys) and the type is simple enough to fit
5519 within one word (nearly everything but aggregates), the
5520 information will be preserved.
5523 Each canonical BFD relocation record contains a pointer to the
5524 symbol to relocate to, the offset of the data to relocate, the
5525 section the data is in, and a pointer to a relocation type
5526 descriptor. Relocation is performed by passing messages through
5527 the relocation type descriptor and the symbol pointer. Therefore,
5528 relocations can be performed on output data using a relocation
5529 method that is only available in one of the input formats. For
5530 instance, Oasys provides a byte relocation format. A relocation
5531 record requesting this relocation type would point indirectly to a
5532 routine to perform this, so the relocation may be performed on a
5533 byte being written to a 68k COFF file, even though 68k COFF has no
5534 such relocation type.
5537 Object formats can contain, for debugging purposes, some form of
5538 mapping between symbols, source line numbers, and addresses in the
5539 output file. These addresses have to be relocated along with the
5540 symbol information. Each symbol with an associated list of line
5541 number records points to the first record of the list. The head
5542 of a line number list consists of a pointer to the symbol, which
5543 allows finding out the address of the function whose line number
5544 is being described. The rest of the list is made up of pairs:
5545 offsets into the section and line numbers. Any format which can
5546 simply derive this information can pass it successfully between
5547 formats (COFF, IEEE and Oasys).
5550 File: ld.info, Node: Reporting Bugs, Next: MRI, Prev: BFD, Up: Top
5555 Your bug reports play an essential role in making `ld' reliable.
5557 Reporting a bug may help you by bringing a solution to your problem,
5558 or it may not. But in any case the principal function of a bug report
5559 is to help the entire community by making the next version of `ld' work
5560 better. Bug reports are your contribution to the maintenance of `ld'.
5562 In order for a bug report to serve its purpose, you must include the
5563 information that enables us to fix the bug.
5567 * Bug Criteria:: Have you found a bug?
5568 * Bug Reporting:: How to report bugs
5571 File: ld.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
5573 6.1 Have You Found a Bug?
5574 =========================
5576 If you are not sure whether you have found a bug, here are some
5579 * If the linker gets a fatal signal, for any input whatever, that is
5580 a `ld' bug. Reliable linkers never crash.
5582 * If `ld' produces an error message for valid input, that is a bug.
5584 * If `ld' does not produce an error message for invalid input, that
5585 may be a bug. In the general case, the linker can not verify that
5586 object files are correct.
5588 * If you are an experienced user of linkers, your suggestions for
5589 improvement of `ld' are welcome in any case.
5592 File: ld.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
5594 6.2 How to Report Bugs
5595 ======================
5597 A number of companies and individuals offer support for GNU products.
5598 If you obtained `ld' from a support organization, we recommend you
5599 contact that organization first.
5601 You can find contact information for many support companies and
5602 individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
5604 Otherwise, send bug reports for `ld' to
5605 `http://www.sourceware.org/bugzilla/'.
5607 The fundamental principle of reporting bugs usefully is this:
5608 *report all the facts*. If you are not sure whether to state a fact or
5609 leave it out, state it!
5611 Often people omit facts because they think they know what causes the
5612 problem and assume that some details do not matter. Thus, you might
5613 assume that the name of a symbol you use in an example does not matter.
5614 Well, probably it does not, but one cannot be sure. Perhaps the bug
5615 is a stray memory reference which happens to fetch from the location
5616 where that name is stored in memory; perhaps, if the name were
5617 different, the contents of that location would fool the linker into
5618 doing the right thing despite the bug. Play it safe and give a
5619 specific, complete example. That is the easiest thing for you to do,
5620 and the most helpful.
5622 Keep in mind that the purpose of a bug report is to enable us to fix
5623 the bug if it is new to us. Therefore, always write your bug reports
5624 on the assumption that the bug has not been reported previously.
5626 Sometimes people give a few sketchy facts and ask, "Does this ring a
5627 bell?" This cannot help us fix a bug, so it is basically useless. We
5628 respond by asking for enough details to enable us to investigate. You
5629 might as well expedite matters by sending them to begin with.
5631 To enable us to fix the bug, you should include all these things:
5633 * The version of `ld'. `ld' announces it if you start it with the
5634 `--version' argument.
5636 Without this, we will not know whether there is any point in
5637 looking for the bug in the current version of `ld'.
5639 * Any patches you may have applied to the `ld' source, including any
5640 patches made to the `BFD' library.
5642 * The type of machine you are using, and the operating system name
5645 * What compiler (and its version) was used to compile `ld'--e.g.
5648 * The command arguments you gave the linker to link your example and
5649 observe the bug. To guarantee you will not omit something
5650 important, list them all. A copy of the Makefile (or the output
5651 from make) is sufficient.
5653 If we were to try to guess the arguments, we would probably guess
5654 wrong and then we might not encounter the bug.
5656 * A complete input file, or set of input files, that will reproduce
5657 the bug. It is generally most helpful to send the actual object
5658 files provided that they are reasonably small. Say no more than
5659 10K. For bigger files you can either make them available by FTP
5660 or HTTP or else state that you are willing to send the object
5661 file(s) to whomever requests them. (Note - your email will be
5662 going to a mailing list, so we do not want to clog it up with
5663 large attachments). But small attachments are best.
5665 If the source files were assembled using `gas' or compiled using
5666 `gcc', then it may be OK to send the source files rather than the
5667 object files. In this case, be sure to say exactly what version of
5668 `gas' or `gcc' was used to produce the object files. Also say how
5669 `gas' or `gcc' were configured.
5671 * A description of what behavior you observe that you believe is
5672 incorrect. For example, "It gets a fatal signal."
5674 Of course, if the bug is that `ld' gets a fatal signal, then we
5675 will certainly notice it. But if the bug is incorrect output, we
5676 might not notice unless it is glaringly wrong. You might as well
5677 not give us a chance to make a mistake.
5679 Even if the problem you experience is a fatal signal, you should
5680 still say so explicitly. Suppose something strange is going on,
5681 such as, your copy of `ld' is out of sync, or you have encountered
5682 a bug in the C library on your system. (This has happened!) Your
5683 copy might crash and ours would not. If you told us to expect a
5684 crash, then when ours fails to crash, we would know that the bug
5685 was not happening for us. If you had not told us to expect a
5686 crash, then we would not be able to draw any conclusion from our
5689 * If you wish to suggest changes to the `ld' source, send us context
5690 diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
5691 Always send diffs from the old file to the new file. If you even
5692 discuss something in the `ld' source, refer to it by context, not
5695 The line numbers in our development sources will not match those
5696 in your sources. Your line numbers would convey no useful
5699 Here are some things that are not necessary:
5701 * A description of the envelope of the bug.
5703 Often people who encounter a bug spend a lot of time investigating
5704 which changes to the input file will make the bug go away and which
5705 changes will not affect it.
5707 This is often time consuming and not very useful, because the way
5708 we will find the bug is by running a single example under the
5709 debugger with breakpoints, not by pure deduction from a series of
5710 examples. We recommend that you save your time for something else.
5712 Of course, if you can find a simpler example to report _instead_
5713 of the original one, that is a convenience for us. Errors in the
5714 output will be easier to spot, running under the debugger will take
5715 less time, and so on.
5717 However, simplification is not vital; if you do not want to do
5718 this, report the bug anyway and send us the entire test case you
5721 * A patch for the bug.
5723 A patch for the bug does help us if it is a good one. But do not
5724 omit the necessary information, such as the test case, on the
5725 assumption that a patch is all we need. We might see problems
5726 with your patch and decide to fix the problem another way, or we
5727 might not understand it at all.
5729 Sometimes with a program as complicated as `ld' it is very hard to
5730 construct an example that will make the program follow a certain
5731 path through the code. If you do not send us the example, we will
5732 not be able to construct one, so we will not be able to verify
5733 that the bug is fixed.
5735 And if we cannot understand what bug you are trying to fix, or why
5736 your patch should be an improvement, we will not install it. A
5737 test case will help us to understand.
5739 * A guess about what the bug is or what it depends on.
5741 Such guesses are usually wrong. Even we cannot guess right about
5742 such things without first using the debugger to find the facts.
5745 File: ld.info, Node: MRI, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top
5747 Appendix A MRI Compatible Script Files
5748 **************************************
5750 To aid users making the transition to GNU `ld' from the MRI linker,
5751 `ld' can use MRI compatible linker scripts as an alternative to the
5752 more general-purpose linker scripting language described in *Note
5753 Scripts::. MRI compatible linker scripts have a much simpler command
5754 set than the scripting language otherwise used with `ld'. GNU `ld'
5755 supports the most commonly used MRI linker commands; these commands are
5758 In general, MRI scripts aren't of much use with the `a.out' object
5759 file format, since it only has three sections and MRI scripts lack some
5760 features to make use of them.
5762 You can specify a file containing an MRI-compatible script using the
5763 `-c' command-line option.
5765 Each command in an MRI-compatible script occupies its own line; each
5766 command line starts with the keyword that identifies the command (though
5767 blank lines are also allowed for punctuation). If a line of an
5768 MRI-compatible script begins with an unrecognized keyword, `ld' issues
5769 a warning message, but continues processing the script.
5771 Lines beginning with `*' are comments.
5773 You can write these commands using all upper-case letters, or all
5774 lower case; for example, `chip' is the same as `CHIP'. The following
5775 list shows only the upper-case form of each command.
5778 `ABSOLUTE SECNAME, SECNAME, ... SECNAME'
5779 Normally, `ld' includes in the output file all sections from all
5780 the input files. However, in an MRI-compatible script, you can
5781 use the `ABSOLUTE' command to restrict the sections that will be
5782 present in your output program. If the `ABSOLUTE' command is used
5783 at all in a script, then only the sections named explicitly in
5784 `ABSOLUTE' commands will appear in the linker output. You can
5785 still use other input sections (whatever you select on the command
5786 line, or using `LOAD') to resolve addresses in the output file.
5788 `ALIAS OUT-SECNAME, IN-SECNAME'
5789 Use this command to place the data from input section IN-SECNAME
5790 in a section called OUT-SECNAME in the linker output file.
5792 IN-SECNAME may be an integer.
5794 `ALIGN SECNAME = EXPRESSION'
5795 Align the section called SECNAME to EXPRESSION. The EXPRESSION
5796 should be a power of two.
5799 Use the value of EXPRESSION as the lowest address (other than
5800 absolute addresses) in the output file.
5803 `CHIP EXPRESSION, EXPRESSION'
5804 This command does nothing; it is accepted only for compatibility.
5807 This command does nothing whatever; it's only accepted for
5810 `FORMAT OUTPUT-FORMAT'
5811 Similar to the `OUTPUT_FORMAT' command in the more general linker
5812 language, but restricted to one of these output formats:
5814 1. S-records, if OUTPUT-FORMAT is `S'
5816 2. IEEE, if OUTPUT-FORMAT is `IEEE'
5818 3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
5822 Print (to the standard output file) a link map, as produced by the
5823 `ld' command-line option `-M'.
5825 The keyword `LIST' may be followed by anything on the same line,
5826 with no change in its effect.
5829 `LOAD FILENAME, FILENAME, ... FILENAME'
5830 Include one or more object file FILENAME in the link; this has the
5831 same effect as specifying FILENAME directly on the `ld' command
5835 OUTPUT-NAME is the name for the program produced by `ld'; the
5836 MRI-compatible command `NAME' is equivalent to the command-line
5837 option `-o' or the general script language command `OUTPUT'.
5839 `ORDER SECNAME, SECNAME, ... SECNAME'
5840 `ORDER SECNAME SECNAME SECNAME'
5841 Normally, `ld' orders the sections in its output file in the order
5842 in which they first appear in the input files. In an
5843 MRI-compatible script, you can override this ordering with the
5844 `ORDER' command. The sections you list with `ORDER' will appear
5845 first in your output file, in the order specified.
5847 `PUBLIC NAME=EXPRESSION'
5848 `PUBLIC NAME,EXPRESSION'
5849 `PUBLIC NAME EXPRESSION'
5850 Supply a value (EXPRESSION) for external symbol NAME used in the
5853 `SECT SECNAME, EXPRESSION'
5854 `SECT SECNAME=EXPRESSION'
5855 `SECT SECNAME EXPRESSION'
5856 You can use any of these three forms of the `SECT' command to
5857 specify the start address (EXPRESSION) for section SECNAME. If
5858 you have more than one `SECT' statement for the same SECNAME, only
5859 the _first_ sets the start address.
5862 File: ld.info, Node: GNU Free Documentation License, Next: LD Index, Prev: MRI, Up: Top
5864 Appendix B GNU Free Documentation License
5865 *****************************************
5867 Version 1.1, March 2000
5869 Copyright (C) 2000, 2003 Free Software Foundation, Inc.
5870 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
5872 Everyone is permitted to copy and distribute verbatim copies
5873 of this license document, but changing it is not allowed.
5878 The purpose of this License is to make a manual, textbook, or other
5879 written document "free" in the sense of freedom: to assure everyone
5880 the effective freedom to copy and redistribute it, with or without
5881 modifying it, either commercially or noncommercially. Secondarily,
5882 this License preserves for the author and publisher a way to get
5883 credit for their work, while not being considered responsible for
5884 modifications made by others.
5886 This License is a kind of "copyleft", which means that derivative
5887 works of the document must themselves be free in the same sense.
5888 It complements the GNU General Public License, which is a copyleft
5889 license designed for free software.
5891 We have designed this License in order to use it for manuals for
5892 free software, because free software needs free documentation: a
5893 free program should come with manuals providing the same freedoms
5894 that the software does. But this License is not limited to
5895 software manuals; it can be used for any textual work, regardless
5896 of subject matter or whether it is published as a printed book.
5897 We recommend this License principally for works whose purpose is
5898 instruction or reference.
5901 1. APPLICABILITY AND DEFINITIONS
5903 This License applies to any manual or other work that contains a
5904 notice placed by the copyright holder saying it can be distributed
5905 under the terms of this License. The "Document", below, refers to
5906 any such manual or work. Any member of the public is a licensee,
5907 and is addressed as "you."
5909 A "Modified Version" of the Document means any work containing the
5910 Document or a portion of it, either copied verbatim, or with
5911 modifications and/or translated into another language.
5913 A "Secondary Section" is a named appendix or a front-matter
5914 section of the Document that deals exclusively with the
5915 relationship of the publishers or authors of the Document to the
5916 Document's overall subject (or to related matters) and contains
5917 nothing that could fall directly within that overall subject.
5918 (For example, if the Document is in part a textbook of
5919 mathematics, a Secondary Section may not explain any mathematics.)
5920 The relationship could be a matter of historical connection with
5921 the subject or with related matters, or of legal, commercial,
5922 philosophical, ethical or political position regarding them.
5924 The "Invariant Sections" are certain Secondary Sections whose
5925 titles are designated, as being those of Invariant Sections, in
5926 the notice that says that the Document is released under this
5929 The "Cover Texts" are certain short passages of text that are
5930 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5931 that says that the Document is released under this License.
5933 A "Transparent" copy of the Document means a machine-readable copy,
5934 represented in a format whose specification is available to the
5935 general public, whose contents can be viewed and edited directly
5936 and straightforwardly with generic text editors or (for images
5937 composed of pixels) generic paint programs or (for drawings) some
5938 widely available drawing editor, and that is suitable for input to
5939 text formatters or for automatic translation to a variety of
5940 formats suitable for input to text formatters. A copy made in an
5941 otherwise Transparent file format whose markup has been designed
5942 to thwart or discourage subsequent modification by readers is not
5943 Transparent. A copy that is not "Transparent" is called "Opaque."
5945 Examples of suitable formats for Transparent copies include plain
5946 ASCII without markup, Texinfo input format, LaTeX input format,
5947 SGML or XML using a publicly available DTD, and
5948 standard-conforming simple HTML designed for human modification.
5949 Opaque formats include PostScript, PDF, proprietary formats that
5950 can be read and edited only by proprietary word processors, SGML
5951 or XML for which the DTD and/or processing tools are not generally
5952 available, and the machine-generated HTML produced by some word
5953 processors for output purposes only.
5955 The "Title Page" means, for a printed book, the title page itself,
5956 plus such following pages as are needed to hold, legibly, the
5957 material this License requires to appear in the title page. For
5958 works in formats which do not have any title page as such, "Title
5959 Page" means the text near the most prominent appearance of the
5960 work's title, preceding the beginning of the body of the text.
5964 You may copy and distribute the Document in any medium, either
5965 commercially or noncommercially, provided that this License, the
5966 copyright notices, and the license notice saying this License
5967 applies to the Document are reproduced in all copies, and that you
5968 add no other conditions whatsoever to those of this License. You
5969 may not use technical measures to obstruct or control the reading
5970 or further copying of the copies you make or distribute. However,
5971 you may accept compensation in exchange for copies. If you
5972 distribute a large enough number of copies you must also follow
5973 the conditions in section 3.
5975 You may also lend copies, under the same conditions stated above,
5976 and you may publicly display copies.
5978 3. COPYING IN QUANTITY
5980 If you publish printed copies of the Document numbering more than
5981 100, and the Document's license notice requires Cover Texts, you
5982 must enclose the copies in covers that carry, clearly and legibly,
5983 all these Cover Texts: Front-Cover Texts on the front cover, and
5984 Back-Cover Texts on the back cover. Both covers must also clearly
5985 and legibly identify you as the publisher of these copies. The
5986 front cover must present the full title with all words of the
5987 title equally prominent and visible. You may add other material
5988 on the covers in addition. Copying with changes limited to the
5989 covers, as long as they preserve the title of the Document and
5990 satisfy these conditions, can be treated as verbatim copying in
5993 If the required texts for either cover are too voluminous to fit
5994 legibly, you should put the first ones listed (as many as fit
5995 reasonably) on the actual cover, and continue the rest onto
5998 If you publish or distribute Opaque copies of the Document
5999 numbering more than 100, you must either include a
6000 machine-readable Transparent copy along with each Opaque copy, or
6001 state in or with each Opaque copy a publicly-accessible
6002 computer-network location containing a complete Transparent copy
6003 of the Document, free of added material, which the general
6004 network-using public has access to download anonymously at no
6005 charge using public-standard network protocols. If you use the
6006 latter option, you must take reasonably prudent steps, when you
6007 begin distribution of Opaque copies in quantity, to ensure that
6008 this Transparent copy will remain thus accessible at the stated
6009 location until at least one year after the last time you
6010 distribute an Opaque copy (directly or through your agents or
6011 retailers) of that edition to the public.
6013 It is requested, but not required, that you contact the authors of
6014 the Document well before redistributing any large number of
6015 copies, to give them a chance to provide you with an updated
6016 version of the Document.
6020 You may copy and distribute a Modified Version of the Document
6021 under the conditions of sections 2 and 3 above, provided that you
6022 release the Modified Version under precisely this License, with
6023 the Modified Version filling the role of the Document, thus
6024 licensing distribution and modification of the Modified Version to
6025 whoever possesses a copy of it. In addition, you must do these
6026 things in the Modified Version:
6028 A. Use in the Title Page (and on the covers, if any) a title
6029 distinct from that of the Document, and from those of previous
6030 versions (which should, if there were any, be listed in the
6031 History section of the Document). You may use the same title
6032 as a previous version if the original publisher of that version
6034 B. List on the Title Page, as authors, one or more persons or
6035 entities responsible for authorship of the modifications in the
6036 Modified Version, together with at least five of the principal
6037 authors of the Document (all of its principal authors, if it
6038 has less than five).
6039 C. State on the Title page the name of the publisher of the
6040 Modified Version, as the publisher.
6041 D. Preserve all the copyright notices of the Document.
6042 E. Add an appropriate copyright notice for your modifications
6043 adjacent to the other copyright notices.
6044 F. Include, immediately after the copyright notices, a license
6045 notice giving the public permission to use the Modified Version
6046 under the terms of this License, in the form shown in the
6048 G. Preserve in that license notice the full lists of Invariant
6049 Sections and required Cover Texts given in the Document's
6051 H. Include an unaltered copy of this License.
6052 I. Preserve the section entitled "History", and its title, and add
6053 to it an item stating at least the title, year, new authors, and
6054 publisher of the Modified Version as given on the Title Page.
6055 If there is no section entitled "History" in the Document,
6056 create one stating the title, year, authors, and publisher of
6057 the Document as given on its Title Page, then add an item
6058 describing the Modified Version as stated in the previous
6060 J. Preserve the network location, if any, given in the Document for
6061 public access to a Transparent copy of the Document, and
6062 likewise the network locations given in the Document for
6063 previous versions it was based on. These may be placed in the
6064 "History" section. You may omit a network location for a work
6065 that was published at least four years before the Document
6066 itself, or if the original publisher of the version it refers
6067 to gives permission.
6068 K. In any section entitled "Acknowledgements" or "Dedications",
6069 preserve the section's title, and preserve in the section all the
6070 substance and tone of each of the contributor acknowledgements
6071 and/or dedications given therein.
6072 L. Preserve all the Invariant Sections of the Document,
6073 unaltered in their text and in their titles. Section numbers
6074 or the equivalent are not considered part of the section titles.
6075 M. Delete any section entitled "Endorsements." Such a section
6076 may not be included in the Modified Version.
6077 N. Do not retitle any existing section as "Endorsements" or to
6078 conflict in title with any Invariant Section.
6080 If the Modified Version includes new front-matter sections or
6081 appendices that qualify as Secondary Sections and contain no
6082 material copied from the Document, you may at your option
6083 designate some or all of these sections as invariant. To do this,
6084 add their titles to the list of Invariant Sections in the Modified
6085 Version's license notice. These titles must be distinct from any
6086 other section titles.
6088 You may add a section entitled "Endorsements", provided it contains
6089 nothing but endorsements of your Modified Version by various
6090 parties-for example, statements of peer review or that the text has
6091 been approved by an organization as the authoritative definition
6094 You may add a passage of up to five words as a Front-Cover Text,
6095 and a passage of up to 25 words as a Back-Cover Text, to the end
6096 of the list of Cover Texts in the Modified Version. Only one
6097 passage of Front-Cover Text and one of Back-Cover Text may be
6098 added by (or through arrangements made by) any one entity. If the
6099 Document already includes a cover text for the same cover,
6100 previously added by you or by arrangement made by the same entity
6101 you are acting on behalf of, you may not add another; but you may
6102 replace the old one, on explicit permission from the previous
6103 publisher that added the old one.
6105 The author(s) and publisher(s) of the Document do not by this
6106 License give permission to use their names for publicity for or to
6107 assert or imply endorsement of any Modified Version.
6109 5. COMBINING DOCUMENTS
6111 You may combine the Document with other documents released under
6112 this License, under the terms defined in section 4 above for
6113 modified versions, provided that you include in the combination
6114 all of the Invariant Sections of all of the original documents,
6115 unmodified, and list them all as Invariant Sections of your
6116 combined work in its license notice.
6118 The combined work need only contain one copy of this License, and
6119 multiple identical Invariant Sections may be replaced with a single
6120 copy. If there are multiple Invariant Sections with the same name
6121 but different contents, make the title of each such section unique
6122 by adding at the end of it, in parentheses, the name of the
6123 original author or publisher of that section if known, or else a
6124 unique number. Make the same adjustment to the section titles in
6125 the list of Invariant Sections in the license notice of the
6128 In the combination, you must combine any sections entitled
6129 "History" in the various original documents, forming one section
6130 entitled "History"; likewise combine any sections entitled
6131 "Acknowledgements", and any sections entitled "Dedications." You
6132 must delete all sections entitled "Endorsements."
6134 6. COLLECTIONS OF DOCUMENTS
6136 You may make a collection consisting of the Document and other
6137 documents released under this License, and replace the individual
6138 copies of this License in the various documents with a single copy
6139 that is included in the collection, provided that you follow the
6140 rules of this License for verbatim copying of each of the
6141 documents in all other respects.
6143 You may extract a single document from such a collection, and
6144 distribute it individually under this License, provided you insert
6145 a copy of this License into the extracted document, and follow
6146 this License in all other respects regarding verbatim copying of
6149 7. AGGREGATION WITH INDEPENDENT WORKS
6151 A compilation of the Document or its derivatives with other
6152 separate and independent documents or works, in or on a volume of
6153 a storage or distribution medium, does not as a whole count as a
6154 Modified Version of the Document, provided no compilation
6155 copyright is claimed for the compilation. Such a compilation is
6156 called an "aggregate", and this License does not apply to the
6157 other self-contained works thus compiled with the Document, on
6158 account of their being thus compiled, if they are not themselves
6159 derivative works of the Document.
6161 If the Cover Text requirement of section 3 is applicable to these
6162 copies of the Document, then if the Document is less than one
6163 quarter of the entire aggregate, the Document's Cover Texts may be
6164 placed on covers that surround only the Document within the
6165 aggregate. Otherwise they must appear on covers around the whole
6170 Translation is considered a kind of modification, so you may
6171 distribute translations of the Document under the terms of section
6172 4. Replacing Invariant Sections with translations requires special
6173 permission from their copyright holders, but you may include
6174 translations of some or all Invariant Sections in addition to the
6175 original versions of these Invariant Sections. You may include a
6176 translation of this License provided that you also include the
6177 original English version of this License. In case of a
6178 disagreement between the translation and the original English
6179 version of this License, the original English version will prevail.
6183 You may not copy, modify, sublicense, or distribute the Document
6184 except as expressly provided for under this License. Any other
6185 attempt to copy, modify, sublicense or distribute the Document is
6186 void, and will automatically terminate your rights under this
6187 License. However, parties who have received copies, or rights,
6188 from you under this License will not have their licenses
6189 terminated so long as such parties remain in full compliance.
6191 10. FUTURE REVISIONS OF THIS LICENSE
6193 The Free Software Foundation may publish new, revised versions of
6194 the GNU Free Documentation License from time to time. Such new
6195 versions will be similar in spirit to the present version, but may
6196 differ in detail to address new problems or concerns. See
6197 http://www.gnu.org/copyleft/.
6199 Each version of the License is given a distinguishing version
6200 number. If the Document specifies that a particular numbered
6201 version of this License "or any later version" applies to it, you
6202 have the option of following the terms and conditions either of
6203 that specified version or of any later version that has been
6204 published (not as a draft) by the Free Software Foundation. If
6205 the Document does not specify a version number of this License,
6206 you may choose any version ever published (not as a draft) by the
6207 Free Software Foundation.
6210 ADDENDUM: How to use this License for your documents
6211 ====================================================
6213 To use this License in a document you have written, include a copy of
6214 the License in the document and put the following copyright and license
6215 notices just after the title page:
6217 Copyright (C) YEAR YOUR NAME.
6218 Permission is granted to copy, distribute and/or modify this document
6219 under the terms of the GNU Free Documentation License, Version 1.1
6220 or any later version published by the Free Software Foundation;
6221 with the Invariant Sections being LIST THEIR TITLES, with the
6222 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
6223 A copy of the license is included in the section entitled "GNU
6224 Free Documentation License."
6226 If you have no Invariant Sections, write "with no Invariant Sections"
6227 instead of saying which ones are invariant. If you have no Front-Cover
6228 Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
6229 LIST"; likewise for Back-Cover Texts.
6231 If your document contains nontrivial examples of program code, we
6232 recommend releasing these examples in parallel under your choice of
6233 free software license, such as the GNU General Public License, to
6234 permit their use in free software.
6237 File: ld.info, Node: LD Index, Prev: GNU Free Documentation License, Up: Top
6245 * ": Symbols. (line 6)
6246 * -(: Options. (line 643)
6247 * --accept-unknown-input-arch: Options. (line 661)
6248 * --add-needed: Options. (line 683)
6249 * --add-stdcall-alias: Options. (line 1450)
6250 * --allow-multiple-definition: Options. (line 892)
6251 * --allow-shlib-undefined: Options. (line 898)
6252 * --architecture=ARCH: Options. (line 104)
6253 * --as-needed: Options. (line 671)
6254 * --auxiliary: Options. (line 205)
6255 * --bank-window: Options. (line 1789)
6256 * --base-file: Options. (line 1455)
6257 * --be8: ARM. (line 23)
6258 * --bss-plt: PowerPC ELF32. (line 13)
6259 * --build-id: Options. (line 1412)
6260 * --build-id=STYLE: Options. (line 1412)
6261 * --check-sections: Options. (line 765)
6262 * --cref: Options. (line 775)
6263 * --default-imported-symver: Options. (line 926)
6264 * --default-script=SCRIPT: Options. (line 488)
6265 * --default-symver: Options. (line 922)
6266 * --defsym SYMBOL=EXP: Options. (line 803)
6267 * --demangle[=STYLE]: Options. (line 816)
6268 * --disable-auto-image-base: Options. (line 1602)
6269 * --disable-auto-import: Options. (line 1731)
6270 * --disable-new-dtags: Options. (line 1375)
6271 * --disable-runtime-pseudo-reloc: Options. (line 1744)
6272 * --disable-stdcall-fixup: Options. (line 1465)
6273 * --discard-all: Options. (line 534)
6274 * --discard-locals: Options. (line 538)
6275 * --dll: Options. (line 1460)
6276 * --dll-search-prefix: Options. (line 1608)
6277 * --dotsyms: PowerPC64 ELF64. (line 33)
6278 * --dynamic-linker FILE: Options. (line 829)
6279 * --dynamic-list-cpp-new: Options. (line 757)
6280 * --dynamic-list-cpp-typeinfo: Options. (line 761)
6281 * --dynamic-list-data: Options. (line 754)
6282 * --dynamic-list=DYNAMIC-LIST-FILE: Options. (line 741)
6283 * --eh-frame-hdr: Options. (line 1371)
6284 * --emit-relocs: Options. (line 423)
6285 * --emit-stack-syms: SPU ELF. (line 46)
6286 * --emit-stub-syms <1>: SPU ELF. (line 15)
6287 * --emit-stub-syms <2>: PowerPC64 ELF64. (line 29)
6288 * --emit-stub-syms: PowerPC ELF32. (line 44)
6289 * --enable-auto-image-base: Options. (line 1594)
6290 * --enable-auto-import: Options. (line 1617)
6291 * --enable-extra-pe-debug: Options. (line 1749)
6292 * --enable-new-dtags: Options. (line 1375)
6293 * --enable-runtime-pseudo-reloc: Options. (line 1736)
6294 * --enable-stdcall-fixup: Options. (line 1465)
6295 * --entry=ENTRY: Options. (line 158)
6296 * --error-unresolved-symbols: Options. (line 1324)
6297 * --exclude-libs: Options. (line 168)
6298 * --exclude-symbols: Options. (line 1507)
6299 * --export-all-symbols: Options. (line 1483)
6300 * --export-dynamic: Options. (line 179)
6301 * --extra-overlay-stubs: SPU ELF. (line 19)
6302 * --fatal-warnings: Options. (line 835)
6303 * --file-alignment: Options. (line 1513)
6304 * --filter: Options. (line 226)
6305 * --fix-v4bx: ARM. (line 44)
6306 * --force-dynamic: Options. (line 432)
6307 * --force-exe-suffix: Options. (line 838)
6308 * --format=FORMAT: Options. (line 115)
6309 * --format=VERSION: TI COFF. (line 6)
6310 * --gc-sections: Options. (line 848)
6311 * --gpsize: Options. (line 259)
6312 * --hash-size=NUMBER: Options. (line 1384)
6313 * --hash-style=STYLE: Options. (line 1392)
6314 * --heap: Options. (line 1519)
6315 * --help: Options. (line 865)
6316 * --image-base: Options. (line 1526)
6317 * --just-symbols=FILE: Options. (line 455)
6318 * --kill-at: Options. (line 1535)
6319 * --large-address-aware: Options. (line 1540)
6320 * --library-path=DIR: Options. (line 318)
6321 * --library=NAMESPEC: Options. (line 285)
6322 * --local-store=lo:hi: SPU ELF. (line 24)
6323 * --major-image-version: Options. (line 1549)
6324 * --major-os-version: Options. (line 1554)
6325 * --major-subsystem-version: Options. (line 1558)
6326 * --minor-image-version: Options. (line 1563)
6327 * --minor-os-version: Options. (line 1568)
6328 * --minor-subsystem-version: Options. (line 1572)
6329 * --mri-script=MRI-CMDFILE: Options. (line 139)
6330 * --multi-subspace: HPPA ELF32. (line 6)
6331 * --nmagic: Options. (line 387)
6332 * --no-accept-unknown-input-arch: Options. (line 661)
6333 * --no-add-needed: Options. (line 683)
6334 * --no-allow-shlib-undefined: Options. (line 898)
6335 * --no-as-needed: Options. (line 671)
6336 * --no-check-sections: Options. (line 765)
6337 * --no-define-common: Options. (line 787)
6338 * --no-demangle: Options. (line 816)
6339 * --no-dotsyms: PowerPC64 ELF64. (line 33)
6340 * --no-enum-size-warning: ARM. (line 94)
6341 * --no-gc-sections: Options. (line 848)
6342 * --no-keep-memory: Options. (line 877)
6343 * --no-multi-toc: PowerPC64 ELF64. (line 74)
6344 * --no-omagic: Options. (line 401)
6345 * --no-opd-optimize: PowerPC64 ELF64. (line 48)
6346 * --no-overlays: SPU ELF. (line 9)
6347 * --no-print-gc-sections: Options. (line 856)
6348 * --no-relax: Xtensa. (line 56)
6349 * --no-tls-optimize <1>: PowerPC64 ELF64. (line 43)
6350 * --no-tls-optimize: PowerPC ELF32. (line 48)
6351 * --no-toc-optimize: PowerPC64 ELF64. (line 60)
6352 * --no-trampoline: Options. (line 1783)
6353 * --no-undefined: Options. (line 884)
6354 * --no-undefined-version: Options. (line 917)
6355 * --no-warn-mismatch: Options. (line 930)
6356 * --no-warn-search-mismatch: Options. (line 939)
6357 * --no-whole-archive: Options. (line 943)
6358 * --noinhibit-exec: Options. (line 947)
6359 * --non-overlapping-opd: PowerPC64 ELF64. (line 54)
6360 * --oformat: Options. (line 959)
6361 * --omagic: Options. (line 392)
6362 * --out-implib: Options. (line 1585)
6363 * --output-def: Options. (line 1577)
6364 * --output=OUTPUT: Options. (line 407)
6365 * --pic-executable: Options. (line 972)
6366 * --pic-veneer: M68HC11/68HC12. (line 38)
6367 * --plugin: SPU ELF. (line 6)
6368 * --print-gc-sections: Options. (line 856)
6369 * --print-map: Options. (line 350)
6370 * --reduce-memory-overheads: Options. (line 1398)
6371 * --relax: Options. (line 988)
6372 * --relax on i960: i960. (line 31)
6373 * --relax on PowerPC: PowerPC ELF32. (line 6)
6374 * --relax on Xtensa: Xtensa. (line 27)
6375 * --relocatable: Options. (line 436)
6376 * --script=SCRIPT: Options. (line 479)
6377 * --sdata-got: PowerPC ELF32. (line 30)
6378 * --section-alignment: Options. (line 1754)
6379 * --section-start SECTIONNAME=ORG: Options. (line 1161)
6380 * --secure-plt: PowerPC ELF32. (line 23)
6381 * --sort-common: Options. (line 1108)
6382 * --sort-section alignment: Options. (line 1118)
6383 * --sort-section name: Options. (line 1114)
6384 * --split-by-file: Options. (line 1122)
6385 * --split-by-reloc: Options. (line 1127)
6386 * --stack: Options. (line 1760)
6387 * --stack-analysis: SPU ELF. (line 29)
6388 * --stats: Options. (line 1140)
6389 * --strip-all: Options. (line 466)
6390 * --strip-debug: Options. (line 470)
6391 * --stub-group-size: PowerPC64 ELF64. (line 6)
6392 * --stub-group-size=N: HPPA ELF32. (line 12)
6393 * --subsystem: Options. (line 1767)
6394 * --support-old-code: ARM. (line 6)
6395 * --sysroot: Options. (line 1144)
6396 * --target-help: Options. (line 869)
6397 * --target1-abs: ARM. (line 27)
6398 * --target1-rel: ARM. (line 27)
6399 * --target2=TYPE: ARM. (line 32)
6400 * --thumb-entry=ENTRY: ARM. (line 17)
6401 * --trace: Options. (line 475)
6402 * --trace-symbol=SYMBOL: Options. (line 544)
6403 * --traditional-format: Options. (line 1149)
6404 * --undefined=SYMBOL: Options. (line 501)
6405 * --unique[=SECTION]: Options. (line 519)
6406 * --unresolved-symbols: Options. (line 1176)
6407 * --use-blx: ARM. (line 57)
6408 * --verbose: Options. (line 1205)
6409 * --version: Options. (line 528)
6410 * --version-script=VERSION-SCRIPTFILE: Options. (line 1211)
6411 * --vfp11-denorm-fix: ARM. (line 66)
6412 * --warn-common: Options. (line 1218)
6413 * --warn-constructors: Options. (line 1286)
6414 * --warn-multiple-gp: Options. (line 1291)
6415 * --warn-once: Options. (line 1305)
6416 * --warn-section-align: Options. (line 1309)
6417 * --warn-shared-textrel: Options. (line 1316)
6418 * --warn-unresolved-symbols: Options. (line 1319)
6419 * --whole-archive: Options. (line 1328)
6420 * --wrap: Options. (line 1342)
6421 * -AARCH: Options. (line 103)
6422 * -aKEYWORD: Options. (line 96)
6423 * -assert KEYWORD: Options. (line 693)
6424 * -b FORMAT: Options. (line 115)
6425 * -Bdynamic: Options. (line 696)
6426 * -Bgroup: Options. (line 706)
6427 * -Bshareable: Options. (line 1100)
6428 * -Bstatic: Options. (line 713)
6429 * -Bsymbolic: Options. (line 728)
6430 * -Bsymbolic-functions: Options. (line 735)
6431 * -c MRI-CMDFILE: Options. (line 139)
6432 * -call_shared: Options. (line 696)
6433 * -d: Options. (line 149)
6434 * -dc: Options. (line 149)
6435 * -dn: Options. (line 713)
6436 * -dp: Options. (line 149)
6437 * -dT SCRIPT: Options. (line 488)
6438 * -dy: Options. (line 696)
6439 * -E: Options. (line 179)
6440 * -e ENTRY: Options. (line 158)
6441 * -EB: Options. (line 198)
6442 * -EL: Options. (line 201)
6443 * -F: Options. (line 226)
6444 * -f: Options. (line 205)
6445 * -fini: Options. (line 250)
6446 * -G: Options. (line 259)
6447 * -g: Options. (line 256)
6448 * -hNAME: Options. (line 267)
6449 * -i: Options. (line 276)
6450 * -IFILE: Options. (line 829)
6451 * -init: Options. (line 279)
6452 * -LDIR: Options. (line 318)
6453 * -lNAMESPEC: Options. (line 285)
6454 * -M: Options. (line 350)
6455 * -m EMULATION: Options. (line 340)
6456 * -Map: Options. (line 873)
6457 * -N: Options. (line 392)
6458 * -n: Options. (line 387)
6459 * -non_shared: Options. (line 713)
6460 * -nostdlib: Options. (line 953)
6461 * -O LEVEL: Options. (line 413)
6462 * -o OUTPUT: Options. (line 407)
6463 * -pie: Options. (line 972)
6464 * -q: Options. (line 423)
6465 * -qmagic: Options. (line 982)
6466 * -Qy: Options. (line 985)
6467 * -r: Options. (line 436)
6468 * -R FILE: Options. (line 455)
6469 * -rpath: Options. (line 1023)
6470 * -rpath-link: Options. (line 1045)
6471 * -S: Options. (line 470)
6472 * -s: Options. (line 466)
6473 * -shared: Options. (line 1100)
6474 * -soname=NAME: Options. (line 267)
6475 * -static: Options. (line 713)
6476 * -t: Options. (line 475)
6477 * -T SCRIPT: Options. (line 479)
6478 * -Tbss ORG: Options. (line 1170)
6479 * -Tdata ORG: Options. (line 1170)
6480 * -Ttext ORG: Options. (line 1170)
6481 * -u SYMBOL: Options. (line 501)
6482 * -Ur: Options. (line 509)
6483 * -V: Options. (line 528)
6484 * -v: Options. (line 528)
6485 * -X: Options. (line 538)
6486 * -x: Options. (line 534)
6487 * -Y PATH: Options. (line 553)
6488 * -y SYMBOL: Options. (line 544)
6489 * -z defs: Options. (line 884)
6490 * -z KEYWORD: Options. (line 557)
6491 * -z muldefs: Options. (line 892)
6492 * .: Location Counter. (line 6)
6493 * /DISCARD/: Output Section Discarding.
6495 * :PHDR: Output Section Phdr.
6497 * =FILLEXP: Output Section Fill.
6499 * >REGION: Output Section Region.
6501 * [COMMON]: Input Section Common.
6503 * ABSOLUTE (MRI): MRI. (line 33)
6504 * absolute and relocatable symbols: Expression Section. (line 6)
6505 * absolute expressions: Expression Section. (line 6)
6506 * ABSOLUTE(EXP): Builtin Functions. (line 10)
6507 * ADDR(SECTION): Builtin Functions. (line 17)
6508 * address, section: Output Section Address.
6510 * ALIAS (MRI): MRI. (line 44)
6511 * ALIGN (MRI): MRI. (line 50)
6512 * align expression: Builtin Functions. (line 36)
6513 * align location counter: Builtin Functions. (line 36)
6514 * ALIGN(ALIGN): Builtin Functions. (line 36)
6515 * ALIGN(EXP,ALIGN): Builtin Functions. (line 36)
6516 * ALIGN(SECTION_ALIGN): Forced Output Alignment.
6518 * ALIGNOF(SECTION): Builtin Functions. (line 62)
6519 * allocating memory: MEMORY. (line 6)
6520 * architecture: Miscellaneous Commands.
6522 * architectures: Options. (line 103)
6523 * archive files, from cmd line: Options. (line 285)
6524 * archive search path in linker script: File Commands. (line 71)
6525 * arithmetic: Expressions. (line 6)
6526 * arithmetic operators: Operators. (line 6)
6527 * ARM interworking support: ARM. (line 6)
6528 * AS_NEEDED(FILES): File Commands. (line 51)
6529 * ASSERT: Miscellaneous Commands.
6531 * assertion in linker script: Miscellaneous Commands.
6533 * assignment in scripts: Assignments. (line 6)
6534 * AT(LMA): Output Section LMA. (line 6)
6535 * AT>LMA_REGION: Output Section LMA. (line 6)
6536 * automatic data imports: WIN32. (line 170)
6537 * back end: BFD. (line 6)
6538 * BASE (MRI): MRI. (line 54)
6539 * BE8: ARM. (line 23)
6540 * BFD canonical format: Canonical format. (line 11)
6541 * BFD requirements: BFD. (line 16)
6542 * big-endian objects: Options. (line 198)
6543 * binary input format: Options. (line 115)
6544 * BLOCK(EXP): Builtin Functions. (line 75)
6545 * bug criteria: Bug Criteria. (line 6)
6546 * bug reports: Bug Reporting. (line 6)
6547 * bugs in ld: Reporting Bugs. (line 6)
6548 * BYTE(EXPRESSION): Output Section Data.
6550 * C++ constructors, arranging in link: Output Section Keywords.
6552 * CHIP (MRI): MRI. (line 58)
6553 * COLLECT_NO_DEMANGLE: Environment. (line 29)
6554 * combining symbols, warnings on: Options. (line 1218)
6555 * command files: Scripts. (line 6)
6556 * command line: Options. (line 6)
6557 * common allocation: Options. (line 149)
6558 * common allocation in linker script: Miscellaneous Commands.
6560 * common symbol placement: Input Section Common.
6562 * compatibility, MRI: Options. (line 139)
6563 * constants in linker scripts: Constants. (line 6)
6564 * CONSTRUCTORS: Output Section Keywords.
6566 * constructors: Options. (line 509)
6567 * constructors, arranging in link: Output Section Keywords.
6569 * crash of linker: Bug Criteria. (line 9)
6570 * CREATE_OBJECT_SYMBOLS: Output Section Keywords.
6572 * creating a DEF file: WIN32. (line 137)
6573 * cross reference table: Options. (line 775)
6574 * cross references: Miscellaneous Commands.
6576 * current output location: Location Counter. (line 6)
6577 * data: Output Section Data.
6579 * DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions.
6581 * DATA_SEGMENT_END(EXP): Builtin Functions. (line 101)
6582 * DATA_SEGMENT_RELRO_END(OFFSET, EXP): Builtin Functions. (line 107)
6583 * dbx: Options. (line 1154)
6584 * DEF files, creating: Options. (line 1577)
6585 * default emulation: Environment. (line 21)
6586 * default input format: Environment. (line 9)
6587 * DEFINED(SYMBOL): Builtin Functions. (line 118)
6588 * deleting local symbols: Options. (line 534)
6589 * demangling, default: Environment. (line 29)
6590 * demangling, from command line: Options. (line 816)
6591 * direct linking to a dll: WIN32. (line 218)
6592 * discarding sections: Output Section Discarding.
6594 * discontinuous memory: MEMORY. (line 6)
6595 * DLLs, creating: Options. (line 1483)
6596 * DLLs, linking to: Options. (line 1608)
6597 * dot: Location Counter. (line 6)
6598 * dot inside sections: Location Counter. (line 36)
6599 * dot outside sections: Location Counter. (line 66)
6600 * dynamic linker, from command line: Options. (line 829)
6601 * dynamic symbol table: Options. (line 179)
6602 * ELF program headers: PHDRS. (line 6)
6603 * emulation: Options. (line 340)
6604 * emulation, default: Environment. (line 21)
6605 * END (MRI): MRI. (line 62)
6606 * endianness: Options. (line 198)
6607 * entry point: Entry Point. (line 6)
6608 * entry point, from command line: Options. (line 158)
6609 * entry point, thumb: ARM. (line 17)
6610 * ENTRY(SYMBOL): Entry Point. (line 6)
6611 * error on valid input: Bug Criteria. (line 12)
6612 * example of linker script: Simple Example. (line 6)
6613 * exporting DLL symbols: WIN32. (line 19)
6614 * expression evaluation order: Evaluation. (line 6)
6615 * expression sections: Expression Section. (line 6)
6616 * expression, absolute: Builtin Functions. (line 10)
6617 * expressions: Expressions. (line 6)
6618 * EXTERN: Miscellaneous Commands.
6620 * fatal signal: Bug Criteria. (line 9)
6621 * file name wildcard patterns: Input Section Wildcards.
6623 * FILEHDR: PHDRS. (line 61)
6624 * filename symbols: Output Section Keywords.
6626 * fill pattern, entire section: Output Section Fill.
6628 * FILL(EXPRESSION): Output Section Data.
6630 * finalization function: Options. (line 250)
6631 * first input file: File Commands. (line 79)
6632 * first instruction: Entry Point. (line 6)
6633 * FIX_V4BX: ARM. (line 44)
6634 * FORCE_COMMON_ALLOCATION: Miscellaneous Commands.
6636 * forcing input section alignment: Forced Input Alignment.
6638 * forcing output section alignment: Forced Output Alignment.
6640 * forcing the creation of dynamic sections: Options. (line 432)
6641 * FORMAT (MRI): MRI. (line 66)
6642 * functions in expressions: Builtin Functions. (line 6)
6643 * garbage collection <1>: Input Section Keep. (line 6)
6644 * garbage collection: Options. (line 848)
6645 * generating optimized output: Options. (line 413)
6646 * GNU linker: Overview. (line 6)
6647 * GNUTARGET: Environment. (line 9)
6648 * GROUP(FILES): File Commands. (line 44)
6649 * grouping input files: File Commands. (line 44)
6650 * groups of archives: Options. (line 643)
6651 * H8/300 support: H8/300. (line 6)
6652 * header size: Builtin Functions. (line 183)
6653 * heap size: Options. (line 1519)
6654 * help: Options. (line 865)
6655 * holes: Location Counter. (line 12)
6656 * holes, filling: Output Section Data.
6658 * HPPA multiple sub-space stubs: HPPA ELF32. (line 6)
6659 * HPPA stub grouping: HPPA ELF32. (line 12)
6660 * i960 support: i960. (line 6)
6661 * image base: Options. (line 1526)
6662 * implicit linker scripts: Implicit Linker Scripts.
6664 * import libraries: WIN32. (line 10)
6665 * INCLUDE FILENAME: File Commands. (line 9)
6666 * including a linker script: File Commands. (line 9)
6667 * including an entire archive: Options. (line 1328)
6668 * incremental link: Options. (line 276)
6669 * INHIBIT_COMMON_ALLOCATION: Miscellaneous Commands.
6671 * initialization function: Options. (line 279)
6672 * initialized data in ROM: Output Section LMA. (line 26)
6673 * input file format in linker script: Format Commands. (line 35)
6674 * input filename symbols: Output Section Keywords.
6676 * input files in linker scripts: File Commands. (line 16)
6677 * input files, displaying: Options. (line 475)
6678 * input format: Options. (line 115)
6679 * input object files in linker scripts: File Commands. (line 16)
6680 * input section alignment: Forced Input Alignment.
6682 * input section basics: Input Section Basics.
6684 * input section wildcards: Input Section Wildcards.
6686 * input sections: Input Section. (line 6)
6687 * INPUT(FILES): File Commands. (line 16)
6688 * integer notation: Constants. (line 6)
6689 * integer suffixes: Constants. (line 12)
6690 * internal object-file format: Canonical format. (line 11)
6691 * invalid input: Bug Criteria. (line 14)
6692 * K and M integer suffixes: Constants. (line 12)
6693 * KEEP: Input Section Keep. (line 6)
6694 * l =: MEMORY. (line 72)
6695 * lazy evaluation: Evaluation. (line 6)
6696 * ld bugs, reporting: Bug Reporting. (line 6)
6697 * LDEMULATION: Environment. (line 21)
6698 * len =: MEMORY. (line 72)
6699 * LENGTH =: MEMORY. (line 72)
6700 * LENGTH(MEMORY): Builtin Functions. (line 135)
6701 * library search path in linker script: File Commands. (line 71)
6702 * link map: Options. (line 350)
6703 * link-time runtime library search path: Options. (line 1045)
6704 * linker crash: Bug Criteria. (line 9)
6705 * linker script concepts: Basic Script Concepts.
6707 * linker script example: Simple Example. (line 6)
6708 * linker script file commands: File Commands. (line 6)
6709 * linker script format: Script Format. (line 6)
6710 * linker script input object files: File Commands. (line 16)
6711 * linker script simple commands: Simple Commands. (line 6)
6712 * linker scripts: Scripts. (line 6)
6713 * LIST (MRI): MRI. (line 77)
6714 * little-endian objects: Options. (line 201)
6715 * LOAD (MRI): MRI. (line 84)
6716 * load address: Output Section LMA. (line 6)
6717 * LOADADDR(SECTION): Builtin Functions. (line 138)
6718 * loading, preventing: Output Section Type.
6720 * local symbols, deleting: Options. (line 538)
6721 * location counter: Location Counter. (line 6)
6722 * LONG(EXPRESSION): Output Section Data.
6724 * M and K integer suffixes: Constants. (line 12)
6725 * M68HC11 and 68HC12 support: M68HC11/68HC12. (line 6)
6726 * machine architecture: Miscellaneous Commands.
6728 * machine dependencies: Machine Dependent. (line 6)
6729 * mapping input sections to output sections: Input Section. (line 6)
6730 * MAX: Builtin Functions. (line 143)
6731 * MEMORY: MEMORY. (line 6)
6732 * memory region attributes: MEMORY. (line 32)
6733 * memory regions: MEMORY. (line 6)
6734 * memory regions and sections: Output Section Region.
6736 * memory usage: Options. (line 877)
6737 * MIN: Builtin Functions. (line 146)
6738 * MRI compatibility: MRI. (line 6)
6739 * MSP430 extra sections: MSP430. (line 11)
6740 * NAME (MRI): MRI. (line 90)
6741 * name, section: Output Section Name.
6743 * names: Symbols. (line 6)
6744 * naming the output file: Options. (line 407)
6745 * NEXT(EXP): Builtin Functions. (line 150)
6746 * NMAGIC: Options. (line 387)
6747 * NO_ENUM_SIZE_WARNING: ARM. (line 94)
6748 * NOCROSSREFS(SECTIONS): Miscellaneous Commands.
6750 * NOLOAD: Output Section Type.
6752 * not enough room for program headers: Builtin Functions. (line 188)
6753 * o =: MEMORY. (line 67)
6754 * objdump -i: BFD. (line 6)
6755 * object file management: BFD. (line 6)
6756 * object files: Options. (line 29)
6757 * object formats available: BFD. (line 6)
6758 * object size: Options. (line 259)
6759 * OMAGIC: Options. (line 392)
6760 * opening object files: BFD outline. (line 6)
6761 * operators for arithmetic: Operators. (line 6)
6762 * options: Options. (line 6)
6763 * ORDER (MRI): MRI. (line 95)
6764 * org =: MEMORY. (line 67)
6765 * ORIGIN =: MEMORY. (line 67)
6766 * ORIGIN(MEMORY): Builtin Functions. (line 156)
6767 * orphan: Orphan Sections. (line 6)
6768 * output file after errors: Options. (line 947)
6769 * output file format in linker script: Format Commands. (line 10)
6770 * output file name in linker script: File Commands. (line 61)
6771 * output section alignment: Forced Output Alignment.
6773 * output section attributes: Output Section Attributes.
6775 * output section data: Output Section Data.
6777 * OUTPUT(FILENAME): File Commands. (line 61)
6778 * OUTPUT_ARCH(BFDARCH): Miscellaneous Commands.
6780 * OUTPUT_FORMAT(BFDNAME): Format Commands. (line 10)
6781 * OVERLAY: Overlay Description.
6783 * overlays: Overlay Description.
6785 * partial link: Options. (line 436)
6786 * PHDRS: PHDRS. (line 6)
6787 * PIC_VENEER: M68HC11/68HC12. (line 38)
6788 * position independent executables: Options. (line 974)
6789 * PowerPC ELF32 options: PowerPC ELF32. (line 13)
6790 * PowerPC GOT: PowerPC ELF32. (line 30)
6791 * PowerPC long branches: PowerPC ELF32. (line 6)
6792 * PowerPC PLT: PowerPC ELF32. (line 13)
6793 * PowerPC stub symbols: PowerPC ELF32. (line 44)
6794 * PowerPC TLS optimization: PowerPC ELF32. (line 48)
6795 * PowerPC64 dot symbols: PowerPC64 ELF64. (line 33)
6796 * PowerPC64 ELF64 options: PowerPC64 ELF64. (line 6)
6797 * PowerPC64 multi-TOC: PowerPC64 ELF64. (line 74)
6798 * PowerPC64 OPD optimization: PowerPC64 ELF64. (line 48)
6799 * PowerPC64 OPD spacing: PowerPC64 ELF64. (line 54)
6800 * PowerPC64 stub grouping: PowerPC64 ELF64. (line 6)
6801 * PowerPC64 stub symbols: PowerPC64 ELF64. (line 29)
6802 * PowerPC64 TLS optimization: PowerPC64 ELF64. (line 43)
6803 * PowerPC64 TOC optimization: PowerPC64 ELF64. (line 60)
6804 * precedence in expressions: Operators. (line 6)
6805 * prevent unnecessary loading: Output Section Type.
6807 * program headers: PHDRS. (line 6)
6808 * program headers and sections: Output Section Phdr.
6810 * program headers, not enough room: Builtin Functions. (line 188)
6811 * program segments: PHDRS. (line 6)
6812 * PROVIDE: PROVIDE. (line 6)
6813 * PROVIDE_HIDDEN: PROVIDE_HIDDEN. (line 6)
6814 * PUBLIC (MRI): MRI. (line 103)
6815 * QUAD(EXPRESSION): Output Section Data.
6817 * quoted symbol names: Symbols. (line 6)
6818 * read-only text: Options. (line 387)
6819 * read/write from cmd line: Options. (line 392)
6820 * regions of memory: MEMORY. (line 6)
6821 * relative expressions: Expression Section. (line 6)
6822 * relaxing addressing modes: Options. (line 988)
6823 * relaxing on H8/300: H8/300. (line 9)
6824 * relaxing on i960: i960. (line 31)
6825 * relaxing on M68HC11: M68HC11/68HC12. (line 12)
6826 * relaxing on Xtensa: Xtensa. (line 27)
6827 * relocatable and absolute symbols: Expression Section. (line 6)
6828 * relocatable output: Options. (line 436)
6829 * removing sections: Output Section Discarding.
6831 * reporting bugs in ld: Reporting Bugs. (line 6)
6832 * requirements for BFD: BFD. (line 16)
6833 * retain relocations in final executable: Options. (line 423)
6834 * retaining specified symbols: Options. (line 1009)
6835 * ROM initialized data: Output Section LMA. (line 26)
6836 * round up expression: Builtin Functions. (line 36)
6837 * round up location counter: Builtin Functions. (line 36)
6838 * runtime library name: Options. (line 267)
6839 * runtime library search path: Options. (line 1023)
6840 * runtime pseudo-relocation: WIN32. (line 196)
6841 * scaled integers: Constants. (line 12)
6842 * scommon section: Input Section Common.
6844 * script files: Options. (line 479)
6845 * scripts: Scripts. (line 6)
6846 * search directory, from cmd line: Options. (line 318)
6847 * search path in linker script: File Commands. (line 71)
6848 * SEARCH_DIR(PATH): File Commands. (line 71)
6849 * SECT (MRI): MRI. (line 109)
6850 * section address: Output Section Address.
6852 * section address in expression: Builtin Functions. (line 17)
6853 * section alignment: Builtin Functions. (line 62)
6854 * section alignment, warnings on: Options. (line 1309)
6855 * section data: Output Section Data.
6857 * section fill pattern: Output Section Fill.
6859 * section load address: Output Section LMA. (line 6)
6860 * section load address in expression: Builtin Functions. (line 138)
6861 * section name: Output Section Name.
6863 * section name wildcard patterns: Input Section Wildcards.
6865 * section size: Builtin Functions. (line 167)
6866 * section, assigning to memory region: Output Section Region.
6868 * section, assigning to program header: Output Section Phdr.
6870 * SECTIONS: SECTIONS. (line 6)
6871 * sections, discarding: Output Section Discarding.
6873 * segment origins, cmd line: Options. (line 1170)
6874 * SEGMENT_START(SEGMENT, DEFAULT): Builtin Functions. (line 159)
6875 * segments, ELF: PHDRS. (line 6)
6876 * shared libraries: Options. (line 1102)
6877 * SHORT(EXPRESSION): Output Section Data.
6879 * SIZEOF(SECTION): Builtin Functions. (line 167)
6880 * SIZEOF_HEADERS: Builtin Functions. (line 183)
6881 * small common symbols: Input Section Common.
6883 * SORT: Input Section Wildcards.
6885 * SORT_BY_ALIGNMENT: Input Section Wildcards.
6887 * SORT_BY_NAME: Input Section Wildcards.
6889 * SPU: SPU ELF. (line 29)
6890 * SPU ELF options: SPU ELF. (line 6)
6891 * SPU extra overlay stubs: SPU ELF. (line 19)
6892 * SPU local store size: SPU ELF. (line 24)
6893 * SPU overlay stub symbols: SPU ELF. (line 15)
6894 * SPU overlays: SPU ELF. (line 9)
6895 * SPU plugins: SPU ELF. (line 6)
6896 * SQUAD(EXPRESSION): Output Section Data.
6898 * stack size: Options. (line 1760)
6899 * standard Unix system: Options. (line 7)
6900 * start of execution: Entry Point. (line 6)
6901 * STARTUP(FILENAME): File Commands. (line 79)
6902 * strip all symbols: Options. (line 466)
6903 * strip debugger symbols: Options. (line 470)
6904 * stripping all but some symbols: Options. (line 1009)
6905 * SUBALIGN(SUBSECTION_ALIGN): Forced Input Alignment.
6907 * suffixes for integers: Constants. (line 12)
6908 * symbol defaults: Builtin Functions. (line 118)
6909 * symbol definition, scripts: Assignments. (line 6)
6910 * symbol names: Symbols. (line 6)
6911 * symbol tracing: Options. (line 544)
6912 * symbol versions: VERSION. (line 6)
6913 * symbol-only input: Options. (line 455)
6914 * symbols, from command line: Options. (line 803)
6915 * symbols, relocatable and absolute: Expression Section. (line 6)
6916 * symbols, retaining selectively: Options. (line 1009)
6917 * synthesizing linker: Options. (line 988)
6918 * synthesizing on H8/300: H8/300. (line 14)
6919 * TARGET(BFDNAME): Format Commands. (line 35)
6920 * TARGET1: ARM. (line 27)
6921 * TARGET2: ARM. (line 32)
6922 * thumb entry point: ARM. (line 17)
6923 * TI COFF versions: TI COFF. (line 6)
6924 * traditional format: Options. (line 1149)
6925 * trampoline generation on M68HC11: M68HC11/68HC12. (line 31)
6926 * trampoline generation on M68HC12: M68HC11/68HC12. (line 31)
6927 * unallocated address, next: Builtin Functions. (line 150)
6928 * undefined symbol: Options. (line 501)
6929 * undefined symbol in linker script: Miscellaneous Commands.
6931 * undefined symbols, warnings on: Options. (line 1305)
6932 * uninitialized data placement: Input Section Common.
6934 * unspecified memory: Output Section Data.
6936 * usage: Options. (line 865)
6937 * USE_BLX: ARM. (line 57)
6938 * using a DEF file: WIN32. (line 42)
6939 * using auto-export functionality: WIN32. (line 22)
6940 * Using decorations: WIN32. (line 141)
6941 * variables, defining: Assignments. (line 6)
6942 * verbose: Options. (line 1205)
6943 * version: Options. (line 528)
6944 * version script: VERSION. (line 6)
6945 * version script, symbol versions: Options. (line 1211)
6946 * VERSION {script text}: VERSION. (line 6)
6947 * versions of symbols: VERSION. (line 6)
6948 * VFP11_DENORM_FIX: ARM. (line 66)
6949 * warnings, on combining symbols: Options. (line 1218)
6950 * warnings, on section alignment: Options. (line 1309)
6951 * warnings, on undefined symbols: Options. (line 1305)
6952 * weak externals: WIN32. (line 386)
6953 * what is this?: Overview. (line 6)
6954 * wildcard file name patterns: Input Section Wildcards.
6956 * Xtensa options: Xtensa. (line 56)
6957 * Xtensa processors: Xtensa. (line 6)
6963 Node: Overview
\x7f1524
6964 Node: Invocation
\x7f2638
6965 Node: Options
\x7f3046
6966 Node: Environment
\x7f83631
6967 Node: Scripts
\x7f85391
6968 Node: Basic Script Concepts
\x7f87125
6969 Node: Script Format
\x7f89832
6970 Node: Simple Example
\x7f90695
6971 Node: Simple Commands
\x7f93791
6972 Node: Entry Point
\x7f94242
6973 Node: File Commands
\x7f95001
6974 Node: Format Commands
\x7f98867
6975 Node: Miscellaneous Commands
\x7f100833
6976 Node: Assignments
\x7f103063
6977 Node: Simple Assignments
\x7f103554
6978 Node: PROVIDE
\x7f105290
6979 Node: PROVIDE_HIDDEN
\x7f106495
6980 Node: Source Code Reference
\x7f106739
6981 Node: SECTIONS
\x7f110319
6982 Node: Output Section Description
\x7f112210
6983 Node: Output Section Name
\x7f113263
6984 Node: Output Section Address
\x7f114139
6985 Node: Input Section
\x7f115788
6986 Node: Input Section Basics
\x7f116589
6987 Node: Input Section Wildcards
\x7f118939
6988 Node: Input Section Common
\x7f123672
6989 Node: Input Section Keep
\x7f125154
6990 Node: Input Section Example
\x7f125644
6991 Node: Output Section Data
\x7f126612
6992 Node: Output Section Keywords
\x7f129389
6993 Node: Output Section Discarding
\x7f132958
6994 Node: Output Section Attributes
\x7f134139
6995 Node: Output Section Type
\x7f135143
6996 Node: Output Section LMA
\x7f136297
6997 Node: Forced Output Alignment
\x7f138810
6998 Node: Forced Input Alignment
\x7f139078
6999 Node: Output Section Region
\x7f139463
7000 Node: Output Section Phdr
\x7f139893
7001 Node: Output Section Fill
\x7f140557
7002 Node: Overlay Description
\x7f141699
7003 Node: MEMORY
\x7f146002
7004 Node: PHDRS
\x7f150202
7005 Node: VERSION
\x7f155241
7006 Node: Expressions
\x7f163033
7007 Node: Constants
\x7f163911
7008 Node: Symbols
\x7f164472
7009 Node: Orphan Sections
\x7f165210
7010 Node: Location Counter
\x7f165973
7011 Node: Operators
\x7f170409
7012 Node: Evaluation
\x7f171331
7013 Node: Expression Section
\x7f172695
7014 Node: Builtin Functions
\x7f174184
7015 Node: Implicit Linker Scripts
\x7f182151
7016 Node: Machine Dependent
\x7f182926
7017 Node: H8/300
\x7f183897
7018 Node: i960
\x7f185522
7019 Node: M68HC11/68HC12
\x7f187207
7021 Node: HPPA ELF32
\x7f193760
7022 Node: MMIX
\x7f195383
7023 Node: MSP430
\x7f196600
7024 Node: PowerPC ELF32
\x7f197649
7025 Node: PowerPC64 ELF64
\x7f200263
7026 Node: SPU ELF
\x7f204677
7027 Node: TI COFF
\x7f207309
7028 Node: WIN32
\x7f207835
7029 Node: Xtensa
\x7f226192
7031 Node: BFD outline
\x7f230769
7032 Node: BFD information loss
\x7f232055
7033 Node: Canonical format
\x7f234572
7034 Node: Reporting Bugs
\x7f238929
7035 Node: Bug Criteria
\x7f239623
7036 Node: Bug Reporting
\x7f240322
7038 Node: GNU Free Documentation License
\x7f252004
7039 Node: LD Index
\x7f271721