3 @c Copyright (C) 1991-2024 Free Software Foundation, Inc.
6 @include configdoc.texi
7 @c (configdoc.texi is generated by the Makefile)
13 @macro gcctabopt{body}
19 @c Configure for the generation of man pages
47 @dircategory Software development
49 * Ld: (ld). The GNU linker.
54 This file documents the @sc{gnu} linker LD
55 @ifset VERSION_PACKAGE
56 @value{VERSION_PACKAGE}
58 version @value{VERSION}.
60 Copyright @copyright{} 1991-2024 Free Software Foundation, Inc.
62 Permission is granted to copy, distribute and/or modify this document
63 under the terms of the GNU Free Documentation License, Version 1.3
64 or any later version published by the Free Software Foundation;
65 with no Invariant Sections, with no Front-Cover Texts, and with no
66 Back-Cover Texts. A copy of the license is included in the
67 section entitled ``GNU Free Documentation License''.
71 @setchapternewpage odd
72 @settitle The GNU linker
77 @ifset VERSION_PACKAGE
78 @subtitle @value{VERSION_PACKAGE}
80 @subtitle Version @value{VERSION}
81 @author Steve Chamberlain
82 @author Ian Lance Taylor
87 \hfill Red Hat Inc\par
88 \hfill nickc\@redhat.com, doc\@redhat.com\par
89 \hfill {\it The GNU linker}\par
90 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
92 \global\parindent=0pt % Steve likes it this way.
95 @vskip 0pt plus 1filll
96 @c man begin COPYRIGHT
97 Copyright @copyright{} 1991-2024 Free Software Foundation, Inc.
99 Permission is granted to copy, distribute and/or modify this document
100 under the terms of the GNU Free Documentation License, Version 1.3
101 or any later version published by the Free Software Foundation;
102 with no Invariant Sections, with no Front-Cover Texts, and with no
103 Back-Cover Texts. A copy of the license is included in the
104 section entitled ``GNU Free Documentation License''.
110 @c FIXME: Talk about importance of *order* of args, cmds to linker!
115 This file documents the @sc{gnu} linker ld
116 @ifset VERSION_PACKAGE
117 @value{VERSION_PACKAGE}
119 version @value{VERSION}.
121 This document is distributed under the terms of the GNU Free
122 Documentation License version 1.3. A copy of the license is included
123 in the section entitled ``GNU Free Documentation License''.
126 * Overview:: Overview
127 * Invocation:: Invocation
128 * Scripts:: Linker Scripts
129 * Plugins:: Linker Plugins
130 * Special Sections:: Special Sections
132 * Machine Dependent:: Machine Dependent Features
136 * H8/300:: ld and the H8/300
139 * Renesas:: ld and other Renesas micros
142 * ARM:: ld and the ARM family
145 * M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families
148 * HPPA ELF32:: ld and HPPA 32-bit ELF
151 * M68K:: ld and Motorola 68K family
154 * MIPS:: ld and MIPS family
157 * PowerPC ELF32:: ld and PowerPC 32-bit ELF Support
160 * PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
163 * S/390 ELF:: ld and S/390 ELF Support
166 * SPU ELF:: ld and SPU ELF Support
169 * TI COFF:: ld and the TI COFF
172 * Win32:: ld and WIN32 (cygwin/mingw)
175 * Xtensa:: ld and Xtensa Processors
178 @ifclear SingleFormat
181 @c Following blank line required for remaining bug in makeinfo conds/menus
183 * Reporting Bugs:: Reporting Bugs
184 * MRI:: MRI Compatible Script Files
185 * GNU Free Documentation License:: GNU Free Documentation License
186 * LD Index:: LD Index
193 @cindex @sc{gnu} linker
194 @cindex what is this?
197 @c man begin SYNOPSIS
198 ld [@b{options}] @var{objfile} @dots{}
202 ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
203 the Info entries for @file{binutils} and
208 @c man begin DESCRIPTION
210 @command{ld} combines a number of object and archive files, relocates
211 their data and ties up symbol references. Usually the last step in
212 compiling a program is to run @command{ld}.
214 @command{ld} accepts Linker Command Language files written in
215 a superset of AT&T's Link Editor Command Language syntax,
216 to provide explicit and total control over the linking process.
220 This man page does not describe the command language; see the
221 @command{ld} entry in @code{info} for full details on the command
222 language and 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 @anchor{unrecognised-input-files}
306 If the linker cannot recognize the format of an object file, it will
307 assume that it is a linker script. A script specified in this way
308 augments the main linker script used for the link (either the default
309 linker script or the one specified by using @samp{-T}). This feature
310 permits the linker to link against a file which appears to be an object
311 or an archive, but actually merely defines some symbol values, or uses
312 @code{INPUT} or @code{GROUP} to load other objects. Specifying a
313 script in this way merely augments the main linker script, with the
314 extra commands placed after the main script; use the @samp{-T} option
315 to replace the default linker script entirely, but note the effect of
316 the @code{INSERT} command. @xref{Scripts}.
318 For options whose names are a single letter,
319 option arguments must either follow the option letter without intervening
320 whitespace, or be given as separate arguments immediately following the
321 option that requires them.
323 For options whose names are multiple letters, either one dash or two can
324 precede the option name; for example, @samp{-trace-symbol} and
325 @samp{--trace-symbol} are equivalent. Note---there is one exception to
326 this rule. Multiple letter options that start with a lower case 'o' can
327 only be preceded by two dashes. This is to reduce confusion with the
328 @samp{-o} option. So for example @samp{-omagic} sets the output file
329 name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
332 Arguments to multiple-letter options must either be separated from the
333 option name by an equals sign, or be given as separate arguments
334 immediately following the option that requires them. For example,
335 @samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
336 Unique abbreviations of the names of multiple-letter options are
339 Note---if the linker is being invoked indirectly, via a compiler driver
340 (e.g. @samp{gcc}) then all the linker command-line options should be
341 prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
342 compiler driver) like this:
345 gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
348 This is important, because otherwise the compiler driver program may
349 silently drop the linker options, resulting in a bad link. Confusion
350 may also arise when passing options that require values through a
351 driver, as the use of a space between option and argument acts as
352 a separator, and causes the driver to pass only the option to the linker
353 and the argument to the compiler. In this case, it is simplest to use
354 the joined forms of both single- and multiple-letter options, such as:
357 gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
360 Here is a table of the generic command-line switches accepted by the GNU
364 @include at-file.texi
366 @kindex -a @var{keyword}
367 @item -a @var{keyword}
368 This option is supported for HP/UX compatibility. The @var{keyword}
369 argument must be one of the strings @samp{archive}, @samp{shared}, or
370 @samp{default}. @samp{-aarchive} is functionally equivalent to
371 @samp{-Bstatic}, and the other two keywords are functionally equivalent
372 to @samp{-Bdynamic}. This option may be used any number of times.
374 @kindex --audit @var{AUDITLIB}
375 @item --audit @var{AUDITLIB}
376 Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
377 @var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
378 specified in the library. If specified multiple times @code{DT_AUDIT}
379 will contain a colon separated list of audit interfaces to use. If the linker
380 finds an object with an audit entry while searching for shared libraries,
381 it will add a corresponding @code{DT_DEPAUDIT} entry in the output file.
382 This option is only meaningful on ELF platforms supporting the rtld-audit
385 @ifclear SingleFormat
386 @cindex binary input format
387 @kindex -b @var{format}
388 @kindex --format=@var{format}
391 @item -b @var{input-format}
392 @itemx --format=@var{input-format}
393 @command{ld} may be configured to support more than one kind of object
394 file. If your @command{ld} is configured this way, you can use the
395 @samp{-b} option to specify the binary format for input object files
396 that follow this option on the command line. Even when @command{ld} is
397 configured to support alternative object formats, you don't usually need
398 to specify this, as @command{ld} should be configured to expect as a
399 default input format the most usual format on each machine.
400 @var{input-format} is a text string, the name of a particular format
401 supported by the BFD libraries. (You can list the available binary
402 formats with @samp{objdump -i}.)
405 You may want to use this option if you are linking files with an unusual
406 binary format. You can also use @samp{-b} to switch formats explicitly (when
407 linking object files of different formats), by including
408 @samp{-b @var{input-format}} before each group of object files in a
411 The default format is taken from the environment variable
416 You can also define the input format from a script, using the command
419 see @ref{Format Commands}.
423 @kindex -c @var{MRI-cmdfile}
424 @kindex --mri-script=@var{MRI-cmdfile}
425 @cindex compatibility, MRI
426 @item -c @var{MRI-commandfile}
427 @itemx --mri-script=@var{MRI-commandfile}
428 For compatibility with linkers produced by MRI, @command{ld} accepts script
429 files written in an alternate, restricted command language, described in
431 @ref{MRI,,MRI Compatible Script Files}.
434 the MRI Compatible Script Files section of GNU ld documentation.
436 Introduce MRI script files with
437 the option @samp{-c}; use the @samp{-T} option to run linker
438 scripts written in the general-purpose @command{ld} scripting language.
439 If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
440 specified by any @samp{-L} options.
442 @cindex common allocation
449 These three options are equivalent; multiple forms are supported for
450 compatibility with other linkers. They assign space to common symbols
451 even if a relocatable output file is specified (with @samp{-r}). The
452 script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
453 @xref{Miscellaneous Commands}.
455 @kindex --depaudit @var{AUDITLIB}
456 @kindex -P @var{AUDITLIB}
457 @item --depaudit @var{AUDITLIB}
458 @itemx -P @var{AUDITLIB}
459 Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
460 @var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
461 specified in the library. If specified multiple times @code{DT_DEPAUDIT}
462 will contain a colon separated list of audit interfaces to use. This
463 option is only meaningful on ELF platforms supporting the rtld-audit interface.
464 The -P option is provided for Solaris compatibility.
466 @kindex --enable-linker-version
467 @item --enable-linker-version
468 Enables the @code{LINKER_VERSION} linker script directive, described
469 in @ref{Output Section Data}. If this directive is used in a linker
470 script and this option has been enabled then a string containing the
471 linker version will be inserted at the current point.
473 Note - this location of this option on the linker command line is
474 significant. It will only affect linker scripts that come after it on
475 the command line, or which are built into the linker.
477 @kindex --disable-linker-version
478 @item --disable-linker-version
479 Disables the @code{LINKER_VERSION} linker script directive, so that it
480 does not insert a version string. This is the default.
482 @kindex --enable-non-contiguous-regions
483 @item --enable-non-contiguous-regions
484 This option avoids generating an error if an input section does not
485 fit a matching output section. The linker tries to allocate the input
486 section to subseque nt matching output sections, and generates an
487 error only if no output section is large enough. This is useful when
488 several non-contiguous memory regions are available and the input
489 section does not require a particular one. The order in which input
490 sections are evaluated does not change, for instance:
494 MEM1 (rwx) : ORIGIN = 0x1000, LENGTH = 0x14
495 MEM2 (rwx) : ORIGIN = 0x1000, LENGTH = 0x40
496 MEM3 (rwx) : ORIGIN = 0x2000, LENGTH = 0x40
499 mem1 : @{ *(.data.*); @} > MEM1
500 mem2 : @{ *(.data.*); @} > MEM2
501 mem3 : @{ *(.data.*); @} > MEM3
509 results in .data.1 affected to mem1, and .data.2 and .data.3
510 affected to mem2, even though .data.3 would fit in mem3.
513 This option is incompatible with INSERT statements because it changes
514 the way input sections are mapped to output sections.
516 @kindex --enable-non-contiguous-regions-warnings
517 @item --enable-non-contiguous-regions-warnings
518 This option enables warnings when
519 @code{--enable-non-contiguous-regions} allows possibly unexpected
520 matches in sections mapping, potentially leading to silently
521 discarding a section instead of failing because it does not fit any
524 @cindex entry point, from command line
525 @kindex -e @var{entry}
526 @kindex --entry=@var{entry}
528 @itemx --entry=@var{entry}
529 Use @var{entry} as the explicit symbol for beginning execution of your
530 program, rather than the default entry point. If there is no symbol
531 named @var{entry}, the linker will try to parse @var{entry} as a number,
532 and use that as the entry address (the number will be interpreted in
533 base 10; you may use a leading @samp{0x} for base 16, or a leading
534 @samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults
535 and other ways of specifying the entry point.
537 @kindex --exclude-libs
538 @item --exclude-libs @var{lib},@var{lib},...
539 Specifies a list of archive libraries from which symbols should not be automatically
540 exported. The library names may be delimited by commas or colons. Specifying
541 @code{--exclude-libs ALL} excludes symbols in all archive libraries from
542 automatic export. This option is available only for the i386 PE targeted
543 port of the linker and for ELF targeted ports. For i386 PE, symbols
544 explicitly listed in a .def file are still exported, regardless of this
545 option. For ELF targeted ports, symbols affected by this option will
546 be treated as hidden.
548 @kindex --exclude-modules-for-implib
549 @item --exclude-modules-for-implib @var{module},@var{module},...
550 Specifies a list of object files or archive members, from which symbols
551 should not be automatically exported, but which should be copied wholesale
552 into the import library being generated during the link. The module names
553 may be delimited by commas or colons, and must match exactly the filenames
554 used by @command{ld} to open the files; for archive members, this is simply
555 the member name, but for object files the name listed must include and
556 match precisely any path used to specify the input file on the linker's
557 command-line. This option is available only for the i386 PE targeted port
558 of the linker. Symbols explicitly listed in a .def file are still exported,
559 regardless of this option.
561 @cindex dynamic symbol table
563 @kindex --export-dynamic
564 @kindex --no-export-dynamic
566 @itemx --export-dynamic
567 @itemx --no-export-dynamic
568 When creating a dynamically linked executable, using the @option{-E}
569 option or the @option{--export-dynamic} option causes the linker to add
570 all symbols to the dynamic symbol table. The dynamic symbol table is the
571 set of symbols which are visible from dynamic objects at run time.
573 If you do not use either of these options (or use the
574 @option{--no-export-dynamic} option to restore the default behavior), the
575 dynamic symbol table will normally contain only those symbols which are
576 referenced by some dynamic object mentioned in the link.
578 If you use @code{dlopen} to load a dynamic object which needs to refer
579 back to the symbols defined by the program, rather than some other
580 dynamic object, then you will probably need to use this option when
581 linking the program itself.
583 You can also use the dynamic list to control what symbols should
584 be added to the dynamic symbol table if the output format supports it.
585 See the description of @samp{--dynamic-list}.
587 Note that this option is specific to ELF targeted ports. PE targets
588 support a similar function to export all symbols from a DLL or EXE; see
589 the description of @samp{--export-all-symbols} below.
591 @kindex --export-dynamic-symbol=@var{glob}
592 @cindex export dynamic symbol
593 @item --export-dynamic-symbol=@var{glob}
594 When creating a dynamically linked executable, symbols matching
595 @var{glob} will be added to the dynamic symbol table. When creating a
596 shared library, references to symbols matching @var{glob} will not be
597 bound to the definitions within the shared library. This option is a
598 no-op when creating a shared library and @samp{-Bsymbolic} or
599 @samp{--dynamic-list} are not specified. This option is only meaningful
600 on ELF platforms which support shared libraries.
602 @kindex --export-dynamic-symbol-list=@var{file}
603 @cindex export dynamic symbol list
604 @item --export-dynamic-symbol-list=@var{file}
605 Specify a @samp{--export-dynamic-symbol} for each pattern in the file.
606 The format of the file is the same as the version node without
607 scope and node name. See @ref{VERSION} for more information.
609 @ifclear SingleFormat
610 @cindex big-endian objects
614 Link big-endian objects. This affects the default output format.
616 @cindex little-endian objects
619 Link little-endian objects. This affects the default output format.
622 @kindex -f @var{name}
623 @kindex --auxiliary=@var{name}
625 @itemx --auxiliary=@var{name}
626 When creating an ELF shared object, set the internal DT_AUXILIARY field
627 to the specified name. This tells the dynamic linker that the symbol
628 table of the shared object should be used as an auxiliary filter on the
629 symbol table of the shared object @var{name}.
631 If you later link a program against this filter object, then, when you
632 run the program, the dynamic linker will see the DT_AUXILIARY field. If
633 the dynamic linker resolves any symbols from the filter object, it will
634 first check whether there is a definition in the shared object
635 @var{name}. If there is one, it will be used instead of the definition
636 in the filter object. The shared object @var{name} need not exist.
637 Thus the shared object @var{name} may be used to provide an alternative
638 implementation of certain functions, perhaps for debugging or for
639 machine-specific performance.
641 This option may be specified more than once. The DT_AUXILIARY entries
642 will be created in the order in which they appear on the command line.
644 @kindex -F @var{name}
645 @kindex --filter=@var{name}
647 @itemx --filter=@var{name}
648 When creating an ELF shared object, set the internal DT_FILTER field to
649 the specified name. This tells the dynamic linker that the symbol table
650 of the shared object which is being created should be used as a filter
651 on the symbol table of the shared object @var{name}.
653 If you later link a program against this filter object, then, when you
654 run the program, the dynamic linker will see the DT_FILTER field. The
655 dynamic linker will resolve symbols according to the symbol table of the
656 filter object as usual, but it will actually link to the definitions
657 found in the shared object @var{name}. Thus the filter object can be
658 used to select a subset of the symbols provided by the object
661 Some older linkers used the @option{-F} option throughout a compilation
662 toolchain for specifying object-file format for both input and output
664 @ifclear SingleFormat
665 The @sc{gnu} linker uses other mechanisms for this purpose: the
666 @option{-b}, @option{--format}, @option{--oformat} options, the
667 @code{TARGET} command in linker scripts, and the @code{GNUTARGET}
668 environment variable.
670 The @sc{gnu} linker will ignore the @option{-F} option when not
671 creating an ELF shared object.
673 @cindex finalization function
674 @kindex -fini=@var{name}
675 @item -fini=@var{name}
676 When creating an ELF executable or shared object, call NAME when the
677 executable or shared object is unloaded, by setting DT_FINI to the
678 address of the function. By default, the linker uses @code{_fini} as
679 the function to call.
683 Ignored. Provided for compatibility with other tools.
685 @kindex -G @var{value}
686 @kindex --gpsize=@var{value}
689 @itemx --gpsize=@var{value}
690 Set the maximum size of objects to be optimized using the GP register to
691 @var{size}. This is only meaningful for object file formats such as
692 MIPS ELF that support putting large and small objects into different
693 sections. This is ignored for other object file formats.
695 @cindex runtime library name
696 @kindex -h @var{name}
697 @kindex -soname=@var{name}
699 @itemx -soname=@var{name}
700 When creating an ELF shared object, set the internal DT_SONAME field to
701 the specified name. When an executable is linked with a shared object
702 which has a DT_SONAME field, then when the executable is run the dynamic
703 linker will attempt to load the shared object specified by the DT_SONAME
704 field rather than using the file name given to the linker.
707 @cindex incremental link
709 Perform an incremental link (same as option @samp{-r}).
711 @cindex initialization function
712 @kindex -init=@var{name}
713 @item -init=@var{name}
714 When creating an ELF executable or shared object, call NAME when the
715 executable or shared object is loaded, by setting DT_INIT to the address
716 of the function. By default, the linker uses @code{_init} as the
719 @cindex archive files, from cmd line
720 @kindex -l @var{namespec}
721 @kindex --library=@var{namespec}
722 @item -l @var{namespec}
723 @itemx --library=@var{namespec}
724 Add the archive or object file specified by @var{namespec} to the
725 list of files to link. This option may be used any number of times.
726 If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
727 will search the library path for a file called @var{filename}, otherwise it
728 will search the library path for a file called @file{lib@var{namespec}.a}.
730 On systems which support shared libraries, @command{ld} may also search for
731 files other than @file{lib@var{namespec}.a}. Specifically, on ELF
732 and SunOS systems, @command{ld} will search a directory for a library
733 called @file{lib@var{namespec}.so} before searching for one called
734 @file{lib@var{namespec}.a}. (By convention, a @code{.so} extension
735 indicates a shared library.) Note that this behavior does not apply
736 to @file{:@var{filename}}, which always specifies a file called
739 The linker will search an archive only once, at the location where it is
740 specified on the command line. If the archive defines a symbol which
741 was undefined in some object which appeared before the archive on the
742 command line, the linker will include the appropriate file(s) from the
743 archive. However, an undefined symbol in an object appearing later on
744 the command line will not cause the linker to search the archive again.
746 See the @option{-(} option for a way to force the linker to search
747 archives multiple times.
749 You may list the same archive multiple times on the command line.
752 This type of archive searching is standard for Unix linkers. However,
753 if you are using @command{ld} on AIX, note that it is different from the
754 behaviour of the AIX linker.
757 @cindex search directory, from cmd line
759 @kindex --library-path=@var{dir}
760 @item -L @var{searchdir}
761 @itemx --library-path=@var{searchdir}
763 Add path @var{searchdir} to the list of paths that @command{ld} will search
764 for archive libraries and @command{ld} control scripts. You may use this
765 option any number of times. The directories are searched in the order
766 in which they are specified on the command line. Directories specified
767 on the command line are searched before the default directories. All
768 @option{-L} options apply to all @option{-l} options, regardless of the
769 order in which the options appear. @option{-L} options do not affect
770 how @command{ld} searches for a linker script unless @option{-T}
773 If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this
774 prefix will be replaced by the @dfn{sysroot prefix}, controlled by the
775 @samp{--sysroot} option, or specified when the linker is configured.
778 The default set of paths searched (without being specified with
779 @samp{-L}) depends on which emulation mode @command{ld} is using, and in
780 some cases also on how it was configured. @xref{Environment}.
783 The paths can also be specified in a link script with the
784 @code{SEARCH_DIR} command. Directories specified this way are searched
785 at the point in which the linker script appears in the command line.
788 @kindex -m @var{emulation}
789 @item -m @var{emulation}
790 Emulate the @var{emulation} linker. You can list the available
791 emulations with the @samp{--verbose} or @samp{-V} options.
793 If the @samp{-m} option is not used, the emulation is taken from the
794 @code{LDEMULATION} environment variable, if that is defined.
796 Otherwise, the default emulation depends upon how the linker was
799 @cindex remapping inputs
800 @kindex --remap-inputs=@file{pattern}=@file{filename}
801 @kindex --remap-inputs-file=@file{file}
802 @item --remap-inputs=@file{pattern}=@file{filename}
803 @itemx --remap-inputs-file=@file{file}
804 These options allow the names of input files to be changed before the
805 linker attempts to open them. The option
806 @option{--remap-inputs=foo.o=bar.o} will cause any attempt to load a
807 file called @file{foo.o} to instead try to load a file called
808 @file{bar.o}. Wildcard patterns are permitted in the first filename,
809 so @option{--remap-inputs=foo*.o=bar.o} will rename any input file that
810 matches @file{foo*.o} to @file{bar.o}.
812 An alternative form of the option
813 @option{--remap-inputs-file=filename} allows the remappings to be read
814 from a file. Each line in the file can contain a single remapping.
815 Blank lines are ignored. Anything from a hash character (@samp{#}) to
816 the end of a line is considered to be a comment and is also ignored.
817 The mapping pattern can be separated from the filename by whitespace
818 or an equals (@samp{=}) character.
820 The options can be specified multiple times. Their contents
821 accumulate. The remappings will be processed in the order in which
822 they occur on the command line, and if they come from a file, in the
823 order in which they occur in the file. If a match is made, no further
824 checking for that filename will be performed.
826 If the replacement filename is @file{/dev/null} or just @file{NUL}
827 then the remapping will actually cause the input file to be ignored.
828 This can be a convenient way to experiment with removing input files
829 from a complicated build environment.
831 Note that this option is position dependent and only affects filenames
832 that come after it on the command line. Thus:
835 ld foo.o --remap-inputs=foo.o=bar.o
838 Will have no effect, whereas:
841 ld --remap-inputs=foo.o=bar.o foo.o
844 Will rename the input file @file{foo.o} to @file{bar.o}.
846 Note - these options also affect files referenced by @emph{INPUT}
847 statements in linker scripts. But since linker scripts are processed
848 after the entire command line is read, the position of the remap
849 options on the command line is not significant.
851 If the @option{verbose} option is enabled then any mappings that match
852 will be reported, although again the @option{verbose} option needs to
853 be enabled on the command line @emph{before} the remaped filenames
856 If the @option{-Map} or @option{--print-map} options are enabled then
857 the remapping list will be included in the map output.
864 Print a link map to the standard output. A link map provides
865 information about the link, including the following:
869 Where object files are mapped into memory.
871 How common symbols are allocated.
873 All archive members included in the link, with a mention of the symbol
874 which caused the archive member to be brought in.
876 The values assigned to symbols.
878 Note - symbols whose values are computed by an expression which
879 involves a reference to a previous value of the same symbol may not
880 have correct result displayed in the link map. This is because the
881 linker discards intermediate results and only retains the final value
882 of an expression. Under such circumstances the linker will display
883 the final value enclosed by square brackets. Thus for example a
884 linker script containing:
892 will produce the following output in the link map if the @option{-M}
897 [0x0000000c] foo = (foo * 0x4)
898 [0x0000000c] foo = (foo + 0x8)
901 See @ref{Expressions} for more information about expressions in linker
905 How GNU properties are merged.
907 When the linker merges input .note.gnu.property sections into one output
908 .note.gnu.property section, some properties are removed or updated.
909 These actions are reported in the link map. For example:
912 Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
915 This indicates that property 0xc0000002 is removed from output when
916 merging properties in @file{foo.o}, whose property 0xc0000002 value
917 is 0x1, and @file{bar.o}, which doesn't have property 0xc0000002.
920 Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
923 This indicates that property 0xc0010001 value is updated to 0x1 in output
924 when merging properties in @file{foo.o}, whose 0xc0010001 property value
925 is 0x1, and @file{bar.o}, whose 0xc0010001 property value is 0x1.
928 On some ELF targets, a list of fixups inserted by @option{--relax}
931 foo.o: Adjusting branch at 0x00000008 towards "far" in section .text
934 This indicates that the branch at 0x00000008 in foo.o, targeting
935 the symbol "far" in section .text, has been replaced by a trampoline.
939 @cindex link map discarded
940 @kindex --print-map-discarded
941 @kindex --no-print-map-discarded
942 @item --print-map-discarded
943 @itemx --no-print-map-discarded
944 Print (or do not print) the list of discarded and garbage collected sections
945 in the link map. Enabled by default.
947 @kindex --print-map-locals
948 @kindex --no-print-map-locals
949 @item --print-map-locals
950 @itemx --no-print-map-locals
951 Print (or do not print) local symbols in the link map. Local symbols
952 will have the text @samp{(local)} printed before their name, and will
953 be listed after all of the global symbols in a given section.
954 Temporary local symbols (typically those that start with @samp{.L})
955 will not be included in the output. Disabled by default.
958 @cindex read-only text
963 Turn off page alignment of sections, and disable linking against shared
964 libraries. If the output format supports Unix style magic numbers,
965 mark the output as @code{NMAGIC}.
969 @cindex read/write from cmd line
973 Set the text and data sections to be readable and writable. Also, do
974 not page-align the data segment, and disable linking against shared
975 libraries. If the output format supports Unix style magic numbers,
976 mark the output as @code{OMAGIC}. Note: Although a writable text section
977 is allowed for PE-COFF targets, it does not conform to the format
978 specification published by Microsoft.
983 This option negates most of the effects of the @option{-N} option. It
984 sets the text section to be read-only, and forces the data segment to
985 be page-aligned. Note - this option does not enable linking against
986 shared libraries. Use @option{-Bdynamic} for this.
988 @kindex -o @var{output}
989 @kindex --output=@var{output}
990 @cindex naming the output file
991 @item -o @var{output}
992 @itemx --output=@var{output}
993 Use @var{output} as the name for the program produced by @command{ld}; if this
994 option is not specified, the name @file{a.out} is used by default. The
995 script command @code{OUTPUT} can also specify the output file name.
997 @kindex --dependency-file=@var{depfile}
998 @cindex dependency file
999 @item --dependency-file=@var{depfile}
1000 Write a @dfn{dependency file} to @var{depfile}. This file contains a rule
1001 suitable for @code{make} describing the output file and all the input files
1002 that were read to produce it. The output is similar to the compiler's
1003 output with @samp{-M -MP} (@pxref{Preprocessor Options,, Options
1004 Controlling the Preprocessor, gcc.info, Using the GNU Compiler
1005 Collection}). Note that there is no option like the compiler's @samp{-MM},
1006 to exclude ``system files'' (which is not a well-specified concept in the
1007 linker, unlike ``system headers'' in the compiler). So the output from
1008 @samp{--dependency-file} is always specific to the exact state of the
1009 installation where it was produced, and should not be copied into
1010 distributed makefiles without careful editing.
1012 @kindex -O @var{level}
1013 @cindex generating optimized output
1014 @item -O @var{level}
1015 If @var{level} is a numeric values greater than zero @command{ld} optimizes
1016 the output. This might take significantly longer and therefore probably
1017 should only be enabled for the final binary. At the moment this
1018 option only affects ELF shared library generation. Future releases of
1019 the linker may make more use of this option. Also currently there is
1020 no difference in the linker's behaviour for different non-zero values
1021 of this option. Again this may change with future releases.
1023 @kindex -plugin @var{name}
1024 @item -plugin @var{name}
1025 Involve a plugin in the linking process. The @var{name} parameter is
1026 the absolute filename of the plugin. Usually this parameter is
1027 automatically added by the complier, when using link time
1028 optimization, but users can also add their own plugins if they so
1031 Note that the location of the compiler originated plugins is different
1032 from the place where the @command{ar}, @command{nm} and
1033 @command{ranlib} programs search for their plugins. In order for
1034 those commands to make use of a compiler based plugin it must first be
1035 copied into the @file{$@{libdir@}/bfd-plugins} directory. All gcc
1036 based linker plugins are backward compatible, so it is sufficient to
1037 just copy in the newest one.
1039 @kindex --push-state
1040 @cindex push state governing input file handling
1042 The @option{--push-state} allows one to preserve the current state of the
1043 flags which govern the input file handling so that they can all be
1044 restored with one corresponding @option{--pop-state} option.
1046 The option which are covered are: @option{-Bdynamic}, @option{-Bstatic},
1047 @option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared},
1048 @option{-static}, @option{-N}, @option{-n}, @option{--whole-archive},
1049 @option{--no-whole-archive}, @option{-r}, @option{-Ur},
1050 @option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries},
1051 @option{--as-needed}, @option{--no-as-needed}, and @option{-a}.
1053 One target for this option are specifications for @file{pkg-config}. When
1054 used with the @option{--libs} option all possibly needed libraries are
1055 listed and then possibly linked with all the time. It is better to return
1056 something as follows:
1059 -Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
1063 @cindex pop state governing input file handling
1065 Undoes the effect of --push-state, restores the previous values of the
1066 flags governing input file handling.
1069 @kindex --emit-relocs
1070 @cindex retain relocations in final executable
1072 @itemx --emit-relocs
1073 Leave relocation sections and contents in fully linked executables.
1074 Post link analysis and optimization tools may need this information in
1075 order to perform correct modifications of executables. This results
1076 in larger executables.
1078 This option is currently only supported on ELF platforms.
1080 @kindex --force-dynamic
1081 @cindex forcing the creation of dynamic sections
1082 @item --force-dynamic
1083 Force the output file to have dynamic sections. This option is specific
1086 @cindex partial link
1087 @cindex relocatable output
1089 @kindex --relocatable
1091 @itemx --relocatable
1092 Generate relocatable output---i.e., generate an output file that can in
1093 turn serve as input to @command{ld}. This is often called @dfn{partial
1094 linking}. As a side effect, in environments that support standard Unix
1095 magic numbers, this option also sets the output file's magic number to
1097 @c ; see @option{-N}.
1098 If this option is not specified, an absolute file is produced. When
1099 linking C++ programs, this option @emph{will not} resolve references to
1100 constructors; to do that, use @samp{-Ur}.
1102 When an input file does not have the same format as the output file,
1103 partial linking is only supported if that input file does not contain any
1104 relocations. Different output formats can have further restrictions; for
1105 example some @code{a.out}-based formats do not support partial linking
1106 with input files in other formats at all.
1108 This option does the same thing as @samp{-i}.
1110 @kindex -R @var{file}
1111 @kindex --just-symbols=@var{file}
1112 @cindex symbol-only input
1113 @item -R @var{filename}
1114 @itemx --just-symbols=@var{filename}
1115 Read symbol names and their addresses from @var{filename}, but do not
1116 relocate it or include it in the output. This allows your output file
1117 to refer symbolically to absolute locations of memory defined in other
1118 programs. You may use this option more than once.
1120 For compatibility with other ELF linkers, if the @option{-R} option is
1121 followed by a directory name, rather than a file name, it is treated as
1122 the @option{-rpath} option.
1126 @cindex strip all symbols
1129 Omit all symbol information from the output file.
1132 @kindex --strip-debug
1133 @cindex strip debugger symbols
1135 @itemx --strip-debug
1136 Omit debugger symbol information (but not all symbols) from the output file.
1138 @kindex --strip-discarded
1139 @kindex --no-strip-discarded
1140 @item --strip-discarded
1141 @itemx --no-strip-discarded
1142 Omit (or do not omit) global symbols defined in discarded sections.
1145 @kindex -plugin-save-temps
1146 @item -plugin-save-temps
1147 Store the plugin ``temporary'' intermediate files permanently.
1151 @cindex input files, displaying
1154 Print the names of the input files as @command{ld} processes them. If
1155 @samp{-t} is given twice then members within archives are also printed.
1156 @samp{-t} output is useful to generate a list of all the object files
1157 and scripts involved in linking, for example, when packaging files for
1158 a linker bug report.
1160 @kindex -T @var{script}
1161 @kindex --script=@var{script}
1162 @cindex script files
1163 @item -T @var{scriptfile}
1164 @itemx --script=@var{scriptfile}
1165 Use @var{scriptfile} as the linker script. This script replaces
1166 @command{ld}'s default linker script (rather than adding to it),
1167 unless the script contains @code{INSERT}, so @var{commandfile} must
1168 specify everything necessary to describe the output file.
1171 If @var{scriptfile} does not exist in the current directory, @code{ld}
1172 looks for it in the directories specified by any preceding @samp{-L}
1175 Command line options that appear before the @option{-T} option can
1176 affect the script, but command line options that appear after it do
1179 Multiple @samp{-T} options will accumulate if they are augmenting the
1180 current script, otherwise the last, non-augmenting, @option{-T} option
1183 There are other ways of specifying linker scripts. See
1184 @xref{--default-script}, @xref{--section-ordering-file} and
1185 @xref{unrecognised-input-files}.
1187 @kindex -dT @var{script}
1188 @kindex --default-script=@var{script}
1189 @cindex script files
1190 @item -dT @var{scriptfile}
1191 @itemx --default-script=@var{scriptfile}
1192 @anchor{--default-script}
1193 Use @var{scriptfile} as the default linker script. @xref{Scripts}.
1195 This option is similar to the @option{--script} option except that
1196 processing of the script is delayed until after the rest of the
1197 command line has been processed. This allows options placed after the
1198 @option{--default-script} option on the command line to affect the
1199 behaviour of the linker script, which can be important when the linker
1200 command line cannot be directly controlled by the user. (eg because
1201 the command line is being constructed by another tool, such as
1204 @kindex -u @var{symbol}
1205 @kindex --undefined=@var{symbol}
1206 @cindex undefined symbol
1207 @item -u @var{symbol}
1208 @itemx --undefined=@var{symbol}
1209 Force @var{symbol} to be entered in the output file as an undefined
1210 symbol. Doing this may, for example, trigger linking of additional
1211 modules from standard libraries. @samp{-u} may be repeated with
1212 different option arguments to enter additional undefined symbols. This
1213 option is equivalent to the @code{EXTERN} linker script command.
1215 If this option is being used to force additional modules to be pulled
1216 into the link, and if it is an error for the symbol to remain
1217 undefined, then the option @option{--require-defined} should be used
1220 @kindex --require-defined=@var{symbol}
1221 @cindex symbols, require defined
1222 @cindex defined symbol
1223 @item --require-defined=@var{symbol}
1224 Require that @var{symbol} is defined in the output file. This option
1225 is the same as option @option{--undefined} except that if @var{symbol}
1226 is not defined in the output file then the linker will issue an error
1227 and exit. The same effect can be achieved in a linker script by using
1228 @code{EXTERN}, @code{ASSERT} and @code{DEFINED} together. This option
1229 can be used multiple times to require additional symbols.
1232 @cindex constructors
1235 For programs that do not use constructors or destructors, or for ELF
1236 based systems this option is equivalent to @option{-r}: it generates
1237 relocatable output---i.e., an output file that can in turn serve as
1238 input to @command{ld}. For other binaries however the @option{-Ur}
1239 option is similar to @option{-r} but it also resolves references to
1240 constructors and destructors.
1242 For those systems where @option{-r} and @option{-Ur} behave
1243 differently, it does not work to use @option{-Ur} on files that were
1244 themselves linked with @option{-Ur}; once the constructor table has
1245 been built, it cannot be added to. Use @option{-Ur} only for the last
1246 partial link, and @option{-r} for the others.
1248 @kindex --orphan-handling=@var{MODE}
1249 @cindex orphan sections
1250 @cindex sections, orphan
1251 @item --orphan-handling=@var{MODE}
1252 Control how orphan sections are handled. An orphan section is one not
1253 specifically mentioned in a linker script. @xref{Orphan Sections}.
1255 @var{MODE} can have any of the following values:
1259 Orphan sections are placed into a suitable output section following
1260 the strategy described in @ref{Orphan Sections}. The option
1261 @samp{--unique} also affects how sections are placed.
1264 All orphan sections are discarded, by placing them in the
1265 @samp{/DISCARD/} section (@pxref{Output Section Discarding}).
1268 The linker will place the orphan section as for @code{place} and also
1272 The linker will exit with an error if any orphan section is found.
1275 The default if @samp{--orphan-handling} is not given is @code{place}.
1277 @kindex --unique[=@var{SECTION}]
1278 @item --unique[=@var{SECTION}]
1279 Creates a separate output section for every input section matching
1280 @var{SECTION}, or if the optional wildcard @var{SECTION} argument is
1281 missing, for every orphan input section. An orphan section is one not
1282 specifically mentioned in a linker script. You may use this option
1283 multiple times on the command line; It prevents the normal merging of
1284 input sections with the same name, overriding output section assignments
1294 Display the version number for @command{ld}. The @option{-V} option also
1295 lists the supported emulations. See also the description of the
1296 @option{--enable-linker-version} in @ref{Options,,Command-line Options}
1297 which can be used to insert the linker version string into a binary.
1300 @kindex --discard-all
1301 @cindex deleting local symbols
1303 @itemx --discard-all
1304 Delete all local symbols.
1307 @kindex --discard-locals
1308 @cindex local symbols, deleting
1310 @itemx --discard-locals
1311 Delete all temporary local symbols. (These symbols start with
1312 system-specific local label prefixes, typically @samp{.L} for ELF systems
1313 or @samp{L} for traditional a.out systems.)
1315 @kindex -y @var{symbol}
1316 @kindex --trace-symbol=@var{symbol}
1317 @cindex symbol tracing
1318 @item -y @var{symbol}
1319 @itemx --trace-symbol=@var{symbol}
1320 Print the name of each linked file in which @var{symbol} appears. This
1321 option may be given any number of times. On many systems it is necessary
1322 to prepend an underscore.
1324 This option is useful when you have an undefined symbol in your link but
1325 don't know where the reference is coming from.
1327 @kindex -Y @var{path}
1329 Add @var{path} to the default library search path. This option exists
1330 for Solaris compatibility.
1332 @kindex -z @var{keyword}
1333 @item -z @var{keyword}
1334 The recognized keywords are:
1337 @item call-nop=prefix-addr
1338 @itemx call-nop=suffix-nop
1339 @itemx call-nop=prefix-@var{byte}
1340 @itemx call-nop=suffix-@var{byte}
1341 Specify the 1-byte @code{NOP} padding when transforming indirect call
1342 to a locally defined function, foo, via its GOT slot.
1343 @option{call-nop=prefix-addr} generates @code{0x67 call foo}.
1344 @option{call-nop=suffix-nop} generates @code{call foo 0x90}.
1345 @option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
1346 @option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
1347 Supported for i386 and x86_64.
1349 @item cet-report=none
1350 @itemx cet-report=warning
1351 @itemx cet-report=error
1352 Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and
1353 GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property
1354 section. @option{cet-report=none}, which is the default, will make the
1355 linker not report missing properties in input files.
1356 @option{cet-report=warning} will make the linker issue a warning for
1357 missing properties in input files. @option{cet-report=error} will make
1358 the linker issue an error for missing properties in input files.
1359 Note that @option{ibt} will turn off the missing
1360 GNU_PROPERTY_X86_FEATURE_1_IBT property report and @option{shstk} will
1361 turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report.
1362 Supported for Linux/i386 and Linux/x86_64.
1366 Combine multiple dynamic relocation sections and sort to improve
1367 dynamic symbol lookup caching. Do not do this if @samp{nocombreloc}.
1371 Generate common symbols with STT_COMMON type during a relocatable
1372 link. Use STT_OBJECT type if @samp{nocommon}.
1374 @item common-page-size=@var{value}
1375 Set the page size most commonly used to @var{value}. Memory image
1376 layout will be optimized to minimize memory pages if the system is
1377 using pages of this size.
1380 Report unresolved symbol references from regular object files. This
1381 is done even if the linker is creating a non-symbolic shared library.
1382 This option is the inverse of @samp{-z undefs}.
1384 @item dynamic-undefined-weak
1385 @itemx nodynamic-undefined-weak
1386 Make undefined weak symbols dynamic when building a dynamic object,
1387 if they are referenced from a regular object file and not forced local
1388 by symbol visibility or versioning. Do not make them dynamic if
1389 @samp{nodynamic-undefined-weak}. If neither option is given, a target
1390 may default to either option being in force, or make some other
1391 selection of undefined weak symbols dynamic. Not all targets support
1395 Marks the object as requiring executable stack.
1398 This option is only meaningful when building a shared object. It makes
1399 the symbols defined by this shared object available for symbol resolution
1400 of subsequently loaded libraries.
1403 This option is only meaningful when building a dynamic executable.
1404 This option marks the executable as requiring global auditing by
1405 setting the @code{DF_1_GLOBAUDIT} bit in the @code{DT_FLAGS_1} dynamic
1406 tag. Global auditing requires that any auditing library defined via
1407 the @option{--depaudit} or @option{-P} command-line options be run for
1408 all dynamic objects loaded by the application.
1411 Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
1412 Supported for Linux/i386 and Linux/x86_64.
1415 Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
1416 to indicate compatibility with IBT. This also implies @option{ibtplt}.
1417 Supported for Linux/i386 and Linux/x86_64.
1419 @item indirect-extern-access
1420 @itemx noindirect-extern-access
1421 Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in
1422 .note.gnu.property section to indicate that object file requires
1423 canonical function pointers and cannot be used with copy relocation.
1424 This option also implies @option{noextern-protected-data} and
1425 @option{nocopyreloc}. Supported for i386 and x86-64.
1427 @option{noindirect-extern-access} removes
1428 GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property
1432 This option is only meaningful when building a shared object.
1433 It marks the object so that its runtime initialization will occur
1434 before the runtime initialization of any other objects brought into
1435 the process at the same time. Similarly the runtime finalization of
1436 the object will occur after the runtime finalization of any other
1440 Specify that the dynamic loader should modify its symbol search order
1441 so that symbols in this shared library interpose all other shared
1442 libraries not so marked.
1446 When generating a shared library or other dynamically loadable ELF
1447 object mark it as one that should (by default) only ever be loaded once,
1448 and only in the main namespace (when using @code{dlmopen}). This is
1449 primarily used to mark fundamental libraries such as libc, libpthread et
1450 al which do not usually function correctly unless they are the sole instances
1451 of themselves. This behaviour can be overridden by the @code{dlmopen} caller
1452 and does not apply to certain loading mechanisms (such as audit libraries).
1455 Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U48 in .note.gnu.property section
1456 to indicate compatibility with Intel LAM_U48. Supported for Linux/x86_64.
1459 Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U57 in .note.gnu.property section
1460 to indicate compatibility with Intel LAM_U57. Supported for Linux/x86_64.
1462 @item lam-u48-report=none
1463 @itemx lam-u48-report=warning
1464 @itemx lam-u48-report=error
1465 Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48
1466 property in input .note.gnu.property section.
1467 @option{lam-u48-report=none}, which is the default, will make the
1468 linker not report missing properties in input files.
1469 @option{lam-u48-report=warning} will make the linker issue a warning for
1470 missing properties in input files. @option{lam-u48-report=error} will
1471 make the linker issue an error for missing properties in input files.
1472 Supported for Linux/x86_64.
1474 @item lam-u57-report=none
1475 @itemx lam-u57-report=warning
1476 @itemx lam-u57-report=error
1477 Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57
1478 property in input .note.gnu.property section.
1479 @option{lam-u57-report=none}, which is the default, will make the
1480 linker not report missing properties in input files.
1481 @option{lam-u57-report=warning} will make the linker issue a warning for
1482 missing properties in input files. @option{lam-u57-report=error} will
1483 make the linker issue an error for missing properties in input files.
1484 Supported for Linux/x86_64.
1486 @item lam-report=none
1487 @itemx lam-report=warning
1488 @itemx lam-report=error
1489 Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 and
1490 GNU_PROPERTY_X86_FEATURE_1_LAM_U57 properties in input .note.gnu.property
1491 section. @option{lam-report=none}, which is the default, will make the
1492 linker not report missing properties in input files.
1493 @option{lam-report=warning} will make the linker issue a warning for
1494 missing properties in input files. @option{lam-report=error} will make
1495 the linker issue an error for missing properties in input files.
1496 Supported for Linux/x86_64.
1499 When generating an executable or shared library, mark it to tell the
1500 dynamic linker to defer function call resolution to the point when
1501 the function is called (lazy binding), rather than at load time.
1502 Lazy binding is the default.
1505 Specify that the object's filters be processed immediately at runtime.
1507 @item max-page-size=@var{value}
1508 Set the maximum memory page size supported to @var{value}.
1512 Mark PLT entries with dynamic tags, DT_X86_64_PLT, DT_X86_64_PLTSZ and
1513 DT_X86_64_PLTENT. Since this option stores a non-zero value in the
1514 r_addend field of R_X86_64_JUMP_SLOT relocations, the resulting
1515 executables and shared libraries are incompatible with dynamic linkers,
1516 such as those in older versions of glibc without the change to ignore
1517 r_addend in R_X86_64_GLOB_DAT and R_X86_64_JUMP_SLOT relocations, which
1518 don't ignore the r_addend field of R_X86_64_JUMP_SLOT relocations.
1519 Supported for x86_64.
1522 Allow multiple definitions.
1525 Disable linker generated .dynbss variables used in place of variables
1526 defined in shared libraries. May result in dynamic text relocations.
1529 Specify that the dynamic loader search for dependencies of this object
1530 should ignore any default library search paths.
1533 Specify that the object shouldn't be unloaded at runtime.
1536 Specify that the object is not available to @code{dlopen}.
1539 Specify that the object can not be dumped by @code{dldump}.
1542 Marks the object as not requiring executable stack.
1544 @item noextern-protected-data
1545 Don't treat protected data symbols as external when building a shared
1546 library. This option overrides the linker backend default. It can be
1547 used to work around incorrect relocations against protected data symbols
1548 generated by compiler. Updates on protected data symbols by another
1549 module aren't visible to the resulting shared library. Supported for
1552 @item noreloc-overflow
1553 Disable relocation overflow check. This can be used to disable
1554 relocation overflow check if there will be no dynamic relocation
1555 overflow at run-time. Supported for x86_64.
1558 When generating an executable or shared library, mark it to tell the
1559 dynamic linker to resolve all symbols when the program is started, or
1560 when the shared library is loaded by dlopen, instead of deferring
1561 function call resolution to the point when the function is first
1565 Specify that the object requires @samp{$ORIGIN} handling in paths.
1567 @item pack-relative-relocs
1568 @itemx nopack-relative-relocs
1569 Generate compact relative relocation in position-independent executable
1570 and shared library. It adds @code{DT_RELR}, @code{DT_RELRSZ} and
1571 @code{DT_RELRENT} entries to the dynamic section. It is ignored when
1572 building position-dependent executable and relocatable output.
1573 @option{nopack-relative-relocs} is the default, which disables compact
1574 relative relocation. When linked against the GNU C Library, a
1575 GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is
1576 added to the output. Supported for i386 and x86-64.
1580 Create an ELF @code{PT_GNU_RELRO} segment header in the object. This
1581 specifies a memory segment that should be made read-only after
1582 relocation, if supported. Specifying @samp{common-page-size} smaller
1583 than the system page size will render this protection ineffective.
1584 Don't create an ELF @code{PT_GNU_RELRO} segment if @samp{norelro}.
1586 @item report-relative-reloc
1587 Report dynamic relative relocations generated by linker. Supported for
1588 Linux/i386 and Linux/x86_64.
1591 @itemx nosectionheader
1592 Generate section header. Don't generate section header if
1593 @samp{nosectionheader} is used. @option{sectionheader} is the default.
1596 @itemx noseparate-code
1597 Create separate code @code{PT_LOAD} segment header in the object. This
1598 specifies a memory segment that should contain only instructions and must
1599 be in wholly disjoint pages from any other data. Don't create separate
1600 code @code{PT_LOAD} segment if @samp{noseparate-code} is used.
1603 Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
1604 to indicate compatibility with Intel Shadow Stack. Supported for
1605 Linux/i386 and Linux/x86_64.
1607 @item stack-size=@var{value}
1608 Specify a stack size for an ELF @code{PT_GNU_STACK} segment.
1609 Specifying zero will override any default non-zero sized
1610 @code{PT_GNU_STACK} segment creation.
1613 @itemx nostart-stop-gc
1614 @cindex start-stop-gc
1615 When @samp{--gc-sections} is in effect, a reference from a retained
1616 section to @code{__start_SECNAME} or @code{__stop_SECNAME} causes all
1617 input sections named @code{SECNAME} to also be retained, if
1618 @code{SECNAME} is representable as a C identifier and either
1619 @code{__start_SECNAME} or @code{__stop_SECNAME} is synthesized by the
1620 linker. @samp{-z start-stop-gc} disables this effect, allowing
1621 sections to be garbage collected as if the special synthesized symbols
1622 were not defined. @samp{-z start-stop-gc} has no effect on a
1623 definition of @code{__start_SECNAME} or @code{__stop_SECNAME} in an
1624 object file or linker script. Such a definition will prevent the
1625 linker providing a synthesized @code{__start_SECNAME} or
1626 @code{__stop_SECNAME} respectively, and therefore the special
1627 treatment by garbage collection for those references.
1629 @item start-stop-visibility=@var{value}
1631 @cindex ELF symbol visibility
1632 Specify the ELF symbol visibility for synthesized
1633 @code{__start_SECNAME} and @code{__stop_SECNAME} symbols (@pxref{Input
1634 Section Example}). @var{value} must be exactly @samp{default},
1635 @samp{internal}, @samp{hidden}, or @samp{protected}. If no @samp{-z
1636 start-stop-visibility} option is given, @samp{protected} is used for
1637 compatibility with historical practice. However, it's highly
1638 recommended to use @samp{-z start-stop-visibility=hidden} in new
1639 programs and shared libraries so that these symbols are not exported
1640 between shared objects, which is not usually what's intended.
1645 Report an error if DT_TEXTREL is set, i.e., if the position-independent
1646 or shared object has dynamic relocations in read-only sections. Don't
1647 report an error if @samp{notext} or @samp{textoff}.
1650 Do not report unresolved symbol references from regular object files,
1651 either when creating an executable, or when creating a shared library.
1652 This option is the inverse of @samp{-z defs}.
1655 @itemx nounique-symbol
1656 Avoid duplicated local symbol names in the symbol string table. Append
1657 ".@code{number}" to duplicated local symbol names if @samp{unique-symbol}
1658 is used. @option{nounique-symbol} is the default.
1660 @item x86-64-baseline
1664 Specify the x86-64 ISA level needed in .note.gnu.property section.
1665 @option{x86-64-baseline} generates @code{GNU_PROPERTY_X86_ISA_1_BASELINE}.
1666 @option{x86-64-v2} generates @code{GNU_PROPERTY_X86_ISA_1_V2}.
1667 @option{x86-64-v3} generates @code{GNU_PROPERTY_X86_ISA_1_V3}.
1668 @option{x86-64-v4} generates @code{GNU_PROPERTY_X86_ISA_1_V4}.
1669 Supported for Linux/i386 and Linux/x86_64.
1673 Other keywords are ignored for Solaris compatibility.
1676 @cindex groups of archives
1677 @item -( @var{archives} -)
1678 @itemx --start-group @var{archives} --end-group
1679 The @var{archives} should be a list of archive files. They may be
1680 either explicit file names, or @samp{-l} options.
1682 The specified archives are searched repeatedly until no new undefined
1683 references are created. Normally, an archive is searched only once in
1684 the order that it is specified on the command line. If a symbol in that
1685 archive is needed to resolve an undefined symbol referred to by an
1686 object in an archive that appears later on the command line, the linker
1687 would not be able to resolve that reference. By grouping the archives,
1688 they will all be searched repeatedly until all possible references are
1691 Using this option has a significant performance cost. It is best to use
1692 it only when there are unavoidable circular references between two or
1695 @kindex --accept-unknown-input-arch
1696 @kindex --no-accept-unknown-input-arch
1697 @item --accept-unknown-input-arch
1698 @itemx --no-accept-unknown-input-arch
1699 Tells the linker to accept input files whose architecture cannot be
1700 recognised. The assumption is that the user knows what they are doing
1701 and deliberately wants to link in these unknown input files. This was
1702 the default behaviour of the linker, before release 2.14. The default
1703 behaviour from release 2.14 onwards is to reject such input files, and
1704 so the @samp{--accept-unknown-input-arch} option has been added to
1705 restore the old behaviour.
1708 @kindex --no-as-needed
1710 @itemx --no-as-needed
1711 This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
1712 on the command line after the @option{--as-needed} option. Normally
1713 the linker will add a DT_NEEDED tag for each dynamic library mentioned
1714 on the command line, regardless of whether the library is actually
1715 needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
1716 emitted for a library that @emph{at that point in the link} satisfies a
1717 non-weak undefined symbol reference from a regular object file or, if
1718 the library is not found in the DT_NEEDED lists of other needed libraries, a
1719 non-weak undefined symbol reference from another needed dynamic library.
1720 Object files or libraries appearing on the command line @emph{after}
1721 the library in question do not affect whether the library is seen as
1722 needed. This is similar to the rules for extraction of object files
1723 from archives. @option{--no-as-needed} restores the default behaviour.
1725 Note: On Linux based systems the @option{--as-needed} option also has
1726 an affect on the behaviour of the @option{--rpath} and
1727 @option{--rpath-link} options. See the description of
1728 @option{--rpath-link} for more details.
1730 @kindex --add-needed
1731 @kindex --no-add-needed
1733 @itemx --no-add-needed
1734 These two options have been deprecated because of the similarity of
1735 their names to the @option{--as-needed} and @option{--no-as-needed}
1736 options. They have been replaced by @option{--copy-dt-needed-entries}
1737 and @option{--no-copy-dt-needed-entries}.
1739 @kindex -assert @var{keyword}
1740 @item -assert @var{keyword}
1741 This option is ignored for SunOS compatibility.
1745 @kindex -call_shared
1749 Link against dynamic libraries. This is only meaningful on platforms
1750 for which shared libraries are supported. This option is normally the
1751 default on such platforms. The different variants of this option are
1752 for compatibility with various systems. You may use this option
1753 multiple times on the command line: it affects library searching for
1754 @option{-l} options which follow it.
1758 Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
1759 section. This causes the runtime linker to handle lookups in this
1760 object and its dependencies to be performed only inside the group.
1761 @option{--unresolved-symbols=report-all} is implied. This option is
1762 only meaningful on ELF platforms which support shared libraries.
1772 Do not link against shared libraries. This is only meaningful on
1773 platforms for which shared libraries are supported. The different
1774 variants of this option are for compatibility with various systems. You
1775 may use this option multiple times on the command line: it affects
1776 library searching for @option{-l} options which follow it. This
1777 option also implies @option{--unresolved-symbols=report-all}. This
1778 option can be used with @option{-shared}. Doing so means that a
1779 shared library is being created but that all of the library's external
1780 references must be resolved by pulling in entries from static
1785 When creating a shared library, bind references to global symbols to the
1786 definition within the shared library, if any. Normally, it is possible
1787 for a program linked against a shared library to override the definition
1788 within the shared library. This option is only meaningful on ELF
1789 platforms which support shared libraries.
1791 @kindex -Bsymbolic-functions
1792 @item -Bsymbolic-functions
1793 When creating a shared library, bind references to global function
1794 symbols to the definition within the shared library, if any.
1795 This option is only meaningful on ELF platforms which support shared
1798 @kindex -Bno-symbolic
1800 This option can cancel previously specified @samp{-Bsymbolic} and
1801 @samp{-Bsymbolic-functions}.
1803 @kindex --dynamic-list=@var{dynamic-list-file}
1804 @item --dynamic-list=@var{dynamic-list-file}
1805 Specify the name of a dynamic list file to the linker. This is
1806 typically used when creating shared libraries to specify a list of
1807 global symbols whose references shouldn't be bound to the definition
1808 within the shared library, or creating dynamically linked executables
1809 to specify a list of symbols which should be added to the symbol table
1810 in the executable. This option is only meaningful on ELF platforms
1811 which support shared libraries.
1813 The format of the dynamic list is the same as the version node without
1814 scope and node name. See @ref{VERSION} for more information.
1816 @kindex --dynamic-list-data
1817 @item --dynamic-list-data
1818 Include all global data symbols to the dynamic list.
1820 @kindex --dynamic-list-cpp-new
1821 @item --dynamic-list-cpp-new
1822 Provide the builtin dynamic list for C++ operator new and delete. It
1823 is mainly useful for building shared libstdc++.
1825 @kindex --dynamic-list-cpp-typeinfo
1826 @item --dynamic-list-cpp-typeinfo
1827 Provide the builtin dynamic list for C++ runtime type identification.
1829 @kindex --check-sections
1830 @kindex --no-check-sections
1831 @item --check-sections
1832 @itemx --no-check-sections
1833 Asks the linker @emph{not} to check section addresses after they have
1834 been assigned to see if there are any overlaps. Normally the linker will
1835 perform this check, and if it finds any overlaps it will produce
1836 suitable error messages. The linker does know about, and does make
1837 allowances for sections in overlays. The default behaviour can be
1838 restored by using the command-line switch @option{--check-sections}.
1839 Section overlap is not usually checked for relocatable links. You can
1840 force checking in that case by using the @option{--check-sections}
1843 @kindex --copy-dt-needed-entries
1844 @kindex --no-copy-dt-needed-entries
1845 @item --copy-dt-needed-entries
1846 @itemx --no-copy-dt-needed-entries
1847 This option affects the treatment of dynamic libraries referred to
1848 by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
1849 command line. Normally the linker won't add a DT_NEEDED tag to the
1850 output binary for each library mentioned in a DT_NEEDED tag in an
1851 input dynamic library. With @option{--copy-dt-needed-entries}
1852 specified on the command line however any dynamic libraries that
1853 follow it will have their DT_NEEDED entries added. The default
1854 behaviour can be restored with @option{--no-copy-dt-needed-entries}.
1856 This option also has an effect on the resolution of symbols in dynamic
1857 libraries. With @option{--copy-dt-needed-entries} dynamic libraries
1858 mentioned on the command line will be recursively searched, following
1859 their DT_NEEDED tags to other libraries, in order to resolve symbols
1860 required by the output binary. With the default setting however
1861 the searching of dynamic libraries that follow it will stop with the
1862 dynamic library itself. No DT_NEEDED links will be traversed to resolve
1865 @cindex cross reference table
1868 Output a cross reference table. If a linker map file is being
1869 generated, the cross reference table is printed to the map file.
1870 Otherwise, it is printed on the standard output.
1872 The format of the table is intentionally simple, so that it may be
1873 easily processed by a script if necessary. The symbols are printed out,
1874 sorted by name. For each symbol, a list of file names is given. If the
1875 symbol is defined, the first file listed is the location of the
1876 definition. If the symbol is defined as a common value then any files
1877 where this happens appear next. Finally any files that reference the
1880 @cindex ctf variables
1881 @kindex --ctf-variables
1882 @kindex --no-ctf-variables
1883 @item --ctf-variables
1884 @item --no-ctf-variables
1885 The CTF debuginfo format supports a section which encodes the names and
1886 types of variables found in the program which do not appear in any symbol
1887 table. These variables clearly cannot be looked up by address by
1888 conventional debuggers, so the space used for their types and names is
1889 usually wasted: the types are usually small but the names are often not.
1890 @option{--ctf-variables} causes the generation of such a section.
1891 The default behaviour can be restored with @option{--no-ctf-variables}.
1893 @cindex ctf type sharing
1894 @kindex --ctf-share-types
1895 @item --ctf-share-types=@var{method}
1896 Adjust the method used to share types between translation units in CTF.
1899 @item share-unconflicted
1900 Put all types that do not have ambiguous definitions into the shared dictionary,
1901 where debuggers can easily access them, even if they only occur in one
1902 translation unit. This is the default.
1904 @item share-duplicated
1905 Put only types that occur in multiple translation units into the shared
1906 dictionary: types with only one definition go into per-translation-unit
1907 dictionaries. Types with ambiguous definitions in multiple translation units
1908 always go into per-translation-unit dictionaries. This tends to make the CTF
1909 larger, but may reduce the amount of CTF in the shared dictionary. For very
1910 large projects this may speed up opening the CTF and save memory in the CTF
1911 consumer at runtime.
1914 @cindex common allocation
1915 @kindex --no-define-common
1916 @item --no-define-common
1917 This option inhibits the assignment of addresses to common symbols.
1918 The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
1919 @xref{Miscellaneous Commands}.
1921 The @samp{--no-define-common} option allows decoupling
1922 the decision to assign addresses to Common symbols from the choice
1923 of the output file type; otherwise a non-Relocatable output type
1924 forces assigning addresses to Common symbols.
1925 Using @samp{--no-define-common} allows Common symbols that are referenced
1926 from a shared library to be assigned addresses only in the main program.
1927 This eliminates the unused duplicate space in the shared library,
1928 and also prevents any possible confusion over resolving to the wrong
1929 duplicate when there are many dynamic modules with specialized search
1930 paths for runtime symbol resolution.
1932 @cindex group allocation in linker script
1933 @cindex section groups
1935 @kindex --force-group-allocation
1936 @item --force-group-allocation
1937 This option causes the linker to place section group members like
1938 normal input sections, and to delete the section groups. This is the
1939 default behaviour for a final link but this option can be used to
1940 change the behaviour of a relocatable link (@samp{-r}). The script
1941 command @code{FORCE_GROUP_ALLOCATION} has the same
1942 effect. @xref{Miscellaneous Commands}.
1944 @cindex symbols, from command line
1945 @kindex --defsym=@var{symbol}=@var{exp}
1946 @item --defsym=@var{symbol}=@var{expression}
1947 Create a global symbol in the output file, containing the absolute
1948 address given by @var{expression}. You may use this option as many
1949 times as necessary to define multiple symbols in the command line. A
1950 limited form of arithmetic is supported for the @var{expression} in this
1951 context: you may give a hexadecimal constant or the name of an existing
1952 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
1953 constants or symbols. If you need more elaborate expressions, consider
1954 using the linker command language from a script (@pxref{Assignments}).
1955 @emph{Note:} there should be no white space between @var{symbol}, the
1956 equals sign (``@key{=}''), and @var{expression}.
1958 The linker processes @samp{--defsym} arguments and @samp{-T} arguments
1959 in order, placing @samp{--defsym} before @samp{-T} will define the
1960 symbol before the linker script from @samp{-T} is processed, while
1961 placing @samp{--defsym} after @samp{-T} will define the symbol after
1962 the linker script has been processed. This difference has
1963 consequences for expressions within the linker script that use the
1964 @samp{--defsym} symbols, which order is correct will depend on what
1965 you are trying to achieve.
1967 @cindex demangling, from command line
1968 @kindex --demangle[=@var{style}]
1969 @kindex --no-demangle
1970 @item --demangle[=@var{style}]
1971 @itemx --no-demangle
1972 These options control whether to demangle symbol names in error messages
1973 and other output. When the linker is told to demangle, it tries to
1974 present symbol names in a readable fashion: it strips leading
1975 underscores if they are used by the object file format, and converts C++
1976 mangled symbol names into user readable names. Different compilers have
1977 different mangling styles. The optional demangling style argument can be used
1978 to choose an appropriate demangling style for your compiler. The linker will
1979 demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
1980 is set. These options may be used to override the default.
1982 @cindex dynamic linker, from command line
1983 @kindex -I@var{file}
1984 @kindex --dynamic-linker=@var{file}
1986 @itemx --dynamic-linker=@var{file}
1987 Set the name of the dynamic linker. This is only meaningful when
1988 generating dynamically linked ELF executables. The default dynamic
1989 linker is normally correct; don't use this unless you know what you are
1992 @kindex --no-dynamic-linker
1993 @item --no-dynamic-linker
1994 When producing an executable file, omit the request for a dynamic
1995 linker to be used at load-time. This is only meaningful for ELF
1996 executables that contain dynamic relocations, and usually requires
1997 entry point code that is capable of processing these relocations.
1999 @kindex --embedded-relocs
2000 @item --embedded-relocs
2001 This option is similar to the @option{--emit-relocs} option except
2002 that the relocs are stored in a target-specific section. This option
2003 is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
2006 @kindex --disable-multiple-abs-defs
2007 @item --disable-multiple-abs-defs
2008 Do not allow multiple definitions with symbols included
2009 in filename invoked by -R or --just-symbols
2011 @kindex --fatal-warnings
2012 @kindex --no-fatal-warnings
2013 @item --fatal-warnings
2014 @itemx --no-fatal-warnings
2015 Treat all warnings as errors. The default behaviour can be restored
2016 with the option @option{--no-fatal-warnings}.
2019 @kindex --no-warnings
2021 @itemx --no-warnings
2022 Do not display any warning or error messages. This overrides
2023 @option{--fatal-warnings} if it has been enabled. This option can be
2024 used when it is known that the output binary will not work, but there
2025 is still a need to create it.
2027 @kindex --force-exe-suffix
2028 @item --force-exe-suffix
2029 Make sure that an output file has a .exe suffix.
2031 If a successfully built fully linked output file does not have a
2032 @code{.exe} or @code{.dll} suffix, this option forces the linker to copy
2033 the output file to one of the same name with a @code{.exe} suffix. This
2034 option is useful when using unmodified Unix makefiles on a Microsoft
2035 Windows host, since some versions of Windows won't run an image unless
2036 it ends in a @code{.exe} suffix.
2038 @kindex --gc-sections
2039 @kindex --no-gc-sections
2040 @cindex garbage collection
2042 @itemx --no-gc-sections
2043 Enable garbage collection of unused input sections. It is ignored on
2044 targets that do not support this option. The default behaviour (of not
2045 performing this garbage collection) can be restored by specifying
2046 @samp{--no-gc-sections} on the command line. Note that garbage
2047 collection for COFF and PE format targets is supported, but the
2048 implementation is currently considered to be experimental.
2050 @samp{--gc-sections} decides which input sections are used by
2051 examining symbols and relocations. The section containing the entry
2052 symbol and all sections containing symbols undefined on the
2053 command-line will be kept, as will sections containing symbols
2054 referenced by dynamic objects. Note that when building shared
2055 libraries, the linker must assume that any visible symbol is
2056 referenced. Once this initial set of sections has been determined,
2057 the linker recursively marks as used any section referenced by their
2058 relocations. See @samp{--entry}, @samp{--undefined}, and
2059 @samp{--gc-keep-exported}.
2061 This option can be set when doing a partial link (enabled with option
2062 @samp{-r}). In this case the root of symbols kept must be explicitly
2063 specified either by one of the options @samp{--entry},
2064 @samp{--undefined}, or @samp{--gc-keep-exported} or by a @code{ENTRY}
2065 command in the linker script.
2067 As a GNU extension, ELF input sections marked with the
2068 @code{SHF_GNU_RETAIN} flag will not be garbage collected.
2070 @kindex --print-gc-sections
2071 @kindex --no-print-gc-sections
2072 @cindex garbage collection
2073 @item --print-gc-sections
2074 @itemx --no-print-gc-sections
2075 List all sections removed by garbage collection. The listing is
2076 printed on stderr. This option is only effective if garbage
2077 collection has been enabled via the @samp{--gc-sections}) option. The
2078 default behaviour (of not listing the sections that are removed) can
2079 be restored by specifying @samp{--no-print-gc-sections} on the command
2082 @kindex --gc-keep-exported
2083 @cindex garbage collection
2084 @item --gc-keep-exported
2085 When @samp{--gc-sections} is enabled, this option prevents garbage
2086 collection of unused input sections that contain global symbols having
2087 default or protected visibility. This option is intended to be used for
2088 executables where unreferenced sections would otherwise be garbage
2089 collected regardless of the external visibility of contained symbols.
2090 Note that this option has no effect when linking shared objects since
2091 it is already the default behaviour. This option is only supported for
2094 @kindex --print-output-format
2095 @cindex output format
2096 @item --print-output-format
2097 Print the name of the default output format (perhaps influenced by
2098 other command-line options). This is the string that would appear
2099 in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}).
2101 @kindex --print-memory-usage
2102 @cindex memory usage
2103 @item --print-memory-usage
2104 Print used size, total size and used size of memory regions created with
2105 the @ref{MEMORY} command. This is useful on embedded targets to have a
2106 quick view of amount of free memory. The format of the output has one
2107 headline and one line per region. It is both human readable and easily
2108 parsable by tools. Here is an example of an output:
2111 Memory region Used Size Region Size %age Used
2112 ROM: 256 KB 1 MB 25.00%
2113 RAM: 32 B 2 GB 0.00%
2120 Print a summary of the command-line options on the standard output and exit.
2122 @kindex --target-help
2124 Print a summary of all target-specific options on the standard output and exit.
2126 @kindex -Map=@var{mapfile}
2127 @item -Map=@var{mapfile}
2128 Print a link map to the file @var{mapfile}. See the description of the
2129 @option{-M} option, above. If @var{mapfile} is just the character
2130 @code{-} then the map will be written to stdout.
2132 Specifying a directory as @var{mapfile} causes the linker map to be
2133 written as a file inside the directory. Normally name of the file
2134 inside the directory is computed as the basename of the @var{output}
2135 file with @code{.map} appended. If however the special character
2136 @code{%} is used then this will be replaced by the full path of the
2137 output file. Additionally if there are any characters after the
2138 @var{%} symbol then @code{.map} will no longer be appended.
2141 -o foo.exe -Map=bar [Creates ./bar]
2142 -o ../dir/foo.exe -Map=bar [Creates ./bar]
2143 -o foo.exe -Map=../dir [Creates ../dir/foo.exe.map]
2144 -o ../dir2/foo.exe -Map=../dir [Creates ../dir/foo.exe.map]
2145 -o foo.exe -Map=% [Creates ./foo.exe.map]
2146 -o ../dir/foo.exe -Map=% [Creates ../dir/foo.exe.map]
2147 -o foo.exe -Map=%.bar [Creates ./foo.exe.bar]
2148 -o ../dir/foo.exe -Map=%.bar [Creates ../dir/foo.exe.bar]
2149 -o ../dir2/foo.exe -Map=../dir/% [Creates ../dir/../dir2/foo.exe.map]
2150 -o ../dir2/foo.exe -Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar]
2153 It is an error to specify more than one @code{%} character.
2155 If the map file already exists then it will be overwritten by this
2158 @cindex memory usage
2159 @kindex --no-keep-memory
2160 @item --no-keep-memory
2161 @command{ld} normally optimizes for speed over memory usage by caching the
2162 symbol tables of input files in memory. This option tells @command{ld} to
2163 instead optimize for memory usage, by rereading the symbol tables as
2164 necessary. This may be required if @command{ld} runs out of memory space
2165 while linking a large executable.
2167 @kindex --no-undefined
2170 @item --no-undefined
2172 Report unresolved symbol references from regular object files. This
2173 is done even if the linker is creating a non-symbolic shared library.
2174 The switch @option{--[no-]allow-shlib-undefined} controls the
2175 behaviour for reporting unresolved references found in shared
2176 libraries being linked in.
2178 The effects of this option can be reverted by using @code{-z undefs}.
2180 @kindex --allow-multiple-definition
2182 @item --allow-multiple-definition
2184 Normally when a symbol is defined multiple times, the linker will
2185 report a fatal error. These options allow multiple definitions and the
2186 first definition will be used.
2188 @kindex --allow-shlib-undefined
2189 @kindex --no-allow-shlib-undefined
2190 @item --allow-shlib-undefined
2191 @itemx --no-allow-shlib-undefined
2192 Allows or disallows undefined symbols in shared libraries.
2193 This switch is similar to @option{--no-undefined} except that it
2194 determines the behaviour when the undefined symbols are in a
2195 shared library rather than a regular object file. It does not affect
2196 how undefined symbols in regular object files are handled.
2198 The default behaviour is to report errors for any undefined symbols
2199 referenced in shared libraries if the linker is being used to create
2200 an executable, but to allow them if the linker is being used to create
2203 The reasons for allowing undefined symbol references in shared
2204 libraries specified at link time are that:
2208 A shared library specified at link time may not be the same as the one
2209 that is available at load time, so the symbol might actually be
2210 resolvable at load time.
2212 There are some operating systems, eg BeOS and HPPA, where undefined
2213 symbols in shared libraries are normal.
2215 The BeOS kernel for example patches shared libraries at load time to
2216 select whichever function is most appropriate for the current
2217 architecture. This is used, for example, to dynamically select an
2218 appropriate memset function.
2221 @kindex --error-handling-script=@var{scriptname}
2222 @item --error-handling-script=@var{scriptname}
2223 If this option is provided then the linker will invoke
2224 @var{scriptname} whenever an error is encountered. Currently however
2225 only two kinds of error are supported: missing symbols and missing
2226 libraries. Two arguments will be passed to script: the keyword
2227 ``undefined-symbol'' or `missing-lib'' and the @var{name} of the
2228 undefined symbol or missing library. The intention is that the script
2229 will provide suggestions to the user as to where the symbol or library
2230 might be found. After the script has finished then the normal linker
2231 error message will be displayed.
2233 The availability of this option is controlled by a configure time
2234 switch, so it may not be present in specific implementations.
2236 @kindex --no-undefined-version
2237 @item --no-undefined-version
2238 Normally when a symbol has an undefined version, the linker will ignore
2239 it. This option disallows symbols with undefined version and a fatal error
2240 will be issued instead.
2242 @kindex --default-symver
2243 @item --default-symver
2244 Create and use a default symbol version (the soname) for unversioned
2247 @kindex --default-imported-symver
2248 @item --default-imported-symver
2249 Create and use a default symbol version (the soname) for unversioned
2252 @kindex --no-warn-mismatch
2253 @item --no-warn-mismatch
2254 Normally @command{ld} will give an error if you try to link together input
2255 files that are mismatched for some reason, perhaps because they have
2256 been compiled for different processors or for different endiannesses.
2257 This option tells @command{ld} that it should silently permit such possible
2258 errors. This option should only be used with care, in cases when you
2259 have taken some special action that ensures that the linker errors are
2262 @kindex --no-warn-search-mismatch
2263 @item --no-warn-search-mismatch
2264 Normally @command{ld} will give a warning if it finds an incompatible
2265 library during a library search. This option silences the warning.
2267 @kindex --no-whole-archive
2268 @item --no-whole-archive
2269 Turn off the effect of the @option{--whole-archive} option for subsequent
2272 @cindex output file after errors
2273 @kindex --noinhibit-exec
2274 @item --noinhibit-exec
2275 Retain the executable output file whenever it is still usable.
2276 Normally, the linker will not produce an output file if it encounters
2277 errors during the link process; it exits without writing an output file
2278 when it issues any error whatsoever.
2282 Only search library directories explicitly specified on the
2283 command line. Library directories specified in linker scripts
2284 (including linker scripts specified on the command line) are ignored.
2286 @ifclear SingleFormat
2287 @kindex --oformat=@var{output-format}
2288 @item --oformat=@var{output-format}
2289 @command{ld} may be configured to support more than one kind of object
2290 file. If your @command{ld} is configured this way, you can use the
2291 @samp{--oformat} option to specify the binary format for the output
2292 object file. Even when @command{ld} is configured to support alternative
2293 object formats, you don't usually need to specify this, as @command{ld}
2294 should be configured to produce as a default output format the most
2295 usual format on each machine. @var{output-format} is a text string, the
2296 name of a particular format supported by the BFD libraries. (You can
2297 list the available binary formats with @samp{objdump -i}.) The script
2298 command @code{OUTPUT_FORMAT} can also specify the output format, but
2299 this option overrides it. @xref{BFD}.
2302 @kindex --out-implib
2303 @item --out-implib @var{file}
2304 Create an import library in @var{file} corresponding to the executable
2305 the linker is generating (eg. a DLL or ELF program). This import
2306 library (which should be called @code{*.dll.a} or @code{*.a} for DLLs)
2307 may be used to link clients against the generated executable; this
2308 behaviour makes it possible to skip a separate import library creation
2309 step (eg. @code{dlltool} for DLLs). This option is only available for
2310 the i386 PE and ELF targetted ports of the linker.
2313 @kindex --pic-executable
2315 @itemx --pic-executable
2316 @cindex position independent executables
2317 Create a position independent executable. This is currently only
2318 supported on ELF platforms. Position independent executables are
2319 relocated by the dynamic linker to the virtual address the OS chooses
2320 for them, which can vary between invocations. They are marked ET_DYN
2321 in the ELF file header, but differ from shared libraries in a number
2322 of ways. In particular, defined symbols in a PIE by default can not
2323 be overridden by another object as they can be in a shared library.
2327 @cindex position dependent executables
2328 Create a position dependent executable. This is the default.
2332 This option is ignored for Linux compatibility.
2336 This option is ignored for SVR4 compatibility.
2339 @cindex synthesizing linker
2340 @cindex relaxing addressing modes
2344 An option with machine dependent effects.
2346 This option is only supported on a few targets.
2349 @xref{H8/300,,@command{ld} and the H8/300}.
2352 @xref{Xtensa,, @command{ld} and Xtensa Processors}.
2355 @xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
2358 @xref{Nios II,,@command{ld} and the Altera Nios II}.
2361 @xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
2364 On some platforms the @option{--relax} option performs target specific,
2365 global optimizations that become possible when the linker resolves
2366 addressing in the program, such as relaxing address modes,
2367 synthesizing new instructions, selecting shorter version of current
2368 instructions, and combining constant values.
2370 On some platforms these link time global optimizations may make symbolic
2371 debugging of the resulting executable impossible.
2373 This is known to be the case for the Matsushita MN10200 and MN10300
2374 family of processors.
2377 On platforms where the feature is supported, the option
2378 @option{--no-relax} will disable it.
2380 On platforms where the feature is not supported, both @option{--relax}
2381 and @option{--no-relax} are accepted, but ignored.
2383 @cindex retaining specified symbols
2384 @cindex stripping all but some symbols
2385 @cindex symbols, retaining selectively
2386 @kindex --retain-symbols-file=@var{filename}
2387 @item --retain-symbols-file=@var{filename}
2388 Retain @emph{only} the symbols listed in the file @var{filename},
2389 discarding all others. @var{filename} is simply a flat file, with one
2390 symbol name per line. This option is especially useful in environments
2394 where a large global symbol table is accumulated gradually, to conserve
2397 @samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
2398 or symbols needed for relocations.
2400 You may only specify @samp{--retain-symbols-file} once in the command
2401 line. It overrides @samp{-s} and @samp{-S}.
2404 @item -rpath=@var{dir}
2405 @cindex runtime library search path
2406 @kindex -rpath=@var{dir}
2407 Add a directory to the runtime library search path. This is used when
2408 linking an ELF executable with shared objects. All @option{-rpath}
2409 arguments are concatenated and passed to the runtime linker, which uses
2410 them to locate shared objects at runtime.
2412 The @option{-rpath} option is also used when locating shared objects which
2413 are needed by shared objects explicitly included in the link; see the
2414 description of the @option{-rpath-link} option. Searching @option{-rpath}
2415 in this way is only supported by native linkers and cross linkers which
2416 have been configured with the @option{--with-sysroot} option.
2418 If @option{-rpath} is not used when linking an ELF executable, the
2419 contents of the environment variable @code{LD_RUN_PATH} will be used if it
2422 The @option{-rpath} option may also be used on SunOS. By default, on
2423 SunOS, the linker will form a runtime search path out of all the
2424 @option{-L} options it is given. If a @option{-rpath} option is used, the
2425 runtime search path will be formed exclusively using the @option{-rpath}
2426 options, ignoring the @option{-L} options. This can be useful when using
2427 gcc, which adds many @option{-L} options which may be on NFS mounted
2430 For compatibility with other ELF linkers, if the @option{-R} option is
2431 followed by a directory name, rather than a file name, it is treated as
2432 the @option{-rpath} option.
2436 @cindex link-time runtime library search path
2437 @kindex -rpath-link=@var{dir}
2438 @item -rpath-link=@var{dir}
2439 When using ELF or SunOS, one shared library may require another. This
2440 happens when an @code{ld -shared} link includes a shared library as one
2443 When the linker encounters such a dependency when doing a non-shared,
2444 non-relocatable link, it will automatically try to locate the required
2445 shared library and include it in the link, if it is not included
2446 explicitly. In such a case, several directories are searched as
2447 described below. The @option{-rpath-link} option specifies the first
2448 set of directories to search. This option may specify a sequence of
2449 directory names either by providing a list of names separated by
2450 colons, or by appearing multiple times.
2452 The tokens @var{$ORIGIN} and @var{$LIB} can appear in these search
2453 directories. They will be replaced by the full path to the directory
2454 containing the program or shared object in the case of @var{$ORIGIN}
2455 and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for
2456 64-bit binaries - in the case of @var{$LIB}.
2458 The alternative form of these tokens - @var{$@{ORIGIN@}} and
2459 @var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not
2462 The @option{--rpath-link} option should be used with caution as it
2463 overrides the search path that may have been hard compiled into a
2464 shared library. In such a case it is possible to unintentionally use
2465 a different search path than the runtime linker would have used.
2467 When additional shared libraries are required, the linker will search
2468 directories in the order listed below in order to find them. Note
2469 however that this only applies to additional libraries needed to
2470 satisfy already included shared libraries. It does @emph{not}
2471 apply to libraries that are included via the @option{-l} command line
2472 option. Searches for @option{-l} libraries are only conducted in
2473 directories specified by the @option{-L} option (@xref{-L}).
2477 Any directories specified by @option{-rpath-link} options.
2479 Any directories specified by @option{-rpath} options. The difference
2480 between @option{-rpath} and @option{-rpath-link} is that directories
2481 specified by @option{-rpath} options are included in the executable and
2482 used at runtime, whereas the @option{-rpath-link} option is only effective
2483 at link time. Searching @option{-rpath} in this way is only supported
2484 by native linkers and cross linkers which have been configured with
2485 the @option{--with-sysroot} option.
2487 On an ELF system, for native linkers, if the @option{-rpath} and
2488 @option{-rpath-link} options were not used, search the contents of the
2489 environment variable @code{LD_RUN_PATH}.
2491 On SunOS, if the @option{-rpath} option was not used, search any
2492 directories specified using @option{-L} options.
2494 For a native linker, search the contents of the environment
2495 variable @code{LD_LIBRARY_PATH}.
2497 For a native ELF linker, the directories in @code{DT_RUNPATH} or
2498 @code{DT_RPATH} of a shared library are searched for shared
2499 libraries needed by it. The @code{DT_RPATH} entries are ignored if
2500 @code{DT_RUNPATH} entries exist.
2502 For a linker for a Linux system, if the file @file{/etc/ld.so.conf}
2503 exists, the list of directories found in that file. Note: the path
2504 to this file is prefixed with the @code{sysroot} value, if that is
2505 defined, and then any @code{prefix} string if the linker was
2506 configured with the @command{--prefix=<path>} option.
2508 For a native linker on a FreeBSD system, any directories specified by
2509 the @code{_PATH_ELF_HINTS} macro defined in the @file{elf-hints.h}
2512 Any directories specified by a @code{SEARCH_DIR} command in a
2513 linker script given on the command line, including scripts specified
2514 by @option{-T} (but not @option{-dT}).
2516 The default directories, normally @file{/lib} and @file{/usr/lib}.
2518 Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH.
2520 Any directories specified by a @code{SEARCH_DIR} command in a default
2524 Note however on Linux based systems there is an additional caveat: If
2525 the @option{--as-needed} option is active @emph{and} a shared library
2526 is located which would normally satisfy the search @emph{and} this
2527 library does not have DT_NEEDED tag for @file{libc.so}
2528 @emph{and} there is a shared library later on in the set of search
2529 directories which also satisfies the search @emph{and}
2530 this second shared library does have a DT_NEEDED tag for
2531 @file{libc.so} @emph{then} the second library will be selected instead
2534 If the required shared library is not found, the linker will issue a
2535 warning and continue with the link.
2539 @kindex --section-ordering-file
2540 @item --section-ordering-file=@var{script}
2541 @anchor{--section-ordering-file}
2542 This option is used to augment the current linker script with
2543 additional mapping of input sections to output sections. This file
2544 must use the same syntax for @code{SECTIONS} as is used in normal
2545 linker scripts, but it should not do anything other than place input
2546 sections into output sections. @pxref{SECTIONS}
2548 A second constraint on the section ordering script is that it can only
2549 reference output sections that are already defined by whichever linker
2550 script is currently in use. (Ie the default linker script or a script
2551 specified on the command line). The benefit of the section ordering
2552 script however is that the input sections are mapped to the start of
2553 the output sections, so that they can ensure the ordering of sections
2554 in the output section. For example, imagine that the default linker
2555 script looks like this:
2559 .text : @{ *(.text.hot) ; *(.text .text.*) @}
2560 .data : @{ *(.data.big) ; *(.data .data.*) @}
2564 Then if a section ordering file like this is used:
2567 .text : @{ *(.text.first) ; *(.text.z*) @}
2568 .data : @{ foo.o(.data.first) ; *(.data.small) @}
2571 This would be equivalent to a linker script like this:
2575 .text : @{ *(.text.first) ; *(.text.z*) ; *(.text.hot) ; *(.text .text.*) @}
2576 .data : @{ foo.o(.data.first) ; *(.data.small) ; *(.data.big) ; *(.data .data.*) @}
2580 The advantage of the section ordering file is that it can be used to
2581 order those sections that matter to the user without having to worry
2582 about any other sections, or memory regions, or anything else.
2588 @cindex shared libraries
2589 Create a shared library. This is currently only supported on ELF, XCOFF
2590 and SunOS platforms. On SunOS, the linker will automatically create a
2591 shared library if the @option{-e} option is not used and there are
2592 undefined symbols in the link.
2594 @kindex --sort-common
2596 @itemx --sort-common=ascending
2597 @itemx --sort-common=descending
2598 This option tells @command{ld} to sort the common symbols by alignment in
2599 ascending or descending order when it places them in the appropriate output
2600 sections. The symbol alignments considered are sixteen-byte or larger,
2601 eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
2602 between symbols due to alignment constraints. If no sorting order is
2603 specified, then descending order is assumed.
2605 @kindex --sort-section=name
2606 @item --sort-section=name
2607 This option will apply @code{SORT_BY_NAME} to all wildcard section
2608 patterns in the linker script.
2610 @kindex --sort-section=alignment
2611 @item --sort-section=alignment
2612 This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
2613 patterns in the linker script.
2615 @kindex --spare-dynamic-tags
2616 @item --spare-dynamic-tags=@var{count}
2617 This option specifies the number of empty slots to leave in the
2618 .dynamic section of ELF shared objects. Empty slots may be needed by
2619 post processing tools, such as the prelinker. The default is 5.
2621 @kindex --split-by-file
2622 @item --split-by-file[=@var{size}]
2623 Similar to @option{--split-by-reloc} but creates a new output section for
2624 each input file when @var{size} is reached. @var{size} defaults to a
2625 size of 1 if not given.
2627 @kindex --split-by-reloc
2628 @item --split-by-reloc[=@var{count}]
2629 Tries to creates extra sections in the output file so that no single
2630 output section in the file contains more than @var{count} relocations.
2631 This is useful when generating huge relocatable files for downloading into
2632 certain real time kernels with the COFF object file format; since COFF
2633 cannot represent more than 65535 relocations in a single section. Note
2634 that this will fail to work with object file formats which do not
2635 support arbitrary sections. The linker will not split up individual
2636 input sections for redistribution, so if a single input section contains
2637 more than @var{count} relocations one output section will contain that
2638 many relocations. @var{count} defaults to a value of 32768.
2642 Compute and display statistics about the operation of the linker, such
2643 as execution time and memory usage.
2645 @kindex --sysroot=@var{directory}
2646 @item --sysroot=@var{directory}
2647 Use @var{directory} as the location of the sysroot, overriding the
2648 configure-time default. This option is only supported by linkers
2649 that were configured using @option{--with-sysroot}.
2653 This is used by COFF/PE based targets to create a task-linked object
2654 file where all of the global symbols have been converted to statics.
2656 @kindex --traditional-format
2657 @cindex traditional format
2658 @item --traditional-format
2659 For some targets, the output of @command{ld} is different in some ways from
2660 the output of some existing linker. This switch requests @command{ld} to
2661 use the traditional format instead.
2664 For example, on SunOS, @command{ld} combines duplicate entries in the
2665 symbol string table. This can reduce the size of an output file with
2666 full debugging information by over 30 percent. Unfortunately, the SunOS
2667 @code{dbx} program can not read the resulting program (@code{gdb} has no
2668 trouble). The @samp{--traditional-format} switch tells @command{ld} to not
2669 combine duplicate entries.
2671 @kindex --section-start=@var{sectionname}=@var{org}
2672 @item --section-start=@var{sectionname}=@var{org}
2673 Locate a section in the output file at the absolute
2674 address given by @var{org}. You may use this option as many
2675 times as necessary to locate multiple sections in the command
2677 @var{org} must be a single hexadecimal integer;
2678 for compatibility with other linkers, you may omit the leading
2679 @samp{0x} usually associated with hexadecimal values. @emph{Note:} there
2680 should be no white space between @var{sectionname}, the equals
2681 sign (``@key{=}''), and @var{org}.
2683 @kindex -Tbss=@var{org}
2684 @kindex -Tdata=@var{org}
2685 @kindex -Ttext=@var{org}
2686 @cindex segment origins, cmd line
2687 @item -Tbss=@var{org}
2688 @itemx -Tdata=@var{org}
2689 @itemx -Ttext=@var{org}
2690 Same as @option{--section-start}, with @code{.bss}, @code{.data} or
2691 @code{.text} as the @var{sectionname}.
2693 @kindex -Ttext-segment=@var{org}
2694 @item -Ttext-segment=@var{org}
2695 @cindex text segment origin, cmd line
2696 When creating an ELF executable, it will set the address of the first
2697 byte of the text segment.
2699 @kindex -Trodata-segment=@var{org}
2700 @item -Trodata-segment=@var{org}
2701 @cindex rodata segment origin, cmd line
2702 When creating an ELF executable or shared object for a target where
2703 the read-only data is in its own segment separate from the executable
2704 text, it will set the address of the first byte of the read-only data segment.
2706 @kindex -Tldata-segment=@var{org}
2707 @item -Tldata-segment=@var{org}
2708 @cindex ldata segment origin, cmd line
2709 When creating an ELF executable or shared object for x86-64 medium memory
2710 model, it will set the address of the first byte of the ldata segment.
2712 @kindex --unresolved-symbols
2713 @item --unresolved-symbols=@var{method}
2714 Determine how to handle unresolved symbols. There are four possible
2715 values for @samp{method}:
2719 Do not report any unresolved symbols.
2722 Report all unresolved symbols. This is the default.
2724 @item ignore-in-object-files
2725 Report unresolved symbols that are contained in shared libraries, but
2726 ignore them if they come from regular object files.
2728 @item ignore-in-shared-libs
2729 Report unresolved symbols that come from regular object files, but
2730 ignore them if they come from shared libraries. This can be useful
2731 when creating a dynamic binary and it is known that all the shared
2732 libraries that it should be referencing are included on the linker's
2736 The behaviour for shared libraries on their own can also be controlled
2737 by the @option{--[no-]allow-shlib-undefined} option.
2739 Normally the linker will generate an error message for each reported
2740 unresolved symbol but the option @option{--warn-unresolved-symbols}
2741 can change this to a warning.
2743 @kindex --verbose[=@var{NUMBER}]
2744 @cindex verbose[=@var{NUMBER}]
2746 @itemx --verbose[=@var{NUMBER}]
2747 Display the version number for @command{ld} and list the linker emulations
2748 supported. Display which input files can and cannot be opened. Display
2749 the linker script being used by the linker. If the optional @var{NUMBER}
2750 argument > 1, plugin symbol status will also be displayed.
2752 @kindex --version-script=@var{version-scriptfile}
2753 @cindex version script, symbol versions
2754 @item --version-script=@var{version-scriptfile}
2755 Specify the name of a version script to the linker. This is typically
2756 used when creating shared libraries to specify additional information
2757 about the version hierarchy for the library being created. This option
2758 is only fully supported on ELF platforms which support shared libraries;
2759 see @ref{VERSION}. It is partially supported on PE platforms, which can
2760 use version scripts to filter symbol visibility in auto-export mode: any
2761 symbols marked @samp{local} in the version script will not be exported.
2764 @kindex --warn-common
2765 @cindex warnings, on combining symbols
2766 @cindex combining symbols, warnings on
2768 Warn when a common symbol is combined with another common symbol or with
2769 a symbol definition. Unix linkers allow this somewhat sloppy practice,
2770 but linkers on some other operating systems do not. This option allows
2771 you to find potential problems from combining global symbols.
2772 Unfortunately, some C libraries use this practice, so you may get some
2773 warnings about symbols in the libraries as well as in your programs.
2775 There are three kinds of global symbols, illustrated here by C examples:
2779 A definition, which goes in the initialized data section of the output
2783 An undefined reference, which does not allocate space.
2784 There must be either a definition or a common symbol for the
2788 A common symbol. If there are only (one or more) common symbols for a
2789 variable, it goes in the uninitialized data area of the output file.
2790 The linker merges multiple common symbols for the same variable into a
2791 single symbol. If they are of different sizes, it picks the largest
2792 size. The linker turns a common symbol into a declaration, if there is
2793 a definition of the same variable.
2796 The @samp{--warn-common} option can produce five kinds of warnings.
2797 Each warning consists of a pair of lines: the first describes the symbol
2798 just encountered, and the second describes the previous symbol
2799 encountered with the same name. One or both of the two symbols will be
2804 Turning a common symbol into a reference, because there is already a
2805 definition for the symbol.
2807 @var{file}(@var{section}): warning: common of `@var{symbol}'
2808 overridden by definition
2809 @var{file}(@var{section}): warning: defined here
2813 Turning a common symbol into a reference, because a later definition for
2814 the symbol is encountered. This is the same as the previous case,
2815 except that the symbols are encountered in a different order.
2817 @var{file}(@var{section}): warning: definition of `@var{symbol}'
2819 @var{file}(@var{section}): warning: common is here
2823 Merging a common symbol with a previous same-sized common symbol.
2825 @var{file}(@var{section}): warning: multiple common
2827 @var{file}(@var{section}): warning: previous common is here
2831 Merging a common symbol with a previous larger common symbol.
2833 @var{file}(@var{section}): warning: common of `@var{symbol}'
2834 overridden by larger common
2835 @var{file}(@var{section}): warning: larger common is here
2839 Merging a common symbol with a previous smaller common symbol. This is
2840 the same as the previous case, except that the symbols are
2841 encountered in a different order.
2843 @var{file}(@var{section}): warning: common of `@var{symbol}'
2844 overriding smaller common
2845 @var{file}(@var{section}): warning: smaller common is here
2849 @kindex --warn-constructors
2850 @item --warn-constructors
2851 Warn if any global constructors are used. This is only useful for a few
2852 object file formats. For formats like COFF or ELF, the linker can not
2853 detect the use of global constructors.
2855 @kindex --warn-execstack
2856 @cindex warnings, on executable stack
2857 @cindex executable stack, warnings on
2858 @item --warn-execstack
2859 @itemx --warn-execstack-objects
2860 @itemx --no-warn-execstack
2861 On ELF platforms the linker may generate warning messages if it is
2862 asked to create an output file that contains an executable stack.
2863 There are three possible states:
2866 Do not generate any warnings.
2868 Always generate warnings, even if the executable stack is requested
2869 via the @option{-z execstack} command line option.
2871 Only generate a warning if an object file requests an executable
2872 stack, but not if the @option{-z execstack} option is used.
2875 The default state depends upon how the linker was configured when it
2876 was built. The @option{--no-warn-execstack} option always puts the
2877 linker into the no-warnings state. The @option{--warn-execstack}
2878 option puts the linker into the warn-always state. The
2879 @option{--warn-execstack-objects} option puts the linker into the
2880 warn-for-object-files-only state.
2882 Note: ELF format input files can specify that they need an executable
2883 stack by having a @var{.note.GNU-stack} section with the executable
2884 bit set in its section flags. They can specify that they do not need
2885 an executable stack by having the same section, but without the
2886 executable flag bit set. If an input file does not have a
2887 @var{.note.GNU-stack} section then the default behaviour is target
2888 specific. For some targets, then absence of such a section implies
2889 that an executable stack @emph{is} required. This is often a problem
2890 for hand crafted assembler files.
2892 @kindex --error-execstack
2893 @item --error-execstack
2894 @itemx --no-error-execstack
2895 If the linker is going to generate a warning message about an
2896 executable stack then the @option{--error-execstack} option will
2897 instead change that warning into an error. Note - this option does
2898 not change the linker's execstack warning generation state. Use
2899 @option{--warn-execstack} or @option{--warn-execstack-objects} to set
2900 a specific warning state.
2902 The @option{--no-error-execstack} option will restore the default
2903 behaviour of generating warning messages.
2905 @kindex --warn-multiple-gp
2906 @item --warn-multiple-gp
2907 Warn if multiple global pointer values are required in the output file.
2908 This is only meaningful for certain processors, such as the Alpha.
2909 Specifically, some processors put large-valued constants in a special
2910 section. A special register (the global pointer) points into the middle
2911 of this section, so that constants can be loaded efficiently via a
2912 base-register relative addressing mode. Since the offset in
2913 base-register relative mode is fixed and relatively small (e.g., 16
2914 bits), this limits the maximum size of the constant pool. Thus, in
2915 large programs, it is often necessary to use multiple global pointer
2916 values in order to be able to address all possible constants. This
2917 option causes a warning to be issued whenever this case occurs.
2920 @cindex warnings, on undefined symbols
2921 @cindex undefined symbols, warnings on
2923 Only warn once for each undefined symbol, rather than once per module
2926 @kindex --warn-rwx-segments
2927 @cindex warnings, on writeable and exectuable segments
2928 @cindex executable segments, warnings on
2929 @item --warn-rwx-segments
2930 @itemx --no-warn-rwx-segments
2931 Warn if the linker creates a loadable, non-zero sized segment that has
2932 all three of the read, write and execute permission flags set. Such a
2933 segment represents a potential security vulnerability. In addition
2934 warnings will be generated if a thread local storage segment is
2935 created with the execute permission flag set, regardless of whether or
2936 not it has the read and/or write flags set.
2938 These warnings are enabled by default. They can be disabled via the
2939 @option{--no-warn-rwx-segments} option and re-enabled via the
2940 @option{--warn-rwx-segments} option.
2942 @kindex --error-rwx-segments
2943 @item --error-rwx-segments
2944 @itemx --no-error-rwx-segments
2945 If the linker is going to generate a warning message about an
2946 executable, writeable segment, or an executable TLS segment, then the
2947 @option{--error-rwx-segments} option will turn this warning into an
2948 error instead. The @option{--no-error-rwx-segments} option will
2949 restore the default behaviour of just generating a warning message.
2951 Note - the @option{--error-rwx-segments} option does not by itself
2952 turn on warnings about these segments. These warnings are either
2953 enabled by default, if the linker was configured that way, or via the
2954 @option{--warn-rwx-segments} command line option.
2956 @kindex --warn-section-align
2957 @cindex warnings, on section alignment
2958 @cindex section alignment, warnings on
2959 @item --warn-section-align
2960 Warn if the address of an output section is changed because of
2961 alignment. Typically, the alignment will be set by an input section.
2962 The address will only be changed if it not explicitly specified; that
2963 is, if the @code{SECTIONS} command does not specify a start address for
2964 the section (@pxref{SECTIONS}).
2966 @kindex --warn-textrel
2967 @item --warn-textrel
2968 Warn if the linker adds DT_TEXTREL to a position-independent executable
2971 @kindex --warn-alternate-em
2972 @item --warn-alternate-em
2973 Warn if an object has alternate ELF machine code.
2975 @kindex --warn-unresolved-symbols
2976 @item --warn-unresolved-symbols
2977 If the linker is going to report an unresolved symbol (see the option
2978 @option{--unresolved-symbols}) it will normally generate an error.
2979 This option makes it generate a warning instead.
2981 @kindex --error-unresolved-symbols
2982 @item --error-unresolved-symbols
2983 This restores the linker's default behaviour of generating errors when
2984 it is reporting unresolved symbols.
2986 @kindex --whole-archive
2987 @cindex including an entire archive
2988 @item --whole-archive
2989 For each archive mentioned on the command line after the
2990 @option{--whole-archive} option, include every object file in the archive
2991 in the link, rather than searching the archive for the required object
2992 files. This is normally used to turn an archive file into a shared
2993 library, forcing every object to be included in the resulting shared
2994 library. This option may be used more than once.
2996 Two notes when using this option from gcc: First, gcc doesn't know
2997 about this option, so you have to use @option{-Wl,-whole-archive}.
2998 Second, don't forget to use @option{-Wl,-no-whole-archive} after your
2999 list of archives, because gcc will add its own list of archives to
3000 your link and you may not want this flag to affect those as well.
3002 @kindex --wrap=@var{symbol}
3003 @item --wrap=@var{symbol}
3004 Use a wrapper function for @var{symbol}. Any undefined reference to
3005 @var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
3006 undefined reference to @code{__real_@var{symbol}} will be resolved to
3009 This can be used to provide a wrapper for a system function. The
3010 wrapper function should be called @code{__wrap_@var{symbol}}. If it
3011 wishes to call the system function, it should call
3012 @code{__real_@var{symbol}}.
3014 Here is a trivial example:
3018 __wrap_malloc (size_t c)
3020 printf ("malloc called with %zu\n", c);
3021 return __real_malloc (c);
3025 If you link other code with this file using @option{--wrap malloc}, then
3026 all calls to @code{malloc} will call the function @code{__wrap_malloc}
3027 instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
3028 call the real @code{malloc} function.
3030 You may wish to provide a @code{__real_malloc} function as well, so that
3031 links without the @option{--wrap} option will succeed. If you do this,
3032 you should not put the definition of @code{__real_malloc} in the same
3033 file as @code{__wrap_malloc}; if you do, the assembler may resolve the
3034 call before the linker has a chance to wrap it to @code{malloc}.
3036 Only undefined references are replaced by the linker. So, translation unit
3037 internal references to @var{symbol} are not resolved to
3038 @code{__wrap_@var{symbol}}. In the next example, the call to @code{f} in
3039 @code{g} is not resolved to @code{__wrap_f}.
3055 @kindex --eh-frame-hdr
3056 @kindex --no-eh-frame-hdr
3057 @item --eh-frame-hdr
3058 @itemx --no-eh-frame-hdr
3059 Request (@option{--eh-frame-hdr}) or suppress
3060 (@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr}
3061 section and ELF @code{PT_GNU_EH_FRAME} segment header.
3063 @kindex --ld-generated-unwind-info
3064 @item --no-ld-generated-unwind-info
3065 Request creation of @code{.eh_frame} unwind info for linker
3066 generated code sections like PLT. This option is on by default
3067 if linker generated unwind info is supported. This option also
3068 controls the generation of @code{.sframe} stack trace info for linker
3069 generated code sections like PLT.
3071 @kindex --enable-new-dtags
3072 @kindex --disable-new-dtags
3073 @item --enable-new-dtags
3074 @itemx --disable-new-dtags
3075 This linker can create the new dynamic tags in ELF. But the older ELF
3076 systems may not understand them. If you specify
3077 @option{--enable-new-dtags}, the new dynamic tags will be created as needed
3078 and older dynamic tags will be omitted.
3079 If you specify @option{--disable-new-dtags}, no new dynamic tags will be
3080 created. By default, the new dynamic tags are not created. Note that
3081 those options are only available for ELF systems.
3083 @kindex --hash-size=@var{number}
3084 @item --hash-size=@var{number}
3085 Set the default size of the linker's hash tables to a prime number
3086 close to @var{number}. Increasing this value can reduce the length of
3087 time it takes the linker to perform its tasks, at the expense of
3088 increasing the linker's memory requirements. Similarly reducing this
3089 value can reduce the memory requirements at the expense of speed.
3091 @kindex --hash-style=@var{style}
3092 @item --hash-style=@var{style}
3093 Set the type of linker's hash table(s). @var{style} can be either
3094 @code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
3095 new style GNU @code{.gnu.hash} section or @code{both} for both
3096 the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
3097 hash tables. The default depends upon how the linker was configured,
3098 but for most Linux based systems it will be @code{both}.
3100 @kindex --compress-debug-sections=none
3101 @kindex --compress-debug-sections=zlib
3102 @kindex --compress-debug-sections=zlib-gnu
3103 @kindex --compress-debug-sections=zlib-gabi
3104 @kindex --compress-debug-sections=zstd
3105 @item --compress-debug-sections=none
3106 @itemx --compress-debug-sections=zlib
3107 @itemx --compress-debug-sections=zlib-gnu
3108 @itemx --compress-debug-sections=zlib-gabi
3109 @itemx --compress-debug-sections=zstd
3110 On ELF platforms, these options control how DWARF debug sections are
3111 compressed using zlib.
3113 @option{--compress-debug-sections=none} doesn't compress DWARF debug
3114 sections. @option{--compress-debug-sections=zlib-gnu} compresses
3115 DWARF debug sections and renames them to begin with @samp{.zdebug}
3116 instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi}
3117 also compresses DWARF debug sections, but rather than renaming them it
3118 sets the SHF_COMPRESSED flag in the sections' headers.
3120 The @option{--compress-debug-sections=zlib} option is an alias for
3121 @option{--compress-debug-sections=zlib-gabi}.
3123 @option{--compress-debug-sections=zstd} compresses DWARF debug sections using
3126 Note that this option overrides any compression in input debug
3127 sections, so if a binary is linked with @option{--compress-debug-sections=none}
3128 for example, then any compressed debug sections in input files will be
3129 uncompressed before they are copied into the output binary.
3131 The default compression behaviour varies depending upon the target
3132 involved and the configure options used to build the toolchain. The
3133 default can be determined by examining the output from the linker's
3134 @option{--help} option.
3136 @kindex --reduce-memory-overheads
3137 @item --reduce-memory-overheads
3138 This option reduces memory requirements at ld runtime, at the expense of
3139 linking speed. This was introduced to select the old O(n^2) algorithm
3140 for link map file generation, rather than the new O(n) algorithm which uses
3141 about 40% more memory for symbol storage.
3143 Another effect of the switch is to set the default hash table size to
3144 1021, which again saves memory at the cost of lengthening the linker's
3145 run time. This is not done however if the @option{--hash-size} switch
3148 The @option{--reduce-memory-overheads} switch may be also be used to
3149 enable other tradeoffs in future versions of the linker.
3151 @kindex --max-cache-size=@var{size}
3152 @item --max-cache-size=@var{size}
3153 @command{ld} normally caches the relocation information and symbol tables
3154 of input files in memory with the unlimited size. This option sets the
3155 maximum cache size to @var{size}.
3158 @kindex --build-id=@var{style}
3160 @itemx --build-id=@var{style}
3161 Request the creation of a @code{.note.gnu.build-id} ELF note section
3162 or a @code{.buildid} COFF section. The contents of the note are
3163 unique bits identifying this linked file. @var{style} can be
3164 @code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit
3165 @sc{SHA1} hash on the normative parts of the output contents,
3166 @code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of
3167 the output contents, or @code{0x@var{hexstring}} to use a chosen bit
3168 string specified as an even number of hexadecimal digits (@code{-} and
3169 @code{:} characters between digit pairs are ignored). If @var{style}
3170 is omitted, @code{sha1} is used.
3172 The @code{md5} and @code{sha1} styles produces an identifier
3173 that is always the same in an identical output file, but will be
3174 unique among all nonidentical output files. It is not intended
3175 to be compared as a checksum for the file's contents. A linked
3176 file may be changed later by other tools, but the build ID bit
3177 string identifying the original linked file does not change.
3179 Passing @code{none} for @var{style} disables the setting from any
3180 @code{--build-id} options earlier on the command line.
3182 @kindex --package-metadata=@var{JSON}
3183 @item --package-metadata=@var{JSON}
3184 Request the creation of a @code{.note.package} ELF note section. The
3185 contents of the note are in JSON format, as per the package metadata
3186 specification. For more information see:
3187 https://systemd.io/ELF_PACKAGE_METADATA/
3188 If the JSON argument is missing/empty then this will disable the
3189 creation of the metadata note, if one had been enabled by an earlier
3190 occurrence of the --package-metadata option.
3191 If the linker has been built with libjansson, then the JSON string
3197 @subsection Options Specific to i386 PE Targets
3199 @c man begin OPTIONS
3201 The i386 PE linker supports the @option{-shared} option, which causes
3202 the output to be a dynamically linked library (DLL) instead of a
3203 normal executable. You should name the output @code{*.dll} when you
3204 use this option. In addition, the linker fully supports the standard
3205 @code{*.def} files, which may be specified on the linker command line
3206 like an object file (in fact, it should precede archives it exports
3207 symbols from, to ensure that they get linked in, just like a normal
3210 In addition to the options common to all targets, the i386 PE linker
3211 support additional command-line options that are specific to the i386
3212 PE target. Options that take values may be separated from their
3213 values by either a space or an equals sign.
3217 @kindex --add-stdcall-alias
3218 @item --add-stdcall-alias
3219 If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
3220 as-is and also with the suffix stripped.
3221 [This option is specific to the i386 PE targeted port of the linker]
3224 @item --base-file @var{file}
3225 Use @var{file} as the name of a file in which to save the base
3226 addresses of all the relocations needed for generating DLLs with
3228 [This is an i386 PE specific option]
3232 Create a DLL instead of a regular executable. You may also use
3233 @option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
3235 [This option is specific to the i386 PE targeted port of the linker]
3237 @kindex --enable-long-section-names
3238 @kindex --disable-long-section-names
3239 @item --enable-long-section-names
3240 @itemx --disable-long-section-names
3241 The PE variants of the COFF object format add an extension that permits
3242 the use of section names longer than eight characters, the normal limit
3243 for COFF. By default, these names are only allowed in object files, as
3244 fully-linked executable images do not carry the COFF string table required
3245 to support the longer names. As a GNU extension, it is possible to
3246 allow their use in executable images as well, or to (probably pointlessly!)
3247 disallow it in object files, by using these two options. Executable images
3248 generated with these long section names are slightly non-standard, carrying
3249 as they do a string table, and may generate confusing output when examined
3250 with non-GNU PE-aware tools, such as file viewers and dumpers. However,
3251 GDB relies on the use of PE long section names to find Dwarf-2 debug
3252 information sections in an executable image at runtime, and so if neither
3253 option is specified on the command-line, @command{ld} will enable long
3254 section names, overriding the default and technically correct behaviour,
3255 when it finds the presence of debug information while linking an executable
3256 image and not stripping symbols.
3257 [This option is valid for all PE targeted ports of the linker]
3259 @kindex --enable-stdcall-fixup
3260 @kindex --disable-stdcall-fixup
3261 @item --enable-stdcall-fixup
3262 @itemx --disable-stdcall-fixup
3263 If the link finds a symbol that it cannot resolve, it will attempt to
3264 do ``fuzzy linking'' by looking for another defined symbol that differs
3265 only in the format of the symbol name (cdecl vs stdcall) and will
3266 resolve that symbol by linking to the match. For example, the
3267 undefined symbol @code{_foo} might be linked to the function
3268 @code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
3269 to the function @code{_bar}. When the linker does this, it prints a
3270 warning, since it normally should have failed to link, but sometimes
3271 import libraries generated from third-party dlls may need this feature
3272 to be usable. If you specify @option{--enable-stdcall-fixup}, this
3273 feature is fully enabled and warnings are not printed. If you specify
3274 @option{--disable-stdcall-fixup}, this feature is disabled and such
3275 mismatches are considered to be errors.
3276 [This option is specific to the i386 PE targeted port of the linker]
3278 @kindex --leading-underscore
3279 @kindex --no-leading-underscore
3280 @item --leading-underscore
3281 @itemx --no-leading-underscore
3282 For most targets default symbol-prefix is an underscore and is defined
3283 in target's description. By this option it is possible to
3284 disable/enable the default underscore symbol-prefix.
3286 @cindex DLLs, creating
3287 @kindex --export-all-symbols
3288 @item --export-all-symbols
3289 If given, all global symbols in the objects used to build a DLL will
3290 be exported by the DLL. Note that this is the default if there
3291 otherwise wouldn't be any exported symbols. When symbols are
3292 explicitly exported via DEF files or implicitly exported via function
3293 attributes, the default is to not export anything else unless this
3294 option is given. Note that the symbols @code{DllMain@@12},
3295 @code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
3296 @code{impure_ptr} will not be automatically
3297 exported. Also, symbols imported from other DLLs will not be
3298 re-exported, nor will symbols specifying the DLL's internal layout
3299 such as those beginning with @code{_head_} or ending with
3300 @code{_iname}. In addition, no symbols from @code{libgcc},
3301 @code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
3302 Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
3303 not be exported, to help with C++ DLLs. Finally, there is an
3304 extensive list of cygwin-private symbols that are not exported
3305 (obviously, this applies on when building DLLs for cygwin targets).
3306 These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
3307 @code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
3308 @code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
3309 @code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
3310 @code{cygwin_premain3}, and @code{environ}.
3311 [This option is specific to the i386 PE targeted port of the linker]
3313 @kindex --exclude-symbols
3314 @item --exclude-symbols @var{symbol},@var{symbol},...
3315 Specifies a list of symbols which should not be automatically
3316 exported. The symbol names may be delimited by commas or colons.
3317 [This option is specific to the i386 PE targeted port of the linker]
3319 @kindex --exclude-all-symbols
3320 @item --exclude-all-symbols
3321 Specifies no symbols should be automatically exported.
3322 [This option is specific to the i386 PE targeted port of the linker]
3324 @kindex --file-alignment
3325 @item --file-alignment
3326 Specify the file alignment. Sections in the file will always begin at
3327 file offsets which are multiples of this number. This defaults to
3329 [This option is specific to the i386 PE targeted port of the linker]
3333 @item --heap @var{reserve}
3334 @itemx --heap @var{reserve},@var{commit}
3335 Specify the number of bytes of memory to reserve (and optionally commit)
3336 to be used as heap for this program. The default is 1MB reserved, 4K
3338 [This option is specific to the i386 PE targeted port of the linker]
3341 @kindex --image-base
3342 @item --image-base @var{value}
3343 Use @var{value} as the base address of your program or dll. This is
3344 the lowest memory location that will be used when your program or dll
3345 is loaded. To reduce the need to relocate and improve performance of
3346 your dlls, each should have a unique base address and not overlap any
3347 other dlls. The default is 0x400000 for executables, and 0x10000000
3349 [This option is specific to the i386 PE targeted port of the linker]
3353 If given, the stdcall suffixes (@@@var{nn}) will be stripped from
3354 symbols before they are exported.
3355 [This option is specific to the i386 PE targeted port of the linker]
3357 @kindex --large-address-aware
3358 @item --large-address-aware
3359 If given, the appropriate bit in the ``Characteristics'' field of the COFF
3360 header is set to indicate that this executable supports virtual addresses
3361 greater than 2 gigabytes. This should be used in conjunction with the /3GB
3362 or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
3363 section of the BOOT.INI. Otherwise, this bit has no effect.
3364 [This option is specific to PE targeted ports of the linker]
3366 @kindex --disable-large-address-aware
3367 @item --disable-large-address-aware
3368 Reverts the effect of a previous @samp{--large-address-aware} option.
3369 This is useful if @samp{--large-address-aware} is always set by the compiler
3370 driver (e.g. Cygwin gcc) and the executable does not support virtual
3371 addresses greater than 2 gigabytes.
3372 [This option is specific to PE targeted ports of the linker]
3374 @kindex --major-image-version
3375 @item --major-image-version @var{value}
3376 Sets the major number of the ``image version''. Defaults to 1.
3377 [This option is specific to the i386 PE targeted port of the linker]
3379 @kindex --major-os-version
3380 @item --major-os-version @var{value}
3381 Sets the major number of the ``os version''. Defaults to 4.
3382 [This option is specific to the i386 PE targeted port of the linker]
3384 @kindex --major-subsystem-version
3385 @item --major-subsystem-version @var{value}
3386 Sets the major number of the ``subsystem version''. Defaults to 4.
3387 [This option is specific to the i386 PE targeted port of the linker]
3389 @kindex --minor-image-version
3390 @item --minor-image-version @var{value}
3391 Sets the minor number of the ``image version''. Defaults to 0.
3392 [This option is specific to the i386 PE targeted port of the linker]
3394 @kindex --minor-os-version
3395 @item --minor-os-version @var{value}
3396 Sets the minor number of the ``os version''. Defaults to 0.
3397 [This option is specific to the i386 PE targeted port of the linker]
3399 @kindex --minor-subsystem-version
3400 @item --minor-subsystem-version @var{value}
3401 Sets the minor number of the ``subsystem version''. Defaults to 0.
3402 [This option is specific to the i386 PE targeted port of the linker]
3404 @cindex DEF files, creating
3405 @cindex DLLs, creating
3406 @kindex --output-def
3407 @item --output-def @var{file}
3408 The linker will create the file @var{file} which will contain a DEF
3409 file corresponding to the DLL the linker is generating. This DEF file
3410 (which should be called @code{*.def}) may be used to create an import
3411 library with @code{dlltool} or may be used as a reference to
3412 automatically or implicitly exported symbols.
3413 [This option is specific to the i386 PE targeted port of the linker]
3415 @cindex DLLs, creating
3416 @kindex --enable-auto-image-base
3417 @item --enable-auto-image-base
3418 @itemx --enable-auto-image-base=@var{value}
3419 Automatically choose the image base for DLLs, optionally starting with base
3420 @var{value}, unless one is specified using the @code{--image-base} argument.
3421 By using a hash generated from the dllname to create unique image bases
3422 for each DLL, in-memory collisions and relocations which can delay program
3423 execution are avoided.
3424 [This option is specific to the i386 PE targeted port of the linker]
3426 @kindex --disable-auto-image-base
3427 @item --disable-auto-image-base
3428 Do not automatically generate a unique image base. If there is no
3429 user-specified image base (@code{--image-base}) then use the platform
3431 [This option is specific to the i386 PE targeted port of the linker]
3433 @cindex DLLs, linking to
3434 @kindex --dll-search-prefix
3435 @item --dll-search-prefix @var{string}
3436 When linking dynamically to a dll without an import library,
3437 search for @code{<string><basename>.dll} in preference to
3438 @code{lib<basename>.dll}. This behaviour allows easy distinction
3439 between DLLs built for the various "subplatforms": native, cygwin,
3440 uwin, pw, etc. For instance, cygwin DLLs typically use
3441 @code{--dll-search-prefix=cyg}.
3442 [This option is specific to the i386 PE targeted port of the linker]
3444 @kindex --enable-auto-import
3445 @item --enable-auto-import
3446 Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
3447 DATA imports from DLLs, thus making it possible to bypass the dllimport
3448 mechanism on the user side and to reference unmangled symbol names.
3449 [This option is specific to the i386 PE targeted port of the linker]
3451 The following remarks pertain to the original implementation of the
3452 feature and are obsolete nowadays for Cygwin and MinGW targets.
3454 Note: Use of the 'auto-import' extension will cause the text section
3455 of the image file to be made writable. This does not conform to the
3456 PE-COFF format specification published by Microsoft.
3458 Note - use of the 'auto-import' extension will also cause read only
3459 data which would normally be placed into the .rdata section to be
3460 placed into the .data section instead. This is in order to work
3461 around a problem with consts that is described here:
3462 http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
3464 Using 'auto-import' generally will 'just work' -- but sometimes you may
3467 "variable '<var>' can't be auto-imported. Please read the
3468 documentation for ld's @code{--enable-auto-import} for details."
3470 This message occurs when some (sub)expression accesses an address
3471 ultimately given by the sum of two constants (Win32 import tables only
3472 allow one). Instances where this may occur include accesses to member
3473 fields of struct variables imported from a DLL, as well as using a
3474 constant index into an array variable imported from a DLL. Any
3475 multiword variable (arrays, structs, long long, etc) may trigger
3476 this error condition. However, regardless of the exact data type
3477 of the offending exported variable, ld will always detect it, issue
3478 the warning, and exit.
3480 There are several ways to address this difficulty, regardless of the
3481 data type of the exported variable:
3483 One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
3484 of adjusting references in your client code for runtime environment, so
3485 this method works only when runtime environment supports this feature.
3487 A second solution is to force one of the 'constants' to be a variable --
3488 that is, unknown and un-optimizable at compile time. For arrays,
3489 there are two possibilities: a) make the indexee (the array's address)
3490 a variable, or b) make the 'constant' index a variable. Thus:
3493 extern type extern_array[];
3495 @{ volatile type *t=extern_array; t[1] @}
3501 extern type extern_array[];
3503 @{ volatile int t=1; extern_array[t] @}
3506 For structs (and most other multiword data types) the only option
3507 is to make the struct itself (or the long long, or the ...) variable:
3510 extern struct s extern_struct;
3511 extern_struct.field -->
3512 @{ volatile struct s *t=&extern_struct; t->field @}
3518 extern long long extern_ll;
3520 @{ volatile long long * local_ll=&extern_ll; *local_ll @}
3523 A third method of dealing with this difficulty is to abandon
3524 'auto-import' for the offending symbol and mark it with
3525 @code{__declspec(dllimport)}. However, in practice that
3526 requires using compile-time #defines to indicate whether you are
3527 building a DLL, building client code that will link to the DLL, or
3528 merely building/linking to a static library. In making the choice
3529 between the various methods of resolving the 'direct address with
3530 constant offset' problem, you should consider typical real-world usage:
3538 void main(int argc, char **argv)@{
3539 printf("%d\n",arr[1]);
3549 void main(int argc, char **argv)@{
3550 /* This workaround is for win32 and cygwin; do not "optimize" */
3551 volatile int *parr = arr;
3552 printf("%d\n",parr[1]);
3559 /* Note: auto-export is assumed (no __declspec(dllexport)) */
3560 #if (defined(_WIN32) || defined(__CYGWIN__)) && \
3561 !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
3562 #define FOO_IMPORT __declspec(dllimport)
3566 extern FOO_IMPORT int arr[];
3569 void main(int argc, char **argv)@{
3570 printf("%d\n",arr[1]);
3574 A fourth way to avoid this problem is to re-code your
3575 library to use a functional interface rather than a data interface
3576 for the offending variables (e.g. set_foo() and get_foo() accessor
3579 @kindex --disable-auto-import
3580 @item --disable-auto-import
3581 Do not attempt to do sophisticated linking of @code{_symbol} to
3582 @code{__imp__symbol} for DATA imports from DLLs.
3583 [This option is specific to the i386 PE targeted port of the linker]
3585 @kindex --enable-runtime-pseudo-reloc
3586 @item --enable-runtime-pseudo-reloc
3587 If your code contains expressions described in --enable-auto-import section,
3588 that is, DATA imports from DLL with non-zero offset, this switch will create
3589 a vector of 'runtime pseudo relocations' which can be used by runtime
3590 environment to adjust references to such data in your client code.
3591 [This option is specific to the i386 PE targeted port of the linker]
3593 @kindex --disable-runtime-pseudo-reloc
3594 @item --disable-runtime-pseudo-reloc
3595 Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
3596 [This option is specific to the i386 PE targeted port of the linker]
3598 @kindex --enable-extra-pe-debug
3599 @item --enable-extra-pe-debug
3600 Show additional debug info related to auto-import symbol thunking.
3601 [This option is specific to the i386 PE targeted port of the linker]
3603 @kindex --section-alignment
3604 @item --section-alignment
3605 Sets the section alignment. Sections in memory will always begin at
3606 addresses which are a multiple of this number. Defaults to 0x1000.
3607 [This option is specific to the i386 PE targeted port of the linker]
3611 @item --stack @var{reserve}
3612 @itemx --stack @var{reserve},@var{commit}
3613 Specify the number of bytes of memory to reserve (and optionally commit)
3614 to be used as stack for this program. The default is 2MB reserved, 4K
3616 [This option is specific to the i386 PE targeted port of the linker]
3619 @item --subsystem @var{which}
3620 @itemx --subsystem @var{which}:@var{major}
3621 @itemx --subsystem @var{which}:@var{major}.@var{minor}
3622 Specifies the subsystem under which your program will execute. The
3623 legal values for @var{which} are @code{native}, @code{windows},
3624 @code{console}, @code{posix}, and @code{xbox}. You may optionally set
3625 the subsystem version also. Numeric values are also accepted for
3627 [This option is specific to the i386 PE targeted port of the linker]
3629 The following options set flags in the @code{DllCharacteristics} field
3630 of the PE file header:
3631 [These options are specific to PE targeted ports of the linker]
3633 @kindex --high-entropy-va
3634 @item --high-entropy-va
3635 @itemx --disable-high-entropy-va
3636 Image is compatible with 64-bit address space layout randomization
3637 (ASLR). This option is enabled by default for 64-bit PE images.
3639 This option also implies @option{--dynamicbase} and
3640 @option{--enable-reloc-section}.
3642 @kindex --dynamicbase
3644 @itemx --disable-dynamicbase
3645 The image base address may be relocated using address space layout
3646 randomization (ASLR). This feature was introduced with MS Windows
3647 Vista for i386 PE targets. This option is enabled by default but
3648 can be disabled via the @option{--disable-dynamicbase} option.
3649 This option also implies @option{--enable-reloc-section}.
3651 @kindex --forceinteg
3653 @itemx --disable-forceinteg
3654 Code integrity checks are enforced. This option is disabled by
3659 @item --disable-nxcompat
3660 The image is compatible with the Data Execution Prevention.
3661 This feature was introduced with MS Windows XP SP2 for i386 PE
3662 targets. The option is enabled by default.
3664 @kindex --no-isolation
3665 @item --no-isolation
3666 @itemx --disable-no-isolation
3667 Although the image understands isolation, do not isolate the image.
3668 This option is disabled by default.
3672 @itemx --disable-no-seh
3673 The image does not use SEH. No SE handler may be called from
3674 this image. This option is disabled by default.
3678 @itemx --disable-no-bind
3679 Do not bind this image. This option is disabled by default.
3683 @itemx --disable-wdmdriver
3684 The driver uses the MS Windows Driver Model. This option is disabled
3689 @itemx --disable-tsaware
3690 The image is Terminal Server aware. This option is disabled by
3693 @kindex --insert-timestamp
3694 @item --insert-timestamp
3695 @itemx --no-insert-timestamp
3696 Insert a real timestamp into the image. This is the default behaviour
3697 as it matches legacy code and it means that the image will work with
3698 other, proprietary tools. The problem with this default is that it
3699 will result in slightly different images being produced each time the
3700 same sources are linked. The option @option{--no-insert-timestamp}
3701 can be used to insert a zero value for the timestamp, this ensuring
3702 that binaries produced from identical sources will compare
3705 If @option{--insert-timestamp} is active then the time inserted is
3706 either the time that the linking takes place or, if the
3707 @code{SOURCE_DATE_EPOCH} environment variable is defined, the number
3708 of seconds since Unix epoch as specified by that variable.
3710 @kindex --enable-reloc-section
3711 @item --enable-reloc-section
3712 @itemx --disable-reloc-section
3713 Create the base relocation table, which is necessary if the image
3714 is loaded at a different image base than specified in the PE header.
3715 This option is enabled by default.
3721 @subsection Options specific to C6X uClinux targets
3723 @c man begin OPTIONS
3725 The C6X uClinux target uses a binary format called DSBT to support shared
3726 libraries. Each shared library in the system needs to have a unique index;
3727 all executables use an index of 0.
3732 @item --dsbt-size @var{size}
3733 This option sets the number of entries in the DSBT of the current executable
3734 or shared library to @var{size}. The default is to create a table with 64
3737 @kindex --dsbt-index
3738 @item --dsbt-index @var{index}
3739 This option sets the DSBT index of the current executable or shared library
3740 to @var{index}. The default is 0, which is appropriate for generating
3741 executables. If a shared library is generated with a DSBT index of 0, the
3742 @code{R_C6000_DSBT_INDEX} relocs are copied into the output file.
3744 @kindex --no-merge-exidx-entries
3745 The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
3746 exidx entries in frame unwind info.
3754 @subsection Options specific to C-SKY targets
3756 @c man begin OPTIONS
3760 @kindex --branch-stub on C-SKY
3762 This option enables linker branch relaxation by inserting branch stub
3763 sections when needed to extend the range of branches. This option is
3764 usually not required since C-SKY supports branch and call instructions that
3765 can access the full memory range and branch relaxation is normally handled by
3766 the compiler or assembler.
3768 @kindex --stub-group-size on C-SKY
3769 @item --stub-group-size=@var{N}
3770 This option allows finer control of linker branch stub creation.
3771 It sets the maximum size of a group of input sections that can
3772 be handled by one stub section. A negative value of @var{N} locates
3773 stub sections after their branches, while a positive value allows stub
3774 sections to appear either before or after the branches. Values of
3775 @samp{1} or @samp{-1} indicate that the
3776 linker should choose suitable defaults.
3784 @subsection Options specific to Motorola 68HC11 and 68HC12 targets
3786 @c man begin OPTIONS
3788 The 68HC11 and 68HC12 linkers support specific options to control the
3789 memory bank switching mapping and trampoline code generation.
3793 @kindex --no-trampoline
3794 @item --no-trampoline
3795 This option disables the generation of trampoline. By default a trampoline
3796 is generated for each far function which is called using a @code{jsr}
3797 instruction (this happens when a pointer to a far function is taken).
3799 @kindex --bank-window
3800 @item --bank-window @var{name}
3801 This option indicates to the linker the name of the memory region in
3802 the @samp{MEMORY} specification that describes the memory bank window.
3803 The definition of such region is then used by the linker to compute
3804 paging and addresses within the memory window.
3812 @subsection Options specific to Motorola 68K target
3814 @c man begin OPTIONS
3816 The following options are supported to control handling of GOT generation
3817 when linking for 68K targets.
3822 @item --got=@var{type}
3823 This option tells the linker which GOT generation scheme to use.
3824 @var{type} should be one of @samp{single}, @samp{negative},
3825 @samp{multigot} or @samp{target}. For more information refer to the
3826 Info entry for @file{ld}.
3834 @subsection Options specific to MIPS targets
3836 @c man begin OPTIONS
3838 The following options are supported to control microMIPS instruction
3839 generation and branch relocation checks for ISA mode transitions when
3840 linking for MIPS targets.
3848 These options control the choice of microMIPS instructions used in code
3849 generated by the linker, such as that in the PLT or lazy binding stubs,
3850 or in relaxation. If @samp{--insn32} is used, then the linker only uses
3851 32-bit instruction encodings. By default or if @samp{--no-insn32} is
3852 used, all instruction encodings are used, including 16-bit ones where
3855 @kindex --ignore-branch-isa
3856 @item --ignore-branch-isa
3857 @kindex --no-ignore-branch-isa
3858 @itemx --no-ignore-branch-isa
3859 These options control branch relocation checks for invalid ISA mode
3860 transitions. If @samp{--ignore-branch-isa} is used, then the linker
3861 accepts any branch relocations and any ISA mode transition required
3862 is lost in relocation calculation, except for some cases of @code{BAL}
3863 instructions which meet relaxation conditions and are converted to
3864 equivalent @code{JALX} instructions as the associated relocation is
3865 calculated. By default or if @samp{--no-ignore-branch-isa} is used
3866 a check is made causing the loss of an ISA mode transition to produce
3869 @kindex --compact-branches
3870 @item --compact-branches
3871 @kindex --no-compact-branches
3872 @itemx --no-compact-branches
3873 These options control the generation of compact instructions by the linker
3874 in the PLT entries for MIPS R6.
3883 @subsection Options specific to PDP11 targets
3885 @c man begin OPTIONS
3887 For the pdp11-aout target, three variants of the output format can be
3888 produced as selected by the following options. The default variant
3889 for pdp11-aout is the @samp{--omagic} option, whereas for other
3890 targets @samp{--nmagic} is the default. The @samp{--imagic} option is
3891 defined only for the pdp11-aout target, while the others are described
3892 here as they apply to the pdp11-aout target.
3901 Mark the output as @code{OMAGIC} (0407) in the @file{a.out} header to
3902 indicate that the text segment is not to be write-protected and
3903 shared. Since the text and data sections are both readable and
3904 writable, the data section is allocated immediately contiguous after
3905 the text segment. This is the oldest format for PDP11 executable
3906 programs and is the default for @command{ld} on PDP11 Unix systems
3907 from the beginning through 2.11BSD.
3914 Mark the output as @code{NMAGIC} (0410) in the @file{a.out} header to
3915 indicate that when the output file is executed, the text portion will
3916 be read-only and shareable among all processes executing the same
3917 file. This involves moving the data areas up to the first possible 8K
3918 byte page boundary following the end of the text. This option creates
3919 a @emph{pure executable} format.
3926 Mark the output as @code{IMAGIC} (0411) in the @file{a.out} header to
3927 indicate that when the output file is executed, the program text and
3928 data areas will be loaded into separate address spaces using the split
3929 instruction and data space feature of the memory management unit in
3930 larger models of the PDP11. This doubles the address space available
3931 to the program. The text segment is again pure, write-protected, and
3932 shareable. The only difference in the output format between this
3933 option and the others, besides the magic number, is that both the text
3934 and data sections start at location 0. The @samp{-z} option selected
3935 this format in 2.11BSD. This option creates a @emph{separate
3941 Equivalent to @samp{--nmagic} for pdp11-aout.
3950 @section Environment Variables
3952 @c man begin ENVIRONMENT
3954 You can change the behaviour of @command{ld} with the environment variables
3955 @ifclear SingleFormat
3958 @code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
3960 @ifclear SingleFormat
3962 @cindex default input format
3963 @code{GNUTARGET} determines the input-file object format if you don't
3964 use @samp{-b} (or its synonym @samp{--format}). Its value should be one
3965 of the BFD names for an input format (@pxref{BFD}). If there is no
3966 @code{GNUTARGET} in the environment, @command{ld} uses the natural format
3967 of the target. If @code{GNUTARGET} is set to @code{default} then BFD
3968 attempts to discover the input format by examining binary input files;
3969 this method often succeeds, but there are potential ambiguities, since
3970 there is no method of ensuring that the magic number used to specify
3971 object-file formats is unique. However, the configuration procedure for
3972 BFD on each system places the conventional format for that system first
3973 in the search-list, so ambiguities are resolved in favor of convention.
3977 @cindex default emulation
3978 @cindex emulation, default
3979 @code{LDEMULATION} determines the default emulation if you don't use the
3980 @samp{-m} option. The emulation can affect various aspects of linker
3981 behaviour, particularly the default linker script. You can list the
3982 available emulations with the @samp{--verbose} or @samp{-V} options. If
3983 the @samp{-m} option is not used, and the @code{LDEMULATION} environment
3984 variable is not defined, the default emulation depends upon how the
3985 linker was configured.
3987 @kindex COLLECT_NO_DEMANGLE
3988 @cindex demangling, default
3989 Normally, the linker will default to demangling symbols. However, if
3990 @code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
3991 default to not demangling symbols. This environment variable is used in
3992 a similar fashion by the @code{gcc} linker wrapper program. The default
3993 may be overridden by the @samp{--demangle} and @samp{--no-demangle}
4000 @chapter Linker Scripts
4003 @cindex linker scripts
4004 @cindex command files
4005 Every link is controlled by a @dfn{linker script}. This script is
4006 written in the linker command language.
4008 The main purpose of the linker script is to describe how the sections in
4009 the input files should be mapped into the output file, and to control
4010 the memory layout of the output file. Most linker scripts do nothing
4011 more than this. However, when necessary, the linker script can also
4012 direct the linker to perform many other operations, using the commands
4015 The linker always uses a linker script. If you do not supply one
4016 yourself, the linker will use a default script that is compiled into the
4017 linker executable. You can use the @samp{--verbose} command-line option
4018 to display the default linker script. Certain command-line options,
4019 such as @samp{-r} or @samp{-N}, will affect the default linker script.
4021 You may supply your own linker script by using the @samp{-T} command
4022 line option. When you do this, your linker script will replace the
4023 default linker script.
4025 You may also use linker scripts implicitly by naming them as input files
4026 to the linker, as though they were files to be linked. @xref{Implicit
4030 * Basic Script Concepts:: Basic Linker Script Concepts
4031 * Script Format:: Linker Script Format
4032 * Simple Example:: Simple Linker Script Example
4033 * Simple Commands:: Simple Linker Script Commands
4034 * Assignments:: Assigning Values to Symbols
4035 * SECTIONS:: SECTIONS Command
4036 * MEMORY:: MEMORY Command
4037 * PHDRS:: PHDRS Command
4038 * VERSION:: VERSION Command
4039 * Expressions:: Expressions in Linker Scripts
4040 * Implicit Linker Scripts:: Implicit Linker Scripts
4043 @node Basic Script Concepts
4044 @section Basic Linker Script Concepts
4045 @cindex linker script concepts
4046 We need to define some basic concepts and vocabulary in order to
4047 describe the linker script language.
4049 The linker combines input files into a single output file. The output
4050 file and each input file are in a special data format known as an
4051 @dfn{object file format}. Each file is called an @dfn{object file}.
4052 The output file is often called an @dfn{executable}, but for our
4053 purposes we will also call it an object file. Each object file has,
4054 among other things, a list of @dfn{sections}. We sometimes refer to a
4055 section in an input file as an @dfn{input section}; similarly, a section
4056 in the output file is an @dfn{output section}.
4058 Each section in an object file has a name and a size. Most sections
4059 also have an associated block of data, known as the @dfn{section
4060 contents}. A section may be marked as @dfn{loadable}, which means that
4061 the contents should be loaded into memory when the output file is run.
4062 A section with no contents may be @dfn{allocatable}, which means that an
4063 area in memory should be set aside, but nothing in particular should be
4064 loaded there (in some cases this memory must be zeroed out). A section
4065 which is neither loadable nor allocatable typically contains some sort
4066 of debugging information.
4068 Every loadable or allocatable output section has two addresses. The
4069 first is the @dfn{VMA}, or virtual memory address. This is the address
4070 the section will have when the output file is run. The second is the
4071 @dfn{LMA}, or load memory address. This is the address at which the
4072 section will be loaded. In most cases the two addresses will be the
4073 same. An example of when they might be different is when a data section
4074 is loaded into ROM, and then copied into RAM when the program starts up
4075 (this technique is often used to initialize global variables in a ROM
4076 based system). In this case the ROM address would be the LMA, and the
4077 RAM address would be the VMA.
4079 You can see the sections in an object file by using the @code{objdump}
4080 program with the @samp{-h} option.
4082 Every object file also has a list of @dfn{symbols}, known as the
4083 @dfn{symbol table}. A symbol may be defined or undefined. Each symbol
4084 has a name, and each defined symbol has an address, among other
4085 information. If you compile a C or C++ program into an object file, you
4086 will get a defined symbol for every defined function and global or
4087 static variable. Every undefined function or global variable which is
4088 referenced in the input file will become an undefined symbol.
4090 You can see the symbols in an object file by using the @code{nm}
4091 program, or by using the @code{objdump} program with the @samp{-t}
4095 @section Linker Script Format
4096 @cindex linker script format
4097 Linker scripts are text files.
4099 You write a linker script as a series of commands. Each command is
4100 either a keyword, possibly followed by arguments, or an assignment to a
4101 symbol. You may separate commands using semicolons. Whitespace is
4104 Strings such as file or format names can normally be entered directly.
4105 If the file name contains a character such as a comma which would
4106 otherwise serve to separate file names, you may put the file name in
4107 double quotes. There is no way to use a double quote character in a
4110 You may include comments in linker scripts just as in C, delimited by
4111 @samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent
4114 @node Simple Example
4115 @section Simple Linker Script Example
4116 @cindex linker script example
4117 @cindex example of linker script
4118 Many linker scripts are fairly simple.
4120 The simplest possible linker script has just one command:
4121 @samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the
4122 memory layout of the output file.
4124 The @samp{SECTIONS} command is a powerful command. Here we will
4125 describe a simple use of it. Let's assume your program consists only of
4126 code, initialized data, and uninitialized data. These will be in the
4127 @samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
4128 Let's assume further that these are the only sections which appear in
4131 For this example, let's say that the code should be loaded at address
4132 0x10000, and that the data should start at address 0x8000000. Here is a
4133 linker script which will do that:
4138 .text : @{ *(.text) @}
4140 .data : @{ *(.data) @}
4141 .bss : @{ *(.bss) @}
4145 You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
4146 followed by a series of symbol assignments and output section
4147 descriptions enclosed in curly braces.
4149 The first line inside the @samp{SECTIONS} command of the above example
4150 sets the value of the special symbol @samp{.}, which is the location
4151 counter. If you do not specify the address of an output section in some
4152 other way (other ways are described later), the address is set from the
4153 current value of the location counter. The location counter is then
4154 incremented by the size of the output section. At the start of the
4155 @samp{SECTIONS} command, the location counter has the value @samp{0}.
4157 The second line defines an output section, @samp{.text}. The colon is
4158 required syntax which may be ignored for now. Within the curly braces
4159 after the output section name, you list the names of the input sections
4160 which should be placed into this output section. The @samp{*} is a
4161 wildcard which matches any file name. The expression @samp{*(.text)}
4162 means all @samp{.text} input sections in all input files.
4164 Since the location counter is @samp{0x10000} when the output section
4165 @samp{.text} is defined, the linker will set the address of the
4166 @samp{.text} section in the output file to be @samp{0x10000}.
4168 The remaining lines define the @samp{.data} and @samp{.bss} sections in
4169 the output file. The linker will place the @samp{.data} output section
4170 at address @samp{0x8000000}. After the linker places the @samp{.data}
4171 output section, the value of the location counter will be
4172 @samp{0x8000000} plus the size of the @samp{.data} output section. The
4173 effect is that the linker will place the @samp{.bss} output section
4174 immediately after the @samp{.data} output section in memory.
4176 The linker will ensure that each output section has the required
4177 alignment, by increasing the location counter if necessary. In this
4178 example, the specified addresses for the @samp{.text} and @samp{.data}
4179 sections will probably satisfy any alignment constraints, but the linker
4180 may have to create a small gap between the @samp{.data} and @samp{.bss}
4183 That's it! That's a simple and complete linker script.
4185 @node Simple Commands
4186 @section Simple Linker Script Commands
4187 @cindex linker script simple commands
4188 In this section we describe the simple linker script commands.
4191 * Entry Point:: Setting the entry point
4192 * File Commands:: Commands dealing with files
4193 @ifclear SingleFormat
4194 * Format Commands:: Commands dealing with object file formats
4197 * REGION_ALIAS:: Assign alias names to memory regions
4198 * Miscellaneous Commands:: Other linker script commands
4202 @subsection Setting the Entry Point
4203 @kindex ENTRY(@var{symbol})
4204 @cindex start of execution
4205 @cindex first instruction
4207 The first instruction to execute in a program is called the @dfn{entry
4208 point}. You can use the @code{ENTRY} linker script command to set the
4209 entry point. The argument is a symbol name:
4214 There are several ways to set the entry point. The linker will set the
4215 entry point by trying each of the following methods in order, and
4216 stopping when one of them succeeds:
4219 the @samp{-e} @var{entry} command-line option;
4221 the @code{ENTRY(@var{symbol})} command in a linker script;
4223 the value of a target-specific symbol, if it is defined; For many
4224 targets this is @code{start}, but PE- and BeOS-based systems for example
4225 check a list of possible entry symbols, matching the first one found.
4227 the address of the first byte of the code section, if present and an
4228 executable is being created - the code section is usually
4229 @samp{.text}, but can be something else;
4231 The address @code{0}.
4235 @subsection Commands Dealing with Files
4236 @cindex linker script file commands
4237 Several linker script commands deal with files.
4240 @item INCLUDE @var{filename}
4241 @kindex INCLUDE @var{filename}
4242 @cindex including a linker script
4243 Include the linker script @var{filename} at this point. The file will
4244 be searched for in the current directory, and in any directory specified
4245 with the @option{-L} option. You can nest calls to @code{INCLUDE} up to
4248 You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or
4249 @code{SECTIONS} commands, or in output section descriptions.
4251 @item INPUT(@var{file}, @var{file}, @dots{})
4252 @itemx INPUT(@var{file} @var{file} @dots{})
4253 @kindex INPUT(@var{files})
4254 @cindex input files in linker scripts
4255 @cindex input object files in linker scripts
4256 @cindex linker script input object files
4257 The @code{INPUT} command directs the linker to include the named files
4258 in the link, as though they were named on the command line.
4260 For example, if you always want to include @file{subr.o} any time you do
4261 a link, but you can't be bothered to put it on every link command line,
4262 then you can put @samp{INPUT (subr.o)} in your linker script.
4264 In fact, if you like, you can list all of your input files in the linker
4265 script, and then invoke the linker with nothing but a @samp{-T} option.
4267 In case a @dfn{sysroot prefix} is configured, and the filename starts
4268 with the @samp{/} character, and the script being processed was
4269 located inside the @dfn{sysroot prefix}, the filename will be looked
4270 for in the @dfn{sysroot prefix}. The @dfn{sysroot prefix} can also be forced by specifying
4271 @code{=} as the first character in the filename path, or prefixing the
4272 filename path with @code{$SYSROOT}. See also the description of
4273 @samp{-L} in @ref{Options,,Command-line Options}.
4275 If a @dfn{sysroot prefix} is not used then the linker will try to open
4276 the file in the directory containing the linker script. If it is not
4277 found the linker will then search the current directory. If it is still
4278 not found the linker will search through the archive library search
4281 If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
4282 name to @code{lib@var{file}.a}, as with the command-line argument
4285 When you use the @code{INPUT} command in an implicit linker script, the
4286 files will be included in the link at the point at which the linker
4287 script file is included. This can affect archive searching.
4289 @item GROUP(@var{file}, @var{file}, @dots{})
4290 @itemx GROUP(@var{file} @var{file} @dots{})
4291 @kindex GROUP(@var{files})
4292 @cindex grouping input files
4293 The @code{GROUP} command is like @code{INPUT}, except that the named
4294 files should all be archives, and they are searched repeatedly until no
4295 new undefined references are created. See the description of @samp{-(}
4296 in @ref{Options,,Command-line Options}.
4298 @item AS_NEEDED(@var{file}, @var{file}, @dots{})
4299 @itemx AS_NEEDED(@var{file} @var{file} @dots{})
4300 @kindex AS_NEEDED(@var{files})
4301 This construct can appear only inside of the @code{INPUT} or @code{GROUP}
4302 commands, among other filenames. The files listed will be handled
4303 as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
4304 with the exception of ELF shared libraries, that will be added only
4305 when they are actually needed. This construct essentially enables
4306 @option{--as-needed} option for all the files listed inside of it
4307 and restores previous @option{--as-needed} resp. @option{--no-as-needed}
4310 @item OUTPUT(@var{filename})
4311 @kindex OUTPUT(@var{filename})
4312 @cindex output file name in linker script
4313 The @code{OUTPUT} command names the output file. Using
4314 @code{OUTPUT(@var{filename})} in the linker script is exactly like using
4315 @samp{-o @var{filename}} on the command line (@pxref{Options,,Command
4316 Line Options}). If both are used, the command-line option takes
4319 You can use the @code{OUTPUT} command to define a default name for the
4320 output file other than the usual default of @file{a.out}.
4322 @item SEARCH_DIR(@var{path})
4323 @kindex SEARCH_DIR(@var{path})
4324 @cindex library search path in linker script
4325 @cindex archive search path in linker script
4326 @cindex search path in linker script
4327 The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
4328 @command{ld} looks for archive libraries. Using
4329 @code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
4330 on the command line (@pxref{Options,,Command-line Options}). If both
4331 are used, then the linker will search both paths. Paths specified using
4332 the command-line option are searched first.
4334 @item STARTUP(@var{filename})
4335 @kindex STARTUP(@var{filename})
4336 @cindex first input file
4337 The @code{STARTUP} command is just like the @code{INPUT} command, except
4338 that @var{filename} will become the first input file to be linked, as
4339 though it were specified first on the command line. This may be useful
4340 when using a system in which the entry point is always the start of the
4344 @ifclear SingleFormat
4345 @node Format Commands
4346 @subsection Commands Dealing with Object File Formats
4347 A couple of linker script commands deal with object file formats.
4350 @item OUTPUT_FORMAT(@var{bfdname})
4351 @itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
4352 @kindex OUTPUT_FORMAT(@var{bfdname})
4353 @cindex output file format in linker script
4354 The @code{OUTPUT_FORMAT} command names the BFD format to use for the
4355 output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is
4356 exactly like using @samp{--oformat @var{bfdname}} on the command line
4357 (@pxref{Options,,Command-line Options}). If both are used, the command
4358 line option takes precedence.
4360 You can use @code{OUTPUT_FORMAT} with three arguments to use different
4361 formats based on the @samp{-EB} and @samp{-EL} command-line options.
4362 This permits the linker script to set the output format based on the
4365 If neither @samp{-EB} nor @samp{-EL} are used, then the output format
4366 will be the first argument, @var{default}. If @samp{-EB} is used, the
4367 output format will be the second argument, @var{big}. If @samp{-EL} is
4368 used, the output format will be the third argument, @var{little}.
4370 For example, the default linker script for the MIPS ELF target uses this
4373 OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
4375 This says that the default format for the output file is
4376 @samp{elf32-bigmips}, but if the user uses the @samp{-EL} command-line
4377 option, the output file will be created in the @samp{elf32-littlemips}
4380 @item TARGET(@var{bfdname})
4381 @kindex TARGET(@var{bfdname})
4382 @cindex input file format in linker script
4383 The @code{TARGET} command names the BFD format to use when reading input
4384 files. It affects subsequent @code{INPUT} and @code{GROUP} commands.
4385 This command is like using @samp{-b @var{bfdname}} on the command line
4386 (@pxref{Options,,Command-line Options}). If the @code{TARGET} command
4387 is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
4388 command is also used to set the format for the output file. @xref{BFD}.
4393 @subsection Assign alias names to memory regions
4394 @kindex REGION_ALIAS(@var{alias}, @var{region})
4395 @cindex region alias
4396 @cindex region names
4398 Alias names can be added to existing memory regions created with the
4399 @ref{MEMORY} command. Each name corresponds to at most one memory region.
4402 REGION_ALIAS(@var{alias}, @var{region})
4405 The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
4406 memory region @var{region}. This allows a flexible mapping of output sections
4407 to memory regions. An example follows.
4409 Suppose we have an application for embedded systems which come with various
4410 memory storage devices. All have a general purpose, volatile memory @code{RAM}
4411 that allows code execution or data storage. Some may have a read-only,
4412 non-volatile memory @code{ROM} that allows code execution and read-only data
4413 access. The last variant is a read-only, non-volatile memory @code{ROM2} with
4414 read-only data access and no code execution capability. We have four output
4419 @code{.text} program code;
4421 @code{.rodata} read-only data;
4423 @code{.data} read-write initialized data;
4425 @code{.bss} read-write zero initialized data.
4428 The goal is to provide a linker command file that contains a system independent
4429 part defining the output sections and a system dependent part mapping the
4430 output sections to the memory regions available on the system. Our embedded
4431 systems come with three different memory setups @code{A}, @code{B} and
4433 @multitable @columnfractions .25 .25 .25 .25
4434 @item Section @tab Variant A @tab Variant B @tab Variant C
4435 @item .text @tab RAM @tab ROM @tab ROM
4436 @item .rodata @tab RAM @tab ROM @tab ROM2
4437 @item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
4438 @item .bss @tab RAM @tab RAM @tab RAM
4440 The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
4441 loaded into region @code{ROM} or @code{ROM2} respectively. Please note that
4442 the load address of the @code{.data} section starts in all three variants at
4443 the end of the @code{.rodata} section.
4445 The base linker script that deals with the output sections follows. It
4446 includes the system dependent @code{linkcmds.memory} file that describes the
4449 INCLUDE linkcmds.memory
4462 .data : AT (rodata_end)
4467 data_size = SIZEOF(.data);
4468 data_load_start = LOADADDR(.data);
4476 Now we need three different @code{linkcmds.memory} files to define memory
4477 regions and alias names. The content of @code{linkcmds.memory} for the three
4478 variants @code{A}, @code{B} and @code{C}:
4481 Here everything goes into the @code{RAM}.
4485 RAM : ORIGIN = 0, LENGTH = 4M
4488 REGION_ALIAS("REGION_TEXT", RAM);
4489 REGION_ALIAS("REGION_RODATA", RAM);
4490 REGION_ALIAS("REGION_DATA", RAM);
4491 REGION_ALIAS("REGION_BSS", RAM);
4494 Program code and read-only data go into the @code{ROM}. Read-write data goes
4495 into the @code{RAM}. An image of the initialized data is loaded into the
4496 @code{ROM} and will be copied during system start into the @code{RAM}.
4500 ROM : ORIGIN = 0, LENGTH = 3M
4501 RAM : ORIGIN = 0x10000000, LENGTH = 1M
4504 REGION_ALIAS("REGION_TEXT", ROM);
4505 REGION_ALIAS("REGION_RODATA", ROM);
4506 REGION_ALIAS("REGION_DATA", RAM);
4507 REGION_ALIAS("REGION_BSS", RAM);
4510 Program code goes into the @code{ROM}. Read-only data goes into the
4511 @code{ROM2}. Read-write data goes into the @code{RAM}. An image of the
4512 initialized data is loaded into the @code{ROM2} and will be copied during
4513 system start into the @code{RAM}.
4517 ROM : ORIGIN = 0, LENGTH = 2M
4518 ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
4519 RAM : ORIGIN = 0x20000000, LENGTH = 1M
4522 REGION_ALIAS("REGION_TEXT", ROM);
4523 REGION_ALIAS("REGION_RODATA", ROM2);
4524 REGION_ALIAS("REGION_DATA", RAM);
4525 REGION_ALIAS("REGION_BSS", RAM);
4529 It is possible to write a common system initialization routine to copy the
4530 @code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
4535 extern char data_start [];
4536 extern char data_size [];
4537 extern char data_load_start [];
4539 void copy_data(void)
4541 if (data_start != data_load_start)
4543 memcpy(data_start, data_load_start, (size_t) data_size);
4548 @node Miscellaneous Commands
4549 @subsection Other Linker Script Commands
4550 There are a few other linker scripts commands.
4553 @item ASSERT(@var{exp}, @var{message})
4555 @cindex assertion in linker script
4556 Ensure that @var{exp} is non-zero. If it is zero, then exit the linker
4557 with an error code, and print @var{message}.
4559 Note that assertions are checked before the final stages of linking
4560 take place. This means that expressions involving symbols PROVIDEd
4561 inside section definitions will fail if the user has not set values
4562 for those symbols. The only exception to this rule is PROVIDEd
4563 symbols that just reference dot. Thus an assertion like this:
4568 PROVIDE (__stack = .);
4569 PROVIDE (__stack_size = 0x100);
4570 ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
4574 will fail if @code{__stack_size} is not defined elsewhere. Symbols
4575 PROVIDEd outside of section definitions are evaluated earlier, so they
4576 can be used inside ASSERTions. Thus:
4579 PROVIDE (__stack_size = 0x100);
4582 PROVIDE (__stack = .);
4583 ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
4589 @item EXTERN(@var{symbol} @var{symbol} @dots{})
4591 @cindex undefined symbol in linker script
4592 Force @var{symbol} to be entered in the output file as an undefined
4593 symbol. Doing this may, for example, trigger linking of additional
4594 modules from standard libraries. You may list several @var{symbol}s for
4595 each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This
4596 command has the same effect as the @samp{-u} command-line option.
4598 @item FORCE_COMMON_ALLOCATION
4599 @kindex FORCE_COMMON_ALLOCATION
4600 @cindex common allocation in linker script
4601 This command has the same effect as the @samp{-d} command-line option:
4602 to make @command{ld} assign space to common symbols even if a relocatable
4603 output file is specified (@samp{-r}).
4605 @item INHIBIT_COMMON_ALLOCATION
4606 @kindex INHIBIT_COMMON_ALLOCATION
4607 @cindex common allocation in linker script
4608 This command has the same effect as the @samp{--no-define-common}
4609 command-line option: to make @code{ld} omit the assignment of addresses
4610 to common symbols even for a non-relocatable output file.
4612 @item FORCE_GROUP_ALLOCATION
4613 @kindex FORCE_GROUP_ALLOCATION
4614 @cindex group allocation in linker script
4615 @cindex section groups
4617 This command has the same effect as the
4618 @samp{--force-group-allocation} command-line option: to make
4619 @command{ld} place section group members like normal input sections,
4620 and to delete the section groups even if a relocatable output file is
4621 specified (@samp{-r}).
4623 @item INSERT [ AFTER | BEFORE ] @var{output_section}
4625 @cindex insert user script into default script
4626 This command is typically used in a script specified by @samp{-T} to
4627 augment the default @code{SECTIONS} with, for example, overlays. It
4628 inserts all prior linker script statements after (or before)
4629 @var{output_section}, and also causes @samp{-T} to not override the
4630 default linker script. The exact insertion point is as for orphan
4631 sections. @xref{Location Counter}. The insertion happens after the
4632 linker has mapped input sections to output sections. Prior to the
4633 insertion, since @samp{-T} scripts are parsed before the default
4634 linker script, statements in the @samp{-T} script occur before the
4635 default linker script statements in the internal linker representation
4636 of the script. In particular, input section assignments will be made
4637 to @samp{-T} output sections before those in the default script. Here
4638 is an example of how a @samp{-T} script using @code{INSERT} might look:
4645 .ov1 @{ ov1*(.text) @}
4646 .ov2 @{ ov2*(.text) @}
4652 Note that when @samp{-T} is used twice, once to override the default
4653 script and once to augment that script using @code{INSERT} the order
4654 of parsing and section assignments apply as for the default script.
4655 The script with @code{INSERT} should be specified @emph{first} on the
4658 @item NOCROSSREFS(@var{section} @var{section} @dots{})
4659 @kindex NOCROSSREFS(@var{sections})
4660 @cindex cross references
4661 This command may be used to tell @command{ld} to issue an error about any
4662 references among certain output sections.
4664 In certain types of programs, particularly on embedded systems when
4665 using overlays, when one section is loaded into memory, another section
4666 will not be. Any direct references between the two sections would be
4667 errors. For example, it would be an error if code in one section called
4668 a function defined in the other section.
4670 The @code{NOCROSSREFS} command takes a list of output section names. If
4671 @command{ld} detects any cross references between the sections, it reports
4672 an error and returns a non-zero exit status. Note that the
4673 @code{NOCROSSREFS} command uses output section names, not input section
4676 @item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{})
4677 @kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections})
4678 @cindex cross references
4679 This command may be used to tell @command{ld} to issue an error about any
4680 references to one section from a list of other sections.
4682 The @code{NOCROSSREFS} command is useful when ensuring that two or more
4683 output sections are entirely independent but there are situations where
4684 a one-way dependency is needed. For example, in a multi-core application
4685 there may be shared code that can be called from each core but for safety
4686 must never call back.
4688 The @code{NOCROSSREFS_TO} command takes a list of output section names.
4689 The first section can not be referenced from any of the other sections.
4690 If @command{ld} detects any references to the first section from any of
4691 the other sections, it reports an error and returns a non-zero exit
4692 status. Note that the @code{NOCROSSREFS_TO} command uses output section
4693 names, not input section names.
4695 @ifclear SingleFormat
4696 @item OUTPUT_ARCH(@var{bfdarch})
4697 @kindex OUTPUT_ARCH(@var{bfdarch})
4698 @cindex machine architecture
4699 @cindex architecture
4700 Specify a particular output machine architecture. The argument is one
4701 of the names used by the BFD library (@pxref{BFD}). You can see the
4702 architecture of an object file by using the @code{objdump} program with
4703 the @samp{-f} option.
4706 @item LD_FEATURE(@var{string})
4707 @kindex LD_FEATURE(@var{string})
4708 This command may be used to modify @command{ld} behavior. If
4709 @var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
4710 in a script are simply treated as numbers everywhere.
4711 @xref{Expression Section}.
4715 @section Assigning Values to Symbols
4716 @cindex assignment in scripts
4717 @cindex symbol definition, scripts
4718 @cindex variables, defining
4719 You may assign a value to a symbol in a linker script. This will define
4720 the symbol and place it into the symbol table with a global scope.
4723 * Simple Assignments:: Simple Assignments
4726 * PROVIDE_HIDDEN:: PROVIDE_HIDDEN
4727 * Source Code Reference:: How to use a linker script defined symbol in source code
4730 @node Simple Assignments
4731 @subsection Simple Assignments
4733 You may assign to a symbol using any of the C assignment operators:
4736 @item @var{symbol} = @var{expression} ;
4737 @itemx @var{symbol} += @var{expression} ;
4738 @itemx @var{symbol} -= @var{expression} ;
4739 @itemx @var{symbol} *= @var{expression} ;
4740 @itemx @var{symbol} /= @var{expression} ;
4741 @itemx @var{symbol} <<= @var{expression} ;
4742 @itemx @var{symbol} >>= @var{expression} ;
4743 @itemx @var{symbol} &= @var{expression} ;
4744 @itemx @var{symbol} |= @var{expression} ;
4747 The first case will define @var{symbol} to the value of
4748 @var{expression}. In the other cases, @var{symbol} must already be
4749 defined, and the value will be adjusted accordingly.
4751 The special symbol name @samp{.} indicates the location counter. You
4752 may only use this within a @code{SECTIONS} command. @xref{Location Counter}.
4754 The semicolon after @var{expression} is required.
4756 Expressions are defined below; see @ref{Expressions}.
4758 You may write symbol assignments as commands in their own right, or as
4759 statements within a @code{SECTIONS} command, or as part of an output
4760 section description in a @code{SECTIONS} command.
4762 The section of the symbol will be set from the section of the
4763 expression; for more information, see @ref{Expression Section}.
4765 Here is an example showing the three different places that symbol
4766 assignments may be used:
4777 _bdata = (. + 3) & ~ 3;
4778 .data : @{ *(.data) @}
4782 In this example, the symbol @samp{floating_point} will be defined as
4783 zero. The symbol @samp{_etext} will be defined as the address following
4784 the last @samp{.text} input section. The symbol @samp{_bdata} will be
4785 defined as the address following the @samp{.text} output section aligned
4786 upward to a 4 byte boundary.
4791 For ELF targeted ports, define a symbol that will be hidden and won't be
4792 exported. The syntax is @code{HIDDEN(@var{symbol} = @var{expression})}.
4794 Here is the example from @ref{Simple Assignments}, rewritten to use
4798 HIDDEN(floating_point = 0);
4806 HIDDEN(_bdata = (. + 3) & ~ 3);
4807 .data : @{ *(.data) @}
4811 In this case none of the three symbols will be visible outside this module.
4816 In some cases, it is desirable for a linker script to define a symbol
4817 only if it is referenced and is not defined by any object included in
4818 the link. For example, traditional linkers defined the symbol
4819 @samp{etext}. However, ANSI C requires that the user be able to use
4820 @samp{etext} as a function name without encountering an error. The
4821 @code{PROVIDE} keyword may be used to define a symbol, such as
4822 @samp{etext}, only if it is referenced but not defined. The syntax is
4823 @code{PROVIDE(@var{symbol} = @var{expression})}.
4825 Here is an example of using @code{PROVIDE} to define @samp{etext}:
4838 In this example, if the program defines @samp{_etext} (with a leading
4839 underscore), the linker will give a multiple definition diagnostic. If,
4840 on the other hand, the program defines @samp{etext} (with no leading
4841 underscore), the linker will silently use the definition in the program.
4842 If the program references @samp{etext} but does not define it, the
4843 linker will use the definition in the linker script.
4845 Note - the @code{PROVIDE} directive considers a common symbol to be
4846 defined, even though such a symbol could be combined with the symbol
4847 that the @code{PROVIDE} would create. This is particularly important
4848 when considering constructor and destructor list symbols such as
4849 @samp{__CTOR_LIST__} as these are often defined as common symbols.
4851 @node PROVIDE_HIDDEN
4852 @subsection PROVIDE_HIDDEN
4853 @cindex PROVIDE_HIDDEN
4854 Similar to @code{PROVIDE}. For ELF targeted ports, the symbol will be
4855 hidden and won't be exported.
4857 @node Source Code Reference
4858 @subsection Source Code Reference
4860 Accessing a linker script defined variable from source code is not
4861 intuitive. In particular a linker script symbol is not equivalent to
4862 a variable declaration in a high level language, it is instead a
4863 symbol that does not have a value.
4865 Before going further, it is important to note that compilers often
4866 transform names in the source code into different names when they are
4867 stored in the symbol table. For example, Fortran compilers commonly
4868 prepend or append an underscore, and C++ performs extensive @samp{name
4869 mangling}. Therefore there might be a discrepancy between the name
4870 of a variable as it is used in source code and the name of the same
4871 variable as it is defined in a linker script. For example in C a
4872 linker script variable might be referred to as:
4878 But in the linker script it might be defined as:
4884 In the remaining examples however it is assumed that no name
4885 transformation has taken place.
4887 When a symbol is declared in a high level language such as C, two
4888 things happen. The first is that the compiler reserves enough space
4889 in the program's memory to hold the @emph{value} of the symbol. The
4890 second is that the compiler creates an entry in the program's symbol
4891 table which holds the symbol's @emph{address}. ie the symbol table
4892 contains the address of the block of memory holding the symbol's
4893 value. So for example the following C declaration, at file scope:
4899 creates an entry called @samp{foo} in the symbol table. This entry
4900 holds the address of an @samp{int} sized block of memory where the
4901 number 1000 is initially stored.
4903 When a program references a symbol the compiler generates code that
4904 first accesses the symbol table to find the address of the symbol's
4905 memory block and then code to read the value from that memory block.
4912 looks up the symbol @samp{foo} in the symbol table, gets the address
4913 associated with this symbol and then writes the value 1 into that
4920 looks up the symbol @samp{foo} in the symbol table, gets its address
4921 and then copies this address into the block of memory associated with
4922 the variable @samp{a}.
4924 Linker scripts symbol declarations, by contrast, create an entry in
4925 the symbol table but do not assign any memory to them. Thus they are
4926 an address without a value. So for example the linker script definition:
4932 creates an entry in the symbol table called @samp{foo} which holds
4933 the address of memory location 1000, but nothing special is stored at
4934 address 1000. This means that you cannot access the @emph{value} of a
4935 linker script defined symbol - it has no value - all you can do is
4936 access the @emph{address} of a linker script defined symbol.
4938 Hence when you are using a linker script defined symbol in source code
4939 you should always take the address of the symbol, and never attempt to
4940 use its value. For example suppose you want to copy the contents of a
4941 section of memory called .ROM into a section called .FLASH and the
4942 linker script contains these declarations:
4946 start_of_ROM = .ROM;
4947 end_of_ROM = .ROM + sizeof (.ROM);
4948 start_of_FLASH = .FLASH;
4952 Then the C source code to perform the copy would be:
4956 extern char start_of_ROM, end_of_ROM, start_of_FLASH;
4958 memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
4962 Note the use of the @samp{&} operators. These are correct.
4963 Alternatively the symbols can be treated as the names of vectors or
4964 arrays and then the code will again work as expected:
4968 extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
4970 memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);
4974 Note how using this method does not require the use of @samp{&}
4978 @section SECTIONS Command
4980 The @code{SECTIONS} command tells the linker how to map input sections
4981 into output sections, and how to place the output sections in memory.
4983 The format of the @code{SECTIONS} command is:
4987 @var{sections-command}
4988 @var{sections-command}
4993 Each @var{sections-command} may of be one of the following:
4997 an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
4999 a symbol assignment (@pxref{Assignments})
5001 an output section description
5003 an overlay description
5006 The @code{ENTRY} command and symbol assignments are permitted inside the
5007 @code{SECTIONS} command for convenience in using the location counter in
5008 those commands. This can also make the linker script easier to
5009 understand because you can use those commands at meaningful points in
5010 the layout of the output file.
5012 Output section descriptions and overlay descriptions are described
5015 If you do not use a @code{SECTIONS} command in your linker script, the
5016 linker will place each input section into an identically named output
5017 section in the order that the sections are first encountered in the
5018 input files. If all input sections are present in the first file, for
5019 example, the order of sections in the output file will match the order
5020 in the first input file. The first section will be at address zero.
5023 * Output Section Description:: Output section description
5024 * Output Section Name:: Output section name
5025 * Output Section Address:: Output section address
5026 * Input Section:: Input section description
5027 * Output Section Data:: Output section data
5028 * Output Section Keywords:: Output section keywords
5029 * Output Section Discarding:: Output section discarding
5030 * Output Section Attributes:: Output section attributes
5031 * Overlay Description:: Overlay description
5034 @node Output Section Description
5035 @subsection Output Section Description
5036 The full description of an output section looks like this:
5039 @var{section} [@var{address}] [(@var{type})] :
5041 [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
5042 [SUBALIGN(@var{subsection_align})]
5045 @var{output-section-command}
5046 @var{output-section-command}
5048 @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,]
5052 Most output sections do not use most of the optional section attributes.
5054 The whitespace around @var{section} is required, so that the section
5055 name is unambiguous. The colon and the curly braces are also required.
5056 The comma at the end may be required if a @var{fillexp} is used and
5057 the next @var{sections-command} looks like a continuation of the expression.
5058 The line breaks and other white space are optional.
5060 Each @var{output-section-command} may be one of the following:
5064 a symbol assignment (@pxref{Assignments})
5066 an input section description (@pxref{Input Section})
5068 data values to include directly (@pxref{Output Section Data})
5070 a special output section keyword (@pxref{Output Section Keywords})
5073 @node Output Section Name
5074 @subsection Output Section Name
5075 @cindex name, section
5076 @cindex section name
5077 The name of the output section is @var{section}. @var{section} must
5078 meet the constraints of your output format. In formats which only
5079 support a limited number of sections, such as @code{a.out}, the name
5080 must be one of the names supported by the format (@code{a.out}, for
5081 example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
5082 output format supports any number of sections, but with numbers and not
5083 names (as is the case for Oasys), the name should be supplied as a
5084 quoted numeric string. A section name may consist of any sequence of
5085 characters, but a name which contains any unusual characters such as
5086 commas must be quoted.
5088 The output section name @samp{/DISCARD/} is special; @ref{Output Section
5091 @node Output Section Address
5092 @subsection Output Section Address
5093 @cindex address, section
5094 @cindex section address
5095 The @var{address} is an expression for the VMA (the virtual memory
5096 address) of the output section. This address is optional, but if it
5097 is provided then the output address will be set exactly as specified.
5099 If the output address is not specified then one will be chosen for the
5100 section, based on the heuristic below. This address will be adjusted
5101 to fit the alignment requirement of the output section. The
5102 alignment requirement is the strictest alignment of any input section
5103 contained within the output section.
5105 The output section address heuristic is as follows:
5109 If an output memory @var{region} is set for the section then it
5110 is added to this region and its address will be the next free address
5114 If the MEMORY command has been used to create a list of memory
5115 regions then the first region which has attributes compatible with the
5116 section is selected to contain it. The section's output address will
5117 be the next free address in that region; @ref{MEMORY}.
5120 If no memory regions were specified, or none match the section then
5121 the output address will be based on the current value of the location
5129 .text . : @{ *(.text) @}
5136 .text : @{ *(.text) @}
5140 are subtly different. The first will set the address of the
5141 @samp{.text} output section to the current value of the location
5142 counter. The second will set it to the current value of the location
5143 counter aligned to the strictest alignment of any of the @samp{.text}
5146 The @var{address} may be an arbitrary expression; @ref{Expressions}.
5147 For example, if you want to align the section on a 0x10 byte boundary,
5148 so that the lowest four bits of the section address are zero, you could
5149 do something like this:
5151 .text ALIGN(0x10) : @{ *(.text) @}
5154 This works because @code{ALIGN} returns the current location counter
5155 aligned upward to the specified value.
5157 Specifying @var{address} for a section will change the value of the
5158 location counter, provided that the section is non-empty. (Empty
5159 sections are ignored).
5162 @subsection Input Section Description
5163 @cindex input sections
5164 @cindex mapping input sections to output sections
5165 The most common output section command is an input section description.
5167 The input section description is the most basic linker script operation.
5168 You use output sections to tell the linker how to lay out your program
5169 in memory. You use input section descriptions to tell the linker how to
5170 map the input files into your memory layout.
5173 * Input Section Basics:: Input section basics
5174 * Input Section Wildcards:: Input section wildcard patterns
5175 * Input Section Common:: Input section for common symbols
5176 * Input Section Keep:: Input section and garbage collection
5177 * Input Section Example:: Input section example
5180 @node Input Section Basics
5181 @subsubsection Input Section Basics
5182 @cindex input section basics
5183 An input section description consists of a file name optionally followed
5184 by a list of section names in parentheses.
5186 The file name and the section name may be wildcard patterns, which we
5187 describe further below (@pxref{Input Section Wildcards}).
5189 The most common input section description is to include all input
5190 sections with a particular name in the output section. For example, to
5191 include all input @samp{.text} sections, you would write:
5196 Here the @samp{*} is a wildcard which matches any file name. To exclude a list
5197 @cindex EXCLUDE_FILE
5198 of files from matching the file name wildcard, EXCLUDE_FILE may be used to
5199 match all files except the ones specified in the EXCLUDE_FILE list. For
5202 EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors)
5205 will cause all .ctors sections from all files except @file{crtend.o}
5206 and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be
5207 placed inside the section list, for example:
5209 *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
5212 The result of this is identically to the previous example. Supporting
5213 two syntaxes for EXCLUDE_FILE is useful if the section list contains
5214 more than one section, as described below.
5216 There are two ways to include more than one section:
5222 The difference between these is the order in which the @samp{.text} and
5223 @samp{.rdata} input sections will appear in the output section. In the
5224 first example, they will be intermingled, appearing in the same order as
5225 they are found in the linker input. In the second example, all
5226 @samp{.text} input sections will appear first, followed by all
5227 @samp{.rdata} input sections.
5229 When using EXCLUDE_FILE with more than one section, if the exclusion
5230 is within the section list then the exclusion only applies to the
5231 immediately following section, for example:
5233 *(EXCLUDE_FILE (*somefile.o) .text .rdata)
5236 will cause all @samp{.text} sections from all files except
5237 @file{somefile.o} to be included, while all @samp{.rdata} sections
5238 from all files, including @file{somefile.o}, will be included. To
5239 exclude the @samp{.rdata} sections from @file{somefile.o} the example
5240 could be modified to:
5242 *(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
5245 Alternatively, placing the EXCLUDE_FILE outside of the section list,
5246 before the input file selection, will cause the exclusion to apply for
5247 all sections. Thus the previous example can be rewritten as:
5249 EXCLUDE_FILE (*somefile.o) *(.text .rdata)
5252 You can specify a file name to include sections from a particular file.
5253 You would do this if one or more of your files contain special data that
5254 needs to be at a particular location in memory. For example:
5259 To refine the sections that are included based on the section flags
5260 of an input section, INPUT_SECTION_FLAGS may be used.
5262 Here is a simple example for using Section header flags for ELF sections:
5267 .text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @}
5268 .text2 : @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @}
5273 In this example, the output section @samp{.text} will be comprised of any
5274 input section matching the name *(.text) whose section header flags
5275 @code{SHF_MERGE} and @code{SHF_STRINGS} are set. The output section
5276 @samp{.text2} will be comprised of any input section matching the name *(.text)
5277 whose section header flag @code{SHF_WRITE} is clear.
5279 You can also specify files within archives by writing a pattern
5280 matching the archive, a colon, then the pattern matching the file,
5281 with no whitespace around the colon.
5285 matches file within archive
5287 matches the whole archive
5289 matches file but not one in an archive
5292 Either one or both of @samp{archive} and @samp{file} can contain shell
5293 wildcards. On DOS based file systems, the linker will assume that a
5294 single letter followed by a colon is a drive specifier, so
5295 @samp{c:myfile.o} is a simple file specification, not @samp{myfile.o}
5296 within an archive called @samp{c}. @samp{archive:file} filespecs may
5297 also be used within an @code{EXCLUDE_FILE} list, but may not appear in
5298 other linker script contexts. For instance, you cannot extract a file
5299 from an archive by using @samp{archive:file} in an @code{INPUT}
5302 If you use a file name without a list of sections, then all sections in
5303 the input file will be included in the output section. This is not
5304 commonly done, but it may by useful on occasion. For example:
5309 When you use a file name which is not an @samp{archive:file} specifier
5310 and does not contain any wild card
5311 characters, the linker will first see if you also specified the file
5312 name on the linker command line or in an @code{INPUT} command. If you
5313 did not, the linker will attempt to open the file as an input file, as
5314 though it appeared on the command line. Note that this differs from an
5315 @code{INPUT} command, because the linker will not search for the file in
5316 the archive search path.
5318 @node Input Section Wildcards
5319 @subsubsection Input Section Wildcard Patterns
5320 @cindex input section wildcards
5321 @cindex wildcard file name patterns
5322 @cindex file name wildcard patterns
5323 @cindex section name wildcard patterns
5324 In an input section description, either the file name or the section
5325 name or both may be wildcard patterns.
5327 The file name of @samp{*} seen in many examples is a simple wildcard
5328 pattern for the file name.
5330 The wildcard patterns are like those used by the Unix shell.
5334 matches any number of characters
5336 matches any single character
5338 matches a single instance of any of the @var{chars}; the @samp{-}
5339 character may be used to specify a range of characters, as in
5340 @samp{[a-z]} to match any lower case letter
5342 quotes the following character
5345 File name wildcard patterns only match files which are explicitly
5346 specified on the command line or in an @code{INPUT} command. The linker
5347 does not search directories to expand wildcards.
5349 If a file name matches more than one wildcard pattern, or if a file name
5350 appears explicitly and is also matched by a wildcard pattern, the linker
5351 will use the first match in the linker script. For example, this
5352 sequence of input section descriptions is probably in error, because the
5353 @file{data.o} rule will not be used:
5355 .data : @{ *(.data) @}
5356 .data1 : @{ data.o(.data) @}
5359 @cindex SORT_BY_NAME
5360 Normally, the linker will place files and sections matched by wildcards
5361 in the order in which they are seen during the link. You can change
5362 this by using the @code{SORT_BY_NAME} keyword, which appears before a wildcard
5363 pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the
5364 @code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
5365 into ascending order by name before placing them in the output file.
5367 @cindex SORT_BY_ALIGNMENT
5368 @code{SORT_BY_ALIGNMENT} is similar to @code{SORT_BY_NAME}.
5369 @code{SORT_BY_ALIGNMENT} will sort sections into descending order of
5370 alignment before placing them in the output file. Placing larger
5371 alignments before smaller alignments can reduce the amount of padding
5374 @cindex SORT_BY_INIT_PRIORITY
5375 @code{SORT_BY_INIT_PRIORITY} is also similar to @code{SORT_BY_NAME}.
5376 @code{SORT_BY_INIT_PRIORITY} will sort sections into ascending
5377 numerical order of the GCC init_priority attribute encoded in the
5378 section name before placing them in the output file. In
5379 @code{.init_array.NNNNN} and @code{.fini_array.NNNNN}, @code{NNNNN} is
5380 the init_priority. In @code{.ctors.NNNNN} and @code{.dtors.NNNNN},
5381 @code{NNNNN} is 65535 minus the init_priority.
5384 @code{SORT} is an alias for @code{SORT_BY_NAME}.
5387 @code{REVERSE} indicates that the sorting should be reversed. If used
5388 on its own then @code{REVERSE} implies @code{SORT_BY_NAME}, otherwise
5389 it reverses the enclosed @code{SORT..} command. Note - reverse
5390 sorting of alignment is not currently supported.
5392 Note - the sorting commands only accept a single wildcard pattern. So
5393 for example the following will not work:
5395 *(REVERSE(.text* .init*))
5397 To resolve this problem list the patterns individually, like this:
5403 Note - you can put the @code{EXCLUDE_FILE} command inside a sorting
5404 command, but not the other way around. So for example:
5406 *(SORT_BY_NAME(EXCLUDE_FILE(foo) .text*))
5410 *(EXCLUDE_FILE(foo) SORT_BY_NAME(.text*))
5415 When there are nested section sorting commands in linker script, there
5416 can be at most 1 level of nesting for section sorting commands.
5420 @code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
5421 It will sort the input sections by name first, then by alignment if two
5422 sections have the same name.
5424 @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
5425 It will sort the input sections by alignment first, then by name if two
5426 sections have the same alignment.
5428 @code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
5429 treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
5431 @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
5432 is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
5434 @code{SORT_BY_NAME} (@code{REVERSE} (wildcard section pattern))
5435 reverse sorts by name.
5437 @code{REVERSE} (@code{SORT_BY_NAME} (wildcard section pattern))
5438 reverse sorts by name.
5440 @code{SORT_BY_INIT_PRIORITY} (@code{REVERSE} (wildcard section pattern))
5441 reverse sorts by init priority.
5443 All other nested section sorting commands are invalid.
5446 When both command-line section sorting option and linker script
5447 section sorting command are used, section sorting command always
5448 takes precedence over the command-line option.
5450 If the section sorting command in linker script isn't nested, the
5451 command-line option will make the section sorting command to be
5452 treated as nested sorting command.
5456 @code{SORT_BY_NAME} (wildcard section pattern ) with
5457 @option{--sort-sections alignment} is equivalent to
5458 @code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
5460 @code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
5461 @option{--sort-section name} is equivalent to
5462 @code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
5465 If the section sorting command in linker script is nested, the
5466 command-line option will be ignored.
5469 @code{SORT_NONE} disables section sorting by ignoring the command-line
5470 section sorting option.
5472 If you ever get confused about where input sections are going, use the
5473 @samp{-M} linker option to generate a map file. The map file shows
5474 precisely how input sections are mapped to output sections.
5476 This example shows how wildcard patterns might be used to partition
5477 files. This linker script directs the linker to place all @samp{.text}
5478 sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
5479 The linker will place the @samp{.data} section from all files beginning
5480 with an upper case character in @samp{.DATA}; for all other files, the
5481 linker will place the @samp{.data} section in @samp{.data}.
5485 .text : @{ *(.text) @}
5486 .DATA : @{ [A-Z]*(.data) @}
5487 .data : @{ *(.data) @}
5488 .bss : @{ *(.bss) @}
5493 @node Input Section Common
5494 @subsubsection Input Section for Common Symbols
5495 @cindex common symbol placement
5496 @cindex uninitialized data placement
5497 A special notation is needed for common symbols, because in many object
5498 file formats common symbols do not have a particular input section. The
5499 linker treats common symbols as though they are in an input section
5500 named @samp{COMMON}.
5502 You may use file names with the @samp{COMMON} section just as with any
5503 other input sections. You can use this to place common symbols from a
5504 particular input file in one section while common symbols from other
5505 input files are placed in another section.
5507 In most cases, common symbols in input files will be placed in the
5508 @samp{.bss} section in the output file. For example:
5510 .bss @{ *(.bss) *(COMMON) @}
5513 @cindex scommon section
5514 @cindex small common symbols
5515 Some object file formats have more than one type of common symbol. For
5516 example, the MIPS ELF object file format distinguishes standard common
5517 symbols and small common symbols. In this case, the linker will use a
5518 different special section name for other types of common symbols. In
5519 the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
5520 symbols and @samp{.scommon} for small common symbols. This permits you
5521 to map the different types of common symbols into memory at different
5525 You will sometimes see @samp{[COMMON]} in old linker scripts. This
5526 notation is now considered obsolete. It is equivalent to
5529 @node Input Section Keep
5530 @subsubsection Input Section and Garbage Collection
5532 @cindex garbage collection
5533 When link-time garbage collection is in use (@samp{--gc-sections}),
5534 it is often useful to mark sections that should not be eliminated.
5535 This is accomplished by surrounding an input section's wildcard entry
5536 with @code{KEEP()}, as in @code{KEEP(*(.init))} or
5537 @code{KEEP(SORT_BY_NAME(*)(.ctors))}.
5539 @node Input Section Example
5540 @subsubsection Input Section Example
5541 The following example is a complete linker script. It tells the linker
5542 to read all of the sections from file @file{all.o} and place them at the
5543 start of output section @samp{outputa} which starts at location
5544 @samp{0x10000}. All of section @samp{.input1} from file @file{foo.o}
5545 follows immediately, in the same output section. All of section
5546 @samp{.input2} from @file{foo.o} goes into output section
5547 @samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
5548 All of the remaining @samp{.input1} and @samp{.input2} sections from any
5549 files are written to output section @samp{outputc}.
5577 If an output section's name is the same as the input section's name
5578 and is representable as a C identifier, then the linker will
5579 automatically @pxref{PROVIDE} two symbols: __start_SECNAME and
5580 __stop_SECNAME, where SECNAME is the name of the section. These
5581 indicate the start address and end address of the output section
5582 respectively. Note: most section names are not representable as
5583 C identifiers because they contain a @samp{.} character.
5585 @node Output Section Data
5586 @subsection Output Section Data
5588 @cindex section data
5589 @cindex output section data
5590 @kindex ASCIZ ``@var{string}''
5591 @kindex BYTE(@var{expression})
5592 @kindex SHORT(@var{expression})
5593 @kindex LONG(@var{expression})
5594 @kindex QUAD(@var{expression})
5595 @kindex SQUAD(@var{expression})
5596 You can include explicit bytes of data in an output section by using
5597 @code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
5598 an output section command. Each keyword is followed by an expression in
5599 parentheses providing the value to store (@pxref{Expressions}). The
5600 value of the expression is stored at the current value of the location
5603 The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
5604 store one, two, four, and eight bytes (respectively). After storing the
5605 bytes, the location counter is incremented by the number of bytes
5608 For example, this will store the byte 1 followed by the four byte value
5609 of the symbol @samp{addr}:
5615 When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
5616 same; they both store an 8 byte, or 64 bit, value. When both host and
5617 target are 32 bits, an expression is computed as 32 bits. In this case
5618 @code{QUAD} stores a 32 bit value zero extended to 64 bits, and
5619 @code{SQUAD} stores a 32 bit value sign extended to 64 bits.
5621 If the object file format of the output file has an explicit endianness,
5622 which is the normal case, the value will be stored in that endianness.
5623 When the object file format does not have an explicit endianness, as is
5624 true of, for example, S-records, the value will be stored in the
5625 endianness of the first input object file.
5627 You can include a zero-terminated string in an output section by using
5628 @code{ASCIZ}. The keyword is followed by a string which is stored at
5629 the current value of the location counter adding a zero byte at the
5630 end. If the string includes spaces it must be enclosed in double
5631 quotes. The string may contain '\n', '\r', '\t' and octal numbers.
5632 Hex numbers are not supported.
5634 For example, this string of 16 characters will create a 17 byte area
5636 ASCIZ "This is 16 bytes"
5639 Note---these commands only work inside a section description and not
5640 between them, so the following will produce an error from the linker:
5642 SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
5644 whereas this will work:
5646 SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
5649 @kindex FILL(@var{expression})
5650 @cindex holes, filling
5651 @cindex unspecified memory
5652 You may use the @code{FILL} command to set the fill pattern for the
5653 current section. It is followed by an expression in parentheses. Any
5654 otherwise unspecified regions of memory within the section (for example,
5655 gaps left due to the required alignment of input sections) are filled
5656 with the value of the expression, repeated as
5657 necessary. A @code{FILL} statement covers memory locations after the
5658 point at which it occurs in the section definition; by including more
5659 than one @code{FILL} statement, you can have different fill patterns in
5660 different parts of an output section.
5662 This example shows how to fill unspecified regions of memory with the
5668 The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
5669 section attribute, but it only affects the
5670 part of the section following the @code{FILL} command, rather than the
5671 entire section. If both are used, the @code{FILL} command takes
5672 precedence. @xref{Output Section Fill}, for details on the fill
5675 Note - normally the value of @code{expression} is zero extended to 4
5676 bytes when used to fill gaps. Thus @samp{FILL(144)} will fill a
5677 region with repeats of the pattern @samp{0 0 0 144}. The value is
5678 treated as a big-endian number, so for example
5679 @samp{FILL(22 * 256 + 23)} will fill the region with repeats of the
5680 pattern @samp{0 0 22 23}. If the expression results in a value with
5681 more than 4 significant bytes only the least 4 bytes of the value will
5684 The above rules do not apply when the @code{expression} is a simple
5685 hexadecimal number. In this case zero extension is not performed and
5686 all bytes are significant. So @samp{FILL(0x90)} will fill a region with
5687 repeats of @samp{0x90} with no zero bytes, and @samp{FILL(0x9192)}
5688 will fill the region with repeats of @samp{0x91 0x92}. Zero bytes
5689 in a hexadecimal expression are significant even at the start, so
5690 @samp{FILL(0x0090)} will fill a region with repeats of @samp{0x00 0x90}.
5692 Hexadecimal numbers can be longer than 4 bytes, and all of the bytes
5693 are significant, so @samp{FILL(0x123456789a)} will fill a region with
5694 repeats of the 5 byte sequence @samp{0x12 0x34 0x56 0x78 0x9a}.
5695 Excess bytes in a hexadecimal value beyond the size of a region will
5696 be silently ignored.
5698 The above only applies to hexadecimal numbers specified as
5699 @samp{0x[0-9][a-f][A-F]}. Hexadecimal numbers specified with a
5700 @samp{$} prefix, or a @samp{h}, @samp{H}, @samp{x} or @samp{X} suffix
5701 will follow the normal fill value rules. This also applies to
5702 expressions that involve hexadecimal numbers, and hexadecimal numbers
5703 that have a magnitude suffix.
5705 @kindex LINKER_VERSION
5706 @cindex LINKER_VERSION
5707 The @code{LINKER_VERSION} command inserts a string containing the
5708 version of the linker at the current point. Note - by default this
5709 directive is disabled and will do nothing. It only becomes active if
5710 the @option{--enable-linker-version} command line option is used.
5712 Built-in linker scripts for ELF based targets already include this
5713 directive in their @samp{.comment} section.
5715 @node Output Section Keywords
5716 @subsection Output Section Keywords
5717 There are a couple of keywords which can appear as output section
5721 @kindex CREATE_OBJECT_SYMBOLS
5722 @cindex input filename symbols
5723 @cindex filename symbols
5724 @item CREATE_OBJECT_SYMBOLS
5725 The command tells the linker to create a symbol for each input file.
5726 The name of each symbol will be the name of the corresponding input
5727 file. The section of each symbol will be the output section in which
5728 the @code{CREATE_OBJECT_SYMBOLS} command appears.
5730 This is conventional for the a.out object file format. It is not
5731 normally used for any other object file format.
5733 @kindex CONSTRUCTORS
5734 @cindex C++ constructors, arranging in link
5735 @cindex constructors, arranging in link
5737 When linking using the a.out object file format, the linker uses an
5738 unusual set construct to support C++ global constructors and
5739 destructors. When linking object file formats which do not support
5740 arbitrary sections, such as ECOFF and XCOFF, the linker will
5741 automatically recognize C++ global constructors and destructors by name.
5742 For these object file formats, the @code{CONSTRUCTORS} command tells the
5743 linker to place constructor information in the output section where the
5744 @code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is
5745 ignored for other object file formats.
5747 The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
5748 constructors, and the symbol @w{@code{__CTOR_END__}} marks the end.
5749 Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark
5750 the start and end of the global destructors. The
5751 first word in the list is the number of entries, followed by the address
5752 of each constructor or destructor, followed by a zero word. The
5753 compiler must arrange to actually run the code. For these object file
5754 formats @sc{gnu} C++ normally calls constructors from a subroutine
5755 @code{__main}; a call to @code{__main} is automatically inserted into
5756 the startup code for @code{main}. @sc{gnu} C++ normally runs
5757 destructors either by using @code{atexit}, or directly from the function
5760 For object file formats such as @code{COFF} or @code{ELF} which support
5761 arbitrary section names, @sc{gnu} C++ will normally arrange to put the
5762 addresses of global constructors and destructors into the @code{.ctors}
5763 and @code{.dtors} sections. Placing the following sequence into your
5764 linker script will build the sort of table which the @sc{gnu} C++
5765 runtime code expects to see.
5769 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
5774 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
5780 If you are using the @sc{gnu} C++ support for initialization priority,
5781 which provides some control over the order in which global constructors
5782 are run, you must sort the constructors at link time to ensure that they
5783 are executed in the correct order. When using the @code{CONSTRUCTORS}
5784 command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead. When using the
5785 @code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
5786 @samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and
5789 Normally the compiler and linker will handle these issues automatically,
5790 and you will not need to concern yourself with them. However, you may
5791 need to consider this if you are using C++ and writing your own linker
5796 @node Output Section Discarding
5797 @subsection Output Section Discarding
5798 @cindex discarding sections
5799 @cindex sections, discarding
5800 @cindex removing sections
5801 The linker will not normally create output sections with no contents.
5802 This is for convenience when referring to input sections that may or
5803 may not be present in any of the input files. For example:
5805 .foo : @{ *(.foo) @}
5808 will only create a @samp{.foo} section in the output file if there is a
5809 @samp{.foo} section in at least one input file, and if the input
5810 sections are not all empty. Other link script directives that allocate
5811 space in an output section will also create the output section. So
5812 too will assignments to dot even if the assignment does not create
5813 space, except for @samp{. = 0}, @samp{. = . + 0}, @samp{. = sym},
5814 @samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when
5815 @samp{sym} is an absolute symbol of value 0 defined in the script.
5816 This allows you to force output of an empty section with @samp{. = .}.
5818 The linker will ignore address assignments (@pxref{Output Section Address})
5819 on discarded output sections, except when the linker script defines
5820 symbols in the output section. In that case the linker will obey
5821 the address assignments, possibly advancing dot even though the
5822 section is discarded.
5825 The special output section name @samp{/DISCARD/} may be used to discard
5826 input sections. Any input sections which are assigned to an output
5827 section named @samp{/DISCARD/} are not included in the output file.
5829 This can be used to discard input sections marked with the ELF flag
5830 @code{SHF_GNU_RETAIN}, which would otherwise have been saved from linker
5833 Note, sections that match the @samp{/DISCARD/} output section will be
5834 discarded even if they are in an ELF section group which has other
5835 members which are not being discarded. This is deliberate.
5836 Discarding takes precedence over grouping.
5838 @node Output Section Attributes
5839 @subsection Output Section Attributes
5840 @cindex output section attributes
5841 We showed above that the full description of an output section looked
5846 @var{section} [@var{address}] [(@var{type})] :
5848 [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT]
5849 [SUBALIGN(@var{subsection_align})]
5852 @var{output-section-command}
5853 @var{output-section-command}
5855 @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
5859 We've already described @var{section}, @var{address}, and
5860 @var{output-section-command}. In this section we will describe the
5861 remaining section attributes.
5864 * Output Section Type:: Output section type
5865 * Output Section LMA:: Output section LMA
5866 * Forced Output Alignment:: Forced Output Alignment
5867 * Forced Input Alignment:: Forced Input Alignment
5868 * Output Section Constraint:: Output section constraint
5869 * Output Section Region:: Output section region
5870 * Output Section Phdr:: Output section phdr
5871 * Output Section Fill:: Output section fill
5874 @node Output Section Type
5875 @subsubsection Output Section Type
5876 Each output section may have a type. The type is a keyword in
5877 parentheses. The following types are defined:
5882 The section should be marked as not loadable, so that it will not be
5883 loaded into memory when the program is run.
5886 The section should be marked as read-only.
5892 These type names are supported for backward compatibility, and are
5893 rarely used. They all have the same effect: the section should be
5894 marked as not allocatable, so that no memory is allocated for the
5895 section when the program is run.
5897 @item TYPE = @var{type}
5898 Set the section type to the integer @var{type}. When generating an ELF
5899 output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
5900 @code{SHT_NOTE}, @code{SHT_NOBITS}, @code{SHT_INIT_ARRAY},
5901 @code{SHT_FINI_ARRAY}, and @code{SHT_PREINIT_ARRAY} are also allowed
5902 for @var{type}. It is the user's responsibility to ensure that any
5903 special requirements of the section type are met.
5905 Note - the TYPE only is used if some or all of the contents of the
5906 section do not have an implicit type of their own. So for example:
5908 .foo . TYPE = SHT_PROGBITS @{ *(.bar) @}
5910 will set the type of section @samp{.foo} to the type of the section
5911 @samp{.bar} in the input files, which may not be the SHT_PROGBITS
5914 .foo . TYPE = SHT_PROGBITS @{ BYTE(1) @}
5916 will set the type of @samp{.foo} to SHT_PROGBBITS. If it is necessary
5917 to override the type of incoming sections and force the output section
5918 type then an extra piece of untyped data will be needed:
5920 .foo . TYPE = SHT_PROGBITS @{ BYTE(1); *(.bar) @}
5923 @item READONLY ( TYPE = @var{type} )
5924 This form of the syntax combines the @var{READONLY} type with the
5925 type specified by @var{type}.
5930 @cindex prevent unnecessary loading
5931 @cindex loading, preventing
5932 The linker normally sets the attributes of an output section based on
5933 the input sections which map into it. You can override this by using
5934 the section type. For example, in the script sample below, the
5935 @samp{ROM} section is addressed at memory location @samp{0} and does not
5936 need to be loaded when the program is run.
5940 ROM 0 (NOLOAD) : @{ @dots{} @}
5946 @node Output Section LMA
5947 @subsubsection Output Section LMA
5948 @kindex AT>@var{lma_region}
5949 @kindex AT(@var{lma})
5950 @cindex load address
5951 @cindex section load address
5952 Every section has a virtual address (VMA) and a load address (LMA); see
5953 @ref{Basic Script Concepts}. The virtual address is specified by the
5954 @pxref{Output Section Address} described earlier. The load address is
5955 specified by the @code{AT} or @code{AT>} keywords. Specifying a load
5956 address is optional.
5958 The @code{AT} keyword takes an expression as an argument. This
5959 specifies the exact load address of the section. The @code{AT>} keyword
5960 takes the name of a memory region as an argument. @xref{MEMORY}. The
5961 load address of the section is set to the next free address in the
5962 region, aligned to the section's alignment requirements.
5964 If neither @code{AT} nor @code{AT>} is specified for an allocatable
5965 section, the linker will use the following heuristic to determine the
5970 If the section has a specific VMA address, then this is used as
5971 the LMA address as well.
5974 If the section is not allocatable then its LMA is set to its VMA.
5977 Otherwise if a memory region can be found that is compatible
5978 with the current section, and this region contains at least one
5979 section, then the LMA is set so the difference between the
5980 VMA and LMA is the same as the difference between the VMA and LMA of
5981 the last section in the located region.
5984 If no memory regions have been declared then a default region
5985 that covers the entire address space is used in the previous step.
5988 If no suitable region could be found, or there was no previous
5989 section then the LMA is set equal to the VMA.
5992 @cindex ROM initialized data
5993 @cindex initialized data in ROM
5994 This feature is designed to make it easy to build a ROM image. For
5995 example, the following linker script creates three output sections: one
5996 called @samp{.text}, which starts at @code{0x1000}, one called
5997 @samp{.mdata}, which is loaded at the end of the @samp{.text} section
5998 even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
5999 uninitialized data at address @code{0x3000}. The symbol @code{_data} is
6000 defined with the value @code{0x2000}, which shows that the location
6001 counter holds the VMA value, not the LMA value.
6007 .text 0x1000 : @{ *(.text) _etext = . ; @}
6009 AT ( ADDR (.text) + SIZEOF (.text) )
6010 @{ _data = . ; *(.data); _edata = . ; @}
6012 @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
6017 The run-time initialization code for use with a program generated with
6018 this linker script would include something like the following, to copy
6019 the initialized data from the ROM image to its runtime address. Notice
6020 how this code takes advantage of the symbols defined by the linker
6025 extern char _etext, _data, _edata, _bstart, _bend;
6026 char *src = &_etext;
6029 /* ROM has data at end of text; copy it. */
6030 while (dst < &_edata)
6034 for (dst = &_bstart; dst< &_bend; dst++)
6039 @node Forced Output Alignment
6040 @subsubsection Forced Output Alignment
6041 @kindex ALIGN(@var{section_align})
6042 @cindex forcing output section alignment
6043 @cindex output section alignment
6044 You can increase an output section's alignment by using ALIGN. As an
6045 alternative you can enforce that the difference between the VMA and LMA remains
6046 intact throughout this output section with the ALIGN_WITH_INPUT attribute.
6048 @node Forced Input Alignment
6049 @subsubsection Forced Input Alignment
6050 @kindex SUBALIGN(@var{subsection_align})
6051 @cindex forcing input section alignment
6052 @cindex input section alignment
6053 You can force input section alignment within an output section by using
6054 SUBALIGN. The value specified overrides any alignment given by input
6055 sections, whether larger or smaller.
6057 @node Output Section Constraint
6058 @subsubsection Output Section Constraint
6061 @cindex constraints on output sections
6062 You can specify that an output section should only be created if all
6063 of its input sections are read-only or all of its input sections are
6064 read-write by using the keyword @code{ONLY_IF_RO} and
6065 @code{ONLY_IF_RW} respectively.
6067 @node Output Section Region
6068 @subsubsection Output Section Region
6069 @kindex >@var{region}
6070 @cindex section, assigning to memory region
6071 @cindex memory regions and sections
6072 You can assign a section to a previously defined region of memory by
6073 using @samp{>@var{region}}. @xref{MEMORY}.
6075 Here is a simple example:
6078 MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
6079 SECTIONS @{ ROM : @{ *(.text) @} >rom @}
6083 @node Output Section Phdr
6084 @subsubsection Output Section Phdr
6086 @cindex section, assigning to program header
6087 @cindex program headers and sections
6088 You can assign a section to a previously defined program segment by
6089 using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to
6090 one or more segments, then all subsequent allocated sections will be
6091 assigned to those segments as well, unless they use an explicitly
6092 @code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the
6093 linker to not put the section in any segment at all.
6095 Here is a simple example:
6098 PHDRS @{ text PT_LOAD ; @}
6099 SECTIONS @{ .text : @{ *(.text) @} :text @}
6103 @node Output Section Fill
6104 @subsubsection Output Section Fill
6105 @kindex =@var{fillexp}
6106 @cindex section fill pattern
6107 @cindex fill pattern, entire section
6108 You can set the fill pattern for an entire section by using
6109 @samp{=@var{fillexp}}. @var{fillexp} is an expression
6110 (@pxref{Expressions}). Any otherwise unspecified regions of memory
6111 within the output section (for example, gaps left due to the required
6112 alignment of input sections) will be filled with the value, repeated as
6113 necessary. If the fill expression is a simple hex number, ie. a string
6114 of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
6115 an arbitrarily long sequence of hex digits can be used to specify the
6116 fill pattern; Leading zeros become part of the pattern too. For all
6117 other cases, including extra parentheses or a unary @code{+}, the fill
6118 pattern is the four least significant bytes of the value of the
6119 expression. If the value is less than four bytes in size then it will
6120 be zero extended to four bytes. In all cases, the number is big-endian.
6123 Fill Value Fill Pattern
6129 You can also change the fill value with a @code{FILL} command in the
6130 output section commands; (@pxref{Output Section Data}).
6132 Here is a simple example:
6135 SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
6139 @node Overlay Description
6140 @subsection Overlay Description
6143 An overlay description provides an easy way to describe sections which
6144 are to be loaded as part of a single memory image but are to be run at
6145 the same memory address. At run time, some sort of overlay manager will
6146 copy the overlaid sections in and out of the runtime memory address as
6147 required, perhaps by simply manipulating addressing bits. This approach
6148 can be useful, for example, when a certain region of memory is faster
6151 Overlays are described using the @code{OVERLAY} command. The
6152 @code{OVERLAY} command is used within a @code{SECTIONS} command, like an
6153 output section description. The full syntax of the @code{OVERLAY}
6154 command is as follows:
6157 OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
6161 @var{output-section-command}
6162 @var{output-section-command}
6164 @} [:@var{phdr}@dots{}] [=@var{fill}]
6167 @var{output-section-command}
6168 @var{output-section-command}
6170 @} [:@var{phdr}@dots{}] [=@var{fill}]
6172 @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,]
6176 Everything is optional except @code{OVERLAY} (a keyword), and each
6177 section must have a name (@var{secname1} and @var{secname2} above). The
6178 section definitions within the @code{OVERLAY} construct are identical to
6179 those within the general @code{SECTIONS} construct (@pxref{SECTIONS}),
6180 except that no addresses and no memory regions may be defined for
6181 sections within an @code{OVERLAY}.
6183 The comma at the end may be required if a @var{fill} is used and
6184 the next @var{sections-command} looks like a continuation of the expression.
6186 The sections are all defined with the same starting address. The load
6187 addresses of the sections are arranged such that they are consecutive in
6188 memory starting at the load address used for the @code{OVERLAY} as a
6189 whole (as with normal section definitions, the load address is optional,
6190 and defaults to the start address; the start address is also optional,
6191 and defaults to the current value of the location counter).
6193 If the @code{NOCROSSREFS} keyword is used, and there are any
6194 references among the sections, the linker will report an error. Since
6195 the sections all run at the same address, it normally does not make
6196 sense for one section to refer directly to another.
6197 @xref{Miscellaneous Commands, NOCROSSREFS}.
6199 For each section within the @code{OVERLAY}, the linker automatically
6200 provides two symbols. The symbol @code{__load_start_@var{secname}} is
6201 defined as the starting load address of the section. The symbol
6202 @code{__load_stop_@var{secname}} is defined as the final load address of
6203 the section. Any characters within @var{secname} which are not legal
6204 within C identifiers are removed. C (or assembler) code may use these
6205 symbols to move the overlaid sections around as necessary.
6207 At the end of the overlay, the value of the location counter is set to
6208 the start address of the overlay plus the size of the largest section.
6210 Here is an example. Remember that this would appear inside a
6211 @code{SECTIONS} construct.
6214 OVERLAY 0x1000 : AT (0x4000)
6216 .text0 @{ o1/*.o(.text) @}
6217 .text1 @{ o2/*.o(.text) @}
6222 This will define both @samp{.text0} and @samp{.text1} to start at
6223 address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
6224 @samp{.text1} will be loaded immediately after @samp{.text0}. The
6225 following symbols will be defined if referenced: @code{__load_start_text0},
6226 @code{__load_stop_text0}, @code{__load_start_text1},
6227 @code{__load_stop_text1}.
6229 C code to copy overlay @code{.text1} into the overlay area might look
6234 extern char __load_start_text1, __load_stop_text1;
6235 memcpy ((char *) 0x1000, &__load_start_text1,
6236 &__load_stop_text1 - &__load_start_text1);
6240 Note that the @code{OVERLAY} command is just syntactic sugar, since
6241 everything it does can be done using the more basic commands. The above
6242 example could have been written identically as follows.
6246 .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
6247 PROVIDE (__load_start_text0 = LOADADDR (.text0));
6248 PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
6249 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
6250 PROVIDE (__load_start_text1 = LOADADDR (.text1));
6251 PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
6252 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
6257 @section MEMORY Command
6259 @cindex memory regions
6260 @cindex regions of memory
6261 @cindex allocating memory
6262 @cindex discontinuous memory
6263 The linker's default configuration permits allocation of all available
6264 memory. You can override this by using the @code{MEMORY} command.
6266 The @code{MEMORY} command describes the location and size of blocks of
6267 memory in the target. You can use it to describe which memory regions
6268 may be used by the linker, and which memory regions it must avoid. You
6269 can then assign sections to particular memory regions. The linker will
6270 set section addresses based on the memory regions, and will warn about
6271 regions that become too full. The linker will not shuffle sections
6272 around to fit into the available regions.
6274 A linker script may contain many uses of the @code{MEMORY} command,
6275 however, all memory blocks defined are treated as if they were
6276 specified inside a single @code{MEMORY} command. The syntax for
6282 @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
6288 The @var{name} is a name used in the linker script to refer to the
6289 region. The region name has no meaning outside of the linker script.
6290 Region names are stored in a separate name space, and will not conflict
6291 with symbol names, file names, or section names. Each memory region
6292 must have a distinct name within the @code{MEMORY} command. However you can
6293 add later alias names to existing memory regions with the @ref{REGION_ALIAS}
6296 @cindex memory region attributes
6297 The @var{attr} string is an optional list of attributes that specify
6298 whether to use a particular memory region for an input section which is
6299 not explicitly mapped in the linker script. As described in
6300 @ref{SECTIONS}, if you do not specify an output section for some input
6301 section, the linker will create an output section with the same name as
6302 the input section. If you define region attributes, the linker will use
6303 them to select the memory region for the output section that it creates.
6305 The @var{attr} string must consist only of the following characters:
6320 Invert the sense of any of the attributes that follow
6323 If an unmapped section matches any of the listed attributes other than
6324 @samp{!}, it will be placed in the memory region. The @samp{!}
6325 attribute reverses the test for the characters that follow, so that an
6326 unmapped section will be placed in the memory region only if it does
6327 not match any of the attributes listed afterwards. Thus an attribute
6328 string of @samp{RW!X} will match any unmapped section that has either
6329 or both of the @samp{R} and @samp{W} attributes, but only as long as
6330 the section does not also have the @samp{X} attribute.
6335 The @var{origin} is an numerical expression for the start address of
6336 the memory region. The expression must evaluate to a constant and it
6337 cannot involve any symbols. The keyword @code{ORIGIN} may be
6338 abbreviated to @code{org} or @code{o} (but not, for example,
6344 The @var{len} is an expression for the size in bytes of the memory
6345 region. As with the @var{origin} expression, the expression must
6346 be numerical only and must evaluate to a constant. The keyword
6347 @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
6349 In the following example, we specify that there are two memory regions
6350 available for allocation: one starting at @samp{0} for 256 kilobytes,
6351 and the other starting at @samp{0x40000000} for four megabytes. The
6352 linker will place into the @samp{rom} memory region every section which
6353 is not explicitly mapped into a memory region, and is either read-only
6354 or executable. The linker will place other sections which are not
6355 explicitly mapped into a memory region into the @samp{ram} memory
6362 rom (rx) : ORIGIN = 0, LENGTH = 256K
6363 ram (!rx) : org = 0x40000000, l = 4M
6368 Once you define a memory region, you can direct the linker to place
6369 specific output sections into that memory region by using the
6370 @samp{>@var{region}} output section attribute. For example, if you have
6371 a memory region named @samp{mem}, you would use @samp{>mem} in the
6372 output section definition. @xref{Output Section Region}. If no address
6373 was specified for the output section, the linker will set the address to
6374 the next available address within the memory region. If the combined
6375 output sections directed to a memory region are too large for the
6376 region, the linker will issue an error message.
6378 It is possible to access the origin and length of a memory in an
6379 expression via the @code{ORIGIN(@var{memory})} and
6380 @code{LENGTH(@var{memory})} functions:
6384 _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
6389 @section PHDRS Command
6391 @cindex program headers
6392 @cindex ELF program headers
6393 @cindex program segments
6394 @cindex segments, ELF
6395 The ELF object file format uses @dfn{program headers}, also knows as
6396 @dfn{segments}. The program headers describe how the program should be
6397 loaded into memory. You can print them out by using the @code{objdump}
6398 program with the @samp{-p} option.
6400 When you run an ELF program on a native ELF system, the system loader
6401 reads the program headers in order to figure out how to load the
6402 program. This will only work if the program headers are set correctly.
6403 This manual does not describe the details of how the system loader
6404 interprets program headers; for more information, see the ELF ABI.
6406 The linker will create reasonable program headers by default. However,
6407 in some cases, you may need to specify the program headers more
6408 precisely. You may use the @code{PHDRS} command for this purpose. When
6409 the linker sees the @code{PHDRS} command in the linker script, it will
6410 not create any program headers other than the ones specified.
6412 The linker only pays attention to the @code{PHDRS} command when
6413 generating an ELF output file. In other cases, the linker will simply
6414 ignore @code{PHDRS}.
6416 This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
6417 @code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
6423 @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
6424 [ FLAGS ( @var{flags} ) ] ;
6429 The @var{name} is used only for reference in the @code{SECTIONS} command
6430 of the linker script. It is not put into the output file. Program
6431 header names are stored in a separate name space, and will not conflict
6432 with symbol names, file names, or section names. Each program header
6433 must have a distinct name. The headers are processed in order and it
6434 is usual for them to map to sections in ascending load address order.
6436 Certain program header types describe segments of memory which the
6437 system loader will load from the file. In the linker script, you
6438 specify the contents of these segments by placing allocatable output
6439 sections in the segments. You use the @samp{:@var{phdr}} output section
6440 attribute to place a section in a particular segment. @xref{Output
6443 It is normal to put certain sections in more than one segment. This
6444 merely implies that one segment of memory contains another. You may
6445 repeat @samp{:@var{phdr}}, using it once for each segment which should
6446 contain the section.
6448 If you place a section in one or more segments using @samp{:@var{phdr}},
6449 then the linker will place all subsequent allocatable sections which do
6450 not specify @samp{:@var{phdr}} in the same segments. This is for
6451 convenience, since generally a whole set of contiguous sections will be
6452 placed in a single segment. You can use @code{:NONE} to override the
6453 default segment and tell the linker to not put the section in any
6458 You may use the @code{FILEHDR} and @code{PHDRS} keywords after
6459 the program header type to further describe the contents of the segment.
6460 The @code{FILEHDR} keyword means that the segment should include the ELF
6461 file header. The @code{PHDRS} keyword means that the segment should
6462 include the ELF program headers themselves. If applied to a loadable
6463 segment (@code{PT_LOAD}), all prior loadable segments must have one of
6466 The @var{type} may be one of the following. The numbers indicate the
6467 value of the keyword.
6470 @item @code{PT_NULL} (0)
6471 Indicates an unused program header.
6473 @item @code{PT_LOAD} (1)
6474 Indicates that this program header describes a segment to be loaded from
6477 @item @code{PT_DYNAMIC} (2)
6478 Indicates a segment where dynamic linking information can be found.
6480 @item @code{PT_INTERP} (3)
6481 Indicates a segment where the name of the program interpreter may be
6484 @item @code{PT_NOTE} (4)
6485 Indicates a segment holding note information.
6487 @item @code{PT_SHLIB} (5)
6488 A reserved program header type, defined but not specified by the ELF
6491 @item @code{PT_PHDR} (6)
6492 Indicates a segment where the program headers may be found.
6494 @item @code{PT_TLS} (7)
6495 Indicates a segment containing thread local storage.
6497 @item @var{expression}
6498 An expression giving the numeric type of the program header. This may
6499 be used for types not defined above.
6502 You can specify that a segment should be loaded at a particular address
6503 in memory by using an @code{AT} expression. This is identical to the
6504 @code{AT} command used as an output section attribute (@pxref{Output
6505 Section LMA}). The @code{AT} command for a program header overrides the
6506 output section attribute.
6508 The linker will normally set the segment flags based on the sections
6509 which comprise the segment. You may use the @code{FLAGS} keyword to
6510 explicitly specify the segment flags. The value of @var{flags} must be
6511 an integer. It is used to set the @code{p_flags} field of the program
6514 Here is an example of @code{PHDRS}. This shows a typical set of program
6515 headers used on a native ELF system.
6521 headers PT_PHDR PHDRS ;
6523 text PT_LOAD FILEHDR PHDRS ;
6525 dynamic PT_DYNAMIC ;
6531 .interp : @{ *(.interp) @} :text :interp
6532 .text : @{ *(.text) @} :text
6533 .rodata : @{ *(.rodata) @} /* defaults to :text */
6535 . = . + 0x1000; /* move to a new page in memory */
6536 .data : @{ *(.data) @} :data
6537 .dynamic : @{ *(.dynamic) @} :data :dynamic
6544 @section VERSION Command
6545 @kindex VERSION @{script text@}
6546 @cindex symbol versions
6547 @cindex version script
6548 @cindex versions of symbols
6549 The linker supports symbol versions when using ELF. Symbol versions are
6550 only useful when using shared libraries. The dynamic linker can use
6551 symbol versions to select a specific version of a function when it runs
6552 a program that may have been linked against an earlier version of the
6555 You can include a version script directly in the main linker script, or
6556 you can supply the version script as an implicit linker script. You can
6557 also use the @samp{--version-script} linker option.
6559 The syntax of the @code{VERSION} command is simply
6561 VERSION @{ version-script-commands @}
6564 The format of the version script commands is identical to that used by
6565 Sun's linker in Solaris 2.5. The version script defines a tree of
6566 version nodes. You specify the node names and interdependencies in the
6567 version script. You can specify which symbols are bound to which
6568 version nodes, and you can reduce a specified set of symbols to local
6569 scope so that they are not globally visible outside of the shared
6572 The easiest way to demonstrate the version script language is with a few
6598 This example version script defines three version nodes. The first
6599 version node defined is @samp{VERS_1.1}; it has no other dependencies.
6600 The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces
6601 a number of symbols to local scope so that they are not visible outside
6602 of the shared library; this is done using wildcard patterns, so that any
6603 symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
6604 is matched. The wildcard patterns available are the same as those used
6605 in the shell when matching filenames (also known as ``globbing'').
6606 However, if you specify the symbol name inside double quotes, then the
6607 name is treated as literal, rather than as a glob pattern.
6609 Next, the version script defines node @samp{VERS_1.2}. This node
6610 depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2}
6611 to the version node @samp{VERS_1.2}.
6613 Finally, the version script defines node @samp{VERS_2.0}. This node
6614 depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1}
6615 and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
6617 When the linker finds a symbol defined in a library which is not
6618 specifically bound to a version node, it will effectively bind it to an
6619 unspecified base version of the library. You can bind all otherwise
6620 unspecified symbols to a given version node by using @samp{global: *;}
6621 somewhere in the version script. Note that it's slightly crazy to use
6622 wildcards in a global spec except on the last version node. Global
6623 wildcards elsewhere run the risk of accidentally adding symbols to the
6624 set exported for an old version. That's wrong since older versions
6625 ought to have a fixed set of symbols.
6627 The names of the version nodes have no specific meaning other than what
6628 they might suggest to the person reading them. The @samp{2.0} version
6629 could just as well have appeared in between @samp{1.1} and @samp{1.2}.
6630 However, this would be a confusing way to write a version script.
6632 Node name can be omitted, provided it is the only version node
6633 in the version script. Such version script doesn't assign any versions to
6634 symbols, only selects which symbols will be globally visible out and which
6638 @{ global: foo; bar; local: *; @};
6641 When you link an application against a shared library that has versioned
6642 symbols, the application itself knows which version of each symbol it
6643 requires, and it also knows which version nodes it needs from each
6644 shared library it is linked against. Thus at runtime, the dynamic
6645 loader can make a quick check to make sure that the libraries you have
6646 linked against do in fact supply all of the version nodes that the
6647 application will need to resolve all of the dynamic symbols. In this
6648 way it is possible for the dynamic linker to know with certainty that
6649 all external symbols that it needs will be resolvable without having to
6650 search for each symbol reference.
6652 The symbol versioning is in effect a much more sophisticated way of
6653 doing minor version checking that SunOS does. The fundamental problem
6654 that is being addressed here is that typically references to external
6655 functions are bound on an as-needed basis, and are not all bound when
6656 the application starts up. If a shared library is out of date, a
6657 required interface may be missing; when the application tries to use
6658 that interface, it may suddenly and unexpectedly fail. With symbol
6659 versioning, the user will get a warning when they start their program if
6660 the libraries being used with the application are too old.
6662 There are several GNU extensions to Sun's versioning approach. The
6663 first of these is the ability to bind a symbol to a version node in the
6664 source file where the symbol is defined instead of in the versioning
6665 script. This was done mainly to reduce the burden on the library
6666 maintainer. You can do this by putting something like:
6668 __asm__(".symver original_foo,foo@@VERS_1.1");
6671 in the C source file. This renames the function @samp{original_foo} to
6672 be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
6673 The @samp{local:} directive can be used to prevent the symbol
6674 @samp{original_foo} from being exported. A @samp{.symver} directive
6675 takes precedence over a version script.
6677 The second GNU extension is to allow multiple versions of the same
6678 function to appear in a given shared library. In this way you can make
6679 an incompatible change to an interface without increasing the major
6680 version number of the shared library, while still allowing applications
6681 linked against the old interface to continue to function.
6683 To do this, you must use multiple @samp{.symver} directives in the
6684 source file. Here is an example:
6687 __asm__(".symver original_foo,foo@@");
6688 __asm__(".symver old_foo,foo@@VERS_1.1");
6689 __asm__(".symver old_foo1,foo@@VERS_1.2");
6690 __asm__(".symver new_foo,foo@@@@VERS_2.0");
6693 In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
6694 unspecified base version of the symbol. The source file that contains this
6695 example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
6696 @samp{old_foo1}, and @samp{new_foo}.
6698 When you have multiple definitions of a given symbol, there needs to be
6699 some way to specify a default version to which external references to
6700 this symbol will be bound. You can do this with the
6701 @samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only
6702 declare one version of a symbol as the default in this manner; otherwise
6703 you would effectively have multiple definitions of the same symbol.
6705 If you wish to bind a reference to a specific version of the symbol
6706 within the shared library, you can use the aliases of convenience
6707 (i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to
6708 specifically bind to an external version of the function in question.
6710 You can also specify the language in the version script:
6713 VERSION extern "lang" @{ version-script-commands @}
6716 The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
6717 The linker will iterate over the list of symbols at the link time and
6718 demangle them according to @samp{lang} before matching them to the
6719 patterns specified in @samp{version-script-commands}. The default
6720 @samp{lang} is @samp{C}.
6722 Demangled names may contains spaces and other special characters. As
6723 described above, you can use a glob pattern to match demangled names,
6724 or you can use a double-quoted string to match the string exactly. In
6725 the latter case, be aware that minor differences (such as differing
6726 whitespace) between the version script and the demangler output will
6727 cause a mismatch. As the exact string generated by the demangler
6728 might change in the future, even if the mangled name does not, you
6729 should check that all of your version directives are behaving as you
6730 expect when you upgrade.
6733 @section Expressions in Linker Scripts
6736 The syntax for expressions in the linker script language is identical to
6737 that of C expressions, except that whitespace is required in some
6738 places to resolve syntactic ambiguities. All expressions are
6739 evaluated as integers. All expressions are evaluated in the same
6740 size, which is 32 bits if both the host and target are 32 bits, and is
6743 You can use and set symbol values in expressions.
6745 The linker defines several special purpose builtin functions for use in
6749 * Constants:: Constants
6750 * Symbolic Constants:: Symbolic constants
6751 * Symbols:: Symbol Names
6752 * Orphan Sections:: Orphan Sections
6753 * Location Counter:: The Location Counter
6754 * Operators:: Operators
6755 * Evaluation:: Evaluation
6756 * Expression Section:: The Section of an Expression
6757 * Builtin Functions:: Builtin Functions
6761 @subsection Constants
6762 @cindex integer notation
6763 @cindex constants in linker scripts
6764 All constants are integers.
6766 As in C, the linker considers an integer beginning with @samp{0} to be
6767 octal, and an integer beginning with @samp{0x} or @samp{0X} to be
6768 hexadecimal. Alternatively the linker accepts suffixes of @samp{h} or
6769 @samp{H} for hexadecimal, @samp{o} or @samp{O} for octal, @samp{b} or
6770 @samp{B} for binary and @samp{d} or @samp{D} for decimal. Any integer
6771 value without a prefix or a suffix is considered to be decimal.
6773 @cindex scaled integers
6774 @cindex K and M integer suffixes
6775 @cindex M and K integer suffixes
6776 @cindex suffixes for integers
6777 @cindex integer suffixes
6778 In addition, you can use the suffixes @code{K} and @code{M} to scale a
6782 @c END TEXI2ROFF-KILL
6783 @code{1024} or @code{1024*1024}
6787 ${\rm 1024}$ or ${\rm 1024}^2$
6789 @c END TEXI2ROFF-KILL
6790 respectively. For example, the following
6791 all refer to the same quantity:
6800 Note - the @code{K} and @code{M} suffixes cannot be used in
6801 conjunction with the base suffixes mentioned above.
6803 @node Symbolic Constants
6804 @subsection Symbolic Constants
6805 @cindex symbolic constants
6807 It is possible to refer to target-specific constants via the use of
6808 the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
6813 The target's maximum page size.
6815 @item COMMONPAGESIZE
6816 @kindex COMMONPAGESIZE
6817 The target's default page size.
6823 .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
6826 will create a text section aligned to the largest page boundary
6827 supported by the target.
6830 @subsection Symbol Names
6831 @cindex symbol names
6833 @cindex quoted symbol names
6835 Unless quoted, symbol names start with a letter, underscore, or period
6836 and may include letters, digits, underscores, periods, and hyphens.
6837 Unquoted symbol names must not conflict with any keywords. You can
6838 specify a symbol which contains odd characters or has the same name as a
6839 keyword by surrounding the symbol name in double quotes:
6842 "with a space" = "also with a space" + 10;
6845 Since symbols can contain many non-alphabetic characters, it is safest
6846 to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
6847 whereas @samp{A - B} is an expression involving subtraction.
6849 @node Orphan Sections
6850 @subsection Orphan Sections
6852 Orphan sections are sections present in the input files which
6853 are not explicitly placed into the output file by the linker
6854 script. The linker will still copy these sections into the
6855 output file by either finding, or creating a suitable output section
6856 in which to place the orphaned input section.
6858 If the name of an orphaned input section exactly matches the name of
6859 an existing output section, then the orphaned input section will be
6860 placed at the end of that output section.
6862 If there is no output section with a matching name then new output
6863 sections will be created. Each new output section will have the same
6864 name as the orphan section placed within it. If there are multiple
6865 orphan sections with the same name, these will all be combined into
6866 one new output section.
6868 If new output sections are created to hold orphaned input sections,
6869 then the linker must decide where to place these new output sections
6870 in relation to existing output sections. On most modern targets, the
6871 linker attempts to place orphan sections after sections of the same
6872 attribute, such as code vs data, loadable vs non-loadable, etc. If no
6873 sections with matching attributes are found, or your target lacks this
6874 support, the orphan section is placed at the end of the file.
6876 The command-line options @samp{--orphan-handling} and @samp{--unique}
6877 (@pxref{Options,,Command-line Options}) can be used to control which
6878 output sections an orphan is placed in.
6880 @node Location Counter
6881 @subsection The Location Counter
6884 @cindex location counter
6885 @cindex current output location
6886 The special linker variable @dfn{dot} @samp{.} always contains the
6887 current output location counter. Since the @code{.} always refers to a
6888 location in an output section, it may only appear in an expression
6889 within a @code{SECTIONS} command. The @code{.} symbol may appear
6890 anywhere that an ordinary symbol is allowed in an expression.
6893 Assigning a value to @code{.} will cause the location counter to be
6894 moved. This may be used to create holes in the output section. The
6895 location counter may not be moved backwards inside an output section,
6896 and may not be moved backwards outside of an output section if so
6897 doing creates areas with overlapping LMAs.
6913 In the previous example, the @samp{.text} section from @file{file1} is
6914 located at the beginning of the output section @samp{output}. It is
6915 followed by a 1000 byte gap. Then the @samp{.text} section from
6916 @file{file2} appears, also with a 1000 byte gap following before the
6917 @samp{.text} section from @file{file3}. The notation @samp{= 0x12345678}
6918 specifies what data to write in the gaps (@pxref{Output Section Fill}).
6920 @cindex dot inside sections
6921 Note: @code{.} actually refers to the byte offset from the start of the
6922 current containing object. Normally this is the @code{SECTIONS}
6923 statement, whose start address is 0, hence @code{.} can be used as an
6924 absolute address. If @code{.} is used inside a section description
6925 however, it refers to the byte offset from the start of that section,
6926 not an absolute address. Thus in a script like this:
6944 The @samp{.text} section will be assigned a starting address of 0x100
6945 and a size of exactly 0x200 bytes, even if there is not enough data in
6946 the @samp{.text} input sections to fill this area. (If there is too
6947 much data, an error will be produced because this would be an attempt to
6948 move @code{.} backwards). The @samp{.data} section will start at 0x500
6949 and it will have an extra 0x600 bytes worth of space after the end of
6950 the values from the @samp{.data} input sections and before the end of
6951 the @samp{.data} output section itself.
6953 @cindex dot outside sections
6954 Setting symbols to the value of the location counter outside of an
6955 output section statement can result in unexpected values if the linker
6956 needs to place orphan sections. For example, given the following:
6962 .text: @{ *(.text) @}
6966 .data: @{ *(.data) @}
6971 If the linker needs to place some input section, e.g. @code{.rodata},
6972 not mentioned in the script, it might choose to place that section
6973 between @code{.text} and @code{.data}. You might think the linker
6974 should place @code{.rodata} on the blank line in the above script, but
6975 blank lines are of no particular significance to the linker. As well,
6976 the linker doesn't associate the above symbol names with their
6977 sections. Instead, it assumes that all assignments or other
6978 statements belong to the previous output section, except for the
6979 special case of an assignment to @code{.}. I.e., the linker will
6980 place the orphan @code{.rodata} section as if the script was written
6987 .text: @{ *(.text) @}
6991 .rodata: @{ *(.rodata) @}
6992 .data: @{ *(.data) @}
6997 This may or may not be the script author's intention for the value of
6998 @code{start_of_data}. One way to influence the orphan section
6999 placement is to assign the location counter to itself, as the linker
7000 assumes that an assignment to @code{.} is setting the start address of
7001 a following output section and thus should be grouped with that
7002 section. So you could write:
7008 .text: @{ *(.text) @}
7013 .data: @{ *(.data) @}
7018 Now, the orphan @code{.rodata} section will be placed between
7019 @code{end_of_text} and @code{start_of_data}.
7023 @subsection Operators
7024 @cindex operators for arithmetic
7025 @cindex arithmetic operators
7026 @cindex precedence in expressions
7027 The linker recognizes the standard C set of arithmetic operators, with
7028 the standard bindings and precedence levels:
7031 @c END TEXI2ROFF-KILL
7033 precedence associativity Operators Notes
7047 13 right += -= *= /= <<= >>= &= |= ^= (2)
7051 (1) Prefix operators
7052 (2) @xref{Assignments}.
7056 \vskip \baselineskip
7057 %"lispnarrowing" is the extra indent used generally for smallexample
7058 \hskip\lispnarrowing\vbox{\offinterlineskip
7061 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
7062 height2pt&\omit&&\omit&&\omit&\cr
7063 &Precedence&& Associativity &&{\rm Operators}&\cr
7064 height2pt&\omit&&\omit&&\omit&\cr
7066 height2pt&\omit&&\omit&&\omit&\cr
7068 % '176 is tilde, '~' in tt font
7069 &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
7070 &2&&left&&* / \%&\cr
7073 &5&&left&& > < <= >=&\cr
7078 &10&&left&&{\&\&}&\cr
7081 &13&&right&&\qquad += -= *= /= <<= >>= \&= |= \^{}=\qquad\ddag&\cr
7083 height2pt&\omit&&\omit&&\omit&\cr}
7088 @obeylines@parskip=0pt@parindent=0pt
7089 @dag@quad Prefix operators.
7090 @ddag@quad @xref{Assignments}.
7093 @c END TEXI2ROFF-KILL
7096 @subsection Evaluation
7097 @cindex lazy evaluation
7098 @cindex expression evaluation order
7099 The linker evaluates expressions lazily. It only computes the value of
7100 an expression when absolutely necessary.
7102 The linker needs some information, such as the value of the start
7103 address of the first section, and the origins and lengths of memory
7104 regions, in order to do any linking at all. These values are computed
7105 as soon as possible when the linker reads in the linker script.
7107 However, other values (such as symbol values) are not known or needed
7108 until after storage allocation. Such values are evaluated later, when
7109 other information (such as the sizes of output sections) is available
7110 for use in the symbol assignment expression.
7112 The sizes of sections cannot be known until after allocation, so
7113 assignments dependent upon these are not performed until after
7116 Some expressions, such as those depending upon the location counter
7117 @samp{.}, must be evaluated during section allocation.
7119 If the result of an expression is required, but the value is not
7120 available, then an error results. For example, a script like the
7126 .text 9+this_isnt_constant :
7132 will cause the error message @samp{non constant expression for initial
7135 @node Expression Section
7136 @subsection The Section of an Expression
7137 @cindex expression sections
7138 @cindex absolute expressions
7139 @cindex relative expressions
7140 @cindex absolute and relocatable symbols
7141 @cindex relocatable and absolute symbols
7142 @cindex symbols, relocatable and absolute
7143 Addresses and symbols may be section relative, or absolute. A section
7144 relative symbol is relocatable. If you request relocatable output
7145 using the @samp{-r} option, a further link operation may change the
7146 value of a section relative symbol. On the other hand, an absolute
7147 symbol will retain the same value throughout any further link
7150 Some terms in linker expressions are addresses. This is true of
7151 section relative symbols and for builtin functions that return an
7152 address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and
7153 @code{SEGMENT_START}. Other terms are simply numbers, or are builtin
7154 functions that return a non-address value, such as @code{LENGTH}.
7155 One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
7156 (@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
7157 differently depending on their location, for compatibility with older
7158 versions of @code{ld}. Expressions appearing outside an output
7159 section definition treat all numbers as absolute addresses.
7160 Expressions appearing inside an output section definition treat
7161 absolute symbols as numbers. If @code{LD_FEATURE ("SANE_EXPR")} is
7162 given, then absolute symbols and numbers are simply treated as numbers
7165 In the following simple example,
7172 __executable_start = 0x100;
7176 __data_start = 0x10;
7184 both @code{.} and @code{__executable_start} are set to the absolute
7185 address 0x100 in the first two assignments, then both @code{.} and
7186 @code{__data_start} are set to 0x10 relative to the @code{.data}
7187 section in the second two assignments.
7189 For expressions involving numbers, relative addresses and absolute
7190 addresses, ld follows these rules to evaluate terms:
7194 Unary operations on an absolute address or number, and binary
7195 operations on two absolute addresses or two numbers, or between one
7196 absolute address and a number, apply the operator to the value(s).
7198 Unary operations on a relative address, and binary operations on two
7199 relative addresses in the same section or between one relative address
7200 and a number, apply the operator to the offset part of the address(es).
7202 Other binary operations, that is, between two relative addresses not
7203 in the same section, or between a relative address and an absolute
7204 address, first convert any non-absolute term to an absolute address
7205 before applying the operator.
7208 The result section of each sub-expression is as follows:
7212 An operation involving only numbers results in a number.
7214 The result of comparisons, @samp{&&} and @samp{||} is also a number.
7216 The result of other binary arithmetic and logical operations on two
7217 relative addresses in the same section or two absolute addresses
7218 (after above conversions) is also a number when
7219 @code{LD_FEATURE ("SANE_EXPR")} or inside an output section definition
7220 but an absolute address otherwise.
7222 The result of other operations on relative addresses or one
7223 relative address and a number, is a relative address in the same
7224 section as the relative operand(s).
7226 The result of other operations on absolute addresses (after above
7227 conversions) is an absolute address.
7230 You can use the builtin function @code{ABSOLUTE} to force an expression
7231 to be absolute when it would otherwise be relative. For example, to
7232 create an absolute symbol set to the address of the end of the output
7233 section @samp{.data}:
7237 .data : @{ *(.data) _edata = ABSOLUTE(.); @}
7241 If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
7242 @samp{.data} section.
7244 Using @code{LOADADDR} also forces an expression absolute, since this
7245 particular builtin function returns an absolute address.
7247 @node Builtin Functions
7248 @subsection Builtin Functions
7249 @cindex functions in expressions
7250 The linker script language includes a number of builtin functions for
7251 use in linker script expressions.
7254 @item ABSOLUTE(@var{exp})
7255 @kindex ABSOLUTE(@var{exp})
7256 @cindex expression, absolute
7257 Return the absolute (non-relocatable, as opposed to non-negative) value
7258 of the expression @var{exp}. Primarily useful to assign an absolute
7259 value to a symbol within a section definition, where symbol values are
7260 normally section relative. @xref{Expression Section}.
7262 @item ADDR(@var{section})
7263 @kindex ADDR(@var{section})
7264 @cindex section address in expression
7265 Return the address (VMA) of the named @var{section}. Your
7266 script must previously have defined the location of that section. In
7267 the following example, @code{start_of_output_1}, @code{symbol_1} and
7268 @code{symbol_2} are assigned equivalent values, except that
7269 @code{symbol_1} will be relative to the @code{.output1} section while
7270 the other two will be absolute:
7276 start_of_output_1 = ABSOLUTE(.);
7281 symbol_1 = ADDR(.output1);
7282 symbol_2 = start_of_output_1;
7288 @item ALIGN(@var{align})
7289 @itemx ALIGN(@var{exp},@var{align})
7290 @kindex ALIGN(@var{align})
7291 @kindex ALIGN(@var{exp},@var{align})
7292 @cindex round up location counter
7293 @cindex align location counter
7294 @cindex round up expression
7295 @cindex align expression
7296 Return the location counter (@code{.}) or arbitrary expression aligned
7297 to the next @var{align} boundary. The single operand @code{ALIGN}
7298 doesn't change the value of the location counter---it just does
7299 arithmetic on it. The two operand @code{ALIGN} allows an arbitrary
7300 expression to be aligned upwards (@code{ALIGN(@var{align})} is
7301 equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}).
7303 Here is an example which aligns the output @code{.data} section to the
7304 next @code{0x2000} byte boundary after the preceding section and sets a
7305 variable within the section to the next @code{0x8000} boundary after the
7310 .data ALIGN(0x2000): @{
7312 variable = ALIGN(0x8000);
7318 The first use of @code{ALIGN} in this example specifies the location of
7319 a section because it is used as the optional @var{address} attribute of
7320 a section definition (@pxref{Output Section Address}). The second use
7321 of @code{ALIGN} is used to defines the value of a symbol.
7323 The builtin function @code{NEXT} is closely related to @code{ALIGN}.
7325 @item ALIGNOF(@var{section})
7326 @kindex ALIGNOF(@var{section})
7327 @cindex section alignment
7328 Return the alignment in bytes of the named @var{section}, if that section has
7329 been allocated, or zero if the section has not been allocated. If the
7330 section does not exist in the linker script the linker will report an
7331 error. If @var{section} is @code{NEXT_SECTION} then @code{ALIGNOF} will
7332 return the alignment of the next allocated section specified in the
7333 linker script, or zero if there is no such section. In the following
7334 example, the alignment of the @code{.output} section is stored as the
7335 first value in that section.
7340 LONG (ALIGNOF (.output))
7347 @item BLOCK(@var{exp})
7348 @kindex BLOCK(@var{exp})
7349 This is a synonym for @code{ALIGN}, for compatibility with older linker
7350 scripts. It is most often seen when setting the address of an output
7353 @item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
7354 @kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
7355 This is equivalent to either
7357 (ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
7361 (ALIGN(@var{maxpagesize})
7362 + ((. + @var{commonpagesize} - 1) & (@var{maxpagesize} - @var{commonpagesize})))
7365 depending on whether the latter uses fewer @var{commonpagesize} sized pages
7366 for the data segment (area between the result of this expression and
7367 @code{DATA_SEGMENT_END}) than the former or not.
7368 If the latter form is used, it means @var{commonpagesize} bytes of runtime
7369 memory will be saved at the expense of up to @var{commonpagesize} wasted
7370 bytes in the on-disk file.
7372 This expression can only be used directly in @code{SECTIONS} commands, not in
7373 any output section descriptions and only once in the linker script.
7374 @var{commonpagesize} should be less or equal to @var{maxpagesize} and should
7375 be the system page size the object wants to be optimized for while still
7376 running on system page sizes up to @var{maxpagesize}. Note however
7377 that @samp{-z relro} protection will not be effective if the system
7378 page size is larger than @var{commonpagesize}.
7383 . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
7386 @item DATA_SEGMENT_END(@var{exp})
7387 @kindex DATA_SEGMENT_END(@var{exp})
7388 This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
7389 evaluation purposes.
7392 . = DATA_SEGMENT_END(.);
7395 @item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
7396 @kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
7397 This defines the end of the @code{PT_GNU_RELRO} segment when
7398 @samp{-z relro} option is used.
7399 When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
7400 does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
7401 @var{exp} + @var{offset} is aligned to the @var{commonpagesize}
7402 argument given to @code{DATA_SEGMENT_ALIGN}. If present in the linker
7403 script, it must be placed between @code{DATA_SEGMENT_ALIGN} and
7404 @code{DATA_SEGMENT_END}. Evaluates to the second argument plus any
7405 padding needed at the end of the @code{PT_GNU_RELRO} segment due to
7409 . = DATA_SEGMENT_RELRO_END(24, .);
7412 @item DEFINED(@var{symbol})
7413 @kindex DEFINED(@var{symbol})
7414 @cindex symbol defaults
7415 Return 1 if @var{symbol} is in the linker global symbol table and is
7416 defined before the statement using DEFINED in the script, otherwise
7417 return 0. You can use this function to provide
7418 default values for symbols. For example, the following script fragment
7419 shows how to set a global symbol @samp{begin} to the first location in
7420 the @samp{.text} section---but if a symbol called @samp{begin} already
7421 existed, its value is preserved:
7427 begin = DEFINED(begin) ? begin : . ;
7435 @item LENGTH(@var{memory})
7436 @kindex LENGTH(@var{memory})
7437 Return the length of the memory region named @var{memory}.
7439 @item LOADADDR(@var{section})
7440 @kindex LOADADDR(@var{section})
7441 @cindex section load address in expression
7442 Return the absolute LMA of the named @var{section}. (@pxref{Output
7445 @item LOG2CEIL(@var{exp})
7446 @kindex LOG2CEIL(@var{exp})
7447 Return the binary logarithm of @var{exp} rounded towards infinity.
7448 @code{LOG2CEIL(0)} returns 0.
7451 @item MAX(@var{exp1}, @var{exp2})
7452 Returns the maximum of @var{exp1} and @var{exp2}.
7455 @item MIN(@var{exp1}, @var{exp2})
7456 Returns the minimum of @var{exp1} and @var{exp2}.
7458 @item NEXT(@var{exp})
7459 @kindex NEXT(@var{exp})
7460 @cindex unallocated address, next
7461 Return the next unallocated address that is a multiple of @var{exp}.
7462 This function is closely related to @code{ALIGN(@var{exp})}; unless you
7463 use the @code{MEMORY} command to define discontinuous memory for the
7464 output file, the two functions are equivalent.
7466 @item ORIGIN(@var{memory})
7467 @kindex ORIGIN(@var{memory})
7468 Return the origin of the memory region named @var{memory}.
7470 @item SEGMENT_START(@var{segment}, @var{default})
7471 @kindex SEGMENT_START(@var{segment}, @var{default})
7472 Return the base address of the named @var{segment}. If an explicit
7473 value has already been given for this segment (with a command-line
7474 @samp{-T} option) then that value will be returned otherwise the value
7475 will be @var{default}. At present, the @samp{-T} command-line option
7476 can only be used to set the base address for the ``text'', ``data'', and
7477 ``bss'' sections, but you can use @code{SEGMENT_START} with any segment
7480 @item SIZEOF(@var{section})
7481 @kindex SIZEOF(@var{section})
7482 @cindex section size
7483 Return the size in bytes of the named @var{section}, if that section has
7484 been allocated, or zero if the section has not been allocated. If the
7485 section does not exist in the linker script the linker will report an
7486 error. If @var{section} is @code{NEXT_SECTION} then @code{SIZEOF} will
7487 return the alignment of the next allocated section specified in the
7488 linker script, or zero if there is no such section. In the following
7489 example, @code{symbol_1} and @code{symbol_2} are assigned identical
7499 symbol_1 = .end - .start ;
7500 symbol_2 = SIZEOF(.output);
7505 @item SIZEOF_HEADERS
7506 @kindex SIZEOF_HEADERS
7508 Return the size in bytes of the output file's headers. This is
7509 information which appears at the start of the output file. You can use
7510 this number when setting the start address of the first section, if you
7511 choose, to facilitate paging.
7513 @cindex not enough room for program headers
7514 @cindex program headers, not enough room
7515 When producing an ELF output file, if the linker script uses the
7516 @code{SIZEOF_HEADERS} builtin function, the linker must compute the
7517 number of program headers before it has determined all the section
7518 addresses and sizes. If the linker later discovers that it needs
7519 additional program headers, it will report an error @samp{not enough
7520 room for program headers}. To avoid this error, you must avoid using
7521 the @code{SIZEOF_HEADERS} function, or you must rework your linker
7522 script to avoid forcing the linker to use additional program headers, or
7523 you must define the program headers yourself using the @code{PHDRS}
7524 command (@pxref{PHDRS}).
7527 @node Implicit Linker Scripts
7528 @section Implicit Linker Scripts
7529 @cindex implicit linker scripts
7530 If you specify a linker input file which the linker can not recognize as
7531 an object file or an archive file, it will try to read the file as a
7532 linker script. If the file can not be parsed as a linker script, the
7533 linker will report an error.
7535 An implicit linker script will not replace the default linker script.
7537 Typically an implicit linker script would contain only symbol
7538 assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
7541 Any input files read because of an implicit linker script will be read
7542 at the position in the command line where the implicit linker script was
7543 read. This can affect archive searching.
7546 @chapter Linker Plugins
7549 @cindex linker plugins
7550 The linker can use dynamically loaded plugins to modify its behavior.
7551 For example, the link-time optimization feature that some compilers
7552 support is implemented with a linker plugin.
7554 Currently there is only one plugin shipped by default, but more may
7555 be added here later.
7557 Plugins are enabled via the use of the @option{-plugin @var{name}}
7558 command line option. @xref{Options}.
7561 * libdep Plugin:: Static Library Dependencies Plugin
7565 @section Static Library Dependencies Plugin
7566 @cindex static library dependencies
7567 Originally, static libraries were contained in an archive file consisting
7568 just of a collection of relocatable object files. Later they evolved to
7569 optionally include a symbol table, to assist in finding the needed objects
7570 within a library. There their evolution ended, and dynamic libraries
7573 One useful feature of dynamic libraries was that, more than just collecting
7574 multiple objects into a single file, they also included a list of their
7575 dependencies, such that one could specify just the name of a single dynamic
7576 library at link time, and all of its dependencies would be implicitly
7577 referenced as well. But static libraries lacked this feature, so if a
7578 link invocation was switched from using dynamic libraries to static
7579 libraries, the link command would usually fail unless it was rewritten to
7580 explicitly list the dependencies of the static library.
7582 The GNU @command{ar} utility now supports a @option{--record-libdeps} option
7583 to embed dependency lists into static libraries as well, and the @file{libdep}
7584 plugin may be used to read this dependency information at link time. The
7585 dependency information is stored as a single string, carrying @option{-l}
7586 and @option{-L} arguments as they would normally appear in a linker
7587 command line. As such, the information can be written with any text
7588 utility and stored into any archive, even if GNU @command{ar} is not
7589 being used to create the archive. The information is stored in an
7590 archive member named @samp{__.LIBDEP}.
7592 For example, given a library @file{libssl.a} that depends on another
7593 library @file{libcrypto.a} which may be found in @file{/usr/local/lib},
7594 the @samp{__.LIBDEP} member of @file{libssl.a} would contain
7597 -L/usr/local/lib -lcrypto
7600 @node Special Sections
7601 @chapter Special Sections
7602 When linking ELF format object files @command{ld} treats some sections
7603 in a special, non standard manner. This part of the manual describes
7608 The contents of any section with this name are assumed to be an ascii
7609 format warning message. The contents will be displayed to the user if
7610 the sections appears in any input file, but the section will not be
7611 copied into the output image. If the @option{--fatal-warnings} option
7612 is enabled then the warnings - if any are encountered - will also stop
7613 the link from completing.
7615 Note - the @samp{.gnu.warning} section is not subject to linker
7616 garbage collection or orphan handling.
7618 @item .gnu.warning.@var{SYM}
7619 The contents of any section whoes name starts with the prefix
7620 @samp{.gnu.warning.} and then finishes with the name of a symbol is
7621 treated in a similar fashion to the @samp{.gnu.warning} section, but
7622 only if the named symbol is referenced. So for example the contents
7623 of a section called @samp{.gnu.warning.foo} will be displayed as
7624 warning message if, and only if, the symbol @samp{foo} is referenced
7625 by one or more of the input files. This includes object files pulled
7626 in from static libraries, shared objects needed to complete the link
7629 Note - because these warning messages are generated before the linker
7630 performs garbage collection (if enabled) it is possible for a warning
7631 to be displayed for a symbol that is later removed and then never
7632 appears in the final output.
7634 @item .note.gnu.property
7635 When the linker combines sections of this name it will merge them
7636 together according to various rules encoded into the notes
7637 themselves. Therefore the contents of the output .note.gnu.property
7638 section may not correspond to a simple concatenation of the input
7639 sections. If the @option{-Map} option has been used to request a
7640 linker map then details of any property merging will be included in
7646 @node Machine Dependent
7647 @chapter Machine Dependent Features
7649 @cindex machine dependencies
7650 @command{ld} has additional features on some platforms; the following
7651 sections describe them. Machines where @command{ld} has no additional
7652 functionality are not listed.
7656 * H8/300:: @command{ld} and the H8/300
7659 * M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families
7662 * ARM:: @command{ld} and the ARM family
7665 * HPPA ELF32:: @command{ld} and HPPA 32-bit ELF
7668 * M68K:: @command{ld} and the Motorola 68K family
7671 * MIPS:: @command{ld} and the MIPS family
7674 * MMIX:: @command{ld} and MMIX
7677 * MSP430:: @command{ld} and MSP430
7680 * NDS32:: @command{ld} and NDS32
7683 * Nios II:: @command{ld} and the Altera Nios II
7686 * PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support
7689 * PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
7692 * S/390 ELF:: @command{ld} and S/390 ELF Support
7695 * SPU ELF:: @command{ld} and SPU ELF Support
7698 * TI COFF:: @command{ld} and TI COFF
7701 * WIN32:: @command{ld} and WIN32 (cygwin/mingw)
7704 * Xtensa:: @command{ld} and Xtensa Processors
7715 @section @command{ld} and the H8/300
7717 @cindex H8/300 support
7718 For the H8/300, @command{ld} can perform these global optimizations when
7719 you specify the @samp{--relax} command-line option.
7722 @cindex relaxing on H8/300
7723 @item relaxing address modes
7724 @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
7725 targets are within eight bits, and turns them into eight-bit
7726 program-counter relative @code{bsr} and @code{bra} instructions,
7729 @cindex synthesizing on H8/300
7730 @item synthesizing instructions
7731 @c FIXME: specifically mov.b, or any mov instructions really? -> mov.b only, at least on H8, H8H, H8S
7732 @command{ld} finds all @code{mov.b} instructions which use the
7733 sixteen-bit absolute address form, but refer to the top
7734 page of memory, and changes them to use the eight-bit address form.
7735 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
7736 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
7737 top page of memory).
7739 @command{ld} finds all @code{mov} instructions which use the register
7740 indirect with 32-bit displacement addressing mode, but use a small
7741 displacement inside 16-bit displacement range, and changes them to use
7742 the 16-bit displacement form. (That is: the linker turns @samp{mov.b
7743 @code{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx}
7744 whenever the displacement @var{d} is in the 16 bit signed integer
7745 range. Only implemented in ELF-format ld).
7747 @item bit manipulation instructions
7748 @command{ld} finds all bit manipulation instructions like @code{band, bclr,
7749 biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
7750 which use 32 bit and 16 bit absolute address form, but refer to the top
7751 page of memory, and changes them to use the 8 bit address form.
7752 (That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into
7753 @samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
7754 the top page of memory).
7756 @item system control instructions
7757 @command{ld} finds all @code{ldc.w, stc.w} instructions which use the
7758 32 bit absolute address form, but refer to the top page of memory, and
7759 changes them to use 16 bit address form.
7760 (That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
7761 @samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
7762 the top page of memory).
7772 @c This stuff is pointless to say unless you're especially concerned
7773 @c with Renesas chips; don't enable it for generic case, please.
7775 @chapter @command{ld} and Other Renesas Chips
7777 @command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
7778 H8/500, and SH chips. No special features, commands, or command-line
7779 options are required for these chips.
7793 @node M68HC11/68HC12
7794 @section @command{ld} and the Motorola 68HC11 and 68HC12 families
7796 @cindex M68HC11 and 68HC12 support
7798 @subsection Linker Relaxation
7800 For the Motorola 68HC11, @command{ld} can perform these global
7801 optimizations when you specify the @samp{--relax} command-line option.
7804 @cindex relaxing on M68HC11
7805 @item relaxing address modes
7806 @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
7807 targets are within eight bits, and turns them into eight-bit
7808 program-counter relative @code{bsr} and @code{bra} instructions,
7811 @command{ld} also looks at all 16-bit extended addressing modes and
7812 transforms them in a direct addressing mode when the address is in
7813 page 0 (between 0 and 0x0ff).
7815 @item relaxing gcc instruction group
7816 When @command{gcc} is called with @option{-mrelax}, it can emit group
7817 of instructions that the linker can optimize to use a 68HC11 direct
7818 addressing mode. These instructions consists of @code{bclr} or
7819 @code{bset} instructions.
7823 @subsection Trampoline Generation
7825 @cindex trampoline generation on M68HC11
7826 @cindex trampoline generation on M68HC12
7827 For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
7828 call a far function using a normal @code{jsr} instruction. The linker
7829 will also change the relocation to some far function to use the
7830 trampoline address instead of the function address. This is typically the
7831 case when a pointer to a function is taken. The pointer will in fact
7832 point to the function trampoline.
7840 @section @command{ld} and the ARM family
7842 @cindex ARM interworking support
7843 @kindex --support-old-code
7844 For the ARM, @command{ld} will generate code stubs to allow functions calls
7845 between ARM and Thumb code. These stubs only work with code that has
7846 been compiled and assembled with the @samp{-mthumb-interwork} command
7847 line option. If it is necessary to link with old ARM object files or
7848 libraries, which have not been compiled with the -mthumb-interwork
7849 option then the @samp{--support-old-code} command-line switch should be
7850 given to the linker. This will make it generate larger stub functions
7851 which will work with non-interworking aware ARM code. Note, however,
7852 the linker does not support generating stubs for function calls to
7853 non-interworking aware Thumb code.
7855 @cindex thumb entry point
7856 @cindex entry point, thumb
7857 @kindex --thumb-entry=@var{entry}
7858 The @samp{--thumb-entry} switch is a duplicate of the generic
7859 @samp{--entry} switch, in that it sets the program's starting address.
7860 But it also sets the bottom bit of the address, so that it can be
7861 branched to using a BX instruction, and the program will start
7862 executing in Thumb mode straight away.
7864 @cindex PE import table prefixing
7865 @kindex --use-nul-prefixed-import-tables
7866 The @samp{--use-nul-prefixed-import-tables} switch is specifying, that
7867 the import tables idata4 and idata5 have to be generated with a zero
7868 element prefix for import libraries. This is the old style to generate
7869 import tables. By default this option is turned off.
7873 The @samp{--be8} switch instructs @command{ld} to generate BE8 format
7874 executables. This option is only valid when linking big-endian
7875 objects - ie ones which have been assembled with the @option{-EB}
7876 option. The resulting image will contain big-endian data and
7880 @kindex --target1-rel
7881 @kindex --target1-abs
7882 The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
7883 @samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32}
7884 or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel}
7885 and @samp{--target1-abs} switches override the default.
7888 @kindex --target2=@var{type}
7889 The @samp{--target2=type} switch overrides the default definition of the
7890 @samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their
7891 meanings, and target defaults are as follows:
7894 @samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
7898 @samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
7903 The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF
7904 specification) enables objects compiled for the ARMv4 architecture to be
7905 interworking-safe when linked with other objects compiled for ARMv4t, but
7906 also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
7908 In the latter case, the switch @option{--fix-v4bx} must be passed to the
7909 linker, which causes v4t @code{BX rM} instructions to be rewritten as
7910 @code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
7912 In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
7913 relocations are ignored.
7915 @cindex FIX_V4BX_INTERWORKING
7916 @kindex --fix-v4bx-interworking
7917 Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX}
7918 relocations with a branch to the following veneer:
7926 This allows generation of libraries/applications that work on ARMv4 cores
7927 and are still interworking safe. Note that the above veneer clobbers the
7928 condition flags, so may cause incorrect program behavior in rare cases.
7932 The @samp{--use-blx} switch enables the linker to use ARM/Thumb
7933 BLX instructions (available on ARMv5t and above) in various
7934 situations. Currently it is used to perform calls via the PLT from Thumb
7935 code using BLX rather than using BX and a mode-switching stub before
7936 each PLT entry. This should lead to such calls executing slightly faster.
7938 @cindex VFP11_DENORM_FIX
7939 @kindex --vfp11-denorm-fix
7940 The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
7941 bug in certain VFP11 coprocessor hardware, which sometimes allows
7942 instructions with denorm operands (which must be handled by support code)
7943 to have those operands overwritten by subsequent instructions before
7944 the support code can read the intended values.
7946 The bug may be avoided in scalar mode if you allow at least one
7947 intervening instruction between a VFP11 instruction which uses a register
7948 and another instruction which writes to the same register, or at least two
7949 intervening instructions if vector mode is in use. The bug only affects
7950 full-compliance floating-point mode: you do not need this workaround if
7951 you are using "runfast" mode. Please contact ARM for further details.
7953 If you know you are using buggy VFP11 hardware, you can
7954 enable this workaround by specifying the linker option
7955 @samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
7956 mode only, or @samp{--vfp-denorm-fix=vector} if you are using
7957 vector mode (the latter also works for scalar code). The default is
7958 @samp{--vfp-denorm-fix=none}.
7960 If the workaround is enabled, instructions are scanned for
7961 potentially-troublesome sequences, and a veneer is created for each
7962 such sequence which may trigger the erratum. The veneer consists of the
7963 first instruction of the sequence and a branch back to the subsequent
7964 instruction. The original instruction is then replaced with a branch to
7965 the veneer. The extra cycles required to call and return from the veneer
7966 are sufficient to avoid the erratum in both the scalar and vector cases.
7968 @cindex ARM1176 erratum workaround
7969 @kindex --fix-arm1176
7970 @kindex --no-fix-arm1176
7971 The @samp{--fix-arm1176} switch enables a link-time workaround for an erratum
7972 in certain ARM1176 processors. The workaround is enabled by default if you
7973 are targeting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled
7974 unconditionally by specifying @samp{--no-fix-arm1176}.
7976 Further information is available in the ``ARM1176JZ-S and ARM1176JZF-S
7977 Programmer Advice Notice'' available on the ARM documentation website at:
7978 http://infocenter.arm.com/.
7980 @cindex STM32L4xx erratum workaround
7981 @kindex --fix-stm32l4xx-629360
7983 The @samp{--fix-stm32l4xx-629360} switch enables a link-time
7984 workaround for a bug in the bus matrix / memory controller for some of
7985 the STM32 Cortex-M4 based products (STM32L4xx). When accessing
7986 off-chip memory via the affected bus for bus reads of 9 words or more,
7987 the bus can generate corrupt data and/or abort. These are only
7988 core-initiated accesses (not DMA), and might affect any access:
7989 integer loads such as LDM, POP and floating-point loads such as VLDM,
7990 VPOP. Stores are not affected.
7992 The bug can be avoided by splitting memory accesses into the
7993 necessary chunks to keep bus reads below 8 words.
7995 The workaround is not enabled by default, this is equivalent to use
7996 @samp{--fix-stm32l4xx-629360=none}. If you know you are using buggy
7997 STM32L4xx hardware, you can enable the workaround by specifying the
7998 linker option @samp{--fix-stm32l4xx-629360}, or the equivalent
7999 @samp{--fix-stm32l4xx-629360=default}.
8001 If the workaround is enabled, instructions are scanned for
8002 potentially-troublesome sequences, and a veneer is created for each
8003 such sequence which may trigger the erratum. The veneer consists in a
8004 replacement sequence emulating the behaviour of the original one and a
8005 branch back to the subsequent instruction. The original instruction is
8006 then replaced with a branch to the veneer.
8008 The workaround does not always preserve the memory access order for
8009 the LDMDB instruction, when the instruction loads the PC.
8011 The workaround is not able to handle problematic instructions when
8012 they are in the middle of an IT block, since a branch is not allowed
8013 there. In that case, the linker reports a warning and no replacement
8016 The workaround is not able to replace problematic instructions with a
8017 PC-relative branch instruction if the @samp{.text} section is too
8018 large. In that case, when the branch that replaces the original code
8019 cannot be encoded, the linker reports a warning and no replacement
8022 @cindex NO_ENUM_SIZE_WARNING
8023 @kindex --no-enum-size-warning
8024 The @option{--no-enum-size-warning} switch prevents the linker from
8025 warning when linking object files that specify incompatible EABI
8026 enumeration size attributes. For example, with this switch enabled,
8027 linking of an object file using 32-bit enumeration values with another
8028 using enumeration values fitted into the smallest possible space will
8031 @cindex NO_WCHAR_SIZE_WARNING
8032 @kindex --no-wchar-size-warning
8033 The @option{--no-wchar-size-warning} switch prevents the linker from
8034 warning when linking object files that specify incompatible EABI
8035 @code{wchar_t} size attributes. For example, with this switch enabled,
8036 linking of an object file using 32-bit @code{wchar_t} values with another
8037 using 16-bit @code{wchar_t} values will not be diagnosed.
8040 @kindex --pic-veneer
8041 The @samp{--pic-veneer} switch makes the linker use PIC sequences for
8042 ARM/Thumb interworking veneers, even if the rest of the binary
8043 is not PIC. This avoids problems on uClinux targets where
8044 @samp{--emit-relocs} is used to generate relocatable binaries.
8046 @cindex STUB_GROUP_SIZE
8047 @kindex --stub-group-size=@var{N}
8048 The linker will automatically generate and insert small sequences of
8049 code into a linked ARM ELF executable whenever an attempt is made to
8050 perform a function call to a symbol that is too far away. The
8051 placement of these sequences of instructions - called stubs - is
8052 controlled by the command-line option @option{--stub-group-size=N}.
8053 The placement is important because a poor choice can create a need for
8054 duplicate stubs, increasing the code size. The linker will try to
8055 group stubs together in order to reduce interruptions to the flow of
8056 code, but it needs guidance as to how big these groups should be and
8057 where they should be placed.
8059 The value of @samp{N}, the parameter to the
8060 @option{--stub-group-size=} option controls where the stub groups are
8061 placed. If it is negative then all stubs are placed after the first
8062 branch that needs them. If it is positive then the stubs can be
8063 placed either before or after the branches that need them. If the
8064 value of @samp{N} is 1 (either +1 or -1) then the linker will choose
8065 exactly where to place groups of stubs, using its built in heuristics.
8066 A value of @samp{N} greater than 1 (or smaller than -1) tells the
8067 linker that a single group of stubs can service at most @samp{N} bytes
8068 from the input sections.
8070 The default, if @option{--stub-group-size=} is not specified, is
8073 Farcalls stubs insertion is fully supported for the ARM-EABI target
8074 only, because it relies on object files properties not present
8077 @cindex Cortex-A8 erratum workaround
8078 @kindex --fix-cortex-a8
8079 @kindex --no-fix-cortex-a8
8080 The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
8082 The erratum only affects Thumb-2 code. Please contact ARM for further details.
8084 @cindex Cortex-A53 erratum 835769 workaround
8085 @kindex --fix-cortex-a53-835769
8086 @kindex --no-fix-cortex-a53-835769
8087 The @samp{--fix-cortex-a53-835769} switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying @samp{--fix-cortex-a53-835769}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a53-835769}.
8089 Please contact ARM for further details.
8091 @kindex --merge-exidx-entries
8092 @kindex --no-merge-exidx-entries
8093 @cindex Merging exidx entries
8094 The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
8097 @cindex 32-bit PLT entries
8098 The @samp{--long-plt} option enables the use of 16 byte PLT entries
8099 which support up to 4Gb of code. The default is to use 12 byte PLT
8100 entries which only support 512Mb of code.
8102 @kindex --no-apply-dynamic-relocs
8103 @cindex AArch64 rela addend
8104 The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply
8105 link-time values for dynamic relocations.
8107 @cindex Placement of SG veneers
8108 All SG veneers are placed in the special output section @code{.gnu.sgstubs}.
8109 Its start address must be set, either with the command-line option
8110 @samp{--section-start} or in a linker script, to indicate where to place these
8113 @kindex --cmse-implib
8114 @cindex Secure gateway import library
8115 The @samp{--cmse-implib} option requests that the import libraries
8116 specified by the @samp{--out-implib} and @samp{--in-implib} options are
8117 secure gateway import libraries, suitable for linking a non-secure
8118 executable against secure code as per ARMv8-M Security Extensions.
8120 @kindex --in-implib=@var{file}
8121 @cindex Input import library
8122 The @samp{--in-implib=file} specifies an input import library whose symbols
8123 must keep the same address in the executable being produced. A warning is
8124 given if no @samp{--out-implib} is given but new symbols have been introduced
8125 in the executable that should be listed in its import library. Otherwise, if
8126 @samp{--out-implib} is specified, the symbols are added to the output import
8127 library. A warning is also given if some symbols present in the input import
8128 library have disappeared from the executable. This option is only effective
8129 for Secure Gateway import libraries, ie. when @samp{--cmse-implib} is
8143 @section @command{ld} and HPPA 32-bit ELF Support
8144 @cindex HPPA multiple sub-space stubs
8145 @kindex --multi-subspace
8146 When generating a shared library, @command{ld} will by default generate
8147 import stubs suitable for use with a single sub-space application.
8148 The @samp{--multi-subspace} switch causes @command{ld} to generate export
8149 stubs, and different (larger) import stubs suitable for use with
8150 multiple sub-spaces.
8152 @cindex HPPA stub grouping
8153 @kindex --stub-group-size=@var{N}
8154 Long branch stubs and import/export stubs are placed by @command{ld} in
8155 stub sections located between groups of input sections.
8156 @samp{--stub-group-size} specifies the maximum size of a group of input
8157 sections handled by one stub section. Since branch offsets are signed,
8158 a stub section may serve two groups of input sections, one group before
8159 the stub section, and one group after it. However, when using
8160 conditional branches that require stubs, it may be better (for branch
8161 prediction) that stub sections only serve one group of input sections.
8162 A negative value for @samp{N} chooses this scheme, ensuring that
8163 branches to stubs always use a negative offset. Two special values of
8164 @samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
8165 @command{ld} to automatically size input section groups for the branch types
8166 detected, with the same behaviour regarding stub placement as other
8167 positive or negative values of @samp{N} respectively.
8169 Note that @samp{--stub-group-size} does not split input sections. A
8170 single input section larger than the group size specified will of course
8171 create a larger group (of one section). If input sections are too
8172 large, it may not be possible for a branch to reach its stub.
8185 @section @command{ld} and the Motorola 68K family
8187 @cindex Motorola 68K GOT generation
8188 @kindex --got=@var{type}
8189 The @samp{--got=@var{type}} option lets you choose the GOT generation scheme.
8190 The choices are @samp{single}, @samp{negative}, @samp{multigot} and
8191 @samp{target}. When @samp{target} is selected the linker chooses
8192 the default GOT generation scheme for the current target.
8193 @samp{single} tells the linker to generate a single GOT with
8194 entries only at non-negative offsets.
8195 @samp{negative} instructs the linker to generate a single GOT with
8196 entries at both negative and positive offsets. Not all environments
8198 @samp{multigot} allows the linker to generate several GOTs in the
8199 output file. All GOT references from a single input object
8200 file access the same GOT, but references from different input object
8201 files might access different GOTs. Not all environments support such GOTs.
8214 @section @command{ld} and the MIPS family
8216 @cindex MIPS microMIPS instruction choice selection
8219 The @samp{--insn32} and @samp{--no-insn32} options control the choice of
8220 microMIPS instructions used in code generated by the linker, such as that
8221 in the PLT or lazy binding stubs, or in relaxation. If @samp{--insn32} is
8222 used, then the linker only uses 32-bit instruction encodings. By default
8223 or if @samp{--no-insn32} is used, all instruction encodings are used,
8224 including 16-bit ones where possible.
8226 @cindex MIPS branch relocation check control
8227 @kindex --ignore-branch-isa
8228 @kindex --no-ignore-branch-isa
8229 The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options
8230 control branch relocation checks for invalid ISA mode transitions. If
8231 @samp{--ignore-branch-isa} is used, then the linker accepts any branch
8232 relocations and any ISA mode transition required is lost in relocation
8233 calculation, except for some cases of @code{BAL} instructions which meet
8234 relaxation conditions and are converted to equivalent @code{JALX}
8235 instructions as the associated relocation is calculated. By default
8236 or if @samp{--no-ignore-branch-isa} is used a check is made causing
8237 the loss of an ISA mode transition to produce an error.
8250 @section @code{ld} and MMIX
8251 For MMIX, there is a choice of generating @code{ELF} object files or
8252 @code{mmo} object files when linking. The simulator @code{mmix}
8253 understands the @code{mmo} format. The binutils @code{objcopy} utility
8254 can translate between the two formats.
8256 There is one special section, the @samp{.MMIX.reg_contents} section.
8257 Contents in this section is assumed to correspond to that of global
8258 registers, and symbols referring to it are translated to special symbols,
8259 equal to registers. In a final link, the start address of the
8260 @samp{.MMIX.reg_contents} section corresponds to the first allocated
8261 global register multiplied by 8. Register @code{$255} is not included in
8262 this section; it is always set to the program entry, which is at the
8263 symbol @code{Main} for @code{mmo} files.
8265 Global symbols with the prefix @code{__.MMIX.start.}, for example
8266 @code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special.
8267 The default linker script uses these to set the default start address
8270 Initial and trailing multiples of zero-valued 32-bit words in a section,
8271 are left out from an mmo file.
8284 @section @code{ld} and MSP430
8285 For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]}
8286 will select an appropriate linker script for selected MPU type. (To get a list of known MPUs
8287 just pass @samp{-m help} option to the linker).
8289 @cindex MSP430 extra sections
8290 The linker will recognize some extra sections which are MSP430 specific:
8293 @item @samp{.vectors}
8294 Defines a portion of ROM where interrupt vectors located.
8296 @item @samp{.bootloader}
8297 Defines the bootloader portion of the ROM (if applicable). Any code
8298 in this section will be uploaded to the MPU.
8300 @item @samp{.infomem}
8301 Defines an information memory section (if applicable). Any code in
8302 this section will be uploaded to the MPU.
8304 @item @samp{.infomemnobits}
8305 This is the same as the @samp{.infomem} section except that any code
8306 in this section will not be uploaded to the MPU.
8308 @item @samp{.noinit}
8309 Denotes a portion of RAM located above @samp{.bss} section.
8311 The last two sections are used by gcc.
8315 @cindex MSP430 Options
8316 @kindex --code-region
8317 @item --code-region=[either,lower,upper,none]
8318 This will transform .text* sections to [either,lower,upper].text* sections. The
8319 argument passed to GCC for -mcode-region is propagated to the linker
8322 @kindex --data-region
8323 @item --data-region=[either,lower,upper,none]
8324 This will transform .data*, .bss* and .rodata* sections to
8325 [either,lower,upper].[data,bss,rodata]* sections. The argument passed to GCC
8326 for -mdata-region is propagated to the linker using this option.
8328 @kindex --disable-sec-transformation
8329 @item --disable-sec-transformation
8330 Prevent the transformation of sections as specified by the @code{--code-region}
8331 and @code{--data-region} options.
8332 This is useful if you are compiling and linking using a single call to the GCC
8333 wrapper, and want to compile the source files using -m[code,data]-region but
8334 not transform the sections for prebuilt libraries and objects.
8348 @section @code{ld} and NDS32
8349 @kindex relaxing on NDS32
8350 For NDS32, there are some options to select relaxation behavior. The linker
8351 relaxes objects according to these options.
8354 @item @samp{--m[no-]fp-as-gp}
8355 Disable/enable fp-as-gp relaxation.
8357 @item @samp{--mexport-symbols=FILE}
8358 Exporting symbols and their address into FILE as linker script.
8360 @item @samp{--m[no-]ex9}
8361 Disable/enable link-time EX9 relaxation.
8363 @item @samp{--mexport-ex9=FILE}
8364 Export the EX9 table after linking.
8366 @item @samp{--mimport-ex9=FILE}
8367 Import the Ex9 table for EX9 relaxation.
8369 @item @samp{--mupdate-ex9}
8370 Update the existing EX9 table.
8372 @item @samp{--mex9-limit=NUM}
8373 Maximum number of entries in the ex9 table.
8375 @item @samp{--mex9-loop-aware}
8376 Avoid generating the EX9 instruction inside the loop.
8378 @item @samp{--m[no-]ifc}
8379 Disable/enable the link-time IFC optimization.
8381 @item @samp{--mifc-loop-aware}
8382 Avoid generating the IFC instruction inside the loop.
8396 @section @command{ld} and the Altera Nios II
8397 @cindex Nios II call relaxation
8398 @kindex --relax on Nios II
8400 Call and immediate jump instructions on Nios II processors are limited to
8401 transferring control to addresses in the same 256MB memory segment,
8402 which may result in @command{ld} giving
8403 @samp{relocation truncated to fit} errors with very large programs.
8404 The command-line option @option{--relax} enables the generation of
8405 trampolines that can access the entire 32-bit address space for calls
8406 outside the normal @code{call} and @code{jmpi} address range. These
8407 trampolines are inserted at section boundaries, so may not themselves
8408 be reachable if an input section and its associated call trampolines are
8411 The @option{--relax} option is enabled by default unless @option{-r}
8412 is also specified. You can disable trampoline generation by using the
8413 @option{--no-relax} linker option. You can also disable this optimization
8414 locally by using the @samp{set .noat} directive in assembly-language
8415 source files, as the linker-inserted trampolines use the @code{at}
8416 register as a temporary.
8418 Note that the linker @option{--relax} option is independent of assembler
8419 relaxation options, and that using the GNU assembler's @option{-relax-all}
8420 option interferes with the linker's more selective call instruction relaxation.
8433 @section @command{ld} and PowerPC 32-bit ELF Support
8434 @cindex PowerPC long branches
8435 @kindex --relax on PowerPC
8436 Branches on PowerPC processors are limited to a signed 26-bit
8437 displacement, which may result in @command{ld} giving
8438 @samp{relocation truncated to fit} errors with very large programs.
8439 @samp{--relax} enables the generation of trampolines that can access
8440 the entire 32-bit address space. These trampolines are inserted at
8441 section boundaries, so may not themselves be reachable if an input
8442 section exceeds 33M in size. You may combine @samp{-r} and
8443 @samp{--relax} to add trampolines in a partial link. In that case
8444 both branches to undefined symbols and inter-section branches are also
8445 considered potentially out of range, and trampolines inserted.
8447 @cindex PowerPC ELF32 options
8452 Current PowerPC GCC accepts a @samp{-msecure-plt} option that
8453 generates code capable of using a newer PLT and GOT layout that has
8454 the security advantage of no executable section ever needing to be
8455 writable and no writable section ever being executable. PowerPC
8456 @command{ld} will generate this layout, including stubs to access the
8457 PLT, if all input files (including startup and static libraries) were
8458 compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old
8459 BSS PLT (and GOT layout) which can give slightly better performance.
8461 @kindex --secure-plt
8463 @command{ld} will use the new PLT and GOT layout if it is linking new
8464 @samp{-fpic} or @samp{-fPIC} code, but does not do so automatically
8465 when linking non-PIC code. This option requests the new PLT and GOT
8466 layout. A warning will be given if some object file requires the old
8472 The new secure PLT and GOT are placed differently relative to other
8473 sections compared to older BSS PLT and GOT placement. The location of
8474 @code{.plt} must change because the new secure PLT is an initialized
8475 section while the old PLT is uninitialized. The reason for the
8476 @code{.got} change is more subtle: The new placement allows
8477 @code{.got} to be read-only in applications linked with
8478 @samp{-z relro -z now}. However, this placement means that
8479 @code{.sdata} cannot always be used in shared libraries, because the
8480 PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
8481 pointer. @samp{--sdata-got} forces the old GOT placement. PowerPC
8482 GCC doesn't use @code{.sdata} in shared libraries, so this option is
8483 really only useful for other compilers that may do so.
8485 @cindex PowerPC stub symbols
8486 @kindex --emit-stub-syms
8487 @item --emit-stub-syms
8488 This option causes @command{ld} to label linker stubs with a local
8489 symbol that encodes the stub type and destination.
8491 @cindex PowerPC TLS optimization
8492 @kindex --no-tls-optimize
8493 @item --no-tls-optimize
8494 PowerPC @command{ld} normally performs some optimization of code
8495 sequences used to access Thread-Local Storage. Use this option to
8496 disable the optimization.
8509 @node PowerPC64 ELF64
8510 @section @command{ld} and PowerPC64 64-bit ELF Support
8512 @cindex PowerPC64 ELF64 options
8514 @cindex PowerPC64 stub grouping
8515 @kindex --stub-group-size
8516 @item --stub-group-size
8517 Long branch stubs, PLT call stubs and TOC adjusting stubs are placed
8518 by @command{ld} in stub sections located between groups of input sections.
8519 @samp{--stub-group-size} specifies the maximum size of a group of input
8520 sections handled by one stub section. Since branch offsets are signed,
8521 a stub section may serve two groups of input sections, one group before
8522 the stub section, and one group after it. However, when using
8523 conditional branches that require stubs, it may be better (for branch
8524 prediction) that stub sections only serve one group of input sections.
8525 A negative value for @samp{N} chooses this scheme, ensuring that
8526 branches to stubs always use a negative offset. Two special values of
8527 @samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
8528 @command{ld} to automatically size input section groups for the branch types
8529 detected, with the same behaviour regarding stub placement as other
8530 positive or negative values of @samp{N} respectively.
8532 Note that @samp{--stub-group-size} does not split input sections. A
8533 single input section larger than the group size specified will of course
8534 create a larger group (of one section). If input sections are too
8535 large, it may not be possible for a branch to reach its stub.
8537 @cindex PowerPC64 stub symbols
8538 @kindex --emit-stub-syms
8539 @item --emit-stub-syms
8540 This option causes @command{ld} to label linker stubs with a local
8541 symbol that encodes the stub type and destination.
8543 @cindex PowerPC64 dot symbols
8545 @kindex --no-dotsyms
8548 These two options control how @command{ld} interprets version patterns
8549 in a version script. Older PowerPC64 compilers emitted both a
8550 function descriptor symbol with the same name as the function, and a
8551 code entry symbol with the name prefixed by a dot (@samp{.}). To
8552 properly version a function @samp{foo}, the version script thus needs
8553 to control both @samp{foo} and @samp{.foo}. The option
8554 @samp{--dotsyms}, on by default, automatically adds the required
8555 dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this
8558 @cindex PowerPC64 register save/restore functions
8559 @kindex --save-restore-funcs
8560 @kindex --no-save-restore-funcs
8561 @item --save-restore-funcs
8562 @itemx --no-save-restore-funcs
8563 These two options control whether PowerPC64 @command{ld} automatically
8564 provides out-of-line register save and restore functions used by
8565 @samp{-Os} code. The default is to provide any such referenced
8566 function for a normal final link, and to not do so for a relocatable
8569 @cindex PowerPC64 TLS optimization
8570 @kindex --no-tls-optimize
8571 @item --no-tls-optimize
8572 PowerPC64 @command{ld} normally performs some optimization of code
8573 sequences used to access Thread-Local Storage. Use this option to
8574 disable the optimization.
8576 @cindex PowerPC64 __tls_get_addr optimization
8577 @kindex --tls-get-addr-optimize
8578 @kindex --no-tls-get-addr-optimize
8579 @kindex --tls-get-addr-regsave
8580 @kindex --no-tls-get-addr-regsave
8581 @item --tls-get-addr-optimize
8582 @itemx --no-tls-get-addr-optimize
8583 These options control how PowerPC64 @command{ld} uses a special
8584 stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support
8585 an optimization that allows the second and subsequent calls to
8586 @code{__tls_get_addr} for a given symbol to be resolved by the special
8587 stub without calling in to glibc. By default the linker enables
8588 generation of the stub when glibc advertises the availability of
8590 Using @option{--tls-get-addr-optimize} with an older glibc won't do
8591 much besides slow down your applications, but may be useful if linking
8592 an application against an older glibc with the expectation that it
8593 will normally be used on systems having a newer glibc.
8594 @option{--tls-get-addr-regsave} forces generation of a stub that saves
8595 and restores volatile registers around the call into glibc. Normally,
8596 this is done when the linker detects a call to __tls_get_addr_desc.
8597 Such calls then go via the register saving stub to __tls_get_addr_opt.
8598 @option{--no-tls-get-addr-regsave} disables generation of the
8601 @cindex PowerPC64 OPD optimization
8602 @kindex --no-opd-optimize
8603 @item --no-opd-optimize
8604 PowerPC64 @command{ld} normally removes @code{.opd} section entries
8605 corresponding to deleted link-once functions, or functions removed by
8606 the action of @samp{--gc-sections} or linker script @code{/DISCARD/}.
8607 Use this option to disable @code{.opd} optimization.
8609 @cindex PowerPC64 OPD spacing
8610 @kindex --non-overlapping-opd
8611 @item --non-overlapping-opd
8612 Some PowerPC64 compilers have an option to generate compressed
8613 @code{.opd} entries spaced 16 bytes apart, overlapping the third word,
8614 the static chain pointer (unused in C) with the first word of the next
8615 entry. This option expands such entries to the full 24 bytes.
8617 @cindex PowerPC64 TOC optimization
8618 @kindex --no-toc-optimize
8619 @item --no-toc-optimize
8620 PowerPC64 @command{ld} normally removes unused @code{.toc} section
8621 entries. Such entries are detected by examining relocations that
8622 reference the TOC in code sections. A reloc in a deleted code section
8623 marks a TOC word as unneeded, while a reloc in a kept code section
8624 marks a TOC word as needed. Since the TOC may reference itself, TOC
8625 relocs are also examined. TOC words marked as both needed and
8626 unneeded will of course be kept. TOC words without any referencing
8627 reloc are assumed to be part of a multi-word entry, and are kept or
8628 discarded as per the nearest marked preceding word. This works
8629 reliably for compiler generated code, but may be incorrect if assembly
8630 code is used to insert TOC entries. Use this option to disable the
8633 @cindex PowerPC64 inline PLT call optimization
8634 @kindex --no-inline-optimize
8635 @item --no-inline-optimize
8636 PowerPC64 @command{ld} normally replaces inline PLT call sequences
8637 marked with @code{R_PPC64_PLTSEQ}, @code{R_PPC64_PLTCALL},
8638 @code{R_PPC64_PLT16_HA} and @code{R_PPC64_PLT16_LO_DS} relocations by
8639 a number of @code{nop}s and a direct call when the function is defined
8640 locally and can't be overridden by some other definition. This option
8641 disables that optimization.
8643 @cindex PowerPC64 multi-TOC
8644 @kindex --no-multi-toc
8645 @item --no-multi-toc
8646 If given any toc option besides @code{-mcmodel=medium} or
8647 @code{-mcmodel=large}, PowerPC64 GCC generates code for a TOC model
8649 entries are accessed with a 16-bit offset from r2. This limits the
8650 total TOC size to 64K. PowerPC64 @command{ld} extends this limit by
8651 grouping code sections such that each group uses less than 64K for its
8652 TOC entries, then inserts r2 adjusting stubs between inter-group
8653 calls. @command{ld} does not split apart input sections, so cannot
8654 help if a single input file has a @code{.toc} section that exceeds
8655 64K, most likely from linking multiple files with @command{ld -r}.
8656 Use this option to turn off this feature.
8658 @cindex PowerPC64 TOC sorting
8659 @kindex --no-toc-sort
8661 By default, @command{ld} sorts TOC sections so that those whose file
8662 happens to have a section called @code{.init} or @code{.fini} are
8663 placed first, followed by TOC sections referenced by code generated
8664 with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections
8665 referenced only by code generated with PowerPC64 gcc's
8666 @code{-mcmodel=medium} or @code{-mcmodel=large} options. Doing this
8667 results in better TOC grouping for multi-TOC. Use this option to turn
8670 @cindex PowerPC64 PLT stub alignment
8672 @kindex --no-plt-align
8674 @itemx --no-plt-align
8675 Use these options to control whether individual PLT call stubs are
8676 aligned to a 32-byte boundary, or to the specified power of two
8677 boundary when using @code{--plt-align=}. A negative value may be
8678 specified to pad PLT call stubs so that they do not cross the
8679 specified power of two boundary (or the minimum number of boundaries
8680 if a PLT stub is so large that it must cross a boundary). By default
8681 PLT call stubs are aligned to 32-byte boundaries.
8683 @cindex PowerPC64 PLT call stub static chain
8684 @kindex --plt-static-chain
8685 @kindex --no-plt-static-chain
8686 @item --plt-static-chain
8687 @itemx --no-plt-static-chain
8688 Use these options to control whether PLT call stubs load the static
8689 chain pointer (r11). @code{ld} defaults to not loading the static
8690 chain since there is never any need to do so on a PLT call.
8692 @cindex PowerPC64 PLT call stub thread safety
8693 @kindex --plt-thread-safe
8694 @kindex --no-plt-thread-safe
8695 @item --plt-thread-safe
8696 @itemx --no-plt-thread-safe
8697 With power7's weakly ordered memory model, it is possible when using
8698 lazy binding for ld.so to update a plt entry in one thread and have
8699 another thread see the individual plt entry words update in the wrong
8700 order, despite ld.so carefully writing in the correct order and using
8701 memory write barriers. To avoid this we need some sort of read
8702 barrier in the call stub, or use LD_BIND_NOW=1. By default, @code{ld}
8703 looks for calls to commonly used functions that create threads, and if
8704 seen, adds the necessary barriers. Use these options to change the
8707 @cindex PowerPC64 ELFv2 PLT localentry optimization
8708 @kindex --plt-localentry
8709 @kindex --no-plt-localentry
8710 @item --plt-localentry
8711 @itemx --no-localentry
8712 ELFv2 functions with localentry:0 are those with a single entry point,
8713 ie. global entry == local entry, and that have no requirement on r2
8714 (the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return.
8715 Such an external function can be called via the PLT without saving r2
8716 or restoring it on return, avoiding a common load-hit-store for small
8717 functions. The optimization is attractive, with up to 40% reduction
8718 in execution time for a small function, but can result in symbol
8719 interposition failures. Also, minor changes in a shared library,
8720 including system libraries, can cause a function that was localentry:0
8721 to become localentry:8. This will result in a dynamic loader
8722 complaint and failure to run. The option is experimental, use with
8723 care. @option{--no-plt-localentry} is the default.
8725 @cindex PowerPC64 Power10 stubs
8726 @kindex --power10-stubs
8727 @kindex --no-power10-stubs
8728 @item --power10-stubs
8729 @itemx --no-power10-stubs
8730 When PowerPC64 @command{ld} links input object files containing
8731 relocations used on power10 prefixed instructions it normally creates
8732 linkage stubs (PLT call and long branch) using power10 instructions
8733 for @code{@@notoc} PLT calls where @code{r2} is not known. The
8734 power10 notoc stubs are smaller and faster, so are preferred for
8735 power10. @option{--power10-stubs} and @option{--no-power10-stubs}
8736 allow you to override the linker's selection of stub instructions.
8737 @option{--power10-stubs=auto} allows the user to select the default
8752 @section @command{ld} and S/390 ELF Support
8754 @cindex S/390 ELF options
8758 @kindex --s390-pgste
8760 This option marks the result file with a @code{PT_S390_PGSTE}
8761 segment. The Linux kernel is supposed to allocate 4k page tables for
8762 binaries marked that way.
8776 @section @command{ld} and SPU ELF Support
8778 @cindex SPU ELF options
8784 This option marks an executable as a PIC plugin module.
8786 @cindex SPU overlays
8787 @kindex --no-overlays
8789 Normally, @command{ld} recognizes calls to functions within overlay
8790 regions, and redirects such calls to an overlay manager via a stub.
8791 @command{ld} also provides a built-in overlay manager. This option
8792 turns off all this special overlay handling.
8794 @cindex SPU overlay stub symbols
8795 @kindex --emit-stub-syms
8796 @item --emit-stub-syms
8797 This option causes @command{ld} to label overlay stubs with a local
8798 symbol that encodes the stub type and destination.
8800 @cindex SPU extra overlay stubs
8801 @kindex --extra-overlay-stubs
8802 @item --extra-overlay-stubs
8803 This option causes @command{ld} to add overlay call stubs on all
8804 function calls out of overlay regions. Normally stubs are not added
8805 on calls to non-overlay regions.
8807 @cindex SPU local store size
8808 @kindex --local-store=lo:hi
8809 @item --local-store=lo:hi
8810 @command{ld} usually checks that a final executable for SPU fits in
8811 the address range 0 to 256k. This option may be used to change the
8812 range. Disable the check entirely with @option{--local-store=0:0}.
8815 @kindex --stack-analysis
8816 @item --stack-analysis
8817 SPU local store space is limited. Over-allocation of stack space
8818 unnecessarily limits space available for code and data, while
8819 under-allocation results in runtime failures. If given this option,
8820 @command{ld} will provide an estimate of maximum stack usage.
8821 @command{ld} does this by examining symbols in code sections to
8822 determine the extents of functions, and looking at function prologues
8823 for stack adjusting instructions. A call-graph is created by looking
8824 for relocations on branch instructions. The graph is then searched
8825 for the maximum stack usage path. Note that this analysis does not
8826 find calls made via function pointers, and does not handle recursion
8827 and other cycles in the call graph. Stack usage may be
8828 under-estimated if your code makes such calls. Also, stack usage for
8829 dynamic allocation, e.g. alloca, will not be detected. If a link map
8830 is requested, detailed information about each function's stack usage
8831 and calls will be given.
8834 @kindex --emit-stack-syms
8835 @item --emit-stack-syms
8836 This option, if given along with @option{--stack-analysis} will result
8837 in @command{ld} emitting stack sizing symbols for each function.
8838 These take the form @code{__stack_<function_name>} for global
8839 functions, and @code{__stack_<number>_<function_name>} for static
8840 functions. @code{<number>} is the section id in hex. The value of
8841 such symbols is the stack requirement for the corresponding function.
8842 The symbol size will be zero, type @code{STT_NOTYPE}, binding
8843 @code{STB_LOCAL}, and section @code{SHN_ABS}.
8857 @section @command{ld}'s Support for Various TI COFF Versions
8858 @cindex TI COFF versions
8859 @kindex --format=@var{version}
8860 The @samp{--format} switch allows selection of one of the various
8861 TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
8862 also supported. The TI COFF versions also vary in header byte-order
8863 format; @command{ld} will read any version or byte order, but the output
8864 header format depends on the default specified by the specific target.
8877 @section @command{ld} and WIN32 (cygwin/mingw)
8879 This section describes some of the win32 specific @command{ld} issues.
8880 See @ref{Options,,Command-line Options} for detailed description of the
8881 command-line options mentioned here.
8884 @cindex import libraries
8885 @item import libraries
8886 The standard Windows linker creates and uses so-called import
8887 libraries, which contains information for linking to dll's. They are
8888 regular static archives and are handled as any other static
8889 archive. The cygwin and mingw ports of @command{ld} have specific
8890 support for creating such libraries provided with the
8891 @samp{--out-implib} command-line option.
8893 @item Resource only DLLs
8894 It is possible to create a DLL that only contains resources, ie just a
8895 @samp{.rsrc} section, but in order to do so a custom linker script
8896 must be used. This is because the built-in default linker scripts
8897 will always create @samp{.text} and @samp{.idata} sections, even if
8898 there is no input to go into them.
8900 The script should look like this, although the @code{OUTPUT_FORMAT}
8901 should be changed to match the desired format.
8904 OUTPUT_FORMAT(pei-i386)
8908 . = ALIGN(__section_alignment__);
8909 .rsrc __image_base__ + __section_alignment__ : ALIGN(4)
8914 /DISCARD/ : @{ *(*) @}
8918 With this script saved to a file called, eg @file{rsrc.ld}, a command
8919 line like this can be used to create the resource only DLL
8920 @file{rsrc.dll} from an input file called @file{rsrc.o}:
8923 ld -dll --subsystem windows -e 0 -s rsrc.o -o rsrc.dll -T rsrc.ld
8926 @item exporting DLL symbols
8927 @cindex exporting DLL symbols
8928 The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
8931 @item using auto-export functionality
8932 @cindex using auto-export functionality
8933 By default @command{ld} exports symbols with the auto-export functionality,
8934 which is controlled by the following command-line options:
8937 @item --export-all-symbols [This is the default]
8938 @item --exclude-symbols
8939 @item --exclude-libs
8940 @item --exclude-modules-for-implib
8941 @item --version-script
8944 When auto-export is in operation, @command{ld} will export all the non-local
8945 (global and common) symbols it finds in a DLL, with the exception of a few
8946 symbols known to belong to the system's runtime and libraries. As it will
8947 often not be desirable to export all of a DLL's symbols, which may include
8948 private functions that are not part of any public interface, the command-line
8949 options listed above may be used to filter symbols out from the list for
8950 exporting. The @samp{--output-def} option can be used in order to see the
8951 final list of exported symbols with all exclusions taken into effect.
8953 If @samp{--export-all-symbols} is not given explicitly on the
8954 command line, then the default auto-export behavior will be @emph{disabled}
8955 if either of the following are true:
8958 @item A DEF file is used.
8959 @item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
8962 @item using a DEF file
8963 @cindex using a DEF file
8964 Another way of exporting symbols is using a DEF file. A DEF file is
8965 an ASCII file containing definitions of symbols which should be
8966 exported when a dll is created. Usually it is named @samp{<dll
8967 name>.def} and is added as any other object file to the linker's
8968 command line. The file's name must end in @samp{.def} or @samp{.DEF}.
8971 gcc -o <output> <objectfiles> <dll name>.def
8974 Using a DEF file turns off the normal auto-export behavior, unless the
8975 @samp{--export-all-symbols} option is also used.
8977 Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
8980 LIBRARY "xyz.dll" BASE=0x20000000
8986 another_foo = abc.dll.afoo
8992 This example defines a DLL with a non-default base address and seven
8993 symbols in the export table. The third exported symbol @code{_bar} is an
8994 alias for the second. The fourth symbol, @code{another_foo} is resolved
8995 by "forwarding" to another module and treating it as an alias for
8996 @code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
8997 @code{var1} is declared to be a data object. The @samp{doo} symbol in
8998 export library is an alias of @samp{foo}, which gets the string name
8999 in export table @samp{foo2}. The @samp{eoo} symbol is an data export
9000 symbol, which gets in export table the name @samp{var1}.
9002 The optional @code{LIBRARY <name>} command indicates the @emph{internal}
9003 name of the output DLL. If @samp{<name>} does not include a suffix,
9004 the default library suffix, @samp{.DLL} is appended.
9006 When the .DEF file is used to build an application, rather than a
9007 library, the @code{NAME <name>} command should be used instead of
9008 @code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
9009 executable suffix, @samp{.EXE} is appended.
9011 With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
9012 specification @code{BASE = <number>} may be used to specify a
9013 non-default base address for the image.
9015 If neither @code{LIBRARY <name>} nor @code{NAME <name>} is specified,
9016 or they specify an empty string, the internal name is the same as the
9017 filename specified on the command line.
9019 The complete specification of an export symbol is:
9023 ( ( ( <name1> [ = <name2> ] )
9024 | ( <name1> = <module-name> . <external-name>))
9025 [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
9028 Declares @samp{<name1>} as an exported symbol from the DLL, or declares
9029 @samp{<name1>} as an exported alias for @samp{<name2>}; or declares
9030 @samp{<name1>} as a "forward" alias for the symbol
9031 @samp{<external-name>} in the DLL @samp{<module-name>}.
9032 Optionally, the symbol may be exported by the specified ordinal
9033 @samp{<integer>} alias. The optional @samp{<name3>} is the to be used
9034 string in import/export table for the symbol.
9036 The optional keywords that follow the declaration indicate:
9038 @code{NONAME}: Do not put the symbol name in the DLL's export table. It
9039 will still be exported by its ordinal alias (either the value specified
9040 by the .def specification or, otherwise, the value assigned by the
9041 linker). The symbol name, however, does remain visible in the import
9042 library (if any), unless @code{PRIVATE} is also specified.
9044 @code{DATA}: The symbol is a variable or object, rather than a function.
9045 The import lib will export only an indirect reference to @code{foo} as
9046 the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
9049 @code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
9050 well as @code{_imp__foo} into the import library. Both refer to the
9051 read-only import address table's pointer to the variable, not to the
9052 variable itself. This can be dangerous. If the user code fails to add
9053 the @code{dllimport} attribute and also fails to explicitly add the
9054 extra indirection that the use of the attribute enforces, the
9055 application will behave unexpectedly.
9057 @code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
9058 it into the static import library used to resolve imports at link time. The
9059 symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
9060 API at runtime or by using the GNU ld extension of linking directly to
9061 the DLL without an import library.
9063 See ld/deffilep.y in the binutils sources for the full specification of
9064 other DEF file statements
9066 @cindex creating a DEF file
9067 While linking a shared dll, @command{ld} is able to create a DEF file
9068 with the @samp{--output-def <file>} command-line option.
9070 @item Using decorations
9071 @cindex Using decorations
9072 Another way of marking symbols for export is to modify the source code
9073 itself, so that when building the DLL each symbol to be exported is
9077 __declspec(dllexport) int a_variable
9078 __declspec(dllexport) void a_function(int with_args)
9081 All such symbols will be exported from the DLL. If, however,
9082 any of the object files in the DLL contain symbols decorated in
9083 this way, then the normal auto-export behavior is disabled, unless
9084 the @samp{--export-all-symbols} option is also used.
9086 Note that object files that wish to access these symbols must @emph{not}
9087 decorate them with dllexport. Instead, they should use dllimport,
9091 __declspec(dllimport) int a_variable
9092 __declspec(dllimport) void a_function(int with_args)
9095 This complicates the structure of library header files, because
9096 when included by the library itself the header must declare the
9097 variables and functions as dllexport, but when included by client
9098 code the header must declare them as dllimport. There are a number
9099 of idioms that are typically used to do this; often client code can
9100 omit the __declspec() declaration completely. See
9101 @samp{--enable-auto-import} and @samp{automatic data imports} for more
9105 @cindex automatic data imports
9106 @item automatic data imports
9107 The standard Windows dll format supports data imports from dlls only
9108 by adding special decorations (dllimport/dllexport), which let the
9109 compiler produce specific assembler instructions to deal with this
9110 issue. This increases the effort necessary to port existing Un*x
9111 code to these platforms, especially for large
9112 c++ libraries and applications. The auto-import feature, which was
9113 initially provided by Paul Sokolovsky, allows one to omit the
9114 decorations to achieve a behavior that conforms to that on POSIX/Un*x
9115 platforms. This feature is enabled with the @samp{--enable-auto-import}
9116 command-line option, although it is enabled by default on cygwin/mingw.
9117 The @samp{--enable-auto-import} option itself now serves mainly to
9118 suppress any warnings that are ordinarily emitted when linked objects
9119 trigger the feature's use.
9121 auto-import of variables does not always work flawlessly without
9122 additional assistance. Sometimes, you will see this message
9124 "variable '<var>' can't be auto-imported. Please read the
9125 documentation for ld's @code{--enable-auto-import} for details."
9127 The @samp{--enable-auto-import} documentation explains why this error
9128 occurs, and several methods that can be used to overcome this difficulty.
9129 One of these methods is the @emph{runtime pseudo-relocs} feature, described
9132 @cindex runtime pseudo-relocation
9133 For complex variables imported from DLLs (such as structs or classes),
9134 object files typically contain a base address for the variable and an
9135 offset (@emph{addend}) within the variable--to specify a particular
9136 field or public member, for instance. Unfortunately, the runtime loader used
9137 in win32 environments is incapable of fixing these references at runtime
9138 without the additional information supplied by dllimport/dllexport decorations.
9139 The standard auto-import feature described above is unable to resolve these
9142 The @samp{--enable-runtime-pseudo-relocs} switch allows these references to
9143 be resolved without error, while leaving the task of adjusting the references
9144 themselves (with their non-zero addends) to specialized code provided by the
9145 runtime environment. Recent versions of the cygwin and mingw environments and
9146 compilers provide this runtime support; older versions do not. However, the
9147 support is only necessary on the developer's platform; the compiled result will
9148 run without error on an older system.
9150 @samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
9153 @cindex direct linking to a dll
9154 @item direct linking to a dll
9155 The cygwin/mingw ports of @command{ld} support the direct linking,
9156 including data symbols, to a dll without the usage of any import
9157 libraries. This is much faster and uses much less memory than does the
9158 traditional import library method, especially when linking large
9159 libraries or applications. When @command{ld} creates an import lib, each
9160 function or variable exported from the dll is stored in its own bfd, even
9161 though a single bfd could contain many exports. The overhead involved in
9162 storing, loading, and processing so many bfd's is quite large, and explains the
9163 tremendous time, memory, and storage needed to link against particularly
9164 large or complex libraries when using import libs.
9166 Linking directly to a dll uses no extra command-line switches other than
9167 @samp{-L} and @samp{-l}, because @command{ld} already searches for a number
9168 of names to match each library. All that is needed from the developer's
9169 perspective is an understanding of this search, in order to force ld to
9170 select the dll instead of an import library.
9173 For instance, when ld is called with the argument @samp{-lxxx} it will attempt
9174 to find, in the first directory of its search path,
9187 before moving on to the next directory in the search path.
9189 (*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
9190 where @samp{<prefix>} is set by the @command{ld} option
9191 @samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
9192 file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
9195 Other win32-based unix environments, such as mingw or pw32, may use other
9196 @samp{<prefix>}es, although at present only cygwin makes use of this feature. It
9197 was originally intended to help avoid name conflicts among dll's built for the
9198 various win32/un*x environments, so that (for example) two versions of a zlib dll
9199 could coexist on the same machine.
9201 The generic cygwin/mingw path layout uses a @samp{bin} directory for
9202 applications and dll's and a @samp{lib} directory for the import
9203 libraries (using cygwin nomenclature):
9209 libxxx.dll.a (in case of dll's)
9210 libxxx.a (in case of static archive)
9213 Linking directly to a dll without using the import library can be
9216 1. Use the dll directly by adding the @samp{bin} path to the link line
9218 gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
9221 However, as the dll's often have version numbers appended to their names
9222 (@samp{cygncurses-5.dll}) this will often fail, unless one specifies
9223 @samp{-L../bin -lncurses-5} to include the version. Import libs are generally
9224 not versioned, and do not have this difficulty.
9226 2. Create a symbolic link from the dll to a file in the @samp{lib}
9227 directory according to the above mentioned search pattern. This
9228 should be used to avoid unwanted changes in the tools needed for
9232 ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
9235 Then you can link without any make environment changes.
9238 gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
9241 This technique also avoids the version number problems, because the following is
9248 libxxx.dll.a -> ../bin/cygxxx-5.dll
9251 Linking directly to a dll without using an import lib will work
9252 even when auto-import features are exercised, and even when
9253 @samp{--enable-runtime-pseudo-relocs} is used.
9255 Given the improvements in speed and memory usage, one might justifiably
9256 wonder why import libraries are used at all. There are three reasons:
9258 1. Until recently, the link-directly-to-dll functionality did @emph{not}
9259 work with auto-imported data.
9261 2. Sometimes it is necessary to include pure static objects within the
9262 import library (which otherwise contains only bfd's for indirection
9263 symbols that point to the exports of a dll). Again, the import lib
9264 for the cygwin kernel makes use of this ability, and it is not
9265 possible to do this without an import lib.
9267 3. Symbol aliases can only be resolved using an import lib. This is
9268 critical when linking against OS-supplied dll's (eg, the win32 API)
9269 in which symbols are usually exported as undecorated aliases of their
9270 stdcall-decorated assembly names.
9272 So, import libs are not going away. But the ability to replace
9273 true import libs with a simple symbolic link to (or a copy of)
9274 a dll, in many cases, is a useful addition to the suite of tools
9275 binutils makes available to the win32 developer. Given the
9276 massive improvements in memory requirements during linking, storage
9277 requirements, and linking speed, we expect that many developers
9278 will soon begin to use this feature whenever possible.
9280 @item symbol aliasing
9282 @item adding additional names
9283 Sometimes, it is useful to export symbols with additional names.
9284 A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
9285 exported as @samp{_foo} by using special directives in the DEF file
9286 when creating the dll. This will affect also the optional created
9287 import library. Consider the following DEF file:
9290 LIBRARY "xyz.dll" BASE=0x61000000
9297 The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
9299 Another method for creating a symbol alias is to create it in the
9300 source code using the "weak" attribute:
9303 void foo () @{ /* Do something. */; @}
9304 void _foo () __attribute__ ((weak, alias ("foo")));
9307 See the gcc manual for more information about attributes and weak
9310 @item renaming symbols
9311 Sometimes it is useful to rename exports. For instance, the cygwin
9312 kernel does this regularly. A symbol @samp{_foo} can be exported as
9313 @samp{foo} but not as @samp{_foo} by using special directives in the
9314 DEF file. (This will also affect the import library, if it is
9315 created). In the following example:
9318 LIBRARY "xyz.dll" BASE=0x61000000
9324 The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
9328 Note: using a DEF file disables the default auto-export behavior,
9329 unless the @samp{--export-all-symbols} command-line option is used.
9330 If, however, you are trying to rename symbols, then you should list
9331 @emph{all} desired exports in the DEF file, including the symbols
9332 that are not being renamed, and do @emph{not} use the
9333 @samp{--export-all-symbols} option. If you list only the
9334 renamed symbols in the DEF file, and use @samp{--export-all-symbols}
9335 to handle the other symbols, then the both the new names @emph{and}
9336 the original names for the renamed symbols will be exported.
9337 In effect, you'd be aliasing those symbols, not renaming them,
9338 which is probably not what you wanted.
9340 @cindex weak externals
9341 @item weak externals
9342 The Windows object format, PE, specifies a form of weak symbols called
9343 weak externals. When a weak symbol is linked and the symbol is not
9344 defined, the weak symbol becomes an alias for some other symbol. There
9345 are three variants of weak externals:
9347 @item Definition is searched for in objects and libraries, historically
9348 called lazy externals.
9349 @item Definition is searched for only in other objects, not in libraries.
9350 This form is not presently implemented.
9351 @item No search; the symbol is an alias. This form is not presently
9354 As a GNU extension, weak symbols that do not specify an alternate symbol
9355 are supported. If the symbol is undefined when linking, the symbol
9356 uses a default value.
9358 @cindex aligned common symbols
9359 @item aligned common symbols
9360 As a GNU extension to the PE file format, it is possible to specify the
9361 desired alignment for a common symbol. This information is conveyed from
9362 the assembler or compiler to the linker by means of GNU-specific commands
9363 carried in the object file's @samp{.drectve} section, which are recognized
9364 by @command{ld} and respected when laying out the common symbols. Native
9365 tools will be able to process object files employing this GNU extension,
9366 but will fail to respect the alignment instructions, and may issue noisy
9367 warnings about unknown linker directives.
9382 @section @code{ld} and Xtensa Processors
9384 @cindex Xtensa processors
9385 The default @command{ld} behavior for Xtensa processors is to interpret
9386 @code{SECTIONS} commands so that lists of explicitly named sections in a
9387 specification with a wildcard file will be interleaved when necessary to
9388 keep literal pools within the range of PC-relative load offsets. For
9389 example, with the command:
9401 @command{ld} may interleave some of the @code{.literal}
9402 and @code{.text} sections from different object files to ensure that the
9403 literal pools are within the range of PC-relative load offsets. A valid
9404 interleaving might place the @code{.literal} sections from an initial
9405 group of files followed by the @code{.text} sections of that group of
9406 files. Then, the @code{.literal} sections from the rest of the files
9407 and the @code{.text} sections from the rest of the files would follow.
9409 @cindex @option{--relax} on Xtensa
9410 @cindex relaxing on Xtensa
9411 Relaxation is enabled by default for the Xtensa version of @command{ld} and
9412 provides two important link-time optimizations. The first optimization
9413 is to combine identical literal values to reduce code size. A redundant
9414 literal will be removed and all the @code{L32R} instructions that use it
9415 will be changed to reference an identical literal, as long as the
9416 location of the replacement literal is within the offset range of all
9417 the @code{L32R} instructions. The second optimization is to remove
9418 unnecessary overhead from assembler-generated ``longcall'' sequences of
9419 @code{L32R}/@code{CALLX@var{n}} when the target functions are within
9420 range of direct @code{CALL@var{n}} instructions.
9422 For each of these cases where an indirect call sequence can be optimized
9423 to a direct call, the linker will change the @code{CALLX@var{n}}
9424 instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
9425 instruction, and remove the literal referenced by the @code{L32R}
9426 instruction if it is not used for anything else. Removing the
9427 @code{L32R} instruction always reduces code size but can potentially
9428 hurt performance by changing the alignment of subsequent branch targets.
9429 By default, the linker will always preserve alignments, either by
9430 switching some instructions between 24-bit encodings and the equivalent
9431 density instructions or by inserting a no-op in place of the @code{L32R}
9432 instruction that was removed. If code size is more important than
9433 performance, the @option{--size-opt} option can be used to prevent the
9434 linker from widening density instructions or inserting no-ops, except in
9435 a few cases where no-ops are required for correctness.
9437 The following Xtensa-specific command-line options can be used to
9440 @cindex Xtensa options
9443 When optimizing indirect calls to direct calls, optimize for code size
9444 more than performance. With this option, the linker will not insert
9445 no-ops or widen density instructions to preserve branch target
9446 alignment. There may still be some cases where no-ops are required to
9447 preserve the correctness of the code.
9449 @item --abi-windowed
9451 Choose ABI for the output object and for the generated PLT code.
9452 PLT code inserted by the linker must match ABI of the output object
9453 because windowed and call0 ABI use incompatible function call
9455 Default ABI is chosen by the ABI tag in the @code{.xtensa.info} section
9456 of the first input object.
9457 A warning is issued if ABI tags of input objects do not match each other
9458 or the chosen output object ABI.
9466 @ifclear SingleFormat
9471 @cindex object file management
9472 @cindex object formats available
9474 The linker accesses object and archive files using the BFD libraries.
9475 These libraries allow the linker to use the same routines to operate on
9476 object files whatever the object file format. A different object file
9477 format can be supported simply by creating a new BFD back end and adding
9478 it to the library. To conserve runtime memory, however, the linker and
9479 associated tools are usually configured to support only a subset of the
9480 object file formats available. You can use @code{objdump -i}
9481 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
9482 list all the formats available for your configuration.
9484 @cindex BFD requirements
9485 @cindex requirements for BFD
9486 As with most implementations, BFD is a compromise between
9487 several conflicting requirements. The major factor influencing
9488 BFD design was efficiency: any time used converting between
9489 formats is time which would not have been spent had BFD not
9490 been involved. This is partly offset by abstraction payback; since
9491 BFD simplifies applications and back ends, more time and care
9492 may be spent optimizing algorithms for a greater speed.
9494 One minor artifact of the BFD solution which you should bear in
9495 mind is the potential for information loss. There are two places where
9496 useful information can be lost using the BFD mechanism: during
9497 conversion and during output. @xref{BFD information loss}.
9500 * BFD outline:: How it works: an outline of BFD
9504 @section How It Works: An Outline of BFD
9505 @cindex opening object files
9506 @include bfdsumm.texi
9509 @node Reporting Bugs
9510 @chapter Reporting Bugs
9511 @cindex bugs in @command{ld}
9512 @cindex reporting bugs in @command{ld}
9514 Your bug reports play an essential role in making @command{ld} reliable.
9516 Reporting a bug may help you by bringing a solution to your problem, or
9517 it may not. But in any case the principal function of a bug report is
9518 to help the entire community by making the next version of @command{ld}
9519 work better. Bug reports are your contribution to the maintenance of
9522 In order for a bug report to serve its purpose, you must include the
9523 information that enables us to fix the bug.
9526 * Bug Criteria:: Have you found a bug?
9527 * Bug Reporting:: How to report bugs
9531 @section Have You Found a Bug?
9532 @cindex bug criteria
9534 If you are not sure whether you have found a bug, here are some guidelines:
9537 @cindex fatal signal
9538 @cindex linker crash
9539 @cindex crash of linker
9541 If the linker gets a fatal signal, for any input whatever, that is a
9542 @command{ld} bug. Reliable linkers never crash.
9544 @cindex error on valid input
9546 If @command{ld} produces an error message for valid input, that is a bug.
9548 @cindex invalid input
9550 If @command{ld} does not produce an error message for invalid input, that
9551 may be a bug. In the general case, the linker can not verify that
9552 object files are correct.
9555 If you are an experienced user of linkers, your suggestions for
9556 improvement of @command{ld} are welcome in any case.
9560 @section How to Report Bugs
9562 @cindex @command{ld} bugs, reporting
9564 A number of companies and individuals offer support for @sc{gnu}
9565 products. If you obtained @command{ld} from a support organization, we
9566 recommend you contact that organization first.
9568 You can find contact information for many support companies and
9569 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
9573 Otherwise, send bug reports for @command{ld} to
9577 The fundamental principle of reporting bugs usefully is this:
9578 @strong{report all the facts}. If you are not sure whether to state a
9579 fact or leave it out, state it!
9581 Often people omit facts because they think they know what causes the
9582 problem and assume that some details do not matter. Thus, you might
9583 assume that the name of a symbol you use in an example does not
9584 matter. Well, probably it does not, but one cannot be sure. Perhaps
9585 the bug is a stray memory reference which happens to fetch from the
9586 location where that name is stored in memory; perhaps, if the name
9587 were different, the contents of that location would fool the linker
9588 into doing the right thing despite the bug. Play it safe and give a
9589 specific, complete example. That is the easiest thing for you to do,
9590 and the most helpful.
9592 Keep in mind that the purpose of a bug report is to enable us to fix
9593 the bug if it is new to us. Therefore, always write your bug reports
9594 on the assumption that the bug has not been reported previously.
9596 Sometimes people give a few sketchy facts and ask, ``Does this ring a
9597 bell?'' This cannot help us fix a bug, so it is basically useless. We
9598 respond by asking for enough details to enable us to investigate.
9599 You might as well expedite matters by sending them to begin with.
9601 To enable us to fix the bug, you should include all these things:
9605 The version of @command{ld}. @command{ld} announces it if you start it with
9606 the @samp{--version} argument.
9608 Without this, we will not know whether there is any point in looking for
9609 the bug in the current version of @command{ld}.
9612 Any patches you may have applied to the @command{ld} source, including any
9613 patches made to the @code{BFD} library.
9616 The type of machine you are using, and the operating system name and
9620 What compiler (and its version) was used to compile @command{ld}---e.g.
9624 The command arguments you gave the linker to link your example and
9625 observe the bug. To guarantee you will not omit something important,
9626 list them all. A copy of the Makefile (or the output from make) is
9629 If we were to try to guess the arguments, we would probably guess wrong
9630 and then we might not encounter the bug.
9633 A complete input file, or set of input files, that will reproduce the
9634 bug. It is generally most helpful to send the actual object files
9635 provided that they are reasonably small. Say no more than 10K. For
9636 bigger files you can either make them available by FTP or HTTP or else
9637 state that you are willing to send the object file(s) to whomever
9638 requests them. (Note - your email will be going to a mailing list, so
9639 we do not want to clog it up with large attachments). But small
9640 attachments are best.
9642 If the source files were assembled using @code{gas} or compiled using
9643 @code{gcc}, then it may be OK to send the source files rather than the
9644 object files. In this case, be sure to say exactly what version of
9645 @code{gas} or @code{gcc} was used to produce the object files. Also say
9646 how @code{gas} or @code{gcc} were configured.
9649 A description of what behavior you observe that you believe is
9650 incorrect. For example, ``It gets a fatal signal.''
9652 Of course, if the bug is that @command{ld} gets a fatal signal, then we
9653 will certainly notice it. But if the bug is incorrect output, we might
9654 not notice unless it is glaringly wrong. You might as well not give us
9655 a chance to make a mistake.
9657 Even if the problem you experience is a fatal signal, you should still
9658 say so explicitly. Suppose something strange is going on, such as, your
9659 copy of @command{ld} is out of sync, or you have encountered a bug in the
9660 C library on your system. (This has happened!) Your copy might crash
9661 and ours would not. If you told us to expect a crash, then when ours
9662 fails to crash, we would know that the bug was not happening for us. If
9663 you had not told us to expect a crash, then we would not be able to draw
9664 any conclusion from our observations.
9667 If you wish to suggest changes to the @command{ld} source, send us context
9668 diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
9669 @samp{-p} option. Always send diffs from the old file to the new file.
9670 If you even discuss something in the @command{ld} source, refer to it by
9671 context, not by line number.
9673 The line numbers in our development sources will not match those in your
9674 sources. Your line numbers would convey no useful information to us.
9677 Here are some things that are not necessary:
9681 A description of the envelope of the bug.
9683 Often people who encounter a bug spend a lot of time investigating
9684 which changes to the input file will make the bug go away and which
9685 changes will not affect it.
9687 This is often time consuming and not very useful, because the way we
9688 will find the bug is by running a single example under the debugger
9689 with breakpoints, not by pure deduction from a series of examples.
9690 We recommend that you save your time for something else.
9692 Of course, if you can find a simpler example to report @emph{instead}
9693 of the original one, that is a convenience for us. Errors in the
9694 output will be easier to spot, running under the debugger will take
9695 less time, and so on.
9697 However, simplification is not vital; if you do not want to do this,
9698 report the bug anyway and send us the entire test case you used.
9701 A patch for the bug.
9703 A patch for the bug does help us if it is a good one. But do not omit
9704 the necessary information, such as the test case, on the assumption that
9705 a patch is all we need. We might see problems with your patch and decide
9706 to fix the problem another way, or we might not understand it at all.
9708 Sometimes with a program as complicated as @command{ld} it is very hard to
9709 construct an example that will make the program follow a certain path
9710 through the code. If you do not send us the example, we will not be
9711 able to construct one, so we will not be able to verify that the bug is
9714 And if we cannot understand what bug you are trying to fix, or why your
9715 patch should be an improvement, we will not install it. A test case will
9716 help us to understand.
9719 A guess about what the bug is or what it depends on.
9721 Such guesses are usually wrong. Even we cannot guess right about such
9722 things without first using the debugger to find the facts.
9726 @appendix MRI Compatible Script Files
9727 @cindex MRI compatibility
9728 To aid users making the transition to @sc{gnu} @command{ld} from the MRI
9729 linker, @command{ld} can use MRI compatible linker scripts as an
9730 alternative to the more general-purpose linker scripting language
9731 described in @ref{Scripts}. MRI compatible linker scripts have a much
9732 simpler command set than the scripting language otherwise used with
9733 @command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI
9734 linker commands; these commands are described here.
9736 In general, MRI scripts aren't of much use with the @code{a.out} object
9737 file format, since it only has three sections and MRI scripts lack some
9738 features to make use of them.
9740 You can specify a file containing an MRI-compatible script using the
9741 @samp{-c} command-line option.
9743 Each command in an MRI-compatible script occupies its own line; each
9744 command line starts with the keyword that identifies the command (though
9745 blank lines are also allowed for punctuation). If a line of an
9746 MRI-compatible script begins with an unrecognized keyword, @command{ld}
9747 issues a warning message, but continues processing the script.
9749 Lines beginning with @samp{*} are comments.
9751 You can write these commands using all upper-case letters, or all
9752 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
9753 The following list shows only the upper-case form of each command.
9756 @cindex @code{ABSOLUTE} (MRI)
9757 @item ABSOLUTE @var{secname}
9758 @itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
9759 Normally, @command{ld} includes in the output file all sections from all
9760 the input files. However, in an MRI-compatible script, you can use the
9761 @code{ABSOLUTE} command to restrict the sections that will be present in
9762 your output program. If the @code{ABSOLUTE} command is used at all in a
9763 script, then only the sections named explicitly in @code{ABSOLUTE}
9764 commands will appear in the linker output. You can still use other
9765 input sections (whatever you select on the command line, or using
9766 @code{LOAD}) to resolve addresses in the output file.
9768 @cindex @code{ALIAS} (MRI)
9769 @item ALIAS @var{out-secname}, @var{in-secname}
9770 Use this command to place the data from input section @var{in-secname}
9771 in a section called @var{out-secname} in the linker output file.
9773 @var{in-secname} may be an integer.
9775 @cindex @code{ALIGN} (MRI)
9776 @item ALIGN @var{secname} = @var{expression}
9777 Align the section called @var{secname} to @var{expression}. The
9778 @var{expression} should be a power of two.
9780 @cindex @code{BASE} (MRI)
9781 @item BASE @var{expression}
9782 Use the value of @var{expression} as the lowest address (other than
9783 absolute addresses) in the output file.
9785 @cindex @code{CHIP} (MRI)
9786 @item CHIP @var{expression}
9787 @itemx CHIP @var{expression}, @var{expression}
9788 This command does nothing; it is accepted only for compatibility.
9790 @cindex @code{END} (MRI)
9792 This command does nothing whatever; it's only accepted for compatibility.
9794 @cindex @code{FORMAT} (MRI)
9795 @item FORMAT @var{output-format}
9796 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
9797 language, but restricted to S-records, if @var{output-format} is @samp{S}
9799 @cindex @code{LIST} (MRI)
9800 @item LIST @var{anything}@dots{}
9801 Print (to the standard output file) a link map, as produced by the
9802 @command{ld} command-line option @samp{-M}.
9804 The keyword @code{LIST} may be followed by anything on the
9805 same line, with no change in its effect.
9807 @cindex @code{LOAD} (MRI)
9808 @item LOAD @var{filename}
9809 @itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
9810 Include one or more object file @var{filename} in the link; this has the
9811 same effect as specifying @var{filename} directly on the @command{ld}
9814 @cindex @code{NAME} (MRI)
9815 @item NAME @var{output-name}
9816 @var{output-name} is the name for the program produced by @command{ld}; the
9817 MRI-compatible command @code{NAME} is equivalent to the command-line
9818 option @samp{-o} or the general script language command @code{OUTPUT}.
9820 @cindex @code{ORDER} (MRI)
9821 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
9822 @itemx ORDER @var{secname} @var{secname} @var{secname}
9823 Normally, @command{ld} orders the sections in its output file in the
9824 order in which they first appear in the input files. In an MRI-compatible
9825 script, you can override this ordering with the @code{ORDER} command. The
9826 sections you list with @code{ORDER} will appear first in your output
9827 file, in the order specified.
9829 @cindex @code{PUBLIC} (MRI)
9830 @item PUBLIC @var{name}=@var{expression}
9831 @itemx PUBLIC @var{name},@var{expression}
9832 @itemx PUBLIC @var{name} @var{expression}
9833 Supply a value (@var{expression}) for external symbol
9834 @var{name} used in the linker input files.
9836 @cindex @code{SECT} (MRI)
9837 @item SECT @var{secname}, @var{expression}
9838 @itemx SECT @var{secname}=@var{expression}
9839 @itemx SECT @var{secname} @var{expression}
9840 You can use any of these three forms of the @code{SECT} command to
9841 specify the start address (@var{expression}) for section @var{secname}.
9842 If you have more than one @code{SECT} statement for the same
9843 @var{secname}, only the @emph{first} sets the start address.
9846 @node GNU Free Documentation License
9847 @appendix GNU Free Documentation License
9851 @unnumbered LD Index
9856 % I think something like @@colophon should be in texinfo. In the
9858 \long\def\colophon{\hbox to0pt{}\vfill
9859 \centerline{The body of this manual is set in}
9860 \centerline{\fontname\tenrm,}
9861 \centerline{with headings in {\bf\fontname\tenbf}}
9862 \centerline{and examples in {\tt\fontname\tentt}.}
9863 \centerline{{\it\fontname\tenit\/} and}
9864 \centerline{{\sl\fontname\tensl\/}}
9865 \centerline{are used for emphasis.}\vfill}
9867 % Blame: doc@@cygnus.com, 28mar91.