3 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
4 @c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
7 @include configdoc.texi
8 @c (configdoc.texi is generated by the Makefile)
14 @macro gcctabopt{body}
20 @c Configure for the generation of man pages
58 * Ld: (ld). The GNU linker.
64 This file documents the @sc{gnu} linker LD version @value{VERSION}.
66 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
67 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
71 Permission is granted to copy, distribute and/or modify this document
72 under the terms of the GNU Free Documentation License, Version 1.1
73 or any later version published by the Free Software Foundation;
74 with no Invariant Sections, with no Front-Cover Texts, and with no
75 Back-Cover Texts. A copy of the license is included in the
76 section entitled ``GNU Free Documentation License''.
78 Permission is granted to process this file through Tex and print the
79 results, provided the printed document carries copying permission
80 notice identical to this one except for the removal of this paragraph
81 (this paragraph not being relevant to the printed manual).
87 @setchapternewpage odd
88 @settitle Using LD, the GNU linker
91 @subtitle The GNU linker
93 @subtitle @code{ld} version 2
94 @subtitle Version @value{VERSION}
95 @author Steve Chamberlain
96 @author Ian Lance Taylor
101 \hfill Red Hat Inc\par
102 \hfill nickc\@credhat.com, doc\@redhat.com\par
103 \hfill {\it Using LD, the GNU linker}\par
104 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
106 \global\parindent=0pt % Steve likes it this way.
109 @vskip 0pt plus 1filll
110 @c man begin COPYRIGHT
111 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
112 2002, 2003, 2004 Free Software Foundation, Inc.
114 Permission is granted to copy, distribute and/or modify this document
115 under the terms of the GNU Free Documentation License, Version 1.1
116 or any later version published by the Free Software Foundation;
117 with no Invariant Sections, with no Front-Cover Texts, and with no
118 Back-Cover Texts. A copy of the license is included in the
119 section entitled ``GNU Free Documentation License''.
124 @c FIXME: Talk about importance of *order* of args, cmds to linker!
129 This file documents the @sc{gnu} linker ld version @value{VERSION}.
131 This document is distributed under the terms of the GNU Free
132 Documentation License. A copy of the license is included in the
133 section entitled ``GNU Free Documentation License''.
136 * Overview:: Overview
137 * Invocation:: Invocation
138 * Scripts:: Linker Scripts
140 * Machine Dependent:: Machine Dependent Features
144 * H8/300:: ld and the H8/300
147 * Renesas:: ld and other Renesas micros
150 * i960:: ld and the Intel 960 family
153 * ARM:: ld and the ARM family
156 * HPPA ELF32:: ld and HPPA 32-bit ELF
159 * M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families
162 * PowerPC ELF32:: ld and PowerPC 32-bit ELF Support
165 * PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
168 * TI COFF:: ld and the TI COFF
171 * Win32:: ld and WIN32 (cygwin/mingw)
174 * Xtensa:: ld and Xtensa Processors
177 @ifclear SingleFormat
180 @c Following blank line required for remaining bug in makeinfo conds/menus
182 * Reporting Bugs:: Reporting Bugs
183 * MRI:: MRI Compatible Script Files
184 * GNU Free Documentation License:: GNU Free Documentation License
185 * LD Index:: LD Index
192 @cindex @sc{gnu} linker
193 @cindex what is this?
196 @c man begin SYNOPSIS
197 ld [@b{options}] @var{objfile} @dots{}
201 ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
202 the Info entries for @file{binutils} and
207 @c man begin DESCRIPTION
209 @command{ld} combines a number of object and archive files, relocates
210 their data and ties up symbol references. Usually the last step in
211 compiling a program is to run @command{ld}.
213 @command{ld} accepts Linker Command Language files written in
214 a superset of AT&T's Link Editor Command Language syntax,
215 to provide explicit and total control over the linking process.
219 This man page does not describe the command language; see the
220 @command{ld} entry in @code{info}, or the manual
221 ld: the GNU linker, for full details on the command language and
222 on other aspects of the GNU linker.
225 @ifclear SingleFormat
226 This version of @command{ld} uses the general purpose BFD libraries
227 to operate on object files. This allows @command{ld} to read, combine, and
228 write object files in many different formats---for example, COFF or
229 @code{a.out}. Different formats may be linked together to produce any
230 available kind of object file. @xref{BFD}, for more information.
233 Aside from its flexibility, the @sc{gnu} linker is more helpful than other
234 linkers in providing diagnostic information. Many linkers abandon
235 execution immediately upon encountering an error; whenever possible,
236 @command{ld} continues executing, allowing you to identify other errors
237 (or, in some cases, to get an output file in spite of the error).
244 @c man begin DESCRIPTION
246 The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations,
247 and to be as compatible as possible with other linkers. As a result,
248 you have many choices to control its behavior.
254 * Options:: Command Line Options
255 * Environment:: Environment Variables
259 @section Command Line Options
267 The linker supports a plethora of command-line options, but in actual
268 practice few of them are used in any particular context.
269 @cindex standard Unix system
270 For instance, a frequent use of @command{ld} is to link standard Unix
271 object files on a standard, supported Unix system. On such a system, to
272 link a file @code{hello.o}:
275 ld -o @var{output} /lib/crt0.o hello.o -lc
278 This tells @command{ld} to produce a file called @var{output} as the
279 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
280 the library @code{libc.a}, which will come from the standard search
281 directories. (See the discussion of the @samp{-l} option below.)
283 Some of the command-line options to @command{ld} may be specified at any
284 point in the command line. However, options which refer to files, such
285 as @samp{-l} or @samp{-T}, cause the file to be read at the point at
286 which the option appears in the command line, relative to the object
287 files and other file options. Repeating non-file options with a
288 different argument will either have no further effect, or override prior
289 occurrences (those further to the left on the command line) of that
290 option. Options which may be meaningfully specified more than once are
291 noted in the descriptions below.
294 Non-option arguments are object files or archives which are to be linked
295 together. They may follow, precede, or be mixed in with command-line
296 options, except that an object file argument may not be placed between
297 an option and its argument.
299 Usually the linker is invoked with at least one object file, but you can
300 specify other forms of binary input files using @samp{-l}, @samp{-R},
301 and the script command language. If @emph{no} binary input files at all
302 are specified, the linker does not produce any output, and issues the
303 message @samp{No input files}.
305 If the linker cannot recognize the format of an object file, it will
306 assume that it is a linker script. A script specified in this way
307 augments the main linker script used for the link (either the default
308 linker script or the one specified by using @samp{-T}). This feature
309 permits the linker to link against a file which appears to be an object
310 or an archive, but actually merely defines some symbol values, or uses
311 @code{INPUT} or @code{GROUP} to load other objects. Note that
312 specifying a script in this way merely augments the main linker script;
313 use the @samp{-T} option to replace the default linker script entirely.
316 For options whose names are a single letter,
317 option arguments must either follow the option letter without intervening
318 whitespace, or be given as separate arguments immediately following the
319 option that requires them.
321 For options whose names are multiple letters, either one dash or two can
322 precede the option name; for example, @samp{-trace-symbol} and
323 @samp{--trace-symbol} are equivalent. Note---there is one exception to
324 this rule. Multiple letter options that start with a lower case 'o' can
325 only be preceeded by two dashes. This is to reduce confusion with the
326 @samp{-o} option. So for example @samp{-omagic} sets the output file
327 name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
330 Arguments to multiple-letter options must either be separated from the
331 option name by an equals sign, or be given as separate arguments
332 immediately following the option that requires them. For example,
333 @samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
334 Unique abbreviations of the names of multiple-letter options are
337 Note---if the linker is being invoked indirectly, via a compiler driver
338 (e.g. @samp{gcc}) then all the linker command line options should be
339 prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
340 compiler driver) like this:
343 gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
346 This is important, because otherwise the compiler driver program may
347 silently drop the linker options, resulting in a bad link.
349 Here is a table of the generic command line switches accepted by the GNU
353 @include at-file.texi
355 @kindex -a@var{keyword}
356 @item -a@var{keyword}
357 This option is supported for HP/UX compatibility. The @var{keyword}
358 argument must be one of the strings @samp{archive}, @samp{shared}, or
359 @samp{default}. @samp{-aarchive} is functionally equivalent to
360 @samp{-Bstatic}, and the other two keywords are functionally equivalent
361 to @samp{-Bdynamic}. This option may be used any number of times.
364 @cindex architectures
366 @item -A@var{architecture}
367 @kindex --architecture=@var{arch}
368 @itemx --architecture=@var{architecture}
369 In the current release of @command{ld}, this option is useful only for the
370 Intel 960 family of architectures. In that @command{ld} configuration, the
371 @var{architecture} argument identifies the particular architecture in
372 the 960 family, enabling some safeguards and modifying the
373 archive-library search path. @xref{i960,,@command{ld} and the Intel 960
374 family}, for details.
376 Future releases of @command{ld} may support similar functionality for
377 other architecture families.
380 @ifclear SingleFormat
381 @cindex binary input format
382 @kindex -b @var{format}
383 @kindex --format=@var{format}
386 @item -b @var{input-format}
387 @itemx --format=@var{input-format}
388 @command{ld} may be configured to support more than one kind of object
389 file. If your @command{ld} is configured this way, you can use the
390 @samp{-b} option to specify the binary format for input object files
391 that follow this option on the command line. Even when @command{ld} is
392 configured to support alternative object formats, you don't usually need
393 to specify this, as @command{ld} should be configured to expect as a
394 default input format the most usual format on each machine.
395 @var{input-format} is a text string, the name of a particular format
396 supported by the BFD libraries. (You can list the available binary
397 formats with @samp{objdump -i}.)
400 You may want to use this option if you are linking files with an unusual
401 binary format. You can also use @samp{-b} to switch formats explicitly (when
402 linking object files of different formats), by including
403 @samp{-b @var{input-format}} before each group of object files in a
406 The default format is taken from the environment variable
411 You can also define the input format from a script, using the command
414 see @ref{Format Commands}.
418 @kindex -c @var{MRI-cmdfile}
419 @kindex --mri-script=@var{MRI-cmdfile}
420 @cindex compatibility, MRI
421 @item -c @var{MRI-commandfile}
422 @itemx --mri-script=@var{MRI-commandfile}
423 For compatibility with linkers produced by MRI, @command{ld} accepts script
424 files written in an alternate, restricted command language, described in
426 @ref{MRI,,MRI Compatible Script Files}.
429 the MRI Compatible Script Files section of GNU ld documentation.
431 Introduce MRI script files with
432 the option @samp{-c}; use the @samp{-T} option to run linker
433 scripts written in the general-purpose @command{ld} scripting language.
434 If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
435 specified by any @samp{-L} options.
437 @cindex common allocation
444 These three options are equivalent; multiple forms are supported for
445 compatibility with other linkers. They assign space to common symbols
446 even if a relocatable output file is specified (with @samp{-r}). The
447 script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
448 @xref{Miscellaneous Commands}.
450 @cindex entry point, from command line
451 @kindex -e @var{entry}
452 @kindex --entry=@var{entry}
454 @itemx --entry=@var{entry}
455 Use @var{entry} as the explicit symbol for beginning execution of your
456 program, rather than the default entry point. If there is no symbol
457 named @var{entry}, the linker will try to parse @var{entry} as a number,
458 and use that as the entry address (the number will be interpreted in
459 base 10; you may use a leading @samp{0x} for base 16, or a leading
460 @samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
461 and other ways of specifying the entry point.
463 @kindex --exclude-libs
464 @item --exclude-libs @var{lib},@var{lib},...
465 Specifies a list of archive libraries from which symbols should not be automatically
466 exported. The library names may be delimited by commas or colons. Specifying
467 @code{--exclude-libs ALL} excludes symbols in all archive libraries from
468 automatic export. This option is available only for the i386 PE targeted
469 port of the linker and for ELF targeted ports. For i386 PE, symbols
470 explicitly listed in a .def file are still exported, regardless of this
471 option. For ELF targeted ports, symbols affected by this option will
472 be treated as hidden.
474 @cindex dynamic symbol table
476 @kindex --export-dynamic
478 @itemx --export-dynamic
479 When creating a dynamically linked executable, add all symbols to the
480 dynamic symbol table. The dynamic symbol table is the set of symbols
481 which are visible from dynamic objects at run time.
483 If you do not use this option, the dynamic symbol table will normally
484 contain only those symbols which are referenced by some dynamic object
485 mentioned in the link.
487 If you use @code{dlopen} to load a dynamic object which needs to refer
488 back to the symbols defined by the program, rather than some other
489 dynamic object, then you will probably need to use this option when
490 linking the program itself.
492 You can also use the version script to control what symbols should
493 be added to the dynamic symbol table if the output format supports it.
494 See the description of @samp{--version-script} in @ref{VERSION}.
496 @ifclear SingleFormat
497 @cindex big-endian objects
501 Link big-endian objects. This affects the default output format.
503 @cindex little-endian objects
506 Link little-endian objects. This affects the default output format.
512 @itemx --auxiliary @var{name}
513 When creating an ELF shared object, set the internal DT_AUXILIARY field
514 to the specified name. This tells the dynamic linker that the symbol
515 table of the shared object should be used as an auxiliary filter on the
516 symbol table of the shared object @var{name}.
518 If you later link a program against this filter object, then, when you
519 run the program, the dynamic linker will see the DT_AUXILIARY field. If
520 the dynamic linker resolves any symbols from the filter object, it will
521 first check whether there is a definition in the shared object
522 @var{name}. If there is one, it will be used instead of the definition
523 in the filter object. The shared object @var{name} need not exist.
524 Thus the shared object @var{name} may be used to provide an alternative
525 implementation of certain functions, perhaps for debugging or for
526 machine specific performance.
528 This option may be specified more than once. The DT_AUXILIARY entries
529 will be created in the order in which they appear on the command line.
534 @itemx --filter @var{name}
535 When creating an ELF shared object, set the internal DT_FILTER field to
536 the specified name. This tells the dynamic linker that the symbol table
537 of the shared object which is being created should be used as a filter
538 on the symbol table of the shared object @var{name}.
540 If you later link a program against this filter object, then, when you
541 run the program, the dynamic linker will see the DT_FILTER field. The
542 dynamic linker will resolve symbols according to the symbol table of the
543 filter object as usual, but it will actually link to the definitions
544 found in the shared object @var{name}. Thus the filter object can be
545 used to select a subset of the symbols provided by the object
548 Some older linkers used the @option{-F} option throughout a compilation
549 toolchain for specifying object-file format for both input and output
551 @ifclear SingleFormat
552 The @sc{gnu} linker uses other mechanisms for this purpose: the
553 @option{-b}, @option{--format}, @option{--oformat} options, the
554 @code{TARGET} command in linker scripts, and the @code{GNUTARGET}
555 environment variable.
557 The @sc{gnu} linker will ignore the @option{-F} option when not
558 creating an ELF shared object.
560 @cindex finalization function
562 @item -fini @var{name}
563 When creating an ELF executable or shared object, call NAME when the
564 executable or shared object is unloaded, by setting DT_FINI to the
565 address of the function. By default, the linker uses @code{_fini} as
566 the function to call.
570 Ignored. Provided for compatibility with other tools.
576 @itemx --gpsize=@var{value}
577 Set the maximum size of objects to be optimized using the GP register to
578 @var{size}. This is only meaningful for object file formats such as
579 MIPS ECOFF which supports putting large and small objects into different
580 sections. This is ignored for other object file formats.
582 @cindex runtime library name
584 @kindex -soname=@var{name}
586 @itemx -soname=@var{name}
587 When creating an ELF shared object, set the internal DT_SONAME field to
588 the specified name. When an executable is linked with a shared object
589 which has a DT_SONAME field, then when the executable is run the dynamic
590 linker will attempt to load the shared object specified by the DT_SONAME
591 field rather than the using the file name given to the linker.
594 @cindex incremental link
596 Perform an incremental link (same as option @samp{-r}).
598 @cindex initialization function
600 @item -init @var{name}
601 When creating an ELF executable or shared object, call NAME when the
602 executable or shared object is loaded, by setting DT_INIT to the address
603 of the function. By default, the linker uses @code{_init} as the
606 @cindex archive files, from cmd line
607 @kindex -l@var{archive}
608 @kindex --library=@var{archive}
609 @item -l@var{archive}
610 @itemx --library=@var{archive}
611 Add archive file @var{archive} to the list of files to link. This
612 option may be used any number of times. @command{ld} will search its
613 path-list for occurrences of @code{lib@var{archive}.a} for every
614 @var{archive} specified.
616 On systems which support shared libraries, @command{ld} may also search for
617 libraries with extensions other than @code{.a}. Specifically, on ELF
618 and SunOS systems, @command{ld} will search a directory for a library with
619 an extension of @code{.so} before searching for one with an extension of
620 @code{.a}. By convention, a @code{.so} extension indicates a shared
623 The linker will search an archive only once, at the location where it is
624 specified on the command line. If the archive defines a symbol which
625 was undefined in some object which appeared before the archive on the
626 command line, the linker will include the appropriate file(s) from the
627 archive. However, an undefined symbol in an object appearing later on
628 the command line will not cause the linker to search the archive again.
630 See the @option{-(} option for a way to force the linker to search
631 archives multiple times.
633 You may list the same archive multiple times on the command line.
636 This type of archive searching is standard for Unix linkers. However,
637 if you are using @command{ld} on AIX, note that it is different from the
638 behaviour of the AIX linker.
641 @cindex search directory, from cmd line
643 @kindex --library-path=@var{dir}
644 @item -L@var{searchdir}
645 @itemx --library-path=@var{searchdir}
646 Add path @var{searchdir} to the list of paths that @command{ld} will search
647 for archive libraries and @command{ld} control scripts. You may use this
648 option any number of times. The directories are searched in the order
649 in which they are specified on the command line. Directories specified
650 on the command line are searched before the default directories. All
651 @option{-L} options apply to all @option{-l} options, regardless of the
652 order in which the options appear.
654 If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
655 by the @dfn{sysroot prefix}, a path specified when the linker is configured.
658 The default set of paths searched (without being specified with
659 @samp{-L}) depends on which emulation mode @command{ld} is using, and in
660 some cases also on how it was configured. @xref{Environment}.
663 The paths can also be specified in a link script with the
664 @code{SEARCH_DIR} command. Directories specified this way are searched
665 at the point in which the linker script appears in the command line.
668 @kindex -m @var{emulation}
669 @item -m@var{emulation}
670 Emulate the @var{emulation} linker. You can list the available
671 emulations with the @samp{--verbose} or @samp{-V} options.
673 If the @samp{-m} option is not used, the emulation is taken from the
674 @code{LDEMULATION} environment variable, if that is defined.
676 Otherwise, the default emulation depends upon how the linker was
684 Print a link map to the standard output. A link map provides
685 information about the link, including the following:
689 Where object files are mapped into memory.
691 How common symbols are allocated.
693 All archive members included in the link, with a mention of the symbol
694 which caused the archive member to be brought in.
696 The values assigned to symbols.
698 Note - symbols whose values are computed by an expression which
699 involves a reference to a previous value of the same symbol may not
700 have correct result displayed in the link map. This is because the
701 linker discards intermediate results and only retains the final value
702 of an expression. Under such circumstances the linker will display
703 the final value enclosed by square brackets. Thus for example a
704 linker script containing:
712 will produce the following output in the link map if the @option{-M}
717 [0x0000000c] foo = (foo * 0x4)
718 [0x0000000c] foo = (foo + 0x8)
721 See @ref{Expressions} for more information about expressions in linker
726 @cindex read-only text
731 Turn off page alignment of sections, and mark the output as
732 @code{NMAGIC} if possible.
736 @cindex read/write from cmd line
740 Set the text and data sections to be readable and writable. Also, do
741 not page-align the data segment, and disable linking against shared
742 libraries. If the output format supports Unix style magic numbers,
743 mark the output as @code{OMAGIC}. Note: Although a writable text section
744 is allowed for PE-COFF targets, it does not conform to the format
745 specification published by Microsoft.
750 This option negates most of the effects of the @option{-N} option. It
751 sets the text section to be read-only, and forces the data segment to
752 be page-aligned. Note - this option does not enable linking against
753 shared libraries. Use @option{-Bdynamic} for this.
755 @kindex -o @var{output}
756 @kindex --output=@var{output}
757 @cindex naming the output file
758 @item -o @var{output}
759 @itemx --output=@var{output}
760 Use @var{output} as the name for the program produced by @command{ld}; if this
761 option is not specified, the name @file{a.out} is used by default. The
762 script command @code{OUTPUT} can also specify the output file name.
764 @kindex -O @var{level}
765 @cindex generating optimized output
767 If @var{level} is a numeric values greater than zero @command{ld} optimizes
768 the output. This might take significantly longer and therefore probably
769 should only be enabled for the final binary.
772 @kindex --emit-relocs
773 @cindex retain relocations in final executable
776 Leave relocation sections and contents in fully linked exececutables.
777 Post link analysis and optimization tools may need this information in
778 order to perform correct modifications of executables. This results
779 in larger executables.
781 This option is currently only supported on ELF platforms.
783 @kindex --force-dynamic
784 @cindex forcing the creation of dynamic sections
785 @item --force-dynamic
786 Force the output file to have dynamic sections. This option is specific
790 @cindex relocatable output
792 @kindex --relocatable
795 Generate relocatable output---i.e., generate an output file that can in
796 turn serve as input to @command{ld}. This is often called @dfn{partial
797 linking}. As a side effect, in environments that support standard Unix
798 magic numbers, this option also sets the output file's magic number to
800 @c ; see @option{-N}.
801 If this option is not specified, an absolute file is produced. When
802 linking C++ programs, this option @emph{will not} resolve references to
803 constructors; to do that, use @samp{-Ur}.
805 When an input file does not have the same format as the output file,
806 partial linking is only supported if that input file does not contain any
807 relocations. Different output formats can have further restrictions; for
808 example some @code{a.out}-based formats do not support partial linking
809 with input files in other formats at all.
811 This option does the same thing as @samp{-i}.
813 @kindex -R @var{file}
814 @kindex --just-symbols=@var{file}
815 @cindex symbol-only input
816 @item -R @var{filename}
817 @itemx --just-symbols=@var{filename}
818 Read symbol names and their addresses from @var{filename}, but do not
819 relocate it or include it in the output. This allows your output file
820 to refer symbolically to absolute locations of memory defined in other
821 programs. You may use this option more than once.
823 For compatibility with other ELF linkers, if the @option{-R} option is
824 followed by a directory name, rather than a file name, it is treated as
825 the @option{-rpath} option.
829 @cindex strip all symbols
832 Omit all symbol information from the output file.
835 @kindex --strip-debug
836 @cindex strip debugger symbols
839 Omit debugger symbol information (but not all symbols) from the output file.
843 @cindex input files, displaying
846 Print the names of the input files as @command{ld} processes them.
848 @kindex -T @var{script}
849 @kindex --script=@var{script}
851 @item -T @var{scriptfile}
852 @itemx --script=@var{scriptfile}
853 Use @var{scriptfile} as the linker script. This script replaces
854 @command{ld}'s default linker script (rather than adding to it), so
855 @var{commandfile} must specify everything necessary to describe the
856 output file. @xref{Scripts}. If @var{scriptfile} does not exist in
857 the current directory, @code{ld} looks for it in the directories
858 specified by any preceding @samp{-L} options. Multiple @samp{-T}
861 @kindex -u @var{symbol}
862 @kindex --undefined=@var{symbol}
863 @cindex undefined symbol
864 @item -u @var{symbol}
865 @itemx --undefined=@var{symbol}
866 Force @var{symbol} to be entered in the output file as an undefined
867 symbol. Doing this may, for example, trigger linking of additional
868 modules from standard libraries. @samp{-u} may be repeated with
869 different option arguments to enter additional undefined symbols. This
870 option is equivalent to the @code{EXTERN} linker script command.
875 For anything other than C++ programs, this option is equivalent to
876 @samp{-r}: it generates relocatable output---i.e., an output file that can in
877 turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur}
878 @emph{does} resolve references to constructors, unlike @samp{-r}.
879 It does not work to use @samp{-Ur} on files that were themselves linked
880 with @samp{-Ur}; once the constructor table has been built, it cannot
881 be added to. Use @samp{-Ur} only for the last partial link, and
882 @samp{-r} for the others.
884 @kindex --unique[=@var{SECTION}]
885 @item --unique[=@var{SECTION}]
886 Creates a separate output section for every input section matching
887 @var{SECTION}, or if the optional wildcard @var{SECTION} argument is
888 missing, for every orphan input section. An orphan section is one not
889 specifically mentioned in a linker script. You may use this option
890 multiple times on the command line; It prevents the normal merging of
891 input sections with the same name, overriding output section assignments
901 Display the version number for @command{ld}. The @option{-V} option also
902 lists the supported emulations.
905 @kindex --discard-all
906 @cindex deleting local symbols
909 Delete all local symbols.
912 @kindex --discard-locals
913 @cindex local symbols, deleting
914 @cindex L, deleting symbols beginning
916 @itemx --discard-locals
917 Delete all temporary local symbols. For most targets, this is all local
918 symbols whose names begin with @samp{L}.
920 @kindex -y @var{symbol}
921 @kindex --trace-symbol=@var{symbol}
922 @cindex symbol tracing
923 @item -y @var{symbol}
924 @itemx --trace-symbol=@var{symbol}
925 Print the name of each linked file in which @var{symbol} appears. This
926 option may be given any number of times. On many systems it is necessary
927 to prepend an underscore.
929 This option is useful when you have an undefined symbol in your link but
930 don't know where the reference is coming from.
932 @kindex -Y @var{path}
934 Add @var{path} to the default library search path. This option exists
935 for Solaris compatibility.
937 @kindex -z @var{keyword}
938 @item -z @var{keyword}
939 The recognized keywords are:
943 Combines multiple reloc sections and sorts them to make dynamic symbol
944 lookup caching possible.
947 Disallows undefined symbols in object files. Undefined symbols in
948 shared libraries are still allowed.
951 Marks the object as requiring executable stack.
954 This option is only meaningful when building a shared object.
955 It marks the object so that its runtime initialization will occur
956 before the runtime initialization of any other objects brought into
957 the process at the same time. Similarly the runtime finalization of
958 the object will occur after the runtime finalization of any other
962 Marks the object that its symbol table interposes before all symbols
963 but the primary executable.
966 Marks the object that its filters be processed immediately at
970 Allows multiple definitions.
973 Disables multiple reloc sections combining.
976 Disables production of copy relocs.
979 Marks the object that the search for dependencies of this object will
980 ignore any default library search paths.
983 Marks the object shouldn't be unloaded at runtime.
986 Marks the object not available to @code{dlopen}.
989 Marks the object can not be dumped by @code{dldump}.
992 Marks the object as not requiring executable stack.
995 Don't create an ELF @code{PT_GNU_RELRO} segment header in the object.
998 When generating an executable or shared library, mark it to tell the
999 dynamic linker to resolve all symbols when the program is started, or
1000 when the shared library is linked to using dlopen, instead of
1001 deferring function call resolution to the point when the function is
1005 Marks the object may contain $ORIGIN.
1008 Create an ELF @code{PT_GNU_RELRO} segment header in the object.
1010 @item max-page-size=@var{value}
1011 Set the emulation maximum page size to @var{value}.
1013 @item common-page-size=@var{value}
1014 Set the emulation common page size to @var{value}.
1018 Other keywords are ignored for Solaris compatibility.
1021 @cindex groups of archives
1022 @item -( @var{archives} -)
1023 @itemx --start-group @var{archives} --end-group
1024 The @var{archives} should be a list of archive files. They may be
1025 either explicit file names, or @samp{-l} options.
1027 The specified archives are searched repeatedly until no new undefined
1028 references are created. Normally, an archive is searched only once in
1029 the order that it is specified on the command line. If a symbol in that
1030 archive is needed to resolve an undefined symbol referred to by an
1031 object in an archive that appears later on the command line, the linker
1032 would not be able to resolve that reference. By grouping the archives,
1033 they all be searched repeatedly until all possible references are
1036 Using this option has a significant performance cost. It is best to use
1037 it only when there are unavoidable circular references between two or
1040 @kindex --accept-unknown-input-arch
1041 @kindex --no-accept-unknown-input-arch
1042 @item --accept-unknown-input-arch
1043 @itemx --no-accept-unknown-input-arch
1044 Tells the linker to accept input files whose architecture cannot be
1045 recognised. The assumption is that the user knows what they are doing
1046 and deliberately wants to link in these unknown input files. This was
1047 the default behaviour of the linker, before release 2.14. The default
1048 behaviour from release 2.14 onwards is to reject such input files, and
1049 so the @samp{--accept-unknown-input-arch} option has been added to
1050 restore the old behaviour.
1053 @kindex --no-as-needed
1055 @itemx --no-as-needed
1056 This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
1057 on the command line after the @option{--as-needed} option. Normally,
1058 the linker will add a DT_NEEDED tag for each dynamic library mentioned
1059 on the command line, regardless of whether the library is actually
1060 needed. @option{--as-needed} causes DT_NEEDED tags to only be emitted
1061 for libraries that satisfy some symbol reference from regular objects
1062 which is undefined at the point that the library was linked.
1063 @option{--no-as-needed} restores the default behaviour.
1065 @kindex --add-needed
1066 @kindex --no-add-needed
1068 @itemx --no-add-needed
1069 This option affects the treatment of dynamic libraries from ELF
1070 DT_NEEDED tags in dynamic libraries mentioned on the command line after
1071 the @option{--no-add-needed} option. Normally, the linker will add
1072 a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
1073 @option{--no-add-needed} causes DT_NEEDED tags will never be emitted
1074 for those libraries from DT_NEEDED tags. @option{--add-needed} restores
1075 the default behaviour.
1077 @kindex -assert @var{keyword}
1078 @item -assert @var{keyword}
1079 This option is ignored for SunOS compatibility.
1083 @kindex -call_shared
1087 Link against dynamic libraries. This is only meaningful on platforms
1088 for which shared libraries are supported. This option is normally the
1089 default on such platforms. The different variants of this option are
1090 for compatibility with various systems. You may use this option
1091 multiple times on the command line: it affects library searching for
1092 @option{-l} options which follow it.
1096 Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
1097 section. This causes the runtime linker to handle lookups in this
1098 object and its dependencies to be performed only inside the group.
1099 @option{--unresolved-symbols=report-all} is implied. This option is
1100 only meaningful on ELF platforms which support shared libraries.
1110 Do not link against shared libraries. This is only meaningful on
1111 platforms for which shared libraries are supported. The different
1112 variants of this option are for compatibility with various systems. You
1113 may use this option multiple times on the command line: it affects
1114 library searching for @option{-l} options which follow it. This
1115 option also implies @option{--unresolved-symbols=report-all}. This
1116 option can be used with @option{-shared}. Doing so means that a
1117 shared library is being created but that all of the library's external
1118 references must be resolved by pulling in entries from static
1123 When creating a shared library, bind references to global symbols to the
1124 definition within the shared library, if any. Normally, it is possible
1125 for a program linked against a shared library to override the definition
1126 within the shared library. This option is only meaningful on ELF
1127 platforms which support shared libraries.
1129 @kindex --check-sections
1130 @kindex --no-check-sections
1131 @item --check-sections
1132 @itemx --no-check-sections
1133 Asks the linker @emph{not} to check section addresses after they have
1134 been assigned to see if there are any overlaps. Normally the linker will
1135 perform this check, and if it finds any overlaps it will produce
1136 suitable error messages. The linker does know about, and does make
1137 allowances for sections in overlays. The default behaviour can be
1138 restored by using the command line switch @option{--check-sections}.
1140 @cindex cross reference table
1143 Output a cross reference table. If a linker map file is being
1144 generated, the cross reference table is printed to the map file.
1145 Otherwise, it is printed on the standard output.
1147 The format of the table is intentionally simple, so that it may be
1148 easily processed by a script if necessary. The symbols are printed out,
1149 sorted by name. For each symbol, a list of file names is given. If the
1150 symbol is defined, the first file listed is the location of the
1151 definition. The remaining files contain references to the symbol.
1153 @cindex common allocation
1154 @kindex --no-define-common
1155 @item --no-define-common
1156 This option inhibits the assignment of addresses to common symbols.
1157 The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
1158 @xref{Miscellaneous Commands}.
1160 The @samp{--no-define-common} option allows decoupling
1161 the decision to assign addresses to Common symbols from the choice
1162 of the output file type; otherwise a non-Relocatable output type
1163 forces assigning addresses to Common symbols.
1164 Using @samp{--no-define-common} allows Common symbols that are referenced
1165 from a shared library to be assigned addresses only in the main program.
1166 This eliminates the unused duplicate space in the shared library,
1167 and also prevents any possible confusion over resolving to the wrong
1168 duplicate when there are many dynamic modules with specialized search
1169 paths for runtime symbol resolution.
1171 @cindex symbols, from command line
1172 @kindex --defsym @var{symbol}=@var{exp}
1173 @item --defsym @var{symbol}=@var{expression}
1174 Create a global symbol in the output file, containing the absolute
1175 address given by @var{expression}. You may use this option as many
1176 times as necessary to define multiple symbols in the command line. A
1177 limited form of arithmetic is supported for the @var{expression} in this
1178 context: you may give a hexadecimal constant or the name of an existing
1179 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
1180 constants or symbols. If you need more elaborate expressions, consider
1181 using the linker command language from a script (@pxref{Assignments,,
1182 Assignment: Symbol Definitions}). @emph{Note:} there should be no white
1183 space between @var{symbol}, the equals sign (``@key{=}''), and
1186 @cindex demangling, from command line
1187 @kindex --demangle[=@var{style}]
1188 @kindex --no-demangle
1189 @item --demangle[=@var{style}]
1190 @itemx --no-demangle
1191 These options control whether to demangle symbol names in error messages
1192 and other output. When the linker is told to demangle, it tries to
1193 present symbol names in a readable fashion: it strips leading
1194 underscores if they are used by the object file format, and converts C++
1195 mangled symbol names into user readable names. Different compilers have
1196 different mangling styles. The optional demangling style argument can be used
1197 to choose an appropriate demangling style for your compiler. The linker will
1198 demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
1199 is set. These options may be used to override the default.
1201 @cindex dynamic linker, from command line
1202 @kindex -I@var{file}
1203 @kindex --dynamic-linker @var{file}
1204 @item --dynamic-linker @var{file}
1205 Set the name of the dynamic linker. This is only meaningful when
1206 generating dynamically linked ELF executables. The default dynamic
1207 linker is normally correct; don't use this unless you know what you are
1211 @kindex --fatal-warnings
1212 @item --fatal-warnings
1213 Treat all warnings as errors.
1215 @kindex --force-exe-suffix
1216 @item --force-exe-suffix
1217 Make sure that an output file has a .exe suffix.
1219 If a successfully built fully linked output file does not have a
1220 @code{.exe} or @code{.dll} suffix, this option forces the linker to copy
1221 the output file to one of the same name with a @code{.exe} suffix. This
1222 option is useful when using unmodified Unix makefiles on a Microsoft
1223 Windows host, since some versions of Windows won't run an image unless
1224 it ends in a @code{.exe} suffix.
1226 @kindex --gc-sections
1227 @kindex --no-gc-sections
1228 @cindex garbage collection
1229 @item --no-gc-sections
1230 @itemx --gc-sections
1231 Enable garbage collection of unused input sections. It is ignored on
1232 targets that do not support this option. This option is not compatible
1233 with @samp{-r}. The default behaviour (of not performing this garbage
1234 collection) can be restored by specifying @samp{--no-gc-sections} on
1241 Print a summary of the command-line options on the standard output and exit.
1243 @kindex --target-help
1245 Print a summary of all target specific options on the standard output and exit.
1248 @item -Map @var{mapfile}
1249 Print a link map to the file @var{mapfile}. See the description of the
1250 @option{-M} option, above.
1252 @cindex memory usage
1253 @kindex --no-keep-memory
1254 @item --no-keep-memory
1255 @command{ld} normally optimizes for speed over memory usage by caching the
1256 symbol tables of input files in memory. This option tells @command{ld} to
1257 instead optimize for memory usage, by rereading the symbol tables as
1258 necessary. This may be required if @command{ld} runs out of memory space
1259 while linking a large executable.
1261 @kindex --no-undefined
1263 @item --no-undefined
1265 Report unresolved symbol references from regular object files. This
1266 is done even if the linker is creating a non-symbolic shared library.
1267 The switch @option{--[no-]allow-shlib-undefined} controls the
1268 behaviour for reporting unresolved references found in shared
1269 libraries being linked in.
1271 @kindex --allow-multiple-definition
1273 @item --allow-multiple-definition
1275 Normally when a symbol is defined multiple times, the linker will
1276 report a fatal error. These options allow multiple definitions and the
1277 first definition will be used.
1279 @kindex --allow-shlib-undefined
1280 @kindex --no-allow-shlib-undefined
1281 @item --allow-shlib-undefined
1282 @itemx --no-allow-shlib-undefined
1283 Allows (the default) or disallows undefined symbols in shared libraries.
1284 This switch is similar to @option{--no-undefined} except that it
1285 determines the behaviour when the undefined symbols are in a
1286 shared library rather than a regular object file. It does not affect
1287 how undefined symbols in regular object files are handled.
1289 The reason that @option{--allow-shlib-undefined} is the default is that
1290 the shared library being specified at link time may not be the same as
1291 the one that is available at load time, so the symbols might actually be
1292 resolvable at load time. Plus there are some systems, (eg BeOS) where
1293 undefined symbols in shared libraries is normal. (The kernel patches
1294 them at load time to select which function is most appropriate
1295 for the current architecture. This is used for example to dynamically
1296 select an appropriate memset function). Apparently it is also normal
1297 for HPPA shared libraries to have undefined symbols.
1299 @kindex --no-undefined-version
1300 @item --no-undefined-version
1301 Normally when a symbol has an undefined version, the linker will ignore
1302 it. This option disallows symbols with undefined version and a fatal error
1303 will be issued instead.
1305 @kindex --default-symver
1306 @item --default-symver
1307 Create and use a default symbol version (the soname) for unversioned
1310 @kindex --default-imported-symver
1311 @item --default-imported-symver
1312 Create and use a default symbol version (the soname) for unversioned
1315 @kindex --no-warn-mismatch
1316 @item --no-warn-mismatch
1317 Normally @command{ld} will give an error if you try to link together input
1318 files that are mismatched for some reason, perhaps because they have
1319 been compiled for different processors or for different endiannesses.
1320 This option tells @command{ld} that it should silently permit such possible
1321 errors. This option should only be used with care, in cases when you
1322 have taken some special action that ensures that the linker errors are
1325 @kindex --no-whole-archive
1326 @item --no-whole-archive
1327 Turn off the effect of the @option{--whole-archive} option for subsequent
1330 @cindex output file after errors
1331 @kindex --noinhibit-exec
1332 @item --noinhibit-exec
1333 Retain the executable output file whenever it is still usable.
1334 Normally, the linker will not produce an output file if it encounters
1335 errors during the link process; it exits without writing an output file
1336 when it issues any error whatsoever.
1340 Only search library directories explicitly specified on the
1341 command line. Library directories specified in linker scripts
1342 (including linker scripts specified on the command line) are ignored.
1344 @ifclear SingleFormat
1346 @item --oformat @var{output-format}
1347 @command{ld} may be configured to support more than one kind of object
1348 file. If your @command{ld} is configured this way, you can use the
1349 @samp{--oformat} option to specify the binary format for the output
1350 object file. Even when @command{ld} is configured to support alternative
1351 object formats, you don't usually need to specify this, as @command{ld}
1352 should be configured to produce as a default output format the most
1353 usual format on each machine. @var{output-format} is a text string, the
1354 name of a particular format supported by the BFD libraries. (You can
1355 list the available binary formats with @samp{objdump -i}.) The script
1356 command @code{OUTPUT_FORMAT} can also specify the output format, but
1357 this option overrides it. @xref{BFD}.
1361 @kindex --pic-executable
1363 @itemx --pic-executable
1364 @cindex position independent executables
1365 Create a position independent executable. This is currently only supported on
1366 ELF platforms. Position independent executables are similar to shared
1367 libraries in that they are relocated by the dynamic linker to the virtual
1368 address the OS chooses for them (which can vary between invocations). Like
1369 normal dynamically linked executables they can be executed and symbols
1370 defined in the executable cannot be overridden by shared libraries.
1374 This option is ignored for Linux compatibility.
1378 This option is ignored for SVR4 compatibility.
1381 @cindex synthesizing linker
1382 @cindex relaxing addressing modes
1384 An option with machine dependent effects.
1386 This option is only supported on a few targets.
1389 @xref{H8/300,,@command{ld} and the H8/300}.
1392 @xref{i960,, @command{ld} and the Intel 960 family}.
1395 @xref{Xtensa,, @command{ld} and Xtensa Processors}.
1398 @xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
1401 @xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
1404 On some platforms, the @samp{--relax} option performs global
1405 optimizations that become possible when the linker resolves addressing
1406 in the program, such as relaxing address modes and synthesizing new
1407 instructions in the output object file.
1409 On some platforms these link time global optimizations may make symbolic
1410 debugging of the resulting executable impossible.
1413 the case for the Matsushita MN10200 and MN10300 family of processors.
1417 On platforms where this is not supported, @samp{--relax} is accepted,
1421 @cindex retaining specified symbols
1422 @cindex stripping all but some symbols
1423 @cindex symbols, retaining selectively
1424 @item --retain-symbols-file @var{filename}
1425 Retain @emph{only} the symbols listed in the file @var{filename},
1426 discarding all others. @var{filename} is simply a flat file, with one
1427 symbol name per line. This option is especially useful in environments
1431 where a large global symbol table is accumulated gradually, to conserve
1434 @samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
1435 or symbols needed for relocations.
1437 You may only specify @samp{--retain-symbols-file} once in the command
1438 line. It overrides @samp{-s} and @samp{-S}.
1441 @item -rpath @var{dir}
1442 @cindex runtime library search path
1444 Add a directory to the runtime library search path. This is used when
1445 linking an ELF executable with shared objects. All @option{-rpath}
1446 arguments are concatenated and passed to the runtime linker, which uses
1447 them to locate shared objects at runtime. The @option{-rpath} option is
1448 also used when locating shared objects which are needed by shared
1449 objects explicitly included in the link; see the description of the
1450 @option{-rpath-link} option. If @option{-rpath} is not used when linking an
1451 ELF executable, the contents of the environment variable
1452 @code{LD_RUN_PATH} will be used if it is defined.
1454 The @option{-rpath} option may also be used on SunOS. By default, on
1455 SunOS, the linker will form a runtime search patch out of all the
1456 @option{-L} options it is given. If a @option{-rpath} option is used, the
1457 runtime search path will be formed exclusively using the @option{-rpath}
1458 options, ignoring the @option{-L} options. This can be useful when using
1459 gcc, which adds many @option{-L} options which may be on NFS mounted
1462 For compatibility with other ELF linkers, if the @option{-R} option is
1463 followed by a directory name, rather than a file name, it is treated as
1464 the @option{-rpath} option.
1468 @cindex link-time runtime library search path
1470 @item -rpath-link @var{DIR}
1471 When using ELF or SunOS, one shared library may require another. This
1472 happens when an @code{ld -shared} link includes a shared library as one
1475 When the linker encounters such a dependency when doing a non-shared,
1476 non-relocatable link, it will automatically try to locate the required
1477 shared library and include it in the link, if it is not included
1478 explicitly. In such a case, the @option{-rpath-link} option
1479 specifies the first set of directories to search. The
1480 @option{-rpath-link} option may specify a sequence of directory names
1481 either by specifying a list of names separated by colons, or by
1482 appearing multiple times.
1484 This option should be used with caution as it overrides the search path
1485 that may have been hard compiled into a shared library. In such a case it
1486 is possible to use unintentionally a different search path than the
1487 runtime linker would do.
1489 The linker uses the following search paths to locate required shared
1493 Any directories specified by @option{-rpath-link} options.
1495 Any directories specified by @option{-rpath} options. The difference
1496 between @option{-rpath} and @option{-rpath-link} is that directories
1497 specified by @option{-rpath} options are included in the executable and
1498 used at runtime, whereas the @option{-rpath-link} option is only effective
1499 at link time. It is for the native linker only.
1501 On an ELF system, if the @option{-rpath} and @code{rpath-link} options
1502 were not used, search the contents of the environment variable
1503 @code{LD_RUN_PATH}. It is for the native linker only.
1505 On SunOS, if the @option{-rpath} option was not used, search any
1506 directories specified using @option{-L} options.
1508 For a native linker, the contents of the environment variable
1509 @code{LD_LIBRARY_PATH}.
1511 For a native ELF linker, the directories in @code{DT_RUNPATH} or
1512 @code{DT_RPATH} of a shared library are searched for shared
1513 libraries needed by it. The @code{DT_RPATH} entries are ignored if
1514 @code{DT_RUNPATH} entries exist.
1516 The default directories, normally @file{/lib} and @file{/usr/lib}.
1518 For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
1519 exists, the list of directories found in that file.
1522 If the required shared library is not found, the linker will issue a
1523 warning and continue with the link.
1530 @cindex shared libraries
1531 Create a shared library. This is currently only supported on ELF, XCOFF
1532 and SunOS platforms. On SunOS, the linker will automatically create a
1533 shared library if the @option{-e} option is not used and there are
1534 undefined symbols in the link.
1537 @kindex --sort-common
1538 This option tells @command{ld} to sort the common symbols by size when it
1539 places them in the appropriate output sections. First come all the one
1540 byte symbols, then all the two byte, then all the four byte, and then
1541 everything else. This is to prevent gaps between symbols due to
1542 alignment constraints.
1544 @kindex --sort-section name
1545 @item --sort-section name
1546 This option will apply @code{SORT_BY_NAME} to all wildcard section
1547 patterns in the linker script.
1549 @kindex --sort-section alignment
1550 @item --sort-section alignment
1551 This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
1552 patterns in the linker script.
1554 @kindex --split-by-file
1555 @item --split-by-file [@var{size}]
1556 Similar to @option{--split-by-reloc} but creates a new output section for
1557 each input file when @var{size} is reached. @var{size} defaults to a
1558 size of 1 if not given.
1560 @kindex --split-by-reloc
1561 @item --split-by-reloc [@var{count}]
1562 Tries to creates extra sections in the output file so that no single
1563 output section in the file contains more than @var{count} relocations.
1564 This is useful when generating huge relocatable files for downloading into
1565 certain real time kernels with the COFF object file format; since COFF
1566 cannot represent more than 65535 relocations in a single section. Note
1567 that this will fail to work with object file formats which do not
1568 support arbitrary sections. The linker will not split up individual
1569 input sections for redistribution, so if a single input section contains
1570 more than @var{count} relocations one output section will contain that
1571 many relocations. @var{count} defaults to a value of 32768.
1575 Compute and display statistics about the operation of the linker, such
1576 as execution time and memory usage.
1579 @item --sysroot=@var{directory}
1580 Use @var{directory} as the location of the sysroot, overriding the
1581 configure-time default. This option is only supported by linkers
1582 that were configured using @option{--with-sysroot}.
1584 @kindex --traditional-format
1585 @cindex traditional format
1586 @item --traditional-format
1587 For some targets, the output of @command{ld} is different in some ways from
1588 the output of some existing linker. This switch requests @command{ld} to
1589 use the traditional format instead.
1592 For example, on SunOS, @command{ld} combines duplicate entries in the
1593 symbol string table. This can reduce the size of an output file with
1594 full debugging information by over 30 percent. Unfortunately, the SunOS
1595 @code{dbx} program can not read the resulting program (@code{gdb} has no
1596 trouble). The @samp{--traditional-format} switch tells @command{ld} to not
1597 combine duplicate entries.
1599 @kindex --section-start @var{sectionname}=@var{org}
1600 @item --section-start @var{sectionname}=@var{org}
1601 Locate a section in the output file at the absolute
1602 address given by @var{org}. You may use this option as many
1603 times as necessary to locate multiple sections in the command
1605 @var{org} must be a single hexadecimal integer;
1606 for compatibility with other linkers, you may omit the leading
1607 @samp{0x} usually associated with hexadecimal values. @emph{Note:} there
1608 should be no white space between @var{sectionname}, the equals
1609 sign (``@key{=}''), and @var{org}.
1611 @kindex -Tbss @var{org}
1612 @kindex -Tdata @var{org}
1613 @kindex -Ttext @var{org}
1614 @cindex segment origins, cmd line
1615 @item -Tbss @var{org}
1616 @itemx -Tdata @var{org}
1617 @itemx -Ttext @var{org}
1618 Same as --section-start, with @code{.bss}, @code{.data} or
1619 @code{.text} as the @var{sectionname}.
1621 @kindex --unresolved-symbols
1622 @item --unresolved-symbols=@var{method}
1623 Determine how to handle unresolved symbols. There are four possible
1624 values for @samp{method}:
1628 Do not report any unresolved symbols.
1631 Report all unresolved symbols. This is the default.
1633 @item ignore-in-object-files
1634 Report unresolved symbols that are contained in shared libraries, but
1635 ignore them if they come from regular object files.
1637 @item ignore-in-shared-libs
1638 Report unresolved symbols that come from regular object files, but
1639 ignore them if they come from shared libraries. This can be useful
1640 when creating a dynamic binary and it is known that all the shared
1641 libraries that it should be referencing are included on the linker's
1645 The behaviour for shared libraries on their own can also be controlled
1646 by the @option{--[no-]allow-shlib-undefined} option.
1648 Normally the linker will generate an error message for each reported
1649 unresolved symbol but the option @option{--warn-unresolved-symbols}
1650 can change this to a warning.
1656 Display the version number for @command{ld} and list the linker emulations
1657 supported. Display which input files can and cannot be opened. Display
1658 the linker script being used by the linker.
1660 @kindex --version-script=@var{version-scriptfile}
1661 @cindex version script, symbol versions
1662 @itemx --version-script=@var{version-scriptfile}
1663 Specify the name of a version script to the linker. This is typically
1664 used when creating shared libraries to specify additional information
1665 about the version hierarchy for the library being created. This option
1666 is only meaningful on ELF platforms which support shared libraries.
1669 @kindex --warn-common
1670 @cindex warnings, on combining symbols
1671 @cindex combining symbols, warnings on
1673 Warn when a common symbol is combined with another common symbol or with
1674 a symbol definition. Unix linkers allow this somewhat sloppy practise,
1675 but linkers on some other operating systems do not. This option allows
1676 you to find potential problems from combining global symbols.
1677 Unfortunately, some C libraries use this practise, so you may get some
1678 warnings about symbols in the libraries as well as in your programs.
1680 There are three kinds of global symbols, illustrated here by C examples:
1684 A definition, which goes in the initialized data section of the output
1688 An undefined reference, which does not allocate space.
1689 There must be either a definition or a common symbol for the
1693 A common symbol. If there are only (one or more) common symbols for a
1694 variable, it goes in the uninitialized data area of the output file.
1695 The linker merges multiple common symbols for the same variable into a
1696 single symbol. If they are of different sizes, it picks the largest
1697 size. The linker turns a common symbol into a declaration, if there is
1698 a definition of the same variable.
1701 The @samp{--warn-common} option can produce five kinds of warnings.
1702 Each warning consists of a pair of lines: the first describes the symbol
1703 just encountered, and the second describes the previous symbol
1704 encountered with the same name. One or both of the two symbols will be
1709 Turning a common symbol into a reference, because there is already a
1710 definition for the symbol.
1712 @var{file}(@var{section}): warning: common of `@var{symbol}'
1713 overridden by definition
1714 @var{file}(@var{section}): warning: defined here
1718 Turning a common symbol into a reference, because a later definition for
1719 the symbol is encountered. This is the same as the previous case,
1720 except that the symbols are encountered in a different order.
1722 @var{file}(@var{section}): warning: definition of `@var{symbol}'
1724 @var{file}(@var{section}): warning: common is here
1728 Merging a common symbol with a previous same-sized common symbol.
1730 @var{file}(@var{section}): warning: multiple common
1732 @var{file}(@var{section}): warning: previous common is here
1736 Merging a common symbol with a previous larger common symbol.
1738 @var{file}(@var{section}): warning: common of `@var{symbol}'
1739 overridden by larger common
1740 @var{file}(@var{section}): warning: larger common is here
1744 Merging a common symbol with a previous smaller common symbol. This is
1745 the same as the previous case, except that the symbols are
1746 encountered in a different order.
1748 @var{file}(@var{section}): warning: common of `@var{symbol}'
1749 overriding smaller common
1750 @var{file}(@var{section}): warning: smaller common is here
1754 @kindex --warn-constructors
1755 @item --warn-constructors
1756 Warn if any global constructors are used. This is only useful for a few
1757 object file formats. For formats like COFF or ELF, the linker can not
1758 detect the use of global constructors.
1760 @kindex --warn-multiple-gp
1761 @item --warn-multiple-gp
1762 Warn if multiple global pointer values are required in the output file.
1763 This is only meaningful for certain processors, such as the Alpha.
1764 Specifically, some processors put large-valued constants in a special
1765 section. A special register (the global pointer) points into the middle
1766 of this section, so that constants can be loaded efficiently via a
1767 base-register relative addressing mode. Since the offset in
1768 base-register relative mode is fixed and relatively small (e.g., 16
1769 bits), this limits the maximum size of the constant pool. Thus, in
1770 large programs, it is often necessary to use multiple global pointer
1771 values in order to be able to address all possible constants. This
1772 option causes a warning to be issued whenever this case occurs.
1775 @cindex warnings, on undefined symbols
1776 @cindex undefined symbols, warnings on
1778 Only warn once for each undefined symbol, rather than once per module
1781 @kindex --warn-section-align
1782 @cindex warnings, on section alignment
1783 @cindex section alignment, warnings on
1784 @item --warn-section-align
1785 Warn if the address of an output section is changed because of
1786 alignment. Typically, the alignment will be set by an input section.
1787 The address will only be changed if it not explicitly specified; that
1788 is, if the @code{SECTIONS} command does not specify a start address for
1789 the section (@pxref{SECTIONS}).
1791 @kindex --warn-shared-textrel
1792 @item --warn-shared-textrel
1793 Warn if the linker adds a DT_TEXTREL to a shared object.
1795 @kindex --warn-unresolved-symbols
1796 @item --warn-unresolved-symbols
1797 If the linker is going to report an unresolved symbol (see the option
1798 @option{--unresolved-symbols}) it will normally generate an error.
1799 This option makes it generate a warning instead.
1801 @kindex --error-unresolved-symbols
1802 @item --error-unresolved-symbols
1803 This restores the linker's default behaviour of generating errors when
1804 it is reporting unresolved symbols.
1806 @kindex --whole-archive
1807 @cindex including an entire archive
1808 @item --whole-archive
1809 For each archive mentioned on the command line after the
1810 @option{--whole-archive} option, include every object file in the archive
1811 in the link, rather than searching the archive for the required object
1812 files. This is normally used to turn an archive file into a shared
1813 library, forcing every object to be included in the resulting shared
1814 library. This option may be used more than once.
1816 Two notes when using this option from gcc: First, gcc doesn't know
1817 about this option, so you have to use @option{-Wl,-whole-archive}.
1818 Second, don't forget to use @option{-Wl,-no-whole-archive} after your
1819 list of archives, because gcc will add its own list of archives to
1820 your link and you may not want this flag to affect those as well.
1823 @item --wrap @var{symbol}
1824 Use a wrapper function for @var{symbol}. Any undefined reference to
1825 @var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
1826 undefined reference to @code{__real_@var{symbol}} will be resolved to
1829 This can be used to provide a wrapper for a system function. The
1830 wrapper function should be called @code{__wrap_@var{symbol}}. If it
1831 wishes to call the system function, it should call
1832 @code{__real_@var{symbol}}.
1834 Here is a trivial example:
1838 __wrap_malloc (size_t c)
1840 printf ("malloc called with %zu\n", c);
1841 return __real_malloc (c);
1845 If you link other code with this file using @option{--wrap malloc}, then
1846 all calls to @code{malloc} will call the function @code{__wrap_malloc}
1847 instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
1848 call the real @code{malloc} function.
1850 You may wish to provide a @code{__real_malloc} function as well, so that
1851 links without the @option{--wrap} option will succeed. If you do this,
1852 you should not put the definition of @code{__real_malloc} in the same
1853 file as @code{__wrap_malloc}; if you do, the assembler may resolve the
1854 call before the linker has a chance to wrap it to @code{malloc}.
1856 @kindex --eh-frame-hdr
1857 @item --eh-frame-hdr
1858 Request creation of @code{.eh_frame_hdr} section and ELF
1859 @code{PT_GNU_EH_FRAME} segment header.
1861 @kindex --enable-new-dtags
1862 @kindex --disable-new-dtags
1863 @item --enable-new-dtags
1864 @itemx --disable-new-dtags
1865 This linker can create the new dynamic tags in ELF. But the older ELF
1866 systems may not understand them. If you specify
1867 @option{--enable-new-dtags}, the dynamic tags will be created as needed.
1868 If you specify @option{--disable-new-dtags}, no new dynamic tags will be
1869 created. By default, the new dynamic tags are not created. Note that
1870 those options are only available for ELF systems.
1872 @kindex --hash-size=@var{number}
1873 @item --hash-size=@var{number}
1874 Set the default size of the linker's hash tables to a prime number
1875 close to @var{number}. Increasing this value can reduce the length of
1876 time it takes the linker to perform its tasks, at the expense of
1877 increasing the linker's memory requirements. Similarly reducing this
1878 value can reduce the memory requirements at the expense of speed.
1880 @kindex --reduce-memory-overheads
1881 @item --reduce-memory-overheads
1882 This option reduces memory requirements at ld runtime, at the expense of
1883 linking speed. This was introduced to select the old O(n^2) algorithm
1884 for link map file generation, rather than the new O(n) algorithm which uses
1885 about 40% more memory for symbol storage.
1887 Another effect of the switch is to set the default hash table size to
1888 1021, which again saves memory at the cost of lengthening the linker's
1889 run time. This is not done however if the @option{--hash-size} switch
1892 The @option{--reduce-memory-overheads} switch may be also be used to
1893 enable other tradeoffs in future versions of the linker.
1899 @subsection Options Specific to i386 PE Targets
1901 @c man begin OPTIONS
1903 The i386 PE linker supports the @option{-shared} option, which causes
1904 the output to be a dynamically linked library (DLL) instead of a
1905 normal executable. You should name the output @code{*.dll} when you
1906 use this option. In addition, the linker fully supports the standard
1907 @code{*.def} files, which may be specified on the linker command line
1908 like an object file (in fact, it should precede archives it exports
1909 symbols from, to ensure that they get linked in, just like a normal
1912 In addition to the options common to all targets, the i386 PE linker
1913 support additional command line options that are specific to the i386
1914 PE target. Options that take values may be separated from their
1915 values by either a space or an equals sign.
1919 @kindex --add-stdcall-alias
1920 @item --add-stdcall-alias
1921 If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
1922 as-is and also with the suffix stripped.
1923 [This option is specific to the i386 PE targeted port of the linker]
1926 @item --base-file @var{file}
1927 Use @var{file} as the name of a file in which to save the base
1928 addresses of all the relocations needed for generating DLLs with
1930 [This is an i386 PE specific option]
1934 Create a DLL instead of a regular executable. You may also use
1935 @option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
1937 [This option is specific to the i386 PE targeted port of the linker]
1939 @kindex --enable-stdcall-fixup
1940 @kindex --disable-stdcall-fixup
1941 @item --enable-stdcall-fixup
1942 @itemx --disable-stdcall-fixup
1943 If the link finds a symbol that it cannot resolve, it will attempt to
1944 do ``fuzzy linking'' by looking for another defined symbol that differs
1945 only in the format of the symbol name (cdecl vs stdcall) and will
1946 resolve that symbol by linking to the match. For example, the
1947 undefined symbol @code{_foo} might be linked to the function
1948 @code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
1949 to the function @code{_bar}. When the linker does this, it prints a
1950 warning, since it normally should have failed to link, but sometimes
1951 import libraries generated from third-party dlls may need this feature
1952 to be usable. If you specify @option{--enable-stdcall-fixup}, this
1953 feature is fully enabled and warnings are not printed. If you specify
1954 @option{--disable-stdcall-fixup}, this feature is disabled and such
1955 mismatches are considered to be errors.
1956 [This option is specific to the i386 PE targeted port of the linker]
1958 @cindex DLLs, creating
1959 @kindex --export-all-symbols
1960 @item --export-all-symbols
1961 If given, all global symbols in the objects used to build a DLL will
1962 be exported by the DLL. Note that this is the default if there
1963 otherwise wouldn't be any exported symbols. When symbols are
1964 explicitly exported via DEF files or implicitly exported via function
1965 attributes, the default is to not export anything else unless this
1966 option is given. Note that the symbols @code{DllMain@@12},
1967 @code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
1968 @code{impure_ptr} will not be automatically
1969 exported. Also, symbols imported from other DLLs will not be
1970 re-exported, nor will symbols specifying the DLL's internal layout
1971 such as those beginning with @code{_head_} or ending with
1972 @code{_iname}. In addition, no symbols from @code{libgcc},
1973 @code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
1974 Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
1975 not be exported, to help with C++ DLLs. Finally, there is an
1976 extensive list of cygwin-private symbols that are not exported
1977 (obviously, this applies on when building DLLs for cygwin targets).
1978 These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
1979 @code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
1980 @code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
1981 @code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
1982 @code{cygwin_premain3}, and @code{environ}.
1983 [This option is specific to the i386 PE targeted port of the linker]
1985 @kindex --exclude-symbols
1986 @item --exclude-symbols @var{symbol},@var{symbol},...
1987 Specifies a list of symbols which should not be automatically
1988 exported. The symbol names may be delimited by commas or colons.
1989 [This option is specific to the i386 PE targeted port of the linker]
1991 @kindex --file-alignment
1992 @item --file-alignment
1993 Specify the file alignment. Sections in the file will always begin at
1994 file offsets which are multiples of this number. This defaults to
1996 [This option is specific to the i386 PE targeted port of the linker]
2000 @item --heap @var{reserve}
2001 @itemx --heap @var{reserve},@var{commit}
2002 Specify the amount of memory to reserve (and optionally commit) to be
2003 used as heap for this program. The default is 1Mb reserved, 4K
2005 [This option is specific to the i386 PE targeted port of the linker]
2008 @kindex --image-base
2009 @item --image-base @var{value}
2010 Use @var{value} as the base address of your program or dll. This is
2011 the lowest memory location that will be used when your program or dll
2012 is loaded. To reduce the need to relocate and improve performance of
2013 your dlls, each should have a unique base address and not overlap any
2014 other dlls. The default is 0x400000 for executables, and 0x10000000
2016 [This option is specific to the i386 PE targeted port of the linker]
2020 If given, the stdcall suffixes (@@@var{nn}) will be stripped from
2021 symbols before they are exported.
2022 [This option is specific to the i386 PE targeted port of the linker]
2024 @kindex --large-address-aware
2025 @item --large-address-aware
2026 If given, the appropriate bit in the ``Charateristics'' field of the COFF
2027 header is set to indicate that this executable supports virtual addresses
2028 greater than 2 gigabytes. This should be used in conjuction with the /3GB
2029 or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
2030 section of the BOOT.INI. Otherwise, this bit has no effect.
2031 [This option is specific to PE targeted ports of the linker]
2033 @kindex --major-image-version
2034 @item --major-image-version @var{value}
2035 Sets the major number of the ``image version''. Defaults to 1.
2036 [This option is specific to the i386 PE targeted port of the linker]
2038 @kindex --major-os-version
2039 @item --major-os-version @var{value}
2040 Sets the major number of the ``os version''. Defaults to 4.
2041 [This option is specific to the i386 PE targeted port of the linker]
2043 @kindex --major-subsystem-version
2044 @item --major-subsystem-version @var{value}
2045 Sets the major number of the ``subsystem version''. Defaults to 4.
2046 [This option is specific to the i386 PE targeted port of the linker]
2048 @kindex --minor-image-version
2049 @item --minor-image-version @var{value}
2050 Sets the minor number of the ``image version''. Defaults to 0.
2051 [This option is specific to the i386 PE targeted port of the linker]
2053 @kindex --minor-os-version
2054 @item --minor-os-version @var{value}
2055 Sets the minor number of the ``os version''. Defaults to 0.
2056 [This option is specific to the i386 PE targeted port of the linker]
2058 @kindex --minor-subsystem-version
2059 @item --minor-subsystem-version @var{value}
2060 Sets the minor number of the ``subsystem version''. Defaults to 0.
2061 [This option is specific to the i386 PE targeted port of the linker]
2063 @cindex DEF files, creating
2064 @cindex DLLs, creating
2065 @kindex --output-def
2066 @item --output-def @var{file}
2067 The linker will create the file @var{file} which will contain a DEF
2068 file corresponding to the DLL the linker is generating. This DEF file
2069 (which should be called @code{*.def}) may be used to create an import
2070 library with @code{dlltool} or may be used as a reference to
2071 automatically or implicitly exported symbols.
2072 [This option is specific to the i386 PE targeted port of the linker]
2074 @cindex DLLs, creating
2075 @kindex --out-implib
2076 @item --out-implib @var{file}
2077 The linker will create the file @var{file} which will contain an
2078 import lib corresponding to the DLL the linker is generating. This
2079 import lib (which should be called @code{*.dll.a} or @code{*.a}
2080 may be used to link clients against the generated DLL; this behaviour
2081 makes it possible to skip a separate @code{dlltool} import library
2083 [This option is specific to the i386 PE targeted port of the linker]
2085 @kindex --enable-auto-image-base
2086 @item --enable-auto-image-base
2087 Automatically choose the image base for DLLs, unless one is specified
2088 using the @code{--image-base} argument. By using a hash generated
2089 from the dllname to create unique image bases for each DLL, in-memory
2090 collisions and relocations which can delay program execution are
2092 [This option is specific to the i386 PE targeted port of the linker]
2094 @kindex --disable-auto-image-base
2095 @item --disable-auto-image-base
2096 Do not automatically generate a unique image base. If there is no
2097 user-specified image base (@code{--image-base}) then use the platform
2099 [This option is specific to the i386 PE targeted port of the linker]
2101 @cindex DLLs, linking to
2102 @kindex --dll-search-prefix
2103 @item --dll-search-prefix @var{string}
2104 When linking dynamically to a dll without an import library,
2105 search for @code{<string><basename>.dll} in preference to
2106 @code{lib<basename>.dll}. This behaviour allows easy distinction
2107 between DLLs built for the various "subplatforms": native, cygwin,
2108 uwin, pw, etc. For instance, cygwin DLLs typically use
2109 @code{--dll-search-prefix=cyg}.
2110 [This option is specific to the i386 PE targeted port of the linker]
2112 @kindex --enable-auto-import
2113 @item --enable-auto-import
2114 Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
2115 DATA imports from DLLs, and create the necessary thunking symbols when
2116 building the import libraries with those DATA exports. Note: Use of the
2117 'auto-import' extension will cause the text section of the image file
2118 to be made writable. This does not conform to the PE-COFF format
2119 specification published by Microsoft.
2121 Using 'auto-import' generally will 'just work' -- but sometimes you may
2124 "variable '<var>' can't be auto-imported. Please read the
2125 documentation for ld's @code{--enable-auto-import} for details."
2127 This message occurs when some (sub)expression accesses an address
2128 ultimately given by the sum of two constants (Win32 import tables only
2129 allow one). Instances where this may occur include accesses to member
2130 fields of struct variables imported from a DLL, as well as using a
2131 constant index into an array variable imported from a DLL. Any
2132 multiword variable (arrays, structs, long long, etc) may trigger
2133 this error condition. However, regardless of the exact data type
2134 of the offending exported variable, ld will always detect it, issue
2135 the warning, and exit.
2137 There are several ways to address this difficulty, regardless of the
2138 data type of the exported variable:
2140 One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
2141 of adjusting references in your client code for runtime environment, so
2142 this method works only when runtime environment supports this feature.
2144 A second solution is to force one of the 'constants' to be a variable --
2145 that is, unknown and un-optimizable at compile time. For arrays,
2146 there are two possibilities: a) make the indexee (the array's address)
2147 a variable, or b) make the 'constant' index a variable. Thus:
2150 extern type extern_array[];
2152 @{ volatile type *t=extern_array; t[1] @}
2158 extern type extern_array[];
2160 @{ volatile int t=1; extern_array[t] @}
2163 For structs (and most other multiword data types) the only option
2164 is to make the struct itself (or the long long, or the ...) variable:
2167 extern struct s extern_struct;
2168 extern_struct.field -->
2169 @{ volatile struct s *t=&extern_struct; t->field @}
2175 extern long long extern_ll;
2177 @{ volatile long long * local_ll=&extern_ll; *local_ll @}
2180 A third method of dealing with this difficulty is to abandon
2181 'auto-import' for the offending symbol and mark it with
2182 @code{__declspec(dllimport)}. However, in practise that
2183 requires using compile-time #defines to indicate whether you are
2184 building a DLL, building client code that will link to the DLL, or
2185 merely building/linking to a static library. In making the choice
2186 between the various methods of resolving the 'direct address with
2187 constant offset' problem, you should consider typical real-world usage:
2195 void main(int argc, char **argv)@{
2196 printf("%d\n",arr[1]);
2206 void main(int argc, char **argv)@{
2207 /* This workaround is for win32 and cygwin; do not "optimize" */
2208 volatile int *parr = arr;
2209 printf("%d\n",parr[1]);
2216 /* Note: auto-export is assumed (no __declspec(dllexport)) */
2217 #if (defined(_WIN32) || defined(__CYGWIN__)) && \
2218 !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
2219 #define FOO_IMPORT __declspec(dllimport)
2223 extern FOO_IMPORT int arr[];
2226 void main(int argc, char **argv)@{
2227 printf("%d\n",arr[1]);
2231 A fourth way to avoid this problem is to re-code your
2232 library to use a functional interface rather than a data interface
2233 for the offending variables (e.g. set_foo() and get_foo() accessor
2235 [This option is specific to the i386 PE targeted port of the linker]
2237 @kindex --disable-auto-import
2238 @item --disable-auto-import
2239 Do not attempt to do sophisticated linking of @code{_symbol} to
2240 @code{__imp__symbol} for DATA imports from DLLs.
2241 [This option is specific to the i386 PE targeted port of the linker]
2243 @kindex --enable-runtime-pseudo-reloc
2244 @item --enable-runtime-pseudo-reloc
2245 If your code contains expressions described in --enable-auto-import section,
2246 that is, DATA imports from DLL with non-zero offset, this switch will create
2247 a vector of 'runtime pseudo relocations' which can be used by runtime
2248 environment to adjust references to such data in your client code.
2249 [This option is specific to the i386 PE targeted port of the linker]
2251 @kindex --disable-runtime-pseudo-reloc
2252 @item --disable-runtime-pseudo-reloc
2253 Do not create pseudo relocations for non-zero offset DATA imports from
2254 DLLs. This is the default.
2255 [This option is specific to the i386 PE targeted port of the linker]
2257 @kindex --enable-extra-pe-debug
2258 @item --enable-extra-pe-debug
2259 Show additional debug info related to auto-import symbol thunking.
2260 [This option is specific to the i386 PE targeted port of the linker]
2262 @kindex --section-alignment
2263 @item --section-alignment
2264 Sets the section alignment. Sections in memory will always begin at
2265 addresses which are a multiple of this number. Defaults to 0x1000.
2266 [This option is specific to the i386 PE targeted port of the linker]
2270 @item --stack @var{reserve}
2271 @itemx --stack @var{reserve},@var{commit}
2272 Specify the amount of memory to reserve (and optionally commit) to be
2273 used as stack for this program. The default is 2Mb reserved, 4K
2275 [This option is specific to the i386 PE targeted port of the linker]
2278 @item --subsystem @var{which}
2279 @itemx --subsystem @var{which}:@var{major}
2280 @itemx --subsystem @var{which}:@var{major}.@var{minor}
2281 Specifies the subsystem under which your program will execute. The
2282 legal values for @var{which} are @code{native}, @code{windows},
2283 @code{console}, @code{posix}, and @code{xbox}. You may optionally set
2284 the subsystem version also. Numeric values are also accepted for
2286 [This option is specific to the i386 PE targeted port of the linker]
2293 @subsection Options specific to Motorola 68HC11 and 68HC12 targets
2295 @c man begin OPTIONS
2297 The 68HC11 and 68HC12 linkers support specific options to control the
2298 memory bank switching mapping and trampoline code generation.
2302 @kindex --no-trampoline
2303 @item --no-trampoline
2304 This option disables the generation of trampoline. By default a trampoline
2305 is generated for each far function which is called using a @code{jsr}
2306 instruction (this happens when a pointer to a far function is taken).
2308 @kindex --bank-window
2309 @item --bank-window @var{name}
2310 This option indicates to the linker the name of the memory region in
2311 the @samp{MEMORY} specification that describes the memory bank window.
2312 The definition of such region is then used by the linker to compute
2313 paging and addresses within the memory window.
2322 @section Environment Variables
2324 @c man begin ENVIRONMENT
2326 You can change the behaviour of @command{ld} with the environment variables
2327 @ifclear SingleFormat
2330 @code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
2332 @ifclear SingleFormat
2334 @cindex default input format
2335 @code{GNUTARGET} determines the input-file object format if you don't
2336 use @samp{-b} (or its synonym @samp{--format}). Its value should be one
2337 of the BFD names for an input format (@pxref{BFD}). If there is no
2338 @code{GNUTARGET} in the environment, @command{ld} uses the natural format
2339 of the target. If @code{GNUTARGET} is set to @code{default} then BFD
2340 attempts to discover the input format by examining binary input files;
2341 this method often succeeds, but there are potential ambiguities, since
2342 there is no method of ensuring that the magic number used to specify
2343 object-file formats is unique. However, the configuration procedure for
2344 BFD on each system places the conventional format for that system first
2345 in the search-list, so ambiguities are resolved in favor of convention.
2349 @cindex default emulation
2350 @cindex emulation, default
2351 @code{LDEMULATION} determines the default emulation if you don't use the
2352 @samp{-m} option. The emulation can affect various aspects of linker
2353 behaviour, particularly the default linker script. You can list the
2354 available emulations with the @samp{--verbose} or @samp{-V} options. If
2355 the @samp{-m} option is not used, and the @code{LDEMULATION} environment
2356 variable is not defined, the default emulation depends upon how the
2357 linker was configured.
2359 @kindex COLLECT_NO_DEMANGLE
2360 @cindex demangling, default
2361 Normally, the linker will default to demangling symbols. However, if
2362 @code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
2363 default to not demangling symbols. This environment variable is used in
2364 a similar fashion by the @code{gcc} linker wrapper program. The default
2365 may be overridden by the @samp{--demangle} and @samp{--no-demangle}
2372 @chapter Linker Scripts
2375 @cindex linker scripts
2376 @cindex command files
2377 Every link is controlled by a @dfn{linker script}. This script is
2378 written in the linker command language.
2380 The main purpose of the linker script is to describe how the sections in
2381 the input files should be mapped into the output file, and to control
2382 the memory layout of the output file. Most linker scripts do nothing
2383 more than this. However, when necessary, the linker script can also
2384 direct the linker to perform many other operations, using the commands
2387 The linker always uses a linker script. If you do not supply one
2388 yourself, the linker will use a default script that is compiled into the
2389 linker executable. You can use the @samp{--verbose} command line option
2390 to display the default linker script. Certain command line options,
2391 such as @samp{-r} or @samp{-N}, will affect the default linker script.
2393 You may supply your own linker script by using the @samp{-T} command
2394 line option. When you do this, your linker script will replace the
2395 default linker script.
2397 You may also use linker scripts implicitly by naming them as input files
2398 to the linker, as though they were files to be linked. @xref{Implicit
2402 * Basic Script Concepts:: Basic Linker Script Concepts
2403 * Script Format:: Linker Script Format
2404 * Simple Example:: Simple Linker Script Example
2405 * Simple Commands:: Simple Linker Script Commands
2406 * Assignments:: Assigning Values to Symbols
2407 * SECTIONS:: SECTIONS Command
2408 * MEMORY:: MEMORY Command
2409 * PHDRS:: PHDRS Command
2410 * VERSION:: VERSION Command
2411 * Expressions:: Expressions in Linker Scripts
2412 * Implicit Linker Scripts:: Implicit Linker Scripts
2415 @node Basic Script Concepts
2416 @section Basic Linker Script Concepts
2417 @cindex linker script concepts
2418 We need to define some basic concepts and vocabulary in order to
2419 describe the linker script language.
2421 The linker combines input files into a single output file. The output
2422 file and each input file are in a special data format known as an
2423 @dfn{object file format}. Each file is called an @dfn{object file}.
2424 The output file is often called an @dfn{executable}, but for our
2425 purposes we will also call it an object file. Each object file has,
2426 among other things, a list of @dfn{sections}. We sometimes refer to a
2427 section in an input file as an @dfn{input section}; similarly, a section
2428 in the output file is an @dfn{output section}.
2430 Each section in an object file has a name and a size. Most sections
2431 also have an associated block of data, known as the @dfn{section
2432 contents}. A section may be marked as @dfn{loadable}, which mean that
2433 the contents should be loaded into memory when the output file is run.
2434 A section with no contents may be @dfn{allocatable}, which means that an
2435 area in memory should be set aside, but nothing in particular should be
2436 loaded there (in some cases this memory must be zeroed out). A section
2437 which is neither loadable nor allocatable typically contains some sort
2438 of debugging information.
2440 Every loadable or allocatable output section has two addresses. The
2441 first is the @dfn{VMA}, or virtual memory address. This is the address
2442 the section will have when the output file is run. The second is the
2443 @dfn{LMA}, or load memory address. This is the address at which the
2444 section will be loaded. In most cases the two addresses will be the
2445 same. An example of when they might be different is when a data section
2446 is loaded into ROM, and then copied into RAM when the program starts up
2447 (this technique is often used to initialize global variables in a ROM
2448 based system). In this case the ROM address would be the LMA, and the
2449 RAM address would be the VMA.
2451 You can see the sections in an object file by using the @code{objdump}
2452 program with the @samp{-h} option.
2454 Every object file also has a list of @dfn{symbols}, known as the
2455 @dfn{symbol table}. A symbol may be defined or undefined. Each symbol
2456 has a name, and each defined symbol has an address, among other
2457 information. If you compile a C or C++ program into an object file, you
2458 will get a defined symbol for every defined function and global or
2459 static variable. Every undefined function or global variable which is
2460 referenced in the input file will become an undefined symbol.
2462 You can see the symbols in an object file by using the @code{nm}
2463 program, or by using the @code{objdump} program with the @samp{-t}
2467 @section Linker Script Format
2468 @cindex linker script format
2469 Linker scripts are text files.
2471 You write a linker script as a series of commands. Each command is
2472 either a keyword, possibly followed by arguments, or an assignment to a
2473 symbol. You may separate commands using semicolons. Whitespace is
2476 Strings such as file or format names can normally be entered directly.
2477 If the file name contains a character such as a comma which would
2478 otherwise serve to separate file names, you may put the file name in
2479 double quotes. There is no way to use a double quote character in a
2482 You may include comments in linker scripts just as in C, delimited by
2483 @samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
2486 @node Simple Example
2487 @section Simple Linker Script Example
2488 @cindex linker script example
2489 @cindex example of linker script
2490 Many linker scripts are fairly simple.
2492 The simplest possible linker script has just one command:
2493 @samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
2494 memory layout of the output file.
2496 The @samp{SECTIONS} command is a powerful command. Here we will
2497 describe a simple use of it. Let's assume your program consists only of
2498 code, initialized data, and uninitialized data. These will be in the
2499 @samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
2500 Let's assume further that these are the only sections which appear in
2503 For this example, let's say that the code should be loaded at address
2504 0x10000, and that the data should start at address 0x8000000. Here is a
2505 linker script which will do that:
2510 .text : @{ *(.text) @}
2512 .data : @{ *(.data) @}
2513 .bss : @{ *(.bss) @}
2517 You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
2518 followed by a series of symbol assignments and output section
2519 descriptions enclosed in curly braces.
2521 The first line inside the @samp{SECTIONS} command of the above example
2522 sets the value of the special symbol @samp{.}, which is the location
2523 counter. If you do not specify the address of an output section in some
2524 other way (other ways are described later), the address is set from the
2525 current value of the location counter. The location counter is then
2526 incremented by the size of the output section. At the start of the
2527 @samp{SECTIONS} command, the location counter has the value @samp{0}.
2529 The second line defines an output section, @samp{.text}. The colon is
2530 required syntax which may be ignored for now. Within the curly braces
2531 after the output section name, you list the names of the input sections
2532 which should be placed into this output section. The @samp{*} is a
2533 wildcard which matches any file name. The expression @samp{*(.text)}
2534 means all @samp{.text} input sections in all input files.
2536 Since the location counter is @samp{0x10000} when the output section
2537 @samp{.text} is defined, the linker will set the address of the
2538 @samp{.text} section in the output file to be @samp{0x10000}.
2540 The remaining lines define the @samp{.data} and @samp{.bss} sections in
2541 the output file. The linker will place the @samp{.data} output section
2542 at address @samp{0x8000000}. After the linker places the @samp{.data}
2543 output section, the value of the location counter will be
2544 @samp{0x8000000} plus the size of the @samp{.data} output section. The
2545 effect is that the linker will place the @samp{.bss} output section
2546 immediately after the @samp{.data} output section in memory.
2548 The linker will ensure that each output section has the required
2549 alignment, by increasing the location counter if necessary. In this
2550 example, the specified addresses for the @samp{.text} and @samp{.data}
2551 sections will probably satisfy any alignment constraints, but the linker
2552 may have to create a small gap between the @samp{.data} and @samp{.bss}
2555 That's it! That's a simple and complete linker script.
2557 @node Simple Commands
2558 @section Simple Linker Script Commands
2559 @cindex linker script simple commands
2560 In this section we describe the simple linker script commands.
2563 * Entry Point:: Setting the entry point
2564 * File Commands:: Commands dealing with files
2565 @ifclear SingleFormat
2566 * Format Commands:: Commands dealing with object file formats
2569 * Miscellaneous Commands:: Other linker script commands
2573 @subsection Setting the Entry Point
2574 @kindex ENTRY(@var{symbol})
2575 @cindex start of execution
2576 @cindex first instruction
2578 The first instruction to execute in a program is called the @dfn{entry
2579 point}. You can use the @code{ENTRY} linker script command to set the
2580 entry point. The argument is a symbol name:
2585 There are several ways to set the entry point. The linker will set the
2586 entry point by trying each of the following methods in order, and
2587 stopping when one of them succeeds:
2590 the @samp{-e} @var{entry} command-line option;
2592 the @code{ENTRY(@var{symbol})} command in a linker script;
2594 the value of the symbol @code{start}, if defined;
2596 the address of the first byte of the @samp{.text} section, if present;
2598 The address @code{0}.
2602 @subsection Commands Dealing with Files
2603 @cindex linker script file commands
2604 Several linker script commands deal with files.
2607 @item INCLUDE @var{filename}
2608 @kindex INCLUDE @var{filename}
2609 @cindex including a linker script
2610 Include the linker script @var{filename} at this point. The file will
2611 be searched for in the current directory, and in any directory specified
2612 with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
2615 @item INPUT(@var{file}, @var{file}, @dots{})
2616 @itemx INPUT(@var{file} @var{file} @dots{})
2617 @kindex INPUT(@var{files})
2618 @cindex input files in linker scripts
2619 @cindex input object files in linker scripts
2620 @cindex linker script input object files
2621 The @code{INPUT} command directs the linker to include the named files
2622 in the link, as though they were named on the command line.
2624 For example, if you always want to include @file{subr.o} any time you do
2625 a link, but you can't be bothered to put it on every link command line,
2626 then you can put @samp{INPUT (subr.o)} in your linker script.
2628 In fact, if you like, you can list all of your input files in the linker
2629 script, and then invoke the linker with nothing but a @samp{-T} option.
2631 In case a @dfn{sysroot prefix} is configured, and the filename starts
2632 with the @samp{/} character, and the script being processed was
2633 located inside the @dfn{sysroot prefix}, the filename will be looked
2634 for in the @dfn{sysroot prefix}. Otherwise, the linker will try to
2635 open the file in the current directory. If it is not found, the
2636 linker will search through the archive library search path. See the
2637 description of @samp{-L} in @ref{Options,,Command Line Options}.
2639 If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
2640 name to @code{lib@var{file}.a}, as with the command line argument
2643 When you use the @code{INPUT} command in an implicit linker script, the
2644 files will be included in the link at the point at which the linker
2645 script file is included. This can affect archive searching.
2647 @item GROUP(@var{file}, @var{file}, @dots{})
2648 @itemx GROUP(@var{file} @var{file} @dots{})
2649 @kindex GROUP(@var{files})
2650 @cindex grouping input files
2651 The @code{GROUP} command is like @code{INPUT}, except that the named
2652 files should all be archives, and they are searched repeatedly until no
2653 new undefined references are created. See the description of @samp{-(}
2654 in @ref{Options,,Command Line Options}.
2656 @item AS_NEEDED(@var{file}, @var{file}, @dots{})
2657 @itemx AS_NEEDED(@var{file} @var{file} @dots{})
2658 @kindex AS_NEEDED(@var{files})
2659 This construct can appear only inside of the @code{INPUT} or @code{GROUP}
2660 commands, among other filenames. The files listed will be handled
2661 as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
2662 with the exception of ELF shared libraries, that will be added only
2663 when they are actually needed. This construct essentially enables
2664 @option{--as-needed} option for all the files listed inside of it
2665 and restores previous @option{--as-needed} resp. @option{--no-as-needed}
2668 @item OUTPUT(@var{filename})
2669 @kindex OUTPUT(@var{filename})
2670 @cindex output file name in linker scripot
2671 The @code{OUTPUT} command names the output file. Using
2672 @code{OUTPUT(@var{filename})} in the linker script is exactly like using
2673 @samp{-o @var{filename}} on the command line (@pxref{Options,,Command
2674 Line Options}). If both are used, the command line option takes
2677 You can use the @code{OUTPUT} command to define a default name for the
2678 output file other than the usual default of @file{a.out}.
2680 @item SEARCH_DIR(@var{path})
2681 @kindex SEARCH_DIR(@var{path})
2682 @cindex library search path in linker script
2683 @cindex archive search path in linker script
2684 @cindex search path in linker script
2685 The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
2686 @command{ld} looks for archive libraries. Using
2687 @code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
2688 on the command line (@pxref{Options,,Command Line Options}). If both
2689 are used, then the linker will search both paths. Paths specified using
2690 the command line option are searched first.
2692 @item STARTUP(@var{filename})
2693 @kindex STARTUP(@var{filename})
2694 @cindex first input file
2695 The @code{STARTUP} command is just like the @code{INPUT} command, except
2696 that @var{filename} will become the first input file to be linked, as
2697 though it were specified first on the command line. This may be useful
2698 when using a system in which the entry point is always the start of the
2702 @ifclear SingleFormat
2703 @node Format Commands
2704 @subsection Commands Dealing with Object File Formats
2705 A couple of linker script commands deal with object file formats.
2708 @item OUTPUT_FORMAT(@var{bfdname})
2709 @itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
2710 @kindex OUTPUT_FORMAT(@var{bfdname})
2711 @cindex output file format in linker script
2712 The @code{OUTPUT_FORMAT} command names the BFD format to use for the
2713 output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
2714 exactly like using @samp{--oformat @var{bfdname}} on the command line
2715 (@pxref{Options,,Command Line Options}). If both are used, the command
2716 line option takes precedence.
2718 You can use @code{OUTPUT_FORMAT} with three arguments to use different
2719 formats based on the @samp{-EB} and @samp{-EL} command line options.
2720 This permits the linker script to set the output format based on the
2723 If neither @samp{-EB} nor @samp{-EL} are used, then the output format
2724 will be the first argument, @var{default}. If @samp{-EB} is used, the
2725 output format will be the second argument, @var{big}. If @samp{-EL} is
2726 used, the output format will be the third argument, @var{little}.
2728 For example, the default linker script for the MIPS ELF target uses this
2731 OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
2733 This says that the default format for the output file is
2734 @samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line
2735 option, the output file will be created in the @samp{elf32-littlemips}
2738 @item TARGET(@var{bfdname})
2739 @kindex TARGET(@var{bfdname})
2740 @cindex input file format in linker script
2741 The @code{TARGET} command names the BFD format to use when reading input
2742 files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
2743 This command is like using @samp{-b @var{bfdname}} on the command line
2744 (@pxref{Options,,Command Line Options}). If the @code{TARGET} command
2745 is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
2746 command is also used to set the format for the output file. @xref{BFD}.
2750 @node Miscellaneous Commands
2751 @subsection Other Linker Script Commands
2752 There are a few other linker scripts commands.
2755 @item ASSERT(@var{exp}, @var{message})
2757 @cindex assertion in linker script
2758 Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
2759 with an error code, and print @var{message}.
2761 @item EXTERN(@var{symbol} @var{symbol} @dots{})
2763 @cindex undefined symbol in linker script
2764 Force @var{symbol} to be entered in the output file as an undefined
2765 symbol. Doing this may, for example, trigger linking of additional
2766 modules from standard libraries. You may list several @var{symbol}s for
2767 each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
2768 command has the same effect as the @samp{-u} command-line option.
2770 @item FORCE_COMMON_ALLOCATION
2771 @kindex FORCE_COMMON_ALLOCATION
2772 @cindex common allocation in linker script
2773 This command has the same effect as the @samp{-d} command-line option:
2774 to make @command{ld} assign space to common symbols even if a relocatable
2775 output file is specified (@samp{-r}).
2777 @item INHIBIT_COMMON_ALLOCATION
2778 @kindex INHIBIT_COMMON_ALLOCATION
2779 @cindex common allocation in linker script
2780 This command has the same effect as the @samp{--no-define-common}
2781 command-line option: to make @code{ld} omit the assignment of addresses
2782 to common symbols even for a non-relocatable output file.
2784 @item NOCROSSREFS(@var{section} @var{section} @dots{})
2785 @kindex NOCROSSREFS(@var{sections})
2786 @cindex cross references
2787 This command may be used to tell @command{ld} to issue an error about any
2788 references among certain output sections.
2790 In certain types of programs, particularly on embedded systems when
2791 using overlays, when one section is loaded into memory, another section
2792 will not be. Any direct references between the two sections would be
2793 errors. For example, it would be an error if code in one section called
2794 a function defined in the other section.
2796 The @code{NOCROSSREFS} command takes a list of output section names. If
2797 @command{ld} detects any cross references between the sections, it reports
2798 an error and returns a non-zero exit status. Note that the
2799 @code{NOCROSSREFS} command uses output section names, not input section
2802 @ifclear SingleFormat
2803 @item OUTPUT_ARCH(@var{bfdarch})
2804 @kindex OUTPUT_ARCH(@var{bfdarch})
2805 @cindex machine architecture
2806 @cindex architecture
2807 Specify a particular output machine architecture. The argument is one
2808 of the names used by the BFD library (@pxref{BFD}). You can see the
2809 architecture of an object file by using the @code{objdump} program with
2810 the @samp{-f} option.
2815 @section Assigning Values to Symbols
2816 @cindex assignment in scripts
2817 @cindex symbol definition, scripts
2818 @cindex variables, defining
2819 You may assign a value to a symbol in a linker script. This will define
2820 the symbol and place it into the symbol table with a global scope.
2823 * Simple Assignments:: Simple Assignments
2825 * PROVIDE_HIDDEN:: PROVIDE_HIDDEN
2826 * Source Code Reference:: How to use a linker script defined symbol in source code
2829 @node Simple Assignments
2830 @subsection Simple Assignments
2832 You may assign to a symbol using any of the C assignment operators:
2835 @item @var{symbol} = @var{expression} ;
2836 @itemx @var{symbol} += @var{expression} ;
2837 @itemx @var{symbol} -= @var{expression} ;
2838 @itemx @var{symbol} *= @var{expression} ;
2839 @itemx @var{symbol} /= @var{expression} ;
2840 @itemx @var{symbol} <<= @var{expression} ;
2841 @itemx @var{symbol} >>= @var{expression} ;
2842 @itemx @var{symbol} &= @var{expression} ;
2843 @itemx @var{symbol} |= @var{expression} ;
2846 The first case will define @var{symbol} to the value of
2847 @var{expression}. In the other cases, @var{symbol} must already be
2848 defined, and the value will be adjusted accordingly.
2850 The special symbol name @samp{.} indicates the location counter. You
2851 may only use this within a @code{SECTIONS} command. @xref{Location Counter}.
2853 The semicolon after @var{expression} is required.
2855 Expressions are defined below; see @ref{Expressions}.
2857 You may write symbol assignments as commands in their own right, or as
2858 statements within a @code{SECTIONS} command, or as part of an output
2859 section description in a @code{SECTIONS} command.
2861 The section of the symbol will be set from the section of the
2862 expression; for more information, see @ref{Expression Section}.
2864 Here is an example showing the three different places that symbol
2865 assignments may be used:
2876 _bdata = (. + 3) & ~ 3;
2877 .data : @{ *(.data) @}
2881 In this example, the symbol @samp{floating_point} will be defined as
2882 zero. The symbol @samp{_etext} will be defined as the address following
2883 the last @samp{.text} input section. The symbol @samp{_bdata} will be
2884 defined as the address following the @samp{.text} output section aligned
2885 upward to a 4 byte boundary.
2890 In some cases, it is desirable for a linker script to define a symbol
2891 only if it is referenced and is not defined by any object included in
2892 the link. For example, traditional linkers defined the symbol
2893 @samp{etext}. However, ANSI C requires that the user be able to use
2894 @samp{etext} as a function name without encountering an error. The
2895 @code{PROVIDE} keyword may be used to define a symbol, such as
2896 @samp{etext}, only if it is referenced but not defined. The syntax is
2897 @code{PROVIDE(@var{symbol} = @var{expression})}.
2899 Here is an example of using @code{PROVIDE} to define @samp{etext}:
2912 In this example, if the program defines @samp{_etext} (with a leading
2913 underscore), the linker will give a multiple definition error. If, on
2914 the other hand, the program defines @samp{etext} (with no leading
2915 underscore), the linker will silently use the definition in the program.
2916 If the program references @samp{etext} but does not define it, the
2917 linker will use the definition in the linker script.
2919 @node PROVIDE_HIDDEN
2920 @subsection PROVIDE_HIDDEN
2921 @cindex PROVIDE_HIDDEN
2922 Similar to @code{PROVIDE}. For ELF targeted ports, the symbol will be
2923 hidden and won't be exported.
2925 @node Source Code Reference
2926 @subsection Source Code Reference
2928 Accessing a linker script defined variable from source code is not
2929 intuitive. In particular a linker script symbol is not equivalent to
2930 a variable declaration in a high level language, it is instead a
2931 symbol that does not have a value.
2933 Before going further, it is important to note that compilers often
2934 transform names in the source code into different names when they are
2935 stored in the symbol table. For example, Fortran compilers commonly
2936 prepend or append an underscore, and C++ performs extensive @samp{name
2937 mangling}. Therefore there might be a discrepancy between the name
2938 of a variable as it is used in source code and the name of the same
2939 variable as it is defined in a linker script. For example in C a
2940 linker script variable might be referred to as:
2946 But in the linker script it might be defined as:
2952 In the remaining examples however it is assumed that no name
2953 transformation has taken place.
2955 When a symbol is declared in a high level language such as C, two
2956 things happen. The first is that the compiler reserves enough space
2957 in the program's memory to hold the @emph{value} of the symbol. The
2958 second is that the compiler creates an entry in the program's symbol
2959 table which holds the symbol's @emph{address}. ie the symbol table
2960 contains the address of the block of memory holding the symbol's
2961 value. So for example the following C declaration, at file scope:
2967 creates a entry called @samp{foo} in the symbol table. This entry
2968 holds the address of an @samp{int} sized block of memory where the
2969 number 1000 is initially stored.
2971 When a program references a symbol the compiler generates code that
2972 first accesses the symbol table to find the address of the symbol's
2973 memory block and then code to read the value from that memory block.
2980 looks up the symbol @samp{foo} in the symbol table, gets the address
2981 associated with this symbol and then writes the value 1 into that
2988 looks up the symbol @samp{foo} in the symbol table, gets it address
2989 and then copies this address into the block of memory associated with
2990 the variable @samp{a}.
2992 Linker scripts symbol declarations, by contrast, create an entry in
2993 the symbol table but do not assign any memory to them. Thus they are
2994 an address without a value. So for example the linker script definition:
3000 creates an entry in the symbol table called @samp{foo} which holds
3001 the address of memory location 1000, but nothing special is stored at
3002 address 1000. This means that you cannot access the @emph{value} of a
3003 linker script defined symbol - it has no value - all you can do is
3004 access the @emph{address} of a linker script defined symbol.
3006 Hence when you are using a linker script defined symbol in source code
3007 you should always take the address of the symbol, and never attempt to
3008 use its value. For example suppose you want to copy the contents of a
3009 section of memory called .ROM into a section called .FLASH and the
3010 linker script contains these declarations:
3014 start_of_ROM = .ROM;
3015 end_of_ROM = .ROM + sizeof (.ROM) - 1;
3016 start_of_FLASH = .FLASH;
3020 Then the C source code to perform the copy would be:
3024 extern char start_of_ROM, end_of_ROM, start_of_FLASH;
3026 memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
3030 Note the use of the @samp{&} operators. These are correct.
3033 @section SECTIONS Command
3035 The @code{SECTIONS} command tells the linker how to map input sections
3036 into output sections, and how to place the output sections in memory.
3038 The format of the @code{SECTIONS} command is:
3042 @var{sections-command}
3043 @var{sections-command}
3048 Each @var{sections-command} may of be one of the following:
3052 an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
3054 a symbol assignment (@pxref{Assignments})
3056 an output section description
3058 an overlay description
3061 The @code{ENTRY} command and symbol assignments are permitted inside the
3062 @code{SECTIONS} command for convenience in using the location counter in
3063 those commands. This can also make the linker script easier to
3064 understand because you can use those commands at meaningful points in
3065 the layout of the output file.
3067 Output section descriptions and overlay descriptions are described
3070 If you do not use a @code{SECTIONS} command in your linker script, the
3071 linker will place each input section into an identically named output
3072 section in the order that the sections are first encountered in the
3073 input files. If all input sections are present in the first file, for
3074 example, the order of sections in the output file will match the order
3075 in the first input file. The first section will be at address zero.
3078 * Output Section Description:: Output section description
3079 * Output Section Name:: Output section name
3080 * Output Section Address:: Output section address
3081 * Input Section:: Input section description
3082 * Output Section Data:: Output section data
3083 * Output Section Keywords:: Output section keywords
3084 * Output Section Discarding:: Output section discarding
3085 * Output Section Attributes:: Output section attributes
3086 * Overlay Description:: Overlay description
3089 @node Output Section Description
3090 @subsection Output Section Description
3091 The full description of an output section looks like this:
3094 @var{section} [@var{address}] [(@var{type})] :
3095 [AT(@var{lma})] [ALIGN(@var{section_align})] [SUBALIGN(@var{subsection_align})]
3097 @var{output-section-command}
3098 @var{output-section-command}
3100 @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
3104 Most output sections do not use most of the optional section attributes.
3106 The whitespace around @var{section} is required, so that the section
3107 name is unambiguous. The colon and the curly braces are also required.
3108 The line breaks and other white space are optional.
3110 Each @var{output-section-command} may be one of the following:
3114 a symbol assignment (@pxref{Assignments})
3116 an input section description (@pxref{Input Section})
3118 data values to include directly (@pxref{Output Section Data})
3120 a special output section keyword (@pxref{Output Section Keywords})
3123 @node Output Section Name
3124 @subsection Output Section Name
3125 @cindex name, section
3126 @cindex section name
3127 The name of the output section is @var{section}. @var{section} must
3128 meet the constraints of your output format. In formats which only
3129 support a limited number of sections, such as @code{a.out}, the name
3130 must be one of the names supported by the format (@code{a.out}, for
3131 example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
3132 output format supports any number of sections, but with numbers and not
3133 names (as is the case for Oasys), the name should be supplied as a
3134 quoted numeric string. A section name may consist of any sequence of
3135 characters, but a name which contains any unusual characters such as
3136 commas must be quoted.
3138 The output section name @samp{/DISCARD/} is special; @ref{Output Section
3141 @node Output Section Address
3142 @subsection Output Section Address
3143 @cindex address, section
3144 @cindex section address
3145 The @var{address} is an expression for the VMA (the virtual memory
3146 address) of the output section. If you do not provide @var{address},
3147 the linker will set it based on @var{region} if present, or otherwise
3148 based on the current value of the location counter.
3150 If you provide @var{address}, the address of the output section will be
3151 set to precisely that. If you provide neither @var{address} nor
3152 @var{region}, then the address of the output section will be set to the
3153 current value of the location counter aligned to the alignment
3154 requirements of the output section. The alignment requirement of the
3155 output section is the strictest alignment of any input section contained
3156 within the output section.
3160 .text . : @{ *(.text) @}
3165 .text : @{ *(.text) @}
3168 are subtly different. The first will set the address of the
3169 @samp{.text} output section to the current value of the location
3170 counter. The second will set it to the current value of the location
3171 counter aligned to the strictest alignment of a @samp{.text} input
3174 The @var{address} may be an arbitrary expression; @ref{Expressions}.
3175 For example, if you want to align the section on a 0x10 byte boundary,
3176 so that the lowest four bits of the section address are zero, you could
3177 do something like this:
3179 .text ALIGN(0x10) : @{ *(.text) @}
3182 This works because @code{ALIGN} returns the current location counter
3183 aligned upward to the specified value.
3185 Specifying @var{address} for a section will change the value of the
3189 @subsection Input Section Description
3190 @cindex input sections
3191 @cindex mapping input sections to output sections
3192 The most common output section command is an input section description.
3194 The input section description is the most basic linker script operation.
3195 You use output sections to tell the linker how to lay out your program
3196 in memory. You use input section descriptions to tell the linker how to
3197 map the input files into your memory layout.
3200 * Input Section Basics:: Input section basics
3201 * Input Section Wildcards:: Input section wildcard patterns
3202 * Input Section Common:: Input section for common symbols
3203 * Input Section Keep:: Input section and garbage collection
3204 * Input Section Example:: Input section example
3207 @node Input Section Basics
3208 @subsubsection Input Section Basics
3209 @cindex input section basics
3210 An input section description consists of a file name optionally followed
3211 by a list of section names in parentheses.
3213 The file name and the section name may be wildcard patterns, which we
3214 describe further below (@pxref{Input Section Wildcards}).
3216 The most common input section description is to include all input
3217 sections with a particular name in the output section. For example, to
3218 include all input @samp{.text} sections, you would write:
3223 Here the @samp{*} is a wildcard which matches any file name. To exclude a list
3224 of files from matching the file name wildcard, EXCLUDE_FILE may be used to
3225 match all files except the ones specified in the EXCLUDE_FILE list. For
3228 (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
3230 will cause all .ctors sections from all files except @file{crtend.o} and
3231 @file{otherfile.o} to be included.
3233 There are two ways to include more than one section:
3239 The difference between these is the order in which the @samp{.text} and
3240 @samp{.rdata} input sections will appear in the output section. In the
3241 first example, they will be intermingled, appearing in the same order as
3242 they are found in the linker input. In the second example, all
3243 @samp{.text} input sections will appear first, followed by all
3244 @samp{.rdata} input sections.
3246 You can specify a file name to include sections from a particular file.
3247 You would do this if one or more of your files contain special data that
3248 needs to be at a particular location in memory. For example:
3253 If you use a file name without a list of sections, then all sections in
3254 the input file will be included in the output section. This is not
3255 commonly done, but it may by useful on occasion. For example:
3260 When you use a file name which does not contain any wild card
3261 characters, the linker will first see if you also specified the file
3262 name on the linker command line or in an @code{INPUT} command. If you
3263 did not, the linker will attempt to open the file as an input file, as
3264 though it appeared on the command line. Note that this differs from an
3265 @code{INPUT} command, because the linker will not search for the file in
3266 the archive search path.
3268 @node Input Section Wildcards
3269 @subsubsection Input Section Wildcard Patterns
3270 @cindex input section wildcards
3271 @cindex wildcard file name patterns
3272 @cindex file name wildcard patterns
3273 @cindex section name wildcard patterns
3274 In an input section description, either the file name or the section
3275 name or both may be wildcard patterns.
3277 The file name of @samp{*} seen in many examples is a simple wildcard
3278 pattern for the file name.
3280 The wildcard patterns are like those used by the Unix shell.
3284 matches any number of characters
3286 matches any single character
3288 matches a single instance of any of the @var{chars}; the @samp{-}
3289 character may be used to specify a range of characters, as in
3290 @samp{[a-z]} to match any lower case letter
3292 quotes the following character
3295 When a file name is matched with a wildcard, the wildcard characters
3296 will not match a @samp{/} character (used to separate directory names on
3297 Unix). A pattern consisting of a single @samp{*} character is an
3298 exception; it will always match any file name, whether it contains a
3299 @samp{/} or not. In a section name, the wildcard characters will match
3300 a @samp{/} character.
3302 File name wildcard patterns only match files which are explicitly
3303 specified on the command line or in an @code{INPUT} command. The linker
3304 does not search directories to expand wildcards.
3306 If a file name matches more than one wildcard pattern, or if a file name
3307 appears explicitly and is also matched by a wildcard pattern, the linker
3308 will use the first match in the linker script. For example, this
3309 sequence of input section descriptions is probably in error, because the
3310 @file{data.o} rule will not be used:
3312 .data : @{ *(.data) @}
3313 .data1 : @{ data.o(.data) @}
3316 @cindex SORT_BY_NAME
3317 Normally, the linker will place files and sections matched by wildcards
3318 in the order in which they are seen during the link. You can change
3319 this by using the @code{SORT_BY_NAME} keyword, which appears before a wildcard
3320 pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the
3321 @code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
3322 into ascending order by name before placing them in the output file.
3324 @cindex SORT_BY_ALIGNMENT
3325 @code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
3326 difference is @code{SORT_BY_ALIGNMENT} will sort sections into
3327 ascending order by alignment before placing them in the output file.
3330 @code{SORT} is an alias for @code{SORT_BY_NAME}.
3332 When there are nested section sorting commands in linker script, there
3333 can be at most 1 level of nesting for section sorting commands.
3337 @code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
3338 It will sort the input sections by name first, then by alignment if 2
3339 sections have the same name.
3341 @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
3342 It will sort the input sections by alignment first, then by name if 2
3343 sections have the same alignment.
3345 @code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
3346 treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
3348 @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
3349 is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
3351 All other nested section sorting commands are invalid.
3354 When both command line section sorting option and linker script
3355 section sorting command are used, section sorting command always
3356 takes precedence over the command line option.
3358 If the section sorting command in linker script isn't nested, the
3359 command line option will make the section sorting command to be
3360 treated as nested sorting command.
3364 @code{SORT_BY_NAME} (wildcard section pattern ) with
3365 @option{--sort-sections alignment} is equivalent to
3366 @code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
3368 @code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
3369 @option{--sort-section name} is equivalent to
3370 @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
3373 If the section sorting command in linker script is nested, the
3374 command line option will be ignored.
3376 If you ever get confused about where input sections are going, use the
3377 @samp{-M} linker option to generate a map file. The map file shows
3378 precisely how input sections are mapped to output sections.
3380 This example shows how wildcard patterns might be used to partition
3381 files. This linker script directs the linker to place all @samp{.text}
3382 sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
3383 The linker will place the @samp{.data} section from all files beginning
3384 with an upper case character in @samp{.DATA}; for all other files, the
3385 linker will place the @samp{.data} section in @samp{.data}.
3389 .text : @{ *(.text) @}
3390 .DATA : @{ [A-Z]*(.data) @}
3391 .data : @{ *(.data) @}
3392 .bss : @{ *(.bss) @}
3397 @node Input Section Common
3398 @subsubsection Input Section for Common Symbols
3399 @cindex common symbol placement
3400 @cindex uninitialized data placement
3401 A special notation is needed for common symbols, because in many object
3402 file formats common symbols do not have a particular input section. The
3403 linker treats common symbols as though they are in an input section
3404 named @samp{COMMON}.
3406 You may use file names with the @samp{COMMON} section just as with any
3407 other input sections. You can use this to place common symbols from a
3408 particular input file in one section while common symbols from other
3409 input files are placed in another section.
3411 In most cases, common symbols in input files will be placed in the
3412 @samp{.bss} section in the output file. For example:
3414 .bss @{ *(.bss) *(COMMON) @}
3417 @cindex scommon section
3418 @cindex small common symbols
3419 Some object file formats have more than one type of common symbol. For
3420 example, the MIPS ELF object file format distinguishes standard common
3421 symbols and small common symbols. In this case, the linker will use a
3422 different special section name for other types of common symbols. In
3423 the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
3424 symbols and @samp{.scommon} for small common symbols. This permits you
3425 to map the different types of common symbols into memory at different
3429 You will sometimes see @samp{[COMMON]} in old linker scripts. This
3430 notation is now considered obsolete. It is equivalent to
3433 @node Input Section Keep
3434 @subsubsection Input Section and Garbage Collection
3436 @cindex garbage collection
3437 When link-time garbage collection is in use (@samp{--gc-sections}),
3438 it is often useful to mark sections that should not be eliminated.
3439 This is accomplished by surrounding an input section's wildcard entry
3440 with @code{KEEP()}, as in @code{KEEP(*(.init))} or
3441 @code{KEEP(SORT_BY_NAME(*)(.ctors))}.
3443 @node Input Section Example
3444 @subsubsection Input Section Example
3445 The following example is a complete linker script. It tells the linker
3446 to read all of the sections from file @file{all.o} and place them at the
3447 start of output section @samp{outputa} which starts at location
3448 @samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
3449 follows immediately, in the same output section. All of section
3450 @samp{.input2} from @file{foo.o} goes into output section
3451 @samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
3452 All of the remaining @samp{.input1} and @samp{.input2} sections from any
3453 files are written to output section @samp{outputc}.
3481 @node Output Section Data
3482 @subsection Output Section Data
3484 @cindex section data
3485 @cindex output section data
3486 @kindex BYTE(@var{expression})
3487 @kindex SHORT(@var{expression})
3488 @kindex LONG(@var{expression})
3489 @kindex QUAD(@var{expression})
3490 @kindex SQUAD(@var{expression})
3491 You can include explicit bytes of data in an output section by using
3492 @code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
3493 an output section command. Each keyword is followed by an expression in
3494 parentheses providing the value to store (@pxref{Expressions}). The
3495 value of the expression is stored at the current value of the location
3498 The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
3499 store one, two, four, and eight bytes (respectively). After storing the
3500 bytes, the location counter is incremented by the number of bytes
3503 For example, this will store the byte 1 followed by the four byte value
3504 of the symbol @samp{addr}:
3510 When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
3511 same; they both store an 8 byte, or 64 bit, value. When both host and
3512 target are 32 bits, an expression is computed as 32 bits. In this case
3513 @code{QUAD} stores a 32 bit value zero extended to 64 bits, and
3514 @code{SQUAD} stores a 32 bit value sign extended to 64 bits.
3516 If the object file format of the output file has an explicit endianness,
3517 which is the normal case, the value will be stored in that endianness.
3518 When the object file format does not have an explicit endianness, as is
3519 true of, for example, S-records, the value will be stored in the
3520 endianness of the first input object file.
3522 Note---these commands only work inside a section description and not
3523 between them, so the following will produce an error from the linker:
3525 SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
3527 whereas this will work:
3529 SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
3532 @kindex FILL(@var{expression})
3533 @cindex holes, filling
3534 @cindex unspecified memory
3535 You may use the @code{FILL} command to set the fill pattern for the
3536 current section. It is followed by an expression in parentheses. Any
3537 otherwise unspecified regions of memory within the section (for example,
3538 gaps left due to the required alignment of input sections) are filled
3539 with the value of the expression, repeated as
3540 necessary. A @code{FILL} statement covers memory locations after the
3541 point at which it occurs in the section definition; by including more
3542 than one @code{FILL} statement, you can have different fill patterns in
3543 different parts of an output section.
3545 This example shows how to fill unspecified regions of memory with the
3551 The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
3552 section attribute, but it only affects the
3553 part of the section following the @code{FILL} command, rather than the
3554 entire section. If both are used, the @code{FILL} command takes
3555 precedence. @xref{Output Section Fill}, for details on the fill
3558 @node Output Section Keywords
3559 @subsection Output Section Keywords
3560 There are a couple of keywords which can appear as output section
3564 @kindex CREATE_OBJECT_SYMBOLS
3565 @cindex input filename symbols
3566 @cindex filename symbols
3567 @item CREATE_OBJECT_SYMBOLS
3568 The command tells the linker to create a symbol for each input file.
3569 The name of each symbol will be the name of the corresponding input
3570 file. The section of each symbol will be the output section in which
3571 the @code{CREATE_OBJECT_SYMBOLS} command appears.
3573 This is conventional for the a.out object file format. It is not
3574 normally used for any other object file format.
3576 @kindex CONSTRUCTORS
3577 @cindex C++ constructors, arranging in link
3578 @cindex constructors, arranging in link
3580 When linking using the a.out object file format, the linker uses an
3581 unusual set construct to support C++ global constructors and
3582 destructors. When linking object file formats which do not support
3583 arbitrary sections, such as ECOFF and XCOFF, the linker will
3584 automatically recognize C++ global constructors and destructors by name.
3585 For these object file formats, the @code{CONSTRUCTORS} command tells the
3586 linker to place constructor information in the output section where the
3587 @code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
3588 ignored for other object file formats.
3590 The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
3591 constructors, and the symbol @w{@code{__CTOR_END__}} marks the end.
3592 Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark
3593 the start and end of the global destructors. The
3594 first word in the list is the number of entries, followed by the address
3595 of each constructor or destructor, followed by a zero word. The
3596 compiler must arrange to actually run the code. For these object file
3597 formats @sc{gnu} C++ normally calls constructors from a subroutine
3598 @code{__main}; a call to @code{__main} is automatically inserted into
3599 the startup code for @code{main}. @sc{gnu} C++ normally runs
3600 destructors either by using @code{atexit}, or directly from the function
3603 For object file formats such as @code{COFF} or @code{ELF} which support
3604 arbitrary section names, @sc{gnu} C++ will normally arrange to put the
3605 addresses of global constructors and destructors into the @code{.ctors}
3606 and @code{.dtors} sections. Placing the following sequence into your
3607 linker script will build the sort of table which the @sc{gnu} C++
3608 runtime code expects to see.
3612 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
3617 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
3623 If you are using the @sc{gnu} C++ support for initialization priority,
3624 which provides some control over the order in which global constructors
3625 are run, you must sort the constructors at link time to ensure that they
3626 are executed in the correct order. When using the @code{CONSTRUCTORS}
3627 command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead. When using the
3628 @code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
3629 @samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and
3632 Normally the compiler and linker will handle these issues automatically,
3633 and you will not need to concern yourself with them. However, you may
3634 need to consider this if you are using C++ and writing your own linker
3639 @node Output Section Discarding
3640 @subsection Output Section Discarding
3641 @cindex discarding sections
3642 @cindex sections, discarding
3643 @cindex removing sections
3644 The linker will not create output section which do not have any
3645 contents. This is for convenience when referring to input sections that
3646 may or may not be present in any of the input files. For example:
3651 will only create a @samp{.foo} section in the output file if there is a
3652 @samp{.foo} section in at least one input file.
3654 If you use anything other than an input section description as an output
3655 section command, such as a symbol assignment, then the output section
3656 will always be created, even if there are no matching input sections.
3659 The special output section name @samp{/DISCARD/} may be used to discard
3660 input sections. Any input sections which are assigned to an output
3661 section named @samp{/DISCARD/} are not included in the output file.
3663 @node Output Section Attributes
3664 @subsection Output Section Attributes
3665 @cindex output section attributes
3666 We showed above that the full description of an output section looked
3670 @var{section} [@var{address}] [(@var{type})] :
3671 [AT(@var{lma})] [ALIGN(@var{section_align})] [SUBALIGN(@var{subsection_align})]
3673 @var{output-section-command}
3674 @var{output-section-command}
3676 @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
3679 We've already described @var{section}, @var{address}, and
3680 @var{output-section-command}. In this section we will describe the
3681 remaining section attributes.
3684 * Output Section Type:: Output section type
3685 * Output Section LMA:: Output section LMA
3686 * Forced Output Alignment:: Forced Output Alignment
3687 * Forced Input Alignment:: Forced Input Alignment
3688 * Output Section Region:: Output section region
3689 * Output Section Phdr:: Output section phdr
3690 * Output Section Fill:: Output section fill
3693 @node Output Section Type
3694 @subsubsection Output Section Type
3695 Each output section may have a type. The type is a keyword in
3696 parentheses. The following types are defined:
3700 The section should be marked as not loadable, so that it will not be
3701 loaded into memory when the program is run.
3706 These type names are supported for backward compatibility, and are
3707 rarely used. They all have the same effect: the section should be
3708 marked as not allocatable, so that no memory is allocated for the
3709 section when the program is run.
3713 @cindex prevent unnecessary loading
3714 @cindex loading, preventing
3715 The linker normally sets the attributes of an output section based on
3716 the input sections which map into it. You can override this by using
3717 the section type. For example, in the script sample below, the
3718 @samp{ROM} section is addressed at memory location @samp{0} and does not
3719 need to be loaded when the program is run. The contents of the
3720 @samp{ROM} section will appear in the linker output file as usual.
3724 ROM 0 (NOLOAD) : @{ @dots{} @}
3730 @node Output Section LMA
3731 @subsubsection Output Section LMA
3732 @kindex AT>@var{lma_region}
3733 @kindex AT(@var{lma})
3734 @cindex load address
3735 @cindex section load address
3736 Every section has a virtual address (VMA) and a load address (LMA); see
3737 @ref{Basic Script Concepts}. The address expression which may appear in
3738 an output section description sets the VMA (@pxref{Output Section
3741 The linker will normally set the LMA equal to the VMA. You can change
3742 that by using the @code{AT} keyword. The expression @var{lma} that
3743 follows the @code{AT} keyword specifies the load address of the
3746 Alternatively, with @samp{AT>@var{lma_region}} expression, you may
3747 specify a memory region for the section's load address. @xref{MEMORY}.
3748 Note that if the section has not had a VMA assigned to it then the
3749 linker will use the @var{lma_region} as the VMA region as well.
3750 @xref{Output Section Region}.
3752 @cindex ROM initialized data
3753 @cindex initialized data in ROM
3754 This feature is designed to make it easy to build a ROM image. For
3755 example, the following linker script creates three output sections: one
3756 called @samp{.text}, which starts at @code{0x1000}, one called
3757 @samp{.mdata}, which is loaded at the end of the @samp{.text} section
3758 even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
3759 uninitialized data at address @code{0x3000}. The symbol @code{_data} is
3760 defined with the value @code{0x2000}, which shows that the location
3761 counter holds the VMA value, not the LMA value.
3767 .text 0x1000 : @{ *(.text) _etext = . ; @}
3769 AT ( ADDR (.text) + SIZEOF (.text) )
3770 @{ _data = . ; *(.data); _edata = . ; @}
3772 @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
3777 The run-time initialization code for use with a program generated with
3778 this linker script would include something like the following, to copy
3779 the initialized data from the ROM image to its runtime address. Notice
3780 how this code takes advantage of the symbols defined by the linker
3785 extern char _etext, _data, _edata, _bstart, _bend;
3786 char *src = &_etext;
3789 /* ROM has data at end of text; copy it. */
3790 while (dst < &_edata) @{
3795 for (dst = &_bstart; dst< &_bend; dst++)
3800 @node Forced Output Alignment
3801 @subsubsection Forced Output Alignment
3802 @kindex ALIGN(@var{section_align})
3803 @cindex forcing output section alignment
3804 @cindex output section alignment
3805 You can increase an output section's alignment by using ALIGN.
3807 @node Forced Input Alignment
3808 @subsubsection Forced Input Alignment
3809 @kindex SUBALIGN(@var{subsection_align})
3810 @cindex forcing input section alignment
3811 @cindex input section alignment
3812 You can force input section alignment within an output section by using
3813 SUBALIGN. The value specified overrides any alignment given by input
3814 sections, whether larger or smaller.
3816 @node Output Section Region
3817 @subsubsection Output Section Region
3818 @kindex >@var{region}
3819 @cindex section, assigning to memory region
3820 @cindex memory regions and sections
3821 You can assign a section to a previously defined region of memory by
3822 using @samp{>@var{region}}. @xref{MEMORY}.
3824 Here is a simple example:
3827 MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
3828 SECTIONS @{ ROM : @{ *(.text) @} >rom @}
3832 @node Output Section Phdr
3833 @subsubsection Output Section Phdr
3835 @cindex section, assigning to program header
3836 @cindex program headers and sections
3837 You can assign a section to a previously defined program segment by
3838 using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
3839 one or more segments, then all subsequent allocated sections will be
3840 assigned to those segments as well, unless they use an explicitly
3841 @code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
3842 linker to not put the section in any segment at all.
3844 Here is a simple example:
3847 PHDRS @{ text PT_LOAD ; @}
3848 SECTIONS @{ .text : @{ *(.text) @} :text @}
3852 @node Output Section Fill
3853 @subsubsection Output Section Fill
3854 @kindex =@var{fillexp}
3855 @cindex section fill pattern
3856 @cindex fill pattern, entire section
3857 You can set the fill pattern for an entire section by using
3858 @samp{=@var{fillexp}}. @var{fillexp} is an expression
3859 (@pxref{Expressions}). Any otherwise unspecified regions of memory
3860 within the output section (for example, gaps left due to the required
3861 alignment of input sections) will be filled with the value, repeated as
3862 necessary. If the fill expression is a simple hex number, ie. a string
3863 of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
3864 an arbitrarily long sequence of hex digits can be used to specify the
3865 fill pattern; Leading zeros become part of the pattern too. For all
3866 other cases, including extra parentheses or a unary @code{+}, the fill
3867 pattern is the four least significant bytes of the value of the
3868 expression. In all cases, the number is big-endian.
3870 You can also change the fill value with a @code{FILL} command in the
3871 output section commands; (@pxref{Output Section Data}).
3873 Here is a simple example:
3876 SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
3880 @node Overlay Description
3881 @subsection Overlay Description
3884 An overlay description provides an easy way to describe sections which
3885 are to be loaded as part of a single memory image but are to be run at
3886 the same memory address. At run time, some sort of overlay manager will
3887 copy the overlaid sections in and out of the runtime memory address as
3888 required, perhaps by simply manipulating addressing bits. This approach
3889 can be useful, for example, when a certain region of memory is faster
3892 Overlays are described using the @code{OVERLAY} command. The
3893 @code{OVERLAY} command is used within a @code{SECTIONS} command, like an
3894 output section description. The full syntax of the @code{OVERLAY}
3895 command is as follows:
3898 OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
3902 @var{output-section-command}
3903 @var{output-section-command}
3905 @} [:@var{phdr}@dots{}] [=@var{fill}]
3908 @var{output-section-command}
3909 @var{output-section-command}
3911 @} [:@var{phdr}@dots{}] [=@var{fill}]
3913 @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
3917 Everything is optional except @code{OVERLAY} (a keyword), and each
3918 section must have a name (@var{secname1} and @var{secname2} above). The
3919 section definitions within the @code{OVERLAY} construct are identical to
3920 those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
3921 except that no addresses and no memory regions may be defined for
3922 sections within an @code{OVERLAY}.
3924 The sections are all defined with the same starting address. The load
3925 addresses of the sections are arranged such that they are consecutive in
3926 memory starting at the load address used for the @code{OVERLAY} as a
3927 whole (as with normal section definitions, the load address is optional,
3928 and defaults to the start address; the start address is also optional,
3929 and defaults to the current value of the location counter).
3931 If the @code{NOCROSSREFS} keyword is used, and there any references
3932 among the sections, the linker will report an error. Since the sections
3933 all run at the same address, it normally does not make sense for one
3934 section to refer directly to another. @xref{Miscellaneous Commands,
3937 For each section within the @code{OVERLAY}, the linker automatically
3938 defines two symbols. The symbol @code{__load_start_@var{secname}} is
3939 defined as the starting load address of the section. The symbol
3940 @code{__load_stop_@var{secname}} is defined as the final load address of
3941 the section. Any characters within @var{secname} which are not legal
3942 within C identifiers are removed. C (or assembler) code may use these
3943 symbols to move the overlaid sections around as necessary.
3945 At the end of the overlay, the value of the location counter is set to
3946 the start address of the overlay plus the size of the largest section.
3948 Here is an example. Remember that this would appear inside a
3949 @code{SECTIONS} construct.
3952 OVERLAY 0x1000 : AT (0x4000)
3954 .text0 @{ o1/*.o(.text) @}
3955 .text1 @{ o2/*.o(.text) @}
3960 This will define both @samp{.text0} and @samp{.text1} to start at
3961 address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
3962 @samp{.text1} will be loaded immediately after @samp{.text0}. The
3963 following symbols will be defined: @code{__load_start_text0},
3964 @code{__load_stop_text0}, @code{__load_start_text1},
3965 @code{__load_stop_text1}.
3967 C code to copy overlay @code{.text1} into the overlay area might look
3972 extern char __load_start_text1, __load_stop_text1;
3973 memcpy ((char *) 0x1000, &__load_start_text1,
3974 &__load_stop_text1 - &__load_start_text1);
3978 Note that the @code{OVERLAY} command is just syntactic sugar, since
3979 everything it does can be done using the more basic commands. The above
3980 example could have been written identically as follows.
3984 .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
3985 __load_start_text0 = LOADADDR (.text0);
3986 __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
3987 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
3988 __load_start_text1 = LOADADDR (.text1);
3989 __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
3990 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
3995 @section MEMORY Command
3997 @cindex memory regions
3998 @cindex regions of memory
3999 @cindex allocating memory
4000 @cindex discontinuous memory
4001 The linker's default configuration permits allocation of all available
4002 memory. You can override this by using the @code{MEMORY} command.
4004 The @code{MEMORY} command describes the location and size of blocks of
4005 memory in the target. You can use it to describe which memory regions
4006 may be used by the linker, and which memory regions it must avoid. You
4007 can then assign sections to particular memory regions. The linker will
4008 set section addresses based on the memory regions, and will warn about
4009 regions that become too full. The linker will not shuffle sections
4010 around to fit into the available regions.
4012 A linker script may contain at most one use of the @code{MEMORY}
4013 command. However, you can define as many blocks of memory within it as
4014 you wish. The syntax is:
4019 @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
4025 The @var{name} is a name used in the linker script to refer to the
4026 region. The region name has no meaning outside of the linker script.
4027 Region names are stored in a separate name space, and will not conflict
4028 with symbol names, file names, or section names. Each memory region
4029 must have a distinct name.
4031 @cindex memory region attributes
4032 The @var{attr} string is an optional list of attributes that specify
4033 whether to use a particular memory region for an input section which is
4034 not explicitly mapped in the linker script. As described in
4035 @ref{SECTIONS}, if you do not specify an output section for some input
4036 section, the linker will create an output section with the same name as
4037 the input section. If you define region attributes, the linker will use
4038 them to select the memory region for the output section that it creates.
4040 The @var{attr} string must consist only of the following characters:
4055 Invert the sense of any of the preceding attributes
4058 If a unmapped section matches any of the listed attributes other than
4059 @samp{!}, it will be placed in the memory region. The @samp{!}
4060 attribute reverses this test, so that an unmapped section will be placed
4061 in the memory region only if it does not match any of the listed
4067 The @var{origin} is an numerical expression for the start address of
4068 the memory region. The expression must evaluate to a constant and it
4069 cannot involve any symbols. The keyword @code{ORIGIN} may be
4070 abbreviated to @code{org} or @code{o} (but not, for example,
4076 The @var{len} is an expression for the size in bytes of the memory
4077 region. As with the @var{origin} expression, the expression must
4078 be numerical only and must evaluate to a constant. The keyword
4079 @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
4081 In the following example, we specify that there are two memory regions
4082 available for allocation: one starting at @samp{0} for 256 kilobytes,
4083 and the other starting at @samp{0x40000000} for four megabytes. The
4084 linker will place into the @samp{rom} memory region every section which
4085 is not explicitly mapped into a memory region, and is either read-only
4086 or executable. The linker will place other sections which are not
4087 explicitly mapped into a memory region into the @samp{ram} memory
4094 rom (rx) : ORIGIN = 0, LENGTH = 256K
4095 ram (!rx) : org = 0x40000000, l = 4M
4100 Once you define a memory region, you can direct the linker to place
4101 specific output sections into that memory region by using the
4102 @samp{>@var{region}} output section attribute. For example, if you have
4103 a memory region named @samp{mem}, you would use @samp{>mem} in the
4104 output section definition. @xref{Output Section Region}. If no address
4105 was specified for the output section, the linker will set the address to
4106 the next available address within the memory region. If the combined
4107 output sections directed to a memory region are too large for the
4108 region, the linker will issue an error message.
4110 It is possible to access the origin and length of a memory in an
4111 expression via the @code{ORIGIN(@var{memory})} and
4112 @code{LENGTH(@var{memory})} functions:
4116 _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
4121 @section PHDRS Command
4123 @cindex program headers
4124 @cindex ELF program headers
4125 @cindex program segments
4126 @cindex segments, ELF
4127 The ELF object file format uses @dfn{program headers}, also knows as
4128 @dfn{segments}. The program headers describe how the program should be
4129 loaded into memory. You can print them out by using the @code{objdump}
4130 program with the @samp{-p} option.
4132 When you run an ELF program on a native ELF system, the system loader
4133 reads the program headers in order to figure out how to load the
4134 program. This will only work if the program headers are set correctly.
4135 This manual does not describe the details of how the system loader
4136 interprets program headers; for more information, see the ELF ABI.
4138 The linker will create reasonable program headers by default. However,
4139 in some cases, you may need to specify the program headers more
4140 precisely. You may use the @code{PHDRS} command for this purpose. When
4141 the linker sees the @code{PHDRS} command in the linker script, it will
4142 not create any program headers other than the ones specified.
4144 The linker only pays attention to the @code{PHDRS} command when
4145 generating an ELF output file. In other cases, the linker will simply
4146 ignore @code{PHDRS}.
4148 This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
4149 @code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
4155 @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
4156 [ FLAGS ( @var{flags} ) ] ;
4161 The @var{name} is used only for reference in the @code{SECTIONS} command
4162 of the linker script. It is not put into the output file. Program
4163 header names are stored in a separate name space, and will not conflict
4164 with symbol names, file names, or section names. Each program header
4165 must have a distinct name.
4167 Certain program header types describe segments of memory which the
4168 system loader will load from the file. In the linker script, you
4169 specify the contents of these segments by placing allocatable output
4170 sections in the segments. You use the @samp{:@var{phdr}} output section
4171 attribute to place a section in a particular segment. @xref{Output
4174 It is normal to put certain sections in more than one segment. This
4175 merely implies that one segment of memory contains another. You may
4176 repeat @samp{:@var{phdr}}, using it once for each segment which should
4177 contain the section.
4179 If you place a section in one or more segments using @samp{:@var{phdr}},
4180 then the linker will place all subsequent allocatable sections which do
4181 not specify @samp{:@var{phdr}} in the same segments. This is for
4182 convenience, since generally a whole set of contiguous sections will be
4183 placed in a single segment. You can use @code{:NONE} to override the
4184 default segment and tell the linker to not put the section in any
4189 You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after
4190 the program header type to further describe the contents of the segment.
4191 The @code{FILEHDR} keyword means that the segment should include the ELF
4192 file header. The @code{PHDRS} keyword means that the segment should
4193 include the ELF program headers themselves.
4195 The @var{type} may be one of the following. The numbers indicate the
4196 value of the keyword.
4199 @item @code{PT_NULL} (0)
4200 Indicates an unused program header.
4202 @item @code{PT_LOAD} (1)
4203 Indicates that this program header describes a segment to be loaded from
4206 @item @code{PT_DYNAMIC} (2)
4207 Indicates a segment where dynamic linking information can be found.
4209 @item @code{PT_INTERP} (3)
4210 Indicates a segment where the name of the program interpreter may be
4213 @item @code{PT_NOTE} (4)
4214 Indicates a segment holding note information.
4216 @item @code{PT_SHLIB} (5)
4217 A reserved program header type, defined but not specified by the ELF
4220 @item @code{PT_PHDR} (6)
4221 Indicates a segment where the program headers may be found.
4223 @item @var{expression}
4224 An expression giving the numeric type of the program header. This may
4225 be used for types not defined above.
4228 You can specify that a segment should be loaded at a particular address
4229 in memory by using an @code{AT} expression. This is identical to the
4230 @code{AT} command used as an output section attribute (@pxref{Output
4231 Section LMA}). The @code{AT} command for a program header overrides the
4232 output section attribute.
4234 The linker will normally set the segment flags based on the sections
4235 which comprise the segment. You may use the @code{FLAGS} keyword to
4236 explicitly specify the segment flags. The value of @var{flags} must be
4237 an integer. It is used to set the @code{p_flags} field of the program
4240 Here is an example of @code{PHDRS}. This shows a typical set of program
4241 headers used on a native ELF system.
4247 headers PT_PHDR PHDRS ;
4249 text PT_LOAD FILEHDR PHDRS ;
4251 dynamic PT_DYNAMIC ;
4257 .interp : @{ *(.interp) @} :text :interp
4258 .text : @{ *(.text) @} :text
4259 .rodata : @{ *(.rodata) @} /* defaults to :text */
4261 . = . + 0x1000; /* move to a new page in memory */
4262 .data : @{ *(.data) @} :data
4263 .dynamic : @{ *(.dynamic) @} :data :dynamic
4270 @section VERSION Command
4271 @kindex VERSION @{script text@}
4272 @cindex symbol versions
4273 @cindex version script
4274 @cindex versions of symbols
4275 The linker supports symbol versions when using ELF. Symbol versions are
4276 only useful when using shared libraries. The dynamic linker can use
4277 symbol versions to select a specific version of a function when it runs
4278 a program that may have been linked against an earlier version of the
4281 You can include a version script directly in the main linker script, or
4282 you can supply the version script as an implicit linker script. You can
4283 also use the @samp{--version-script} linker option.
4285 The syntax of the @code{VERSION} command is simply
4287 VERSION @{ version-script-commands @}
4290 The format of the version script commands is identical to that used by
4291 Sun's linker in Solaris 2.5. The version script defines a tree of
4292 version nodes. You specify the node names and interdependencies in the
4293 version script. You can specify which symbols are bound to which
4294 version nodes, and you can reduce a specified set of symbols to local
4295 scope so that they are not globally visible outside of the shared
4298 The easiest way to demonstrate the version script language is with a few
4319 "int f(int, double)";
4324 This example version script defines three version nodes. The first
4325 version node defined is @samp{VERS_1.1}; it has no other dependencies.
4326 The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
4327 a number of symbols to local scope so that they are not visible outside
4328 of the shared library; this is done using wildcard patterns, so that any
4329 symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
4330 is matched. The wildcard patterns available are the same as those used
4331 in the shell when matching filenames (also known as ``globbing'').
4332 However, if you specify the symbol name inside double quotes, then the
4333 name is treated as literal, rather than as a glob pattern.
4335 Next, the version script defines node @samp{VERS_1.2}. This node
4336 depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
4337 to the version node @samp{VERS_1.2}.
4339 Finally, the version script defines node @samp{VERS_2.0}. This node
4340 depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
4341 and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
4343 When the linker finds a symbol defined in a library which is not
4344 specifically bound to a version node, it will effectively bind it to an
4345 unspecified base version of the library. You can bind all otherwise
4346 unspecified symbols to a given version node by using @samp{global: *;}
4347 somewhere in the version script.
4349 The names of the version nodes have no specific meaning other than what
4350 they might suggest to the person reading them. The @samp{2.0} version
4351 could just as well have appeared in between @samp{1.1} and @samp{1.2}.
4352 However, this would be a confusing way to write a version script.
4354 Node name can be omited, provided it is the only version node
4355 in the version script. Such version script doesn't assign any versions to
4356 symbols, only selects which symbols will be globally visible out and which
4360 @{ global: foo; bar; local: *; @};
4363 When you link an application against a shared library that has versioned
4364 symbols, the application itself knows which version of each symbol it
4365 requires, and it also knows which version nodes it needs from each
4366 shared library it is linked against. Thus at runtime, the dynamic
4367 loader can make a quick check to make sure that the libraries you have
4368 linked against do in fact supply all of the version nodes that the
4369 application will need to resolve all of the dynamic symbols. In this
4370 way it is possible for the dynamic linker to know with certainty that
4371 all external symbols that it needs will be resolvable without having to
4372 search for each symbol reference.
4374 The symbol versioning is in effect a much more sophisticated way of
4375 doing minor version checking that SunOS does. The fundamental problem
4376 that is being addressed here is that typically references to external
4377 functions are bound on an as-needed basis, and are not all bound when
4378 the application starts up. If a shared library is out of date, a
4379 required interface may be missing; when the application tries to use
4380 that interface, it may suddenly and unexpectedly fail. With symbol
4381 versioning, the user will get a warning when they start their program if
4382 the libraries being used with the application are too old.
4384 There are several GNU extensions to Sun's versioning approach. The
4385 first of these is the ability to bind a symbol to a version node in the
4386 source file where the symbol is defined instead of in the versioning
4387 script. This was done mainly to reduce the burden on the library
4388 maintainer. You can do this by putting something like:
4390 __asm__(".symver original_foo,foo@@VERS_1.1");
4393 in the C source file. This renames the function @samp{original_foo} to
4394 be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
4395 The @samp{local:} directive can be used to prevent the symbol
4396 @samp{original_foo} from being exported. A @samp{.symver} directive
4397 takes precedence over a version script.
4399 The second GNU extension is to allow multiple versions of the same
4400 function to appear in a given shared library. In this way you can make
4401 an incompatible change to an interface without increasing the major
4402 version number of the shared library, while still allowing applications
4403 linked against the old interface to continue to function.
4405 To do this, you must use multiple @samp{.symver} directives in the
4406 source file. Here is an example:
4409 __asm__(".symver original_foo,foo@@");
4410 __asm__(".symver old_foo,foo@@VERS_1.1");
4411 __asm__(".symver old_foo1,foo@@VERS_1.2");
4412 __asm__(".symver new_foo,foo@@@@VERS_2.0");
4415 In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
4416 unspecified base version of the symbol. The source file that contains this
4417 example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
4418 @samp{old_foo1}, and @samp{new_foo}.
4420 When you have multiple definitions of a given symbol, there needs to be
4421 some way to specify a default version to which external references to
4422 this symbol will be bound. You can do this with the
4423 @samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
4424 declare one version of a symbol as the default in this manner; otherwise
4425 you would effectively have multiple definitions of the same symbol.
4427 If you wish to bind a reference to a specific version of the symbol
4428 within the shared library, you can use the aliases of convenience
4429 (i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to
4430 specifically bind to an external version of the function in question.
4432 You can also specify the language in the version script:
4435 VERSION extern "lang" @{ version-script-commands @}
4438 The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
4439 The linker will iterate over the list of symbols at the link time and
4440 demangle them according to @samp{lang} before matching them to the
4441 patterns specified in @samp{version-script-commands}.
4443 Demangled names may contains spaces and other special characters. As
4444 described above, you can use a glob pattern to match demangled names,
4445 or you can use a double-quoted string to match the string exactly. In
4446 the latter case, be aware that minor differences (such as differing
4447 whitespace) between the version script and the demangler output will
4448 cause a mismatch. As the exact string generated by the demangler
4449 might change in the future, even if the mangled name does not, you
4450 should check that all of your version directives are behaving as you
4451 expect when you upgrade.
4454 @section Expressions in Linker Scripts
4457 The syntax for expressions in the linker script language is identical to
4458 that of C expressions. All expressions are evaluated as integers. All
4459 expressions are evaluated in the same size, which is 32 bits if both the
4460 host and target are 32 bits, and is otherwise 64 bits.
4462 You can use and set symbol values in expressions.
4464 The linker defines several special purpose builtin functions for use in
4468 * Constants:: Constants
4469 * Symbols:: Symbol Names
4470 * Orphan Sections:: Orphan Sections
4471 * Location Counter:: The Location Counter
4472 * Operators:: Operators
4473 * Evaluation:: Evaluation
4474 * Expression Section:: The Section of an Expression
4475 * Builtin Functions:: Builtin Functions
4479 @subsection Constants
4480 @cindex integer notation
4481 @cindex constants in linker scripts
4482 All constants are integers.
4484 As in C, the linker considers an integer beginning with @samp{0} to be
4485 octal, and an integer beginning with @samp{0x} or @samp{0X} to be
4486 hexadecimal. The linker considers other integers to be decimal.
4488 @cindex scaled integers
4489 @cindex K and M integer suffixes
4490 @cindex M and K integer suffixes
4491 @cindex suffixes for integers
4492 @cindex integer suffixes
4493 In addition, you can use the suffixes @code{K} and @code{M} to scale a
4497 @c END TEXI2ROFF-KILL
4498 @code{1024} or @code{1024*1024}
4502 ${\rm 1024}$ or ${\rm 1024}^2$
4504 @c END TEXI2ROFF-KILL
4505 respectively. For example, the following all refer to the same quantity:
4513 @subsection Symbol Names
4514 @cindex symbol names
4516 @cindex quoted symbol names
4518 Unless quoted, symbol names start with a letter, underscore, or period
4519 and may include letters, digits, underscores, periods, and hyphens.
4520 Unquoted symbol names must not conflict with any keywords. You can
4521 specify a symbol which contains odd characters or has the same name as a
4522 keyword by surrounding the symbol name in double quotes:
4525 "with a space" = "also with a space" + 10;
4528 Since symbols can contain many non-alphabetic characters, it is safest
4529 to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
4530 whereas @samp{A - B} is an expression involving subtraction.
4532 @node Orphan Sections
4533 @subsection Orphan Sections
4535 Orphan sections are sections present in the input files which
4536 are not explicitly placed into the output file by the linker
4537 script. The linker will still copy these sections into the
4538 output file, but it has to guess as to where they should be
4539 placed. The linker uses a simple heuristic to do this. It
4540 attempts to place orphan sections after non-orphan sections of the
4541 same attribute, such as code vs data, loadable vs non-loadable, etc.
4542 If there is not enough room to do this then it places
4543 at the end of the file.
4545 For ELF targets, the attribute of the section includes section type as
4546 well as section flag.
4548 @node Location Counter
4549 @subsection The Location Counter
4552 @cindex location counter
4553 @cindex current output location
4554 The special linker variable @dfn{dot} @samp{.} always contains the
4555 current output location counter. Since the @code{.} always refers to a
4556 location in an output section, it may only appear in an expression
4557 within a @code{SECTIONS} command. The @code{.} symbol may appear
4558 anywhere that an ordinary symbol is allowed in an expression.
4561 Assigning a value to @code{.} will cause the location counter to be
4562 moved. This may be used to create holes in the output section. The
4563 location counter may never be moved backwards.
4579 In the previous example, the @samp{.text} section from @file{file1} is
4580 located at the beginning of the output section @samp{output}. It is
4581 followed by a 1000 byte gap. Then the @samp{.text} section from
4582 @file{file2} appears, also with a 1000 byte gap following before the
4583 @samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
4584 specifies what data to write in the gaps (@pxref{Output Section Fill}).
4586 @cindex dot inside sections
4587 Note: @code{.} actually refers to the byte offset from the start of the
4588 current containing object. Normally this is the @code{SECTIONS}
4589 statement, whose start address is 0, hence @code{.} can be used as an
4590 absolute address. If @code{.} is used inside a section description
4591 however, it refers to the byte offset from the start of that section,
4592 not an absolute address. Thus in a script like this:
4610 The @samp{.text} section will be assigned a starting address of 0x100
4611 and a size of exactly 0x200 bytes, even if there is not enough data in
4612 the @samp{.text} input sections to fill this area. (If there is too
4613 much data, an error will be produced because this would be an attempt to
4614 move @code{.} backwards). The @samp{.data} section will start at 0x500
4615 and it will have an extra 0x600 bytes worth of space after the end of
4616 the values from the @samp{.data} input sections and before the end of
4617 the @samp{.data} output section itself.
4619 @cindex dot outside sections
4620 Setting symbols to the value of the location counter outside of an
4621 output section statement can result in unexpected values if the linker
4622 needs to place orphan sections. For example, given the following:
4628 .text: @{ *(.text) @}
4632 .data: @{ *(.data) @}
4637 If the linker needs to place some input section, e.g. @code{.rodata},
4638 not mentioned in the script, it might choose to place that section
4639 between @code{.text} and @code{.data}. You might think the linker
4640 should place @code{.rodata} on the blank line in the above script, but
4641 blank lines are of no particular significance to the linker. As well,
4642 the linker doesn't associate the above symbol names with their
4643 sections. Instead, it assumes that all assignments or other
4644 statements belong to the previous output section, except for the
4645 special case of an assignment to @code{.}. I.e., the linker will
4646 place the orphan @code{.rodata} section as if the script was written
4653 .text: @{ *(.text) @}
4657 .rodata: @{ *(.rodata) @}
4658 .data: @{ *(.data) @}
4663 This may or may not be the script author's intention for the value of
4664 @code{start_of_data}. One way to influence the orphan section
4665 placement is to assign the location counter to itself, as the linker
4666 assumes that an assignment to @code{.} is setting the start address of
4667 a following output section and thus should be grouped with that
4668 section. So you could write:
4674 .text: @{ *(.text) @}
4679 .data: @{ *(.data) @}
4684 Now, the orphan @code{.rodata} section will be placed between
4685 @code{end_of_text} and @code{start_of_data}.
4689 @subsection Operators
4690 @cindex operators for arithmetic
4691 @cindex arithmetic operators
4692 @cindex precedence in expressions
4693 The linker recognizes the standard C set of arithmetic operators, with
4694 the standard bindings and precedence levels:
4697 @c END TEXI2ROFF-KILL
4699 precedence associativity Operators Notes
4705 5 left == != > < <= >=
4711 11 right &= += -= *= /= (2)
4715 (1) Prefix operators
4716 (2) @xref{Assignments}.
4720 \vskip \baselineskip
4721 %"lispnarrowing" is the extra indent used generally for smallexample
4722 \hskip\lispnarrowing\vbox{\offinterlineskip
4725 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
4726 height2pt&\omit&&\omit&&\omit&\cr
4727 &Precedence&& Associativity &&{\rm Operators}&\cr
4728 height2pt&\omit&&\omit&&\omit&\cr
4730 height2pt&\omit&&\omit&&\omit&\cr
4732 % '176 is tilde, '~' in tt font
4733 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
4734 &2&&left&&* / \%&\cr
4737 &5&&left&&== != > < <= >=&\cr
4740 &8&&left&&{\&\&}&\cr
4743 &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
4745 height2pt&\omit&&\omit&&\omit&\cr}
4750 @obeylines@parskip=0pt@parindent=0pt
4751 @dag@quad Prefix operators.
4752 @ddag@quad @xref{Assignments}.
4755 @c END TEXI2ROFF-KILL
4758 @subsection Evaluation
4759 @cindex lazy evaluation
4760 @cindex expression evaluation order
4761 The linker evaluates expressions lazily. It only computes the value of
4762 an expression when absolutely necessary.
4764 The linker needs some information, such as the value of the start
4765 address of the first section, and the origins and lengths of memory
4766 regions, in order to do any linking at all. These values are computed
4767 as soon as possible when the linker reads in the linker script.
4769 However, other values (such as symbol values) are not known or needed
4770 until after storage allocation. Such values are evaluated later, when
4771 other information (such as the sizes of output sections) is available
4772 for use in the symbol assignment expression.
4774 The sizes of sections cannot be known until after allocation, so
4775 assignments dependent upon these are not performed until after
4778 Some expressions, such as those depending upon the location counter
4779 @samp{.}, must be evaluated during section allocation.
4781 If the result of an expression is required, but the value is not
4782 available, then an error results. For example, a script like the
4788 .text 9+this_isnt_constant :
4794 will cause the error message @samp{non constant expression for initial
4797 @node Expression Section
4798 @subsection The Section of an Expression
4799 @cindex expression sections
4800 @cindex absolute expressions
4801 @cindex relative expressions
4802 @cindex absolute and relocatable symbols
4803 @cindex relocatable and absolute symbols
4804 @cindex symbols, relocatable and absolute
4805 When the linker evaluates an expression, the result is either absolute
4806 or relative to some section. A relative expression is expressed as a
4807 fixed offset from the base of a section.
4809 The position of the expression within the linker script determines
4810 whether it is absolute or relative. An expression which appears within
4811 an output section definition is relative to the base of the output
4812 section. An expression which appears elsewhere will be absolute.
4814 A symbol set to a relative expression will be relocatable if you request
4815 relocatable output using the @samp{-r} option. That means that a
4816 further link operation may change the value of the symbol. The symbol's
4817 section will be the section of the relative expression.
4819 A symbol set to an absolute expression will retain the same value
4820 through any further link operation. The symbol will be absolute, and
4821 will not have any particular associated section.
4823 You can use the builtin function @code{ABSOLUTE} to force an expression
4824 to be absolute when it would otherwise be relative. For example, to
4825 create an absolute symbol set to the address of the end of the output
4826 section @samp{.data}:
4830 .data : @{ *(.data) _edata = ABSOLUTE(.); @}
4834 If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
4835 @samp{.data} section.
4837 @node Builtin Functions
4838 @subsection Builtin Functions
4839 @cindex functions in expressions
4840 The linker script language includes a number of builtin functions for
4841 use in linker script expressions.
4844 @item ABSOLUTE(@var{exp})
4845 @kindex ABSOLUTE(@var{exp})
4846 @cindex expression, absolute
4847 Return the absolute (non-relocatable, as opposed to non-negative) value
4848 of the expression @var{exp}. Primarily useful to assign an absolute
4849 value to a symbol within a section definition, where symbol values are
4850 normally section relative. @xref{Expression Section}.
4852 @item ADDR(@var{section})
4853 @kindex ADDR(@var{section})
4854 @cindex section address in expression
4855 Return the absolute address (the VMA) of the named @var{section}. Your
4856 script must previously have defined the location of that section. In
4857 the following example, @code{symbol_1} and @code{symbol_2} are assigned
4864 start_of_output_1 = ABSOLUTE(.);
4869 symbol_1 = ADDR(.output1);
4870 symbol_2 = start_of_output_1;
4876 @item ALIGN(@var{align})
4877 @itemx ALIGN(@var{exp},@var{align})
4878 @kindex ALIGN(@var{align})
4879 @kindex ALIGN(@var{exp},@var{align})
4880 @cindex round up location counter
4881 @cindex align location counter
4882 @cindex round up expression
4883 @cindex align expression
4884 Return the location counter (@code{.}) or arbitrary expression aligned
4885 to the next @var{align} boundary. The single operand @code{ALIGN}
4886 doesn't change the value of the location counter---it just does
4887 arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
4888 expression to be aligned upwards (@code{ALIGN(@var{align})} is
4889 equivalent to @code{ALIGN(., @var{align})}).
4891 Here is an example which aligns the output @code{.data} section to the
4892 next @code{0x2000} byte boundary after the preceding section and sets a
4893 variable within the section to the next @code{0x8000} boundary after the
4898 .data ALIGN(0x2000): @{
4900 variable = ALIGN(0x8000);
4906 The first use of @code{ALIGN} in this example specifies the location of
4907 a section because it is used as the optional @var{address} attribute of
4908 a section definition (@pxref{Output Section Address}). The second use
4909 of @code{ALIGN} is used to defines the value of a symbol.
4911 The builtin function @code{NEXT} is closely related to @code{ALIGN}.
4913 @item BLOCK(@var{exp})
4914 @kindex BLOCK(@var{exp})
4915 This is a synonym for @code{ALIGN}, for compatibility with older linker
4916 scripts. It is most often seen when setting the address of an output
4919 @item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
4920 @kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
4921 This is equivalent to either
4923 (ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
4927 (ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
4930 depending on whether the latter uses fewer @var{commonpagesize} sized pages
4931 for the data segment (area between the result of this expression and
4932 @code{DATA_SEGMENT_END}) than the former or not.
4933 If the latter form is used, it means @var{commonpagesize} bytes of runtime
4934 memory will be saved at the expense of up to @var{commonpagesize} wasted
4935 bytes in the on-disk file.
4937 This expression can only be used directly in @code{SECTIONS} commands, not in
4938 any output section descriptions and only once in the linker script.
4939 @var{commonpagesize} should be less or equal to @var{maxpagesize} and should
4940 be the system page size the object wants to be optimized for (while still
4941 working on system page sizes up to @var{maxpagesize}).
4946 . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
4949 @item DATA_SEGMENT_END(@var{exp})
4950 @kindex DATA_SEGMENT_END(@var{exp})
4951 This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
4952 evaluation purposes.
4955 . = DATA_SEGMENT_END(.);
4958 @item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
4959 @kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
4960 This defines the end of the @code{PT_GNU_RELRO} segment when
4961 @samp{-z relro} option is used. Second argument is returned.
4962 When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
4963 does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
4964 @var{exp} + @var{offset} is aligned to the most commonly used page
4965 boundary for particular target. If present in the linker script,
4966 it must always come in between @code{DATA_SEGMENT_ALIGN} and
4967 @code{DATA_SEGMENT_END}.
4970 . = DATA_SEGMENT_RELRO_END(24, .);
4973 @item DEFINED(@var{symbol})
4974 @kindex DEFINED(@var{symbol})
4975 @cindex symbol defaults
4976 Return 1 if @var{symbol} is in the linker global symbol table and is
4977 defined before the statement using DEFINED in the script, otherwise
4978 return 0. You can use this function to provide
4979 default values for symbols. For example, the following script fragment
4980 shows how to set a global symbol @samp{begin} to the first location in
4981 the @samp{.text} section---but if a symbol called @samp{begin} already
4982 existed, its value is preserved:
4988 begin = DEFINED(begin) ? begin : . ;
4996 @item LENGTH(@var{memory})
4997 @kindex LENGTH(@var{memory})
4998 Return the length of the memory region named @var{memory}.
5000 @item LOADADDR(@var{section})
5001 @kindex LOADADDR(@var{section})
5002 @cindex section load address in expression
5003 Return the absolute LMA of the named @var{section}. This is normally
5004 the same as @code{ADDR}, but it may be different if the @code{AT}
5005 attribute is used in the output section definition (@pxref{Output
5009 @item MAX(@var{exp1}, @var{exp2})
5010 Returns the maximum of @var{exp1} and @var{exp2}.
5013 @item MIN(@var{exp1}, @var{exp2})
5014 Returns the minimum of @var{exp1} and @var{exp2}.
5016 @item NEXT(@var{exp})
5017 @kindex NEXT(@var{exp})
5018 @cindex unallocated address, next
5019 Return the next unallocated address that is a multiple of @var{exp}.
5020 This function is closely related to @code{ALIGN(@var{exp})}; unless you
5021 use the @code{MEMORY} command to define discontinuous memory for the
5022 output file, the two functions are equivalent.
5024 @item ORIGIN(@var{memory})
5025 @kindex ORIGIN(@var{memory})
5026 Return the origin of the memory region named @var{memory}.
5028 @item SEGMENT_START(@var{segment}, @var{default})
5029 @kindex SEGMENT_START(@var{segment}, @var{default})
5030 Return the base address of the named @var{segment}. If an explicit
5031 value has been given for this segment (with a command-line @samp{-T}
5032 option) that value will be returned; otherwise the value will be
5033 @var{default}. At present, the @samp{-T} command-line option can only
5034 be used to set the base address for the ``text'', ``data'', and
5035 ``bss'' sections, but you use @code{SEGMENT_START} with any segment
5038 @item SIZEOF(@var{section})
5039 @kindex SIZEOF(@var{section})
5040 @cindex section size
5041 Return the size in bytes of the named @var{section}, if that section has
5042 been allocated. If the section has not been allocated when this is
5043 evaluated, the linker will report an error. In the following example,
5044 @code{symbol_1} and @code{symbol_2} are assigned identical values:
5053 symbol_1 = .end - .start ;
5054 symbol_2 = SIZEOF(.output);
5059 @item SIZEOF_HEADERS
5060 @itemx sizeof_headers
5061 @kindex SIZEOF_HEADERS
5063 Return the size in bytes of the output file's headers. This is
5064 information which appears at the start of the output file. You can use
5065 this number when setting the start address of the first section, if you
5066 choose, to facilitate paging.
5068 @cindex not enough room for program headers
5069 @cindex program headers, not enough room
5070 When producing an ELF output file, if the linker script uses the
5071 @code{SIZEOF_HEADERS} builtin function, the linker must compute the
5072 number of program headers before it has determined all the section
5073 addresses and sizes. If the linker later discovers that it needs
5074 additional program headers, it will report an error @samp{not enough
5075 room for program headers}. To avoid this error, you must avoid using
5076 the @code{SIZEOF_HEADERS} function, or you must rework your linker
5077 script to avoid forcing the linker to use additional program headers, or
5078 you must define the program headers yourself using the @code{PHDRS}
5079 command (@pxref{PHDRS}).
5082 @node Implicit Linker Scripts
5083 @section Implicit Linker Scripts
5084 @cindex implicit linker scripts
5085 If you specify a linker input file which the linker can not recognize as
5086 an object file or an archive file, it will try to read the file as a
5087 linker script. If the file can not be parsed as a linker script, the
5088 linker will report an error.
5090 An implicit linker script will not replace the default linker script.
5092 Typically an implicit linker script would contain only symbol
5093 assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
5096 Any input files read because of an implicit linker script will be read
5097 at the position in the command line where the implicit linker script was
5098 read. This can affect archive searching.
5101 @node Machine Dependent
5102 @chapter Machine Dependent Features
5104 @cindex machine dependencies
5105 @command{ld} has additional features on some platforms; the following
5106 sections describe them. Machines where @command{ld} has no additional
5107 functionality are not listed.
5111 * H8/300:: @command{ld} and the H8/300
5114 * i960:: @command{ld} and the Intel 960 family
5117 * ARM:: @command{ld} and the ARM family
5120 * HPPA ELF32:: @command{ld} and HPPA 32-bit ELF
5123 * MMIX:: @command{ld} and MMIX
5126 * MSP430:: @command{ld} and MSP430
5129 * M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families
5132 * PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support
5135 * PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
5138 * TI COFF:: @command{ld} and TI COFF
5141 * WIN32:: @command{ld} and WIN32 (cygwin/mingw)
5144 * Xtensa:: @command{ld} and Xtensa Processors
5155 @section @command{ld} and the H8/300
5157 @cindex H8/300 support
5158 For the H8/300, @command{ld} can perform these global optimizations when
5159 you specify the @samp{--relax} command-line option.
5162 @cindex relaxing on H8/300
5163 @item relaxing address modes
5164 @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
5165 targets are within eight bits, and turns them into eight-bit
5166 program-counter relative @code{bsr} and @code{bra} instructions,
5169 @cindex synthesizing on H8/300
5170 @item synthesizing instructions
5171 @c FIXME: specifically mov.b, or any mov instructions really?
5172 @command{ld} finds all @code{mov.b} instructions which use the
5173 sixteen-bit absolute address form, but refer to the top
5174 page of memory, and changes them to use the eight-bit address form.
5175 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
5176 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
5177 top page of memory).
5179 @item bit manipulation instructions
5180 @command{ld} finds all bit manipulation instructions like @code{band, bclr,
5181 biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
5182 which use 32 bit and 16 bit absolute address form, but refer to the top
5183 page of memory, and changes them to use the 8 bit address form.
5184 (That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into
5185 @samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
5186 the top page of memory).
5188 @item system control instructions
5189 @command{ld} finds all @code{ldc.w, stc.w} instrcutions which use the
5190 32 bit absolute address form, but refer to the top page of memory, and
5191 changes them to use 16 bit address form.
5192 (That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
5193 @samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
5194 the top page of memory).
5204 @c This stuff is pointless to say unless you're especially concerned
5205 @c with Renesas chips; don't enable it for generic case, please.
5207 @chapter @command{ld} and Other Renesas Chips
5209 @command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
5210 H8/500, and SH chips. No special features, commands, or command-line
5211 options are required for these chips.
5221 @section @command{ld} and the Intel 960 Family
5223 @cindex i960 support
5225 You can use the @samp{-A@var{architecture}} command line option to
5226 specify one of the two-letter names identifying members of the 960
5227 family; the option specifies the desired output target, and warns of any
5228 incompatible instructions in the input files. It also modifies the
5229 linker's search strategy for archive libraries, to support the use of
5230 libraries specific to each particular architecture, by including in the
5231 search loop names suffixed with the string identifying the architecture.
5233 For example, if your @command{ld} command line included @w{@samp{-ACA}} as
5234 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
5235 paths, and in any paths you specify with @samp{-L}) for a library with
5248 The first two possibilities would be considered in any event; the last
5249 two are due to the use of @w{@samp{-ACA}}.
5251 You can meaningfully use @samp{-A} more than once on a command line, since
5252 the 960 architecture family allows combination of target architectures; each
5253 use will add another pair of name variants to search for when @w{@samp{-l}}
5254 specifies a library.
5256 @cindex @option{--relax} on i960
5257 @cindex relaxing on i960
5258 @command{ld} supports the @samp{--relax} option for the i960 family. If
5259 you specify @samp{--relax}, @command{ld} finds all @code{balx} and
5260 @code{calx} instructions whose targets are within 24 bits, and turns
5261 them into 24-bit program-counter relative @code{bal} and @code{cal}
5262 instructions, respectively. @command{ld} also turns @code{cal}
5263 instructions into @code{bal} instructions when it determines that the
5264 target subroutine is a leaf routine (that is, the target subroutine does
5265 not itself call any subroutines).
5282 @node M68HC11/68HC12
5283 @section @command{ld} and the Motorola 68HC11 and 68HC12 families
5285 @cindex M68HC11 and 68HC12 support
5287 @subsection Linker Relaxation
5289 For the Motorola 68HC11, @command{ld} can perform these global
5290 optimizations when you specify the @samp{--relax} command-line option.
5293 @cindex relaxing on M68HC11
5294 @item relaxing address modes
5295 @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
5296 targets are within eight bits, and turns them into eight-bit
5297 program-counter relative @code{bsr} and @code{bra} instructions,
5300 @command{ld} also looks at all 16-bit extended addressing modes and
5301 transforms them in a direct addressing mode when the address is in
5302 page 0 (between 0 and 0x0ff).
5304 @item relaxing gcc instruction group
5305 When @command{gcc} is called with @option{-mrelax}, it can emit group
5306 of instructions that the linker can optimize to use a 68HC11 direct
5307 addressing mode. These instructions consists of @code{bclr} or
5308 @code{bset} instructions.
5312 @subsection Trampoline Generation
5314 @cindex trampoline generation on M68HC11
5315 @cindex trampoline generation on M68HC12
5316 For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
5317 call a far function using a normal @code{jsr} instruction. The linker
5318 will also change the relocation to some far function to use the
5319 trampoline address instead of the function address. This is typically the
5320 case when a pointer to a function is taken. The pointer will in fact
5321 point to the function trampoline.
5329 @section @command{ld} and the ARM family
5331 @cindex ARM interworking support
5332 @kindex --support-old-code
5333 For the ARM, @command{ld} will generate code stubs to allow functions calls
5334 betweem ARM and Thumb code. These stubs only work with code that has
5335 been compiled and assembled with the @samp{-mthumb-interwork} command
5336 line option. If it is necessary to link with old ARM object files or
5337 libraries, which have not been compiled with the -mthumb-interwork
5338 option then the @samp{--support-old-code} command line switch should be
5339 given to the linker. This will make it generate larger stub functions
5340 which will work with non-interworking aware ARM code. Note, however,
5341 the linker does not support generating stubs for function calls to
5342 non-interworking aware Thumb code.
5344 @cindex thumb entry point
5345 @cindex entry point, thumb
5346 @kindex --thumb-entry=@var{entry}
5347 The @samp{--thumb-entry} switch is a duplicate of the generic
5348 @samp{--entry} switch, in that it sets the program's starting address.
5349 But it also sets the bottom bit of the address, so that it can be
5350 branched to using a BX instruction, and the program will start
5351 executing in Thumb mode straight away.
5355 The @samp{--be8} switch instructs @command{ld} to generate BE8 format
5356 executables. This option is only valid when linking big-endian objects.
5357 The resulting image will contain big-endian data and little-endian code.
5360 @kindex --target1-rel
5361 @kindex --target1-abs
5362 The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
5363 @samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32}
5364 or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel}
5365 and @samp{--target1-abs} switches override the default.
5368 @kindex --target2=@var{type}
5369 The @samp{--target2=type} switch overrides the default definition of the
5370 @samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their
5371 meanings, and target defaults are as follows:
5374 @samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
5376 @samp{R_ARM_ABS32} (arm*-*-symbianelf)
5378 @samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
5383 The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF
5384 specification) enables objects compiled for the ARMv4 architecture to be
5385 interworking-safe when linked with other objects compiled for ARMv4t, but
5386 also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
5388 In the latter case, the switch @option{--fix-v4bx} must be passed to the
5389 linker, which causes v4t @code{BX rM} instructions to be rewritten as
5390 @code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
5392 In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
5393 relocations are ignored.
5397 The @samp{--use-blx} switch enables the linker to use ARM/Thumb
5398 BLX instructions (available on ARMv5t and above) in various
5399 situations. Currently it is used to perform calls via the PLT from Thumb
5400 code using BLX rather than using BX and a mode-switching stub before
5401 each PLT entry. This should lead to such calls executing slightly faster.
5403 This option is enabled implicitly for SymbianOS, so there is no need to
5404 specify it if you are using that target.
5417 @section @command{ld} and HPPA 32-bit ELF Support
5418 @cindex HPPA multiple sub-space stubs
5419 @kindex --multi-subspace
5420 When generating a shared library, @command{ld} will by default generate
5421 import stubs suitable for use with a single sub-space application.
5422 The @samp{--multi-subspace} switch causes @command{ld} to generate export
5423 stubs, and different (larger) import stubs suitable for use with
5424 multiple sub-spaces.
5426 @cindex HPPA stub grouping
5427 @kindex --stub-group-size=@var{N}
5428 Long branch stubs and import/export stubs are placed by @command{ld} in
5429 stub sections located between groups of input sections.
5430 @samp{--stub-group-size} specifies the maximum size of a group of input
5431 sections handled by one stub section. Since branch offsets are signed,
5432 a stub section may serve two groups of input sections, one group before
5433 the stub section, and one group after it. However, when using
5434 conditional branches that require stubs, it may be better (for branch
5435 prediction) that stub sections only serve one group of input sections.
5436 A negative value for @samp{N} chooses this scheme, ensuring that
5437 branches to stubs always use a negative offset. Two special values of
5438 @samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
5439 @command{ld} to automatically size input section groups for the branch types
5440 detected, with the same behaviour regarding stub placement as other
5441 positive or negative values of @samp{N} respectively.
5443 Note that @samp{--stub-group-size} does not split input sections. A
5444 single input section larger than the group size specified will of course
5445 create a larger group (of one section). If input sections are too
5446 large, it may not be possible for a branch to reach its stub.
5459 @section @code{ld} and MMIX
5460 For MMIX, there is a choice of generating @code{ELF} object files or
5461 @code{mmo} object files when linking. The simulator @code{mmix}
5462 understands the @code{mmo} format. The binutils @code{objcopy} utility
5463 can translate between the two formats.
5465 There is one special section, the @samp{.MMIX.reg_contents} section.
5466 Contents in this section is assumed to correspond to that of global
5467 registers, and symbols referring to it are translated to special symbols,
5468 equal to registers. In a final link, the start address of the
5469 @samp{.MMIX.reg_contents} section corresponds to the first allocated
5470 global register multiplied by 8. Register @code{$255} is not included in
5471 this section; it is always set to the program entry, which is at the
5472 symbol @code{Main} for @code{mmo} files.
5474 Symbols with the prefix @code{__.MMIX.start.}, for example
5475 @code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special;
5476 there must be only one each, even if they are local. The default linker
5477 script uses these to set the default start address of a section.
5479 Initial and trailing multiples of zero-valued 32-bit words in a section,
5480 are left out from an mmo file.
5493 @section @code{ld} and MSP430
5494 For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]}
5495 will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
5496 just pass @samp{-m help} option to the linker).
5498 @cindex MSP430 extra sections
5499 The linker will recognize some extra sections which are MSP430 specific:
5502 @item @samp{.vectors}
5503 Defines a portion of ROM where interrupt vectors located.
5505 @item @samp{.bootloader}
5506 Defines the bootloader portion of the ROM (if applicable). Any code
5507 in this section will be uploaded to the MPU.
5509 @item @samp{.infomem}
5510 Defines an information memory section (if applicable). Any code in
5511 this section will be uploaded to the MPU.
5513 @item @samp{.infomemnobits}
5514 This is the same as the @samp{.infomem} section except that any code
5515 in this section will not be uploaded to the MPU.
5517 @item @samp{.noinit}
5518 Denotes a portion of RAM located above @samp{.bss} section.
5520 The last two sections are used by gcc.
5534 @section @command{ld} and PowerPC 32-bit ELF Support
5535 @cindex PowerPC long branches
5536 @kindex --relax on PowerPC
5537 Branches on PowerPC processors are limited to a signed 26-bit
5538 displacement, which may result in @command{ld} giving
5539 @samp{relocation truncated to fit} errors with very large programs.
5540 @samp{--relax} enables the generation of trampolines that can access
5541 the entire 32-bit address space. These trampolines are inserted at
5542 section boundaries, so may not themselves be reachable if an input
5543 section exceeds 33M in size.
5545 @cindex PowerPC ELF32 options
5550 Current PowerPC GCC accepts a @samp{-msecure-plt} option that
5551 generates code capable of using a newer PLT and GOT layout that has
5552 the security advantage of no executable section ever needing to be
5553 writable and no writable section ever being executable. PowerPC
5554 @command{ld} will generate this layout, including stubs to access the
5555 PLT, if all input files (including startup and static libraries) were
5556 compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old
5557 BSS PLT (and GOT layout) which can give slightly better performance.
5562 The new secure PLT and GOT are placed differently relative to other
5563 sections compared to older BSS PLT and GOT placement. The location of
5564 @code{.plt} must change because the new secure PLT is an initialized
5565 section while the old PLT is uninitialized. The reason for the
5566 @code{.got} change is more subtle: The new placement allows
5567 @code{.got} to be read-only in applications linked with
5568 @samp{-z relro -z now}. However, this placement means that
5569 @code{.sdata} cannot always be used in shared libraries, because the
5570 PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
5571 pointer. @samp{--sdata-got} forces the old GOT placement. PowerPC
5572 GCC doesn't use @code{.sdata} in shared libraries, so this option is
5573 really only useful for other compilers that may do so.
5575 @cindex PowerPC stub symbols
5576 @kindex --emit-stub-syms
5577 @item --emit-stub-syms
5578 This option causes @command{ld} to label linker stubs with a local
5579 symbol that encodes the stub type and destination.
5581 @cindex PowerPC TLS optimization
5582 @kindex --no-tls-optimize
5583 @item --no-tls-optimize
5584 PowerPC @command{ld} normally performs some optimization of code
5585 sequences used to access Thread-Local Storage. Use this option to
5586 disable the optimization.
5599 @node PowerPC64 ELF64
5600 @section @command{ld} and PowerPC64 64-bit ELF Support
5602 @cindex PowerPC64 ELF64 options
5604 @cindex PowerPC64 stub grouping
5605 @kindex --stub-group-size
5606 @item --stub-group-size
5607 Long branch stubs, PLT call stubs and TOC adjusting stubs are placed
5608 by @command{ld} in stub sections located between groups of input sections.
5609 @samp{--stub-group-size} specifies the maximum size of a group of input
5610 sections handled by one stub section. Since branch offsets are signed,
5611 a stub section may serve two groups of input sections, one group before
5612 the stub section, and one group after it. However, when using
5613 conditional branches that require stubs, it may be better (for branch
5614 prediction) that stub sections only serve one group of input sections.
5615 A negative value for @samp{N} chooses this scheme, ensuring that
5616 branches to stubs always use a negative offset. Two special values of
5617 @samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
5618 @command{ld} to automatically size input section groups for the branch types
5619 detected, with the same behaviour regarding stub placement as other
5620 positive or negative values of @samp{N} respectively.
5622 Note that @samp{--stub-group-size} does not split input sections. A
5623 single input section larger than the group size specified will of course
5624 create a larger group (of one section). If input sections are too
5625 large, it may not be possible for a branch to reach its stub.
5627 @cindex PowerPC64 stub symbols
5628 @kindex --emit-stub-syms
5629 @item --emit-stub-syms
5630 This option causes @command{ld} to label linker stubs with a local
5631 symbol that encodes the stub type and destination.
5633 @cindex PowerPC64 dot symbols
5635 @kindex --no-dotsyms
5636 @item --dotsyms, --no-dotsyms
5637 These two options control how @command{ld} interprets version patterns
5638 in a version script. Older PowerPC64 compilers emitted both a
5639 function descriptor symbol with the same name as the function, and a
5640 code entry symbol with the name prefixed by a dot (@samp{.}). To
5641 properly version a function @samp{foo}, the version script thus needs
5642 to control both @samp{foo} and @samp{.foo}. The option
5643 @samp{--dotsyms}, on by default, automatically adds the required
5644 dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
5647 @cindex PowerPC64 TLS optimization
5648 @kindex --no-tls-optimize
5649 @item --no-tls-optimize
5650 PowerPC64 @command{ld} normally performs some optimization of code
5651 sequences used to access Thread-Local Storage. Use this option to
5652 disable the optimization.
5654 @cindex PowerPC64 OPD optimization
5655 @kindex --no-opd-optimize
5656 @item --no-opd-optimize
5657 PowerPC64 @command{ld} normally removes @code{.opd} section entries
5658 corresponding to deleted link-once functions, or functions removed by
5659 the action of @samp{--gc-sections} or linker scrip @code{/DISCARD/}.
5660 Use this option to disable @code{.opd} optimization.
5662 @cindex PowerPC64 OPD spacing
5663 @kindex --non-overlapping-opd
5664 @item --non-overlapping-opd
5665 Some PowerPC64 compilers have an option to generate compressed
5666 @code{.opd} entries spaced 16 bytes apart, overlapping the third word,
5667 the static chain pointer (unused in C) with the first word of the next
5668 entry. This option expands such entries to the full 24 bytes.
5670 @cindex PowerPC64 TOC optimization
5671 @kindex --no-toc-optimize
5672 @item --no-toc-optimize
5673 PowerPC64 @command{ld} normally removes unused @code{.toc} section
5674 entries. Such entries are detected by examining relocations that
5675 reference the TOC in code sections. A reloc in a deleted code section
5676 marks a TOC word as unneeded, while a reloc in a kept code section
5677 marks a TOC word as needed. Since the TOC may reference itself, TOC
5678 relocs are also examined. TOC words marked as both needed and
5679 unneeded will of course be kept. TOC words without any referencing
5680 reloc are assumed to be part of a multi-word entry, and are kept or
5681 discarded as per the nearest marked preceding word. This works
5682 reliably for compiler generated code, but may be incorrect if assembly
5683 code is used to insert TOC entries. Use this option to disable the
5686 @cindex PowerPC64 multi-TOC
5687 @kindex --no-multi-toc
5688 @item --no-multi-toc
5689 By default, PowerPC64 GCC generates code for a TOC model where TOC
5690 entries are accessed with a 16-bit offset from r2. This limits the
5691 total TOC size to 64K. PowerPC64 @command{ld} extends this limit by
5692 grouping code sections such that each group uses less than 64K for its
5693 TOC entries, then inserts r2 adjusting stubs between inter-group
5694 calls. @command{ld} does not split apart input sections, so cannot
5695 help if a single input file has a @code{.toc} section that exceeds
5696 64K, most likely from linking multiple files with @command{ld -r}.
5697 Use this option to turn off this feature.
5711 @section @command{ld}'s Support for Various TI COFF Versions
5712 @cindex TI COFF versions
5713 @kindex --format=@var{version}
5714 The @samp{--format} switch allows selection of one of the various
5715 TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
5716 also supported. The TI COFF versions also vary in header byte-order
5717 format; @command{ld} will read any version or byte order, but the output
5718 header format depends on the default specified by the specific target.
5731 @section @command{ld} and WIN32 (cygwin/mingw)
5733 This section describes some of the win32 specific @command{ld} issues.
5734 See @ref{Options,,Command Line Options} for detailed decription of the
5735 command line options mentioned here.
5738 @cindex import libraries
5739 @item import libraries
5740 The standard Windows linker creates and uses so-called import
5741 libraries, which contains information for linking to dll's. They are
5742 regular static archives and are handled as any other static
5743 archive. The cygwin and mingw ports of @command{ld} have specific
5744 support for creating such libraries provided with the
5745 @samp{--out-implib} command line option.
5747 @item exporting DLL symbols
5748 @cindex exporting DLL symbols
5749 The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
5752 @item using auto-export functionality
5753 @cindex using auto-export functionality
5754 By default @command{ld} exports symbols with the auto-export functionality,
5755 which is controlled by the following command line options:
5758 @item --export-all-symbols [This is the default]
5759 @item --exclude-symbols
5760 @item --exclude-libs
5763 If, however, @samp{--export-all-symbols} is not given explicitly on the
5764 command line, then the default auto-export behavior will be @emph{disabled}
5765 if either of the following are true:
5768 @item A DEF file is used.
5769 @item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
5772 @item using a DEF file
5773 @cindex using a DEF file
5774 Another way of exporting symbols is using a DEF file. A DEF file is
5775 an ASCII file containing definitions of symbols which should be
5776 exported when a dll is created. Usually it is named @samp{<dll
5777 name>.def} and is added as any other object file to the linker's
5778 command line. The file's name must end in @samp{.def} or @samp{.DEF}.
5781 gcc -o <output> <objectfiles> <dll name>.def
5784 Using a DEF file turns off the normal auto-export behavior, unless the
5785 @samp{--export-all-symbols} option is also used.
5787 Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
5790 LIBRARY "xyz.dll" BASE=0x20000000
5796 another_foo = abc.dll.afoo
5800 This example defines a DLL with a non-default base address and five
5801 symbols in the export table. The third exported symbol @code{_bar} is an
5802 alias for the second. The fourth symbol, @code{another_foo} is resolved
5803 by "forwarding" to another module and treating it as an alias for
5804 @code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
5805 @code{var1} is declared to be a data object.
5807 The optional @code{LIBRARY <name>} command indicates the @emph{internal}
5808 name of the output DLL. If @samp{<name>} does not include a suffix,
5809 the default library suffix, @samp{.DLL} is appended.
5811 When the .DEF file is used to build an application. rather than a
5812 library, the @code{NAME <name>} command shoud be used instead of
5813 @code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
5814 executable suffix, @samp{.EXE} is appended.
5816 With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
5817 specification @code{BASE = <number>} may be used to specify a
5818 non-default base address for the image.
5820 If neither @code{LIBRARY <name>} nor @code{NAME <name>} is specified,
5821 or they specify an empty string, the internal name is the same as the
5822 filename specified on the command line.
5824 The complete specification of an export symbol is:
5828 ( ( ( <name1> [ = <name2> ] )
5829 | ( <name1> = <module-name> . <external-name>))
5830 [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
5833 Declares @samp{<name1>} as an exported symbol from the DLL, or declares
5834 @samp{<name1>} as an exported alias for @samp{<name2>}; or declares
5835 @samp{<name1>} as a "forward" alias for the symbol
5836 @samp{<external-name>} in the DLL @samp{<module-name>}.
5837 Optionally, the symbol may be exported by the specified ordinal
5838 @samp{<integer>} alias.
5840 The optional keywords that follow the declaration indicate:
5842 @code{NONAME}: Do not put the symbol name in the DLL's export table. It
5843 will still be exported by its ordinal alias (either the value specified
5844 by the .def specification or, otherwise, the value assigned by the
5845 linker). The symbol name, however, does remain visible in the import
5846 library (if any), unless @code{PRIVATE} is also specified.
5848 @code{DATA}: The symbol is a variable or object, rather than a function.
5849 The import lib will export only an indirect reference to @code{foo} as
5850 the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
5853 @code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
5854 well as @code{_imp__foo} into the import library. Both refer to the
5855 read-only import address table's pointer to the variable, not to the
5856 variable itself. This can be dangerous. If the user code fails to add
5857 the @code{dllimport} attribute and also fails to explicitly add the
5858 extra indirection that the use of the attribute enforces, the
5859 application will behave unexpectedly.
5861 @code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
5862 it into the static import library used to resolve imports at link time. The
5863 symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
5864 API at runtime or by by using the GNU ld extension of linking directly to
5865 the DLL without an import library.
5867 See ld/deffilep.y in the binutils sources for the full specification of
5868 other DEF file statements
5870 @cindex creating a DEF file
5871 While linking a shared dll, @command{ld} is able to create a DEF file
5872 with the @samp{--output-def <file>} command line option.
5874 @item Using decorations
5875 @cindex Using decorations
5876 Another way of marking symbols for export is to modify the source code
5877 itself, so that when building the DLL each symbol to be exported is
5881 __declspec(dllexport) int a_variable
5882 __declspec(dllexport) void a_function(int with_args)
5885 All such symbols will be exported from the DLL. If, however,
5886 any of the object files in the DLL contain symbols decorated in
5887 this way, then the normal auto-export behavior is disabled, unless
5888 the @samp{--export-all-symbols} option is also used.
5890 Note that object files that wish to access these symbols must @emph{not}
5891 decorate them with dllexport. Instead, they should use dllimport,
5895 __declspec(dllimport) int a_variable
5896 __declspec(dllimport) void a_function(int with_args)
5899 This complicates the structure of library header files, because
5900 when included by the library itself the header must declare the
5901 variables and functions as dllexport, but when included by client
5902 code the header must declare them as dllimport. There are a number
5903 of idioms that are typically used to do this; often client code can
5904 omit the __declspec() declaration completely. See
5905 @samp{--enable-auto-import} and @samp{automatic data imports} for more
5909 @cindex automatic data imports
5910 @item automatic data imports
5911 The standard Windows dll format supports data imports from dlls only
5912 by adding special decorations (dllimport/dllexport), which let the
5913 compiler produce specific assembler instructions to deal with this
5914 issue. This increases the effort necessary to port existing Un*x
5915 code to these platforms, especially for large
5916 c++ libraries and applications. The auto-import feature, which was
5917 initially provided by Paul Sokolovsky, allows one to omit the
5918 decorations to archieve a behavior that conforms to that on POSIX/Un*x
5919 platforms. This feature is enabled with the @samp{--enable-auto-import}
5920 command-line option, although it is enabled by default on cygwin/mingw.
5921 The @samp{--enable-auto-import} option itself now serves mainly to
5922 suppress any warnings that are ordinarily emitted when linked objects
5923 trigger the feature's use.
5925 auto-import of variables does not always work flawlessly without
5926 additional assistance. Sometimes, you will see this message
5928 "variable '<var>' can't be auto-imported. Please read the
5929 documentation for ld's @code{--enable-auto-import} for details."
5931 The @samp{--enable-auto-import} documentation explains why this error
5932 occurs, and several methods that can be used to overcome this difficulty.
5933 One of these methods is the @emph{runtime pseudo-relocs} feature, described
5936 @cindex runtime pseudo-relocation
5937 For complex variables imported from DLLs (such as structs or classes),
5938 object files typically contain a base address for the variable and an
5939 offset (@emph{addend}) within the variable--to specify a particular
5940 field or public member, for instance. Unfortunately, the runtime loader used
5941 in win32 environments is incapable of fixing these references at runtime
5942 without the additional information supplied by dllimport/dllexport decorations.
5943 The standard auto-import feature described above is unable to resolve these
5946 The @samp{--enable-runtime-pseudo-relocs} switch allows these references to
5947 be resolved without error, while leaving the task of adjusting the references
5948 themselves (with their non-zero addends) to specialized code provided by the
5949 runtime environment. Recent versions of the cygwin and mingw environments and
5950 compilers provide this runtime support; older versions do not. However, the
5951 support is only necessary on the developer's platform; the compiled result will
5952 run without error on an older system.
5954 @samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
5957 @cindex direct linking to a dll
5958 @item direct linking to a dll
5959 The cygwin/mingw ports of @command{ld} support the direct linking,
5960 including data symbols, to a dll without the usage of any import
5961 libraries. This is much faster and uses much less memory than does the
5962 traditional import library method, expecially when linking large
5963 libraries or applications. When @command{ld} creates an import lib, each
5964 function or variable exported from the dll is stored in its own bfd, even
5965 though a single bfd could contain many exports. The overhead involved in
5966 storing, loading, and processing so many bfd's is quite large, and explains the
5967 tremendous time, memory, and storage needed to link against particularly
5968 large or complex libraries when using import libs.
5970 Linking directly to a dll uses no extra command-line switches other than
5971 @samp{-L} and @samp{-l}, because @command{ld} already searches for a number
5972 of names to match each library. All that is needed from the developer's
5973 perspective is an understanding of this search, in order to force ld to
5974 select the dll instead of an import library.
5977 For instance, when ld is called with the argument @samp{-lxxx} it will attempt
5978 to find, in the first directory of its search path,
5989 before moving on to the next directory in the search path.
5991 (*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
5992 where @samp{<prefix>} is set by the @command{ld} option
5993 @samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
5994 file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
5997 Other win32-based unix environments, such as mingw or pw32, may use other
5998 @samp{<prefix>}es, although at present only cygwin makes use of this feature. It
5999 was originally intended to help avoid name conflicts among dll's built for the
6000 various win32/un*x environments, so that (for example) two versions of a zlib dll
6001 could coexist on the same machine.
6003 The generic cygwin/mingw path layout uses a @samp{bin} directory for
6004 applications and dll's and a @samp{lib} directory for the import
6005 libraries (using cygwin nomenclature):
6011 libxxx.dll.a (in case of dll's)
6012 libxxx.a (in case of static archive)
6015 Linking directly to a dll without using the import library can be
6018 1. Use the dll directly by adding the @samp{bin} path to the link line
6020 gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
6023 However, as the dll's often have version numbers appended to their names
6024 (@samp{cygncurses-5.dll}) this will often fail, unless one specifies
6025 @samp{-L../bin -lncurses-5} to include the version. Import libs are generally
6026 not versioned, and do not have this difficulty.
6028 2. Create a symbolic link from the dll to a file in the @samp{lib}
6029 directory according to the above mentioned search pattern. This
6030 should be used to avoid unwanted changes in the tools needed for
6034 ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
6037 Then you can link without any make environment changes.
6040 gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
6043 This technique also avoids the version number problems, because the following is
6050 libxxx.dll.a -> ../bin/cygxxx-5.dll
6053 Linking directly to a dll without using an import lib will work
6054 even when auto-import features are exercised, and even when
6055 @samp{--enable-runtime-pseudo-relocs} is used.
6057 Given the improvements in speed and memory usage, one might justifiably
6058 wonder why import libraries are used at all. There are two reasons:
6060 1. Until recently, the link-directly-to-dll functionality did @emph{not}
6061 work with auto-imported data.
6063 2. Sometimes it is necessary to include pure static objects within the
6064 import library (which otherwise contains only bfd's for indirection
6065 symbols that point to the exports of a dll). Again, the import lib
6066 for the cygwin kernel makes use of this ability, and it is not
6067 possible to do this without an import lib.
6069 So, import libs are not going away. But the ability to replace
6070 true import libs with a simple symbolic link to (or a copy of)
6071 a dll, in most cases, is a useful addition to the suite of tools
6072 binutils makes available to the win32 developer. Given the
6073 massive improvements in memory requirements during linking, storage
6074 requirements, and linking speed, we expect that many developers
6075 will soon begin to use this feature whenever possible.
6077 @item symbol aliasing
6079 @item adding additional names
6080 Sometimes, it is useful to export symbols with additional names.
6081 A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
6082 exported as @samp{_foo} by using special directives in the DEF file
6083 when creating the dll. This will affect also the optional created
6084 import library. Consider the following DEF file:
6087 LIBRARY "xyz.dll" BASE=0x61000000
6094 The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
6096 Another method for creating a symbol alias is to create it in the
6097 source code using the "weak" attribute:
6100 void foo () @{ /* Do something. */; @}
6101 void _foo () __attribute__ ((weak, alias ("foo")));
6104 See the gcc manual for more information about attributes and weak
6107 @item renaming symbols
6108 Sometimes it is useful to rename exports. For instance, the cygwin
6109 kernel does this regularly. A symbol @samp{_foo} can be exported as
6110 @samp{foo} but not as @samp{_foo} by using special directives in the
6111 DEF file. (This will also affect the import library, if it is
6112 created). In the following example:
6115 LIBRARY "xyz.dll" BASE=0x61000000
6121 The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
6125 Note: using a DEF file disables the default auto-export behavior,
6126 unless the @samp{--export-all-symbols} command line option is used.
6127 If, however, you are trying to rename symbols, then you should list
6128 @emph{all} desired exports in the DEF file, including the symbols
6129 that are not being renamed, and do @emph{not} use the
6130 @samp{--export-all-symbols} option. If you list only the
6131 renamed symbols in the DEF file, and use @samp{--export-all-symbols}
6132 to handle the other symbols, then the both the new names @emph{and}
6133 the original names for the renamed symbols will be exported.
6134 In effect, you'd be aliasing those symbols, not renaming them,
6135 which is probably not what you wanted.
6137 @cindex weak externals
6138 @item weak externals
6139 The Windows object format, PE, specifies a form of weak symbols called
6140 weak externals. When a weak symbol is linked and the symbol is not
6141 defined, the weak symbol becomes an alias for some other symbol. There
6142 are three variants of weak externals:
6144 @item Definition is searched for in objects and libraries, historically
6145 called lazy externals.
6146 @item Definition is searched for only in other objects, not in libraries.
6147 This form is not presently implemented.
6148 @item No search; the symbol is an alias. This form is not presently
6151 As a GNU extension, weak symbols that do not specify an alternate symbol
6152 are supported. If the symbol is undefined when linking, the symbol
6153 uses a default value.
6167 @section @code{ld} and Xtensa Processors
6169 @cindex Xtensa processors
6170 The default @command{ld} behavior for Xtensa processors is to interpret
6171 @code{SECTIONS} commands so that lists of explicitly named sections in a
6172 specification with a wildcard file will be interleaved when necessary to
6173 keep literal pools within the range of PC-relative load offsets. For
6174 example, with the command:
6186 @command{ld} may interleave some of the @code{.literal}
6187 and @code{.text} sections from different object files to ensure that the
6188 literal pools are within the range of PC-relative load offsets. A valid
6189 interleaving might place the @code{.literal} sections from an initial
6190 group of files followed by the @code{.text} sections of that group of
6191 files. Then, the @code{.literal} sections from the rest of the files
6192 and the @code{.text} sections from the rest of the files would follow.
6194 @cindex @option{--relax} on Xtensa
6195 @cindex relaxing on Xtensa
6196 Relaxation is enabled by default for the Xtensa version of @command{ld} and
6197 provides two important link-time optimizations. The first optimization
6198 is to combine identical literal values to reduce code size. A redundant
6199 literal will be removed and all the @code{L32R} instructions that use it
6200 will be changed to reference an identical literal, as long as the
6201 location of the replacement literal is within the offset range of all
6202 the @code{L32R} instructions. The second optimization is to remove
6203 unnecessary overhead from assembler-generated ``longcall'' sequences of
6204 @code{L32R}/@code{CALLX@var{n}} when the target functions are within
6205 range of direct @code{CALL@var{n}} instructions.
6207 For each of these cases where an indirect call sequence can be optimized
6208 to a direct call, the linker will change the @code{CALLX@var{n}}
6209 instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
6210 instruction, and remove the literal referenced by the @code{L32R}
6211 instruction if it is not used for anything else. Removing the
6212 @code{L32R} instruction always reduces code size but can potentially
6213 hurt performance by changing the alignment of subsequent branch targets.
6214 By default, the linker will always preserve alignments, either by
6215 switching some instructions between 24-bit encodings and the equivalent
6216 density instructions or by inserting a no-op in place of the @code{L32R}
6217 instruction that was removed. If code size is more important than
6218 performance, the @option{--size-opt} option can be used to prevent the
6219 linker from widening density instructions or inserting no-ops, except in
6220 a few cases where no-ops are required for correctness.
6222 The following Xtensa-specific command-line options can be used to
6225 @cindex Xtensa options
6229 Since the Xtensa version of @code{ld} enables the @option{--relax} option
6230 by default, the @option{--no-relax} option is provided to disable
6234 When optimizing indirect calls to direct calls, optimize for code size
6235 more than performance. With this option, the linker will not insert
6236 no-ops or widen density instructions to preserve branch target
6237 alignment. There may still be some cases where no-ops are required to
6238 preserve the correctness of the code.
6246 @ifclear SingleFormat
6251 @cindex object file management
6252 @cindex object formats available
6254 The linker accesses object and archive files using the BFD libraries.
6255 These libraries allow the linker to use the same routines to operate on
6256 object files whatever the object file format. A different object file
6257 format can be supported simply by creating a new BFD back end and adding
6258 it to the library. To conserve runtime memory, however, the linker and
6259 associated tools are usually configured to support only a subset of the
6260 object file formats available. You can use @code{objdump -i}
6261 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
6262 list all the formats available for your configuration.
6264 @cindex BFD requirements
6265 @cindex requirements for BFD
6266 As with most implementations, BFD is a compromise between
6267 several conflicting requirements. The major factor influencing
6268 BFD design was efficiency: any time used converting between
6269 formats is time which would not have been spent had BFD not
6270 been involved. This is partly offset by abstraction payback; since
6271 BFD simplifies applications and back ends, more time and care
6272 may be spent optimizing algorithms for a greater speed.
6274 One minor artifact of the BFD solution which you should bear in
6275 mind is the potential for information loss. There are two places where
6276 useful information can be lost using the BFD mechanism: during
6277 conversion and during output. @xref{BFD information loss}.
6280 * BFD outline:: How it works: an outline of BFD
6284 @section How It Works: An Outline of BFD
6285 @cindex opening object files
6286 @include bfdsumm.texi
6289 @node Reporting Bugs
6290 @chapter Reporting Bugs
6291 @cindex bugs in @command{ld}
6292 @cindex reporting bugs in @command{ld}
6294 Your bug reports play an essential role in making @command{ld} reliable.
6296 Reporting a bug may help you by bringing a solution to your problem, or
6297 it may not. But in any case the principal function of a bug report is
6298 to help the entire community by making the next version of @command{ld}
6299 work better. Bug reports are your contribution to the maintenance of
6302 In order for a bug report to serve its purpose, you must include the
6303 information that enables us to fix the bug.
6306 * Bug Criteria:: Have you found a bug?
6307 * Bug Reporting:: How to report bugs
6311 @section Have You Found a Bug?
6312 @cindex bug criteria
6314 If you are not sure whether you have found a bug, here are some guidelines:
6317 @cindex fatal signal
6318 @cindex linker crash
6319 @cindex crash of linker
6321 If the linker gets a fatal signal, for any input whatever, that is a
6322 @command{ld} bug. Reliable linkers never crash.
6324 @cindex error on valid input
6326 If @command{ld} produces an error message for valid input, that is a bug.
6328 @cindex invalid input
6330 If @command{ld} does not produce an error message for invalid input, that
6331 may be a bug. In the general case, the linker can not verify that
6332 object files are correct.
6335 If you are an experienced user of linkers, your suggestions for
6336 improvement of @command{ld} are welcome in any case.
6340 @section How to Report Bugs
6342 @cindex @command{ld} bugs, reporting
6344 A number of companies and individuals offer support for @sc{gnu}
6345 products. If you obtained @command{ld} from a support organization, we
6346 recommend you contact that organization first.
6348 You can find contact information for many support companies and
6349 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
6352 Otherwise, send bug reports for @command{ld} to
6353 @samp{bug-binutils@@gnu.org}.
6355 The fundamental principle of reporting bugs usefully is this:
6356 @strong{report all the facts}. If you are not sure whether to state a
6357 fact or leave it out, state it!
6359 Often people omit facts because they think they know what causes the
6360 problem and assume that some details do not matter. Thus, you might
6361 assume that the name of a symbol you use in an example does not
6362 matter. Well, probably it does not, but one cannot be sure. Perhaps
6363 the bug is a stray memory reference which happens to fetch from the
6364 location where that name is stored in memory; perhaps, if the name
6365 were different, the contents of that location would fool the linker
6366 into doing the right thing despite the bug. Play it safe and give a
6367 specific, complete example. That is the easiest thing for you to do,
6368 and the most helpful.
6370 Keep in mind that the purpose of a bug report is to enable us to fix
6371 the bug if it is new to us. Therefore, always write your bug reports
6372 on the assumption that the bug has not been reported previously.
6374 Sometimes people give a few sketchy facts and ask, ``Does this ring a
6375 bell?'' This cannot help us fix a bug, so it is basically useless. We
6376 respond by asking for enough details to enable us to investigate.
6377 You might as well expedite matters by sending them to begin with.
6379 To enable us to fix the bug, you should include all these things:
6383 The version of @command{ld}. @command{ld} announces it if you start it with
6384 the @samp{--version} argument.
6386 Without this, we will not know whether there is any point in looking for
6387 the bug in the current version of @command{ld}.
6390 Any patches you may have applied to the @command{ld} source, including any
6391 patches made to the @code{BFD} library.
6394 The type of machine you are using, and the operating system name and
6398 What compiler (and its version) was used to compile @command{ld}---e.g.
6402 The command arguments you gave the linker to link your example and
6403 observe the bug. To guarantee you will not omit something important,
6404 list them all. A copy of the Makefile (or the output from make) is
6407 If we were to try to guess the arguments, we would probably guess wrong
6408 and then we might not encounter the bug.
6411 A complete input file, or set of input files, that will reproduce the
6412 bug. It is generally most helpful to send the actual object files
6413 provided that they are reasonably small. Say no more than 10K. For
6414 bigger files you can either make them available by FTP or HTTP or else
6415 state that you are willing to send the object file(s) to whomever
6416 requests them. (Note - your email will be going to a mailing list, so
6417 we do not want to clog it up with large attachments). But small
6418 attachments are best.
6420 If the source files were assembled using @code{gas} or compiled using
6421 @code{gcc}, then it may be OK to send the source files rather than the
6422 object files. In this case, be sure to say exactly what version of
6423 @code{gas} or @code{gcc} was used to produce the object files. Also say
6424 how @code{gas} or @code{gcc} were configured.
6427 A description of what behavior you observe that you believe is
6428 incorrect. For example, ``It gets a fatal signal.''
6430 Of course, if the bug is that @command{ld} gets a fatal signal, then we
6431 will certainly notice it. But if the bug is incorrect output, we might
6432 not notice unless it is glaringly wrong. You might as well not give us
6433 a chance to make a mistake.
6435 Even if the problem you experience is a fatal signal, you should still
6436 say so explicitly. Suppose something strange is going on, such as, your
6437 copy of @command{ld} is out of synch, or you have encountered a bug in the
6438 C library on your system. (This has happened!) Your copy might crash
6439 and ours would not. If you told us to expect a crash, then when ours
6440 fails to crash, we would know that the bug was not happening for us. If
6441 you had not told us to expect a crash, then we would not be able to draw
6442 any conclusion from our observations.
6445 If you wish to suggest changes to the @command{ld} source, send us context
6446 diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
6447 @samp{-p} option. Always send diffs from the old file to the new file.
6448 If you even discuss something in the @command{ld} source, refer to it by
6449 context, not by line number.
6451 The line numbers in our development sources will not match those in your
6452 sources. Your line numbers would convey no useful information to us.
6455 Here are some things that are not necessary:
6459 A description of the envelope of the bug.
6461 Often people who encounter a bug spend a lot of time investigating
6462 which changes to the input file will make the bug go away and which
6463 changes will not affect it.
6465 This is often time consuming and not very useful, because the way we
6466 will find the bug is by running a single example under the debugger
6467 with breakpoints, not by pure deduction from a series of examples.
6468 We recommend that you save your time for something else.
6470 Of course, if you can find a simpler example to report @emph{instead}
6471 of the original one, that is a convenience for us. Errors in the
6472 output will be easier to spot, running under the debugger will take
6473 less time, and so on.
6475 However, simplification is not vital; if you do not want to do this,
6476 report the bug anyway and send us the entire test case you used.
6479 A patch for the bug.
6481 A patch for the bug does help us if it is a good one. But do not omit
6482 the necessary information, such as the test case, on the assumption that
6483 a patch is all we need. We might see problems with your patch and decide
6484 to fix the problem another way, or we might not understand it at all.
6486 Sometimes with a program as complicated as @command{ld} it is very hard to
6487 construct an example that will make the program follow a certain path
6488 through the code. If you do not send us the example, we will not be
6489 able to construct one, so we will not be able to verify that the bug is
6492 And if we cannot understand what bug you are trying to fix, or why your
6493 patch should be an improvement, we will not install it. A test case will
6494 help us to understand.
6497 A guess about what the bug is or what it depends on.
6499 Such guesses are usually wrong. Even we cannot guess right about such
6500 things without first using the debugger to find the facts.
6504 @appendix MRI Compatible Script Files
6505 @cindex MRI compatibility
6506 To aid users making the transition to @sc{gnu} @command{ld} from the MRI
6507 linker, @command{ld} can use MRI compatible linker scripts as an
6508 alternative to the more general-purpose linker scripting language
6509 described in @ref{Scripts}. MRI compatible linker scripts have a much
6510 simpler command set than the scripting language otherwise used with
6511 @command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
6512 linker commands; these commands are described here.
6514 In general, MRI scripts aren't of much use with the @code{a.out} object
6515 file format, since it only has three sections and MRI scripts lack some
6516 features to make use of them.
6518 You can specify a file containing an MRI-compatible script using the
6519 @samp{-c} command-line option.
6521 Each command in an MRI-compatible script occupies its own line; each
6522 command line starts with the keyword that identifies the command (though
6523 blank lines are also allowed for punctuation). If a line of an
6524 MRI-compatible script begins with an unrecognized keyword, @command{ld}
6525 issues a warning message, but continues processing the script.
6527 Lines beginning with @samp{*} are comments.
6529 You can write these commands using all upper-case letters, or all
6530 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
6531 The following list shows only the upper-case form of each command.
6534 @cindex @code{ABSOLUTE} (MRI)
6535 @item ABSOLUTE @var{secname}
6536 @itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
6537 Normally, @command{ld} includes in the output file all sections from all
6538 the input files. However, in an MRI-compatible script, you can use the
6539 @code{ABSOLUTE} command to restrict the sections that will be present in
6540 your output program. If the @code{ABSOLUTE} command is used at all in a
6541 script, then only the sections named explicitly in @code{ABSOLUTE}
6542 commands will appear in the linker output. You can still use other
6543 input sections (whatever you select on the command line, or using
6544 @code{LOAD}) to resolve addresses in the output file.
6546 @cindex @code{ALIAS} (MRI)
6547 @item ALIAS @var{out-secname}, @var{in-secname}
6548 Use this command to place the data from input section @var{in-secname}
6549 in a section called @var{out-secname} in the linker output file.
6551 @var{in-secname} may be an integer.
6553 @cindex @code{ALIGN} (MRI)
6554 @item ALIGN @var{secname} = @var{expression}
6555 Align the section called @var{secname} to @var{expression}. The
6556 @var{expression} should be a power of two.
6558 @cindex @code{BASE} (MRI)
6559 @item BASE @var{expression}
6560 Use the value of @var{expression} as the lowest address (other than
6561 absolute addresses) in the output file.
6563 @cindex @code{CHIP} (MRI)
6564 @item CHIP @var{expression}
6565 @itemx CHIP @var{expression}, @var{expression}
6566 This command does nothing; it is accepted only for compatibility.
6568 @cindex @code{END} (MRI)
6570 This command does nothing whatever; it's only accepted for compatibility.
6572 @cindex @code{FORMAT} (MRI)
6573 @item FORMAT @var{output-format}
6574 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
6575 language, but restricted to one of these output formats:
6579 S-records, if @var{output-format} is @samp{S}
6582 IEEE, if @var{output-format} is @samp{IEEE}
6585 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
6589 @cindex @code{LIST} (MRI)
6590 @item LIST @var{anything}@dots{}
6591 Print (to the standard output file) a link map, as produced by the
6592 @command{ld} command-line option @samp{-M}.
6594 The keyword @code{LIST} may be followed by anything on the
6595 same line, with no change in its effect.
6597 @cindex @code{LOAD} (MRI)
6598 @item LOAD @var{filename}
6599 @itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
6600 Include one or more object file @var{filename} in the link; this has the
6601 same effect as specifying @var{filename} directly on the @command{ld}
6604 @cindex @code{NAME} (MRI)
6605 @item NAME @var{output-name}
6606 @var{output-name} is the name for the program produced by @command{ld}; the
6607 MRI-compatible command @code{NAME} is equivalent to the command-line
6608 option @samp{-o} or the general script language command @code{OUTPUT}.
6610 @cindex @code{ORDER} (MRI)
6611 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
6612 @itemx ORDER @var{secname} @var{secname} @var{secname}
6613 Normally, @command{ld} orders the sections in its output file in the
6614 order in which they first appear in the input files. In an MRI-compatible
6615 script, you can override this ordering with the @code{ORDER} command. The
6616 sections you list with @code{ORDER} will appear first in your output
6617 file, in the order specified.
6619 @cindex @code{PUBLIC} (MRI)
6620 @item PUBLIC @var{name}=@var{expression}
6621 @itemx PUBLIC @var{name},@var{expression}
6622 @itemx PUBLIC @var{name} @var{expression}
6623 Supply a value (@var{expression}) for external symbol
6624 @var{name} used in the linker input files.
6626 @cindex @code{SECT} (MRI)
6627 @item SECT @var{secname}, @var{expression}
6628 @itemx SECT @var{secname}=@var{expression}
6629 @itemx SECT @var{secname} @var{expression}
6630 You can use any of these three forms of the @code{SECT} command to
6631 specify the start address (@var{expression}) for section @var{secname}.
6632 If you have more than one @code{SECT} statement for the same
6633 @var{secname}, only the @emph{first} sets the start address.
6639 @unnumbered LD Index
6644 % I think something like @colophon should be in texinfo. In the
6646 \long\def\colophon{\hbox to0pt{}\vfill
6647 \centerline{The body of this manual is set in}
6648 \centerline{\fontname\tenrm,}
6649 \centerline{with headings in {\bf\fontname\tenbf}}
6650 \centerline{and examples in {\tt\fontname\tentt}.}
6651 \centerline{{\it\fontname\tenit\/} and}
6652 \centerline{{\sl\fontname\tensl\/}}
6653 \centerline{are used for emphasis.}\vfill}
6655 % Blame: doc@cygnus.com, 28mar91.