8 This file documents the GNU linker ld version "2.17.50 [FreeBSD] 2007-07-03".
10 This document is distributed under the terms of the GNU Free Documentation
11 License. A copy of the license is included in the section entitled \(lqGNU Free
12 Documentation License\(rq.
16 combines a number of object and archive files, relocates their data and ties
17 up symbol references. Usually the last step in compiling a program is to run
21 accepts Linker Command Language files written in a superset of AT&T's Link
22 Editor Command Language syntax, to provide explicit and total control over
27 uses the general purpose BFD libraries to operate on object files. This allows
29 to read, combine, and write object files in many different formats---for example,
32 Different formats may be linked together to produce any available kind of
33 object file.See Section
37 Aside from its flexibility, the GNU linker is more helpful than other linkers
38 in providing diagnostic information. Many linkers abandon execution immediately
39 upon encountering an error; whenever possible,
41 continues executing, allowing you to identify other errors (or, in some cases,
42 to get an output file in spite of the error).
47 is meant to cover a broad range of situations, and to be as compatible as
48 possible with other linkers. As a result, you have many choices to control
51 .Ss Command Line Options
52 The linker supports a plethora of command-line options, but in actual practice
53 few of them are used in any particular context. For instance, a frequent use
56 is to link standard Unix object files on a standard, supported Unix system.
57 On such a system, to link a file
60 .Bd -literal -offset indent
61 ld -o output /lib/crt0.o hello.o -lc
66 to produce a file called
68 as the result of linking the file
74 which will come from the standard search directories. (See the discussion
79 Some of the command-line options to
81 may be specified at any point in the command line. However, options which
82 refer to files, such as
86 cause the file to be read at the point at which the option appears in the
87 command line, relative to the object files and other file options. Repeating
88 non-file options with a different argument will either have no further effect,
89 or override prior occurrences (those further to the left on the command line)
90 of that option. Options which may be meaningfully specified more than once
91 are noted in the descriptions below.
93 Non-option arguments are object files or archives which are to be linked together.
94 They may follow, precede, or be mixed in with command-line options, except
95 that an object file argument may not be placed between an option and its argument.
97 Usually the linker is invoked with at least one object file, but you can specify
98 other forms of binary input files using
101 and the script command language. If
103 binary input files at all are specified, the linker does not produce any output,
104 and issues the message
107 If the linker cannot recognize the format of an object file, it will assume
108 that it is a linker script. A script specified in this way augments the main
109 linker script used for the link (either the default linker script or the one
112 This feature permits the linker to link against a file which appears to be
113 an object or an archive, but actually merely defines some symbol values, or
118 to load other objects. Note that specifying a script in this way merely augments
119 the main linker script; use the
121 option to replace the default linker script entirely.See Section
124 For options whose names are a single letter, option arguments must either
125 follow the option letter without intervening whitespace, or be given as separate
126 arguments immediately following the option that requires them.
128 For options whose names are multiple letters, either one dash or two can precede
129 the option name; for example,
133 are equivalent. Note---there is one exception to this rule. Multiple letter
134 options that start with a lower case 'o' can only be preceded by two dashes.
135 This is to reduce confusion with the
137 option. So for example
139 sets the output file name to
143 sets the NMAGIC flag on the output.
145 Arguments to multiple-letter options must either be separated from the option
146 name by an equals sign, or be given as separate arguments immediately following
147 the option that requires them. For example,
148 .Li --trace-symbol foo
150 .Li --trace-symbol=foo
151 are equivalent. Unique abbreviations of the names of multiple-letter options
154 Note---if the linker is being invoked indirectly, via a compiler driver (e.g.
156 then all the linker command line options should be prefixed by
158 (or whatever is appropriate for the particular compiler driver) like this:
160 .Bd -literal -offset indent
161 gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
164 This is important, because otherwise the compiler driver program may silently
165 drop the linker options, resulting in a bad link.
167 Here is a table of the generic command line switches accepted by the GNU linker:
171 Read command-line options from
173 The options read are inserted in place of the original @
177 does not exist, or cannot be read, then the option will be treated literally,
182 are separated by whitespace. A whitespace character may be included in an
183 option by surrounding the entire option in either single or double quotes.
184 Any character (including a backslash) may be included by prefixing the character
185 to be included with a backslash. The
187 may itself contain additional @
189 options; any such options will be processed recursively.
192 This option is supported for HP/UX compatibility. The
194 argument must be one of the strings
200 is functionally equivalent to
202 and the other two keywords are functionally equivalent to
204 This option may be used any number of times.
206 .It -A Va architecture
207 .It --architecture= Va architecture
208 In the current release of
210 this option is useful only for the Intel 960 family of architectures. In that
214 argument identifies the particular architecture in the 960 family, enabling
215 some safeguards and modifying the archive-library search path.See Section
221 may support similar functionality for other architecture families.
223 .It -b Va input-format
224 .It --format= Va input-format
226 may be configured to support more than one kind of object file. If your
228 is configured this way, you can use the
230 option to specify the binary format for input object files that follow this
231 option on the command line. Even when
233 is configured to support alternative object formats, you don't usually need
236 should be configured to expect as a default input format the most usual format
239 is a text string, the name of a particular format supported by the BFD libraries.
240 (You can list the available binary formats with
244 You may want to use this option if you are linking files with an unusual binary
245 format. You can also use
247 to switch formats explicitly (when linking object files of different formats),
249 .Li -b Va input-format
250 before each group of object files in a particular format.
252 The default format is taken from the environment variable
254 See Section.Dq Environment .
255 You can also define the input format from a script, using the command
259 .It -c Va MRI-commandfile
260 .It --mri-script= Va MRI-commandfile
261 For compatibility with linkers produced by MRI,
263 accepts script files written in an alternate, restricted command language,
264 described in MRI,,MRI Compatible Script Files. Introduce MRI script files
269 option to run linker scripts written in the general-purpose
271 scripting language. If
275 looks for it in the directories specified by any
282 These three options are equivalent; multiple forms are supported for compatibility
283 with other linkers. They assign space to common symbols even if a relocatable
284 output file is specified (with
287 .Li FORCE_COMMON_ALLOCATION
288 has the same effect.See Section
289 .Dq Miscellaneous Commands .
292 .It --entry= Va entry
295 as the explicit symbol for beginning execution of your program, rather than
296 the default entry point. If there is no symbol named
298 the linker will try to parse
300 as a number, and use that as the entry address (the number will be interpreted
301 in base 10; you may use a leading
303 for base 16, or a leading
305 for base 8).See Section
307 for a discussion of defaults and other ways of specifying the entry point.
309 .It --exclude-libs Va lib, Va lib,...
310 Specifies a list of archive libraries from which symbols should not be automatically
311 exported. The library names may be delimited by commas or colons. Specifying
312 .Li --exclude-libs ALL
313 excludes symbols in all archive libraries from automatic export. This option
314 is available only for the i386 PE targeted port of the linker and for ELF
315 targeted ports. For i386 PE, symbols explicitly listed in a .def file are
316 still exported, regardless of this option. For ELF targeted ports, symbols
317 affected by this option will be treated as hidden.
321 When creating a dynamically linked executable, add all symbols to the dynamic
322 symbol table. The dynamic symbol table is the set of symbols which are visible
323 from dynamic objects at run time.
325 If you do not use this option, the dynamic symbol table will normally contain
326 only those symbols which are referenced by some dynamic object mentioned in
331 to load a dynamic object which needs to refer back to the symbols defined
332 by the program, rather than some other dynamic object, then you will probably
333 need to use this option when linking the program itself.
335 You can also use the dynamic list to control what symbols should be added
336 to the dynamic symbol table if the output format supports it. See the description
341 Link big-endian objects. This affects the default output format.
344 Link little-endian objects. This affects the default output format.
347 .It --auxiliary Va name
348 When creating an ELF shared object, set the internal DT_AUXILIARY field to
349 the specified name. This tells the dynamic linker that the symbol table of
350 the shared object should be used as an auxiliary filter on the symbol table
354 If you later link a program against this filter object, then, when you run
355 the program, the dynamic linker will see the DT_AUXILIARY field. If the dynamic
356 linker resolves any symbols from the filter object, it will first check whether
357 there is a definition in the shared object
359 If there is one, it will be used instead of the definition in the filter object.
362 need not exist. Thus the shared object
364 may be used to provide an alternative implementation of certain functions,
365 perhaps for debugging or for machine specific performance.
367 This option may be specified more than once. The DT_AUXILIARY entries will
368 be created in the order in which they appear on the command line.
372 When creating an ELF shared object, set the internal DT_FILTER field to the
373 specified name. This tells the dynamic linker that the symbol table of the
374 shared object which is being created should be used as a filter on the symbol
375 table of the shared object
378 If you later link a program against this filter object, then, when you run
379 the program, the dynamic linker will see the DT_FILTER field. The dynamic
380 linker will resolve symbols according to the symbol table of the filter object
381 as usual, but it will actually link to the definitions found in the shared
384 Thus the filter object can be used to select a subset of the symbols provided
388 Some older linkers used the
390 option throughout a compilation toolchain for specifying object-file format
391 for both input and output object files. The GNU linker uses other mechanisms
392 for this purpose: the
398 command in linker scripts, and the
400 environment variable. The GNU linker will ignore the
402 option when not creating an ELF shared object.
405 When creating an ELF executable or shared object, call NAME when the executable
406 or shared object is unloaded, by setting DT_FINI to the address of the function.
407 By default, the linker uses
409 as the function to call.
412 Ignored. Provided for compatibility with other tools.
415 .It --gpsize= Va value
416 Set the maximum size of objects to be optimized using the GP register to
418 This is only meaningful for object file formats such as MIPS ECOFF which supports
419 putting large and small objects into different sections. This is ignored for
420 other object file formats.
424 When creating an ELF shared object, set the internal DT_SONAME field to the
425 specified name. When an executable is linked with a shared object which has
426 a DT_SONAME field, then when the executable is run the dynamic linker will
427 attempt to load the shared object specified by the DT_SONAME field rather
428 than the using the file name given to the linker.
431 Perform an incremental link (same as option
435 When creating an ELF executable or shared object, call NAME when the executable
436 or shared object is loaded, by setting DT_INIT to the address of the function.
437 By default, the linker uses
439 as the function to call.
442 .It --library= Va namespec
443 Add the archive or object file specified by
445 to the list of files to link. This option may be used any number of times.
451 will search the library path for a file called
453 otherise it will search the library path for a file called
454 .Pa lib Va namespec.a .
456 On systems which support shared libraries,
458 may also search for files other than
459 .Pa lib Va namespec.a .
460 Specifically, on ELF and SunOS systems,
462 will search a directory for a library called
463 .Pa lib Va namespec.so
464 before searching for one called
465 .Pa lib Va namespec.a .
468 extension indicates a shared library.) Note that this behavior does not apply
471 which always specifies a file called
474 The linker will search an archive only once, at the location where it is specified
475 on the command line. If the archive defines a symbol which was undefined in
476 some object which appeared before the archive on the command line, the linker
477 will include the appropriate file(s) from the archive. However, an undefined
478 symbol in an object appearing later on the command line will not cause the
479 linker to search the archive again.
483 option for a way to force the linker to search archives multiple times.
485 You may list the same archive multiple times on the command line.
487 This type of archive searching is standard for Unix linkers. However, if you
490 on AIX, note that it is different from the behaviour of the AIX linker.
493 .It --library-path= Va searchdir
496 to the list of paths that
498 will search for archive libraries and
500 control scripts. You may use this option any number of times. The directories
501 are searched in the order in which they are specified on the command line.
502 Directories specified on the command line are searched before the default
507 options, regardless of the order in which the options appear.
515 will be replaced by the
517 a path specified when the linker is configured.
519 The default set of paths searched (without being specified with
521 depends on which emulation mode
523 is using, and in some cases also on how it was configured.See Section
526 The paths can also be specified in a link script with the
528 command. Directories specified this way are searched at the point in which
529 the linker script appears in the command line.
534 linker. You can list the available emulations with the
542 option is not used, the emulation is taken from the
544 environment variable, if that is defined.
546 Otherwise, the default emulation depends upon how the linker was configured.
550 Print a link map to the standard output. A link map provides information about
551 the link, including the following:
555 Where object files are mapped into memory.
557 How common symbols are allocated.
559 All archive members included in the link, with a mention of the symbol which
560 caused the archive member to be brought in.
562 The values assigned to symbols.
564 Note - symbols whose values are computed by an expression which involves a
565 reference to a previous value of the same symbol may not have correct result
566 displayed in the link map. This is because the linker discards intermediate
567 results and only retains the final value of an expression. Under such circumstances
568 the linker will display the final value enclosed by square brackets. Thus
569 for example a linker script containing:
571 .Bd -literal -offset indent
577 will produce the following output in the link map if the
581 .Bd -literal -offset indent
583 [0x0000000c] foo = (foo * 0x4)
584 [0x0000000c] foo = (foo + 0x8)
587 See Expressions for more information about expressions in linker scripts.
592 Turn off page alignment of sections, and mark the output as
598 Set the text and data sections to be readable and writable. Also, do not page-align
599 the data segment, and disable linking against shared libraries. If the output
600 format supports Unix style magic numbers, mark the output as
602 Note: Although a writable text section is allowed for PE-COFF targets, it
603 does not conform to the format specification published by Microsoft.
606 This option negates most of the effects of the
608 option. It sets the text section to be read-only, and forces the data segment
609 to be page-aligned. Note - this option does not enable linking against shared
615 .It --output= Va output
618 as the name for the program produced by
620 if this option is not specified, the name
622 is used by default. The script command
624 can also specify the output file name.
629 is a numeric values greater than zero
631 optimizes the output. This might take significantly longer and therefore probably
632 should only be enabled for the final binary.
636 Leave relocation sections and contents in fully linked executables. Post link
637 analysis and optimization tools may need this information in order to perform
638 correct modifications of executables. This results in larger executables.
640 This option is currently only supported on ELF platforms.
643 Force the output file to have dynamic sections. This option is specific to
648 Generate relocatable output---i.e., generate an output file that can in turn
652 .Em partial linking .
653 As a side effect, in environments that support standard Unix magic numbers,
654 this option also sets the output file's magic number to
656 If this option is not specified, an absolute file is produced. When linking
657 C++ programs, this option
659 resolve references to constructors; to do that, use
662 When an input file does not have the same format as the output file, partial
663 linking is only supported if that input file does not contain any relocations.
664 Different output formats can have further restrictions; for example some
666 -based formats do not support partial linking with input files in other formats
669 This option does the same thing as
673 .It --just-symbols= Va filename
674 Read symbol names and their addresses from
676 but do not relocate it or include it in the output. This allows your output
677 file to refer symbolically to absolute locations of memory defined in other
678 programs. You may use this option more than once.
680 For compatibility with other ELF linkers, if the
682 option is followed by a directory name, rather than a file name, it is treated
689 Omit all symbol information from the output file.
693 Omit debugger symbol information (but not all symbols) from the output file.
697 Print the names of the input files as
702 .It --script= Va scriptfile
705 as the linker script. This script replaces
707 \&'s default linker script (rather than adding to it), so
709 must specify everything necessary to describe the output file.See Section
713 does not exist in the current directory,
715 looks for it in the directories specified by any preceding
721 .It -dT Va scriptfile
722 .It --default-script= Va scriptfile
725 as the default linker script.See Section
728 This option is similar to the
730 option except that processing of the script is delayed until after the rest
731 of the command line has been processed. This allows options placed after the
733 option on the command line to affect the behaviour of the linker script, which
734 can be important when the linker command line cannot be directly controlled
735 by the user. (eg because the command line is being constructed by another
740 .It --undefined= Va symbol
743 to be entered in the output file as an undefined symbol. Doing this may, for
744 example, trigger linking of additional modules from standard libraries.
746 may be repeated with different option arguments to enter additional undefined
747 symbols. This option is equivalent to the
749 linker script command.
752 For anything other than C++ programs, this option is equivalent to
754 it generates relocatable output---i.e., an output file that can in turn serve
757 When linking C++ programs,
760 resolve references to constructors, unlike
762 It does not work to use
764 on files that were themselves linked with
766 once the constructor table has been built, it cannot be added to. Use
768 only for the last partial link, and
772 .It --unique[= Va SECTION]
773 Creates a separate output section for every input section matching
775 or if the optional wildcard
777 argument is missing, for every orphan input section. An orphan section is
778 one not specifically mentioned in a linker script. You may use this option
779 multiple times on the command line; It prevents the normal merging of input
780 sections with the same name, overriding output section assignments in a linker
786 Display the version number for
790 option also lists the supported emulations.
794 Delete all local symbols.
798 Delete all temporary local symbols. (These symbols start with system-specific
799 local label prefixes, typically
803 for traditional a.out systems.)
806 .It --trace-symbol= Va symbol
807 Print the name of each linked file in which
809 appears. This option may be given any number of times. On many systems it
810 is necessary to prepend an underscore.
812 This option is useful when you have an undefined symbol in your link but don't
813 know where the reference is coming from.
818 to the default library search path. This option exists for Solaris compatibility.
821 The recognized keywords are:
824 Combines multiple reloc sections and sorts them to make dynamic symbol lookup
828 Disallows undefined symbols in object files. Undefined symbols in shared libraries
832 Marks the object as requiring executable stack.
835 This option is only meaningful when building a shared object. It marks the
836 object so that its runtime initialization will occur before the runtime initialization
837 of any other objects brought into the process at the same time. Similarly
838 the runtime finalization of the object will occur after the runtime finalization
839 of any other objects.
842 Marks the object that its symbol table interposes before all symbols but the
846 When generating an executable or shared library, mark it to tell the dynamic
847 linker to defer function call resolution to the point when the function is
848 called (lazy binding), rather than at load time. Lazy binding is the default.
851 Marks the object that its filters be processed immediately at runtime.
854 Allows multiple definitions.
857 Disables multiple reloc sections combining.
860 Disables production of copy relocs.
863 Marks the object that the search for dependencies of this object will ignore
864 any default library search paths.
867 Marks the object shouldn't be unloaded at runtime.
870 Marks the object not available to
874 Marks the object can not be dumped by
878 Marks the object as not requiring executable stack.
883 segment header in the object.
886 When generating an executable or shared library, mark it to tell the dynamic
887 linker to resolve all symbols when the program is started, or when the shared
888 library is linked to using dlopen, instead of deferring function call resolution
889 to the point when the function is first called.
892 Marks the object may contain $ORIGIN.
897 segment header in the object.
899 .It max-page-size= Va value
900 Set the emulation maximum page size to
903 .It common-page-size= Va value
904 Set the emulation common page size to
908 Other keywords are ignored for Solaris compatibility.
910 .It -( Va archives -)
911 .It --start-group Va archives --end-group
914 should be a list of archive files. They may be either explicit file names,
919 The specified archives are searched repeatedly until no new undefined references
920 are created. Normally, an archive is searched only once in the order that
921 it is specified on the command line. If a symbol in that archive is needed
922 to resolve an undefined symbol referred to by an object in an archive that
923 appears later on the command line, the linker would not be able to resolve
924 that reference. By grouping the archives, they all be searched repeatedly
925 until all possible references are resolved.
927 Using this option has a significant performance cost. It is best to use it
928 only when there are unavoidable circular references between two or more archives.
930 .It --accept-unknown-input-arch
931 .It --no-accept-unknown-input-arch
932 Tells the linker to accept input files whose architecture cannot be recognised.
933 The assumption is that the user knows what they are doing and deliberately
934 wants to link in these unknown input files. This was the default behaviour
935 of the linker, before release 2.14. The default behaviour from release 2.14
936 onwards is to reject such input files, and so the
937 .Li --accept-unknown-input-arch
938 option has been added to restore the old behaviour.
942 This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on
943 the command line after the
945 option. Normally, the linker will add a DT_NEEDED tag for each dynamic library
946 mentioned on the command line, regardless of whether the library is actually
949 causes DT_NEEDED tags to only be emitted for libraries that satisfy some symbol
950 reference from regular objects which is undefined at the point that the library
953 restores the default behaviour.
957 This option affects the treatment of dynamic libraries from ELF DT_NEEDED
958 tags in dynamic libraries mentioned on the command line after the
960 option. Normally, the linker will add a DT_NEEDED tag for each dynamic library
963 causes DT_NEEDED tags will never be emitted for those libraries from DT_NEEDED
966 restores the default behaviour.
968 .It -assert Va keyword
969 This option is ignored for SunOS compatibility.
974 Link against dynamic libraries. This is only meaningful on platforms for which
975 shared libraries are supported. This option is normally the default on such
976 platforms. The different variants of this option are for compatibility with
977 various systems. You may use this option multiple times on the command line:
978 it affects library searching for
980 options which follow it.
987 entry in the dynamic section. This causes the runtime linker to handle lookups
988 in this object and its dependencies to be performed only inside the group.
989 .Op --unresolved-symbols=report-all
990 is implied. This option is only meaningful on ELF platforms which support
997 Do not link against shared libraries. This is only meaningful on platforms
998 for which shared libraries are supported. The different variants of this option
999 are for compatibility with various systems. You may use this option multiple
1000 times on the command line: it affects library searching for
1002 options which follow it. This option also implies
1003 .Op --unresolved-symbols=report-all .
1004 This option can be used with
1006 Doing so means that a shared library is being created but that all of the
1007 library's external references must be resolved by pulling in entries from
1011 When creating a shared library, bind references to global symbols to the definition
1012 within the shared library, if any. Normally, it is possible for a program
1013 linked against a shared library to override the definition within the shared
1014 library. This option is only meaningful on ELF platforms which support shared
1017 .It -Bsymbolic-functions
1018 When creating a shared library, bind references to global function symbols
1019 to the definition within the shared library, if any. This option is only meaningful
1020 on ELF platforms which support shared libraries.
1022 .It --dynamic-list= Va dynamic-list-file
1023 Specify the name of a dynamic list file to the linker. This is typically used
1024 when creating shared libraries to specify a list of global symbols whose references
1025 shouldn't be bound to the definition within the shared library, or creating
1026 dynamically linked executables to specify a list of symbols which should be
1027 added to the symbol table in the executable. This option is only meaningful
1028 on ELF platforms which support shared libraries.
1030 The format of the dynamic list is the same as the version node without scope
1031 and node name. See VERSION for more information.
1033 .It --dynamic-list-data
1034 Include all global data symbols to the dynamic list.
1036 .It --dynamic-list-cpp-new
1037 Provide the builtin dynamic list for C++ operator new and delete. It is mainly
1038 useful for building shared libstdc++.
1040 .It --dynamic-list-cpp-typeinfo
1041 Provide the builtin dynamic list for C++ runtime type identification.
1043 .It --check-sections
1044 .It --no-check-sections
1047 to check section addresses after they have been assigned to see if there are
1048 any overlaps. Normally the linker will perform this check, and if it finds
1049 any overlaps it will produce suitable error messages. The linker does know
1050 about, and does make allowances for sections in overlays. The default behaviour
1051 can be restored by using the command line switch
1052 .Op --check-sections .
1055 Output a cross reference table. If a linker map file is being generated, the
1056 cross reference table is printed to the map file. Otherwise, it is printed
1057 on the standard output.
1059 The format of the table is intentionally simple, so that it may be easily
1060 processed by a script if necessary. The symbols are printed out, sorted by
1061 name. For each symbol, a list of file names is given. If the symbol is defined,
1062 the first file listed is the location of the definition. The remaining files
1063 contain references to the symbol.
1065 .It --no-define-common
1066 This option inhibits the assignment of addresses to common symbols. The script
1068 .Li INHIBIT_COMMON_ALLOCATION
1069 has the same effect.See Section
1070 .Dq Miscellaneous Commands .
1073 .Li --no-define-common
1074 option allows decoupling the decision to assign addresses to Common symbols
1075 from the choice of the output file type; otherwise a non-Relocatable output
1076 type forces assigning addresses to Common symbols. Using
1077 .Li --no-define-common
1078 allows Common symbols that are referenced from a shared library to be assigned
1079 addresses only in the main program. This eliminates the unused duplicate space
1080 in the shared library, and also prevents any possible confusion over resolving
1081 to the wrong duplicate when there are many dynamic modules with specialized
1082 search paths for runtime symbol resolution.
1084 .It --defsym Va symbol= Va expression
1085 Create a global symbol in the output file, containing the absolute address
1088 You may use this option as many times as necessary to define multiple symbols
1089 in the command line. A limited form of arithmetic is supported for the
1091 in this context: you may give a hexadecimal constant or the name of an existing
1096 to add or subtract hexadecimal constants or symbols. If you need more elaborate
1097 expressions, consider using the linker command language from a script (see Section
1100 there should be no white space between
1102 the equals sign (\(lq=\(rq), and
1105 .It --demangle[= Va style]
1107 These options control whether to demangle symbol names in error messages and
1108 other output. When the linker is told to demangle, it tries to present symbol
1109 names in a readable fashion: it strips leading underscores if they are used
1110 by the object file format, and converts C++ mangled symbol names into user
1111 readable names. Different compilers have different mangling styles. The optional
1112 demangling style argument can be used to choose an appropriate demangling
1113 style for your compiler. The linker will demangle by default unless the environment
1115 .Li COLLECT_NO_DEMANGLE
1116 is set. These options may be used to override the default.
1118 .It --dynamic-linker Va file
1119 Set the name of the dynamic linker. This is only meaningful when generating
1120 dynamically linked ELF executables. The default dynamic linker is normally
1121 correct; don't use this unless you know what you are doing.
1123 .It --fatal-warnings
1124 Treat all warnings as errors.
1126 .It --force-exe-suffix
1127 Make sure that an output file has a .exe suffix.
1129 If a successfully built fully linked output file does not have a
1133 suffix, this option forces the linker to copy the output file to one of the
1136 suffix. This option is useful when using unmodified Unix makefiles on a Microsoft
1137 Windows host, since some versions of Windows won't run an image unless it
1143 .It --no-gc-sections
1144 Enable garbage collection of unused input sections. It is ignored on targets
1145 that do not support this option. This option is not compatible with
1149 The default behaviour (of not performing this garbage collection) can be restored
1151 .Li --no-gc-sections
1152 on the command line.
1154 .It --print-gc-sections
1155 .It --no-print-gc-sections
1156 List all sections removed by garbage collection. The listing is printed on
1157 stderr. This option is only effective if garbage collection has been enabled
1160 option. The default behaviour (of not listing the sections that are removed)
1161 can be restored by specifying
1162 .Li --no-print-gc-sections
1163 on the command line.
1166 Print a summary of the command-line options on the standard output and exit.
1169 Print a summary of all target specific options on the standard output and
1173 Print a link map to the file
1175 See the description of the
1179 .It --no-keep-memory
1181 normally optimizes for speed over memory usage by caching the symbol tables
1182 of input files in memory. This option tells
1184 to instead optimize for memory usage, by rereading the symbol tables as necessary.
1185 This may be required if
1187 runs out of memory space while linking a large executable.
1191 Report unresolved symbol references from regular object files. This is done
1192 even if the linker is creating a non-symbolic shared library. The switch
1193 .Op --[no-]allow-shlib-undefined
1194 controls the behaviour for reporting unresolved references found in shared
1195 libraries being linked in.
1197 .It --allow-multiple-definition
1199 Normally when a symbol is defined multiple times, the linker will report a
1200 fatal error. These options allow multiple definitions and the first definition
1203 .It --allow-shlib-undefined
1204 .It --no-allow-shlib-undefined
1205 Allows (the default) or disallows undefined symbols in shared libraries. This
1206 switch is similar to
1208 except that it determines the behaviour when the undefined symbols are in
1209 a shared library rather than a regular object file. It does not affect how
1210 undefined symbols in regular object files are handled.
1213 .Op --allow-shlib-undefined
1214 is the default is that the shared library being specified at link time may
1215 not be the same as the one that is available at load time, so the symbols
1216 might actually be resolvable at load time. Plus there are some systems, (eg
1217 BeOS) where undefined symbols in shared libraries is normal. (The kernel patches
1218 them at load time to select which function is most appropriate for the current
1219 architecture. This is used for example to dynamically select an appropriate
1220 memset function). Apparently it is also normal for HPPA shared libraries to
1221 have undefined symbols.
1223 .It --no-undefined-version
1224 Normally when a symbol has an undefined version, the linker will ignore it.
1225 This option disallows symbols with undefined version and a fatal error will
1228 .It --default-symver
1229 Create and use a default symbol version (the soname) for unversioned exported
1232 .It --default-imported-symver
1233 Create and use a default symbol version (the soname) for unversioned imported
1236 .It --no-warn-mismatch
1239 will give an error if you try to link together input files that are mismatched
1240 for some reason, perhaps because they have been compiled for different processors
1241 or for different endiannesses. This option tells
1243 that it should silently permit such possible errors. This option should only
1244 be used with care, in cases when you have taken some special action that ensures
1245 that the linker errors are inappropriate.
1247 .It --no-warn-search-mismatch
1250 will give a warning if it finds an incompatible library during a library search.
1251 This option silences the warning.
1253 .It --no-whole-archive
1254 Turn off the effect of the
1256 option for subsequent archive files.
1258 .It --noinhibit-exec
1259 Retain the executable output file whenever it is still usable. Normally, the
1260 linker will not produce an output file if it encounters errors during the
1261 link process; it exits without writing an output file when it issues any error
1265 Only search library directories explicitly specified on the command line.
1266 Library directories specified in linker scripts (including linker scripts
1267 specified on the command line) are ignored.
1269 .It --oformat Va output-format
1271 may be configured to support more than one kind of object file. If your
1273 is configured this way, you can use the
1275 option to specify the binary format for the output object file. Even when
1277 is configured to support alternative object formats, you don't usually need
1280 should be configured to produce as a default output format the most usual
1281 format on each machine.
1283 is a text string, the name of a particular format supported by the BFD libraries.
1284 (You can list the available binary formats with
1288 can also specify the output format, but this option overrides it.See Section
1292 .It --pic-executable
1293 Create a position independent executable. This is currently only supported
1294 on ELF platforms. Position independent executables are similar to shared libraries
1295 in that they are relocated by the dynamic linker to the virtual address the
1296 OS chooses for them (which can vary between invocations). Like normal dynamically
1297 linked executables they can be executed and symbols defined in the executable
1298 cannot be overridden by shared libraries.
1301 This option is ignored for Linux compatibility.
1304 This option is ignored for SVR4 compatibility.
1307 An option with machine dependent effects. This option is only supported on
1308 a few targets.See Section
1310 See Section.Dq i960 .
1311 See Section.Dq Xtensa .
1312 See Section.Dq M68HC11/68HC12 .
1313 See Section.Dq PowerPC ELF32 .
1315 On some platforms, the
1317 option performs global optimizations that become possible when the linker
1318 resolves addressing in the program, such as relaxing address modes and synthesizing
1319 new instructions in the output object file.
1321 On some platforms these link time global optimizations may make symbolic debugging
1322 of the resulting executable impossible. This is known to be the case for the
1323 Matsushita MN10200 and MN10300 family of processors.
1325 On platforms where this is not supported,
1327 is accepted, but ignored.
1329 .It --retain-symbols-file Va filename
1332 the symbols listed in the file
1334 discarding all others.
1336 is simply a flat file, with one symbol name per line. This option is especially
1337 useful in environments (such as VxWorks) where a large global symbol table
1338 is accumulated gradually, to conserve run-time memory.
1340 .Li --retain-symbols-file
1343 discard undefined symbols, or symbols needed for relocations.
1345 You may only specify
1346 .Li --retain-symbols-file
1347 once in the command line. It overrides
1353 Add a directory to the runtime library search path. This is used when linking
1354 an ELF executable with shared objects. All
1356 arguments are concatenated and passed to the runtime linker, which uses them
1357 to locate shared objects at runtime. The
1359 option is also used when locating shared objects which are needed by shared
1360 objects explicitly included in the link; see the description of the
1364 is not used when linking an ELF executable, the contents of the environment
1367 will be used if it is defined.
1371 option may also be used on SunOS. By default, on SunOS, the linker will form
1372 a runtime search patch out of all the
1374 options it is given. If a
1376 option is used, the runtime search path will be formed exclusively using the
1378 options, ignoring the
1380 options. This can be useful when using gcc, which adds many
1382 options which may be on NFS mounted file systems.
1384 For compatibility with other ELF linkers, if the
1386 option is followed by a directory name, rather than a file name, it is treated
1391 .It -rpath-link Va DIR
1392 When using ELF or SunOS, one shared library may require another. This happens
1395 link includes a shared library as one of the input files.
1397 When the linker encounters such a dependency when doing a non-shared, non-relocatable
1398 link, it will automatically try to locate the required shared library and
1399 include it in the link, if it is not included explicitly. In such a case,
1402 option specifies the first set of directories to search. The
1404 option may specify a sequence of directory names either by specifying a list
1405 of names separated by colons, or by appearing multiple times.
1407 This option should be used with caution as it overrides the search path that
1408 may have been hard compiled into a shared library. In such a case it is possible
1409 to use unintentionally a different search path than the runtime linker would
1412 The linker uses the following search paths to locate required shared libraries:
1415 Any directories specified by
1419 Any directories specified by
1421 options. The difference between
1425 is that directories specified by
1427 options are included in the executable and used at runtime, whereas the
1429 option is only effective at link time. Searching
1431 in this way is only supported by native linkers and cross linkers which have
1432 been configured with the
1436 On an ELF system, if the
1440 options were not used, search the contents of the environment variable
1442 It is for the native linker only.
1446 option was not used, search any directories specified using
1450 For a native linker, the contents of the environment variable
1451 .Li LD_LIBRARY_PATH .
1453 For a native ELF linker, the directories in
1457 of a shared library are searched for shared libraries needed by it. The
1459 entries are ignored if
1463 The default directories, normally
1468 For a native linker on an ELF system, if the file
1470 exists, the list of directories found in that file.
1473 If the required shared library is not found, the linker will issue a warning
1474 and continue with the link.
1478 Create a shared library. This is currently only supported on ELF, XCOFF and
1479 SunOS platforms. On SunOS, the linker will automatically create a shared library
1482 option is not used and there are undefined symbols in the link.
1487 to sort the common symbols by size when it places them in the appropriate
1488 output sections. First come all the one byte symbols, then all the two byte,
1489 then all the four byte, and then everything else. This is to prevent gaps
1490 between symbols due to alignment constraints.
1492 .It --sort-section name
1493 This option will apply
1495 to all wildcard section patterns in the linker script.
1497 .It --sort-section alignment
1498 This option will apply
1499 .Li SORT_BY_ALIGNMENT
1500 to all wildcard section patterns in the linker script.
1502 .It --split-by-file [ Va size]
1504 .Op --split-by-reloc
1505 but creates a new output section for each input file when
1509 defaults to a size of 1 if not given.
1511 .It --split-by-reloc [ Va count]
1512 Tries to creates extra sections in the output file so that no single output
1513 section in the file contains more than
1515 relocations. This is useful when generating huge relocatable files for downloading
1516 into certain real time kernels with the COFF object file format; since COFF
1517 cannot represent more than 65535 relocations in a single section. Note that
1518 this will fail to work with object file formats which do not support arbitrary
1519 sections. The linker will not split up individual input sections for redistribution,
1520 so if a single input section contains more than
1522 relocations one output section will contain that many relocations.
1524 defaults to a value of 32768.
1527 Compute and display statistics about the operation of the linker, such as
1528 execution time and memory usage.
1530 .It --sysroot= Va directory
1533 as the location of the sysroot, overriding the configure-time default. This
1534 option is only supported by linkers that were configured using
1535 .Op --with-sysroot .
1537 .It --traditional-format
1538 For some targets, the output of
1540 is different in some ways from the output of some existing linker. This switch
1543 to use the traditional format instead.
1545 For example, on SunOS,
1547 combines duplicate entries in the symbol string table. This can reduce the
1548 size of an output file with full debugging information by over 30 percent.
1549 Unfortunately, the SunOS
1551 program can not read the resulting program (
1553 has no trouble). The
1554 .Li --traditional-format
1557 to not combine duplicate entries.
1559 .It --section-start Va sectionname= Va org
1560 Locate a section in the output file at the absolute address given by
1562 You may use this option as many times as necessary to locate multiple sections
1563 in the command line.
1565 must be a single hexadecimal integer; for compatibility with other linkers,
1566 you may omit the leading
1568 usually associated with hexadecimal values.
1570 there should be no white space between
1572 the equals sign (\(lq=\(rq), and
1578 Same as --section-start, with
1586 .It --unresolved-symbols= Va method
1587 Determine how to handle unresolved symbols. There are four possible values
1593 Do not report any unresolved symbols.
1596 Report all unresolved symbols. This is the default.
1598 .It ignore-in-object-files
1599 Report unresolved symbols that are contained in shared libraries, but ignore
1600 them if they come from regular object files.
1602 .It ignore-in-shared-libs
1603 Report unresolved symbols that come from regular object files, but ignore
1604 them if they come from shared libraries. This can be useful when creating
1605 a dynamic binary and it is known that all the shared libraries that it should
1606 be referencing are included on the linker's command line.
1609 The behaviour for shared libraries on their own can also be controlled by
1611 .Op --[no-]allow-shlib-undefined
1614 Normally the linker will generate an error message for each reported unresolved
1615 symbol but the option
1616 .Op --warn-unresolved-symbols
1617 can change this to a warning.
1621 Display the version number for
1623 and list the linker emulations supported. Display which input files can and
1624 cannot be opened. Display the linker script being used by the linker.
1626 .It --version-script= Va version-scriptfile
1627 Specify the name of a version script to the linker. This is typically used
1628 when creating shared libraries to specify additional information about the
1629 version hierarchy for the library being created. This option is only meaningful
1630 on ELF platforms which support shared libraries.See Section
1634 Warn when a common symbol is combined with another common symbol or with a
1635 symbol definition. Unix linkers allow this somewhat sloppy practise, but linkers
1636 on some other operating systems do not. This option allows you to find potential
1637 problems from combining global symbols. Unfortunately, some C libraries use
1638 this practise, so you may get some warnings about symbols in the libraries
1639 as well as in your programs.
1641 There are three kinds of global symbols, illustrated here by C examples:
1645 A definition, which goes in the initialized data section of the output file.
1648 An undefined reference, which does not allocate space. There must be either
1649 a definition or a common symbol for the variable somewhere.
1652 A common symbol. If there are only (one or more) common symbols for a variable,
1653 it goes in the uninitialized data area of the output file. The linker merges
1654 multiple common symbols for the same variable into a single symbol. If they
1655 are of different sizes, it picks the largest size. The linker turns a common
1656 symbol into a declaration, if there is a definition of the same variable.
1661 option can produce five kinds of warnings. Each warning consists of a pair
1662 of lines: the first describes the symbol just encountered, and the second
1663 describes the previous symbol encountered with the same name. One or both
1664 of the two symbols will be a common symbol.
1668 Turning a common symbol into a reference, because there is already a definition
1670 .Bd -literal -offset indent
1671 file(section): warning: common of `symbol'
1672 overridden by definition
1673 file(section): warning: defined here
1677 Turning a common symbol into a reference, because a later definition for the
1678 symbol is encountered. This is the same as the previous case, except that
1679 the symbols are encountered in a different order.
1680 .Bd -literal -offset indent
1681 file(section): warning: definition of `symbol'
1683 file(section): warning: common is here
1687 Merging a common symbol with a previous same-sized common symbol.
1688 .Bd -literal -offset indent
1689 file(section): warning: multiple common
1691 file(section): warning: previous common is here
1695 Merging a common symbol with a previous larger common symbol.
1696 .Bd -literal -offset indent
1697 file(section): warning: common of `symbol'
1698 overridden by larger common
1699 file(section): warning: larger common is here
1703 Merging a common symbol with a previous smaller common symbol. This is the
1704 same as the previous case, except that the symbols are encountered in a different
1706 .Bd -literal -offset indent
1707 file(section): warning: common of `symbol'
1708 overriding smaller common
1709 file(section): warning: smaller common is here
1713 .It --warn-constructors
1714 Warn if any global constructors are used. This is only useful for a few object
1715 file formats. For formats like COFF or ELF, the linker can not detect the
1716 use of global constructors.
1718 .It --warn-multiple-gp
1719 Warn if multiple global pointer values are required in the output file. This
1720 is only meaningful for certain processors, such as the Alpha. Specifically,
1721 some processors put large-valued constants in a special section. A special
1722 register (the global pointer) points into the middle of this section, so that
1723 constants can be loaded efficiently via a base-register relative addressing
1724 mode. Since the offset in base-register relative mode is fixed and relatively
1725 small (e.g., 16 bits), this limits the maximum size of the constant pool.
1726 Thus, in large programs, it is often necessary to use multiple global pointer
1727 values in order to be able to address all possible constants. This option
1728 causes a warning to be issued whenever this case occurs.
1731 Only warn once for each undefined symbol, rather than once per module which
1734 .It --warn-section-align
1735 Warn if the address of an output section is changed because of alignment.
1736 Typically, the alignment will be set by an input section. The address will
1737 only be changed if it not explicitly specified; that is, if the
1739 command does not specify a start address for the section (see Section
1742 .It --warn-shared-textrel
1743 Warn if the linker adds a DT_TEXTREL to a shared object.
1745 .It --warn-unresolved-symbols
1746 If the linker is going to report an unresolved symbol (see the option
1747 .Op --unresolved-symbols )
1748 it will normally generate an error. This option makes it generate a warning
1751 .It --error-unresolved-symbols
1752 This restores the linker's default behaviour of generating errors when it
1753 is reporting unresolved symbols.
1756 For each archive mentioned on the command line after the
1758 option, include every object file in the archive in the link, rather than
1759 searching the archive for the required object files. This is normally used
1760 to turn an archive file into a shared library, forcing every object to be
1761 included in the resulting shared library. This option may be used more than
1764 Two notes when using this option from gcc: First, gcc doesn't know about this
1765 option, so you have to use
1766 .Op -Wl,-whole-archive .
1767 Second, don't forget to use
1768 .Op -Wl,-no-whole-archive
1769 after your list of archives, because gcc will add its own list of archives
1770 to your link and you may not want this flag to affect those as well.
1772 .It --wrap Va symbol
1773 Use a wrapper function for
1775 Any undefined reference to
1778 .Li __wrap_ Va symbol .
1779 Any undefined reference to
1780 .Li __real_ Va symbol
1784 This can be used to provide a wrapper for a system function. The wrapper function
1786 .Li __wrap_ Va symbol .
1787 If it wishes to call the system function, it should call
1788 .Li __real_ Va symbol .
1790 Here is a trivial example:
1792 .Bd -literal -offset indent
1794 __wrap_malloc (size_t c)
1796 printf ("malloc called with %zu\en", c);
1797 return __real_malloc (c);
1801 If you link other code with this file using
1805 will call the function
1807 instead. The call to
1815 You may wish to provide a
1817 function as well, so that links without the
1819 option will succeed. If you do this, you should not put the definition of
1823 if you do, the assembler may resolve the call before the linker has a chance
1834 .It --enable-new-dtags
1835 .It --disable-new-dtags
1836 This linker can create the new dynamic tags in ELF. But the older ELF systems
1837 may not understand them. If you specify
1838 .Op --enable-new-dtags ,
1839 the dynamic tags will be created as needed. If you specify
1840 .Op --disable-new-dtags ,
1841 no new dynamic tags will be created. By default, the new dynamic tags are
1842 not created. Note that those options are only available for ELF systems.
1844 .It --hash-size= Va number
1845 Set the default size of the linker's hash tables to a prime number close to
1847 Increasing this value can reduce the length of time it takes the linker to
1848 perform its tasks, at the expense of increasing the linker's memory requirements.
1849 Similarly reducing this value can reduce the memory requirements at the expense
1852 .It --hash-style= Va style
1853 Set the type of linker's hash table(s).
1865 for both the classic ELF
1869 hash tables. The default is
1872 .It --reduce-memory-overheads
1873 This option reduces memory requirements at ld runtime, at the expense of linking
1874 speed. This was introduced to select the old O(n^2) algorithm for link map
1875 file generation, rather than the new O(n) algorithm which uses about 40% more
1876 memory for symbol storage.
1878 Another effect of the switch is to set the default hash table size to 1021,
1879 which again saves memory at the cost of lengthening the linker's run time.
1880 This is not done however if the
1882 switch has been used.
1885 .Op --reduce-memory-overheads
1886 switch may be also be used to enable other tradeoffs in future versions of
1890 .Em Options Specific to i386 PE Targets
1892 The i386 PE linker supports the
1894 option, which causes the output to be a dynamically linked library (DLL) instead
1895 of a normal executable. You should name the output
1897 when you use this option. In addition, the linker fully supports the standard
1899 files, which may be specified on the linker command line like an object file
1900 (in fact, it should precede archives it exports symbols from, to ensure that
1901 they get linked in, just like a normal object file).
1903 In addition to the options common to all targets, the i386 PE linker support
1904 additional command line options that are specific to the i386 PE target. Options
1905 that take values may be separated from their values by either a space or an
1909 .It --add-stdcall-alias
1910 If given, symbols with a stdcall suffix (@
1912 will be exported as-is and also with the suffix stripped. [This option is
1913 specific to the i386 PE targeted port of the linker]
1915 .It --base-file Va file
1918 as the name of a file in which to save the base addresses of all the relocations
1919 needed for generating DLLs with
1921 [This is an i386 PE specific option]
1924 Create a DLL instead of a regular executable. You may also use
1930 file. [This option is specific to the i386 PE targeted port of the linker]
1932 .It --enable-stdcall-fixup
1933 .It --disable-stdcall-fixup
1934 If the link finds a symbol that it cannot resolve, it will attempt to do \(lqfuzzy
1935 linking\(rq by looking for another defined symbol that differs only in the format
1936 of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking
1937 to the match. For example, the undefined symbol
1939 might be linked to the function
1941 or the undefined symbol
1943 might be linked to the function
1945 When the linker does this, it prints a warning, since it normally should have
1946 failed to link, but sometimes import libraries generated from third-party
1947 dlls may need this feature to be usable. If you specify
1948 .Op --enable-stdcall-fixup ,
1949 this feature is fully enabled and warnings are not printed. If you specify
1950 .Op --disable-stdcall-fixup ,
1951 this feature is disabled and such mismatches are considered to be errors.
1952 [This option is specific to the i386 PE targeted port of the linker]
1954 .It --export-all-symbols
1955 If given, all global symbols in the objects used to build a DLL will be exported
1956 by the DLL. Note that this is the default if there otherwise wouldn't be any
1957 exported symbols. When symbols are explicitly exported via DEF files or implicitly
1958 exported via function attributes, the default is to not export anything else
1959 unless this option is given. Note that the symbols
1961 .Li DllEntryPoint@0 ,
1962 .Li DllMainCRTStartup@12 ,
1965 will not be automatically exported. Also, symbols imported from other DLLs
1966 will not be re-exported, nor will symbols specifying the DLL's internal layout
1967 such as those beginning with
1971 In addition, no symbols from
1977 will be exported. Symbols whose names begin with
1981 will not be exported, to help with C++ DLLs. Finally, there is an extensive
1982 list of cygwin-private symbols that are not exported (obviously, this applies
1983 on when building DLLs for cygwin targets). These cygwin-excludes are:
1984 .Li _cygwin_dll_entry@12 ,
1985 .Li _cygwin_crt0_common@8 ,
1986 .Li _cygwin_noncygwin_dll_entry@12 ,
1989 .Li cygwin_attach_dll ,
1990 .Li cygwin_premain0 ,
1991 .Li cygwin_premain1 ,
1992 .Li cygwin_premain2 ,
1993 .Li cygwin_premain3 ,
1996 [This option is specific to the i386 PE targeted port of the linker]
1998 .It --exclude-symbols Va symbol, Va symbol,...
1999 Specifies a list of symbols which should not be automatically exported. The
2000 symbol names may be delimited by commas or colons. [This option is specific
2001 to the i386 PE targeted port of the linker]
2003 .It --file-alignment
2004 Specify the file alignment. Sections in the file will always begin at file
2005 offsets which are multiples of this number. This defaults to 512. [This option
2006 is specific to the i386 PE targeted port of the linker]
2008 .It --heap Va reserve
2009 .It --heap Va reserve, Va commit
2010 Specify the amount of memory to reserve (and optionally commit) to be used
2011 as heap for this program. The default is 1Mb reserved, 4K committed. [This
2012 option is specific to the i386 PE targeted port of the linker]
2014 .It --image-base Va value
2017 as the base address of your program or dll. This is the lowest memory location
2018 that will be used when your program or dll is loaded. To reduce the need to
2019 relocate and improve performance of your dlls, each should have a unique base
2020 address and not overlap any other dlls. The default is 0x400000 for executables,
2021 and 0x10000000 for dlls. [This option is specific to the i386 PE targeted
2025 If given, the stdcall suffixes (@
2027 will be stripped from symbols before they are exported. [This option is specific
2028 to the i386 PE targeted port of the linker]
2030 .It --large-address-aware
2031 If given, the appropriate bit in the \(lqCharacteristics\(rq field of the COFF header
2032 is set to indicate that this executable supports virtual addresses greater
2033 than 2 gigabytes. This should be used in conjunction with the /3GB or /USERVA=
2035 megabytes switch in the \(lq[operating systems]\(rq section of the BOOT.INI. Otherwise,
2036 this bit has no effect. [This option is specific to PE targeted ports of the
2039 .It --major-image-version Va value
2040 Sets the major number of the \(lqimage version\(rq. Defaults to 1. [This option is
2041 specific to the i386 PE targeted port of the linker]
2043 .It --major-os-version Va value
2044 Sets the major number of the \(lqos version\(rq. Defaults to 4. [This option is specific
2045 to the i386 PE targeted port of the linker]
2047 .It --major-subsystem-version Va value
2048 Sets the major number of the \(lqsubsystem version\(rq. Defaults to 4. [This option
2049 is specific to the i386 PE targeted port of the linker]
2051 .It --minor-image-version Va value
2052 Sets the minor number of the \(lqimage version\(rq. Defaults to 0. [This option is
2053 specific to the i386 PE targeted port of the linker]
2055 .It --minor-os-version Va value
2056 Sets the minor number of the \(lqos version\(rq. Defaults to 0. [This option is specific
2057 to the i386 PE targeted port of the linker]
2059 .It --minor-subsystem-version Va value
2060 Sets the minor number of the \(lqsubsystem version\(rq. Defaults to 0. [This option
2061 is specific to the i386 PE targeted port of the linker]
2063 .It --output-def Va file
2064 The linker will create the file
2066 which will contain a DEF file corresponding to the DLL the linker is generating.
2067 This DEF file (which should be called
2069 may be used to create an import library with
2071 or may be used as a reference to automatically or implicitly exported symbols.
2072 [This option is specific to the i386 PE targeted port of the linker]
2074 .It --out-implib Va file
2075 The linker will create the file
2077 which will contain an import lib corresponding to the DLL the linker is generating.
2078 This import lib (which should be called
2082 may be used to link clients against the generated DLL; this behaviour makes
2083 it possible to skip a separate
2085 import library creation step. [This option is specific to the i386 PE targeted
2088 .It --enable-auto-image-base
2089 Automatically choose the image base for DLLs, unless one is specified using
2092 argument. By using a hash generated from the dllname to create unique image
2093 bases for each DLL, in-memory collisions and relocations which can delay program
2094 execution are avoided. [This option is specific to the i386 PE targeted port
2097 .It --disable-auto-image-base
2098 Do not automatically generate a unique image base. If there is no user-specified
2101 then use the platform default. [This option is specific to the i386 PE targeted
2104 .It --dll-search-prefix Va string
2105 When linking dynamically to a dll without an import library, search for
2106 .Li <string><basename>.dll
2108 .Li lib<basename>.dll .
2109 This behaviour allows easy distinction between DLLs built for the various
2110 "subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically
2112 .Li --dll-search-prefix=cyg .
2113 [This option is specific to the i386 PE targeted port of the linker]
2115 .It --enable-auto-import
2116 Do sophisticated linking of
2120 for DATA imports from DLLs, and create the necessary thunking symbols when
2121 building the import libraries with those DATA exports. Note: Use of the 'auto-import'
2122 extension will cause the text section of the image file to be made writable.
2123 This does not conform to the PE-COFF format specification published by Microsoft.
2125 Using 'auto-import' generally will 'just work' -- but sometimes you may see
2128 "variable '<var>' can't be auto-imported. Please read the documentation for
2130 .Li --enable-auto-import
2133 This message occurs when some (sub)expression accesses an address ultimately
2134 given by the sum of two constants (Win32 import tables only allow one). Instances
2135 where this may occur include accesses to member fields of struct variables
2136 imported from a DLL, as well as using a constant index into an array variable
2137 imported from a DLL. Any multiword variable (arrays, structs, long long, etc)
2138 may trigger this error condition. However, regardless of the exact data type
2139 of the offending exported variable, ld will always detect it, issue the warning,
2142 There are several ways to address this difficulty, regardless of the data
2143 type of the exported variable:
2145 One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
2146 of adjusting references in your client code for runtime environment, so this
2147 method works only when runtime environment supports this feature.
2149 A second solution is to force one of the 'constants' to be a variable -- that
2150 is, unknown and un-optimizable at compile time. For arrays, there are two
2151 possibilities: a) make the indexee (the array's address) a variable, or b)
2152 make the 'constant' index a variable. Thus:
2154 .Bd -literal -offset indent
2155 extern type extern_array[];
2157 { volatile type *t=extern_array; t[1] }
2162 .Bd -literal -offset indent
2163 extern type extern_array[];
2165 { volatile int t=1; extern_array[t] }
2168 For structs (and most other multiword data types) the only option is to make
2169 the struct itself (or the long long, or the ...) variable:
2171 .Bd -literal -offset indent
2172 extern struct s extern_struct;
2173 extern_struct.field -->
2174 { volatile struct s *t=&extern_struct; t->field }
2179 .Bd -literal -offset indent
2180 extern long long extern_ll;
2182 { volatile long long * local_ll=&extern_ll; *local_ll }
2185 A third method of dealing with this difficulty is to abandon 'auto-import'
2186 for the offending symbol and mark it with
2187 .Li __declspec(dllimport) .
2188 However, in practise that requires using compile-time #defines to indicate
2189 whether you are building a DLL, building client code that will link to the
2190 DLL, or merely building/linking to a static library. In making the choice
2191 between the various methods of resolving the 'direct address with constant
2192 offset' problem, you should consider typical real-world usage:
2195 .Bd -literal -offset indent
2200 void main(int argc, char **argv){
2201 printf("%d\en",arr[1]);
2206 .Bd -literal -offset indent
2211 void main(int argc, char **argv){
2212 /* This workaround is for win32 and cygwin; do not "optimize" */
2213 volatile int *parr = arr;
2214 printf("%d\en",parr[1]);
2219 .Bd -literal -offset indent
2221 /* Note: auto-export is assumed (no __declspec(dllexport)) */
2222 #if (defined(_WIN32) || defined(__CYGWIN__)) && \e
2223 !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
2224 #define FOO_IMPORT __declspec(dllimport)
2228 extern FOO_IMPORT int arr[];
2231 void main(int argc, char **argv){
2232 printf("%d\en",arr[1]);
2236 A fourth way to avoid this problem is to re-code your library to use a functional
2237 interface rather than a data interface for the offending variables (e.g. set_foo()
2238 and get_foo() accessor functions). [This option is specific to the i386 PE
2239 targeted port of the linker]
2241 .It --disable-auto-import
2242 Do not attempt to do sophisticated linking of
2246 for DATA imports from DLLs. [This option is specific to the i386 PE targeted
2249 .It --enable-runtime-pseudo-reloc
2250 If your code contains expressions described in --enable-auto-import section,
2251 that is, DATA imports from DLL with non-zero offset, this switch will create
2252 a vector of 'runtime pseudo relocations' which can be used by runtime environment
2253 to adjust references to such data in your client code. [This option is specific
2254 to the i386 PE targeted port of the linker]
2256 .It --disable-runtime-pseudo-reloc
2257 Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
2258 This is the default. [This option is specific to the i386 PE targeted port
2261 .It --enable-extra-pe-debug
2262 Show additional debug info related to auto-import symbol thunking. [This option
2263 is specific to the i386 PE targeted port of the linker]
2265 .It --section-alignment
2266 Sets the section alignment. Sections in memory will always begin at addresses
2267 which are a multiple of this number. Defaults to 0x1000. [This option is specific
2268 to the i386 PE targeted port of the linker]
2270 .It --stack Va reserve
2271 .It --stack Va reserve, Va commit
2272 Specify the amount of memory to reserve (and optionally commit) to be used
2273 as stack for this program. The default is 2Mb reserved, 4K committed. [This
2274 option is specific to the i386 PE targeted port of the linker]
2276 .It --subsystem Va which
2277 .It --subsystem Va which: Va major
2278 .It --subsystem Va which: Va major. Va minor
2279 Specifies the subsystem under which your program will execute. The legal values
2289 You may optionally set the subsystem version also. Numeric values are also
2292 [This option is specific to the i386 PE targeted port of the linker]
2295 .Em Options specific to Motorola 68HC11 and 68HC12 targets
2297 The 68HC11 and 68HC12 linkers support specific options to control the memory
2298 bank switching mapping and trampoline code generation.
2302 This option disables the generation of trampoline. By default a trampoline
2303 is generated for each far function which is called using a
2305 instruction (this happens when a pointer to a far function is taken).
2307 .It --bank-window Va name
2308 This option indicates to the linker the name of the memory region in the
2310 specification that describes the memory bank window. The definition of such
2311 region is then used by the linker to compute paging and addresses within the
2315 .Ss Environment Variables
2316 You can change the behaviour of
2318 with the environment variables
2322 .Li COLLECT_NO_DEMANGLE .
2325 determines the input-file object format if you don't use
2329 Its value should be one of the BFD names for an input format (see Section
2335 uses the natural format of the target. If
2339 then BFD attempts to discover the input format by examining binary input files;
2340 this method often succeeds, but there are potential ambiguities, since there
2341 is no method of ensuring that the magic number used to specify object-file
2342 formats is unique. However, the configuration procedure for BFD on each system
2343 places the conventional format for that system first in the search-list, so
2344 ambiguities are resolved in favor of convention.
2347 determines the default emulation if you don't use the
2349 option. The emulation can affect various aspects of linker behaviour, particularly
2350 the default linker script. You can list the available emulations with the
2356 option is not used, and the
2358 environment variable is not defined, the default emulation depends upon how
2359 the linker was configured.
2361 Normally, the linker will default to demangling symbols. However, if
2362 .Li COLLECT_NO_DEMANGLE
2363 is set in the environment, then it will default to not demangling symbols.
2364 This environment variable is used in a similar fashion by the
2366 linker wrapper program. The default may be overridden by the
2373 Every link is controlled by a
2375 This script is written in the linker command language.
2377 The main purpose of the linker script is to describe how the sections in the
2378 input files should be mapped into the output file, and to control the memory
2379 layout of the output file. Most linker scripts do nothing more than this.
2380 However, when necessary, the linker script can also direct the linker to perform
2381 many other operations, using the commands described below.
2383 The linker always uses a linker script. If you do not supply one yourself,
2384 the linker will use a default script that is compiled into the linker executable.
2387 command line option to display the default linker script. Certain command
2388 line options, such as
2392 will affect the default linker script.
2394 You may supply your own linker script by using the
2396 command line option. When you do this, your linker script will replace the
2397 default linker script.
2399 You may also use linker scripts implicitly by naming them as input files to
2400 the linker, as though they were files to be linked.See Section
2401 .Dq Implicit Linker Scripts .
2403 .Ss Basic Linker Script Concepts
2404 We need to define some basic concepts and vocabulary in order to describe
2405 the linker script language.
2407 The linker combines input files into a single output file. The output file
2408 and each input file are in a special data format known as an
2409 .Em object file format .
2410 Each file is called an
2412 The output file is often called an
2414 but for our purposes we will also call it an object file. Each object file
2415 has, among other things, a list of
2417 We sometimes refer to a section in an input file as an
2419 similarly, a section in the output file is an
2420 .Em output section .
2422 Each section in an object file has a name and a size. Most sections also have
2423 an associated block of data, known as the
2424 .Em section contents .
2425 A section may be marked as
2427 which mean that the contents should be loaded into memory when the output
2428 file is run. A section with no contents may be
2430 which means that an area in memory should be set aside, but nothing in particular
2431 should be loaded there (in some cases this memory must be zeroed out). A section
2432 which is neither loadable nor allocatable typically contains some sort of
2433 debugging information.
2435 Every loadable or allocatable output section has two addresses. The first
2438 or virtual memory address. This is the address the section will have when
2439 the output file is run. The second is the
2441 or load memory address. This is the address at which the section will be loaded.
2442 In most cases the two addresses will be the same. An example of when they
2443 might be different is when a data section is loaded into ROM, and then copied
2444 into RAM when the program starts up (this technique is often used to initialize
2445 global variables in a ROM based system). In this case the ROM address would
2446 be the LMA, and the RAM address would be the VMA.
2448 You can see the sections in an object file by using the
2454 Every object file also has a list of
2458 A symbol may be defined or undefined. Each symbol has a name, and each defined
2459 symbol has an address, among other information. If you compile a C or C++
2460 program into an object file, you will get a defined symbol for every defined
2461 function and global or static variable. Every undefined function or global
2462 variable which is referenced in the input file will become an undefined symbol.
2464 You can see the symbols in an object file by using the
2466 program, or by using the
2472 .Ss Linker Script Format
2473 Linker scripts are text files.
2475 You write a linker script as a series of commands. Each command is either
2476 a keyword, possibly followed by arguments, or an assignment to a symbol. You
2477 may separate commands using semicolons. Whitespace is generally ignored.
2479 Strings such as file or format names can normally be entered directly. If
2480 the file name contains a character such as a comma which would otherwise serve
2481 to separate file names, you may put the file name in double quotes. There
2482 is no way to use a double quote character in a file name.
2484 You may include comments in linker scripts just as in C, delimited by
2488 As in C, comments are syntactically equivalent to whitespace.
2490 .Ss Simple Linker Script Example
2491 Many linker scripts are fairly simple.
2493 The simplest possible linker script has just one command:
2497 command to describe the memory layout of the output file.
2501 command is a powerful command. Here we will describe a simple use of it. Let's
2502 assume your program consists only of code, initialized data, and uninitialized
2503 data. These will be in the
2508 sections, respectively. Let's assume further that these are the only sections
2509 which appear in your input files.
2511 For this example, let's say that the code should be loaded at address 0x10000,
2512 and that the data should start at address 0x8000000. Here is a linker script
2514 .Bd -literal -offset indent
2518 .text : { *(.text) }
2520 .data : { *(.data) }
2527 command as the keyword
2529 followed by a series of symbol assignments and output section descriptions
2530 enclosed in curly braces.
2532 The first line inside the
2534 command of the above example sets the value of the special symbol
2536 which is the location counter. If you do not specify the address of an output
2537 section in some other way (other ways are described later), the address is
2538 set from the current value of the location counter. The location counter is
2539 then incremented by the size of the output section. At the start of the
2541 command, the location counter has the value
2544 The second line defines an output section,
2546 The colon is required syntax which may be ignored for now. Within the curly
2547 braces after the output section name, you list the names of the input sections
2548 which should be placed into this output section. The
2550 is a wildcard which matches any file name. The expression
2554 input sections in all input files.
2556 Since the location counter is
2558 when the output section
2560 is defined, the linker will set the address of the
2562 section in the output file to be
2565 The remaining lines define the
2569 sections in the output file. The linker will place the
2571 output section at address
2573 After the linker places the
2575 output section, the value of the location counter will be
2577 plus the size of the
2579 output section. The effect is that the linker will place the
2581 output section immediately after the
2583 output section in memory.
2585 The linker will ensure that each output section has the required alignment,
2586 by increasing the location counter if necessary. In this example, the specified
2591 sections will probably satisfy any alignment constraints, but the linker may
2592 have to create a small gap between the
2598 That's it! That's a simple and complete linker script.
2600 .Ss Simple Linker Script Commands
2601 In this section we describe the simple linker script commands.
2603 .Em Setting the Entry Point
2605 The first instruction to execute in a program is called the
2609 linker script command to set the entry point. The argument is a symbol name:
2610 .Bd -literal -offset indent
2614 There are several ways to set the entry point. The linker will set the entry
2615 point by trying each of the following methods in order, and stopping when
2616 one of them succeeds:
2622 command-line option;
2625 .Li ENTRY( Va symbol)
2626 command in a linker script;
2628 the value of the symbol
2632 the address of the first byte of the
2634 section, if present;
2640 .Em Commands Dealing with Files
2642 Several linker script commands deal with files.
2645 .It INCLUDE Va filename
2646 Include the linker script
2648 at this point. The file will be searched for in the current directory, and
2649 in any directory specified with the
2651 option. You can nest calls to
2653 up to 10 levels deep.
2655 .It INPUT( Va file, Va file, ...)
2656 .It INPUT( Va file Va file ...)
2659 command directs the linker to include the named files in the link, as though
2660 they were named on the command line.
2662 For example, if you always want to include
2664 any time you do a link, but you can't be bothered to put it on every link
2665 command line, then you can put
2667 in your linker script.
2669 In fact, if you like, you can list all of your input files in the linker script,
2670 and then invoke the linker with nothing but a
2676 is configured, and the filename starts with the
2678 character, and the script being processed was located inside the
2679 .Em sysroot prefix ,
2680 the filename will be looked for in the
2681 .Em sysroot prefix .
2682 Otherwise, the linker will try to open the file in the current directory.
2683 If it is not found, the linker will search through the archive library search
2684 path. See the description of
2686 in Options,,Command Line Options.
2689 .Li INPUT (-l Va file) ,
2691 will transform the name to
2693 as with the command line argument
2698 command in an implicit linker script, the files will be included in the link
2699 at the point at which the linker script file is included. This can affect
2702 .It GROUP( Va file, Va file, ...)
2703 .It GROUP( Va file Va file ...)
2708 except that the named files should all be archives, and they are searched
2709 repeatedly until no new undefined references are created. See the description
2712 in Options,,Command Line Options.
2714 .It AS_NEEDED( Va file, Va file, ...)
2715 .It AS_NEEDED( Va file Va file ...)
2716 This construct can appear only inside of the
2720 commands, among other filenames. The files listed will be handled as if they
2721 appear directly in the
2725 commands, with the exception of ELF shared libraries, that will be added only
2726 when they are actually needed. This construct essentially enables
2728 option for all the files listed inside of it and restores previous
2734 .It OUTPUT( Va filename)
2737 command names the output file. Using
2738 .Li OUTPUT( Va filename)
2739 in the linker script is exactly like using
2741 on the command line (see Section
2743 If both are used, the command line option takes precedence.
2747 command to define a default name for the output file other than the usual
2751 .It SEARCH_DIR( Va path)
2756 to the list of paths where
2758 looks for archive libraries. Using
2759 .Li SEARCH_DIR( Va path)
2760 is exactly like using
2762 on the command line (see Section
2764 If both are used, then the linker will search both paths. Paths specified
2765 using the command line option are searched first.
2767 .It STARTUP( Va filename)
2770 command is just like the
2772 command, except that
2774 will become the first input file to be linked, as though it were specified
2775 first on the command line. This may be useful when using a system in which
2776 the entry point is always the start of the first file.
2779 .Em Commands Dealing with Object File Formats
2781 A couple of linker script commands deal with object file formats.
2784 .It OUTPUT_FORMAT( Va bfdname)
2785 .It OUTPUT_FORMAT( Va default, Va big, Va little)
2788 command names the BFD format to use for the output file (see Section
2791 .Li OUTPUT_FORMAT( Va bfdname)
2792 is exactly like using
2793 .Li --oformat Va bfdname
2794 on the command line (see Section
2796 If both are used, the command line option takes precedence.
2800 with three arguments to use different formats based on the
2804 command line options. This permits the linker script to set the output format
2805 based on the desired endianness.
2811 are used, then the output format will be the first argument,
2815 is used, the output format will be the second argument,
2819 is used, the output format will be the third argument,
2822 For example, the default linker script for the MIPS ELF target uses this command:
2823 .Bd -literal -offset indent
2824 OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
2826 This says that the default format for the output file is
2828 but if the user uses the
2830 command line option, the output file will be created in the
2831 .Li elf32-littlemips
2834 .It TARGET( Va bfdname)
2837 command names the BFD format to use when reading input files. It affects subsequent
2841 commands. This command is like using
2843 on the command line (see Section
2849 is not, then the last
2851 command is also used to set the format for the output file.See Section
2855 .Em Other Linker Script Commands
2857 There are a few other linker scripts commands.
2860 .It ASSERT( Va exp, Va message)
2863 is non-zero. If it is zero, then exit the linker with an error code, and print
2866 .It EXTERN( Va symbol Va symbol ...)
2869 to be entered in the output file as an undefined symbol. Doing this may, for
2870 example, trigger linking of additional modules from standard libraries. You
2877 multiple times. This command has the same effect as the
2879 command-line option.
2881 .It FORCE_COMMON_ALLOCATION
2882 This command has the same effect as the
2884 command-line option: to make
2886 assign space to common symbols even if a relocatable output file is specified
2890 .It INHIBIT_COMMON_ALLOCATION
2891 This command has the same effect as the
2892 .Li --no-define-common
2893 command-line option: to make
2895 omit the assignment of addresses to common symbols even for a non-relocatable
2898 .It NOCROSSREFS( Va section Va section ...)
2899 This command may be used to tell
2901 to issue an error about any references among certain output sections.
2903 In certain types of programs, particularly on embedded systems when using
2904 overlays, when one section is loaded into memory, another section will not
2905 be. Any direct references between the two sections would be errors. For example,
2906 it would be an error if code in one section called a function defined in the
2911 command takes a list of output section names. If
2913 detects any cross references between the sections, it reports an error and
2914 returns a non-zero exit status. Note that the
2916 command uses output section names, not input section names.
2918 .It OUTPUT_ARCH( Va bfdarch)
2919 Specify a particular output machine architecture. The argument is one of the
2920 names used by the BFD library (see Section
2922 You can see the architecture of an object file by using the
2929 .Ss Assigning Values to Symbols
2930 You may assign a value to a symbol in a linker script. This will define the
2931 symbol and place it into the symbol table with a global scope.
2933 .Em Simple Assignments
2935 You may assign to a symbol using any of the C assignment operators:
2938 .It Va symbol = Va expression ;
2939 .It Va symbol += Va expression ;
2940 .It Va symbol -= Va expression ;
2941 .It Va symbol *= Va expression ;
2942 .It Va symbol /= Va expression ;
2943 .It Va symbol <<= Va expression ;
2944 .It Va symbol >>= Va expression ;
2945 .It Va symbol &= Va expression ;
2946 .It Va symbol |= Va expression ;
2949 The first case will define
2955 must already be defined, and the value will be adjusted accordingly.
2957 The special symbol name
2959 indicates the location counter. You may only use this within a
2962 .Dq Location Counter .
2968 Expressions are defined below; see Expressions.
2970 You may write symbol assignments as commands in their own right, or as statements
2973 command, or as part of an output section description in a
2977 The section of the symbol will be set from the section of the expression;
2978 for more information, see Expression Section.
2980 Here is an example showing the three different places that symbol assignments
2983 .Bd -literal -offset indent
2992 _bdata = (. + 3) & ~ 3;
2993 .data : { *(.data) }
2996 In this example, the symbol
2998 will be defined as zero. The symbol
3000 will be defined as the address following the last
3002 input section. The symbol
3004 will be defined as the address following the
3006 output section aligned upward to a 4 byte boundary.
3010 In some cases, it is desirable for a linker script to define a symbol only
3011 if it is referenced and is not defined by any object included in the link.
3012 For example, traditional linkers defined the symbol
3014 However, ANSI C requires that the user be able to use
3016 as a function name without encountering an error. The
3018 keyword may be used to define a symbol, such as
3020 only if it is referenced but not defined. The syntax is
3021 .Li PROVIDE( Va symbol = Va expression) .
3023 Here is an example of using
3027 .Bd -literal -offset indent
3039 In this example, if the program defines
3041 (with a leading underscore), the linker will give a multiple definition error.
3042 If, on the other hand, the program defines
3044 (with no leading underscore), the linker will silently use the definition
3045 in the program. If the program references
3047 but does not define it, the linker will use the definition in the linker script.
3053 For ELF targeted ports, the symbol will be hidden and won't be exported.
3055 .Em Source Code Reference
3057 Accessing a linker script defined variable from source code is not intuitive.
3058 In particular a linker script symbol is not equivalent to a variable declaration
3059 in a high level language, it is instead a symbol that does not have a value.
3061 Before going further, it is important to note that compilers often transform
3062 names in the source code into different names when they are stored in the
3063 symbol table. For example, Fortran compilers commonly prepend or append an
3064 underscore, and C++ performs extensive
3066 Therefore there might be a discrepancy between the name of a variable as it
3067 is used in source code and the name of the same variable as it is defined
3068 in a linker script. For example in C a linker script variable might be referred
3071 .Bd -literal -offset indent
3075 But in the linker script it might be defined as:
3077 .Bd -literal -offset indent
3081 In the remaining examples however it is assumed that no name transformation
3084 When a symbol is declared in a high level language such as C, two things happen.
3085 The first is that the compiler reserves enough space in the program's memory
3088 of the symbol. The second is that the compiler creates an entry in the program's
3089 symbol table which holds the symbol's
3091 ie the symbol table contains the address of the block of memory holding the
3092 symbol's value. So for example the following C declaration, at file scope:
3094 .Bd -literal -offset indent
3098 creates a entry called
3100 in the symbol table. This entry holds the address of an
3102 sized block of memory where the number 1000 is initially stored.
3104 When a program references a symbol the compiler generates code that first
3105 accesses the symbol table to find the address of the symbol's memory block
3106 and then code to read the value from that memory block. So:
3108 .Bd -literal -offset indent
3114 in the symbol table, gets the address associated with this symbol and then
3115 writes the value 1 into that address. Whereas:
3117 .Bd -literal -offset indent
3123 in the symbol table, gets it address and then copies this address into the
3124 block of memory associated with the variable
3127 Linker scripts symbol declarations, by contrast, create an entry in the symbol
3128 table but do not assign any memory to them. Thus they are an address without
3129 a value. So for example the linker script definition:
3131 .Bd -literal -offset indent
3135 creates an entry in the symbol table called
3137 which holds the address of memory location 1000, but nothing special is stored
3138 at address 1000. This means that you cannot access the
3140 of a linker script defined symbol - it has no value - all you can do is access
3143 of a linker script defined symbol.
3145 Hence when you are using a linker script defined symbol in source code you
3146 should always take the address of the symbol, and never attempt to use its
3147 value. For example suppose you want to copy the contents of a section of memory
3148 called .ROM into a section called .FLASH and the linker script contains these
3151 .Bd -literal -offset indent
3153 start_of_ROM = .ROM;
3154 end_of_ROM = .ROM + sizeof (.ROM) - 1;
3155 start_of_FLASH = .FLASH;
3159 Then the C source code to perform the copy would be:
3161 .Bd -literal -offset indent
3163 extern char start_of_ROM, end_of_ROM, start_of_FLASH;
3165 memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
3171 operators. These are correct.
3173 .Ss SECTIONS Command
3176 command tells the linker how to map input sections into output sections, and
3177 how to place the output sections in memory.
3182 .Bd -literal -offset indent
3192 .Va sections-command
3193 may of be one of the following:
3199 command (see Section
3202 a symbol assignment (see Section
3205 an output section description
3207 an overlay description
3212 command and symbol assignments are permitted inside the
3214 command for convenience in using the location counter in those commands. This
3215 can also make the linker script easier to understand because you can use those
3216 commands at meaningful points in the layout of the output file.
3218 Output section descriptions and overlay descriptions are described below.
3222 command in your linker script, the linker will place each input section into
3223 an identically named output section in the order that the sections are first
3224 encountered in the input files. If all input sections are present in the first
3225 file, for example, the order of sections in the output file will match the
3226 order in the first input file. The first section will be at address zero.
3228 .Em Output Section Description
3230 The full description of an output section looks like this:
3231 .Bd -literal -offset indent
3233 section [address] [(type)] :
3234 [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)]
3236 output-section-command
3237 output-section-command
3239 } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp]
3243 Most output sections do not use most of the optional section attributes.
3245 The whitespace around
3247 is required, so that the section name is unambiguous. The colon and the curly
3248 braces are also required. The line breaks and other white space are optional.
3251 .Va output-section-command
3252 may be one of the following:
3256 a symbol assignment (see Section
3259 an input section description (see Section
3262 data values to include directly (see Section
3263 .Dq Output Section Data )
3265 a special output section keyword (see Section
3266 .Dq Output Section Keywords )
3269 .Em Output Section Name
3271 The name of the output section is
3274 must meet the constraints of your output format. In formats which only support
3275 a limited number of sections, such as
3277 the name must be one of the names supported by the format (
3279 for example, allows only
3284 If the output format supports any number of sections, but with numbers and
3285 not names (as is the case for Oasys), the name should be supplied as a quoted
3286 numeric string. A section name may consist of any sequence of characters,
3287 but a name which contains any unusual characters such as commas must be quoted.
3289 The output section name
3291 is special; Output Section Discarding.
3293 .Em Output Section Address
3297 is an expression for the VMA (the virtual memory address) of the output section.
3298 If you do not provide
3300 the linker will set it based on
3302 if present, or otherwise based on the current value of the location counter.
3306 the address of the output section will be set to precisely that. If you provide
3311 then the address of the output section will be set to the current value of
3312 the location counter aligned to the alignment requirements of the output section.
3313 The alignment requirement of the output section is the strictest alignment
3314 of any input section contained within the output section.
3317 .Bd -literal -offset indent
3318 \&.text . : { *(.text) }
3321 .Bd -literal -offset indent
3322 \&.text : { *(.text) }
3324 are subtly different. The first will set the address of the
3326 output section to the current value of the location counter. The second will
3327 set it to the current value of the location counter aligned to the strictest
3334 may be an arbitrary expression; Expressions. For example, if you want to align
3335 the section on a 0x10 byte boundary, so that the lowest four bits of the section
3336 address are zero, you could do something like this:
3337 .Bd -literal -offset indent
3338 \&.text ALIGN(0x10) : { *(.text) }
3342 returns the current location counter aligned upward to the specified value.
3346 for a section will change the value of the location counter.
3348 .Em Input Section Description
3350 The most common output section command is an input section description.
3352 The input section description is the most basic linker script operation. You
3353 use output sections to tell the linker how to lay out your program in memory.
3354 You use input section descriptions to tell the linker how to map the input
3355 files into your memory layout.
3357 .No Input Section Basics
3359 An input section description consists of a file name optionally followed by
3360 a list of section names in parentheses.
3362 The file name and the section name may be wildcard patterns, which we describe
3363 further below (see Section
3364 .Dq Input Section Wildcards ) .
3366 The most common input section description is to include all input sections
3367 with a particular name in the output section. For example, to include all
3370 sections, you would write:
3371 .Bd -literal -offset indent
3376 is a wildcard which matches any file name. To exclude a list of files from
3377 matching the file name wildcard, EXCLUDE_FILE may be used to match all files
3378 except the ones specified in the EXCLUDE_FILE list. For example:
3379 .Bd -literal -offset indent
3380 (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
3382 will cause all .ctors sections from all files except
3388 There are two ways to include more than one section:
3389 .Bd -literal -offset indent
3393 The difference between these is the order in which the
3397 input sections will appear in the output section. In the first example, they
3398 will be intermingled, appearing in the same order as they are found in the
3399 linker input. In the second example, all
3401 input sections will appear first, followed by all
3405 You can specify a file name to include sections from a particular file. You
3406 would do this if one or more of your files contain special data that needs
3407 to be at a particular location in memory. For example:
3408 .Bd -literal -offset indent
3412 If you use a file name without a list of sections, then all sections in the
3413 input file will be included in the output section. This is not commonly done,
3414 but it may by useful on occasion. For example:
3415 .Bd -literal -offset indent
3419 When you use a file name which does not contain any wild card characters,
3420 the linker will first see if you also specified the file name on the linker
3421 command line or in an
3423 command. If you did not, the linker will attempt to open the file as an input
3424 file, as though it appeared on the command line. Note that this differs from
3427 command, because the linker will not search for the file in the archive search
3430 .No Input Section Wildcard Patterns
3432 In an input section description, either the file name or the section name
3433 or both may be wildcard patterns.
3437 seen in many examples is a simple wildcard pattern for the file name.
3439 The wildcard patterns are like those used by the Unix shell.
3443 matches any number of characters
3445 matches any single character
3447 matches a single instance of any of the
3451 character may be used to specify a range of characters, as in
3453 to match any lower case letter
3455 quotes the following character
3458 When a file name is matched with a wildcard, the wildcard characters will
3461 character (used to separate directory names on Unix). A pattern consisting
3464 character is an exception; it will always match any file name, whether it
3467 or not. In a section name, the wildcard characters will match a
3471 File name wildcard patterns only match files which are explicitly specified
3472 on the command line or in an
3474 command. The linker does not search directories to expand wildcards.
3476 If a file name matches more than one wildcard pattern, or if a file name appears
3477 explicitly and is also matched by a wildcard pattern, the linker will use
3478 the first match in the linker script. For example, this sequence of input
3479 section descriptions is probably in error, because the
3481 rule will not be used:
3482 .Bd -literal -offset indent
3483 \&.data : { *(.data) }
3484 \&.data1 : { data.o(.data) }
3487 Normally, the linker will place files and sections matched by wildcards in
3488 the order in which they are seen during the link. You can change this by using
3491 keyword, which appears before a wildcard pattern in parentheses (e.g.,
3492 .Li SORT_BY_NAME(.text*) ) .
3495 keyword is used, the linker will sort the files or sections into ascending
3496 order by name before placing them in the output file.
3498 .Li SORT_BY_ALIGNMENT
3502 .Li SORT_BY_ALIGNMENT
3503 will sort sections into ascending order by alignment before placing them in
3510 When there are nested section sorting commands in linker script, there can
3511 be at most 1 level of nesting for section sorting commands.
3517 .Li SORT_BY_ALIGNMENT
3518 (wildcard section pattern)). It will sort the input sections by name first,
3519 then by alignment if 2 sections have the same name.
3521 .Li SORT_BY_ALIGNMENT
3524 (wildcard section pattern)). It will sort the input sections by alignment
3525 first, then by name if 2 sections have the same alignment.
3530 (wildcard section pattern)) is treated the same as
3532 (wildcard section pattern).
3534 .Li SORT_BY_ALIGNMENT
3536 .Li SORT_BY_ALIGNMENT
3537 (wildcard section pattern)) is treated the same as
3538 .Li SORT_BY_ALIGNMENT
3539 (wildcard section pattern).
3541 All other nested section sorting commands are invalid.
3544 When both command line section sorting option and linker script section sorting
3545 command are used, section sorting command always takes precedence over the
3546 command line option.
3548 If the section sorting command in linker script isn't nested, the command
3549 line option will make the section sorting command to be treated as nested
3555 (wildcard section pattern ) with
3556 .Op --sort-sections alignment
3560 .Li SORT_BY_ALIGNMENT
3561 (wildcard section pattern)).
3563 .Li SORT_BY_ALIGNMENT
3564 (wildcard section pattern) with
3565 .Op --sort-section name
3567 .Li SORT_BY_ALIGNMENT
3570 (wildcard section pattern)).
3573 If the section sorting command in linker script is nested, the command line
3574 option will be ignored.
3576 If you ever get confused about where input sections are going, use the
3578 linker option to generate a map file. The map file shows precisely how input
3579 sections are mapped to output sections.
3581 This example shows how wildcard patterns might be used to partition files.
3582 This linker script directs the linker to place all
3590 The linker will place the
3592 section from all files beginning with an upper case character in
3594 for all other files, the linker will place the
3598 .Bd -literal -offset indent
3601 .text : { *(.text) }
3602 .DATA : { [A-Z]*(.data) }
3603 .data : { *(.data) }
3609 .No Input Section for Common Symbols
3611 A special notation is needed for common symbols, because in many object file
3612 formats common symbols do not have a particular input section. The linker
3613 treats common symbols as though they are in an input section named
3616 You may use file names with the
3618 section just as with any other input sections. You can use this to place common
3619 symbols from a particular input file in one section while common symbols from
3620 other input files are placed in another section.
3622 In most cases, common symbols in input files will be placed in the
3624 section in the output file. For example:
3625 .Bd -literal -offset indent
3626 \&.bss { *(.bss) *(COMMON) }
3629 Some object file formats have more than one type of common symbol. For example,
3630 the MIPS ELF object file format distinguishes standard common symbols and
3631 small common symbols. In this case, the linker will use a different special
3632 section name for other types of common symbols. In the case of MIPS ELF, the
3635 for standard common symbols and
3637 for small common symbols. This permits you to map the different types of common
3638 symbols into memory at different locations.
3640 You will sometimes see
3642 in old linker scripts. This notation is now considered obsolete. It is equivalent
3646 .No Input Section and Garbage Collection
3648 When link-time garbage collection is in use (
3649 .Li --gc-sections ) ,
3650 it is often useful to mark sections that should not be eliminated. This is
3651 accomplished by surrounding an input section's wildcard entry with
3656 .Li KEEP(SORT_BY_NAME(*)(.ctors)) .
3658 .No Input Section Example
3660 The following example is a complete linker script. It tells the linker to
3661 read all of the sections from file
3663 and place them at the start of output section
3665 which starts at location
3671 follows immediately, in the same output section. All of section
3675 goes into output section
3681 All of the remaining
3685 sections from any files are written to output section
3688 .Bd -literal -offset indent
3714 .Em Output Section Data
3716 You can include explicit bytes of data in an output section by using
3723 as an output section command. Each keyword is followed by an expression in
3724 parentheses providing the value to store (see Section
3726 The value of the expression is stored at the current value of the location
3735 commands store one, two, four, and eight bytes (respectively). After storing
3736 the bytes, the location counter is incremented by the number of bytes stored.
3738 For example, this will store the byte 1 followed by the four byte value of
3741 .Bd -literal -offset indent
3746 When using a 64 bit host or target,
3750 are the same; they both store an 8 byte, or 64 bit, value. When both host
3751 and target are 32 bits, an expression is computed as 32 bits. In this case
3753 stores a 32 bit value zero extended to 64 bits, and
3755 stores a 32 bit value sign extended to 64 bits.
3757 If the object file format of the output file has an explicit endianness, which
3758 is the normal case, the value will be stored in that endianness. When the
3759 object file format does not have an explicit endianness, as is true of, for
3760 example, S-records, the value will be stored in the endianness of the first
3763 Note---these commands only work inside a section description and not between
3764 them, so the following will produce an error from the linker:
3765 .Bd -literal -offset indent
3766 SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
3768 whereas this will work:
3769 .Bd -literal -offset indent
3770 SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }
3775 command to set the fill pattern for the current section. It is followed by
3776 an expression in parentheses. Any otherwise unspecified regions of memory
3777 within the section (for example, gaps left due to the required alignment of
3778 input sections) are filled with the value of the expression, repeated as necessary.
3781 statement covers memory locations after the point at which it occurs in the
3782 section definition; by including more than one
3784 statement, you can have different fill patterns in different parts of an output
3787 This example shows how to fill unspecified regions of memory with the value
3789 .Bd -literal -offset indent
3795 command is similar to the
3797 output section attribute, but it only affects the part of the section following
3800 command, rather than the entire section. If both are used, the
3802 command takes precedence.See Section
3803 .Dq Output Section Fill ,
3804 for details on the fill expression.
3806 .Em Output Section Keywords
3808 There are a couple of keywords which can appear as output section commands.
3811 .It CREATE_OBJECT_SYMBOLS
3812 The command tells the linker to create a symbol for each input file. The name
3813 of each symbol will be the name of the corresponding input file. The section
3814 of each symbol will be the output section in which the
3815 .Li CREATE_OBJECT_SYMBOLS
3818 This is conventional for the a.out object file format. It is not normally
3819 used for any other object file format.
3822 When linking using the a.out object file format, the linker uses an unusual
3823 set construct to support C++ global constructors and destructors. When linking
3824 object file formats which do not support arbitrary sections, such as ECOFF
3825 and XCOFF, the linker will automatically recognize C++ global constructors
3826 and destructors by name. For these object file formats, the
3828 command tells the linker to place constructor information in the output section
3831 command appears. The
3833 command is ignored for other object file formats.
3837 marks the start of the global constructors, and the symbol
3839 marks the end. Similarly,
3843 mark the start and end of the global destructors. The first word in the list
3844 is the number of entries, followed by the address of each constructor or destructor,
3845 followed by a zero word. The compiler must arrange to actually run the code.
3846 For these object file formats GNU C++ normally calls constructors from a subroutine
3850 is automatically inserted into the startup code for
3852 GNU C++ normally runs destructors either by using
3854 or directly from the function
3857 For object file formats such as
3861 which support arbitrary section names, GNU C++ will normally arrange to put
3862 the addresses of global constructors and destructors into the
3866 sections. Placing the following sequence into your linker script will build
3867 the sort of table which the GNU C++ runtime code expects to see.
3869 .Bd -literal -offset indent
3871 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
3876 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
3882 If you are using the GNU C++ support for initialization priority, which provides
3883 some control over the order in which global constructors are run, you must
3884 sort the constructors at link time to ensure that they are executed in the
3885 correct order. When using the
3888 .Li SORT_BY_NAME(CONSTRUCTORS)
3889 instead. When using the
3894 .Li *(SORT_BY_NAME(.ctors))
3896 .Li *(SORT_BY_NAME(.dtors))
3902 Normally the compiler and linker will handle these issues automatically, and
3903 you will not need to concern yourself with them. However, you may need to
3904 consider this if you are using C++ and writing your own linker scripts.
3907 .Em Output Section Discarding
3909 The linker will not create output sections with no contents. This is for convenience
3910 when referring to input sections that may or may not be present in any of
3911 the input files. For example:
3912 .Bd -literal -offset indent
3913 \&.foo : { *(.foo) }
3917 section in the output file if there is a
3919 section in at least one input file, and if the input sections are not all
3920 empty. Other link script directives that allocate space in an output section
3921 will also create the output section.
3923 The linker will ignore address assignments (see Section
3924 .Dq Output Section Address )
3925 on discarded output sections, except when the linker script defines symbols
3926 in the output section. In that case the linker will obey the address assignments,
3927 possibly advancing dot even though the section is discarded.
3929 The special output section name
3931 may be used to discard input sections. Any input sections which are assigned
3932 to an output section named
3934 are not included in the output file.
3936 .Em Output Section Attributes
3938 We showed above that the full description of an output section looked like
3940 .Bd -literal -offset indent
3942 section [address] [(type)] :
3943 [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)]
3945 output-section-command
3946 output-section-command
3948 } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp]
3951 We've already described
3955 .Va output-section-command .
3956 In this section we will describe the remaining section attributes.
3958 .No Output Section Type
3960 Each output section may have a type. The type is a keyword in parentheses.
3961 The following types are defined:
3965 The section should be marked as not loadable, so that it will not be loaded
3966 into memory when the program is run.
3971 These type names are supported for backward compatibility, and are rarely
3972 used. They all have the same effect: the section should be marked as not allocatable,
3973 so that no memory is allocated for the section when the program is run.
3976 The linker normally sets the attributes of an output section based on the
3977 input sections which map into it. You can override this by using the section
3978 type. For example, in the script sample below, the
3980 section is addressed at memory location
3982 and does not need to be loaded when the program is run. The contents of the
3984 section will appear in the linker output file as usual.
3985 .Bd -literal -offset indent
3988 ROM 0 (NOLOAD) : { ... }
3994 .No Output Section LMA
3996 Every section has a virtual address (VMA) and a load address (LMA); see Basic
3997 Script Concepts. The address expression which may appear in an output section
3998 description sets the VMA (see Section
3999 .Dq Output Section Address ) .
4005 keyword specifies the load address of the section.
4008 .Li AT> Va lma_region
4009 expression, you may specify a memory region for the section's load address.See Section
4011 Note that if the section has not had a VMA assigned to it then the linker
4014 as the VMA region as well.
4020 is specified for an allocatable section, the linker will set the LMA such
4021 that the difference between VMA and LMA for the section is the same as the
4022 preceding output section in the same region. If there is no preceding output
4023 section or the section is not allocatable, the linker will set the LMA equal
4024 to the VMA.See Section
4025 .Dq Output Section Region .
4027 This feature is designed to make it easy to build a ROM image. For example,
4028 the following linker script creates three output sections: one called
4034 which is loaded at the end of the
4036 section even though its VMA is
4040 to hold uninitialized data at address
4044 is defined with the value
4046 which shows that the location counter holds the VMA value, not the LMA value.
4048 .Bd -literal -offset indent
4052 .text 0x1000 : { *(.text) _etext = . ; }
4054 AT ( ADDR (.text) + SIZEOF (.text) )
4055 { _data = . ; *(.data); _edata = . ; }
4057 { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;}
4062 The run-time initialization code for use with a program generated with this
4063 linker script would include something like the following, to copy the initialized
4064 data from the ROM image to its runtime address. Notice how this code takes
4065 advantage of the symbols defined by the linker script.
4067 .Bd -literal -offset indent
4069 extern char _etext, _data, _edata, _bstart, _bend;
4070 char *src = &_etext;
4073 /* ROM has data at end of text; copy it. */
4074 while (dst < &_edata) {
4079 for (dst = &_bstart; dst< &_bend; dst++)
4084 .No Forced Output Alignment
4086 You can increase an output section's alignment by using ALIGN.
4088 .No Forced Input Alignment
4090 You can force input section alignment within an output section by using SUBALIGN.
4091 The value specified overrides any alignment given by input sections, whether
4094 .No Output Section Region
4096 You can assign a section to a previously defined region of memory by using
4098 See Section.Dq MEMORY .
4100 Here is a simple example:
4101 .Bd -literal -offset indent
4103 MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
4104 SECTIONS { ROM : { *(.text) } >rom }
4108 .No Output Section Phdr
4110 You can assign a section to a previously defined program segment by using
4112 See Section.Dq PHDRS .
4113 If a section is assigned to one or more segments, then all subsequent allocated
4114 sections will be assigned to those segments as well, unless they use an explicitly
4116 modifier. You can use
4118 to tell the linker to not put the section in any segment at all.
4120 Here is a simple example:
4121 .Bd -literal -offset indent
4123 PHDRS { text PT_LOAD ; }
4124 SECTIONS { .text : { *(.text) } :text }
4128 .No Output Section Fill
4130 You can set the fill pattern for an entire section by using
4133 is an expression (see Section
4135 Any otherwise unspecified regions of memory within the output section (for
4136 example, gaps left due to the required alignment of input sections) will be
4137 filled with the value, repeated as necessary. If the fill expression is a
4138 simple hex number, ie. a string of hex digit starting with
4140 and without a trailing
4144 then an arbitrarily long sequence of hex digits can be used to specify the
4145 fill pattern; Leading zeros become part of the pattern too. For all other
4146 cases, including extra parentheses or a unary
4148 the fill pattern is the four least significant bytes of the value of the expression.
4149 In all cases, the number is big-endian.
4151 You can also change the fill value with a
4153 command in the output section commands; (see Section
4154 .Dq Output Section Data ) .
4156 Here is a simple example:
4157 .Bd -literal -offset indent
4159 SECTIONS { .text : { *(.text) } =0x90909090 }
4163 .Em Overlay Description
4165 An overlay description provides an easy way to describe sections which are
4166 to be loaded as part of a single memory image but are to be run at the same
4167 memory address. At run time, some sort of overlay manager will copy the overlaid
4168 sections in and out of the runtime memory address as required, perhaps by
4169 simply manipulating addressing bits. This approach can be useful, for example,
4170 when a certain region of memory is faster than another.
4172 Overlays are described using the
4176 command is used within a
4178 command, like an output section description. The full syntax of the
4180 command is as follows:
4181 .Bd -literal -offset indent
4183 OVERLAY [start] : [NOCROSSREFS] [AT ( ldaddr )]
4187 output-section-command
4188 output-section-command
4190 } [:phdr...] [=fill]
4193 output-section-command
4194 output-section-command
4196 } [:phdr...] [=fill]
4198 } [>region] [:phdr...] [=fill]
4202 Everything is optional except
4204 (a keyword), and each section must have a name (
4208 above). The section definitions within the
4210 construct are identical to those within the general
4212 contruct (see Section
4214 except that no addresses and no memory regions may be defined for sections
4218 The sections are all defined with the same starting address. The load addresses
4219 of the sections are arranged such that they are consecutive in memory starting
4220 at the load address used for the
4222 as a whole (as with normal section definitions, the load address is optional,
4223 and defaults to the start address; the start address is also optional, and
4224 defaults to the current value of the location counter).
4228 keyword is used, and there any references among the sections, the linker will
4229 report an error. Since the sections all run at the same address, it normally
4230 does not make sense for one section to refer directly to another.See Section
4231 .Dq Miscellaneous Commands .
4233 For each section within the
4235 the linker automatically provides two symbols. The symbol
4236 .Li __load_start_ Va secname
4237 is defined as the starting load address of the section. The symbol
4238 .Li __load_stop_ Va secname
4239 is defined as the final load address of the section. Any characters within
4241 which are not legal within C identifiers are removed. C (or assembler) code
4242 may use these symbols to move the overlaid sections around as necessary.
4244 At the end of the overlay, the value of the location counter is set to the
4245 start address of the overlay plus the size of the largest section.
4247 Here is an example. Remember that this would appear inside a
4250 .Bd -literal -offset indent
4252 OVERLAY 0x1000 : AT (0x4000)
4254 .text0 { o1/*.o(.text) }
4255 .text1 { o2/*.o(.text) }
4259 This will define both
4263 to start at address 0x1000.
4265 will be loaded at address 0x4000, and
4267 will be loaded immediately after
4269 The following symbols will be defined if referenced:
4270 .Li __load_start_text0 ,
4271 .Li __load_stop_text0 ,
4272 .Li __load_start_text1 ,
4273 .Li __load_stop_text1 .
4275 C code to copy overlay
4277 into the overlay area might look like the following.
4279 .Bd -literal -offset indent
4281 extern char __load_start_text1, __load_stop_text1;
4282 memcpy ((char *) 0x1000, &__load_start_text1,
4283 &__load_stop_text1 - &__load_start_text1);
4289 command is just syntactic sugar, since everything it does can be done using
4290 the more basic commands. The above example could have been written identically
4293 .Bd -literal -offset indent
4295 .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
4296 PROVIDE (__load_start_text0 = LOADADDR (.text0));
4297 PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
4298 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
4299 PROVIDE (__load_start_text1 = LOADADDR (.text1));
4300 PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
4301 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
4306 The linker's default configuration permits allocation of all available memory.
4307 You can override this by using the
4313 command describes the location and size of blocks of memory in the target.
4314 You can use it to describe which memory regions may be used by the linker,
4315 and which memory regions it must avoid. You can then assign sections to particular
4316 memory regions. The linker will set section addresses based on the memory
4317 regions, and will warn about regions that become too full. The linker will
4318 not shuffle sections around to fit into the available regions.
4320 A linker script may contain at most one use of the
4322 command. However, you can define as many blocks of memory within it as you
4323 wish. The syntax is:
4324 .Bd -literal -offset indent
4328 name [(attr)] : ORIGIN = origin, LENGTH = len
4336 is a name used in the linker script to refer to the region. The region name
4337 has no meaning outside of the linker script. Region names are stored in a
4338 separate name space, and will not conflict with symbol names, file names,
4339 or section names. Each memory region must have a distinct name.
4343 string is an optional list of attributes that specify whether to use a particular
4344 memory region for an input section which is not explicitly mapped in the linker
4345 script. As described in SECTIONS, if you do not specify an output section
4346 for some input section, the linker will create an output section with the
4347 same name as the input section. If you define region attributes, the linker
4348 will use them to select the memory region for the output section that it creates.
4352 string must consist only of the following characters:
4368 Invert the sense of any of the preceding attributes
4371 If a unmapped section matches any of the listed attributes other than
4373 it will be placed in the memory region. The
4375 attribute reverses this test, so that an unmapped section will be placed in
4376 the memory region only if it does not match any of the listed attributes.
4380 is an numerical expression for the start address of the memory region. The
4381 expression must evaluate to a constant and it cannot involve any symbols.
4384 may be abbreviated to
4388 (but not, for example,
4393 is an expression for the size in bytes of the memory region. As with the
4395 expression, the expression must be numerical only and must evaluate to a constant.
4398 may be abbreviated to
4403 In the following example, we specify that there are two memory regions available
4404 for allocation: one starting at
4406 for 256 kilobytes, and the other starting at
4408 for four megabytes. The linker will place into the
4410 memory region every section which is not explicitly mapped into a memory region,
4411 and is either read-only or executable. The linker will place other sections
4412 which are not explicitly mapped into a memory region into the
4416 .Bd -literal -offset indent
4420 rom (rx) : ORIGIN = 0, LENGTH = 256K
4421 ram (!rx) : org = 0x40000000, l = 4M
4426 Once you define a memory region, you can direct the linker to place specific
4427 output sections into that memory region by using the
4429 output section attribute. For example, if you have a memory region named
4433 in the output section definition.See Section
4434 .Dq Output Section Region .
4435 If no address was specified for the output section, the linker will set the
4436 address to the next available address within the memory region. If the combined
4437 output sections directed to a memory region are too large for the region,
4438 the linker will issue an error message.
4440 It is possible to access the origin and length of a memory in an expression
4442 .Li ORIGIN( Va memory)
4444 .Li LENGTH( Va memory)
4447 .Bd -literal -offset indent
4449 _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
4454 The ELF object file format uses
4455 .Em program headers ,
4458 The program headers describe how the program should be loaded into memory.
4459 You can print them out by using the
4465 When you run an ELF program on a native ELF system, the system loader reads
4466 the program headers in order to figure out how to load the program. This will
4467 only work if the program headers are set correctly. This manual does not describe
4468 the details of how the system loader interprets program headers; for more
4469 information, see the ELF ABI.
4471 The linker will create reasonable program headers by default. However, in
4472 some cases, you may need to specify the program headers more precisely. You
4475 command for this purpose. When the linker sees the
4477 command in the linker script, it will not create any program headers other
4478 than the ones specified.
4480 The linker only pays attention to the
4482 command when generating an ELF output file. In other cases, the linker will
4486 This is the syntax of the
4496 .Bd -literal -offset indent
4500 name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ]
4501 [ FLAGS ( flags ) ] ;
4508 is used only for reference in the
4510 command of the linker script. It is not put into the output file. Program
4511 header names are stored in a separate name space, and will not conflict with
4512 symbol names, file names, or section names. Each program header must have
4515 Certain program header types describe segments of memory which the system
4516 loader will load from the file. In the linker script, you specify the contents
4517 of these segments by placing allocatable output sections in the segments.
4520 output section attribute to place a section in a particular segment.See Section
4521 .Dq Output Section Phdr .
4523 It is normal to put certain sections in more than one segment. This merely
4524 implies that one segment of memory contains another. You may repeat
4526 using it once for each segment which should contain the section.
4528 If you place a section in one or more segments using
4530 then the linker will place all subsequent allocatable sections which do not
4533 in the same segments. This is for convenience, since generally a whole set
4534 of contiguous sections will be placed in a single segment. You can use
4536 to override the default segment and tell the linker to not put the section
4537 in any segment at all.
4543 keywords appear after the program header type to further describe the contents
4546 keyword means that the segment should include the ELF file header. The
4548 keyword means that the segment should include the ELF program headers themselves.
4552 may be one of the following. The numbers indicate the value of the keyword.
4556 Indicates an unused program header.
4559 Indicates that this program header describes a segment to be loaded from the
4562 .It Li PT_DYNAMIC (2)
4563 Indicates a segment where dynamic linking information can be found.
4565 .It Li PT_INTERP (3)
4566 Indicates a segment where the name of the program interpreter may be found.
4569 Indicates a segment holding note information.
4572 A reserved program header type, defined but not specified by the ELF ABI.
4575 Indicates a segment where the program headers may be found.
4578 An expression giving the numeric type of the program header. This may be used
4579 for types not defined above.
4582 You can specify that a segment should be loaded at a particular address in
4585 expression. This is identical to the
4587 command used as an output section attribute (see Section
4588 .Dq Output Section LMA ) .
4591 command for a program header overrides the output section attribute.
4593 The linker will normally set the segment flags based on the sections which
4594 comprise the segment. You may use the
4596 keyword to explicitly specify the segment flags. The value of
4598 must be an integer. It is used to set the
4600 field of the program header.
4602 Here is an example of
4604 This shows a typical set of program headers used on a native ELF system.
4606 .Bd -literal -offset indent
4610 headers PT_PHDR PHDRS ;
4612 text PT_LOAD FILEHDR PHDRS ;
4614 dynamic PT_DYNAMIC ;
4620 .interp : { *(.interp) } :text :interp
4621 .text : { *(.text) } :text
4622 .rodata : { *(.rodata) } /* defaults to :text */
4624 . = . + 0x1000; /* move to a new page in memory */
4625 .data : { *(.data) } :data
4626 .dynamic : { *(.dynamic) } :data :dynamic
4633 The linker supports symbol versions when using ELF. Symbol versions are only
4634 useful when using shared libraries. The dynamic linker can use symbol versions
4635 to select a specific version of a function when it runs a program that may
4636 have been linked against an earlier version of the shared library.
4638 You can include a version script directly in the main linker script, or you
4639 can supply the version script as an implicit linker script. You can also use
4641 .Li --version-script
4647 .Bd -literal -offset indent
4648 VERSION { version-script-commands }
4651 The format of the version script commands is identical to that used by Sun's
4652 linker in Solaris 2.5. The version script defines a tree of version nodes.
4653 You specify the node names and interdependencies in the version script. You
4654 can specify which symbols are bound to which version nodes, and you can reduce
4655 a specified set of symbols to local scope so that they are not globally visible
4656 outside of the shared library.
4658 The easiest way to demonstrate the version script language is with a few examples.
4660 .Bd -literal -offset indent
4678 "int f(int, double)";
4683 This example version script defines three version nodes. The first version
4686 it has no other dependencies. The script binds the symbol
4690 It reduces a number of symbols to local scope so that they are not visible
4691 outside of the shared library; this is done using wildcard patterns, so that
4692 any symbol whose name begins with
4697 is matched. The wildcard patterns available are the same as those used in
4698 the shell when matching filenames (also known as \(lqglobbing\(rq). However, if you
4699 specify the symbol name inside double quotes, then the name is treated as
4700 literal, rather than as a glob pattern.
4702 Next, the version script defines node
4704 This node depends upon
4706 The script binds the symbol
4711 Finally, the version script defines node
4713 This node depends upon
4715 The scripts binds the symbols
4719 are bound to the version node
4722 When the linker finds a symbol defined in a library which is not specifically
4723 bound to a version node, it will effectively bind it to an unspecified base
4724 version of the library. You can bind all otherwise unspecified symbols to
4725 a given version node by using
4727 somewhere in the version script.
4729 The names of the version nodes have no specific meaning other than what they
4730 might suggest to the person reading them. The
4732 version could just as well have appeared in between
4736 However, this would be a confusing way to write a version script.
4738 Node name can be omitted, provided it is the only version node in the version
4739 script. Such version script doesn't assign any versions to symbols, only selects
4740 which symbols will be globally visible out and which won't.
4742 .Bd -literal -offset indent
4743 { global: foo; bar; local: *; };
4746 When you link an application against a shared library that has versioned symbols,
4747 the application itself knows which version of each symbol it requires, and
4748 it also knows which version nodes it needs from each shared library it is
4749 linked against. Thus at runtime, the dynamic loader can make a quick check
4750 to make sure that the libraries you have linked against do in fact supply
4751 all of the version nodes that the application will need to resolve all of
4752 the dynamic symbols. In this way it is possible for the dynamic linker to
4753 know with certainty that all external symbols that it needs will be resolvable
4754 without having to search for each symbol reference.
4756 The symbol versioning is in effect a much more sophisticated way of doing
4757 minor version checking that SunOS does. The fundamental problem that is being
4758 addressed here is that typically references to external functions are bound
4759 on an as-needed basis, and are not all bound when the application starts up.
4760 If a shared library is out of date, a required interface may be missing; when
4761 the application tries to use that interface, it may suddenly and unexpectedly
4762 fail. With symbol versioning, the user will get a warning when they start
4763 their program if the libraries being used with the application are too old.
4765 There are several GNU extensions to Sun's versioning approach. The first of
4766 these is the ability to bind a symbol to a version node in the source file
4767 where the symbol is defined instead of in the versioning script. This was
4768 done mainly to reduce the burden on the library maintainer. You can do this
4769 by putting something like:
4770 .Bd -literal -offset indent
4771 __asm__(".symver original_foo,foo@VERS_1.1");
4773 in the C source file. This renames the function
4777 bound to the version node
4781 directive can be used to prevent the symbol
4783 from being exported. A
4785 directive takes precedence over a version script.
4787 The second GNU extension is to allow multiple versions of the same function
4788 to appear in a given shared library. In this way you can make an incompatible
4789 change to an interface without increasing the major version number of the
4790 shared library, while still allowing applications linked against the old interface
4791 to continue to function.
4793 To do this, you must use multiple
4795 directives in the source file. Here is an example:
4797 .Bd -literal -offset indent
4798 __asm__(".symver original_foo,foo@");
4799 __asm__(".symver old_foo,foo@VERS_1.1");
4800 __asm__(".symver old_foo1,foo@VERS_1.2");
4801 __asm__(".symver new_foo,foo@@VERS_2.0");
4806 represents the symbol
4808 bound to the unspecified base version of the symbol. The source file that
4809 contains this example would define 4 C functions:
4816 When you have multiple definitions of a given symbol, there needs to be some
4817 way to specify a default version to which external references to this symbol
4818 will be bound. You can do this with the
4822 directive. You can only declare one version of a symbol as the default in
4823 this manner; otherwise you would effectively have multiple definitions of
4826 If you wish to bind a reference to a specific version of the symbol within
4827 the shared library, you can use the aliases of convenience (i.e.,
4831 directive to specifically bind to an external version of the function in question.
4833 You can also specify the language in the version script:
4835 .Bd -literal -offset indent
4836 VERSION extern "lang" { version-script-commands }
4846 The linker will iterate over the list of symbols at the link time and demangle
4849 before matching them to the patterns specified in
4850 .Li version-script-commands .
4852 Demangled names may contains spaces and other special characters. As described
4853 above, you can use a glob pattern to match demangled names, or you can use
4854 a double-quoted string to match the string exactly. In the latter case, be
4855 aware that minor differences (such as differing whitespace) between the version
4856 script and the demangler output will cause a mismatch. As the exact string
4857 generated by the demangler might change in the future, even if the mangled
4858 name does not, you should check that all of your version directives are behaving
4859 as you expect when you upgrade.
4861 .Ss Expressions in Linker Scripts
4862 The syntax for expressions in the linker script language is identical to that
4863 of C expressions. All expressions are evaluated as integers. All expressions
4864 are evaluated in the same size, which is 32 bits if both the host and target
4865 are 32 bits, and is otherwise 64 bits.
4867 You can use and set symbol values in expressions.
4869 The linker defines several special purpose builtin functions for use in expressions.
4873 All constants are integers.
4875 As in C, the linker considers an integer beginning with
4877 to be octal, and an integer beginning with
4881 to be hexadecimal. The linker considers other integers to be decimal.
4883 In addition, you can use the suffixes
4887 to scale a constant by
4891 respectively. For example, the following all refer to the same quantity:
4892 .Bd -literal -offset indent
4900 Unless quoted, symbol names start with a letter, underscore, or period and
4901 may include letters, digits, underscores, periods, and hyphens. Unquoted symbol
4902 names must not conflict with any keywords. You can specify a symbol which
4903 contains odd characters or has the same name as a keyword by surrounding the
4904 symbol name in double quotes:
4905 .Bd -literal -offset indent
4907 "with a space" = "also with a space" + 10;
4910 Since symbols can contain many non-alphabetic characters, it is safest to
4911 delimit symbols with spaces. For example,
4913 is one symbol, whereas
4915 is an expression involving subtraction.
4919 Orphan sections are sections present in the input files which are not explicitly
4920 placed into the output file by the linker script. The linker will still copy
4921 these sections into the output file, but it has to guess as to where they
4922 should be placed. The linker uses a simple heuristic to do this. It attempts
4923 to place orphan sections after non-orphan sections of the same attribute,
4924 such as code vs data, loadable vs non-loadable, etc. If there is not enough
4925 room to do this then it places at the end of the file.
4927 For ELF targets, the attribute of the section includes section type as well
4930 .Em The Location Counter
4932 The special linker variable
4935 always contains the current output location counter. Since the
4937 always refers to a location in an output section, it may only appear in an
4942 symbol may appear anywhere that an ordinary symbol is allowed in an expression.
4944 Assigning a value to
4946 will cause the location counter to be moved. This may be used to create holes
4947 in the output section. The location counter may not be moved backwards inside
4948 an output section, and may not be moved backwards outside of an output section
4949 if so doing creates areas with overlapping LMAs.
4951 .Bd -literal -offset indent
4964 In the previous example, the
4968 is located at the beginning of the output section
4970 It is followed by a 1000 byte gap. Then the
4974 appears, also with a 1000 byte gap following before the
4980 specifies what data to write in the gaps (see Section
4981 .Dq Output Section Fill ) .
4985 actually refers to the byte offset from the start of the current containing
4986 object. Normally this is the
4988 statement, whose start address is 0, hence
4990 can be used as an absolute address. If
4992 is used inside a section description however, it refers to the byte offset
4993 from the start of that section, not an absolute address. Thus in a script
4996 .Bd -literal -offset indent
5014 section will be assigned a starting address of 0x100 and a size of exactly
5015 0x200 bytes, even if there is not enough data in the
5017 input sections to fill this area. (If there is too much data, an error will
5018 be produced because this would be an attempt to move
5022 section will start at 0x500 and it will have an extra 0x600 bytes worth of
5023 space after the end of the values from the
5025 input sections and before the end of the
5027 output section itself.
5029 Setting symbols to the value of the location counter outside of an output
5030 section statement can result in unexpected values if the linker needs to place
5031 orphan sections. For example, given the following:
5033 .Bd -literal -offset indent
5046 If the linker needs to place some input section, e.g.
5048 not mentioned in the script, it might choose to place that section between
5052 You might think the linker should place
5054 on the blank line in the above script, but blank lines are of no particular
5055 significance to the linker. As well, the linker doesn't associate the above
5056 symbol names with their sections. Instead, it assumes that all assignments
5057 or other statements belong to the previous output section, except for the
5058 special case of an assignment to
5060 I.e., the linker will place the orphan
5062 section as if the script was written as follows:
5064 .Bd -literal -offset indent
5072 .rodata: { *(.rodata) }
5078 This may or may not be the script author's intention for the value of
5080 One way to influence the orphan section placement is to assign the location
5081 counter to itself, as the linker assumes that an assignment to
5083 is setting the start address of a following output section and thus should
5084 be grouped with that section. So you could write:
5086 .Bd -literal -offset indent
5102 section will be placed between
5109 The linker recognizes the standard C set of arithmetic operators, with the
5110 standard bindings and precedence levels:
5111 .Bd -literal -offset indent
5112 precedence associativity Operators Notes
5118 5 left == != > < <= >=
5124 11 right &= += -= *= /= (2)
5127 Notes: (1) Prefix operators (2)See Section
5132 The linker evaluates expressions lazily. It only computes the value of an
5133 expression when absolutely necessary.
5135 The linker needs some information, such as the value of the start address
5136 of the first section, and the origins and lengths of memory regions, in order
5137 to do any linking at all. These values are computed as soon as possible when
5138 the linker reads in the linker script.
5140 However, other values (such as symbol values) are not known or needed until
5141 after storage allocation. Such values are evaluated later, when other information
5142 (such as the sizes of output sections) is available for use in the symbol
5143 assignment expression.
5145 The sizes of sections cannot be known until after allocation, so assignments
5146 dependent upon these are not performed until after allocation.
5148 Some expressions, such as those depending upon the location counter
5150 must be evaluated during section allocation.
5152 If the result of an expression is required, but the value is not available,
5153 then an error results. For example, a script like the following
5154 .Bd -literal -offset indent
5158 .text 9+this_isnt_constant :
5163 will cause the error message
5164 .Li non constant expression for initial address .
5166 .Em The Section of an Expression
5168 When the linker evaluates an expression, the result is either absolute or
5169 relative to some section. A relative expression is expressed as a fixed offset
5170 from the base of a section.
5172 The position of the expression within the linker script determines whether
5173 it is absolute or relative. An expression which appears within an output section
5174 definition is relative to the base of the output section. An expression which
5175 appears elsewhere will be absolute.
5177 A symbol set to a relative expression will be relocatable if you request relocatable
5180 option. That means that a further link operation may change the value of the
5181 symbol. The symbol's section will be the section of the relative expression.
5183 A symbol set to an absolute expression will retain the same value through
5184 any further link operation. The symbol will be absolute, and will not have
5185 any particular associated section.
5187 You can use the builtin function
5189 to force an expression to be absolute when it would otherwise be relative.
5190 For example, to create an absolute symbol set to the address of the end of
5193 .Bd -literal -offset indent
5196 .data : { *(.data) _edata = ABSOLUTE(.); }
5203 would be relative to the
5207 .Em Builtin Functions
5209 The linker script language includes a number of builtin functions for use
5210 in linker script expressions.
5213 .It ABSOLUTE( Va exp)
5214 Return the absolute (non-relocatable, as opposed to non-negative) value of
5217 Primarily useful to assign an absolute value to a symbol within a section
5218 definition, where symbol values are normally section relative.See Section
5219 .Dq Expression Section .
5221 .It ADDR( Va section)
5222 Return the absolute address (the VMA) of the named
5224 Your script must previously have defined the location of that section. In
5225 the following example,
5229 are assigned identical values:
5230 .Bd -literal -offset indent
5235 start_of_output_1 = ABSOLUTE(.);
5240 symbol_1 = ADDR(.output1);
5241 symbol_2 = start_of_output_1;
5247 .It ALIGN( Va align)
5248 .It ALIGN( Va exp, Va align)
5249 Return the location counter (
5251 or arbitrary expression aligned to the next
5253 boundary. The single operand
5255 doesn't change the value of the location counter---it just does arithmetic
5256 on it. The two operand
5258 allows an arbitrary expression to be aligned upwards (
5259 .Li ALIGN( Va align)
5261 .Li ALIGN(., Va align) ) .
5263 Here is an example which aligns the output
5267 byte boundary after the preceding section and sets a variable within the section
5270 boundary after the input sections:
5271 .Bd -literal -offset indent
5274 .data ALIGN(0x2000): {
5276 variable = ALIGN(0x8000);
5283 in this example specifies the location of a section because it is used as
5286 attribute of a section definition (see Section
5287 .Dq Output Section Address ) .
5290 is used to defines the value of a symbol.
5292 The builtin function
5294 is closely related to
5297 .It ALIGNOF( Va section)
5298 Return the alignment in bytes of the named
5300 if that section has been allocated. If the section has not been allocated
5301 when this is evaluated, the linker will report an error. In the following
5302 example, the alignment of the
5304 section is stored as the first value in that section.
5305 .Bd -literal -offset indent
5309 LONG (ALIGNOF (.output))
5317 This is a synonym for
5319 for compatibility with older linker scripts. It is most often seen when setting
5320 the address of an output section.
5322 .It DATA_SEGMENT_ALIGN( Va maxpagesize, Va commonpagesize)
5323 This is equivalent to either
5324 .Bd -literal -offset indent
5325 (ALIGN(maxpagesize) + (. & (maxpagesize - 1)))
5328 .Bd -literal -offset indent
5329 (ALIGN(maxpagesize) + (. & (maxpagesize - commonpagesize)))
5331 depending on whether the latter uses fewer
5333 sized pages for the data segment (area between the result of this expression
5335 .Li DATA_SEGMENT_END )
5336 than the former or not. If the latter form is used, it means
5338 bytes of runtime memory will be saved at the expense of up to
5340 wasted bytes in the on-disk file.
5342 This expression can only be used directly in
5344 commands, not in any output section descriptions and only once in the linker
5347 should be less or equal to
5349 and should be the system page size the object wants to be optimized for (while
5350 still working on system page sizes up to
5354 .Bd -literal -offset indent
5355 . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
5358 .It DATA_SEGMENT_END( Va exp)
5359 This defines the end of data segment for
5360 .Li DATA_SEGMENT_ALIGN
5361 evaluation purposes.
5363 .Bd -literal -offset indent
5364 . = DATA_SEGMENT_END(.);
5367 .It DATA_SEGMENT_RELRO_END( Va offset, Va exp)
5368 This defines the end of the
5372 option is used. Second argument is returned. When
5374 option is not present,
5375 .Li DATA_SEGMENT_RELRO_END
5376 does nothing, otherwise
5377 .Li DATA_SEGMENT_ALIGN
5382 is aligned to the most commonly used page boundary for particular target.
5383 If present in the linker script, it must always come in between
5384 .Li DATA_SEGMENT_ALIGN
5386 .Li DATA_SEGMENT_END .
5388 .Bd -literal -offset indent
5389 . = DATA_SEGMENT_RELRO_END(24, .);
5392 .It DEFINED( Va symbol)
5395 is in the linker global symbol table and is defined before the statement using
5396 DEFINED in the script, otherwise return 0. You can use this function to provide
5397 default values for symbols. For example, the following script fragment shows
5398 how to set a global symbol
5400 to the first location in the
5402 section---but if a symbol called
5404 already existed, its value is preserved:
5406 .Bd -literal -offset indent
5410 begin = DEFINED(begin) ? begin : . ;
5418 .It LENGTH( Va memory)
5419 Return the length of the memory region named
5422 .It LOADADDR( Va section)
5423 Return the absolute LMA of the named
5425 This is normally the same as
5427 but it may be different if the
5429 attribute is used in the output section definition (see Section
5430 .Dq Output Section LMA ) .
5432 .It MAX( Va exp1, Va exp2)
5433 Returns the maximum of
5438 .It MIN( Va exp1, Va exp2)
5439 Returns the minimum of
5445 Return the next unallocated address that is a multiple of
5447 This function is closely related to
5448 .Li ALIGN( Va exp) ;
5451 command to define discontinuous memory for the output file, the two functions
5454 .It ORIGIN( Va memory)
5455 Return the origin of the memory region named
5458 .It SEGMENT_START( Va segment, Va default)
5459 Return the base address of the named
5461 If an explicit value has been given for this segment (with a command-line
5463 option) that value will be returned; otherwise the value will be
5467 command-line option can only be used to set the base address for the \(lqtext\(rq,
5468 \(lqdata\(rq, and \(lqbss\(rq sections, but you use
5470 with any segment name.
5472 .It SIZEOF( Va section)
5473 Return the size in bytes of the named
5475 if that section has been allocated. If the section has not been allocated
5476 when this is evaluated, the linker will report an error. In the following
5481 are assigned identical values:
5482 .Bd -literal -offset indent
5490 symbol_1 = .end - .start ;
5491 symbol_2 = SIZEOF(.output);
5498 Return the size in bytes of the output file's headers. This is information
5499 which appears at the start of the output file. You can use this number when
5500 setting the start address of the first section, if you choose, to facilitate
5503 When producing an ELF output file, if the linker script uses the
5505 builtin function, the linker must compute the number of program headers before
5506 it has determined all the section addresses and sizes. If the linker later
5507 discovers that it needs additional program headers, it will report an error
5508 .Li not enough room for program headers .
5509 To avoid this error, you must avoid using the
5511 function, or you must rework your linker script to avoid forcing the linker
5512 to use additional program headers, or you must define the program headers
5515 command (see Section
5519 .Ss Implicit Linker Scripts
5520 If you specify a linker input file which the linker can not recognize as an
5521 object file or an archive file, it will try to read the file as a linker script.
5522 If the file can not be parsed as a linker script, the linker will report an
5525 An implicit linker script will not replace the default linker script.
5527 Typically an implicit linker script would contain only symbol assignments,
5535 Any input files read because of an implicit linker script will be read at
5536 the position in the command line where the implicit linker script was read.
5537 This can affect archive searching.
5539 .Sh Machine Dependent Features
5541 has additional features on some platforms; the following sections describe
5542 them. Machines where
5544 has no additional functionality are not listed.
5546 .Ss Xr ld and the H8/300
5549 can perform these global optimizations when you specify the
5551 command-line option.
5554 .It relaxing address modes
5560 instructions whose targets are within eight bits, and turns them into eight-bit
5561 program-counter relative
5565 instructions, respectively.
5567 .It synthesizing instructions
5571 instructions which use the sixteen-bit absolute address form, but refer to
5572 the top page of memory, and changes them to use the eight-bit address form.
5573 (That is: the linker turns
5574 .Li mov.b Li @ Va aa:16
5576 .Li mov.b Li @ Va aa:8
5577 whenever the address
5579 is in the top page of memory).
5581 .It bit manipulation instructions
5583 finds all bit manipulation instructions like
5584 .Li band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor
5585 which use 32 bit and 16 bit absolute address form, but refer to the top page
5586 of memory, and changes them to use the 8 bit address form. (That is: the linker
5588 .Li bset #xx:3, Li @ Va aa:32
5590 .Li bset #xx:3, Li @ Va aa:8
5591 whenever the address
5593 is in the top page of memory).
5595 .It system control instructions
5599 instructions which use the 32 bit absolute address form, but refer to the
5600 top page of memory, and changes them to use 16 bit address form. (That is:
5602 .Li ldc.w Li @ Va aa:32,ccr
5604 .Li ldc.w Li @ Va aa:16,ccr
5605 whenever the address
5607 is in the top page of memory).
5610 .Ss Xr ld and the Intel 960 Family
5612 .Li -A Va architecture
5613 command line option to specify one of the two-letter names identifying members
5614 of the 960 family; the option specifies the desired output target, and warns
5615 of any incompatible instructions in the input files. It also modifies the
5616 linker's search strategy for archive libraries, to support the use of libraries
5617 specific to each particular architecture, by including in the search loop
5618 names suffixed with the string identifying the architecture.
5620 For example, if your
5622 command line included
5626 , the linker would look (in its built-in search paths, and in any paths you
5629 for a library with the names
5631 .Bd -literal -offset indent
5640 The first two possibilities would be considered in any event; the last two
5641 are due to the use of
5645 You can meaningfully use
5647 more than once on a command line, since the 960 architecture family allows
5648 combination of target architectures; each use will add another pair of name
5649 variants to search for when
5651 specifies a library.
5656 option for the i960 family. If you specify
5663 instructions whose targets are within 24 bits, and turns them into 24-bit
5664 program-counter relative
5668 instructions, respectively.
5674 instructions when it determines that the target subroutine is a leaf routine
5675 (that is, the target subroutine does not itself call any subroutines).
5677 .Ss Xr ld and the Motorola 68HC11 and 68HC12 families
5678 .Em Linker Relaxation
5680 For the Motorola 68HC11,
5682 can perform these global optimizations when you specify the
5684 command-line option.
5687 .It relaxing address modes
5693 instructions whose targets are within eight bits, and turns them into eight-bit
5694 program-counter relative
5698 instructions, respectively.
5701 also looks at all 16-bit extended addressing modes and transforms them in
5702 a direct addressing mode when the address is in page 0 (between 0 and 0x0ff).
5704 .It relaxing gcc instruction group
5709 it can emit group of instructions that the linker can optimize to use a 68HC11
5710 direct addressing mode. These instructions consists of
5717 .Em Trampoline Generation
5719 For 68HC11 and 68HC12,
5721 can generate trampoline code to call a far function using a normal
5723 instruction. The linker will also change the relocation to some far function
5724 to use the trampoline address instead of the function address. This is typically
5725 the case when a pointer to a function is taken. The pointer will in fact point
5726 to the function trampoline.
5730 switch makes the linker use PIC sequences for ARM/Thumb interworking veneers,
5731 even if the rest of the binary is not PIC. This avoids problems on uClinux
5734 is used to generate relocatable binaries.
5736 .Ss Xr ld and the ARM family
5739 will generate code stubs to allow functions calls between ARM and Thumb code.
5740 These stubs only work with code that has been compiled and assembled with
5742 .Li -mthumb-interwork
5743 command line option. If it is necessary to link with old ARM object files
5744 or libraries, which have not been compiled with the -mthumb-interwork option
5746 .Li --support-old-code
5747 command line switch should be given to the linker. This will make it generate
5748 larger stub functions which will work with non-interworking aware ARM code.
5749 Note, however, the linker does not support generating stubs for function calls
5750 to non-interworking aware Thumb code.
5754 switch is a duplicate of the generic
5756 switch, in that it sets the program's starting address. But it also sets the
5757 bottom bit of the address, so that it can be branched to using a BX instruction,
5758 and the program will start executing in Thumb mode straight away.
5764 to generate BE8 format executables. This option is only valid when linking
5765 big-endian objects. The resulting image will contain big-endian data and little-endian
5770 relocation is typically used for entries in the
5772 section. It is interpreted as either
5776 depending on the target. The
5780 switches override the default.
5784 switch overrides the default definition of the
5786 relocation. Valid values for
5788 their meanings, and target defaults are as follows:
5792 (arm*-*-elf, arm*-*-eabi)
5798 (arm*-*-linux, arm*-*-*bsd)
5803 relocation (defined by the ARM AAELF specification) enables objects compiled
5804 for the ARMv4 architecture to be interworking-safe when linked with other
5805 objects compiled for ARMv4t, but also allows pure ARMv4 binaries to be built
5806 from the same ARMv4 objects.
5808 In the latter case, the switch
5810 must be passed to the linker, which causes v4t
5812 instructions to be rewritten as
5814 since v4 processors do not have a
5818 In the former case, the switch should not be used, and
5820 relocations are ignored.
5824 switch enables the linker to use ARM/Thumb BLX instructions (available on
5825 ARMv5t and above) in various situations. Currently it is used to perform calls
5826 via the PLT from Thumb code using BLX rather than using BX and a mode-switching
5827 stub before each PLT entry. This should lead to such calls executing slightly
5830 This option is enabled implicitly for SymbianOS, so there is no need to specify
5831 it if you are using that target.
5834 .Li --vfp11-denorm-fix
5835 switch enables a link-time workaround for a bug in certain VFP11 coprocessor
5836 hardware, which sometimes allows instructions with denorm operands (which
5837 must be handled by support code) to have those operands overwritten by subsequent
5838 instructions before the support code can read the intended values.
5840 The bug may be avoided in scalar mode if you allow at least one intervening
5841 instruction between a VFP11 instruction which uses a register and another
5842 instruction which writes to the same register, or at least two intervening
5843 instructions if vector mode is in use. The bug only affects full-compliance
5844 floating-point mode: you do not need this workaround if you are using "runfast"
5845 mode. Please contact ARM for further details.
5847 If you know you are using buggy VFP11 hardware, you can enable this workaround
5848 by specifying the linker option
5849 .Li --vfp-denorm-fix=scalar
5850 if you are using the VFP11 scalar mode only, or
5851 .Li --vfp-denorm-fix=vector
5852 if you are using vector mode (the latter also works for scalar code). The
5854 .Li --vfp-denorm-fix=none .
5856 If the workaround is enabled, instructions are scanned for potentially-troublesome
5857 sequences, and a veneer is created for each such sequence which may trigger
5858 the erratum. The veneer consists of the first instruction of the sequence
5859 and a branch back to the subsequent instruction. The original instruction
5860 is then replaced with a branch to the veneer. The extra cycles required to
5861 call and return from the veneer are sufficient to avoid the erratum in both
5862 the scalar and vector cases.
5865 .Li --no-enum-size-warning
5866 switch prevents the linker from warning when linking object files that specify
5867 incompatible EABI enumeration size attributes. For example, with this switch
5868 enabled, linking of an object file using 32-bit enumeration values with another
5869 using enumeration values fitted into the smallest possible space will not
5872 .Ss Xr ld and HPPA 32-bit ELF Support
5873 When generating a shared library,
5875 will by default generate import stubs suitable for use with a single sub-space
5877 .Li --multi-subspace
5880 to generate export stubs, and different (larger) import stubs suitable for
5881 use with multiple sub-spaces.
5883 Long branch stubs and import/export stubs are placed by
5885 in stub sections located between groups of input sections.
5886 .Li --stub-group-size
5887 specifies the maximum size of a group of input sections handled by one stub
5888 section. Since branch offsets are signed, a stub section may serve two groups
5889 of input sections, one group before the stub section, and one group after
5890 it. However, when using conditional branches that require stubs, it may be
5891 better (for branch prediction) that stub sections only serve one group of
5892 input sections. A negative value for
5894 chooses this scheme, ensuring that branches to stubs always use a negative
5895 offset. Two special values of
5903 to automatically size input section groups for the branch types detected,
5904 with the same behaviour regarding stub placement as other positive or negative
5910 .Li --stub-group-size
5911 does not split input sections. A single input section larger than the group
5912 size specified will of course create a larger group (of one section). If input
5913 sections are too large, it may not be possible for a branch to reach its stub.
5916 For MMIX, there is a choice of generating
5920 object files when linking. The simulator
5924 format. The binutils
5926 utility can translate between the two formats.
5928 There is one special section, the
5929 .Li .MMIX.reg_contents
5930 section. Contents in this section is assumed to correspond to that of global
5931 registers, and symbols referring to it are translated to special symbols,
5932 equal to registers. In a final link, the start address of the
5933 .Li .MMIX.reg_contents
5934 section corresponds to the first allocated global register multiplied by 8.
5937 is not included in this section; it is always set to the program entry, which
5944 Symbols with the prefix
5945 .Li __.MMIX.start. ,
5947 .Li __.MMIX.start..text
5949 .Li __.MMIX.start..data
5950 are special; there must be only one each, even if they are local. The default
5951 linker script uses these to set the default start address of a section.
5953 Initial and trailing multiples of zero-valued 32-bit words in a section, are
5954 left out from an mmo file.
5956 .Ss Li ld and MSP430
5957 For the MSP430 it is possible to select the MPU architecture. The flag
5959 will select an appropriate linker script for selected MPU type. (To get a
5960 list of known MPUs just pass
5962 option to the linker).
5964 The linker will recognize some extra sections which are MSP430 specific:
5968 Defines a portion of ROM where interrupt vectors located.
5971 Defines the bootloader portion of the ROM (if applicable). Any code in this
5972 section will be uploaded to the MPU.
5975 Defines an information memory section (if applicable). Any code in this section
5976 will be uploaded to the MPU.
5978 .It Li .infomemnobits
5979 This is the same as the
5981 section except that any code in this section will not be uploaded to the MPU.
5984 Denotes a portion of RAM located above
5988 The last two sections are used by gcc.
5991 .Ss Xr ld and PowerPC 32-bit ELF Support
5992 Branches on PowerPC processors are limited to a signed 26-bit displacement,
5996 .Li relocation truncated to fit
5997 errors with very large programs.
5999 enables the generation of trampolines that can access the entire 32-bit address
6000 space. These trampolines are inserted at section boundaries, so may not themselves
6001 be reachable if an input section exceeds 33M in size.
6005 Current PowerPC GCC accepts a
6007 option that generates code capable of using a newer PLT and GOT layout that
6008 has the security advantage of no executable section ever needing to be writable
6009 and no writable section ever being executable. PowerPC
6011 will generate this layout, including stubs to access the PLT, if all input
6012 files (including startup and static libraries) were compiled with
6015 forces the old BSS PLT (and GOT layout) which can give slightly better performance.
6019 will use the new PLT and GOT layout if it is linking new
6023 code, but does not do so automatically when linking non-PIC code. This option
6024 requests the new PLT and GOT layout. A warning will be given if some object
6025 file requires the old style BSS PLT.
6028 The new secure PLT and GOT are placed differently relative to other sections
6029 compared to older BSS PLT and GOT placement. The location of
6031 must change because the new secure PLT is an initialized section while the
6032 old PLT is uninitialized. The reason for the
6034 change is more subtle: The new placement allows
6036 to be read-only in applications linked with
6037 .Li -z relro -z now .
6038 However, this placement means that
6040 cannot always be used in shared libraries, because the PowerPC ABI accesses
6042 in shared libraries from the GOT pointer.
6044 forces the old GOT placement. PowerPC GCC doesn't use
6046 in shared libraries, so this option is really only useful for other compilers
6049 .It --emit-stub-syms
6052 to label linker stubs with a local symbol that encodes the stub type and destination.
6054 .It --no-tls-optimize
6057 normally performs some optimization of code sequences used to access Thread-Local
6058 Storage. Use this option to disable the optimization.
6061 .Ss Xr ld and PowerPC64 64-bit ELF Support
6063 .It --stub-group-size
6064 Long branch stubs, PLT call stubs and TOC adjusting stubs are placed by
6066 in stub sections located between groups of input sections.
6067 .Li --stub-group-size
6068 specifies the maximum size of a group of input sections handled by one stub
6069 section. Since branch offsets are signed, a stub section may serve two groups
6070 of input sections, one group before the stub section, and one group after
6071 it. However, when using conditional branches that require stubs, it may be
6072 better (for branch prediction) that stub sections only serve one group of
6073 input sections. A negative value for
6075 chooses this scheme, ensuring that branches to stubs always use a negative
6076 offset. Two special values of
6084 to automatically size input section groups for the branch types detected,
6085 with the same behaviour regarding stub placement as other positive or negative
6091 .Li --stub-group-size
6092 does not split input sections. A single input section larger than the group
6093 size specified will of course create a larger group (of one section). If input
6094 sections are too large, it may not be possible for a branch to reach its stub.
6096 .It --emit-stub-syms
6099 to label linker stubs with a local symbol that encodes the stub type and destination.
6101 .It --dotsyms, --no-dotsyms
6102 These two options control how
6104 interprets version patterns in a version script. Older PowerPC64 compilers
6105 emitted both a function descriptor symbol with the same name as the function,
6106 and a code entry symbol with the name prefixed by a dot (
6108 To properly version a function
6110 the version script thus needs to control both
6116 on by default, automatically adds the required dot-prefixed patterns. Use
6118 to disable this feature.
6120 .It --no-tls-optimize
6123 normally performs some optimization of code sequences used to access Thread-Local
6124 Storage. Use this option to disable the optimization.
6126 .It --no-opd-optimize
6131 section entries corresponding to deleted link-once functions, or functions
6132 removed by the action of
6136 Use this option to disable
6140 .It --non-overlapping-opd
6141 Some PowerPC64 compilers have an option to generate compressed
6143 entries spaced 16 bytes apart, overlapping the third word, the static chain
6144 pointer (unused in C) with the first word of the next entry. This option expands
6145 such entries to the full 24 bytes.
6147 .It --no-toc-optimize
6150 normally removes unused
6152 section entries. Such entries are detected by examining relocations that reference
6153 the TOC in code sections. A reloc in a deleted code section marks a TOC word
6154 as unneeded, while a reloc in a kept code section marks a TOC word as needed.
6155 Since the TOC may reference itself, TOC relocs are also examined. TOC words
6156 marked as both needed and unneeded will of course be kept. TOC words without
6157 any referencing reloc are assumed to be part of a multi-word entry, and are
6158 kept or discarded as per the nearest marked preceding word. This works reliably
6159 for compiler generated code, but may be incorrect if assembly code is used
6160 to insert TOC entries. Use this option to disable the optimization.
6163 By default, PowerPC64 GCC generates code for a TOC model where TOC entries
6164 are accessed with a 16-bit offset from r2. This limits the total TOC size
6167 extends this limit by grouping code sections such that each group uses less
6168 than 64K for its TOC entries, then inserts r2 adjusting stubs between inter-group
6171 does not split apart input sections, so cannot help if a single input file
6174 section that exceeds 64K, most likely from linking multiple files with
6176 Use this option to turn off this feature.
6179 .Ss Xr ld and SPU ELF Support
6182 This option marks an executable as a PIC plugin module.
6187 recognizes calls to functions within overlay regions, and redirects such calls
6188 to an overlay manager via a stub.
6190 also provides a built-in overlay manager. This option turns off all this special
6193 .It --emit-stub-syms
6196 to label overlay stubs with a local symbol that encodes the stub type and
6199 .It --extra-overlay-stubs
6202 to add overlay call stubs on all function calls out of overlay regions. Normally
6203 stubs are not added on calls to non-overlay regions.
6205 .It --local-store=lo:hi
6207 usually checks that a final executable for SPU fits in the address range 0
6208 to 256k. This option may be used to change the range. Disable the check entirely
6210 .Op --local-store=0:0 .
6212 .It --stack-analysis
6213 SPU local store space is limited. Over-allocation of stack space unnecessarily
6214 limits space available for code and data, while under-allocation results in
6215 runtime failures. If given this option,
6217 will provide an estimate of maximum stack usage.
6219 does this by examining symbols in code sections to determine the extents of
6220 functions, and looking at function prologues for stack adjusting instructions.
6221 A call-graph is created by looking for relocations on branch instructions.
6222 The graph is then searched for the maximum stack usage path. Note that this
6223 analysis does not find calls made via function pointers, and does not handle
6224 recursion and other cycles in the call graph. Stack usage may be under-estimated
6225 if your code makes such calls. Also, stack usage for dynamic allocation, e.g.
6226 alloca, will not be detected. If a link map is requested, detailed information
6227 about each function's stack usage and calls will be given.
6229 .It --emit-stack-syms
6230 This option, if given along with
6231 .Op --stack-analysis
6234 emitting stack sizing symbols for each function. These take the form
6235 .Li __stack_<function_name>
6236 for global functions, and
6237 .Li __stack_<number>_<function_name>
6238 for static functions.
6240 is the section id in hex. The value of such symbols is the stack requirement
6241 for the corresponding function. The symbol size will be zero, type
6249 .Ss Xr ld's Support for Various TI COFF Versions
6252 switch allows selection of one of the various TI COFF versions. The latest
6253 of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions
6254 also vary in header byte-order format;
6256 will read any version or byte order, but the output header format depends
6257 on the default specified by the specific target.
6259 .Ss Xr ld and WIN32 (cygwin/mingw)
6260 This section describes some of the win32 specific
6262 issues. See Options,,Command Line Options for detailed description of the
6263 command line options mentioned here.
6266 .It import libraries
6267 The standard Windows linker creates and uses so-called import libraries, which
6268 contains information for linking to dll's. They are regular static archives
6269 and are handled as any other static archive. The cygwin and mingw ports of
6271 have specific support for creating such libraries provided with the
6273 command line option.
6275 .It exporting DLL symbols
6278 has several ways to export symbols for dll's.
6281 .It using auto-export functionality
6284 exports symbols with the auto-export functionality, which is controlled by
6285 the following command line options:
6289 --export-all-symbols [This is the default]
6297 .Li --export-all-symbols
6298 is not given explicitly on the command line, then the default auto-export
6301 if either of the following are true:
6307 Any symbol in any object file was marked with the __declspec(dllexport) attribute.
6310 .It using a DEF file
6311 Another way of exporting symbols is using a DEF file. A DEF file is an ASCII
6312 file containing definitions of symbols which should be exported when a dll
6313 is created. Usually it is named
6315 and is added as any other object file to the linker's command line. The file's
6321 .Bd -literal -offset indent
6322 gcc -o <output> <objectfiles> <dll name>.def
6325 Using a DEF file turns off the normal auto-export behavior, unless the
6326 .Li --export-all-symbols
6327 option is also used.
6329 Here is an example of a DEF file for a shared library called
6332 .Bd -literal -offset indent
6333 LIBRARY "xyz.dll" BASE=0x20000000
6339 another_foo = abc.dll.afoo
6343 This example defines a DLL with a non-default base address and five symbols
6344 in the export table. The third exported symbol
6346 is an alias for the second. The fourth symbol,
6348 is resolved by "forwarding" to another module and treating it as an alias
6351 exported from the DLL
6355 is declared to be a data object.
6359 command indicates the
6361 name of the output DLL. If
6363 does not include a suffix, the default library suffix,
6367 When the .DEF file is used to build an application, rather than a library,
6370 command should be used instead of
6374 does not include a suffix, the default executable suffix,
6382 the optional specification
6384 may be used to specify a non-default base address for the image.
6390 is specified, or they specify an empty string, the internal name is the same
6391 as the filename specified on the command line.
6393 The complete specification of an export symbol is:
6395 .Bd -literal -offset indent
6397 ( ( ( <name1> [ = <name2> ] )
6398 | ( <name1> = <module-name> . <external-name>))
6399 [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
6404 as an exported symbol from the DLL, or declares
6406 as an exported alias for
6410 as a "forward" alias for the symbol
6414 Optionally, the symbol may be exported by the specified ordinal
6418 The optional keywords that follow the declaration indicate:
6421 Do not put the symbol name in the DLL's export table. It will still be exported
6422 by its ordinal alias (either the value specified by the .def specification
6423 or, otherwise, the value assigned by the linker). The symbol name, however,
6424 does remain visible in the import library (if any), unless
6429 The symbol is a variable or object, rather than a function. The import lib
6430 will export only an indirect reference to
6442 but put the undecorated
6446 into the import library. Both refer to the read-only import address table's
6447 pointer to the variable, not to the variable itself. This can be dangerous.
6448 If the user code fails to add the
6450 attribute and also fails to explicitly add the extra indirection that the
6451 use of the attribute enforces, the application will behave unexpectedly.
6454 Put the symbol in the DLL's export table, but do not put it into the static
6455 import library used to resolve imports at link time. The symbol can still
6456 be imported using the
6457 .Li LoadLibrary/GetProcAddress
6458 API at runtime or by by using the GNU ld extension of linking directly to
6459 the DLL without an import library. See ld/deffilep.y in the binutils sources
6460 for the full specification of other DEF file statements
6462 While linking a shared dll,
6464 is able to create a DEF file with the
6465 .Li --output-def <file>
6466 command line option.
6468 .It Using decorations
6469 Another way of marking symbols for export is to modify the source code itself,
6470 so that when building the DLL each symbol to be exported is declared as:
6472 .Bd -literal -offset indent
6473 __declspec(dllexport) int a_variable
6474 __declspec(dllexport) void a_function(int with_args)
6477 All such symbols will be exported from the DLL. If, however, any of the object
6478 files in the DLL contain symbols decorated in this way, then the normal auto-export
6479 behavior is disabled, unless the
6480 .Li --export-all-symbols
6481 option is also used.
6483 Note that object files that wish to access these symbols must
6485 decorate them with dllexport. Instead, they should use dllimport, instead:
6487 .Bd -literal -offset indent
6488 __declspec(dllimport) int a_variable
6489 __declspec(dllimport) void a_function(int with_args)
6492 This complicates the structure of library header files, because when included
6493 by the library itself the header must declare the variables and functions
6494 as dllexport, but when included by client code the header must declare them
6495 as dllimport. There are a number of idioms that are typically used to do this;
6496 often client code can omit the __declspec() declaration completely. See
6497 .Li --enable-auto-import
6499 .Li automatic data imports
6500 for more information.
6503 .It automatic data imports
6504 The standard Windows dll format supports data imports from dlls only by adding
6505 special decorations (dllimport/dllexport), which let the compiler produce
6506 specific assembler instructions to deal with this issue. This increases the
6507 effort necessary to port existing Un*x code to these platforms, especially
6508 for large c++ libraries and applications. The auto-import feature, which was
6509 initially provided by Paul Sokolovsky, allows one to omit the decorations
6510 to achieve a behavior that conforms to that on POSIX/Un*x platforms. This
6511 feature is enabled with the
6512 .Li --enable-auto-import
6513 command-line option, although it is enabled by default on cygwin/mingw. The
6514 .Li --enable-auto-import
6515 option itself now serves mainly to suppress any warnings that are ordinarily
6516 emitted when linked objects trigger the feature's use.
6518 auto-import of variables does not always work flawlessly without additional
6519 assistance. Sometimes, you will see this message
6521 "variable '<var>' can't be auto-imported. Please read the documentation for
6523 .Li --enable-auto-import
6527 .Li --enable-auto-import
6528 documentation explains why this error occurs, and several methods that can
6529 be used to overcome this difficulty. One of these methods is the
6530 .Em runtime pseudo-relocs
6531 feature, described below.
6533 For complex variables imported from DLLs (such as structs or classes), object
6534 files typically contain a base address for the variable and an offset (
6536 within the variable--to specify a particular field or public member, for instance.
6537 Unfortunately, the runtime loader used in win32 environments is incapable
6538 of fixing these references at runtime without the additional information supplied
6539 by dllimport/dllexport decorations. The standard auto-import feature described
6540 above is unable to resolve these references.
6543 .Li --enable-runtime-pseudo-relocs
6544 switch allows these references to be resolved without error, while leaving
6545 the task of adjusting the references themselves (with their non-zero addends)
6546 to specialized code provided by the runtime environment. Recent versions of
6547 the cygwin and mingw environments and compilers provide this runtime support;
6548 older versions do not. However, the support is only necessary on the developer's
6549 platform; the compiled result will run without error on an older system.
6551 .Li --enable-runtime-pseudo-relocs
6552 is not the default; it must be explicitly enabled as needed.
6554 .It direct linking to a dll
6555 The cygwin/mingw ports of
6557 support the direct linking, including data symbols, to a dll without the usage
6558 of any import libraries. This is much faster and uses much less memory than
6559 does the traditional import library method, especially when linking large
6560 libraries or applications. When
6562 creates an import lib, each function or variable exported from the dll is
6563 stored in its own bfd, even though a single bfd could contain many exports.
6564 The overhead involved in storing, loading, and processing so many bfd's is
6565 quite large, and explains the tremendous time, memory, and storage needed
6566 to link against particularly large or complex libraries when using import
6569 Linking directly to a dll uses no extra command-line switches other than
6575 already searches for a number of names to match each library. All that is
6576 needed from the developer's perspective is an understanding of this search,
6577 in order to force ld to select the dll instead of an import library.
6579 For instance, when ld is called with the argument
6581 it will attempt to find, in the first directory of its search path,
6583 .Bd -literal -offset indent
6593 before moving on to the next directory in the search path.
6595 (*) Actually, this is not
6598 .Li <prefix>xxx.dll ,
6604 .Li --dll-search-prefix=<prefix> .
6605 In the case of cygwin, the standard gcc spec file includes
6606 .Li --dll-search-prefix=cyg ,
6607 so in effect we actually search for
6610 Other win32-based unix environments, such as mingw or pw32, may use other
6612 es, although at present only cygwin makes use of this feature. It was originally
6613 intended to help avoid name conflicts among dll's built for the various win32/un*x
6614 environments, so that (for example) two versions of a zlib dll could coexist
6615 on the same machine.
6617 The generic cygwin/mingw path layout uses a
6619 directory for applications and dll's and a
6621 directory for the import libraries (using cygwin nomenclature):
6623 .Bd -literal -offset indent
6627 libxxx.dll.a (in case of dll's)
6628 libxxx.a (in case of static archive)
6631 Linking directly to a dll without using the import library can be done two
6634 1. Use the dll directly by adding the
6636 path to the link line
6637 .Bd -literal -offset indent
6638 gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
6641 However, as the dll's often have version numbers appended to their names (
6642 .Li cygncurses-5.dll )
6643 this will often fail, unless one specifies
6644 .Li -L../bin -lncurses-5
6645 to include the version. Import libs are generally not versioned, and do not
6646 have this difficulty.
6648 2. Create a symbolic link from the dll to a file in the
6650 directory according to the above mentioned search pattern. This should be
6651 used to avoid unwanted changes in the tools needed for making the app/dll.
6653 .Bd -literal -offset indent
6654 ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
6657 Then you can link without any make environment changes.
6659 .Bd -literal -offset indent
6660 gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
6663 This technique also avoids the version number problems, because the following
6666 .Bd -literal -offset indent
6670 libxxx.dll.a -> ../bin/cygxxx-5.dll
6673 Linking directly to a dll without using an import lib will work even when
6674 auto-import features are exercised, and even when
6675 .Li --enable-runtime-pseudo-relocs
6678 Given the improvements in speed and memory usage, one might justifiably wonder
6679 why import libraries are used at all. There are three reasons:
6681 1. Until recently, the link-directly-to-dll functionality did
6683 work with auto-imported data.
6685 2. Sometimes it is necessary to include pure static objects within the import
6686 library (which otherwise contains only bfd's for indirection symbols that
6687 point to the exports of a dll). Again, the import lib for the cygwin kernel
6688 makes use of this ability, and it is not possible to do this without an import
6691 3. Symbol aliases can only be resolved using an import lib. This is critical
6692 when linking against OS-supplied dll's (eg, the win32 API) in which symbols
6693 are usually exported as undecorated aliases of their stdcall-decorated assembly
6696 So, import libs are not going away. But the ability to replace true import
6697 libs with a simple symbolic link to (or a copy of) a dll, in many cases, is
6698 a useful addition to the suite of tools binutils makes available to the win32
6699 developer. Given the massive improvements in memory requirements during linking,
6700 storage requirements, and linking speed, we expect that many developers will
6701 soon begin to use this feature whenever possible.
6705 .It adding additional names
6706 Sometimes, it is useful to export symbols with additional names. A symbol
6710 but it can also be exported as
6712 by using special directives in the DEF file when creating the dll. This will
6713 affect also the optional created import library. Consider the following DEF
6716 .Bd -literal -offset indent
6717 LIBRARY "xyz.dll" BASE=0x61000000
6731 Another method for creating a symbol alias is to create it in the source code
6732 using the "weak" attribute:
6734 .Bd -literal -offset indent
6735 void foo () { /* Do something. */; }
6736 void _foo () __attribute__ ((weak, alias ("foo")));
6739 See the gcc manual for more information about attributes and weak symbols.
6741 .It renaming symbols
6742 Sometimes it is useful to rename exports. For instance, the cygwin kernel
6743 does this regularly. A symbol
6749 by using special directives in the DEF file. (This will also affect the import
6750 library, if it is created). In the following example:
6752 .Bd -literal -offset indent
6753 LIBRARY "xyz.dll" BASE=0x61000000
6761 maps the exported symbol
6767 Note: using a DEF file disables the default auto-export behavior, unless the
6768 .Li --export-all-symbols
6769 command line option is used. If, however, you are trying to rename symbols,
6770 then you should list
6772 desired exports in the DEF file, including the symbols that are not being
6776 .Li --export-all-symbols
6777 option. If you list only the renamed symbols in the DEF file, and use
6778 .Li --export-all-symbols
6779 to handle the other symbols, then the both the new names
6781 the original names for the renamed symbols will be exported. In effect, you'd
6782 be aliasing those symbols, not renaming them, which is probably not what you
6786 The Windows object format, PE, specifies a form of weak symbols called weak
6787 externals. When a weak symbol is linked and the symbol is not defined, the
6788 weak symbol becomes an alias for some other symbol. There are three variants
6792 Definition is searched for in objects and libraries, historically
6793 called lazy externals.
6795 Definition is searched for only in other objects, not in libraries.
6796 This form is not presently implemented.
6798 No search; the symbol is an alias. This form is not presently
6801 As a GNU extension, weak symbols that do not specify an alternate symbol are
6802 supported. If the symbol is undefined when linking, the symbol uses a default
6806 .Ss Li ld and Xtensa Processors
6809 behavior for Xtensa processors is to interpret
6811 commands so that lists of explicitly named sections in a specification with
6812 a wildcard file will be interleaved when necessary to keep literal pools within
6813 the range of PC-relative load offsets. For example, with the command:
6815 .Bd -literal -offset indent
6825 may interleave some of the
6829 sections from different object files to ensure that the literal pools are
6830 within the range of PC-relative load offsets. A valid interleaving might place
6833 sections from an initial group of files followed by the
6835 sections of that group of files. Then, the
6837 sections from the rest of the files and the
6839 sections from the rest of the files would follow.
6841 Relaxation is enabled by default for the Xtensa version of
6843 and provides two important link-time optimizations. The first optimization
6844 is to combine identical literal values to reduce code size. A redundant literal
6845 will be removed and all the
6847 instructions that use it will be changed to reference an identical literal,
6848 as long as the location of the replacement literal is within the offset range
6851 instructions. The second optimization is to remove unnecessary overhead from
6852 assembler-generated \(lqlongcall\(rq sequences of
6856 when the target functions are within range of direct
6860 For each of these cases where an indirect call sequence can be optimized to
6861 a direct call, the linker will change the
6865 instruction, remove the
6867 instruction, and remove the literal referenced by the
6869 instruction if it is not used for anything else. Removing the
6871 instruction always reduces code size but can potentially hurt performance
6872 by changing the alignment of subsequent branch targets. By default, the linker
6873 will always preserve alignments, either by switching some instructions between
6874 24-bit encodings and the equivalent density instructions or by inserting a
6875 no-op in place of the
6877 instruction that was removed. If code size is more important than performance,
6880 option can be used to prevent the linker from widening density instructions
6881 or inserting no-ops, except in a few cases where no-ops are required for correctness.
6883 The following Xtensa-specific command-line options can be used to control
6888 Since the Xtensa version of
6892 option by default, the
6894 option is provided to disable relaxation.
6897 When optimizing indirect calls to direct calls, optimize for code size more
6898 than performance. With this option, the linker will not insert no-ops or widen
6899 density instructions to preserve branch target alignment. There may still
6900 be some cases where no-ops are required to preserve the correctness of the
6905 The linker accesses object and archive files using the BFD libraries. These
6906 libraries allow the linker to use the same routines to operate on object files
6907 whatever the object file format. A different object file format can be supported
6908 simply by creating a new BFD back end and adding it to the library. To conserve
6909 runtime memory, however, the linker and associated tools are usually configured
6910 to support only a subset of the object file formats available. You can use
6914 to list all the formats available for your configuration.
6916 As with most implementations, BFD is a compromise between several conflicting
6917 requirements. The major factor influencing BFD design was efficiency: any
6918 time used converting between formats is time which would not have been spent
6919 had BFD not been involved. This is partly offset by abstraction payback; since
6920 BFD simplifies applications and back ends, more time and care may be spent
6921 optimizing algorithms for a greater speed.
6923 One minor artifact of the BFD solution which you should bear in mind is the
6924 potential for information loss. There are two places where useful information
6925 can be lost using the BFD mechanism: during conversion and during output.See Section
6926 .Dq BFD information loss .
6928 .Ss How It Works: An Outline of BFD
6929 When an object file is opened, BFD subroutines automatically determine the
6930 format of the input object file. They then build a descriptor in memory with
6931 pointers to routines that will be used to access elements of the object file's
6934 As different information from the object files is required, BFD reads from
6935 different sections of the file and processes them. For example, a very common
6936 operation for the linker is processing symbol tables. Each BFD back end provides
6937 a routine for converting between the object file's representation of symbols
6938 and an internal canonical format. When the linker asks for the symbol table
6939 of an object file, it calls through a memory pointer to the routine from the
6940 relevant BFD back end which reads and converts the table into a canonical
6941 form. The linker then operates upon the canonical form. When the link is finished
6942 and the linker writes the output file's symbol table, another BFD back end
6943 routine is called to take the newly created symbol table and convert it into
6944 the chosen output format.
6946 .Em Information Loss
6948 .Em Information can be lost during output.
6949 The output formats supported by BFD do not provide identical facilities, and
6950 information which can be described in one form has nowhere to go in another
6951 format. One example of this is alignment information in
6953 There is nowhere in an
6955 format file to store alignment information on the contained data, so when
6956 a file is linked from
6960 image is produced, alignment information will not propagate to the output
6961 file. (The linker will still use the alignment information internally, so
6962 the link is performed correctly).
6964 Another example is COFF section names. COFF files may contain an unlimited
6965 number of sections, each one with a textual section name. If the target of
6966 the link is a format which does not have many sections (e.g.,
6968 or has sections without names (e.g., the Oasys format), the link cannot be
6969 done simply. You can circumvent this problem by describing the desired input-to-output
6970 section mapping with the linker command language.
6972 .Em Information can be lost during canonicalization.
6973 The BFD internal canonical form of the external formats is not exhaustive;
6974 there are structures in input formats for which there is no direct representation
6975 internally. This means that the BFD back ends cannot maintain all possible
6976 data richness through the transformation between external to internal and
6977 back to external formats.
6979 This limitation is only a problem when an application reads one format and
6980 writes another. Each BFD back end is responsible for maintaining as much data
6981 as possible, and the internal BFD canonical form has structures which are
6982 opaque to the BFD core, and exported only to the back ends. When a file is
6983 read in one format, the canonical form is generated for BFD and the application.
6984 At the same time, the back end saves away any information which may otherwise
6985 be lost. If the data is then written back in the same format, the back end
6986 routine will be able to use the canonical form provided by the BFD core as
6987 well as the information it prepared earlier. Since there is a great deal of
6988 commonality between back ends, there is no information lost when linking or
6989 copying big endian COFF to little endian COFF, or
6993 When a mixture of formats is linked, the information is only lost from the
6994 files whose format differs from the destination.
6996 .Em The BFD canonical object-file format
6998 The greatest potential for loss of information occurs when there is the least
6999 overlap between the information provided by the source format, that stored
7000 by the canonical format, and that needed by the destination format. A brief
7001 description of the canonical form may help you understand which kinds of data
7002 you can count on preserving across conversions.
7006 Information stored on a per-file basis includes target machine architecture,
7007 particular implementation format type, a demand pageable bit, and a write
7008 protected bit. Information like Unix magic numbers is not stored here---only
7009 the magic numbers' meaning, so a
7011 file would have both the demand pageable bit and the write protected text
7012 bit set. The byte order of the target is stored on a per-file basis, so that
7013 big- and little-endian object files may be used with one another.
7016 Each section in the input file contains the name of the section, the section's
7017 original address in the object file, size and alignment information, various
7018 flags, and pointers into other BFD data structures.
7021 Each symbol contains a pointer to the information for the object file which
7022 originally defined it, its name, its value, and various flag bits. When a
7023 BFD back end reads in a symbol table, it relocates all symbols to make them
7024 relative to the base of the section where they were defined. Doing this ensures
7025 that each symbol points to its containing section. Each symbol also has a
7026 varying amount of hidden private data for the BFD back end. Since the symbol
7027 points to the original file, the private data format for that symbol is accessible.
7029 can operate on a collection of symbols of wildly different formats without
7032 Normal global and simple local symbols are maintained on output, so an output
7033 file (no matter its format) will retain symbols pointing to functions and
7034 to global, static, and common variables. Some symbol information is not worth
7037 type information is stored in the symbol table as long symbol names. This
7038 information would be useless to most COFF debuggers; the linker has command
7039 line switches to allow users to throw it away.
7041 There is one word of type information within the symbol, so if the format
7042 supports symbol type information within symbols (for example, COFF, IEEE,
7043 Oasys) and the type is simple enough to fit within one word (nearly everything
7044 but aggregates), the information will be preserved.
7046 .It relocation level
7047 Each canonical BFD relocation record contains a pointer to the symbol to relocate
7048 to, the offset of the data to relocate, the section the data is in, and a
7049 pointer to a relocation type descriptor. Relocation is performed by passing
7050 messages through the relocation type descriptor and the symbol pointer. Therefore,
7051 relocations can be performed on output data using a relocation method that
7052 is only available in one of the input formats. For instance, Oasys provides
7053 a byte relocation format. A relocation record requesting this relocation type
7054 would point indirectly to a routine to perform this, so the relocation may
7055 be performed on a byte being written to a 68k COFF file, even though 68k COFF
7056 has no such relocation type.
7059 Object formats can contain, for debugging purposes, some form of mapping between
7060 symbols, source line numbers, and addresses in the output file. These addresses
7061 have to be relocated along with the symbol information. Each symbol with an
7062 associated list of line number records points to the first record of the list.
7063 The head of a line number list consists of a pointer to the symbol, which
7064 allows finding out the address of the function whose line number is being
7065 described. The rest of the list is made up of pairs: offsets into the section
7066 and line numbers. Any format which can simply derive this information can
7067 pass it successfully between formats (COFF, IEEE and Oasys).
7071 Your bug reports play an essential role in making
7075 Reporting a bug may help you by bringing a solution to your problem, or it
7076 may not. But in any case the principal function of a bug report is to help
7077 the entire community by making the next version of
7079 work better. Bug reports are your contribution to the maintenance of
7082 In order for a bug report to serve its purpose, you must include the information
7083 that enables us to fix the bug.
7085 .Ss Have You Found a Bug?
7086 If you are not sure whether you have found a bug, here are some guidelines:
7090 If the linker gets a fatal signal, for any input whatever, that is a
7092 bug. Reliable linkers never crash.
7097 produces an error message for valid input, that is a bug.
7102 does not produce an error message for invalid input, that may be a bug. In
7103 the general case, the linker can not verify that object files are correct.
7106 If you are an experienced user of linkers, your suggestions for improvement
7109 are welcome in any case.
7112 .Ss How to Report Bugs
7113 A number of companies and individuals offer support for GNU products. If you
7116 from a support organization, we recommend you contact that organization first.
7118 You can find contact information for many support companies and individuals
7121 in the GNU Emacs distribution.
7123 The fundamental principle of reporting bugs usefully is this:
7124 .Sy report all the facts .
7125 If you are not sure whether to state a fact or leave it out, state it!
7127 Often people omit facts because they think they know what causes the problem
7128 and assume that some details do not matter. Thus, you might assume that the
7129 name of a symbol you use in an example does not matter. Well, probably it
7130 does not, but one cannot be sure. Perhaps the bug is a stray memory reference
7131 which happens to fetch from the location where that name is stored in memory;
7132 perhaps, if the name were different, the contents of that location would fool
7133 the linker into doing the right thing despite the bug. Play it safe and give
7134 a specific, complete example. That is the easiest thing for you to do, and
7137 Keep in mind that the purpose of a bug report is to enable us to fix the bug
7138 if it is new to us. Therefore, always write your bug reports on the assumption
7139 that the bug has not been reported previously.
7141 Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq
7142 This cannot help us fix a bug, so it is basically useless. We respond by asking
7143 for enough details to enable us to investigate. You might as well expedite
7144 matters by sending them to begin with.
7146 To enable us to fix the bug, you should include all these things:
7153 announces it if you start it with the
7157 Without this, we will not know whether there is any point in looking for the
7158 bug in the current version of
7162 Any patches you may have applied to the
7164 source, including any patches made to the
7169 The type of machine you are using, and the operating system name and version
7173 What compiler (and its version) was used to compile
7180 The command arguments you gave the linker to link your example and observe
7181 the bug. To guarantee you will not omit something important, list them all.
7182 A copy of the Makefile (or the output from make) is sufficient.
7184 If we were to try to guess the arguments, we would probably guess wrong and
7185 then we might not encounter the bug.
7188 A complete input file, or set of input files, that will reproduce the bug.
7189 It is generally most helpful to send the actual object files provided that
7190 they are reasonably small. Say no more than 10K. For bigger files you can
7191 either make them available by FTP or HTTP or else state that you are willing
7192 to send the object file(s) to whomever requests them. (Note - your email will
7193 be going to a mailing list, so we do not want to clog it up with large attachments).
7194 But small attachments are best.
7196 If the source files were assembled using
7200 then it may be OK to send the source files rather than the object files. In
7201 this case, be sure to say exactly what version of
7205 was used to produce the object files. Also say how
7212 A description of what behavior you observe that you believe is incorrect.
7213 For example, \(lqIt gets a fatal signal.\(rq
7215 Of course, if the bug is that
7217 gets a fatal signal, then we will certainly notice it. But if the bug is incorrect
7218 output, we might not notice unless it is glaringly wrong. You might as well
7219 not give us a chance to make a mistake.
7221 Even if the problem you experience is a fatal signal, you should still say
7222 so explicitly. Suppose something strange is going on, such as, your copy of
7224 is out of sync, or you have encountered a bug in the C library on your system.
7225 (This has happened!) Your copy might crash and ours would not. If you told
7226 us to expect a crash, then when ours fails to crash, we would know that the
7227 bug was not happening for us. If you had not told us to expect a crash, then
7228 we would not be able to draw any conclusion from our observations.
7231 If you wish to suggest changes to the
7233 source, send us context diffs, as generated by
7240 option. Always send diffs from the old file to the new file. If you even discuss
7243 source, refer to it by context, not by line number.
7245 The line numbers in our development sources will not match those in your sources.
7246 Your line numbers would convey no useful information to us.
7249 Here are some things that are not necessary:
7253 A description of the envelope of the bug.
7255 Often people who encounter a bug spend a lot of time investigating which changes
7256 to the input file will make the bug go away and which changes will not affect
7259 This is often time consuming and not very useful, because the way we will
7260 find the bug is by running a single example under the debugger with breakpoints,
7261 not by pure deduction from a series of examples. We recommend that you save
7262 your time for something else.
7264 Of course, if you can find a simpler example to report
7266 of the original one, that is a convenience for us. Errors in the output will
7267 be easier to spot, running under the debugger will take less time, and so
7270 However, simplification is not vital; if you do not want to do this, report
7271 the bug anyway and send us the entire test case you used.
7274 A patch for the bug.
7276 A patch for the bug does help us if it is a good one. But do not omit the
7277 necessary information, such as the test case, on the assumption that a patch
7278 is all we need. We might see problems with your patch and decide to fix the
7279 problem another way, or we might not understand it at all.
7281 Sometimes with a program as complicated as
7283 it is very hard to construct an example that will make the program follow
7284 a certain path through the code. If you do not send us the example, we will
7285 not be able to construct one, so we will not be able to verify that the bug
7288 And if we cannot understand what bug you are trying to fix, or why your patch
7289 should be an improvement, we will not install it. A test case will help us
7293 A guess about what the bug is or what it depends on.
7295 Such guesses are usually wrong. Even we cannot guess right about such things
7296 without first using the debugger to find the facts.
7299 .Sh MRI Compatible Script Files
7300 To aid users making the transition to GNU
7302 from the MRI linker,
7304 can use MRI compatible linker scripts as an alternative to the more general-purpose
7305 linker scripting language described in Scripts. MRI compatible linker scripts
7306 have a much simpler command set than the scripting language otherwise used
7311 supports the most commonly used MRI linker commands; these commands are described
7314 In general, MRI scripts aren't of much use with the
7316 object file format, since it only has three sections and MRI scripts lack
7317 some features to make use of them.
7319 You can specify a file containing an MRI-compatible script using the
7321 command-line option.
7323 Each command in an MRI-compatible script occupies its own line; each command
7324 line starts with the keyword that identifies the command (though blank lines
7325 are also allowed for punctuation). If a line of an MRI-compatible script begins
7326 with an unrecognized keyword,
7328 issues a warning message, but continues processing the script.
7330 Lines beginning with
7334 You can write these commands using all upper-case letters, or all lower case;
7339 The following list shows only the upper-case form of each command.
7342 .It ABSOLUTE Va secname
7343 .It ABSOLUTE Va secname, Va secname, ... Va secname
7346 includes in the output file all sections from all the input files. However,
7347 in an MRI-compatible script, you can use the
7349 command to restrict the sections that will be present in your output program.
7352 command is used at all in a script, then only the sections named explicitly
7355 commands will appear in the linker output. You can still use other input sections
7356 (whatever you select on the command line, or using
7358 to resolve addresses in the output file.
7360 .It ALIAS Va out-secname, Va in-secname
7361 Use this command to place the data from input section
7365 in the linker output file.
7370 .It ALIGN Va secname = Va expression
7371 Align the section called
7377 should be a power of two.
7379 .It BASE Va expression
7382 as the lowest address (other than absolute addresses) in the output file.
7384 .It CHIP Va expression
7385 .It CHIP Va expression, Va expression
7386 This command does nothing; it is accepted only for compatibility.
7389 This command does nothing whatever; it's only accepted for compatibility.
7391 .It FORMAT Va output-format
7394 command in the more general linker language, but restricted to one of these
7419 .It LIST Va anything...
7420 Print (to the standard output file) a link map, as produced by the
7427 may be followed by anything on the same line, with no change in its effect.
7429 .It LOAD Va filename
7430 .It LOAD Va filename, Va filename, ... Va filename
7431 Include one or more object file
7433 in the link; this has the same effect as specifying
7439 .It NAME Va output-name
7441 is the name for the program produced by
7443 the MRI-compatible command
7445 is equivalent to the command-line option
7447 or the general script language command
7450 .It ORDER Va secname, Va secname, ... Va secname
7451 .It ORDER Va secname Va secname Va secname
7454 orders the sections in its output file in the order in which they first appear
7455 in the input files. In an MRI-compatible script, you can override this ordering
7458 command. The sections you list with
7460 will appear first in your output file, in the order specified.
7462 .It PUBLIC Va name= Va expression
7463 .It PUBLIC Va name, Va expression
7464 .It PUBLIC Va name Va expression
7469 used in the linker input files.
7471 .It SECT Va secname, Va expression
7472 .It SECT Va secname= Va expression
7473 .It SECT Va secname Va expression
7474 You can use any of these three forms of the
7476 command to specify the start address (
7480 If you have more than one
7482 statement for the same
7486 sets the start address.
7489 .Sh GNU Free Documentation License
7490 .Bd -filled -offset indent
7491 Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street,
7492 Fifth Floor, Boston, MA 02110-1301 USA
7494 Everyone is permitted to copy and distribute verbatim copies of this license
7495 document, but changing it is not allowed.
7502 The purpose of this License is to make a manual, textbook, or other written
7503 document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom
7504 to copy and redistribute it, with or without modifying it, either commercially
7505 or noncommercially. Secondarily, this License preserves for the author and
7506 publisher a way to get credit for their work, while not being considered responsible
7507 for modifications made by others.
7509 This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the
7510 document must themselves be free in the same sense. It complements the GNU
7511 General Public License, which is a copyleft license designed for free software.
7513 We have designed this License in order to use it for manuals for free software,
7514 because free software needs free documentation: a free program should come
7515 with manuals providing the same freedoms that the software does. But this
7516 License is not limited to software manuals; it can be used for any textual
7517 work, regardless of subject matter or whether it is published as a printed
7518 book. We recommend this License principally for works whose purpose is instruction
7522 APPLICABILITY AND DEFINITIONS
7524 This License applies to any manual or other work that contains a notice placed
7525 by the copyright holder saying it can be distributed under the terms of this
7526 License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member
7527 of the public is a licensee, and is addressed as \(lqyou.\(rq
7529 A \(lqModified Version\(rq of the Document means any work containing the Document
7530 or a portion of it, either copied verbatim, or with modifications and/or translated
7531 into another language.
7533 A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document
7534 that deals exclusively with the relationship of the publishers or authors
7535 of the Document to the Document's overall subject (or to related matters)
7536 and contains nothing that could fall directly within that overall subject.
7537 (For example, if the Document is in part a textbook of mathematics, a Secondary
7538 Section may not explain any mathematics.) The relationship could be a matter
7539 of historical connection with the subject or with related matters, or of legal,
7540 commercial, philosophical, ethical or political position regarding them.
7542 The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated,
7543 as being those of Invariant Sections, in the notice that says that the Document
7544 is released under this License.
7546 The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover
7547 Texts or Back-Cover Texts, in the notice that says that the Document is released
7550 A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented
7551 in a format whose specification is available to the general public, whose
7552 contents can be viewed and edited directly and straightforwardly with generic
7553 text editors or (for images composed of pixels) generic paint programs or
7554 (for drawings) some widely available drawing editor, and that is suitable
7555 for input to text formatters or for automatic translation to a variety of
7556 formats suitable for input to text formatters. A copy made in an otherwise
7557 Transparent file format whose markup has been designed to thwart or discourage
7558 subsequent modification by readers is not Transparent. A copy that is not
7559 \(lqTransparent\(rq is called \(lqOpaque.\(rq
7561 Examples of suitable formats for Transparent copies include plain ASCII without
7562 markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
7563 available DTD, and standard-conforming simple HTML designed for human modification.
7564 Opaque formats include PostScript, PDF, proprietary formats that can be read
7565 and edited only by proprietary word processors, SGML or XML for which the
7566 DTD and/or processing tools are not generally available, and the machine-generated
7567 HTML produced by some word processors for output purposes only.
7569 The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such
7570 following pages as are needed to hold, legibly, the material this License
7571 requires to appear in the title page. For works in formats which do not have
7572 any title page as such, \(lqTitle Page\(rq means the text near the most prominent
7573 appearance of the work's title, preceding the beginning of the body of the
7579 You may copy and distribute the Document in any medium, either commercially
7580 or noncommercially, provided that this License, the copyright notices, and
7581 the license notice saying this License applies to the Document are reproduced
7582 in all copies, and that you add no other conditions whatsoever to those of
7583 this License. You may not use technical measures to obstruct or control the
7584 reading or further copying of the copies you make or distribute. However,
7585 you may accept compensation in exchange for copies. If you distribute a large
7586 enough number of copies you must also follow the conditions in section 3.
7588 You may also lend copies, under the same conditions stated above, and you
7589 may publicly display copies.
7594 If you publish printed copies of the Document numbering more than 100, and
7595 the Document's license notice requires Cover Texts, you must enclose the copies
7596 in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover
7597 Texts on the front cover, and Back-Cover Texts on the back cover. Both covers
7598 must also clearly and legibly identify you as the publisher of these copies.
7599 The front cover must present the full title with all words of the title equally
7600 prominent and visible. You may add other material on the covers in addition.
7601 Copying with changes limited to the covers, as long as they preserve the title
7602 of the Document and satisfy these conditions, can be treated as verbatim copying
7605 If the required texts for either cover are too voluminous to fit legibly,
7606 you should put the first ones listed (as many as fit reasonably) on the actual
7607 cover, and continue the rest onto adjacent pages.
7609 If you publish or distribute Opaque copies of the Document numbering more
7610 than 100, you must either include a machine-readable Transparent copy along
7611 with each Opaque copy, or state in or with each Opaque copy a publicly-accessible
7612 computer-network location containing a complete Transparent copy of the Document,
7613 free of added material, which the general network-using public has access
7614 to download anonymously at no charge using public-standard network protocols.
7615 If you use the latter option, you must take reasonably prudent steps, when
7616 you begin distribution of Opaque copies in quantity, to ensure that this Transparent
7617 copy will remain thus accessible at the stated location until at least one
7618 year after the last time you distribute an Opaque copy (directly or through
7619 your agents or retailers) of that edition to the public.
7621 It is requested, but not required, that you contact the authors of the Document
7622 well before redistributing any large number of copies, to give them a chance
7623 to provide you with an updated version of the Document.
7628 You may copy and distribute a Modified Version of the Document under the conditions
7629 of sections 2 and 3 above, provided that you release the Modified Version
7630 under precisely this License, with the Modified Version filling the role of
7631 the Document, thus licensing distribution and modification of the Modified
7632 Version to whoever possesses a copy of it. In addition, you must do these
7633 things in the Modified Version:
7635 A. Use in the Title Page (and on the covers, if any) a title distinct from
7636 that of the Document, and from those of previous versions (which should, if
7637 there were any, be listed in the History section of the Document). You may
7638 use the same title as a previous version if the original publisher of that
7639 version gives permission. B. List on the Title Page, as authors, one or more
7640 persons or entities responsible for authorship of the modifications in the
7641 Modified Version, together with at least five of the principal authors of
7642 the Document (all of its principal authors, if it has less than five). C.
7643 State on the Title page the name of the publisher of the Modified Version,
7644 as the publisher. D. Preserve all the copyright notices of the Document.
7645 E. Add an appropriate copyright notice for your modifications adjacent to
7646 the other copyright notices. F. Include, immediately after the copyright
7647 notices, a license notice giving the public permission to use the Modified
7648 Version under the terms of this License, in the form shown in the Addendum
7649 below. G. Preserve in that license notice the full lists of Invariant Sections
7650 and required Cover Texts given in the Document's license notice. H. Include
7651 an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq,
7652 and its title, and add to it an item stating at least the title, year, new
7653 authors, and publisher of the Modified Version as given on the Title Page.
7654 If there is no section entitled \(lqHistory\(rq in the Document, create one stating
7655 the title, year, authors, and publisher of the Document as given on its Title
7656 Page, then add an item describing the Modified Version as stated in the previous
7657 sentence. J. Preserve the network location, if any, given in the Document
7658 for public access to a Transparent copy of the Document, and likewise the
7659 network locations given in the Document for previous versions it was based
7660 on. These may be placed in the \(lqHistory\(rq section. You may omit a network location
7661 for a work that was published at least four years before the Document itself,
7662 or if the original publisher of the version it refers to gives permission.
7663 K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's
7664 title, and preserve in the section all the substance and tone of each of the
7665 contributor acknowledgements and/or dedications given therein. L. Preserve
7666 all the Invariant Sections of the Document, unaltered in their text and in
7667 their titles. Section numbers or the equivalent are not considered part of
7668 the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section
7669 may not be included in the Modified Version. N. Do not retitle any existing
7670 section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section.
7672 If the Modified Version includes new front-matter sections or appendices that
7673 qualify as Secondary Sections and contain no material copied from the Document,
7674 you may at your option designate some or all of these sections as invariant.
7675 To do this, add their titles to the list of Invariant Sections in the Modified
7676 Version's license notice. These titles must be distinct from any other section
7679 You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing
7680 but endorsements of your Modified Version by various parties--for example,
7681 statements of peer review or that the text has been approved by an organization
7682 as the authoritative definition of a standard.
7684 You may add a passage of up to five words as a Front-Cover Text, and a passage
7685 of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
7686 in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover
7687 Text may be added by (or through arrangements made by) any one entity. If
7688 the Document already includes a cover text for the same cover, previously
7689 added by you or by arrangement made by the same entity you are acting on behalf
7690 of, you may not add another; but you may replace the old one, on explicit
7691 permission from the previous publisher that added the old one.
7693 The author(s) and publisher(s) of the Document do not by this License give
7694 permission to use their names for publicity for or to assert or imply endorsement
7695 of any Modified Version.
7700 You may combine the Document with other documents released under this License,
7701 under the terms defined in section 4 above for modified versions, provided
7702 that you include in the combination all of the Invariant Sections of all of
7703 the original documents, unmodified, and list them all as Invariant Sections
7704 of your combined work in its license notice.
7706 The combined work need only contain one copy of this License, and multiple
7707 identical Invariant Sections may be replaced with a single copy. If there
7708 are multiple Invariant Sections with the same name but different contents,
7709 make the title of each such section unique by adding at the end of it, in
7710 parentheses, the name of the original author or publisher of that section
7711 if known, or else a unique number. Make the same adjustment to the section
7712 titles in the list of Invariant Sections in the license notice of the combined
7715 In the combination, you must combine any sections entitled \(lqHistory\(rq in the
7716 various original documents, forming one section entitled \(lqHistory\(rq; likewise
7717 combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled
7718 \(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq
7721 COLLECTIONS OF DOCUMENTS
7723 You may make a collection consisting of the Document and other documents released
7724 under this License, and replace the individual copies of this License in the
7725 various documents with a single copy that is included in the collection, provided
7726 that you follow the rules of this License for verbatim copying of each of
7727 the documents in all other respects.
7729 You may extract a single document from such a collection, and distribute it
7730 individually under this License, provided you insert a copy of this License
7731 into the extracted document, and follow this License in all other respects
7732 regarding verbatim copying of that document.
7735 AGGREGATION WITH INDEPENDENT WORKS
7737 A compilation of the Document or its derivatives with other separate and independent
7738 documents or works, in or on a volume of a storage or distribution medium,
7739 does not as a whole count as a Modified Version of the Document, provided
7740 no compilation copyright is claimed for the compilation. Such a compilation
7741 is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained
7742 works thus compiled with the Document, on account of their being thus compiled,
7743 if they are not themselves derivative works of the Document.
7745 If the Cover Text requirement of section 3 is applicable to these copies of
7746 the Document, then if the Document is less than one quarter of the entire
7747 aggregate, the Document's Cover Texts may be placed on covers that surround
7748 only the Document within the aggregate. Otherwise they must appear on covers
7749 around the whole aggregate.
7754 Translation is considered a kind of modification, so you may distribute translations
7755 of the Document under the terms of section 4. Replacing Invariant Sections
7756 with translations requires special permission from their copyright holders,
7757 but you may include translations of some or all Invariant Sections in addition
7758 to the original versions of these Invariant Sections. You may include a translation
7759 of this License provided that you also include the original English version
7760 of this License. In case of a disagreement between the translation and the
7761 original English version of this License, the original English version will
7767 You may not copy, modify, sublicense, or distribute the Document except as
7768 expressly provided for under this License. Any other attempt to copy, modify,
7769 sublicense or distribute the Document is void, and will automatically terminate
7770 your rights under this License. However, parties who have received copies,
7771 or rights, from you under this License will not have their licenses terminated
7772 so long as such parties remain in full compliance.
7775 FUTURE REVISIONS OF THIS LICENSE
7777 The Free Software Foundation may publish new, revised versions of the GNU
7778 Free Documentation License from time to time. Such new versions will be similar
7779 in spirit to the present version, but may differ in detail to address new
7780 problems or concerns. See http://www.gnu.org/copyleft/.
7782 Each version of the License is given a distinguishing version number. If the
7783 Document specifies that a particular numbered version of this License \(lqor any
7784 later version\(rq applies to it, you have the option of following the terms and
7785 conditions either of that specified version or of any later version that has
7786 been published (not as a draft) by the Free Software Foundation. If the Document
7787 does not specify a version number of this License, you may choose any version
7788 ever published (not as a draft) by the Free Software Foundation.
7791 .Ss ADDENDUM: How to use this License for your documents
7792 To use this License in a document you have written, include a copy of the
7793 License in the document and put the following copyright and license notices
7794 just after the title page:
7796 .Bd -literal -offset indent
7798 Copyright (C) year your name.
7799 Permission is granted to copy, distribute and/or modify this document
7800 under the terms of the GNU Free Documentation License, Version 1.1
7801 or any later version published by the Free Software Foundation;
7802 with the Invariant Sections being list their titles, with the
7803 Front-Cover Texts being list, and with the Back-Cover Texts being list.
7804 A copy of the license is included in the section entitled "GNU
7805 Free Documentation License."
7809 If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead
7810 of saying which ones are invariant. If you have no Front-Cover Texts, write
7811 \(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being
7813 \(rq; likewise for Back-Cover Texts.
7815 If your document contains nontrivial examples of program code, we recommend
7816 releasing these examples in parallel under your choice of free software license,
7817 such as the GNU General Public License, to permit their use in free software.