diff options
Diffstat (limited to 'ld/ld.texi')
| -rw-r--r-- | ld/ld.texi | 8683 |
1 files changed, 8683 insertions, 0 deletions
diff --git a/ld/ld.texi b/ld/ld.texi new file mode 100644 index 0000000..40d79dd --- /dev/null +++ b/ld/ld.texi @@ -0,0 +1,8683 @@ +\input texinfo +@setfilename ld.info +@c Copyright (C) 1991-2018 Free Software Foundation, Inc. +@syncodeindex ky cp +@c man begin INCLUDE +@include configdoc.texi +@c (configdoc.texi is generated by the Makefile) +@include bfdver.texi +@c man end + +@c @smallbook + +@macro gcctabopt{body} +@code{\body\} +@end macro + +@c man begin NAME +@ifset man +@c Configure for the generation of man pages +@set UsesEnvVars +@set GENERIC +@set ARM +@set C6X +@set H8300 +@set HPPA +@set M68HC11 +@set M68K +@set MIPS +@set MMIX +@set MSP430 +@set NDS32 +@set NIOSII +@set POWERPC +@set POWERPC64 +@set Renesas +@set S/390 +@set SPU +@set TICOFF +@set WIN32 +@set XTENSA +@end ifset +@c man end + +@ifnottex +@dircategory Software development +@direntry +* Ld: (ld). The GNU linker. +@end direntry +@end ifnottex + +@copying +This file documents the @sc{gnu} linker LD +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +version @value{VERSION}. + +Copyright @copyright{} 1991-2018 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled ``GNU Free Documentation License''. +@end copying +@iftex +@finalout +@setchapternewpage odd +@settitle The GNU linker +@titlepage +@title The GNU linker +@sp 1 +@subtitle @code{ld} +@ifset VERSION_PACKAGE +@subtitle @value{VERSION_PACKAGE} +@end ifset +@subtitle Version @value{VERSION} +@author Steve Chamberlain +@author Ian Lance Taylor +@page + +@tex +{\parskip=0pt +\hfill Red Hat Inc\par +\hfill nickc\@credhat.com, doc\@redhat.com\par +\hfill {\it The GNU linker}\par +\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par +} +\global\parindent=0pt % Steve likes it this way. +@end tex + +@vskip 0pt plus 1filll +@c man begin COPYRIGHT +Copyright @copyright{} 1991-2018 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled ``GNU Free Documentation License''. +@c man end + +@end titlepage +@end iftex +@contents +@c FIXME: Talk about importance of *order* of args, cmds to linker! + +@ifnottex +@node Top +@top LD +This file documents the @sc{gnu} linker ld +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +version @value{VERSION}. + +This document is distributed under the terms of the GNU Free +Documentation License version 1.3. A copy of the license is included +in the section entitled ``GNU Free Documentation License''. + +@menu +* Overview:: Overview +* Invocation:: Invocation +* Scripts:: Linker Scripts +@ifset GENERIC +* Machine Dependent:: Machine Dependent Features +@end ifset +@ifclear GENERIC +@ifset H8300 +* H8/300:: ld and the H8/300 +@end ifset +@ifset Renesas +* Renesas:: ld and other Renesas micros +@end ifset +@ifset ARM +* ARM:: ld and the ARM family +@end ifset +@ifset M68HC11 +* M68HC11/68HC12:: ld and the Motorola 68HC11 and 68HC12 families +@end ifset +@ifset HPPA +* HPPA ELF32:: ld and HPPA 32-bit ELF +@end ifset +@ifset M68K +* M68K:: ld and Motorola 68K family +@end ifset +@ifset MIPS +* MIPS:: ld and MIPS family +@end ifset +@ifset POWERPC +* PowerPC ELF32:: ld and PowerPC 32-bit ELF Support +@end ifset +@ifset POWERPC64 +* PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support +@end ifset +@ifset S/390 +* S/390 ELF:: ld and S/390 ELF Support +@end ifset +@ifset SPU +* SPU ELF:: ld and SPU ELF Support +@end ifset +@ifset TICOFF +* TI COFF:: ld and the TI COFF +@end ifset +@ifset WIN32 +* Win32:: ld and WIN32 (cygwin/mingw) +@end ifset +@ifset XTENSA +* Xtensa:: ld and Xtensa Processors +@end ifset +@end ifclear +@ifclear SingleFormat +* BFD:: BFD +@end ifclear +@c Following blank line required for remaining bug in makeinfo conds/menus + +* Reporting Bugs:: Reporting Bugs +* MRI:: MRI Compatible Script Files +* GNU Free Documentation License:: GNU Free Documentation License +* LD Index:: LD Index +@end menu +@end ifnottex + +@node Overview +@chapter Overview + +@cindex @sc{gnu} linker +@cindex what is this? + +@ifset man +@c man begin SYNOPSIS +ld [@b{options}] @var{objfile} @dots{} +@c man end + +@c man begin SEEALSO +ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and +the Info entries for @file{binutils} and +@file{ld}. +@c man end +@end ifset + +@c man begin DESCRIPTION + +@command{ld} combines a number of object and archive files, relocates +their data and ties up symbol references. Usually the last step in +compiling a program is to run @command{ld}. + +@command{ld} accepts Linker Command Language files written in +a superset of AT&T's Link Editor Command Language syntax, +to provide explicit and total control over the linking process. + +@ifset man +@c For the man only +This man page does not describe the command language; see the +@command{ld} entry in @code{info} for full details on the command +language and on other aspects of the GNU linker. +@end ifset + +@ifclear SingleFormat +This version of @command{ld} uses the general purpose BFD libraries +to operate on object files. This allows @command{ld} to read, combine, and +write object files in many different formats---for example, COFF or +@code{a.out}. Different formats may be linked together to produce any +available kind of object file. @xref{BFD}, for more information. +@end ifclear + +Aside from its flexibility, the @sc{gnu} linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +@command{ld} continues executing, allowing you to identify other errors +(or, in some cases, to get an output file in spite of the error). + +@c man end + +@node Invocation +@chapter Invocation + +@c man begin DESCRIPTION + +The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations, +and to be as compatible as possible with other linkers. As a result, +you have many choices to control its behavior. + +@c man end + +@ifset UsesEnvVars +@menu +* Options:: Command Line Options +* Environment:: Environment Variables +@end menu + +@node Options +@section Command Line Options +@end ifset + +@cindex command line +@cindex options + +@c man begin OPTIONS + +The linker supports a plethora of command-line options, but in actual +practice few of them are used in any particular context. +@cindex standard Unix system +For instance, a frequent use of @command{ld} is to link standard Unix +object files on a standard, supported Unix system. On such a system, to +link a file @code{hello.o}: + +@smallexample +ld -o @var{output} /lib/crt0.o hello.o -lc +@end smallexample + +This tells @command{ld} to produce a file called @var{output} as the +result of linking the file @code{/lib/crt0.o} with @code{hello.o} and +the library @code{libc.a}, which will come from the standard search +directories. (See the discussion of the @samp{-l} option below.) + +Some of the command-line options to @command{ld} may be specified at any +point in the command line. However, options which refer to files, such +as @samp{-l} or @samp{-T}, cause the file to be read at the point at +which the option appears in the command line, relative to the object +files and other file options. Repeating non-file options with a +different argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of that +option. Options which may be meaningfully specified more than once are +noted in the descriptions below. + +@cindex object files +Non-option arguments are object files or archives which are to be linked +together. They may follow, precede, or be mixed in with command-line +options, except that an object file argument may not be placed between +an option and its argument. + +Usually the linker is invoked with at least one object file, but you can +specify other forms of binary input files using @samp{-l}, @samp{-R}, +and the script command language. If @emph{no} binary input files at all +are specified, the linker does not produce any output, and issues the +message @samp{No input files}. + +If the linker cannot recognize the format of an object file, it will +assume that it is a linker script. A script specified in this way +augments the main linker script used for the link (either the default +linker script or the one specified by using @samp{-T}). This feature +permits the linker to link against a file which appears to be an object +or an archive, but actually merely defines some symbol values, or uses +@code{INPUT} or @code{GROUP} to load other objects. Specifying a +script in this way merely augments the main linker script, with the +extra commands placed after the main script; use the @samp{-T} option +to replace the default linker script entirely, but note the effect of +the @code{INSERT} command. @xref{Scripts}. + +For options whose names are a single letter, +option arguments must either follow the option letter without intervening +whitespace, or be given as separate arguments immediately following the +option that requires them. + +For options whose names are multiple letters, either one dash or two can +precede the option name; for example, @samp{-trace-symbol} and +@samp{--trace-symbol} are equivalent. Note---there is one exception to +this rule. Multiple letter options that start with a lower case 'o' can +only be preceded by two dashes. This is to reduce confusion with the +@samp{-o} option. So for example @samp{-omagic} sets the output file +name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the +output. + +Arguments to multiple-letter options must either be separated from the +option name by an equals sign, or be given as separate arguments +immediately following the option that requires them. For example, +@samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent. +Unique abbreviations of the names of multiple-letter options are +accepted. + +Note---if the linker is being invoked indirectly, via a compiler driver +(e.g. @samp{gcc}) then all the linker command line options should be +prefixed by @samp{-Wl,} (or whatever is appropriate for the particular +compiler driver) like this: + +@smallexample + gcc -Wl,--start-group foo.o bar.o -Wl,--end-group +@end smallexample + +This is important, because otherwise the compiler driver program may +silently drop the linker options, resulting in a bad link. Confusion +may also arise when passing options that require values through a +driver, as the use of a space between option and argument acts as +a separator, and causes the driver to pass only the option to the linker +and the argument to the compiler. In this case, it is simplest to use +the joined forms of both single- and multiple-letter options, such as: + +@smallexample + gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map +@end smallexample + +Here is a table of the generic command line switches accepted by the GNU +linker: + +@table @gcctabopt +@include at-file.texi + +@kindex -a @var{keyword} +@item -a @var{keyword} +This option is supported for HP/UX compatibility. The @var{keyword} +argument must be one of the strings @samp{archive}, @samp{shared}, or +@samp{default}. @samp{-aarchive} is functionally equivalent to +@samp{-Bstatic}, and the other two keywords are functionally equivalent +to @samp{-Bdynamic}. This option may be used any number of times. + +@kindex --audit @var{AUDITLIB} +@item --audit @var{AUDITLIB} +Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section. +@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME +specified in the library. If specified multiple times @code{DT_AUDIT} +will contain a colon separated list of audit interfaces to use. If the linker +finds an object with an audit entry while searching for shared libraries, +it will add a corresponding @code{DT_DEPAUDIT} entry in the output file. +This option is only meaningful on ELF platforms supporting the rtld-audit +interface. + +@ifclear SingleFormat +@cindex binary input format +@kindex -b @var{format} +@kindex --format=@var{format} +@cindex input format +@cindex input format +@item -b @var{input-format} +@itemx --format=@var{input-format} +@command{ld} may be configured to support more than one kind of object +file. If your @command{ld} is configured this way, you can use the +@samp{-b} option to specify the binary format for input object files +that follow this option on the command line. Even when @command{ld} is +configured to support alternative object formats, you don't usually need +to specify this, as @command{ld} should be configured to expect as a +default input format the most usual format on each machine. +@var{input-format} is a text string, the name of a particular format +supported by the BFD libraries. (You can list the available binary +formats with @samp{objdump -i}.) +@xref{BFD}. + +You may want to use this option if you are linking files with an unusual +binary format. You can also use @samp{-b} to switch formats explicitly (when +linking object files of different formats), by including +@samp{-b @var{input-format}} before each group of object files in a +particular format. + +The default format is taken from the environment variable +@code{GNUTARGET}. +@ifset UsesEnvVars +@xref{Environment}. +@end ifset +You can also define the input format from a script, using the command +@code{TARGET}; +@ifclear man +see @ref{Format Commands}. +@end ifclear +@end ifclear + +@kindex -c @var{MRI-cmdfile} +@kindex --mri-script=@var{MRI-cmdfile} +@cindex compatibility, MRI +@item -c @var{MRI-commandfile} +@itemx --mri-script=@var{MRI-commandfile} +For compatibility with linkers produced by MRI, @command{ld} accepts script +files written in an alternate, restricted command language, described in +@ifclear man +@ref{MRI,,MRI Compatible Script Files}. +@end ifclear +@ifset man +the MRI Compatible Script Files section of GNU ld documentation. +@end ifset +Introduce MRI script files with +the option @samp{-c}; use the @samp{-T} option to run linker +scripts written in the general-purpose @command{ld} scripting language. +If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories +specified by any @samp{-L} options. + +@cindex common allocation +@kindex -d +@kindex -dc +@kindex -dp +@item -d +@itemx -dc +@itemx -dp +These three options are equivalent; multiple forms are supported for +compatibility with other linkers. They assign space to common symbols +even if a relocatable output file is specified (with @samp{-r}). The +script command @code{FORCE_COMMON_ALLOCATION} has the same effect. +@xref{Miscellaneous Commands}. + +@kindex --depaudit @var{AUDITLIB} +@kindex -P @var{AUDITLIB} +@item --depaudit @var{AUDITLIB} +@itemx -P @var{AUDITLIB} +Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section. +@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME +specified in the library. If specified multiple times @code{DT_DEPAUDIT} +will contain a colon separated list of audit interfaces to use. This +option is only meaningful on ELF platforms supporting the rtld-audit interface. +The -P option is provided for Solaris compatibility. + +@cindex entry point, from command line +@kindex -e @var{entry} +@kindex --entry=@var{entry} +@item -e @var{entry} +@itemx --entry=@var{entry} +Use @var{entry} as the explicit symbol for beginning execution of your +program, rather than the default entry point. If there is no symbol +named @var{entry}, the linker will try to parse @var{entry} as a number, +and use that as the entry address (the number will be interpreted in +base 10; you may use a leading @samp{0x} for base 16, or a leading +@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults +and other ways of specifying the entry point. + +@kindex --exclude-libs +@item --exclude-libs @var{lib},@var{lib},... +Specifies a list of archive libraries from which symbols should not be automatically +exported. The library names may be delimited by commas or colons. Specifying +@code{--exclude-libs ALL} excludes symbols in all archive libraries from +automatic export. This option is available only for the i386 PE targeted +port of the linker and for ELF targeted ports. For i386 PE, symbols +explicitly listed in a .def file are still exported, regardless of this +option. For ELF targeted ports, symbols affected by this option will +be treated as hidden. + +@kindex --exclude-modules-for-implib +@item --exclude-modules-for-implib @var{module},@var{module},... +Specifies a list of object files or archive members, from which symbols +should not be automatically exported, but which should be copied wholesale +into the import library being generated during the link. The module names +may be delimited by commas or colons, and must match exactly the filenames +used by @command{ld} to open the files; for archive members, this is simply +the member name, but for object files the name listed must include and +match precisely any path used to specify the input file on the linker's +command-line. This option is available only for the i386 PE targeted port +of the linker. Symbols explicitly listed in a .def file are still exported, +regardless of this option. + +@cindex dynamic symbol table +@kindex -E +@kindex --export-dynamic +@kindex --no-export-dynamic +@item -E +@itemx --export-dynamic +@itemx --no-export-dynamic +When creating a dynamically linked executable, using the @option{-E} +option or the @option{--export-dynamic} option causes the linker to add +all symbols to the dynamic symbol table. The dynamic symbol table is the +set of symbols which are visible from dynamic objects at run time. + +If you do not use either of these options (or use the +@option{--no-export-dynamic} option to restore the default behavior), the +dynamic symbol table will normally contain only those symbols which are +referenced by some dynamic object mentioned in the link. + +If you use @code{dlopen} to load a dynamic object which needs to refer +back to the symbols defined by the program, rather than some other +dynamic object, then you will probably need to use this option when +linking the program itself. + +You can also use the dynamic list to control what symbols should +be added to the dynamic symbol table if the output format supports it. +See the description of @samp{--dynamic-list}. + +Note that this option is specific to ELF targeted ports. PE targets +support a similar function to export all symbols from a DLL or EXE; see +the description of @samp{--export-all-symbols} below. + +@ifclear SingleFormat +@cindex big-endian objects +@cindex endianness +@kindex -EB +@item -EB +Link big-endian objects. This affects the default output format. + +@cindex little-endian objects +@kindex -EL +@item -EL +Link little-endian objects. This affects the default output format. +@end ifclear + +@kindex -f @var{name} +@kindex --auxiliary=@var{name} +@item -f @var{name} +@itemx --auxiliary=@var{name} +When creating an ELF shared object, set the internal DT_AUXILIARY field +to the specified name. This tells the dynamic linker that the symbol +table of the shared object should be used as an auxiliary filter on the +symbol table of the shared object @var{name}. + +If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the DT_AUXILIARY field. If +the dynamic linker resolves any symbols from the filter object, it will +first check whether there is a definition in the shared object +@var{name}. If there is one, it will be used instead of the definition +in the filter object. The shared object @var{name} need not exist. +Thus the shared object @var{name} may be used to provide an alternative +implementation of certain functions, perhaps for debugging or for +machine specific performance. + +This option may be specified more than once. The DT_AUXILIARY entries +will be created in the order in which they appear on the command line. + +@kindex -F @var{name} +@kindex --filter=@var{name} +@item -F @var{name} +@itemx --filter=@var{name} +When creating an ELF shared object, set the internal DT_FILTER field to +the specified name. This tells the dynamic linker that the symbol table +of the shared object which is being created should be used as a filter +on the symbol table of the shared object @var{name}. + +If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the DT_FILTER field. The +dynamic linker will resolve symbols according to the symbol table of the +filter object as usual, but it will actually link to the definitions +found in the shared object @var{name}. Thus the filter object can be +used to select a subset of the symbols provided by the object +@var{name}. + +Some older linkers used the @option{-F} option throughout a compilation +toolchain for specifying object-file format for both input and output +object files. +@ifclear SingleFormat +The @sc{gnu} linker uses other mechanisms for this purpose: the +@option{-b}, @option{--format}, @option{--oformat} options, the +@code{TARGET} command in linker scripts, and the @code{GNUTARGET} +environment variable. +@end ifclear +The @sc{gnu} linker will ignore the @option{-F} option when not +creating an ELF shared object. + +@cindex finalization function +@kindex -fini=@var{name} +@item -fini=@var{name} +When creating an ELF executable or shared object, call NAME when the +executable or shared object is unloaded, by setting DT_FINI to the +address of the function. By default, the linker uses @code{_fini} as +the function to call. + +@kindex -g +@item -g +Ignored. Provided for compatibility with other tools. + +@kindex -G @var{value} +@kindex --gpsize=@var{value} +@cindex object size +@item -G @var{value} +@itemx --gpsize=@var{value} +Set the maximum size of objects to be optimized using the GP register to +@var{size}. This is only meaningful for object file formats such as +MIPS ELF that support putting large and small objects into different +sections. This is ignored for other object file formats. + +@cindex runtime library name +@kindex -h @var{name} +@kindex -soname=@var{name} +@item -h @var{name} +@itemx -soname=@var{name} +When creating an ELF shared object, set the internal DT_SONAME field to +the specified name. When an executable is linked with a shared object +which has a DT_SONAME field, then when the executable is run the dynamic +linker will attempt to load the shared object specified by the DT_SONAME +field rather than the using the file name given to the linker. + +@kindex -i +@cindex incremental link +@item -i +Perform an incremental link (same as option @samp{-r}). + +@cindex initialization function +@kindex -init=@var{name} +@item -init=@var{name} +When creating an ELF executable or shared object, call NAME when the +executable or shared object is loaded, by setting DT_INIT to the address +of the function. By default, the linker uses @code{_init} as the +function to call. + +@cindex archive files, from cmd line +@kindex -l @var{namespec} +@kindex --library=@var{namespec} +@item -l @var{namespec} +@itemx --library=@var{namespec} +Add the archive or object file specified by @var{namespec} to the +list of files to link. This option may be used any number of times. +If @var{namespec} is of the form @file{:@var{filename}}, @command{ld} +will search the library path for a file called @var{filename}, otherwise it +will search the library path for a file called @file{lib@var{namespec}.a}. + +On systems which support shared libraries, @command{ld} may also search for +files other than @file{lib@var{namespec}.a}. Specifically, on ELF +and SunOS systems, @command{ld} will search a directory for a library +called @file{lib@var{namespec}.so} before searching for one called +@file{lib@var{namespec}.a}. (By convention, a @code{.so} extension +indicates a shared library.) Note that this behavior does not apply +to @file{:@var{filename}}, which always specifies a file called +@var{filename}. + +The linker will search an archive only once, at the location where it is +specified on the command line. If the archive defines a symbol which +was undefined in some object which appeared before the archive on the +command line, the linker will include the appropriate file(s) from the +archive. However, an undefined symbol in an object appearing later on +the command line will not cause the linker to search the archive again. + +See the @option{-(} option for a way to force the linker to search +archives multiple times. + +You may list the same archive multiple times on the command line. + +@ifset GENERIC +This type of archive searching is standard for Unix linkers. However, +if you are using @command{ld} on AIX, note that it is different from the +behaviour of the AIX linker. +@end ifset + +@cindex search directory, from cmd line +@kindex -L @var{dir} +@kindex --library-path=@var{dir} +@item -L @var{searchdir} +@itemx --library-path=@var{searchdir} +Add path @var{searchdir} to the list of paths that @command{ld} will search +for archive libraries and @command{ld} control scripts. You may use this +option any number of times. The directories are searched in the order +in which they are specified on the command line. Directories specified +on the command line are searched before the default directories. All +@option{-L} options apply to all @option{-l} options, regardless of the +order in which the options appear. @option{-L} options do not affect +how @command{ld} searches for a linker script unless @option{-T} +option is specified. + +If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this +prefix will be replaced by the @dfn{sysroot prefix}, controlled by the +@samp{--sysroot} option, or specified when the linker is configured. + +@ifset UsesEnvVars +The default set of paths searched (without being specified with +@samp{-L}) depends on which emulation mode @command{ld} is using, and in +some cases also on how it was configured. @xref{Environment}. +@end ifset + +The paths can also be specified in a link script with the +@code{SEARCH_DIR} command. Directories specified this way are searched +at the point in which the linker script appears in the command line. + +@cindex emulation +@kindex -m @var{emulation} +@item -m @var{emulation} +Emulate the @var{emulation} linker. You can list the available +emulations with the @samp{--verbose} or @samp{-V} options. + +If the @samp{-m} option is not used, the emulation is taken from the +@code{LDEMULATION} environment variable, if that is defined. + +Otherwise, the default emulation depends upon how the linker was +configured. + +@cindex link map +@kindex -M +@kindex --print-map +@item -M +@itemx --print-map +Print a link map to the standard output. A link map provides +information about the link, including the following: + +@itemize @bullet +@item +Where object files are mapped into memory. +@item +How common symbols are allocated. +@item +All archive members included in the link, with a mention of the symbol +which caused the archive member to be brought in. +@item +The values assigned to symbols. + +Note - symbols whose values are computed by an expression which +involves a reference to a previous value of the same symbol may not +have correct result displayed in the link map. This is because the +linker discards intermediate results and only retains the final value +of an expression. Under such circumstances the linker will display +the final value enclosed by square brackets. Thus for example a +linker script containing: + +@smallexample + foo = 1 + foo = foo * 4 + foo = foo + 8 +@end smallexample + +will produce the following output in the link map if the @option{-M} +option is used: + +@smallexample + 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) +@end smallexample + +See @ref{Expressions} for more information about expressions in linker +scripts. +@end itemize + +@kindex -n +@cindex read-only text +@cindex NMAGIC +@kindex --nmagic +@item -n +@itemx --nmagic +Turn off page alignment of sections, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as @code{NMAGIC}. + +@kindex -N +@kindex --omagic +@cindex read/write from cmd line +@cindex OMAGIC +@item -N +@itemx --omagic +Set the text and data sections to be readable and writable. Also, do +not page-align the data segment, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as @code{OMAGIC}. Note: Although a writable text section +is allowed for PE-COFF targets, it does not conform to the format +specification published by Microsoft. + +@kindex --no-omagic +@cindex OMAGIC +@item --no-omagic +This option negates most of the effects of the @option{-N} option. It +sets the text section to be read-only, and forces the data segment to +be page-aligned. Note - this option does not enable linking against +shared libraries. Use @option{-Bdynamic} for this. + +@kindex -o @var{output} +@kindex --output=@var{output} +@cindex naming the output file +@item -o @var{output} +@itemx --output=@var{output} +Use @var{output} as the name for the program produced by @command{ld}; if this +option is not specified, the name @file{a.out} is used by default. The +script command @code{OUTPUT} can also specify the output file name. + +@kindex -O @var{level} +@cindex generating optimized output +@item -O @var{level} +If @var{level} is a numeric values greater than zero @command{ld} optimizes +the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. At the moment this +option only affects ELF shared library generation. Future releases of +the linker may make more use of this option. Also currently there is +no difference in the linker's behaviour for different non-zero values +of this option. Again this may change with future releases. + +@kindex -plugin @var{name} +@item -plugin @var{name} +Involve a plugin in the linking process. The @var{name} parameter is +the absolute filename of the plugin. Usually this parameter is +automatically added by the complier, when using link time +optimization, but users can also add their own plugins if they so +wish. + +Note that the location of the compiler originated plugins is different +from the place where the @command{ar}, @command{nm} and +@command{ranlib} programs search for their plugins. In order for +those commands to make use of a compiler based plugin it must first be +copied into the @file{$@{libdir@}/bfd-plugins} directory. All gcc +based linker plugins are backward compatible, so it is sufficient to +just copy in the newest one. + +@kindex --push-state +@cindex push state governing input file handling +@item --push-state +The @option{--push-state} allows to preserve the current state of the +flags which govern the input file handling so that they can all be +restored with one corresponding @option{--pop-state} option. + +The option which are covered are: @option{-Bdynamic}, @option{-Bstatic}, +@option{-dn}, @option{-dy}, @option{-call_shared}, @option{-non_shared}, +@option{-static}, @option{-N}, @option{-n}, @option{--whole-archive}, +@option{--no-whole-archive}, @option{-r}, @option{-Ur}, +@option{--copy-dt-needed-entries}, @option{--no-copy-dt-needed-entries}, +@option{--as-needed}, @option{--no-as-needed}, and @option{-a}. + +One target for this option are specifications for @file{pkg-config}. When +used with the @option{--libs} option all possibly needed libraries are +listed and then possibly linked with all the time. It is better to return +something as follows: + +@smallexample +-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state +@end smallexample + +@kindex --pop-state +@cindex pop state governing input file handling +@item --pop-state +Undoes the effect of --push-state, restores the previous values of the +flags governing input file handling. + +@kindex -q +@kindex --emit-relocs +@cindex retain relocations in final executable +@item -q +@itemx --emit-relocs +Leave relocation sections and contents in fully linked executables. +Post link analysis and optimization tools may need this information in +order to perform correct modifications of executables. This results +in larger executables. + +This option is currently only supported on ELF platforms. + +@kindex --force-dynamic +@cindex forcing the creation of dynamic sections +@item --force-dynamic +Force the output file to have dynamic sections. This option is specific +to VxWorks targets. + +@cindex partial link +@cindex relocatable output +@kindex -r +@kindex --relocatable +@item -r +@itemx --relocatable +Generate relocatable output---i.e., generate an output file that can in +turn serve as input to @command{ld}. This is often called @dfn{partial +linking}. As a side effect, in environments that support standard Unix +magic numbers, this option also sets the output file's magic number to +@code{OMAGIC}. +@c ; see @option{-N}. +If this option is not specified, an absolute file is produced. When +linking C++ programs, this option @emph{will not} resolve references to +constructors; to do that, use @samp{-Ur}. + +When an input file does not have the same format as the output file, +partial linking is only supported if that input file does not contain any +relocations. Different output formats can have further restrictions; for +example some @code{a.out}-based formats do not support partial linking +with input files in other formats at all. + +This option does the same thing as @samp{-i}. + +@kindex -R @var{file} +@kindex --just-symbols=@var{file} +@cindex symbol-only input +@item -R @var{filename} +@itemx --just-symbols=@var{filename} +Read symbol names and their addresses from @var{filename}, but do not +relocate it or include it in the output. This allows your output file +to refer symbolically to absolute locations of memory defined in other +programs. You may use this option more than once. + +For compatibility with other ELF linkers, if the @option{-R} option is +followed by a directory name, rather than a file name, it is treated as +the @option{-rpath} option. + +@kindex -s +@kindex --strip-all +@cindex strip all symbols +@item -s +@itemx --strip-all +Omit all symbol information from the output file. + +@kindex -S +@kindex --strip-debug +@cindex strip debugger symbols +@item -S +@itemx --strip-debug +Omit debugger symbol information (but not all symbols) from the output file. + +@kindex --strip-discarded +@kindex --no-strip-discarded +@item --strip-discarded +@itemx --no-strip-discarded +Omit (or do not omit) global symbols defined in discarded sections. +Enabled by default. + +@kindex -t +@kindex --trace +@cindex input files, displaying +@item -t +@itemx --trace +Print the names of the input files as @command{ld} processes them. + +@kindex -T @var{script} +@kindex --script=@var{script} +@cindex script files +@item -T @var{scriptfile} +@itemx --script=@var{scriptfile} +Use @var{scriptfile} as the linker script. This script replaces +@command{ld}'s default linker script (rather than adding to it), so +@var{commandfile} must specify everything necessary to describe the +output file. @xref{Scripts}. If @var{scriptfile} does not exist in +the current directory, @code{ld} looks for it in the directories +specified by any preceding @samp{-L} options. Multiple @samp{-T} +options accumulate. + +@kindex -dT @var{script} +@kindex --default-script=@var{script} +@cindex script files +@item -dT @var{scriptfile} +@itemx --default-script=@var{scriptfile} +Use @var{scriptfile} as the default linker script. @xref{Scripts}. + +This option is similar to the @option{--script} option except that +processing of the script is delayed until after the rest of the +command line has been processed. This allows options placed after the +@option{--default-script} option on the command line to affect the +behaviour of the linker script, which can be important when the linker +command line cannot be directly controlled by the user. (eg because +the command line is being constructed by another tool, such as +@samp{gcc}). + +@kindex -u @var{symbol} +@kindex --undefined=@var{symbol} +@cindex undefined symbol +@item -u @var{symbol} +@itemx --undefined=@var{symbol} +Force @var{symbol} to be entered in the output file as an undefined +symbol. Doing this may, for example, trigger linking of additional +modules from standard libraries. @samp{-u} may be repeated with +different option arguments to enter additional undefined symbols. This +option is equivalent to the @code{EXTERN} linker script command. + +If this option is being used to force additional modules to be pulled +into the link, and if it is an error for the symbol to remain +undefined, then the option @option{--require-defined} should be used +instead. + +@kindex --require-defined=@var{symbol} +@cindex symbols, require defined +@cindex defined symbol +@item --require-defined=@var{symbol} +Require that @var{symbol} is defined in the output file. This option +is the same as option @option{--undefined} except that if @var{symbol} +is not defined in the output file then the linker will issue an error +and exit. The same effect can be achieved in a linker script by using +@code{EXTERN}, @code{ASSERT} and @code{DEFINED} together. This option +can be used multiple times to require additional symbols. + +@kindex -Ur +@cindex constructors +@item -Ur +For anything other than C++ programs, this option is equivalent to +@samp{-r}: it generates relocatable output---i.e., an output file that can in +turn serve as input to @command{ld}. When linking C++ programs, @samp{-Ur} +@emph{does} resolve references to constructors, unlike @samp{-r}. +It does not work to use @samp{-Ur} on files that were themselves linked +with @samp{-Ur}; once the constructor table has been built, it cannot +be added to. Use @samp{-Ur} only for the last partial link, and +@samp{-r} for the others. + +@kindex --orphan-handling=@var{MODE} +@cindex orphan sections +@cindex sections, orphan +@item --orphan-handling=@var{MODE} +Control how orphan sections are handled. An orphan section is one not +specifically mentioned in a linker script. @xref{Orphan Sections}. + +@var{MODE} can have any of the following values: + +@table @code +@item place +Orphan sections are placed into a suitable output section following +the strategy described in @ref{Orphan Sections}. The option +@samp{--unique} also affects how sections are placed. + +@item discard +All orphan sections are discarded, by placing them in the +@samp{/DISCARD/} section (@pxref{Output Section Discarding}). + +@item warn +The linker will place the orphan section as for @code{place} and also +issue a warning. + +@item error +The linker will exit with an error if any orphan section is found. +@end table + +The default if @samp{--orphan-handling} is not given is @code{place}. + +@kindex --unique[=@var{SECTION}] +@item --unique[=@var{SECTION}] +Creates a separate output section for every input section matching +@var{SECTION}, or if the optional wildcard @var{SECTION} argument is +missing, for every orphan input section. An orphan section is one not +specifically mentioned in a linker script. You may use this option +multiple times on the command line; It prevents the normal merging of +input sections with the same name, overriding output section assignments +in a linker script. + +@kindex -v +@kindex -V +@kindex --version +@cindex version +@item -v +@itemx --version +@itemx -V +Display the version number for @command{ld}. The @option{-V} option also +lists the supported emulations. + +@kindex -x +@kindex --discard-all +@cindex deleting local symbols +@item -x +@itemx --discard-all +Delete all local symbols. + +@kindex -X +@kindex --discard-locals +@cindex local symbols, deleting +@item -X +@itemx --discard-locals +Delete all temporary local symbols. (These symbols start with +system-specific local label prefixes, typically @samp{.L} for ELF systems +or @samp{L} for traditional a.out systems.) + +@kindex -y @var{symbol} +@kindex --trace-symbol=@var{symbol} +@cindex symbol tracing +@item -y @var{symbol} +@itemx --trace-symbol=@var{symbol} +Print the name of each linked file in which @var{symbol} appears. This +option may be given any number of times. On many systems it is necessary +to prepend an underscore. + +This option is useful when you have an undefined symbol in your link but +don't know where the reference is coming from. + +@kindex -Y @var{path} +@item -Y @var{path} +Add @var{path} to the default library search path. This option exists +for Solaris compatibility. + +@kindex -z @var{keyword} +@item -z @var{keyword} +The recognized keywords are: +@table @samp + +@item bndplt +Always generate BND prefix in PLT entries. Supported for Linux/x86_64. + +@item call-nop=prefix-addr +@itemx call-nop=suffix-nop +@itemx call-nop=prefix-@var{byte} +@itemx call-nop=suffix-@var{byte} +Specify the 1-byte @code{NOP} padding when transforming indirect call +to a locally defined function, foo, via its GOT slot. +@option{call-nop=prefix-addr} generates @code{0x67 call foo}. +@option{call-nop=suffix-nop} generates @code{call foo 0x90}. +@option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}. +@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}. +Supported for i386 and x86_64. + +@item combreloc +@itemx nocombreloc +Combine multiple dynamic relocation sections and sort to improve +dynamic symbol lookup caching. Do not do this if @samp{nocombreloc}. + +@item common +@itemx nocommon +Generate common symbols with STT_COMMON type during a relocatable +link. Use STT_OBJECT type if @samp{nocommon}. + +@item common-page-size=@var{value} +Set the page size most commonly used to @var{value}. Memory image +layout will be optimized to minimize memory pages if the system is +using pages of this size. + +@item defs +Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +This option is the inverse of @samp{-z undefs}. + +@item dynamic-undefined-weak +@itemx nodynamic-undefined-weak +Make undefined weak symbols dynamic when building a dynamic object, +if they are referenced from a regular object file and not forced local +by symbol visibility or versioning. Do not make them dynamic if +@samp{nodynamic-undefined-weak}. If neither option is given, a target +may default to either option being in force, or make some other +selection of undefined weak symbols dynamic. Not all targets support +these options. + +@item execstack +Marks the object as requiring executable stack. + +@item global +This option is only meaningful when building a shared object. It makes +the symbols defined by this shared object available for symbol resolution +of subsequently loaded libraries. + +@item globalaudit +This option is only meaningful when building a dynamic executable. +This option marks the executable as requiring global auditing by +setting the @code{DF_1_GLOBAUDIT} bit in the @code{DT_FLAGS_1} dynamic +tag. Global auditing requires that any auditing library defined via +the @option{--depaudit} or @option{-P} command line options be run for +all dynamic objects loaded by the application. + +@item ibtplt +Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries. +Supported for Linux/i386 and Linux/x86_64. + +@item ibt +Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section +to indicate compatibility with IBT. This also implies @option{ibtplt}. +Supported for Linux/i386 and Linux/x86_64. + +@item initfirst +This option is only meaningful when building a shared object. +It marks the object so that its runtime initialization will occur +before the runtime initialization of any other objects brought into +the process at the same time. Similarly the runtime finalization of +the object will occur after the runtime finalization of any other +objects. + +@item interpose +Specify that the dynamic loader should modify its symbol search order +so that symbols in this shared library interpose all other shared +libraries not so marked. + +@item lazy +When generating an executable or shared library, mark it to tell the +dynamic linker to defer function call resolution to the point when +the function is called (lazy binding), rather than at load time. +Lazy binding is the default. + +@item loadfltr +Specify that the object's filters be processed immediately at runtime. + +@item max-page-size=@var{value} +Set the maximum memory page size supported to @var{value}. + +@item muldefs +Allow multiple definitions. + +@item nocopyreloc +Disable linker generated .dynbss variables used in place of variables +defined in shared libraries. May result in dynamic text relocations. + +@item nodefaultlib +Specify that the dynamic loader search for dependencies of this object +should ignore any default library search paths. + +@item nodelete +Specify that the object shouldn't be unloaded at runtime. + +@item nodlopen +Specify that the object is not available to @code{dlopen}. + +@item nodump +Specify that the object can not be dumped by @code{dldump}. + +@item noexecstack +Marks the object as not requiring executable stack. + +@item noextern-protected-data +Don't treat protected data symbols as external when building a shared +library. This option overrides the linker backend default. It can be +used to work around incorrect relocations against protected data symbols +generated by compiler. Updates on protected data symbols by another +module aren't visible to the resulting shared library. Supported for +i386 and x86-64. + +@item noreloc-overflow +Disable relocation overflow check. This can be used to disable +relocation overflow check if there will be no dynamic relocation +overflow at run-time. Supported for x86_64. + +@item now +When generating an executable or shared library, mark it to tell the +dynamic linker to resolve all symbols when the program is started, or +when the shared library is loaded by dlopen, instead of deferring +function call resolution to the point when the function is first +called. + +@item origin +Specify that the object requires @samp{$ORIGIN} handling in paths. + +@item relro +@itemx norelro +Create an ELF @code{PT_GNU_RELRO} segment header in the object. This +specifies a memory segment that should be made read-only after +relocation, if supported. Specifying @samp{common-page-size} smaller +than the system page size will render this protection ineffective. +Don't create an ELF @code{PT_GNU_RELRO} segment if @samp{norelro}. + +@item separate-code +@itemx noseparate-code +Create separate code @code{PT_LOAD} segment header in the object. This +specifies a memory segment that should contain only instructions and must +be in wholly disjoint pages from any other data. Don't create separate +code @code{PT_LOAD} segment if @samp{noseparate-code} is used. + +@item shstk +Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section +to indicate compatibility with Intel Shadow Stack. Supported for +Linux/i386 and Linux/x86_64. + +@item stack-size=@var{value} +Specify a stack size for an ELF @code{PT_GNU_STACK} segment. +Specifying zero will override any default non-zero sized +@code{PT_GNU_STACK} segment creation. + +@item text +@itemx notext +@itemx textoff +Report an error if DT_TEXTREL is set, i.e., if the binary has dynamic +relocations in read-only sections. Don't report an error if +@samp{notext} or @samp{textoff}. + +@item undefs +Do not report unresolved symbol references from regular object files, +either when creating an executable, or when creating a shared library. +This option is the inverse of @samp{-z defs}. + +@end table + +Other keywords are ignored for Solaris compatibility. + +@kindex -( +@cindex groups of archives +@item -( @var{archives} -) +@itemx --start-group @var{archives} --end-group +The @var{archives} should be a list of archive files. They may be +either explicit file names, or @samp{-l} options. + +The specified archives are searched repeatedly until no new undefined +references are created. Normally, an archive is searched only once in +the order that it is specified on the command line. If a symbol in that +archive is needed to resolve an undefined symbol referred to by an +object in an archive that appears later on the command line, the linker +would not be able to resolve that reference. By grouping the archives, +they all be searched repeatedly until all possible references are +resolved. + +Using this option has a significant performance cost. It is best to use +it only when there are unavoidable circular references between two or +more archives. + +@kindex --accept-unknown-input-arch +@kindex --no-accept-unknown-input-arch +@item --accept-unknown-input-arch +@itemx --no-accept-unknown-input-arch +Tells the linker to accept input files whose architecture cannot be +recognised. The assumption is that the user knows what they are doing +and deliberately wants to link in these unknown input files. This was +the default behaviour of the linker, before release 2.14. The default +behaviour from release 2.14 onwards is to reject such input files, and +so the @samp{--accept-unknown-input-arch} option has been added to +restore the old behaviour. + +@kindex --as-needed +@kindex --no-as-needed +@item --as-needed +@itemx --no-as-needed +This option affects ELF DT_NEEDED tags for dynamic libraries mentioned +on the command line after the @option{--as-needed} option. Normally +the linker will add a DT_NEEDED tag for each dynamic library mentioned +on the command line, regardless of whether the library is actually +needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be +emitted for a library that @emph{at that point in the link} satisfies a +non-weak undefined symbol reference from a regular object file or, if +the library is not found in the DT_NEEDED lists of other needed libraries, a +non-weak undefined symbol reference from another needed dynamic library. +Object files or libraries appearing on the command line @emph{after} +the library in question do not affect whether the library is seen as +needed. This is similar to the rules for extraction of object files +from archives. @option{--no-as-needed} restores the default behaviour. + +@kindex --add-needed +@kindex --no-add-needed +@item --add-needed +@itemx --no-add-needed +These two options have been deprecated because of the similarity of +their names to the @option{--as-needed} and @option{--no-as-needed} +options. They have been replaced by @option{--copy-dt-needed-entries} +and @option{--no-copy-dt-needed-entries}. + +@kindex -assert @var{keyword} +@item -assert @var{keyword} +This option is ignored for SunOS compatibility. + +@kindex -Bdynamic +@kindex -dy +@kindex -call_shared +@item -Bdynamic +@itemx -dy +@itemx -call_shared +Link against dynamic libraries. This is only meaningful on platforms +for which shared libraries are supported. This option is normally the +default on such platforms. The different variants of this option are +for compatibility with various systems. You may use this option +multiple times on the command line: it affects library searching for +@option{-l} options which follow it. + +@kindex -Bgroup +@item -Bgroup +Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic +section. This causes the runtime linker to handle lookups in this +object and its dependencies to be performed only inside the group. +@option{--unresolved-symbols=report-all} is implied. This option is +only meaningful on ELF platforms which support shared libraries. + +@kindex -Bstatic +@kindex -dn +@kindex -non_shared +@kindex -static +@item -Bstatic +@itemx -dn +@itemx -non_shared +@itemx -static +Do not link against shared libraries. This is only meaningful on +platforms for which shared libraries are supported. The different +variants of this option are for compatibility with various systems. You +may use this option multiple times on the command line: it affects +library searching for @option{-l} options which follow it. This +option also implies @option{--unresolved-symbols=report-all}. This +option can be used with @option{-shared}. Doing so means that a +shared library is being created but that all of the library's external +references must be resolved by pulling in entries from static +libraries. + +@kindex -Bsymbolic +@item -Bsymbolic +When creating a shared library, bind references to global symbols to the +definition within the shared library, if any. Normally, it is possible +for a program linked against a shared library to override the definition +within the shared library. This option can also be used with the +@option{--export-dynamic} option, when creating a position independent +executable, to bind references to global symbols to the definition within +the executable. This option is only meaningful on ELF platforms which +support shared libraries and position independent executables. + +@kindex -Bsymbolic-functions +@item -Bsymbolic-functions +When creating a shared library, bind references to global function +symbols to the definition within the shared library, if any. +This option can also be used with the @option{--export-dynamic} option, +when creating a position independent executable, to bind references +to global function symbols to the definition within the executable. +This option is only meaningful on ELF platforms which support shared +libraries and position independent executables. + +@kindex --dynamic-list=@var{dynamic-list-file} +@item --dynamic-list=@var{dynamic-list-file} +Specify the name of a dynamic list file to the linker. This is +typically used when creating shared libraries to specify a list of +global symbols whose references shouldn't be bound to the definition +within the shared library, or creating dynamically linked executables +to specify a list of symbols which should be added to the symbol table +in the executable. This option is only meaningful on ELF platforms +which support shared libraries. + +The format of the dynamic list is the same as the version node without +scope and node name. See @ref{VERSION} for more information. + +@kindex --dynamic-list-data +@item --dynamic-list-data +Include all global data symbols to the dynamic list. + +@kindex --dynamic-list-cpp-new +@item --dynamic-list-cpp-new +Provide the builtin dynamic list for C++ operator new and delete. It +is mainly useful for building shared libstdc++. + +@kindex --dynamic-list-cpp-typeinfo +@item --dynamic-list-cpp-typeinfo +Provide the builtin dynamic list for C++ runtime type identification. + +@kindex --check-sections +@kindex --no-check-sections +@item --check-sections +@itemx --no-check-sections +Asks the linker @emph{not} to check section addresses after they have +been assigned to see if there are any overlaps. Normally the linker will +perform this check, and if it finds any overlaps it will produce +suitable error messages. The linker does know about, and does make +allowances for sections in overlays. The default behaviour can be +restored by using the command line switch @option{--check-sections}. +Section overlap is not usually checked for relocatable links. You can +force checking in that case by using the @option{--check-sections} +option. + +@kindex --copy-dt-needed-entries +@kindex --no-copy-dt-needed-entries +@item --copy-dt-needed-entries +@itemx --no-copy-dt-needed-entries +This option affects the treatment of dynamic libraries referred to +by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the +command line. Normally the linker won't add a DT_NEEDED tag to the +output binary for each library mentioned in a DT_NEEDED tag in an +input dynamic library. With @option{--copy-dt-needed-entries} +specified on the command line however any dynamic libraries that +follow it will have their DT_NEEDED entries added. The default +behaviour can be restored with @option{--no-copy-dt-needed-entries}. + +This option also has an effect on the resolution of symbols in dynamic +libraries. With @option{--copy-dt-needed-entries} dynamic libraries +mentioned on the command line will be recursively searched, following +their DT_NEEDED tags to other libraries, in order to resolve symbols +required by the output binary. With the default setting however +the searching of dynamic libraries that follow it will stop with the +dynamic library itself. No DT_NEEDED links will be traversed to resolve +symbols. + +@cindex cross reference table +@kindex --cref +@item --cref +Output a cross reference table. If a linker map file is being +generated, the cross reference table is printed to the map file. +Otherwise, it is printed on the standard output. + +The format of the table is intentionally simple, so that it may be +easily processed by a script if necessary. The symbols are printed out, +sorted by name. For each symbol, a list of file names is given. If the +symbol is defined, the first file listed is the location of the +definition. If the symbol is defined as a common value then any files +where this happens appear next. Finally any files that reference the +symbol are listed. + +@cindex common allocation +@kindex --no-define-common +@item --no-define-common +This option inhibits the assignment of addresses to common symbols. +The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect. +@xref{Miscellaneous Commands}. + +The @samp{--no-define-common} option allows decoupling +the decision to assign addresses to Common symbols from the choice +of the output file type; otherwise a non-Relocatable output type +forces assigning addresses to Common symbols. +Using @samp{--no-define-common} allows Common symbols that are referenced +from a shared library to be assigned addresses only in the main program. +This eliminates the unused duplicate space in the shared library, +and also prevents any possible confusion over resolving to the wrong +duplicate when there are many dynamic modules with specialized search +paths for runtime symbol resolution. + +@cindex group allocation in linker script +@cindex section groups +@cindex COMDAT +@kindex --force-group-allocation +@item --force-group-allocation +This option causes the linker to place section group members like +normal input sections, and to delete the section groups. This is the +default behaviour for a final link but this option can be used to +change the behaviour of a relocatable link (@samp{-r}). The script +command @code{FORCE_GROUP_ALLOCATION} has the same +effect. @xref{Miscellaneous Commands}. + +@cindex symbols, from command line +@kindex --defsym=@var{symbol}=@var{exp} +@item --defsym=@var{symbol}=@var{expression} +Create a global symbol in the output file, containing the absolute +address given by @var{expression}. You may use this option as many +times as necessary to define multiple symbols in the command line. A +limited form of arithmetic is supported for the @var{expression} in this +context: you may give a hexadecimal constant or the name of an existing +symbol, or use @code{+} and @code{-} to add or subtract hexadecimal +constants or symbols. If you need more elaborate expressions, consider +using the linker command language from a script (@pxref{Assignments}). +@emph{Note:} there should be no white space between @var{symbol}, the +equals sign (``@key{=}''), and @var{expression}. + +@cindex demangling, from command line +@kindex --demangle[=@var{style}] +@kindex --no-demangle +@item --demangle[=@var{style}] +@itemx --no-demangle +These options control whether to demangle symbol names in error messages +and other output. When the linker is told to demangle, it tries to +present symbol names in a readable fashion: it strips leading +underscores if they are used by the object file format, and converts C++ +mangled symbol names into user readable names. Different compilers have +different mangling styles. The optional demangling style argument can be used +to choose an appropriate demangling style for your compiler. The linker will +demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE} +is set. These options may be used to override the default. + +@cindex dynamic linker, from command line +@kindex -I@var{file} +@kindex --dynamic-linker=@var{file} +@item -I@var{file} +@itemx --dynamic-linker=@var{file} +Set the name of the dynamic linker. This is only meaningful when +generating dynamically linked ELF executables. The default dynamic +linker is normally correct; don't use this unless you know what you are +doing. + +@kindex --no-dynamic-linker +@item --no-dynamic-linker +When producing an executable file, omit the request for a dynamic +linker to be used at load-time. This is only meaningful for ELF +executables that contain dynamic relocations, and usually requires +entry point code that is capable of processing these relocations. + +@kindex --embedded-relocs +@item --embedded-relocs +This option is similar to the @option{--emit-relocs} option except +that the relocs are stored in a target specific section. This option +is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K} +targets. + +@kindex --disable-multiple-abs-defs +@item --disable-multiple-abs-defs +Do not allow multiple definitions with symbols included +in filename invoked by -R or --just-symbols + +@kindex --fatal-warnings +@kindex --no-fatal-warnings +@item --fatal-warnings +@itemx --no-fatal-warnings +Treat all warnings as errors. The default behaviour can be restored +with the option @option{--no-fatal-warnings}. + +@kindex --force-exe-suffix +@item --force-exe-suffix +Make sure that an output file has a .exe suffix. + +If a successfully built fully linked output file does not have a +@code{.exe} or @code{.dll} suffix, this option forces the linker to copy +the output file to one of the same name with a @code{.exe} suffix. This +option is useful when using unmodified Unix makefiles on a Microsoft +Windows host, since some versions of Windows won't run an image unless +it ends in a @code{.exe} suffix. + +@kindex --gc-sections +@kindex --no-gc-sections +@cindex garbage collection +@item --gc-sections +@itemx --no-gc-sections +Enable garbage collection of unused input sections. It is ignored on +targets that do not support this option. The default behaviour (of not +performing this garbage collection) can be restored by specifying +@samp{--no-gc-sections} on the command line. Note that garbage +collection for COFF and PE format targets is supported, but the +implementation is currently considered to be experimental. + +@samp{--gc-sections} decides which input sections are used by +examining symbols and relocations. The section containing the entry +symbol and all sections containing symbols undefined on the +command-line will be kept, as will sections containing symbols +referenced by dynamic objects. Note that when building shared +libraries, the linker must assume that any visible symbol is +referenced. Once this initial set of sections has been determined, +the linker recursively marks as used any section referenced by their +relocations. See @samp{--entry} and @samp{--undefined}. + +This option can be set when doing a partial link (enabled with option +@samp{-r}). In this case the root of symbols kept must be explicitly +specified either by an @samp{--entry} or @samp{--undefined} option or by +a @code{ENTRY} command in the linker script. + +@kindex --print-gc-sections +@kindex --no-print-gc-sections +@cindex garbage collection +@item --print-gc-sections +@itemx --no-print-gc-sections +List all sections removed by garbage collection. The listing is +printed on stderr. This option is only effective if garbage +collection has been enabled via the @samp{--gc-sections}) option. The +default behaviour (of not listing the sections that are removed) can +be restored by specifying @samp{--no-print-gc-sections} on the command +line. + +@kindex --gc-keep-exported +@cindex garbage collection +@item --gc-keep-exported +When @samp{--gc-sections} is enabled, this option prevents garbage +collection of unused input sections that contain global symbols having +default or protected visibility. This option is intended to be used for +executables where unreferenced sections would otherwise be garbage +collected regardless of the external visibility of contained symbols. +Note that this option has no effect when linking shared objects since +it is already the default behaviour. This option is only supported for +ELF format targets. + +@kindex --print-output-format +@cindex output format +@item --print-output-format +Print the name of the default output format (perhaps influenced by +other command-line options). This is the string that would appear +in an @code{OUTPUT_FORMAT} linker script command (@pxref{File Commands}). + +@kindex --print-memory-usage +@cindex memory usage +@item --print-memory-usage +Print used size, total size and used size of memory regions created with +the @ref{MEMORY} command. This is useful on embedded targets to have a +quick view of amount of free memory. The format of the output has one +headline and one line per region. It is both human readable and easily +parsable by tools. Here is an example of an output: + +@smallexample +Memory region Used Size Region Size %age Used + ROM: 256 KB 1 MB 25.00% + RAM: 32 B 2 GB 0.00% +@end smallexample + +@cindex help +@cindex usage +@kindex --help +@item --help +Print a summary of the command-line options on the standard output and exit. + +@kindex --target-help +@item --target-help +Print a summary of all target specific options on the standard output and exit. + +@kindex -Map=@var{mapfile} +@item -Map=@var{mapfile} +Print a link map to the file @var{mapfile}. See the description of the +@option{-M} option, above. + +@cindex memory usage +@kindex --no-keep-memory +@item --no-keep-memory +@command{ld} normally optimizes for speed over memory usage by caching the +symbol tables of input files in memory. This option tells @command{ld} to +instead optimize for memory usage, by rereading the symbol tables as +necessary. This may be required if @command{ld} runs out of memory space +while linking a large executable. + +@kindex --no-undefined +@kindex -z defs +@kindex -z undefs +@item --no-undefined +@itemx -z defs +Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +The switch @option{--[no-]allow-shlib-undefined} controls the +behaviour for reporting unresolved references found in shared +libraries being linked in. + +The effects of this option can be reverted by using @code{-z undefs}. + +@kindex --allow-multiple-definition +@kindex -z muldefs +@item --allow-multiple-definition +@itemx -z muldefs +Normally when a symbol is defined multiple times, the linker will +report a fatal error. These options allow multiple definitions and the +first definition will be used. + +@kindex --allow-shlib-undefined +@kindex --no-allow-shlib-undefined +@item --allow-shlib-undefined +@itemx --no-allow-shlib-undefined +Allows or disallows undefined symbols in shared libraries. +This switch is similar to @option{--no-undefined} except that it +determines the behaviour when the undefined symbols are in a +shared library rather than a regular object file. It does not affect +how undefined symbols in regular object files are handled. + +The default behaviour is to report errors for any undefined symbols +referenced in shared libraries if the linker is being used to create +an executable, but to allow them if the linker is being used to create +a shared library. + +The reasons for allowing undefined symbol references in shared +libraries specified at link time are that: + +@itemize @bullet +@item +A shared library specified at link time may not be the same as the one +that is available at load time, so the symbol might actually be +resolvable at load time. +@item +There are some operating systems, eg BeOS and HPPA, where undefined +symbols in shared libraries are normal. + +The BeOS kernel for example patches shared libraries at load time to +select whichever function is most appropriate for the current +architecture. This is used, for example, to dynamically select an +appropriate memset function. +@end itemize + +@kindex --no-undefined-version +@item --no-undefined-version +Normally when a symbol has an undefined version, the linker will ignore +it. This option disallows symbols with undefined version and a fatal error +will be issued instead. + +@kindex --default-symver +@item --default-symver +Create and use a default symbol version (the soname) for unversioned +exported symbols. + +@kindex --default-imported-symver +@item --default-imported-symver +Create and use a default symbol version (the soname) for unversioned +imported symbols. + +@kindex --no-warn-mismatch +@item --no-warn-mismatch +Normally @command{ld} will give an error if you try to link together input +files that are mismatched for some reason, perhaps because they have +been compiled for different processors or for different endiannesses. +This option tells @command{ld} that it should silently permit such possible +errors. This option should only be used with care, in cases when you +have taken some special action that ensures that the linker errors are +inappropriate. + +@kindex --no-warn-search-mismatch +@item --no-warn-search-mismatch +Normally @command{ld} will give a warning if it finds an incompatible +library during a library search. This option silences the warning. + +@kindex --no-whole-archive +@item --no-whole-archive +Turn off the effect of the @option{--whole-archive} option for subsequent +archive files. + +@cindex output file after errors +@kindex --noinhibit-exec +@item --noinhibit-exec +Retain the executable output file whenever it is still usable. +Normally, the linker will not produce an output file if it encounters +errors during the link process; it exits without writing an output file +when it issues any error whatsoever. + +@kindex -nostdlib +@item -nostdlib +Only search library directories explicitly specified on the +command line. Library directories specified in linker scripts +(including linker scripts specified on the command line) are ignored. + +@ifclear SingleFormat +@kindex --oformat=@var{output-format} +@item --oformat=@var{output-format} +@command{ld} may be configured to support more than one kind of object +file. If your @command{ld} is configured this way, you can use the +@samp{--oformat} option to specify the binary format for the output +object file. Even when @command{ld} is configured to support alternative +object formats, you don't usually need to specify this, as @command{ld} +should be configured to produce as a default output format the most +usual format on each machine. @var{output-format} is a text string, the +name of a particular format supported by the BFD libraries. (You can +list the available binary formats with @samp{objdump -i}.) The script +command @code{OUTPUT_FORMAT} can also specify the output format, but +this option overrides it. @xref{BFD}. +@end ifclear + +@kindex --out-implib +@item --out-implib @var{file} +Create an import library in @var{file} corresponding to the executable +the linker is generating (eg. a DLL or ELF program). This import +library (which should be called @code{*.dll.a} or @code{*.a} for DLLs) +may be used to link clients against the generated executable; this +behaviour makes it possible to skip a separate import library creation +step (eg. @code{dlltool} for DLLs). This option is only available for +the i386 PE and ELF targetted ports of the linker. + +@kindex -pie +@kindex --pic-executable +@item -pie +@itemx --pic-executable +@cindex position independent executables +Create a position independent executable. This is currently only supported on +ELF platforms. Position independent executables are similar to shared +libraries in that they are relocated by the dynamic linker to the virtual +address the OS chooses for them (which can vary between invocations). Like +normal dynamically linked executables they can be executed and symbols +defined in the executable cannot be overridden by shared libraries. + +@kindex -qmagic +@item -qmagic +This option is ignored for Linux compatibility. + +@kindex -Qy +@item -Qy +This option is ignored for SVR4 compatibility. + +@kindex --relax +@cindex synthesizing linker +@cindex relaxing addressing modes +@cindex --no-relax +@item --relax +@itemx --no-relax +An option with machine dependent effects. +@ifset GENERIC +This option is only supported on a few targets. +@end ifset +@ifset H8300 +@xref{H8/300,,@command{ld} and the H8/300}. +@end ifset +@ifset XTENSA +@xref{Xtensa,, @command{ld} and Xtensa Processors}. +@end ifset +@ifset M68HC11 +@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}. +@end ifset +@ifset NIOSII +@xref{Nios II,,@command{ld} and the Altera Nios II}. +@end ifset +@ifset POWERPC +@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}. +@end ifset + +On some platforms the @samp{--relax} option performs target specific, +global optimizations that become possible when the linker resolves +addressing in the program, such as relaxing address modes, +synthesizing new instructions, selecting shorter version of current +instructions, and combining constant values. + +On some platforms these link time global optimizations may make symbolic +debugging of the resulting executable impossible. +@ifset GENERIC +This is known to be the case for the Matsushita MN10200 and MN10300 +family of processors. +@end ifset + +@ifset GENERIC +On platforms where this is not supported, @samp{--relax} is accepted, +but ignored. +@end ifset + +On platforms where @samp{--relax} is accepted the option +@samp{--no-relax} can be used to disable the feature. + +@cindex retaining specified symbols +@cindex stripping all but some symbols +@cindex symbols, retaining selectively +@kindex --retain-symbols-file=@var{filename} +@item --retain-symbols-file=@var{filename} +Retain @emph{only} the symbols listed in the file @var{filename}, +discarding all others. @var{filename} is simply a flat file, with one +symbol name per line. This option is especially useful in environments +@ifset GENERIC +(such as VxWorks) +@end ifset +where a large global symbol table is accumulated gradually, to conserve +run-time memory. + +@samp{--retain-symbols-file} does @emph{not} discard undefined symbols, +or symbols needed for relocations. + +You may only specify @samp{--retain-symbols-file} once in the command +line. It overrides @samp{-s} and @samp{-S}. + +@ifset GENERIC +@item -rpath=@var{dir} +@cindex runtime library search path +@kindex -rpath=@var{dir} +Add a directory to the runtime library search path. This is used when +linking an ELF executable with shared objects. All @option{-rpath} +arguments are concatenated and passed to the runtime linker, which uses +them to locate shared objects at runtime. The @option{-rpath} option is +also used when locating shared objects which are needed by shared +objects explicitly included in the link; see the description of the +@option{-rpath-link} option. If @option{-rpath} is not used when linking an +ELF executable, the contents of the environment variable +@code{LD_RUN_PATH} will be used if it is defined. + +The @option{-rpath} option may also be used on SunOS. By default, on +SunOS, the linker will form a runtime search path out of all the +@option{-L} options it is given. If a @option{-rpath} option is used, the +runtime search path will be formed exclusively using the @option{-rpath} +options, ignoring the @option{-L} options. This can be useful when using +gcc, which adds many @option{-L} options which may be on NFS mounted +file systems. + +For compatibility with other ELF linkers, if the @option{-R} option is +followed by a directory name, rather than a file name, it is treated as +the @option{-rpath} option. +@end ifset + +@ifset GENERIC +@cindex link-time runtime library search path +@kindex -rpath-link=@var{dir} +@item -rpath-link=@var{dir} +When using ELF or SunOS, one shared library may require another. This +happens when an @code{ld -shared} link includes a shared library as one +of the input files. + +When the linker encounters such a dependency when doing a non-shared, +non-relocatable link, it will automatically try to locate the required +shared library and include it in the link, if it is not included +explicitly. In such a case, the @option{-rpath-link} option +specifies the first set of directories to search. The +@option{-rpath-link} option may specify a sequence of directory names +either by specifying a list of names separated by colons, or by +appearing multiple times. + +The tokens @var{$ORIGIN} and @var{$LIB} can appear in these search +directories. They will be replaced by the full path to the directory +containing the program or shared object in the case of @var{$ORIGIN} +and either @samp{lib} - for 32-bit binaries - or @samp{lib64} - for +64-bit binaries - in the case of @var{$LIB}. + +The alternative form of these tokens - @var{$@{ORIGIN@}} and +@var{$@{LIB@}} can also be used. The token @var{$PLATFORM} is not +supported. + +This option should be used with caution as it overrides the search path +that may have been hard compiled into a shared library. In such a case it +is possible to use unintentionally a different search path than the +runtime linker would do. + +The linker uses the following search paths to locate required shared +libraries: +@enumerate +@item +Any directories specified by @option{-rpath-link} options. +@item +Any directories specified by @option{-rpath} options. The difference +between @option{-rpath} and @option{-rpath-link} is that directories +specified by @option{-rpath} options are included in the executable and +used at runtime, whereas the @option{-rpath-link} option is only effective +at link time. Searching @option{-rpath} in this way is only supported +by native linkers and cross linkers which have been configured with +the @option{--with-sysroot} option. +@item +On an ELF system, for native linkers, if the @option{-rpath} and +@option{-rpath-link} options were not used, search the contents of the +environment variable @code{LD_RUN_PATH}. +@item +On SunOS, if the @option{-rpath} option was not used, search any +directories specified using @option{-L} options. +@item +For a native linker, search the contents of the environment +variable @code{LD_LIBRARY_PATH}. +@item +For a native ELF linker, the directories in @code{DT_RUNPATH} or +@code{DT_RPATH} of a shared library are searched for shared +libraries needed by it. The @code{DT_RPATH} entries are ignored if +@code{DT_RUNPATH} entries exist. +@item +The default directories, normally @file{/lib} and @file{/usr/lib}. +@item +For a native linker on an ELF system, if the file @file{/etc/ld.so.conf} +exists, the list of directories found in that file. +@end enumerate + +If the required shared library is not found, the linker will issue a +warning and continue with the link. +@end ifset + +@kindex -shared +@kindex -Bshareable +@item -shared +@itemx -Bshareable +@cindex shared libraries +Create a shared library. This is currently only supported on ELF, XCOFF +and SunOS platforms. On SunOS, the linker will automatically create a +shared library if the @option{-e} option is not used and there are +undefined symbols in the link. + +@kindex --sort-common +@item --sort-common +@itemx --sort-common=ascending +@itemx --sort-common=descending +This option tells @command{ld} to sort the common symbols by alignment in +ascending or descending order when it places them in the appropriate output +sections. The symbol alignments considered are sixteen-byte or larger, +eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps +between symbols due to alignment constraints. If no sorting order is +specified, then descending order is assumed. + +@kindex --sort-section=name +@item --sort-section=name +This option will apply @code{SORT_BY_NAME} to all wildcard section +patterns in the linker script. + +@kindex --sort-section=alignment +@item --sort-section=alignment +This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section +patterns in the linker script. + +@kindex --spare-dynamic-tags +@item --spare-dynamic-tags=@var{count} +This option specifies the number of empty slots to leave in the +.dynamic section of ELF shared objects. Empty slots may be needed by +post processing tools, such as the prelinker. The default is 5. + +@kindex --split-by-file +@item --split-by-file[=@var{size}] +Similar to @option{--split-by-reloc} but creates a new output section for +each input file when @var{size} is reached. @var{size} defaults to a +size of 1 if not given. + +@kindex --split-by-reloc +@item --split-by-reloc[=@var{count}] +Tries to creates extra sections in the output file so that no single +output section in the file contains more than @var{count} relocations. +This is useful when generating huge relocatable files for downloading into +certain real time kernels with the COFF object file format; since COFF +cannot represent more than 65535 relocations in a single section. Note +that this will fail to work with object file formats which do not +support arbitrary sections. The linker will not split up individual +input sections for redistribution, so if a single input section contains +more than @var{count} relocations one output section will contain that +many relocations. @var{count} defaults to a value of 32768. + +@kindex --stats +@item --stats +Compute and display statistics about the operation of the linker, such +as execution time and memory usage. + +@kindex --sysroot=@var{directory} +@item --sysroot=@var{directory} +Use @var{directory} as the location of the sysroot, overriding the +configure-time default. This option is only supported by linkers +that were configured using @option{--with-sysroot}. + +@kindex --task-link +@item --task-link +This is used by COFF/PE based targets to create a task-linked object +file where all of the global symbols have been converted to statics. + +@kindex --traditional-format +@cindex traditional format +@item --traditional-format +For some targets, the output of @command{ld} is different in some ways from +the output of some existing linker. This switch requests @command{ld} to +use the traditional format instead. + +@cindex dbx +For example, on SunOS, @command{ld} combines duplicate entries in the +symbol string table. This can reduce the size of an output file with +full debugging information by over 30 percent. Unfortunately, the SunOS +@code{dbx} program can not read the resulting program (@code{gdb} has no +trouble). The @samp{--traditional-format} switch tells @command{ld} to not +combine duplicate entries. + +@kindex --section-start=@var{sectionname}=@var{org} +@item --section-start=@var{sectionname}=@var{org} +Locate a section in the output file at the absolute +address given by @var{org}. You may use this option as many +times as necessary to locate multiple sections in the command +line. +@var{org} must be a single hexadecimal integer; +for compatibility with other linkers, you may omit the leading +@samp{0x} usually associated with hexadecimal values. @emph{Note:} there +should be no white space between @var{sectionname}, the equals +sign (``@key{=}''), and @var{org}. + +@kindex -Tbss=@var{org} +@kindex -Tdata=@var{org} +@kindex -Ttext=@var{org} +@cindex segment origins, cmd line +@item -Tbss=@var{org} +@itemx -Tdata=@var{org} +@itemx -Ttext=@var{org} +Same as @option{--section-start}, with @code{.bss}, @code{.data} or +@code{.text} as the @var{sectionname}. + +@kindex -Ttext-segment=@var{org} +@item -Ttext-segment=@var{org} +@cindex text segment origin, cmd line +When creating an ELF executable, it will set the address of the first +byte of the text segment. + +@kindex -Trodata-segment=@var{org} +@item -Trodata-segment=@var{org} +@cindex rodata segment origin, cmd line +When creating an ELF executable or shared object for a target where +the read-only data is in its own segment separate from the executable +text, it will set the address of the first byte of the read-only data segment. + +@kindex -Tldata-segment=@var{org} +@item -Tldata-segment=@var{org} +@cindex ldata segment origin, cmd line +When creating an ELF executable or shared object for x86-64 medium memory +model, it will set the address of the first byte of the ldata segment. + +@kindex --unresolved-symbols +@item --unresolved-symbols=@var{method} +Determine how to handle unresolved symbols. There are four possible +values for @samp{method}: + +@table @samp +@item ignore-all +Do not report any unresolved symbols. + +@item report-all +Report all unresolved symbols. This is the default. + +@item ignore-in-object-files +Report unresolved symbols that are contained in shared libraries, but +ignore them if they come from regular object files. + +@item ignore-in-shared-libs +Report unresolved symbols that come from regular object files, but +ignore them if they come from shared libraries. This can be useful +when creating a dynamic binary and it is known that all the shared +libraries that it should be referencing are included on the linker's +command line. +@end table + +The behaviour for shared libraries on their own can also be controlled +by the @option{--[no-]allow-shlib-undefined} option. + +Normally the linker will generate an error message for each reported +unresolved symbol but the option @option{--warn-unresolved-symbols} +can change this to a warning. + +@kindex --verbose[=@var{NUMBER}] +@cindex verbose[=@var{NUMBER}] +@item --dll-verbose +@itemx --verbose[=@var{NUMBER}] +Display the version number for @command{ld} and list the linker emulations +supported. Display which input files can and cannot be opened. Display +the linker script being used by the linker. If the optional @var{NUMBER} +argument > 1, plugin symbol status will also be displayed. + +@kindex --version-script=@var{version-scriptfile} +@cindex version script, symbol versions +@item --version-script=@var{version-scriptfile} +Specify the name of a version script to the linker. This is typically +used when creating shared libraries to specify additional information +about the version hierarchy for the library being created. This option +is only fully supported on ELF platforms which support shared libraries; +see @ref{VERSION}. It is partially supported on PE platforms, which can +use version scripts to filter symbol visibility in auto-export mode: any +symbols marked @samp{local} in the version script will not be exported. +@xref{WIN32}. + +@kindex --warn-common +@cindex warnings, on combining symbols +@cindex combining symbols, warnings on +@item --warn-common +Warn when a common symbol is combined with another common symbol or with +a symbol definition. Unix linkers allow this somewhat sloppy practice, +but linkers on some other operating systems do not. This option allows +you to find potential problems from combining global symbols. +Unfortunately, some C libraries use this practice, so you may get some +warnings about symbols in the libraries as well as in your programs. + +There are three kinds of global symbols, illustrated here by C examples: + +@table @samp +@item int i = 1; +A definition, which goes in the initialized data section of the output +file. + +@item extern int i; +An undefined reference, which does not allocate space. +There must be either a definition or a common symbol for the +variable somewhere. + +@item int i; +A common symbol. If there are only (one or more) common symbols for a +variable, it goes in the uninitialized data area of the output file. +The linker merges multiple common symbols for the same variable into a +single symbol. If they are of different sizes, it picks the largest +size. The linker turns a common symbol into a declaration, if there is +a definition of the same variable. +@end table + +The @samp{--warn-common} option can produce five kinds of warnings. +Each warning consists of a pair of lines: the first describes the symbol +just encountered, and the second describes the previous symbol +encountered with the same name. One or both of the two symbols will be +a common symbol. + +@enumerate +@item +Turning a common symbol into a reference, because there is already a +definition for the symbol. +@smallexample +@var{file}(@var{section}): warning: common of `@var{symbol}' + overridden by definition +@var{file}(@var{section}): warning: defined here +@end smallexample + +@item +Turning a common symbol into a reference, because a later definition for +the symbol is encountered. This is the same as the previous case, +except that the symbols are encountered in a different order. +@smallexample +@var{file}(@var{section}): warning: definition of `@var{symbol}' + overriding common +@var{file}(@var{section}): warning: common is here +@end smallexample + +@item +Merging a common symbol with a previous same-sized common symbol. +@smallexample +@var{file}(@var{section}): warning: multiple common + of `@var{symbol}' +@var{file}(@var{section}): warning: previous common is here +@end smallexample + +@item +Merging a common symbol with a previous larger common symbol. +@smallexample +@var{file}(@var{section}): warning: common of `@var{symbol}' + overridden by larger common +@var{file}(@var{section}): warning: larger common is here +@end smallexample + +@item +Merging a common symbol with a previous smaller common symbol. This is +the same as the previous case, except that the symbols are +encountered in a different order. +@smallexample +@var{file}(@var{section}): warning: common of `@var{symbol}' + overriding smaller common +@var{file}(@var{section}): warning: smaller common is here +@end smallexample +@end enumerate + +@kindex --warn-constructors +@item --warn-constructors +Warn if any global constructors are used. This is only useful for a few +object file formats. For formats like COFF or ELF, the linker can not +detect the use of global constructors. + +@kindex --warn-multiple-gp +@item --warn-multiple-gp +Warn if multiple global pointer values are required in the output file. +This is only meaningful for certain processors, such as the Alpha. +Specifically, some processors put large-valued constants in a special +section. A special register (the global pointer) points into the middle +of this section, so that constants can be loaded efficiently via a +base-register relative addressing mode. Since the offset in +base-register relative mode is fixed and relatively small (e.g., 16 +bits), this limits the maximum size of the constant pool. Thus, in +large programs, it is often necessary to use multiple global pointer +values in order to be able to address all possible constants. This +option causes a warning to be issued whenever this case occurs. + +@kindex --warn-once +@cindex warnings, on undefined symbols +@cindex undefined symbols, warnings on +@item --warn-once +Only warn once for each undefined symbol, rather than once per module +which refers to it. + +@kindex --warn-section-align +@cindex warnings, on section alignment +@cindex section alignment, warnings on +@item --warn-section-align +Warn if the address of an output section is changed because of +alignment. Typically, the alignment will be set by an input section. +The address will only be changed if it not explicitly specified; that +is, if the @code{SECTIONS} command does not specify a start address for +the section (@pxref{SECTIONS}). + +@kindex --warn-shared-textrel +@item --warn-shared-textrel +Warn if the linker adds a DT_TEXTREL to a shared object. + +@kindex --warn-alternate-em +@item --warn-alternate-em +Warn if an object has alternate ELF machine code. + +@kindex --warn-unresolved-symbols +@item --warn-unresolved-symbols +If the linker is going to report an unresolved symbol (see the option +@option{--unresolved-symbols}) it will normally generate an error. +This option makes it generate a warning instead. + +@kindex --error-unresolved-symbols +@item --error-unresolved-symbols +This restores the linker's default behaviour of generating errors when +it is reporting unresolved symbols. + +@kindex --whole-archive +@cindex including an entire archive +@item --whole-archive +For each archive mentioned on the command line after the +@option{--whole-archive} option, include every object file in the archive +in the link, rather than searching the archive for the required object +files. This is normally used to turn an archive file into a shared +library, forcing every object to be included in the resulting shared +library. This option may be used more than once. + +Two notes when using this option from gcc: First, gcc doesn't know +about this option, so you have to use @option{-Wl,-whole-archive}. +Second, don't forget to use @option{-Wl,-no-whole-archive} after your +list of archives, because gcc will add its own list of archives to +your link and you may not want this flag to affect those as well. + +@kindex --wrap=@var{symbol} +@item --wrap=@var{symbol} +Use a wrapper function for @var{symbol}. Any undefined reference to +@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any +undefined reference to @code{__real_@var{symbol}} will be resolved to +@var{symbol}. + +This can be used to provide a wrapper for a system function. The +wrapper function should be called @code{__wrap_@var{symbol}}. If it +wishes to call the system function, it should call +@code{__real_@var{symbol}}. + +Here is a trivial example: + +@smallexample +void * +__wrap_malloc (size_t c) +@{ + printf ("malloc called with %zu\n", c); + return __real_malloc (c); +@} +@end smallexample + +If you link other code with this file using @option{--wrap malloc}, then +all calls to @code{malloc} will call the function @code{__wrap_malloc} +instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will +call the real @code{malloc} function. + +You may wish to provide a @code{__real_malloc} function as well, so that +links without the @option{--wrap} option will succeed. If you do this, +you should not put the definition of @code{__real_malloc} in the same +file as @code{__wrap_malloc}; if you do, the assembler may resolve the +call before the linker has a chance to wrap it to @code{malloc}. + +@kindex --eh-frame-hdr +@kindex --no-eh-frame-hdr +@item --eh-frame-hdr +@itemx --no-eh-frame-hdr +Request (@option{--eh-frame-hdr}) or suppress +(@option{--no-eh-frame-hdr}) the creation of @code{.eh_frame_hdr} +section and ELF @code{PT_GNU_EH_FRAME} segment header. + +@kindex --ld-generated-unwind-info +@item --no-ld-generated-unwind-info +Request creation of @code{.eh_frame} unwind info for linker +generated code sections like PLT. This option is on by default +if linker generated unwind info is supported. + +@kindex --enable-new-dtags +@kindex --disable-new-dtags +@item --enable-new-dtags +@itemx --disable-new-dtags +This linker can create the new dynamic tags in ELF. But the older ELF +systems may not understand them. If you specify +@option{--enable-new-dtags}, the new dynamic tags will be created as needed +and older dynamic tags will be omitted. +If you specify @option{--disable-new-dtags}, no new dynamic tags will be +created. By default, the new dynamic tags are not created. Note that +those options are only available for ELF systems. + +@kindex --hash-size=@var{number} +@item --hash-size=@var{number} +Set the default size of the linker's hash tables to a prime number +close to @var{number}. Increasing this value can reduce the length of +time it takes the linker to perform its tasks, at the expense of +increasing the linker's memory requirements. Similarly reducing this +value can reduce the memory requirements at the expense of speed. + +@kindex --hash-style=@var{style} +@item --hash-style=@var{style} +Set the type of linker's hash table(s). @var{style} can be either +@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for +new style GNU @code{.gnu.hash} section or @code{both} for both +the classic ELF @code{.hash} and new style GNU @code{.gnu.hash} +hash tables. The default is @code{sysv}. + +@kindex --compress-debug-sections=none +@kindex --compress-debug-sections=zlib +@kindex --compress-debug-sections=zlib-gnu +@kindex --compress-debug-sections=zlib-gabi +@item --compress-debug-sections=none +@itemx --compress-debug-sections=zlib +@itemx --compress-debug-sections=zlib-gnu +@itemx --compress-debug-sections=zlib-gabi +On ELF platforms, these options control how DWARF debug sections are +compressed using zlib. + +@option{--compress-debug-sections=none} doesn't compress DWARF debug +sections. @option{--compress-debug-sections=zlib-gnu} compresses +DWARF debug sections and renames them to begin with @samp{.zdebug} +instead of @samp{.debug}. @option{--compress-debug-sections=zlib-gabi} +also compresses DWARF debug sections, but rather than renaming them it +sets the SHF_COMPRESSED flag in the sections' headers. + +The @option{--compress-debug-sections=zlib} option is an alias for +@option{--compress-debug-sections=zlib-gabi}. + +Note that this option overrides any compression in input debug +sections, so if a binary is linked with @option{--compress-debug-sections=none} +for example, then any compressed debug sections in input files will be +uncompressed before they are copied into the output binary. + +The default compression behaviour varies depending upon the target +involved and the configure options used to build the toolchain. The +default can be determined by examining the output from the linker's +@option{--help} option. + +@kindex --reduce-memory-overheads +@item --reduce-memory-overheads +This option reduces memory requirements at ld runtime, at the expense of +linking speed. This was introduced to select the old O(n^2) algorithm +for link map file generation, rather than the new O(n) algorithm which uses +about 40% more memory for symbol storage. + +Another effect of the switch is to set the default hash table size to +1021, which again saves memory at the cost of lengthening the linker's +run time. This is not done however if the @option{--hash-size} switch +has been used. + +The @option{--reduce-memory-overheads} switch may be also be used to +enable other tradeoffs in future versions of the linker. + +@kindex --build-id +@kindex --build-id=@var{style} +@item --build-id +@itemx --build-id=@var{style} +Request the creation of a @code{.note.gnu.build-id} ELF note section +or a @code{.buildid} COFF section. The contents of the note are +unique bits identifying this linked file. @var{style} can be +@code{uuid} to use 128 random bits, @code{sha1} to use a 160-bit +@sc{SHA1} hash on the normative parts of the output contents, +@code{md5} to use a 128-bit @sc{MD5} hash on the normative parts of +the output contents, or @code{0x@var{hexstring}} to use a chosen bit +string specified as an even number of hexadecimal digits (@code{-} and +@code{:} characters between digit pairs are ignored). If @var{style} +is omitted, @code{sha1} is used. + +The @code{md5} and @code{sha1} styles produces an identifier +that is always the same in an identical output file, but will be +unique among all nonidentical output files. It is not intended +to be compared as a checksum for the file's contents. A linked +file may be changed later by other tools, but the build ID bit +string identifying the original linked file does not change. + +Passing @code{none} for @var{style} disables the setting from any +@code{--build-id} options earlier on the command line. +@end table + +@c man end + +@subsection Options Specific to i386 PE Targets + +@c man begin OPTIONS + +The i386 PE linker supports the @option{-shared} option, which causes +the output to be a dynamically linked library (DLL) instead of a +normal executable. You should name the output @code{*.dll} when you +use this option. In addition, the linker fully supports the standard +@code{*.def} files, which may be specified on the linker command line +like an object file (in fact, it should precede archives it exports +symbols from, to ensure that they get linked in, just like a normal +object file). + +In addition to the options common to all targets, the i386 PE linker +support additional command line options that are specific to the i386 +PE target. Options that take values may be separated from their +values by either a space or an equals sign. + +@table @gcctabopt + +@kindex --add-stdcall-alias +@item --add-stdcall-alias +If given, symbols with a stdcall suffix (@@@var{nn}) will be exported +as-is and also with the suffix stripped. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --base-file +@item --base-file @var{file} +Use @var{file} as the name of a file in which to save the base +addresses of all the relocations needed for generating DLLs with +@file{dlltool}. +[This is an i386 PE specific option] + +@kindex --dll +@item --dll +Create a DLL instead of a regular executable. You may also use +@option{-shared} or specify a @code{LIBRARY} in a given @code{.def} +file. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --enable-long-section-names +@kindex --disable-long-section-names +@item --enable-long-section-names +@itemx --disable-long-section-names +The PE variants of the COFF object format add an extension that permits +the use of section names longer than eight characters, the normal limit +for COFF. By default, these names are only allowed in object files, as +fully-linked executable images do not carry the COFF string table required +to support the longer names. As a GNU extension, it is possible to +allow their use in executable images as well, or to (probably pointlessly!) +disallow it in object files, by using these two options. Executable images +generated with these long section names are slightly non-standard, carrying +as they do a string table, and may generate confusing output when examined +with non-GNU PE-aware tools, such as file viewers and dumpers. However, +GDB relies on the use of PE long section names to find Dwarf-2 debug +information sections in an executable image at runtime, and so if neither +option is specified on the command-line, @command{ld} will enable long +section names, overriding the default and technically correct behaviour, +when it finds the presence of debug information while linking an executable +image and not stripping symbols. +[This option is valid for all PE targeted ports of the linker] + +@kindex --enable-stdcall-fixup +@kindex --disable-stdcall-fixup +@item --enable-stdcall-fixup +@itemx --disable-stdcall-fixup +If the link finds a symbol that it cannot resolve, it will attempt to +do ``fuzzy linking'' by looking for another defined symbol that differs +only in the format of the symbol name (cdecl vs stdcall) and will +resolve that symbol by linking to the match. For example, the +undefined symbol @code{_foo} might be linked to the function +@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked +to the function @code{_bar}. When the linker does this, it prints a +warning, since it normally should have failed to link, but sometimes +import libraries generated from third-party dlls may need this feature +to be usable. If you specify @option{--enable-stdcall-fixup}, this +feature is fully enabled and warnings are not printed. If you specify +@option{--disable-stdcall-fixup}, this feature is disabled and such +mismatches are considered to be errors. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --leading-underscore +@kindex --no-leading-underscore +@item --leading-underscore +@itemx --no-leading-underscore +For most targets default symbol-prefix is an underscore and is defined +in target's description. By this option it is possible to +disable/enable the default underscore symbol-prefix. + +@cindex DLLs, creating +@kindex --export-all-symbols +@item --export-all-symbols +If given, all global symbols in the objects used to build a DLL will +be exported by the DLL. Note that this is the default if there +otherwise wouldn't be any exported symbols. When symbols are +explicitly exported via DEF files or implicitly exported via function +attributes, the default is to not export anything else unless this +option is given. Note that the symbols @code{DllMain@@12}, +@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and +@code{impure_ptr} will not be automatically +exported. Also, symbols imported from other DLLs will not be +re-exported, nor will symbols specifying the DLL's internal layout +such as those beginning with @code{_head_} or ending with +@code{_iname}. In addition, no symbols from @code{libgcc}, +@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported. +Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will +not be exported, to help with C++ DLLs. Finally, there is an +extensive list of cygwin-private symbols that are not exported +(obviously, this applies on when building DLLs for cygwin targets). +These cygwin-excludes are: @code{_cygwin_dll_entry@@12}, +@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12}, +@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll}, +@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2}, +@code{cygwin_premain3}, and @code{environ}. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --exclude-symbols +@item --exclude-symbols @var{symbol},@var{symbol},... +Specifies a list of symbols which should not be automatically +exported. The symbol names may be delimited by commas or colons. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --exclude-all-symbols +@item --exclude-all-symbols +Specifies no symbols should be automatically exported. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --file-alignment +@item --file-alignment +Specify the file alignment. Sections in the file will always begin at +file offsets which are multiples of this number. This defaults to +512. +[This option is specific to the i386 PE targeted port of the linker] + +@cindex heap size +@kindex --heap +@item --heap @var{reserve} +@itemx --heap @var{reserve},@var{commit} +Specify the number of bytes of memory to reserve (and optionally commit) +to be used as heap for this program. The default is 1MB reserved, 4K +committed. +[This option is specific to the i386 PE targeted port of the linker] + +@cindex image base +@kindex --image-base +@item --image-base @var{value} +Use @var{value} as the base address of your program or dll. This is +the lowest memory location that will be used when your program or dll +is loaded. To reduce the need to relocate and improve performance of +your dlls, each should have a unique base address and not overlap any +other dlls. The default is 0x400000 for executables, and 0x10000000 +for dlls. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --kill-at +@item --kill-at +If given, the stdcall suffixes (@@@var{nn}) will be stripped from +symbols before they are exported. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --large-address-aware +@item --large-address-aware +If given, the appropriate bit in the ``Characteristics'' field of the COFF +header is set to indicate that this executable supports virtual addresses +greater than 2 gigabytes. This should be used in conjunction with the /3GB +or /USERVA=@var{value} megabytes switch in the ``[operating systems]'' +section of the BOOT.INI. Otherwise, this bit has no effect. +[This option is specific to PE targeted ports of the linker] + +@kindex --disable-large-address-aware +@item --disable-large-address-aware +Reverts the effect of a previous @samp{--large-address-aware} option. +This is useful if @samp{--large-address-aware} is always set by the compiler +driver (e.g. Cygwin gcc) and the executable does not support virtual +addresses greater than 2 gigabytes. +[This option is specific to PE targeted ports of the linker] + +@kindex --major-image-version +@item --major-image-version @var{value} +Sets the major number of the ``image version''. Defaults to 1. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --major-os-version +@item --major-os-version @var{value} +Sets the major number of the ``os version''. Defaults to 4. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --major-subsystem-version +@item --major-subsystem-version @var{value} +Sets the major number of the ``subsystem version''. Defaults to 4. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --minor-image-version +@item --minor-image-version @var{value} +Sets the minor number of the ``image version''. Defaults to 0. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --minor-os-version +@item --minor-os-version @var{value} +Sets the minor number of the ``os version''. Defaults to 0. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --minor-subsystem-version +@item --minor-subsystem-version @var{value} +Sets the minor number of the ``subsystem version''. Defaults to 0. +[This option is specific to the i386 PE targeted port of the linker] + +@cindex DEF files, creating +@cindex DLLs, creating +@kindex --output-def +@item --output-def @var{file} +The linker will create the file @var{file} which will contain a DEF +file corresponding to the DLL the linker is generating. This DEF file +(which should be called @code{*.def}) may be used to create an import +library with @code{dlltool} or may be used as a reference to +automatically or implicitly exported symbols. +[This option is specific to the i386 PE targeted port of the linker] + +@cindex DLLs, creating +@kindex --enable-auto-image-base +@item --enable-auto-image-base +@itemx --enable-auto-image-base=@var{value} +Automatically choose the image base for DLLs, optionally starting with base +@var{value}, unless one is specified using the @code{--image-base} argument. +By using a hash generated from the dllname to create unique image bases +for each DLL, in-memory collisions and relocations which can delay program +execution are avoided. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --disable-auto-image-base +@item --disable-auto-image-base +Do not automatically generate a unique image base. If there is no +user-specified image base (@code{--image-base}) then use the platform +default. +[This option is specific to the i386 PE targeted port of the linker] + +@cindex DLLs, linking to +@kindex --dll-search-prefix +@item --dll-search-prefix @var{string} +When linking dynamically to a dll without an import library, +search for @code{<string><basename>.dll} in preference to +@code{lib<basename>.dll}. This behaviour allows easy distinction +between DLLs built for the various "subplatforms": native, cygwin, +uwin, pw, etc. For instance, cygwin DLLs typically use +@code{--dll-search-prefix=cyg}. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --enable-auto-import +@item --enable-auto-import +Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for +DATA imports from DLLs, thus making it possible to bypass the dllimport +mechanism on the user side and to reference unmangled symbol names. +[This option is specific to the i386 PE targeted port of the linker] + +The following remarks pertain to the original implementation of the +feature and are obsolete nowadays for Cygwin and MinGW targets. + +Note: Use of the 'auto-import' extension will cause the text section +of the image file to be made writable. This does not conform to the +PE-COFF format specification published by Microsoft. + +Note - use of the 'auto-import' extension will also cause read only +data which would normally be placed into the .rdata section to be +placed into the .data section instead. This is in order to work +around a problem with consts that is described here: +http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html + +Using 'auto-import' generally will 'just work' -- but sometimes you may +see this message: + +"variable '<var>' can't be auto-imported. Please read the +documentation for ld's @code{--enable-auto-import} for details." + +This message occurs when some (sub)expression accesses an address +ultimately given by the sum of two constants (Win32 import tables only +allow one). Instances where this may occur include accesses to member +fields of struct variables imported from a DLL, as well as using a +constant index into an array variable imported from a DLL. Any +multiword variable (arrays, structs, long long, etc) may trigger +this error condition. However, regardless of the exact data type +of the offending exported variable, ld will always detect it, issue +the warning, and exit. + +There are several ways to address this difficulty, regardless of the +data type of the exported variable: + +One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task +of adjusting references in your client code for runtime environment, so +this method works only when runtime environment supports this feature. + +A second solution is to force one of the 'constants' to be a variable -- +that is, unknown and un-optimizable at compile time. For arrays, +there are two possibilities: a) make the indexee (the array's address) +a variable, or b) make the 'constant' index a variable. Thus: + +@example +extern type extern_array[]; +extern_array[1] --> + @{ volatile type *t=extern_array; t[1] @} +@end example + +or + +@example +extern type extern_array[]; +extern_array[1] --> + @{ volatile int t=1; extern_array[t] @} +@end example + +For structs (and most other multiword data types) the only option +is to make the struct itself (or the long long, or the ...) variable: + +@example +extern struct s extern_struct; +extern_struct.field --> + @{ volatile struct s *t=&extern_struct; t->field @} +@end example + +or + +@example +extern long long extern_ll; +extern_ll --> + @{ volatile long long * local_ll=&extern_ll; *local_ll @} +@end example + +A third method of dealing with this difficulty is to abandon +'auto-import' for the offending symbol and mark it with +@code{__declspec(dllimport)}. However, in practice that +requires using compile-time #defines to indicate whether you are +building a DLL, building client code that will link to the DLL, or +merely building/linking to a static library. In making the choice +between the various methods of resolving the 'direct address with +constant offset' problem, you should consider typical real-world usage: + +Original: +@example +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv)@{ + printf("%d\n",arr[1]); +@} +@end example + +Solution 1: +@example +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv)@{ + /* This workaround is for win32 and cygwin; do not "optimize" */ + volatile int *parr = arr; + printf("%d\n",parr[1]); +@} +@end example + +Solution 2: +@example +--foo.h +/* Note: auto-export is assumed (no __declspec(dllexport)) */ +#if (defined(_WIN32) || defined(__CYGWIN__)) && \ + !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) +#define FOO_IMPORT __declspec(dllimport) +#else +#define FOO_IMPORT +#endif +extern FOO_IMPORT int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv)@{ + printf("%d\n",arr[1]); +@} +@end example + +A fourth way to avoid this problem is to re-code your +library to use a functional interface rather than a data interface +for the offending variables (e.g. set_foo() and get_foo() accessor +functions). + +@kindex --disable-auto-import +@item --disable-auto-import +Do not attempt to do sophisticated linking of @code{_symbol} to +@code{__imp__symbol} for DATA imports from DLLs. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --enable-runtime-pseudo-reloc +@item --enable-runtime-pseudo-reloc +If your code contains expressions described in --enable-auto-import section, +that is, DATA imports from DLL with non-zero offset, this switch will create +a vector of 'runtime pseudo relocations' which can be used by runtime +environment to adjust references to such data in your client code. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --disable-runtime-pseudo-reloc +@item --disable-runtime-pseudo-reloc +Do not create pseudo relocations for non-zero offset DATA imports from DLLs. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --enable-extra-pe-debug +@item --enable-extra-pe-debug +Show additional debug info related to auto-import symbol thunking. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --section-alignment +@item --section-alignment +Sets the section alignment. Sections in memory will always begin at +addresses which are a multiple of this number. Defaults to 0x1000. +[This option is specific to the i386 PE targeted port of the linker] + +@cindex stack size +@kindex --stack +@item --stack @var{reserve} +@itemx --stack @var{reserve},@var{commit} +Specify the number of bytes of memory to reserve (and optionally commit) +to be used as stack for this program. The default is 2MB reserved, 4K +committed. +[This option is specific to the i386 PE targeted port of the linker] + +@kindex --subsystem +@item --subsystem @var{which} +@itemx --subsystem @var{which}:@var{major} +@itemx --subsystem @var{which}:@var{major}.@var{minor} +Specifies the subsystem under which your program will execute. The +legal values for @var{which} are @code{native}, @code{windows}, +@code{console}, @code{posix}, and @code{xbox}. You may optionally set +the subsystem version also. Numeric values are also accepted for +@var{which}. +[This option is specific to the i386 PE targeted port of the linker] + +The following options set flags in the @code{DllCharacteristics} field +of the PE file header: +[These options are specific to PE targeted ports of the linker] + +@kindex --high-entropy-va +@item --high-entropy-va +Image is compatible with 64-bit address space layout randomization +(ASLR). + +@kindex --dynamicbase +@item --dynamicbase +The image base address may be relocated using address space layout +randomization (ASLR). This feature was introduced with MS Windows +Vista for i386 PE targets. + +@kindex --forceinteg +@item --forceinteg +Code integrity checks are enforced. + +@kindex --nxcompat +@item --nxcompat +The image is compatible with the Data Execution Prevention. +This feature was introduced with MS Windows XP SP2 for i386 PE targets. + +@kindex --no-isolation +@item --no-isolation +Although the image understands isolation, do not isolate the image. + +@kindex --no-seh +@item --no-seh +The image does not use SEH. No SE handler may be called from +this image. + +@kindex --no-bind +@item --no-bind +Do not bind this image. + +@kindex --wdmdriver +@item --wdmdriver +The driver uses the MS Windows Driver Model. + +@kindex --tsaware +@item --tsaware +The image is Terminal Server aware. + +@kindex --insert-timestamp +@item --insert-timestamp +@itemx --no-insert-timestamp +Insert a real timestamp into the image. This is the default behaviour +as it matches legacy code and it means that the image will work with +other, proprietary tools. The problem with this default is that it +will result in slightly different images being produced each time the +same sources are linked. The option @option{--no-insert-timestamp} +can be used to insert a zero value for the timestamp, this ensuring +that binaries produced from identical sources will compare +identically. +@end table + +@c man end + +@ifset C6X +@subsection Options specific to C6X uClinux targets + +@c man begin OPTIONS + +The C6X uClinux target uses a binary format called DSBT to support shared +libraries. Each shared library in the system needs to have a unique index; +all executables use an index of 0. + +@table @gcctabopt + +@kindex --dsbt-size +@item --dsbt-size @var{size} +This option sets the number of entries in the DSBT of the current executable +or shared library to @var{size}. The default is to create a table with 64 +entries. + +@kindex --dsbt-index +@item --dsbt-index @var{index} +This option sets the DSBT index of the current executable or shared library +to @var{index}. The default is 0, which is appropriate for generating +executables. If a shared library is generated with a DSBT index of 0, the +@code{R_C6000_DSBT_INDEX} relocs are copied into the output file. + +@kindex --no-merge-exidx-entries +The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent +exidx entries in frame unwind info. + +@end table + +@c man end +@end ifset + +@ifset M68HC11 +@subsection Options specific to Motorola 68HC11 and 68HC12 targets + +@c man begin OPTIONS + +The 68HC11 and 68HC12 linkers support specific options to control the +memory bank switching mapping and trampoline code generation. + +@table @gcctabopt + +@kindex --no-trampoline +@item --no-trampoline +This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a @code{jsr} +instruction (this happens when a pointer to a far function is taken). + +@kindex --bank-window +@item --bank-window @var{name} +This option indicates to the linker the name of the memory region in +the @samp{MEMORY} specification that describes the memory bank window. +The definition of such region is then used by the linker to compute +paging and addresses within the memory window. + +@end table + +@c man end +@end ifset + +@ifset M68K +@subsection Options specific to Motorola 68K target + +@c man begin OPTIONS + +The following options are supported to control handling of GOT generation +when linking for 68K targets. + +@table @gcctabopt + +@kindex --got +@item --got=@var{type} +This option tells the linker which GOT generation scheme to use. +@var{type} should be one of @samp{single}, @samp{negative}, +@samp{multigot} or @samp{target}. For more information refer to the +Info entry for @file{ld}. + +@end table + +@c man end +@end ifset + +@ifset MIPS +@subsection Options specific to MIPS targets + +@c man begin OPTIONS + +The following options are supported to control microMIPS instruction +generation and branch relocation checks for ISA mode transitions when +linking for MIPS targets. + +@table @gcctabopt + +@kindex --insn32 +@item --insn32 +@kindex --no-insn32 +@itemx --no-insn32 +These options control the choice of microMIPS instructions used in code +generated by the linker, such as that in the PLT or lazy binding stubs, +or in relaxation. If @samp{--insn32} is used, then the linker only uses +32-bit instruction encodings. By default or if @samp{--no-insn32} is +used, all instruction encodings are used, including 16-bit ones where +possible. + +@kindex --ignore-branch-isa +@item --ignore-branch-isa +@kindex --no-ignore-branch-isa +@itemx --no-ignore-branch-isa +These options control branch relocation checks for invalid ISA mode +transitions. If @samp{--ignore-branch-isa} is used, then the linker +accepts any branch relocations and any ISA mode transition required +is lost in relocation calculation, except for some cases of @code{BAL} +instructions which meet relaxation conditions and are converted to +equivalent @code{JALX} instructions as the associated relocation is +calculated. By default or if @samp{--no-ignore-branch-isa} is used +a check is made causing the loss of an ISA mode transition to produce +an error. + +@end table + +@c man end +@end ifset + +@ifset UsesEnvVars +@node Environment +@section Environment Variables + +@c man begin ENVIRONMENT + +You can change the behaviour of @command{ld} with the environment variables +@ifclear SingleFormat +@code{GNUTARGET}, +@end ifclear +@code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}. + +@ifclear SingleFormat +@kindex GNUTARGET +@cindex default input format +@code{GNUTARGET} determines the input-file object format if you don't +use @samp{-b} (or its synonym @samp{--format}). Its value should be one +of the BFD names for an input format (@pxref{BFD}). If there is no +@code{GNUTARGET} in the environment, @command{ld} uses the natural format +of the target. If @code{GNUTARGET} is set to @code{default} then BFD +attempts to discover the input format by examining binary input files; +this method often succeeds, but there are potential ambiguities, since +there is no method of ensuring that the magic number used to specify +object-file formats is unique. However, the configuration procedure for +BFD on each system places the conventional format for that system first +in the search-list, so ambiguities are resolved in favor of convention. +@end ifclear + +@kindex LDEMULATION +@cindex default emulation +@cindex emulation, default +@code{LDEMULATION} determines the default emulation if you don't use the +@samp{-m} option. The emulation can affect various aspects of linker +behaviour, particularly the default linker script. You can list the +available emulations with the @samp{--verbose} or @samp{-V} options. If +the @samp{-m} option is not used, and the @code{LDEMULATION} environment +variable is not defined, the default emulation depends upon how the +linker was configured. + +@kindex COLLECT_NO_DEMANGLE +@cindex demangling, default +Normally, the linker will default to demangling symbols. However, if +@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will +default to not demangling symbols. This environment variable is used in +a similar fashion by the @code{gcc} linker wrapper program. The default +may be overridden by the @samp{--demangle} and @samp{--no-demangle} +options. + +@c man end +@end ifset + +@node Scripts +@chapter Linker Scripts + +@cindex scripts +@cindex linker scripts +@cindex command files +Every link is controlled by a @dfn{linker script}. This script is +written in the linker command language. + +The main purpose of the linker script is to describe how the sections in +the input files should be mapped into the output file, and to control +the memory layout of the output file. Most linker scripts do nothing +more than this. However, when necessary, the linker script can also +direct the linker to perform many other operations, using the commands +described below. + +The linker always uses a linker script. If you do not supply one +yourself, the linker will use a default script that is compiled into the +linker executable. You can use the @samp{--verbose} command line option +to display the default linker script. Certain command line options, +such as @samp{-r} or @samp{-N}, will affect the default linker script. + +You may supply your own linker script by using the @samp{-T} command +line option. When you do this, your linker script will replace the +default linker script. + +You may also use linker scripts implicitly by naming them as input files +to the linker, as though they were files to be linked. @xref{Implicit +Linker Scripts}. + +@menu +* Basic Script Concepts:: Basic Linker Script Concepts +* Script Format:: Linker Script Format +* Simple Example:: Simple Linker Script Example +* Simple Commands:: Simple Linker Script Commands +* Assignments:: Assigning Values to Symbols +* SECTIONS:: SECTIONS Command +* MEMORY:: MEMORY Command +* PHDRS:: PHDRS Command +* VERSION:: VERSION Command +* Expressions:: Expressions in Linker Scripts +* Implicit Linker Scripts:: Implicit Linker Scripts +@end menu + +@node Basic Script Concepts +@section Basic Linker Script Concepts +@cindex linker script concepts +We need to define some basic concepts and vocabulary in order to +describe the linker script language. + +The linker combines input files into a single output file. The output +file and each input file are in a special data format known as an +@dfn{object file format}. Each file is called an @dfn{object file}. +The output file is often called an @dfn{executable}, but for our +purposes we will also call it an object file. Each object file has, +among other things, a list of @dfn{sections}. We sometimes refer to a +section in an input file as an @dfn{input section}; similarly, a section +in the output file is an @dfn{output section}. + +Each section in an object file has a name and a size. Most sections +also have an associated block of data, known as the @dfn{section +contents}. A section may be marked as @dfn{loadable}, which means that +the contents should be loaded into memory when the output file is run. +A section with no contents may be @dfn{allocatable}, which means that an +area in memory should be set aside, but nothing in particular should be +loaded there (in some cases this memory must be zeroed out). A section +which is neither loadable nor allocatable typically contains some sort +of debugging information. + +Every loadable or allocatable output section has two addresses. The +first is the @dfn{VMA}, or virtual memory address. This is the address +the section will have when the output file is run. The second is the +@dfn{LMA}, or load memory address. This is the address at which the +section will be loaded. In most cases the two addresses will be the +same. An example of when they might be different is when a data section +is loaded into ROM, and then copied into RAM when the program starts up +(this technique is often used to initialize global variables in a ROM +based system). In this case the ROM address would be the LMA, and the +RAM address would be the VMA. + +You can see the sections in an object file by using the @code{objdump} +program with the @samp{-h} option. + +Every object file also has a list of @dfn{symbols}, known as the +@dfn{symbol table}. A symbol may be defined or undefined. Each symbol +has a name, and each defined symbol has an address, among other +information. If you compile a C or C++ program into an object file, you +will get a defined symbol for every defined function and global or +static variable. Every undefined function or global variable which is +referenced in the input file will become an undefined symbol. + +You can see the symbols in an object file by using the @code{nm} +program, or by using the @code{objdump} program with the @samp{-t} +option. + +@node Script Format +@section Linker Script Format +@cindex linker script format +Linker scripts are text files. + +You write a linker script as a series of commands. Each command is +either a keyword, possibly followed by arguments, or an assignment to a +symbol. You may separate commands using semicolons. Whitespace is +generally ignored. + +Strings such as file or format names can normally be entered directly. +If the file name contains a character such as a comma which would +otherwise serve to separate file names, you may put the file name in +double quotes. There is no way to use a double quote character in a +file name. + +You may include comments in linker scripts just as in C, delimited by +@samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent +to whitespace. + +@node Simple Example +@section Simple Linker Script Example +@cindex linker script example +@cindex example of linker script +Many linker scripts are fairly simple. + +The simplest possible linker script has just one command: +@samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the +memory layout of the output file. + +The @samp{SECTIONS} command is a powerful command. Here we will +describe a simple use of it. Let's assume your program consists only of +code, initialized data, and uninitialized data. These will be in the +@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively. +Let's assume further that these are the only sections which appear in +your input files. + +For this example, let's say that the code should be loaded at address +0x10000, and that the data should start at address 0x8000000. Here is a +linker script which will do that: +@smallexample +SECTIONS +@{ + . = 0x10000; + .text : @{ *(.text) @} + . = 0x8000000; + .data : @{ *(.data) @} + .bss : @{ *(.bss) @} +@} +@end smallexample + +You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS}, +followed by a series of symbol assignments and output section +descriptions enclosed in curly braces. + +The first line inside the @samp{SECTIONS} command of the above example +sets the value of the special symbol @samp{.}, which is the location +counter. If you do not specify the address of an output section in some +other way (other ways are described later), the address is set from the +current value of the location counter. The location counter is then +incremented by the size of the output section. At the start of the +@samp{SECTIONS} command, the location counter has the value @samp{0}. + +The second line defines an output section, @samp{.text}. The colon is +required syntax which may be ignored for now. Within the curly braces +after the output section name, you list the names of the input sections +which should be placed into this output section. The @samp{*} is a +wildcard which matches any file name. The expression @samp{*(.text)} +means all @samp{.text} input sections in all input files. + +Since the location counter is @samp{0x10000} when the output section +@samp{.text} is defined, the linker will set the address of the +@samp{.text} section in the output file to be @samp{0x10000}. + +The remaining lines define the @samp{.data} and @samp{.bss} sections in +the output file. The linker will place the @samp{.data} output section +at address @samp{0x8000000}. After the linker places the @samp{.data} +output section, the value of the location counter will be +@samp{0x8000000} plus the size of the @samp{.data} output section. The +effect is that the linker will place the @samp{.bss} output section +immediately after the @samp{.data} output section in memory. + +The linker will ensure that each output section has the required +alignment, by increasing the location counter if necessary. In this +example, the specified addresses for the @samp{.text} and @samp{.data} +sections will probably satisfy any alignment constraints, but the linker +may have to create a small gap between the @samp{.data} and @samp{.bss} +sections. + +That's it! That's a simple and complete linker script. + +@node Simple Commands +@section Simple Linker Script Commands +@cindex linker script simple commands +In this section we describe the simple linker script commands. + +@menu +* Entry Point:: Setting the entry point +* File Commands:: Commands dealing with files +@ifclear SingleFormat +* Format Commands:: Commands dealing with object file formats +@end ifclear + +* REGION_ALIAS:: Assign alias names to memory regions +* Miscellaneous Commands:: Other linker script commands +@end menu + +@node Entry Point +@subsection Setting the Entry Point +@kindex ENTRY(@var{symbol}) +@cindex start of execution +@cindex first instruction +@cindex entry point +The first instruction to execute in a program is called the @dfn{entry +point}. You can use the @code{ENTRY} linker script command to set the +entry point. The argument is a symbol name: +@smallexample +ENTRY(@var{symbol}) +@end smallexample + +There are several ways to set the entry point. The linker will set the +entry point by trying each of the following methods in order, and +stopping when one of them succeeds: +@itemize @bullet +@item +the @samp{-e} @var{entry} command-line option; +@item +the @code{ENTRY(@var{symbol})} command in a linker script; +@item +the value of a target specific symbol, if it is defined; For many +targets this is @code{start}, but PE and BeOS based systems for example +check a list of possible entry symbols, matching the first one found. +@item +the address of the first byte of the @samp{.text} section, if present; +@item +The address @code{0}. +@end itemize + +@node File Commands +@subsection Commands Dealing with Files +@cindex linker script file commands +Several linker script commands deal with files. + +@table @code +@item INCLUDE @var{filename} +@kindex INCLUDE @var{filename} +@cindex including a linker script +Include the linker script @var{filename} at this point. The file will +be searched for in the current directory, and in any directory specified +with the @option{-L} option. You can nest calls to @code{INCLUDE} up to +10 levels deep. + +You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or +@code{SECTIONS} commands, or in output section descriptions. + +@item INPUT(@var{file}, @var{file}, @dots{}) +@itemx INPUT(@var{file} @var{file} @dots{}) +@kindex INPUT(@var{files}) +@cindex input files in linker scripts +@cindex input object files in linker scripts +@cindex linker script input object files +The @code{INPUT} command directs the linker to include the named files +in the link, as though they were named on the command line. + +For example, if you always want to include @file{subr.o} any time you do +a link, but you can't be bothered to put it on every link command line, +then you can put @samp{INPUT (subr.o)} in your linker script. + +In fact, if you like, you can list all of your input files in the linker +script, and then invoke the linker with nothing but a @samp{-T} option. + +In case a @dfn{sysroot prefix} is configured, and the filename starts +with the @samp{/} character, and the script being processed was +located inside the @dfn{sysroot prefix}, the filename will be looked +for in the @dfn{sysroot prefix}. Otherwise, the linker will try to +open the file in the current directory. If it is not found, the +linker will search through the archive library search path. +The @dfn{sysroot prefix} can also be forced by specifying @code{=} +as the first character in the filename path, or prefixing the filename +path with @code{$SYSROOT}. See also the description of @samp{-L} in +@ref{Options,,Command Line Options}. + +If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the +name to @code{lib@var{file}.a}, as with the command line argument +@samp{-l}. + +When you use the @code{INPUT} command in an implicit linker script, the +files will be included in the link at the point at which the linker +script file is included. This can affect archive searching. + +@item GROUP(@var{file}, @var{file}, @dots{}) +@itemx GROUP(@var{file} @var{file} @dots{}) +@kindex GROUP(@var{files}) +@cindex grouping input files +The @code{GROUP} command is like @code{INPUT}, except that the named +files should all be archives, and they are searched repeatedly until no +new undefined references are created. See the description of @samp{-(} +in @ref{Options,,Command Line Options}. + +@item AS_NEEDED(@var{file}, @var{file}, @dots{}) +@itemx AS_NEEDED(@var{file} @var{file} @dots{}) +@kindex AS_NEEDED(@var{files}) +This construct can appear only inside of the @code{INPUT} or @code{GROUP} +commands, among other filenames. The files listed will be handled +as if they appear directly in the @code{INPUT} or @code{GROUP} commands, +with the exception of ELF shared libraries, that will be added only +when they are actually needed. This construct essentially enables +@option{--as-needed} option for all the files listed inside of it +and restores previous @option{--as-needed} resp. @option{--no-as-needed} +setting afterwards. + +@item OUTPUT(@var{filename}) +@kindex OUTPUT(@var{filename}) +@cindex output file name in linker script +The @code{OUTPUT} command names the output file. Using +@code{OUTPUT(@var{filename})} in the linker script is exactly like using +@samp{-o @var{filename}} on the command line (@pxref{Options,,Command +Line Options}). If both are used, the command line option takes +precedence. + +You can use the @code{OUTPUT} command to define a default name for the +output file other than the usual default of @file{a.out}. + +@item SEARCH_DIR(@var{path}) +@kindex SEARCH_DIR(@var{path}) +@cindex library search path in linker script +@cindex archive search path in linker script +@cindex search path in linker script +The @code{SEARCH_DIR} command adds @var{path} to the list of paths where +@command{ld} looks for archive libraries. Using +@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}} +on the command line (@pxref{Options,,Command Line Options}). If both +are used, then the linker will search both paths. Paths specified using +the command line option are searched first. + +@item STARTUP(@var{filename}) +@kindex STARTUP(@var{filename}) +@cindex first input file +The @code{STARTUP} command is just like the @code{INPUT} command, except +that @var{filename} will become the first input file to be linked, as +though it were specified first on the command line. This may be useful +when using a system in which the entry point is always the start of the +first file. +@end table + +@ifclear SingleFormat +@node Format Commands +@subsection Commands Dealing with Object File Formats +A couple of linker script commands deal with object file formats. + +@table @code +@item OUTPUT_FORMAT(@var{bfdname}) +@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little}) +@kindex OUTPUT_FORMAT(@var{bfdname}) +@cindex output file format in linker script +The @code{OUTPUT_FORMAT} command names the BFD format to use for the +output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is +exactly like using @samp{--oformat @var{bfdname}} on the command line +(@pxref{Options,,Command Line Options}). If both are used, the command +line option takes precedence. + +You can use @code{OUTPUT_FORMAT} with three arguments to use different +formats based on the @samp{-EB} and @samp{-EL} command line options. +This permits the linker script to set the output format based on the +desired endianness. + +If neither @samp{-EB} nor @samp{-EL} are used, then the output format +will be the first argument, @var{default}. If @samp{-EB} is used, the +output format will be the second argument, @var{big}. If @samp{-EL} is +used, the output format will be the third argument, @var{little}. + +For example, the default linker script for the MIPS ELF target uses this +command: +@smallexample +OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) +@end smallexample +This says that the default format for the output file is +@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line +option, the output file will be created in the @samp{elf32-littlemips} +format. + +@item TARGET(@var{bfdname}) +@kindex TARGET(@var{bfdname}) +@cindex input file format in linker script +The @code{TARGET} command names the BFD format to use when reading input +files. It affects subsequent @code{INPUT} and @code{GROUP} commands. +This command is like using @samp{-b @var{bfdname}} on the command line +(@pxref{Options,,Command Line Options}). If the @code{TARGET} command +is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET} +command is also used to set the format for the output file. @xref{BFD}. +@end table +@end ifclear + +@node REGION_ALIAS +@subsection Assign alias names to memory regions +@kindex REGION_ALIAS(@var{alias}, @var{region}) +@cindex region alias +@cindex region names + +Alias names can be added to existing memory regions created with the +@ref{MEMORY} command. Each name corresponds to at most one memory region. + +@smallexample +REGION_ALIAS(@var{alias}, @var{region}) +@end smallexample + +The @code{REGION_ALIAS} function creates an alias name @var{alias} for the +memory region @var{region}. This allows a flexible mapping of output sections +to memory regions. An example follows. + +Suppose we have an application for embedded systems which come with various +memory storage devices. All have a general purpose, volatile memory @code{RAM} +that allows code execution or data storage. Some may have a read-only, +non-volatile memory @code{ROM} that allows code execution and read-only data +access. The last variant is a read-only, non-volatile memory @code{ROM2} with +read-only data access and no code execution capability. We have four output +sections: + +@itemize @bullet +@item +@code{.text} program code; +@item +@code{.rodata} read-only data; +@item +@code{.data} read-write initialized data; +@item +@code{.bss} read-write zero initialized data. +@end itemize + +The goal is to provide a linker command file that contains a system independent +part defining the output sections and a system dependent part mapping the +output sections to the memory regions available on the system. Our embedded +systems come with three different memory setups @code{A}, @code{B} and +@code{C}: +@multitable @columnfractions .25 .25 .25 .25 +@item Section @tab Variant A @tab Variant B @tab Variant C +@item .text @tab RAM @tab ROM @tab ROM +@item .rodata @tab RAM @tab ROM @tab ROM2 +@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2 +@item .bss @tab RAM @tab RAM @tab RAM +@end multitable +The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is +loaded into region @code{ROM} or @code{ROM2} respectively. Please note that +the load address of the @code{.data} section starts in all three variants at +the end of the @code{.rodata} section. + +The base linker script that deals with the output sections follows. It +includes the system dependent @code{linkcmds.memory} file that describes the +memory layout: +@smallexample +INCLUDE linkcmds.memory + +SECTIONS + @{ + .text : + @{ + *(.text) + @} > REGION_TEXT + .rodata : + @{ + *(.rodata) + rodata_end = .; + @} > REGION_RODATA + .data : AT (rodata_end) + @{ + data_start = .; + *(.data) + @} > REGION_DATA + data_size = SIZEOF(.data); + data_load_start = LOADADDR(.data); + .bss : + @{ + *(.bss) + @} > REGION_BSS + @} +@end smallexample + +Now we need three different @code{linkcmds.memory} files to define memory +regions and alias names. The content of @code{linkcmds.memory} for the three +variants @code{A}, @code{B} and @code{C}: +@table @code +@item A +Here everything goes into the @code{RAM}. +@smallexample +MEMORY + @{ + RAM : ORIGIN = 0, LENGTH = 4M + @} + +REGION_ALIAS("REGION_TEXT", RAM); +REGION_ALIAS("REGION_RODATA", RAM); +REGION_ALIAS("REGION_DATA", RAM); +REGION_ALIAS("REGION_BSS", RAM); +@end smallexample +@item B +Program code and read-only data go into the @code{ROM}. Read-write data goes +into the @code{RAM}. An image of the initialized data is loaded into the +@code{ROM} and will be copied during system start into the @code{RAM}. +@smallexample +MEMORY + @{ + ROM : ORIGIN = 0, LENGTH = 3M + RAM : ORIGIN = 0x10000000, LENGTH = 1M + @} + +REGION_ALIAS("REGION_TEXT", ROM); +REGION_ALIAS("REGION_RODATA", ROM); +REGION_ALIAS("REGION_DATA", RAM); +REGION_ALIAS("REGION_BSS", RAM); +@end smallexample +@item C +Program code goes into the @code{ROM}. Read-only data goes into the +@code{ROM2}. Read-write data goes into the @code{RAM}. An image of the +initialized data is loaded into the @code{ROM2} and will be copied during +system start into the @code{RAM}. +@smallexample +MEMORY + @{ + ROM : ORIGIN = 0, LENGTH = 2M + ROM2 : ORIGIN = 0x10000000, LENGTH = 1M + RAM : ORIGIN = 0x20000000, LENGTH = 1M + @} + +REGION_ALIAS("REGION_TEXT", ROM); +REGION_ALIAS("REGION_RODATA", ROM2); +REGION_ALIAS("REGION_DATA", RAM); +REGION_ALIAS("REGION_BSS", RAM); +@end smallexample +@end table + +It is possible to write a common system initialization routine to copy the +@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if +necessary: +@smallexample +#include <string.h> + +extern char data_start []; +extern char data_size []; +extern char data_load_start []; + +void copy_data(void) +@{ + if (data_start != data_load_start) + @{ + memcpy(data_start, data_load_start, (size_t) data_size); + @} +@} +@end smallexample + +@node Miscellaneous Commands +@subsection Other Linker Script Commands +There are a few other linker scripts commands. + +@table @code +@item ASSERT(@var{exp}, @var{message}) +@kindex ASSERT +@cindex assertion in linker script +Ensure that @var{exp} is non-zero. If it is zero, then exit the linker +with an error code, and print @var{message}. + +Note that assertions are checked before the final stages of linking +take place. This means that expressions involving symbols PROVIDEd +inside section definitions will fail if the user has not set values +for those symbols. The only exception to this rule is PROVIDEd +symbols that just reference dot. Thus an assertion like this: + +@smallexample + .stack : + @{ + PROVIDE (__stack = .); + PROVIDE (__stack_size = 0x100); + ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack"); + @} +@end smallexample + +will fail if @code{__stack_size} is not defined elsewhere. Symbols +PROVIDEd outside of section definitions are evaluated earlier, so they +can be used inside ASSERTions. Thus: + +@smallexample + PROVIDE (__stack_size = 0x100); + .stack : + @{ + PROVIDE (__stack = .); + ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack"); + @} +@end smallexample + +will work. + +@item EXTERN(@var{symbol} @var{symbol} @dots{}) +@kindex EXTERN +@cindex undefined symbol in linker script +Force @var{symbol} to be entered in the output file as an undefined +symbol. Doing this may, for example, trigger linking of additional +modules from standard libraries. You may list several @var{symbol}s for +each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This +command has the same effect as the @samp{-u} command-line option. + +@item FORCE_COMMON_ALLOCATION +@kindex FORCE_COMMON_ALLOCATION +@cindex common allocation in linker script +This command has the same effect as the @samp{-d} command-line option: +to make @command{ld} assign space to common symbols even if a relocatable +output file is specified (@samp{-r}). + +@item INHIBIT_COMMON_ALLOCATION +@kindex INHIBIT_COMMON_ALLOCATION +@cindex common allocation in linker script +This command has the same effect as the @samp{--no-define-common} +command-line option: to make @code{ld} omit the assignment of addresses +to common symbols even for a non-relocatable output file. + +@item FORCE_GROUP_ALLOCATION +@kindex FORCE_GROUP_ALLOCATION +@cindex group allocation in linker script +@cindex section groups +@cindex COMDAT +This command has the same effect as the +@samp{--force-group-allocation} command-line option: to make +@command{ld} place section group members like normal input sections, +and to delete the section groups even if a relocatable output file is +specified (@samp{-r}). + +@item INSERT [ AFTER | BEFORE ] @var{output_section} +@kindex INSERT +@cindex insert user script into default script +This command is typically used in a script specified by @samp{-T} to +augment the default @code{SECTIONS} with, for example, overlays. It +inserts all prior linker script statements after (or before) +@var{output_section}, and also causes @samp{-T} to not override the +default linker script. The exact insertion point is as for orphan +sections. @xref{Location Counter}. The insertion happens after the +linker has mapped input sections to output sections. Prior to the +insertion, since @samp{-T} scripts are parsed before the default +linker script, statements in the @samp{-T} script occur before the +default linker script statements in the internal linker representation +of the script. In particular, input section assignments will be made +to @samp{-T} output sections before those in the default script. Here +is an example of how a @samp{-T} script using @code{INSERT} might look: + +@smallexample +SECTIONS +@{ + OVERLAY : + @{ + .ov1 @{ ov1*(.text) @} + .ov2 @{ ov2*(.text) @} + @} +@} +INSERT AFTER .text; +@end smallexample + +@item NOCROSSREFS(@var{section} @var{section} @dots{}) +@kindex NOCROSSREFS(@var{sections}) +@cindex cross references +This command may be used to tell @command{ld} to issue an error about any +references among certain output sections. + +In certain types of programs, particularly on embedded systems when +using overlays, when one section is loaded into memory, another section +will not be. Any direct references between the two sections would be +errors. For example, it would be an error if code in one section called +a function defined in the other section. + +The @code{NOCROSSREFS} command takes a list of output section names. If +@command{ld} detects any cross references between the sections, it reports +an error and returns a non-zero exit status. Note that the +@code{NOCROSSREFS} command uses output section names, not input section +names. + +@item NOCROSSREFS_TO(@var{tosection} @var{fromsection} @dots{}) +@kindex NOCROSSREFS_TO(@var{tosection} @var{fromsections}) +@cindex cross references +This command may be used to tell @command{ld} to issue an error about any +references to one section from a list of other sections. + +The @code{NOCROSSREFS} command is useful when ensuring that two or more +output sections are entirely independent but there are situations where +a one-way dependency is needed. For example, in a multi-core application +there may be shared code that can be called from each core but for safety +must never call back. + +The @code{NOCROSSREFS_TO} command takes a list of output section names. +The first section can not be referenced from any of the other sections. +If @command{ld} detects any references to the first section from any of +the other sections, it reports an error and returns a non-zero exit +status. Note that the @code{NOCROSSREFS_TO} command uses output section +names, not input section names. + +@ifclear SingleFormat +@item OUTPUT_ARCH(@var{bfdarch}) +@kindex OUTPUT_ARCH(@var{bfdarch}) +@cindex machine architecture +@cindex architecture +Specify a particular output machine architecture. The argument is one +of the names used by the BFD library (@pxref{BFD}). You can see the +architecture of an object file by using the @code{objdump} program with +the @samp{-f} option. +@end ifclear + +@item LD_FEATURE(@var{string}) +@kindex LD_FEATURE(@var{string}) +This command may be used to modify @command{ld} behavior. If +@var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers +in a script are simply treated as numbers everywhere. +@xref{Expression Section}. +@end table + +@node Assignments +@section Assigning Values to Symbols +@cindex assignment in scripts +@cindex symbol definition, scripts +@cindex variables, defining +You may assign a value to a symbol in a linker script. This will define +the symbol and place it into the symbol table with a global scope. + +@menu +* Simple Assignments:: Simple Assignments +* HIDDEN:: HIDDEN +* PROVIDE:: PROVIDE +* PROVIDE_HIDDEN:: PROVIDE_HIDDEN +* Source Code Reference:: How to use a linker script defined symbol in source code +@end menu + +@node Simple Assignments +@subsection Simple Assignments + +You may assign to a symbol using any of the C assignment operators: + +@table @code +@item @var{symbol} = @var{expression} ; +@itemx @var{symbol} += @var{expression} ; +@itemx @var{symbol} -= @var{expression} ; +@itemx @var{symbol} *= @var{expression} ; +@itemx @var{symbol} /= @var{expression} ; +@itemx @var{symbol} <<= @var{expression} ; +@itemx @var{symbol} >>= @var{expression} ; +@itemx @var{symbol} &= @var{expression} ; +@itemx @var{symbol} |= @var{expression} ; +@end table + +The first case will define @var{symbol} to the value of +@var{expression}. In the other cases, @var{symbol} must already be +defined, and the value will be adjusted accordingly. + +The special symbol name @samp{.} indicates the location counter. You +may only use this within a @code{SECTIONS} command. @xref{Location Counter}. + +The semicolon after @var{expression} is required. + +Expressions are defined below; see @ref{Expressions}. + +You may write symbol assignments as commands in their own right, or as +statements within a @code{SECTIONS} command, or as part of an output +section description in a @code{SECTIONS} command. + +The section of the symbol will be set from the section of the +expression; for more information, see @ref{Expression Section}. + +Here is an example showing the three different places that symbol +assignments may be used: + +@smallexample +floating_point = 0; +SECTIONS +@{ + .text : + @{ + *(.text) + _etext = .; + @} + _bdata = (. + 3) & ~ 3; + .data : @{ *(.data) @} +@} +@end smallexample +@noindent +In this example, the symbol @samp{floating_point} will be defined as +zero. The symbol @samp{_etext} will be defined as the address following +the last @samp{.text} input section. The symbol @samp{_bdata} will be +defined as the address following the @samp{.text} output section aligned +upward to a 4 byte boundary. + +@node HIDDEN +@subsection HIDDEN +@cindex HIDDEN +For ELF targeted ports, define a symbol that will be hidden and won't be +exported. The syntax is @code{HIDDEN(@var{symbol} = @var{expression})}. + +Here is the example from @ref{Simple Assignments}, rewritten to use +@code{HIDDEN}: + +@smallexample +HIDDEN(floating_point = 0); +SECTIONS +@{ + .text : + @{ + *(.text) + HIDDEN(_etext = .); + @} + HIDDEN(_bdata = (. + 3) & ~ 3); + .data : @{ *(.data) @} +@} +@end smallexample +@noindent +In this case none of the three symbols will be visible outside this module. + +@node PROVIDE +@subsection PROVIDE +@cindex PROVIDE +In some cases, it is desirable for a linker script to define a symbol +only if it is referenced and is not defined by any object included in +the link. For example, traditional linkers defined the symbol +@samp{etext}. However, ANSI C requires that the user be able to use +@samp{etext} as a function name without encountering an error. The +@code{PROVIDE} keyword may be used to define a symbol, such as +@samp{etext}, only if it is referenced but not defined. The syntax is +@code{PROVIDE(@var{symbol} = @var{expression})}. + +Here is an example of using @code{PROVIDE} to define @samp{etext}: +@smallexample +SECTIONS +@{ + .text : + @{ + *(.text) + _etext = .; + PROVIDE(etext = .); + @} +@} +@end smallexample + +In this example, if the program defines @samp{_etext} (with a leading +underscore), the linker will give a multiple definition error. If, on +the other hand, the program defines @samp{etext} (with no leading +underscore), the linker will silently use the definition in the program. +If the program references @samp{etext} but does not define it, the +linker will use the definition in the linker script. + +Note - the @code{PROVIDE} directive considers a common symbol to be +defined, even though such a symbol could be combined with the symbol +that the @code{PROVIDE} would create. This is particularly important +when considering constructor and destructor list symbols such as +@samp{__CTOR_LIST__} as these are often defined as common symbols. + +@node PROVIDE_HIDDEN +@subsection PROVIDE_HIDDEN +@cindex PROVIDE_HIDDEN +Similar to @code{PROVIDE}. For ELF targeted ports, the symbol will be +hidden and won't be exported. + +@node Source Code Reference +@subsection Source Code Reference + +Accessing a linker script defined variable from source code is not +intuitive. In particular a linker script symbol is not equivalent to +a variable declaration in a high level language, it is instead a +symbol that does not have a value. + +Before going further, it is important to note that compilers often +transform names in the source code into different names when they are +stored in the symbol table. For example, Fortran compilers commonly +prepend or append an underscore, and C++ performs extensive @samp{name +mangling}. Therefore there might be a discrepancy between the name +of a variable as it is used in source code and the name of the same +variable as it is defined in a linker script. For example in C a +linker script variable might be referred to as: + +@smallexample + extern int foo; +@end smallexample + +But in the linker script it might be defined as: + +@smallexample + _foo = 1000; +@end smallexample + +In the remaining examples however it is assumed that no name +transformation has taken place. + +When a symbol is declared in a high level language such as C, two +things happen. The first is that the compiler reserves enough space +in the program's memory to hold the @emph{value} of the symbol. The +second is that the compiler creates an entry in the program's symbol +table which holds the symbol's @emph{address}. ie the symbol table +contains the address of the block of memory holding the symbol's +value. So for example the following C declaration, at file scope: + +@smallexample + int foo = 1000; +@end smallexample + +creates an entry called @samp{foo} in the symbol table. This entry +holds the address of an @samp{int} sized block of memory where the +number 1000 is initially stored. + +When a program references a symbol the compiler generates code that +first accesses the symbol table to find the address of the symbol's +memory block and then code to read the value from that memory block. +So: + +@smallexample + foo = 1; +@end smallexample + +looks up the symbol @samp{foo} in the symbol table, gets the address +associated with this symbol and then writes the value 1 into that +address. Whereas: + +@smallexample + int * a = & foo; +@end smallexample + +looks up the symbol @samp{foo} in the symbol table, gets its address +and then copies this address into the block of memory associated with +the variable @samp{a}. + +Linker scripts symbol declarations, by contrast, create an entry in +the symbol table but do not assign any memory to them. Thus they are +an address without a value. So for example the linker script definition: + +@smallexample + foo = 1000; +@end smallexample + +creates an entry in the symbol table called @samp{foo} which holds +the address of memory location 1000, but nothing special is stored at +address 1000. This means that you cannot access the @emph{value} of a +linker script defined symbol - it has no value - all you can do is +access the @emph{address} of a linker script defined symbol. + +Hence when you are using a linker script defined symbol in source code +you should always take the address of the symbol, and never attempt to +use its value. For example suppose you want to copy the contents of a +section of memory called .ROM into a section called .FLASH and the +linker script contains these declarations: + +@smallexample +@group + start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM); + start_of_FLASH = .FLASH; +@end group +@end smallexample + +Then the C source code to perform the copy would be: + +@smallexample +@group + extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); +@end group +@end smallexample + +Note the use of the @samp{&} operators. These are correct. +Alternatively the symbols can be treated as the names of vectors or +arrays and then the code will again work as expected: + +@smallexample +@group + extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[]; + + memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM); +@end group +@end smallexample + +Note how using this method does not require the use of @samp{&} +operators. + +@node SECTIONS +@section SECTIONS Command +@kindex SECTIONS +The @code{SECTIONS} command tells the linker how to map input sections +into output sections, and how to place the output sections in memory. + +The format of the @code{SECTIONS} command is: +@smallexample +SECTIONS +@{ + @var{sections-command} + @var{sections-command} + @dots{} +@} +@end smallexample + +Each @var{sections-command} may of be one of the following: + +@itemize @bullet +@item +an @code{ENTRY} command (@pxref{Entry Point,,Entry command}) +@item +a symbol assignment (@pxref{Assignments}) +@item +an output section description +@item +an overlay description +@end itemize + +The @code{ENTRY} command and symbol assignments are permitted inside the +@code{SECTIONS} command for convenience in using the location counter in +those commands. This can also make the linker script easier to +understand because you can use those commands at meaningful points in +the layout of the output file. + +Output section descriptions and overlay descriptions are described +below. + +If you do not use a @code{SECTIONS} command in your linker script, the +linker will place each input section into an identically named output +section in the order that the sections are first encountered in the +input files. If all input sections are present in the first file, for +example, the order of sections in the output file will match the order +in the first input file. The first section will be at address zero. + +@menu +* Output Section Description:: Output section description +* Output Section Name:: Output section name +* Output Section Address:: Output section address +* Input Section:: Input section description +* Output Section Data:: Output section data +* Output Section Keywords:: Output section keywords +* Output Section Discarding:: Output section discarding +* Output Section Attributes:: Output section attributes +* Overlay Description:: Overlay description +@end menu + +@node Output Section Description +@subsection Output Section Description +The full description of an output section looks like this: +@smallexample +@group +@var{section} [@var{address}] [(@var{type})] : + [AT(@var{lma})] + [ALIGN(@var{section_align}) | ALIGN_WITH_INPUT] + [SUBALIGN(@var{subsection_align})] + [@var{constraint}] + @{ + @var{output-section-command} + @var{output-section-command} + @dots{} + @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] [,] +@end group +@end smallexample + +Most output sections do not use most of the optional section attributes. + +The whitespace around @var{section} is required, so that the section +name is unambiguous. The colon and the curly braces are also required. +The comma at the end may be required if a @var{fillexp} is used and +the next @var{sections-command} looks like a continuation of the expression. +The line breaks and other white space are optional. + +Each @var{output-section-command} may be one of the following: + +@itemize @bullet +@item +a symbol assignment (@pxref{Assignments}) +@item +an input section description (@pxref{Input Section}) +@item +data values to include directly (@pxref{Output Section Data}) +@item +a special output section keyword (@pxref{Output Section Keywords}) +@end itemize + +@node Output Section Name +@subsection Output Section Name +@cindex name, section +@cindex section name +The name of the output section is @var{section}. @var{section} must +meet the constraints of your output format. In formats which only +support a limited number of sections, such as @code{a.out}, the name +must be one of the names supported by the format (@code{a.out}, for +example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the +output format supports any number of sections, but with numbers and not +names (as is the case for Oasys), the name should be supplied as a +quoted numeric string. A section name may consist of any sequence of +characters, but a name which contains any unusual characters such as +commas must be quoted. + +The output section name @samp{/DISCARD/} is special; @ref{Output Section +Discarding}. + +@node Output Section Address +@subsection Output Section Address +@cindex address, section +@cindex section address +The @var{address} is an expression for the VMA (the virtual memory +address) of the output section. This address is optional, but if it +is provided then the output address will be set exactly as specified. + +If the output address is not specified then one will be chosen for the +section, based on the heuristic below. This address will be adjusted +to fit the alignment requirement of the output section. The +alignment requirement is the strictest alignment of any input section +contained within the output section. + +The output section address heuristic is as follows: + +@itemize @bullet +@item +If an output memory @var{region} is set for the section then it +is added to this region and its address will be the next free address +in that region. + +@item +If the MEMORY command has been used to create a list of memory +regions then the first region which has attributes compatible with the +section is selected to contain it. The section's output address will +be the next free address in that region; @ref{MEMORY}. + +@item +If no memory regions were specified, or none match the section then +the output address will be based on the current value of the location +counter. +@end itemize + +@noindent +For example: + +@smallexample +.text . : @{ *(.text) @} +@end smallexample + +@noindent +and + +@smallexample +.text : @{ *(.text) @} +@end smallexample + +@noindent +are subtly different. The first will set the address of the +@samp{.text} output section to the current value of the location +counter. The second will set it to the current value of the location +counter aligned to the strictest alignment of any of the @samp{.text} +input sections. + +The @var{address} may be an arbitrary expression; @ref{Expressions}. +For example, if you want to align the section on a 0x10 byte boundary, +so that the lowest four bits of the section address are zero, you could +do something like this: +@smallexample +.text ALIGN(0x10) : @{ *(.text) @} +@end smallexample +@noindent +This works because @code{ALIGN} returns the current location counter +aligned upward to the specified value. + +Specifying @var{address} for a section will change the value of the +location counter, provided that the section is non-empty. (Empty +sections are ignored). + +@node Input Section +@subsection Input Section Description +@cindex input sections +@cindex mapping input sections to output sections +The most common output section command is an input section description. + +The input section description is the most basic linker script operation. +You use output sections to tell the linker how to lay out your program +in memory. You use input section descriptions to tell the linker how to +map the input files into your memory layout. + +@menu +* Input Section Basics:: Input section basics +* Input Section Wildcards:: Input section wildcard patterns +* Input Section Common:: Input section for common symbols +* Input Section Keep:: Input section and garbage collection +* Input Section Example:: Input section example +@end menu + +@node Input Section Basics +@subsubsection Input Section Basics +@cindex input section basics +An input section description consists of a file name optionally followed +by a list of section names in parentheses. + +The file name and the section name may be wildcard patterns, which we +describe further below (@pxref{Input Section Wildcards}). + +The most common input section description is to include all input +sections with a particular name in the output section. For example, to +include all input @samp{.text} sections, you would write: +@smallexample +*(.text) +@end smallexample +@noindent +Here the @samp{*} is a wildcard which matches any file name. To exclude a list +@cindex EXCLUDE_FILE +of files from matching the file name wildcard, EXCLUDE_FILE may be used to +match all files except the ones specified in the EXCLUDE_FILE list. For +example: +@smallexample +EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors) +@end smallexample +@noindent +will cause all .ctors sections from all files except @file{crtend.o} +and @file{otherfile.o} to be included. The EXCLUDE_FILE can also be +placed inside the section list, for example: +@smallexample +*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors) +@end smallexample +@noindent +The result of this is identically to the previous example. Supporting +two syntaxes for EXCLUDE_FILE is useful if the section list contains +more than one section, as described below. + +There are two ways to include more than one section: +@smallexample +*(.text .rdata) +*(.text) *(.rdata) +@end smallexample +@noindent +The difference between these is the order in which the @samp{.text} and +@samp{.rdata} input sections will appear in the output section. In the +first example, they will be intermingled, appearing in the same order as +they are found in the linker input. In the second example, all +@samp{.text} input sections will appear first, followed by all +@samp{.rdata} input sections. + +When using EXCLUDE_FILE with more than one section, if the exclusion +is within the section list then the exclusion only applies to the +immediately following section, for example: +@smallexample +*(EXCLUDE_FILE (*somefile.o) .text .rdata) +@end smallexample +@noindent +will cause all @samp{.text} sections from all files except +@file{somefile.o} to be included, while all @samp{.rdata} sections +from all files, including @file{somefile.o}, will be included. To +exclude the @samp{.rdata} sections from @file{somefile.o} the example +could be modified to: +@smallexample +*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata) +@end smallexample +@noindent +Alternatively, placing the EXCLUDE_FILE outside of the section list, +before the input file selection, will cause the exclusion to apply for +all sections. Thus the previous example can be rewritten as: +@smallexample +EXCLUDE_FILE (*somefile.o) *(.text .rdata) +@end smallexample + +You can specify a file name to include sections from a particular file. +You would do this if one or more of your files contain special data that +needs to be at a particular location in memory. For example: +@smallexample +data.o(.data) +@end smallexample + +To refine the sections that are included based on the section flags +of an input section, INPUT_SECTION_FLAGS may be used. + +Here is a simple example for using Section header flags for ELF sections: + +@smallexample +@group +SECTIONS @{ + .text : @{ INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) @} + .text2 : @{ INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) @} +@} +@end group +@end smallexample + +In this example, the output section @samp{.text} will be comprised of any +input section matching the name *(.text) whose section header flags +@code{SHF_MERGE} and @code{SHF_STRINGS} are set. The output section +@samp{.text2} will be comprised of any input section matching the name *(.text) +whose section header flag @code{SHF_WRITE} is clear. + +You can also specify files within archives by writing a pattern +matching the archive, a colon, then the pattern matching the file, +with no whitespace around the colon. + +@table @samp +@item archive:file +matches file within archive +@item archive: +matches the whole archive +@item :file +matches file but not one in an archive +@end table + +Either one or both of @samp{archive} and @samp{file} can contain shell +wildcards. On DOS based file systems, the linker will assume that a +single letter followed by a colon is a drive specifier, so +@samp{c:myfile.o} is a simple file specification, not @samp{myfile.o} +within an archive called @samp{c}. @samp{archive:file} filespecs may +also be used within an @code{EXCLUDE_FILE} list, but may not appear in +other linker script contexts. For instance, you cannot extract a file +from an archive by using @samp{archive:file} in an @code{INPUT} +command. + +If you use a file name without a list of sections, then all sections in +the input file will be included in the output section. This is not +commonly done, but it may by useful on occasion. For example: +@smallexample +data.o +@end smallexample + +When you use a file name which is not an @samp{archive:file} specifier +and does not contain any wild card +characters, the linker will first see if you also specified the file +name on the linker command line or in an @code{INPUT} command. If you +did not, the linker will attempt to open the file as an input file, as +though it appeared on the command line. Note that this differs from an +@code{INPUT} command, because the linker will not search for the file in +the archive search path. + +@node Input Section Wildcards +@subsubsection Input Section Wildcard Patterns +@cindex input section wildcards +@cindex wildcard file name patterns +@cindex file name wildcard patterns +@cindex section name wildcard patterns +In an input section description, either the file name or the section +name or both may be wildcard patterns. + +The file name of @samp{*} seen in many examples is a simple wildcard +pattern for the file name. + +The wildcard patterns are like those used by the Unix shell. + +@table @samp +@item * +matches any number of characters +@item ? +matches any single character +@item [@var{chars}] +matches a single instance of any of the @var{chars}; the @samp{-} +character may be used to specify a range of characters, as in +@samp{[a-z]} to match any lower case letter +@item \ +quotes the following character +@end table + +When a file name is matched with a wildcard, the wildcard characters +will not match a @samp{/} character (used to separate directory names on +Unix). A pattern consisting of a single @samp{*} character is an +exception; it will always match any file name, whether it contains a +@samp{/} or not. In a section name, the wildcard characters will match +a @samp{/} character. + +File name wildcard patterns only match files which are explicitly +specified on the command line or in an @code{INPUT} command. The linker +does not search directories to expand wildcards. + +If a file name matches more than one wildcard pattern, or if a file name +appears explicitly and is also matched by a wildcard pattern, the linker +will use the first match in the linker script. For example, this +sequence of input section descriptions is probably in error, because the +@file{data.o} rule will not be used: +@smallexample +.data : @{ *(.data) @} +.data1 : @{ data.o(.data) @} +@end smallexample + +@cindex SORT_BY_NAME +Normally, the linker will place files and sections matched by wildcards +in the order in which they are seen during the link. You can change +this by using the @code{SORT_BY_NAME} keyword, which appears before a wildcard +pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}). When the +@code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections +into ascending order by name before placing them in the output file. + +@cindex SORT_BY_ALIGNMENT +@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The +difference is @code{SORT_BY_ALIGNMENT} will sort sections into +descending order by alignment before placing them in the output file. +Larger alignments are placed before smaller alignments in order to +reduce the amount of padding necessary. + +@cindex SORT_BY_INIT_PRIORITY +@code{SORT_BY_INIT_PRIORITY} is very similar to @code{SORT_BY_NAME}. The +difference is @code{SORT_BY_INIT_PRIORITY} will sort sections into +ascending order by numerical value of the GCC init_priority attribute +encoded in the section name before placing them in the output file. + +@cindex SORT +@code{SORT} is an alias for @code{SORT_BY_NAME}. + +When there are nested section sorting commands in linker script, there +can be at most 1 level of nesting for section sorting commands. + +@enumerate +@item +@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)). +It will sort the input sections by name first, then by alignment if two +sections have the same name. +@item +@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)). +It will sort the input sections by alignment first, then by name if two +sections have the same alignment. +@item +@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is +treated the same as @code{SORT_BY_NAME} (wildcard section pattern). +@item +@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)) +is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern). +@item +All other nested section sorting commands are invalid. +@end enumerate + +When both command line section sorting option and linker script +section sorting command are used, section sorting command always +takes precedence over the command line option. + +If the section sorting command in linker script isn't nested, the +command line option will make the section sorting command to be +treated as nested sorting command. + +@enumerate +@item +@code{SORT_BY_NAME} (wildcard section pattern ) with +@option{--sort-sections alignment} is equivalent to +@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)). +@item +@code{SORT_BY_ALIGNMENT} (wildcard section pattern) with +@option{--sort-section name} is equivalent to +@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)). +@end enumerate + +If the section sorting command in linker script is nested, the +command line option will be ignored. + +@cindex SORT_NONE +@code{SORT_NONE} disables section sorting by ignoring the command line +section sorting option. + +If you ever get confused about where input sections are going, use the +@samp{-M} linker option to generate a map file. The map file shows +precisely how input sections are mapped to output sections. + +This example shows how wildcard patterns might be used to partition +files. This linker script directs the linker to place all @samp{.text} +sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}. +The linker will place the @samp{.data} section from all files beginning +with an upper case character in @samp{.DATA}; for all other files, the +linker will place the @samp{.data} section in @samp{.data}. +@smallexample +@group +SECTIONS @{ + .text : @{ *(.text) @} + .DATA : @{ [A-Z]*(.data) @} + .data : @{ *(.data) @} + .bss : @{ *(.bss) @} +@} +@end group +@end smallexample + +@node Input Section Common +@subsubsection Input Section for Common Symbols +@cindex common symbol placement +@cindex uninitialized data placement +A special notation is needed for common symbols, because in many object +file formats common symbols do not have a particular input section. The +linker treats common symbols as though they are in an input section +named @samp{COMMON}. + +You may use file names with the @samp{COMMON} section just as with any +other input sections. You can use this to place common symbols from a +particular input file in one section while common symbols from other +input files are placed in another section. + +In most cases, common symbols in input files will be placed in the +@samp{.bss} section in the output file. For example: +@smallexample +.bss @{ *(.bss) *(COMMON) @} +@end smallexample + +@cindex scommon section +@cindex small common symbols +Some object file formats have more than one type of common symbol. For +example, the MIPS ELF object file format distinguishes standard common +symbols and small common symbols. In this case, the linker will use a +different special section name for other types of common symbols. In +the case of MIPS ELF, the linker uses @samp{COMMON} for standard common +symbols and @samp{.scommon} for small common symbols. This permits you +to map the different types of common symbols into memory at different +locations. + +@cindex [COMMON] +You will sometimes see @samp{[COMMON]} in old linker scripts. This +notation is now considered obsolete. It is equivalent to +@samp{*(COMMON)}. + +@node Input Section Keep +@subsubsection Input Section and Garbage Collection +@cindex KEEP +@cindex garbage collection +When link-time garbage collection is in use (@samp{--gc-sections}), +it is often useful to mark sections that should not be eliminated. +This is accomplished by surrounding an input section's wildcard entry +with @code{KEEP()}, as in @code{KEEP(*(.init))} or +@code{KEEP(SORT_BY_NAME(*)(.ctors))}. + +@node Input Section Example +@subsubsection Input Section Example +The following example is a complete linker script. It tells the linker +to read all of the sections from file @file{all.o} and place them at the +start of output section @samp{outputa} which starts at location +@samp{0x10000}. All of section @samp{.input1} from file @file{foo.o} +follows immediately, in the same output section. All of section +@samp{.input2} from @file{foo.o} goes into output section +@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}. +All of the remaining @samp{.input1} and @samp{.input2} sections from any +files are written to output section @samp{outputc}. + +@smallexample +@group +SECTIONS @{ + outputa 0x10000 : + @{ + all.o + foo.o (.input1) + @} +@end group +@group + outputb : + @{ + foo.o (.input2) + foo1.o (.input1) + @} +@end group +@group + outputc : + @{ + *(.input1) + *(.input2) + @} +@} +@end group +@end smallexample + +If an output section's name is the same as the input section's name +and is representable as a C identifier, then the linker will +automatically @pxref{PROVIDE} two symbols: __start_SECNAME and +__stop_SECNAME, where SECNAME is the name of the section. These +indicate the start address and end address of the output section +respectively. Note: most section names are not representable as +C identifiers because they contain a @samp{.} character. + +@node Output Section Data +@subsection Output Section Data +@cindex data +@cindex section data +@cindex output section data +@kindex BYTE(@var{expression}) +@kindex SHORT(@var{expression}) +@kindex LONG(@var{expression}) +@kindex QUAD(@var{expression}) +@kindex SQUAD(@var{expression}) +You can include explicit bytes of data in an output section by using +@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as +an output section command. Each keyword is followed by an expression in +parentheses providing the value to store (@pxref{Expressions}). The +value of the expression is stored at the current value of the location +counter. + +The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands +store one, two, four, and eight bytes (respectively). After storing the +bytes, the location counter is incremented by the number of bytes +stored. + +For example, this will store the byte 1 followed by the four byte value +of the symbol @samp{addr}: +@smallexample +BYTE(1) +LONG(addr) +@end smallexample + +When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the +same; they both store an 8 byte, or 64 bit, value. When both host and +target are 32 bits, an expression is computed as 32 bits. In this case +@code{QUAD} stores a 32 bit value zero extended to 64 bits, and +@code{SQUAD} stores a 32 bit value sign extended to 64 bits. + +If the object file format of the output file has an explicit endianness, +which is the normal case, the value will be stored in that endianness. +When the object file format does not have an explicit endianness, as is +true of, for example, S-records, the value will be stored in the +endianness of the first input object file. + +Note---these commands only work inside a section description and not +between them, so the following will produce an error from the linker: +@smallexample +SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@ +@end smallexample +whereas this will work: +@smallexample +SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@ +@end smallexample + +@kindex FILL(@var{expression}) +@cindex holes, filling +@cindex unspecified memory +You may use the @code{FILL} command to set the fill pattern for the +current section. It is followed by an expression in parentheses. Any +otherwise unspecified regions of memory within the section (for example, +gaps left due to the required alignment of input sections) are filled +with the value of the expression, repeated as +necessary. A @code{FILL} statement covers memory locations after the +point at which it occurs in the section definition; by including more +than one @code{FILL} statement, you can have different fill patterns in +different parts of an output section. + +This example shows how to fill unspecified regions of memory with the +value @samp{0x90}: +@smallexample +FILL(0x90909090) +@end smallexample + +The @code{FILL} command is similar to the @samp{=@var{fillexp}} output +section attribute, but it only affects the +part of the section following the @code{FILL} command, rather than the +entire section. If both are used, the @code{FILL} command takes +precedence. @xref{Output Section Fill}, for details on the fill +expression. + +@node Output Section Keywords +@subsection Output Section Keywords +There are a couple of keywords which can appear as output section +commands. + +@table @code +@kindex CREATE_OBJECT_SYMBOLS +@cindex input filename symbols +@cindex filename symbols +@item CREATE_OBJECT_SYMBOLS +The command tells the linker to create a symbol for each input file. +The name of each symbol will be the name of the corresponding input +file. The section of each symbol will be the output section in which +the @code{CREATE_OBJECT_SYMBOLS} command appears. + +This is conventional for the a.out object file format. It is not +normally used for any other object file format. + +@kindex CONSTRUCTORS +@cindex C++ constructors, arranging in link +@cindex constructors, arranging in link +@item CONSTRUCTORS +When linking using the a.out object file format, the linker uses an +unusual set construct to support C++ global constructors and +destructors. When linking object file formats which do not support +arbitrary sections, such as ECOFF and XCOFF, the linker will +automatically recognize C++ global constructors and destructors by name. +For these object file formats, the @code{CONSTRUCTORS} command tells the +linker to place constructor information in the output section where the +@code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is +ignored for other object file formats. + +The symbol @w{@code{__CTOR_LIST__}} marks the start of the global +constructors, and the symbol @w{@code{__CTOR_END__}} marks the end. +Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark +the start and end of the global destructors. The +first word in the list is the number of entries, followed by the address +of each constructor or destructor, followed by a zero word. The +compiler must arrange to actually run the code. For these object file +formats @sc{gnu} C++ normally calls constructors from a subroutine +@code{__main}; a call to @code{__main} is automatically inserted into +the startup code for @code{main}. @sc{gnu} C++ normally runs +destructors either by using @code{atexit}, or directly from the function +@code{exit}. + +For object file formats such as @code{COFF} or @code{ELF} which support +arbitrary section names, @sc{gnu} C++ will normally arrange to put the +addresses of global constructors and destructors into the @code{.ctors} +and @code{.dtors} sections. Placing the following sequence into your +linker script will build the sort of table which the @sc{gnu} C++ +runtime code expects to see. + +@smallexample + __CTOR_LIST__ = .; + LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) + *(.ctors) + LONG(0) + __CTOR_END__ = .; + __DTOR_LIST__ = .; + LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) + *(.dtors) + LONG(0) + __DTOR_END__ = .; +@end smallexample + +If you are using the @sc{gnu} C++ support for initialization priority, +which provides some control over the order in which global constructors +are run, you must sort the constructors at link time to ensure that they +are executed in the correct order. When using the @code{CONSTRUCTORS} +command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead. When using the +@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and +@samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and +@samp{*(.dtors)}. + +Normally the compiler and linker will handle these issues automatically, +and you will not need to concern yourself with them. However, you may +need to consider this if you are using C++ and writing your own linker +scripts. + +@end table + +@node Output Section Discarding +@subsection Output Section Discarding +@cindex discarding sections +@cindex sections, discarding +@cindex removing sections +The linker will not normally create output sections with no contents. +This is for convenience when referring to input sections that may or +may not be present in any of the input files. For example: +@smallexample +.foo : @{ *(.foo) @} +@end smallexample +@noindent +will only create a @samp{.foo} section in the output file if there is a +@samp{.foo} section in at least one input file, and if the input +sections are not all empty. Other link script directives that allocate +space in an output section will also create the output section. So +too will assignments to dot even if the assignment does not create +space, except for @samp{. = 0}, @samp{. = . + 0}, @samp{. = sym}, +@samp{. = . + sym} and @samp{. = ALIGN (. != 0, expr, 1)} when +@samp{sym} is an absolute symbol of value 0 defined in the script. +This allows you to force output of an empty section with @samp{. = .}. + +The linker will ignore address assignments (@pxref{Output Section Address}) +on discarded output sections, except when the linker script defines +symbols in the output section. In that case the linker will obey +the address assignments, possibly advancing dot even though the +section is discarded. + +@cindex /DISCARD/ +The special output section name @samp{/DISCARD/} may be used to discard +input sections. Any input sections which are assigned to an output +section named @samp{/DISCARD/} are not included in the output file. + +@node Output Section Attributes +@subsection Output Section Attributes +@cindex output section attributes +We showed above that the full description of an output section looked +like this: + +@smallexample +@group +@var{section} [@var{address}] [(@var{type})] : + [AT(@var{lma})] + [ALIGN(@var{section_align})] + [SUBALIGN(@var{subsection_align})] + [@var{constraint}] + @{ + @var{output-section-command} + @var{output-section-command} + @dots{} + @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] +@end group +@end smallexample + +We've already described @var{section}, @var{address}, and +@var{output-section-command}. In this section we will describe the +remaining section attributes. + +@menu +* Output Section Type:: Output section type +* Output Section LMA:: Output section LMA +* Forced Output Alignment:: Forced Output Alignment +* Forced Input Alignment:: Forced Input Alignment +* Output Section Constraint:: Output section constraint +* Output Section Region:: Output section region +* Output Section Phdr:: Output section phdr +* Output Section Fill:: Output section fill +@end menu + +@node Output Section Type +@subsubsection Output Section Type +Each output section may have a type. The type is a keyword in +parentheses. The following types are defined: + +@table @code +@item NOLOAD +The section should be marked as not loadable, so that it will not be +loaded into memory when the program is run. +@item DSECT +@itemx COPY +@itemx INFO +@itemx OVERLAY +These type names are supported for backward compatibility, and are +rarely used. They all have the same effect: the section should be +marked as not allocatable, so that no memory is allocated for the +section when the program is run. +@end table + +@kindex NOLOAD +@cindex prevent unnecessary loading +@cindex loading, preventing +The linker normally sets the attributes of an output section based on +the input sections which map into it. You can override this by using +the section type. For example, in the script sample below, the +@samp{ROM} section is addressed at memory location @samp{0} and does not +need to be loaded when the program is run. +@smallexample +@group +SECTIONS @{ + ROM 0 (NOLOAD) : @{ @dots{} @} + @dots{} +@} +@end group +@end smallexample + +@node Output Section LMA +@subsubsection Output Section LMA +@kindex AT>@var{lma_region} +@kindex AT(@var{lma}) +@cindex load address +@cindex section load address +Every section has a virtual address (VMA) and a load address (LMA); see +@ref{Basic Script Concepts}. The virtual address is specified by the +@pxref{Output Section Address} described earlier. The load address is +specified by the @code{AT} or @code{AT>} keywords. Specifying a load +address is optional. + +The @code{AT} keyword takes an expression as an argument. This +specifies the exact load address of the section. The @code{AT>} keyword +takes the name of a memory region as an argument. @xref{MEMORY}. The +load address of the section is set to the next free address in the +region, aligned to the section's alignment requirements. + +If neither @code{AT} nor @code{AT>} is specified for an allocatable +section, the linker will use the following heuristic to determine the +load address: + +@itemize @bullet +@item +If the section has a specific VMA address, then this is used as +the LMA address as well. + +@item +If the section is not allocatable then its LMA is set to its VMA. + +@item +Otherwise if a memory region can be found that is compatible +with the current section, and this region contains at least one +section, then the LMA is set so the difference between the +VMA and LMA is the same as the difference between the VMA and LMA of +the last section in the located region. + +@item +If no memory regions have been declared then a default region +that covers the entire address space is used in the previous step. + +@item +If no suitable region could be found, or there was no previous +section then the LMA is set equal to the VMA. +@end itemize + +@cindex ROM initialized data +@cindex initialized data in ROM +This feature is designed to make it easy to build a ROM image. For +example, the following linker script creates three output sections: one +called @samp{.text}, which starts at @code{0x1000}, one called +@samp{.mdata}, which is loaded at the end of the @samp{.text} section +even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold +uninitialized data at address @code{0x3000}. The symbol @code{_data} is +defined with the value @code{0x2000}, which shows that the location +counter holds the VMA value, not the LMA value. + +@smallexample +@group +SECTIONS + @{ + .text 0x1000 : @{ *(.text) _etext = . ; @} + .mdata 0x2000 : + AT ( ADDR (.text) + SIZEOF (.text) ) + @{ _data = . ; *(.data); _edata = . ; @} + .bss 0x3000 : + @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@} +@} +@end group +@end smallexample + +The run-time initialization code for use with a program generated with +this linker script would include something like the following, to copy +the initialized data from the ROM image to its runtime address. Notice +how this code takes advantage of the symbols defined by the linker +script. + +@smallexample +@group +extern char _etext, _data, _edata, _bstart, _bend; +char *src = &_etext; +char *dst = &_data; + +/* ROM has data at end of text; copy it. */ +while (dst < &_edata) + *dst++ = *src++; + +/* Zero bss. */ +for (dst = &_bstart; dst< &_bend; dst++) + *dst = 0; +@end group +@end smallexample + +@node Forced Output Alignment +@subsubsection Forced Output Alignment +@kindex ALIGN(@var{section_align}) +@cindex forcing output section alignment +@cindex output section alignment +You can increase an output section's alignment by using ALIGN. As an +alternative you can enforce that the difference between the VMA and LMA remains +intact throughout this output section with the ALIGN_WITH_INPUT attribute. + +@node Forced Input Alignment +@subsubsection Forced Input Alignment +@kindex SUBALIGN(@var{subsection_align}) +@cindex forcing input section alignment +@cindex input section alignment +You can force input section alignment within an output section by using +SUBALIGN. The value specified overrides any alignment given by input +sections, whether larger or smaller. + +@node Output Section Constraint +@subsubsection Output Section Constraint +@kindex ONLY_IF_RO +@kindex ONLY_IF_RW +@cindex constraints on output sections +You can specify that an output section should only be created if all +of its input sections are read-only or all of its input sections are +read-write by using the keyword @code{ONLY_IF_RO} and +@code{ONLY_IF_RW} respectively. + +@node Output Section Region +@subsubsection Output Section Region +@kindex >@var{region} +@cindex section, assigning to memory region +@cindex memory regions and sections +You can assign a section to a previously defined region of memory by +using @samp{>@var{region}}. @xref{MEMORY}. + +Here is a simple example: +@smallexample +@group +MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @} +SECTIONS @{ ROM : @{ *(.text) @} >rom @} +@end group +@end smallexample + +@node Output Section Phdr +@subsubsection Output Section Phdr +@kindex :@var{phdr} +@cindex section, assigning to program header +@cindex program headers and sections +You can assign a section to a previously defined program segment by +using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to +one or more segments, then all subsequent allocated sections will be +assigned to those segments as well, unless they use an explicitly +@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the +linker to not put the section in any segment at all. + +Here is a simple example: +@smallexample +@group +PHDRS @{ text PT_LOAD ; @} +SECTIONS @{ .text : @{ *(.text) @} :text @} +@end group +@end smallexample + +@node Output Section Fill +@subsubsection Output Section Fill +@kindex =@var{fillexp} +@cindex section fill pattern +@cindex fill pattern, entire section +You can set the fill pattern for an entire section by using +@samp{=@var{fillexp}}. @var{fillexp} is an expression +(@pxref{Expressions}). Any otherwise unspecified regions of memory +within the output section (for example, gaps left due to the required +alignment of input sections) will be filled with the value, repeated as +necessary. If the fill expression is a simple hex number, ie. a string +of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then +an arbitrarily long sequence of hex digits can be used to specify the +fill pattern; Leading zeros become part of the pattern too. For all +other cases, including extra parentheses or a unary @code{+}, the fill +pattern is the four least significant bytes of the value of the +expression. In all cases, the number is big-endian. + +You can also change the fill value with a @code{FILL} command in the +output section commands; (@pxref{Output Section Data}). + +Here is a simple example: +@smallexample +@group +SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @} +@end group +@end smallexample + +@node Overlay Description +@subsection Overlay Description +@kindex OVERLAY +@cindex overlays +An overlay description provides an easy way to describe sections which +are to be loaded as part of a single memory image but are to be run at +the same memory address. At run time, some sort of overlay manager will +copy the overlaid sections in and out of the runtime memory address as +required, perhaps by simply manipulating addressing bits. This approach +can be useful, for example, when a certain region of memory is faster +than another. + +Overlays are described using the @code{OVERLAY} command. The +@code{OVERLAY} command is used within a @code{SECTIONS} command, like an +output section description. The full syntax of the @code{OVERLAY} +command is as follows: +@smallexample +@group +OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )] + @{ + @var{secname1} + @{ + @var{output-section-command} + @var{output-section-command} + @dots{} + @} [:@var{phdr}@dots{}] [=@var{fill}] + @var{secname2} + @{ + @var{output-section-command} + @var{output-section-command} + @dots{} + @} [:@var{phdr}@dots{}] [=@var{fill}] + @dots{} + @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] [,] +@end group +@end smallexample + +Everything is optional except @code{OVERLAY} (a keyword), and each +section must have a name (@var{secname1} and @var{secname2} above). The +section definitions within the @code{OVERLAY} construct are identical to +those within the general @code{SECTIONS} construct (@pxref{SECTIONS}), +except that no addresses and no memory regions may be defined for +sections within an @code{OVERLAY}. + +The comma at the end may be required if a @var{fill} is used and +the next @var{sections-command} looks like a continuation of the expression. + +The sections are all defined with the same starting address. The load +addresses of the sections are arranged such that they are consecutive in +memory starting at the load address used for the @code{OVERLAY} as a +whole (as with normal section definitions, the load address is optional, +and defaults to the start address; the start address is also optional, +and defaults to the current value of the location counter). + +If the @code{NOCROSSREFS} keyword is used, and there are any +references among the sections, the linker will report an error. Since +the sections all run at the same address, it normally does not make +sense for one section to refer directly to another. +@xref{Miscellaneous Commands, NOCROSSREFS}. + +For each section within the @code{OVERLAY}, the linker automatically +provides two symbols. The symbol @code{__load_start_@var{secname}} is +defined as the starting load address of the section. The symbol +@code{__load_stop_@var{secname}} is defined as the final load address of +the section. Any characters within @var{secname} which are not legal +within C identifiers are removed. C (or assembler) code may use these +symbols to move the overlaid sections around as necessary. + +At the end of the overlay, the value of the location counter is set to +the start address of the overlay plus the size of the largest section. + +Here is an example. Remember that this would appear inside a +@code{SECTIONS} construct. +@smallexample +@group + OVERLAY 0x1000 : AT (0x4000) + @{ + .text0 @{ o1/*.o(.text) @} + .text1 @{ o2/*.o(.text) @} + @} +@end group +@end smallexample +@noindent +This will define both @samp{.text0} and @samp{.text1} to start at +address 0x1000. @samp{.text0} will be loaded at address 0x4000, and +@samp{.text1} will be loaded immediately after @samp{.text0}. The +following symbols will be defined if referenced: @code{__load_start_text0}, +@code{__load_stop_text0}, @code{__load_start_text1}, +@code{__load_stop_text1}. + +C code to copy overlay @code{.text1} into the overlay area might look +like the following. + +@smallexample +@group + extern char __load_start_text1, __load_stop_text1; + memcpy ((char *) 0x1000, &__load_start_text1, + &__load_stop_text1 - &__load_start_text1); +@end group +@end smallexample + +Note that the @code{OVERLAY} command is just syntactic sugar, since +everything it does can be done using the more basic commands. The above +example could have been written identically as follows. + +@smallexample +@group + .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @} + PROVIDE (__load_start_text0 = LOADADDR (.text0)); + PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @} + PROVIDE (__load_start_text1 = LOADADDR (.text1)); + PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); +@end group +@end smallexample + +@node MEMORY +@section MEMORY Command +@kindex MEMORY +@cindex memory regions +@cindex regions of memory +@cindex allocating memory +@cindex discontinuous memory +The linker's default configuration permits allocation of all available +memory. You can override this by using the @code{MEMORY} command. + +The @code{MEMORY} command describes the location and size of blocks of +memory in the target. You can use it to describe which memory regions +may be used by the linker, and which memory regions it must avoid. You +can then assign sections to particular memory regions. The linker will +set section addresses based on the memory regions, and will warn about +regions that become too full. The linker will not shuffle sections +around to fit into the available regions. + +A linker script may contain many uses of the @code{MEMORY} command, +however, all memory blocks defined are treated as if they were +specified inside a single @code{MEMORY} command. The syntax for +@code{MEMORY} is: +@smallexample +@group +MEMORY + @{ + @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len} + @dots{} + @} +@end group +@end smallexample + +The @var{name} is a name used in the linker script to refer to the +region. The region name has no meaning outside of the linker script. +Region names are stored in a separate name space, and will not conflict +with symbol names, file names, or section names. Each memory region +must have a distinct name within the @code{MEMORY} command. However you can +add later alias names to existing memory regions with the @ref{REGION_ALIAS} +command. + +@cindex memory region attributes +The @var{attr} string is an optional list of attributes that specify +whether to use a particular memory region for an input section which is +not explicitly mapped in the linker script. As described in +@ref{SECTIONS}, if you do not specify an output section for some input +section, the linker will create an output section with the same name as +the input section. If you define region attributes, the linker will use +them to select the memory region for the output section that it creates. + +The @var{attr} string must consist only of the following characters: +@table @samp +@item R +Read-only section +@item W +Read/write section +@item X +Executable section +@item A +Allocatable section +@item I +Initialized section +@item L +Same as @samp{I} +@item ! +Invert the sense of any of the attributes that follow +@end table + +If a unmapped section matches any of the listed attributes other than +@samp{!}, it will be placed in the memory region. The @samp{!} +attribute reverses this test, so that an unmapped section will be placed +in the memory region only if it does not match any of the listed +attributes. + +@kindex ORIGIN = +@kindex o = +@kindex org = +The @var{origin} is an numerical expression for the start address of +the memory region. The expression must evaluate to a constant and it +cannot involve any symbols. The keyword @code{ORIGIN} may be +abbreviated to @code{org} or @code{o} (but not, for example, +@code{ORG}). + +@kindex LENGTH = +@kindex len = +@kindex l = +The @var{len} is an expression for the size in bytes of the memory +region. As with the @var{origin} expression, the expression must +be numerical only and must evaluate to a constant. The keyword +@code{LENGTH} may be abbreviated to @code{len} or @code{l}. + +In the following example, we specify that there are two memory regions +available for allocation: one starting at @samp{0} for 256 kilobytes, +and the other starting at @samp{0x40000000} for four megabytes. The +linker will place into the @samp{rom} memory region every section which +is not explicitly mapped into a memory region, and is either read-only +or executable. The linker will place other sections which are not +explicitly mapped into a memory region into the @samp{ram} memory +region. + +@smallexample +@group +MEMORY + @{ + rom (rx) : ORIGIN = 0, LENGTH = 256K + ram (!rx) : org = 0x40000000, l = 4M + @} +@end group +@end smallexample + +Once you define a memory region, you can direct the linker to place +specific output sections into that memory region by using the +@samp{>@var{region}} output section attribute. For example, if you have +a memory region named @samp{mem}, you would use @samp{>mem} in the +output section definition. @xref{Output Section Region}. If no address +was specified for the output section, the linker will set the address to +the next available address within the memory region. If the combined +output sections directed to a memory region are too large for the +region, the linker will issue an error message. + +It is possible to access the origin and length of a memory in an +expression via the @code{ORIGIN(@var{memory})} and +@code{LENGTH(@var{memory})} functions: + +@smallexample +@group + _fstack = ORIGIN(ram) + LENGTH(ram) - 4; +@end group +@end smallexample + +@node PHDRS +@section PHDRS Command +@kindex PHDRS +@cindex program headers +@cindex ELF program headers +@cindex program segments +@cindex segments, ELF +The ELF object file format uses @dfn{program headers}, also knows as +@dfn{segments}. The program headers describe how the program should be +loaded into memory. You can print them out by using the @code{objdump} +program with the @samp{-p} option. + +When you run an ELF program on a native ELF system, the system loader +reads the program headers in order to figure out how to load the +program. This will only work if the program headers are set correctly. +This manual does not describe the details of how the system loader +interprets program headers; for more information, see the ELF ABI. + +The linker will create reasonable program headers by default. However, +in some cases, you may need to specify the program headers more +precisely. You may use the @code{PHDRS} command for this purpose. When +the linker sees the @code{PHDRS} command in the linker script, it will +not create any program headers other than the ones specified. + +The linker only pays attention to the @code{PHDRS} command when +generating an ELF output file. In other cases, the linker will simply +ignore @code{PHDRS}. + +This is the syntax of the @code{PHDRS} command. The words @code{PHDRS}, +@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords. + +@smallexample +@group +PHDRS +@{ + @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ] + [ FLAGS ( @var{flags} ) ] ; +@} +@end group +@end smallexample + +The @var{name} is used only for reference in the @code{SECTIONS} command +of the linker script. It is not put into the output file. Program +header names are stored in a separate name space, and will not conflict +with symbol names, file names, or section names. Each program header +must have a distinct name. The headers are processed in order and it +is usual for them to map to sections in ascending load address order. + +Certain program header types describe segments of memory which the +system loader will load from the file. In the linker script, you +specify the contents of these segments by placing allocatable output +sections in the segments. You use the @samp{:@var{phdr}} output section +attribute to place a section in a particular segment. @xref{Output +Section Phdr}. + +It is normal to put certain sections in more than one segment. This +merely implies that one segment of memory contains another. You may +repeat @samp{:@var{phdr}}, using it once for each segment which should +contain the section. + +If you place a section in one or more segments using @samp{:@var{phdr}}, +then the linker will place all subsequent allocatable sections which do +not specify @samp{:@var{phdr}} in the same segments. This is for +convenience, since generally a whole set of contiguous sections will be +placed in a single segment. You can use @code{:NONE} to override the +default segment and tell the linker to not put the section in any +segment at all. + +@kindex FILEHDR +@kindex PHDRS +You may use the @code{FILEHDR} and @code{PHDRS} keywords after +the program header type to further describe the contents of the segment. +The @code{FILEHDR} keyword means that the segment should include the ELF +file header. The @code{PHDRS} keyword means that the segment should +include the ELF program headers themselves. If applied to a loadable +segment (@code{PT_LOAD}), all prior loadable segments must have one of +these keywords. + +The @var{type} may be one of the following. The numbers indicate the +value of the keyword. + +@table @asis +@item @code{PT_NULL} (0) +Indicates an unused program header. + +@item @code{PT_LOAD} (1) +Indicates that this program header describes a segment to be loaded from +the file. + +@item @code{PT_DYNAMIC} (2) +Indicates a segment where dynamic linking information can be found. + +@item @code{PT_INTERP} (3) +Indicates a segment where the name of the program interpreter may be +found. + +@item @code{PT_NOTE} (4) +Indicates a segment holding note information. + +@item @code{PT_SHLIB} (5) +A reserved program header type, defined but not specified by the ELF +ABI. + +@item @code{PT_PHDR} (6) +Indicates a segment where the program headers may be found. + +@item @code{PT_TLS} (7) +Indicates a segment containing thread local storage. + +@item @var{expression} +An expression giving the numeric type of the program header. This may +be used for types not defined above. +@end table + +You can specify that a segment should be loaded at a particular address +in memory by using an @code{AT} expression. This is identical to the +@code{AT} command used as an output section attribute (@pxref{Output +Section LMA}). The @code{AT} command for a program header overrides the +output section attribute. + +The linker will normally set the segment flags based on the sections +which comprise the segment. You may use the @code{FLAGS} keyword to +explicitly specify the segment flags. The value of @var{flags} must be +an integer. It is used to set the @code{p_flags} field of the program +header. + +Here is an example of @code{PHDRS}. This shows a typical set of program +headers used on a native ELF system. + +@example +@group +PHDRS +@{ + headers PT_PHDR PHDRS ; + interp PT_INTERP ; + text PT_LOAD FILEHDR PHDRS ; + data PT_LOAD ; + dynamic PT_DYNAMIC ; +@} + +SECTIONS +@{ + . = SIZEOF_HEADERS; + .interp : @{ *(.interp) @} :text :interp + .text : @{ *(.text) @} :text + .rodata : @{ *(.rodata) @} /* defaults to :text */ + @dots{} + . = . + 0x1000; /* move to a new page in memory */ + .data : @{ *(.data) @} :data + .dynamic : @{ *(.dynamic) @} :data :dynamic + @dots{} +@} +@end group +@end example + +@node VERSION +@section VERSION Command +@kindex VERSION @{script text@} +@cindex symbol versions +@cindex version script +@cindex versions of symbols +The linker supports symbol versions when using ELF. Symbol versions are +only useful when using shared libraries. The dynamic linker can use +symbol versions to select a specific version of a function when it runs +a program that may have been linked against an earlier version of the +shared library. + +You can include a version script directly in the main linker script, or +you can supply the version script as an implicit linker script. You can +also use the @samp{--version-script} linker option. + +The syntax of the @code{VERSION} command is simply +@smallexample +VERSION @{ version-script-commands @} +@end smallexample + +The format of the version script commands is identical to that used by +Sun's linker in Solaris 2.5. The version script defines a tree of +version nodes. You specify the node names and interdependencies in the +version script. You can specify which symbols are bound to which +version nodes, and you can reduce a specified set of symbols to local +scope so that they are not globally visible outside of the shared +library. + +The easiest way to demonstrate the version script language is with a few +examples. + +@smallexample +VERS_1.1 @{ + global: + foo1; + local: + old*; + original*; + new*; +@}; + +VERS_1.2 @{ + foo2; +@} VERS_1.1; + +VERS_2.0 @{ + bar1; bar2; + extern "C++" @{ + ns::*; + "f(int, double)"; + @}; +@} VERS_1.2; +@end smallexample + +This example version script defines three version nodes. The first +version node defined is @samp{VERS_1.1}; it has no other dependencies. +The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces +a number of symbols to local scope so that they are not visible outside +of the shared library; this is done using wildcard patterns, so that any +symbol whose name begins with @samp{old}, @samp{original}, or @samp{new} +is matched. The wildcard patterns available are the same as those used +in the shell when matching filenames (also known as ``globbing''). +However, if you specify the symbol name inside double quotes, then the +name is treated as literal, rather than as a glob pattern. + +Next, the version script defines node @samp{VERS_1.2}. This node +depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2} +to the version node @samp{VERS_1.2}. + +Finally, the version script defines node @samp{VERS_2.0}. This node +depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1} +and @samp{bar2} are bound to the version node @samp{VERS_2.0}. + +When the linker finds a symbol defined in a library which is not +specifically bound to a version node, it will effectively bind it to an +unspecified base version of the library. You can bind all otherwise +unspecified symbols to a given version node by using @samp{global: *;} +somewhere in the version script. Note that it's slightly crazy to use +wildcards in a global spec except on the last version node. Global +wildcards elsewhere run the risk of accidentally adding symbols to the +set exported for an old version. That's wrong since older versions +ought to have a fixed set of symbols. + +The names of the version nodes have no specific meaning other than what +they might suggest to the person reading them. The @samp{2.0} version +could just as well have appeared in between @samp{1.1} and @samp{1.2}. +However, this would be a confusing way to write a version script. + +Node name can be omitted, provided it is the only version node +in the version script. Such version script doesn't assign any versions to +symbols, only selects which symbols will be globally visible out and which +won't. + +@smallexample +@{ global: foo; bar; local: *; @}; +@end smallexample + +When you link an application against a shared library that has versioned +symbols, the application itself knows which version of each symbol it +requires, and it also knows which version nodes it needs from each +shared library it is linked against. Thus at runtime, the dynamic +loader can make a quick check to make sure that the libraries you have +linked against do in fact supply all of the version nodes that the +application will need to resolve all of the dynamic symbols. In this +way it is possible for the dynamic linker to know with certainty that +all external symbols that it needs will be resolvable without having to +search for each symbol reference. + +The symbol versioning is in effect a much more sophisticated way of +doing minor version checking that SunOS does. The fundamental problem +that is being addressed here is that typically references to external +functions are bound on an as-needed basis, and are not all bound when +the application starts up. If a shared library is out of date, a +required interface may be missing; when the application tries to use +that interface, it may suddenly and unexpectedly fail. With symbol +versioning, the user will get a warning when they start their program if +the libraries being used with the application are too old. + +There are several GNU extensions to Sun's versioning approach. The +first of these is the ability to bind a symbol to a version node in the +source file where the symbol is defined instead of in the versioning +script. This was done mainly to reduce the burden on the library +maintainer. You can do this by putting something like: +@smallexample +__asm__(".symver original_foo,foo@@VERS_1.1"); +@end smallexample +@noindent +in the C source file. This renames the function @samp{original_foo} to +be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}. +The @samp{local:} directive can be used to prevent the symbol +@samp{original_foo} from being exported. A @samp{.symver} directive +takes precedence over a version script. + +The second GNU extension is to allow multiple versions of the same +function to appear in a given shared library. In this way you can make +an incompatible change to an interface without increasing the major +version number of the shared library, while still allowing applications +linked against the old interface to continue to function. + +To do this, you must use multiple @samp{.symver} directives in the +source file. Here is an example: + +@smallexample +__asm__(".symver original_foo,foo@@"); +__asm__(".symver old_foo,foo@@VERS_1.1"); +__asm__(".symver old_foo1,foo@@VERS_1.2"); +__asm__(".symver new_foo,foo@@@@VERS_2.0"); +@end smallexample + +In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the +unspecified base version of the symbol. The source file that contains this +example would define 4 C functions: @samp{original_foo}, @samp{old_foo}, +@samp{old_foo1}, and @samp{new_foo}. + +When you have multiple definitions of a given symbol, there needs to be +some way to specify a default version to which external references to +this symbol will be bound. You can do this with the +@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only +declare one version of a symbol as the default in this manner; otherwise +you would effectively have multiple definitions of the same symbol. + +If you wish to bind a reference to a specific version of the symbol +within the shared library, you can use the aliases of convenience +(i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to +specifically bind to an external version of the function in question. + +You can also specify the language in the version script: + +@smallexample +VERSION extern "lang" @{ version-script-commands @} +@end smallexample + +The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}. +The linker will iterate over the list of symbols at the link time and +demangle them according to @samp{lang} before matching them to the +patterns specified in @samp{version-script-commands}. The default +@samp{lang} is @samp{C}. + +Demangled names may contains spaces and other special characters. As +described above, you can use a glob pattern to match demangled names, +or you can use a double-quoted string to match the string exactly. In +the latter case, be aware that minor differences (such as differing +whitespace) between the version script and the demangler output will +cause a mismatch. As the exact string generated by the demangler +might change in the future, even if the mangled name does not, you +should check that all of your version directives are behaving as you +expect when you upgrade. + +@node Expressions +@section Expressions in Linker Scripts +@cindex expressions +@cindex arithmetic +The syntax for expressions in the linker script language is identical to +that of C expressions. All expressions are evaluated as integers. All +expressions are evaluated in the same size, which is 32 bits if both the +host and target are 32 bits, and is otherwise 64 bits. + +You can use and set symbol values in expressions. + +The linker defines several special purpose builtin functions for use in +expressions. + +@menu +* Constants:: Constants +* Symbolic Constants:: Symbolic constants +* Symbols:: Symbol Names +* Orphan Sections:: Orphan Sections +* Location Counter:: The Location Counter +* Operators:: Operators +* Evaluation:: Evaluation +* Expression Section:: The Section of an Expression +* Builtin Functions:: Builtin Functions +@end menu + +@node Constants +@subsection Constants +@cindex integer notation +@cindex constants in linker scripts +All constants are integers. + +As in C, the linker considers an integer beginning with @samp{0} to be +octal, and an integer beginning with @samp{0x} or @samp{0X} to be +hexadecimal. Alternatively the linker accepts suffixes of @samp{h} or +@samp{H} for hexadecimal, @samp{o} or @samp{O} for octal, @samp{b} or +@samp{B} for binary and @samp{d} or @samp{D} for decimal. Any integer +value without a prefix or a suffix is considered to be decimal. + +@cindex scaled integers +@cindex K and M integer suffixes +@cindex M and K integer suffixes +@cindex suffixes for integers +@cindex integer suffixes +In addition, you can use the suffixes @code{K} and @code{M} to scale a +constant by +@c TEXI2ROFF-KILL +@ifnottex +@c END TEXI2ROFF-KILL +@code{1024} or @code{1024*1024} +@c TEXI2ROFF-KILL +@end ifnottex +@tex +${\rm 1024}$ or ${\rm 1024}^2$ +@end tex +@c END TEXI2ROFF-KILL +respectively. For example, the following +all refer to the same quantity: + +@smallexample +_fourk_1 = 4K; +_fourk_2 = 4096; +_fourk_3 = 0x1000; +_fourk_4 = 10000o; +@end smallexample + +Note - the @code{K} and @code{M} suffixes cannot be used in +conjunction with the base suffixes mentioned above. + +@node Symbolic Constants +@subsection Symbolic Constants +@cindex symbolic constants +@kindex CONSTANT +It is possible to refer to target specific constants via the use of +the @code{CONSTANT(@var{name})} operator, where @var{name} is one of: + +@table @code +@item MAXPAGESIZE +@kindex MAXPAGESIZE +The target's maximum page size. + +@item COMMONPAGESIZE +@kindex COMMONPAGESIZE +The target's default page size. +@end table + +So for example: + +@smallexample + .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @} +@end smallexample + +will create a text section aligned to the largest page boundary +supported by the target. + +@node Symbols +@subsection Symbol Names +@cindex symbol names +@cindex names +@cindex quoted symbol names +@kindex " +Unless quoted, symbol names start with a letter, underscore, or period +and may include letters, digits, underscores, periods, and hyphens. +Unquoted symbol names must not conflict with any keywords. You can +specify a symbol which contains odd characters or has the same name as a +keyword by surrounding the symbol name in double quotes: +@smallexample +"SECTION" = 9; +"with a space" = "also with a space" + 10; +@end smallexample + +Since symbols can contain many non-alphabetic characters, it is safest +to delimit symbols with spaces. For example, @samp{A-B} is one symbol, +whereas @samp{A - B} is an expression involving subtraction. + +@node Orphan Sections +@subsection Orphan Sections +@cindex orphan +Orphan sections are sections present in the input files which +are not explicitly placed into the output file by the linker +script. The linker will still copy these sections into the +output file by either finding, or creating a suitable output section +in which to place the orphaned input section. + +If the name of an orphaned input section exactly matches the name of +an existing output section, then the orphaned input section will be +placed at the end of that output section. + +If there is no output section with a matching name then new output +sections will be created. Each new output section will have the same +name as the orphan section placed within it. If there are multiple +orphan sections with the same name, these will all be combined into +one new output section. + +If new output sections are created to hold orphaned input sections, +then the linker must decide where to place these new output sections +in relation to existing output sections. On most modern targets, the +linker attempts to place orphan sections after sections of the same +attribute, such as code vs data, loadable vs non-loadable, etc. If no +sections with matching attributes are found, or your target lacks this +support, the orphan section is placed at the end of the file. + +The command line options @samp{--orphan-handling} and @samp{--unique} +(@pxref{Options,,Command Line Options}) can be used to control which +output sections an orphan is placed in. + +@node Location Counter +@subsection The Location Counter +@kindex . +@cindex dot +@cindex location counter +@cindex current output location +The special linker variable @dfn{dot} @samp{.} always contains the +current output location counter. Since the @code{.} always refers to a +location in an output section, it may only appear in an expression +within a @code{SECTIONS} command. The @code{.} symbol may appear +anywhere that an ordinary symbol is allowed in an expression. + +@cindex holes +Assigning a value to @code{.} will cause the location counter to be +moved. This may be used to create holes in the output section. The +location counter may not be moved backwards inside an output section, +and may not be moved backwards outside of an output section if so +doing creates areas with overlapping LMAs. + +@smallexample +SECTIONS +@{ + output : + @{ + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + @} = 0x12345678; +@} +@end smallexample +@noindent +In the previous example, the @samp{.text} section from @file{file1} is +located at the beginning of the output section @samp{output}. It is +followed by a 1000 byte gap. Then the @samp{.text} section from +@file{file2} appears, also with a 1000 byte gap following before the +@samp{.text} section from @file{file3}. The notation @samp{= 0x12345678} +specifies what data to write in the gaps (@pxref{Output Section Fill}). + +@cindex dot inside sections +Note: @code{.} actually refers to the byte offset from the start of the +current containing object. Normally this is the @code{SECTIONS} +statement, whose start address is 0, hence @code{.} can be used as an +absolute address. If @code{.} is used inside a section description +however, it refers to the byte offset from the start of that section, +not an absolute address. Thus in a script like this: + +@smallexample +SECTIONS +@{ + . = 0x100 + .text: @{ + *(.text) + . = 0x200 + @} + . = 0x500 + .data: @{ + *(.data) + . += 0x600 + @} +@} +@end smallexample + +The @samp{.text} section will be assigned a starting address of 0x100 +and a size of exactly 0x200 bytes, even if there is not enough data in +the @samp{.text} input sections to fill this area. (If there is too +much data, an error will be produced because this would be an attempt to +move @code{.} backwards). The @samp{.data} section will start at 0x500 +and it will have an extra 0x600 bytes worth of space after the end of +the values from the @samp{.data} input sections and before the end of +the @samp{.data} output section itself. + +@cindex dot outside sections +Setting symbols to the value of the location counter outside of an +output section statement can result in unexpected values if the linker +needs to place orphan sections. For example, given the following: + +@smallexample +SECTIONS +@{ + start_of_text = . ; + .text: @{ *(.text) @} + end_of_text = . ; + + start_of_data = . ; + .data: @{ *(.data) @} + end_of_data = . ; +@} +@end smallexample + +If the linker needs to place some input section, e.g. @code{.rodata}, +not mentioned in the script, it might choose to place that section +between @code{.text} and @code{.data}. You might think the linker +should place @code{.rodata} on the blank line in the above script, but +blank lines are of no particular significance to the linker. As well, +the linker doesn't associate the above symbol names with their +sections. Instead, it assumes that all assignments or other +statements belong to the previous output section, except for the +special case of an assignment to @code{.}. I.e., the linker will +place the orphan @code{.rodata} section as if the script was written +as follows: + +@smallexample +SECTIONS +@{ + start_of_text = . ; + .text: @{ *(.text) @} + end_of_text = . ; + + start_of_data = . ; + .rodata: @{ *(.rodata) @} + .data: @{ *(.data) @} + end_of_data = . ; +@} +@end smallexample + +This may or may not be the script author's intention for the value of +@code{start_of_data}. One way to influence the orphan section +placement is to assign the location counter to itself, as the linker +assumes that an assignment to @code{.} is setting the start address of +a following output section and thus should be grouped with that +section. So you could write: + +@smallexample +SECTIONS +@{ + start_of_text = . ; + .text: @{ *(.text) @} + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: @{ *(.data) @} + end_of_data = . ; +@} +@end smallexample + +Now, the orphan @code{.rodata} section will be placed between +@code{end_of_text} and @code{start_of_data}. + +@need 2000 +@node Operators +@subsection Operators +@cindex operators for arithmetic +@cindex arithmetic operators +@cindex precedence in expressions +The linker recognizes the standard C set of arithmetic operators, with +the standard bindings and precedence levels: +@c TEXI2ROFF-KILL +@ifnottex +@c END TEXI2ROFF-KILL +@smallexample +precedence associativity Operators Notes +(highest) +1 left ! - ~ (1) +2 left * / % +3 left + - +4 left >> << +5 left == != > < <= >= +6 left & +7 left | +8 left && +9 left || +10 right ? : +11 right &= += -= *= /= (2) +(lowest) +@end smallexample +Notes: +(1) Prefix operators +(2) @xref{Assignments}. +@c TEXI2ROFF-KILL +@end ifnottex +@tex +\vskip \baselineskip +%"lispnarrowing" is the extra indent used generally for smallexample +\hskip\lispnarrowing\vbox{\offinterlineskip +\hrule +\halign +{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr +height2pt&\omit&&\omit&&\omit&\cr +&Precedence&& Associativity &&{\rm Operators}&\cr +height2pt&\omit&&\omit&&\omit&\cr +\noalign{\hrule} +height2pt&\omit&&\omit&&\omit&\cr +&highest&&&&&\cr +% '176 is tilde, '~' in tt font +&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr +&2&&left&&* / \%&\cr +&3&&left&&+ -&\cr +&4&&left&&>> <<&\cr +&5&&left&&== != > < <= >=&\cr +&6&&left&&\&&\cr +&7&&left&&|&\cr +&8&&left&&{\&\&}&\cr +&9&&left&&||&\cr +&10&&right&&? :&\cr +&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr +&lowest&&&&&\cr +height2pt&\omit&&\omit&&\omit&\cr} +\hrule} +@end tex +@iftex +{ +@obeylines@parskip=0pt@parindent=0pt +@dag@quad Prefix operators. +@ddag@quad @xref{Assignments}. +} +@end iftex +@c END TEXI2ROFF-KILL + +@node Evaluation +@subsection Evaluation +@cindex lazy evaluation +@cindex expression evaluation order +The linker evaluates expressions lazily. It only computes the value of +an expression when absolutely necessary. + +The linker needs some information, such as the value of the start +address of the first section, and the origins and lengths of memory +regions, in order to do any linking at all. These values are computed +as soon as possible when the linker reads in the linker script. + +However, other values (such as symbol values) are not known or needed +until after storage allocation. Such values are evaluated later, when +other information (such as the sizes of output sections) is available +for use in the symbol assignment expression. + +The sizes of sections cannot be known until after allocation, so +assignments dependent upon these are not performed until after +allocation. + +Some expressions, such as those depending upon the location counter +@samp{.}, must be evaluated during section allocation. + +If the result of an expression is required, but the value is not +available, then an error results. For example, a script like the +following +@smallexample +@group +SECTIONS + @{ + .text 9+this_isnt_constant : + @{ *(.text) @} + @} +@end group +@end smallexample +@noindent +will cause the error message @samp{non constant expression for initial +address}. + +@node Expression Section +@subsection The Section of an Expression +@cindex expression sections +@cindex absolute expressions +@cindex relative expressions +@cindex absolute and relocatable symbols +@cindex relocatable and absolute symbols +@cindex symbols, relocatable and absolute +Addresses and symbols may be section relative, or absolute. A section +relative symbol is relocatable. If you request relocatable output +using the @samp{-r} option, a further link operation may change the +value of a section relative symbol. On the other hand, an absolute +symbol will retain the same value throughout any further link +operations. + +Some terms in linker expressions are addresses. This is true of +section relative symbols and for builtin functions that return an +address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and +@code{SEGMENT_START}. Other terms are simply numbers, or are builtin +functions that return a non-address value, such as @code{LENGTH}. +One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")} +(@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated +differently depending on their location, for compatibility with older +versions of @code{ld}. Expressions appearing outside an output +section definition treat all numbers as absolute addresses. +Expressions appearing inside an output section definition treat +absolute symbols as numbers. If @code{LD_FEATURE ("SANE_EXPR")} is +given, then absolute symbols and numbers are simply treated as numbers +everywhere. + +In the following simple example, + +@smallexample +@group +SECTIONS + @{ + . = 0x100; + __executable_start = 0x100; + .data : + @{ + . = 0x10; + __data_start = 0x10; + *(.data) + @} + @dots{} + @} +@end group +@end smallexample + +both @code{.} and @code{__executable_start} are set to the absolute +address 0x100 in the first two assignments, then both @code{.} and +@code{__data_start} are set to 0x10 relative to the @code{.data} +section in the second two assignments. + +For expressions involving numbers, relative addresses and absolute +addresses, ld follows these rules to evaluate terms: + +@itemize @bullet +@item +Unary operations on an absolute address or number, and binary +operations on two absolute addresses or two numbers, or between one +absolute address and a number, apply the operator to the value(s). +@item +Unary operations on a relative address, and binary operations on two +relative addresses in the same section or between one relative address +and a number, apply the operator to the offset part of the address(es). +@item +Other binary operations, that is, between two relative addresses not +in the same section, or between a relative address and an absolute +address, first convert any non-absolute term to an absolute address +before applying the operator. +@end itemize + +The result section of each sub-expression is as follows: + +@itemize @bullet +@item +An operation involving only numbers results in a number. +@item +The result of comparisons, @samp{&&} and @samp{||} is also a number. +@item +The result of other binary arithmetic and logical operations on two +relative addresses in the same section or two absolute addresses +(after above conversions) is also a number when +@code{LD_FEATURE ("SANE_EXPR")} or inside an output section definition +but an absolute address otherwise. +@item +The result of other operations on relative addresses or one +relative address and a number, is a relative address in the same +section as the relative operand(s). +@item +The result of other operations on absolute addresses (after above +conversions) is an absolute address. +@end itemize + +You can use the builtin function @code{ABSOLUTE} to force an expression +to be absolute when it would otherwise be relative. For example, to +create an absolute symbol set to the address of the end of the output +section @samp{.data}: +@smallexample +SECTIONS + @{ + .data : @{ *(.data) _edata = ABSOLUTE(.); @} + @} +@end smallexample +@noindent +If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the +@samp{.data} section. + +Using @code{LOADADDR} also forces an expression absolute, since this +particular builtin function returns an absolute address. + +@node Builtin Functions +@subsection Builtin Functions +@cindex functions in expressions +The linker script language includes a number of builtin functions for +use in linker script expressions. + +@table @code +@item ABSOLUTE(@var{exp}) +@kindex ABSOLUTE(@var{exp}) +@cindex expression, absolute +Return the absolute (non-relocatable, as opposed to non-negative) value +of the expression @var{exp}. Primarily useful to assign an absolute +value to a symbol within a section definition, where symbol values are +normally section relative. @xref{Expression Section}. + +@item ADDR(@var{section}) +@kindex ADDR(@var{section}) +@cindex section address in expression +Return the address (VMA) of the named @var{section}. Your +script must previously have defined the location of that section. In +the following example, @code{start_of_output_1}, @code{symbol_1} and +@code{symbol_2} are assigned equivalent values, except that +@code{symbol_1} will be relative to the @code{.output1} section while +the other two will be absolute: +@smallexample +@group +SECTIONS @{ @dots{} + .output1 : + @{ + start_of_output_1 = ABSOLUTE(.); + @dots{} + @} + .output : + @{ + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + @} +@dots{} @} +@end group +@end smallexample + +@item ALIGN(@var{align}) +@itemx ALIGN(@var{exp},@var{align}) +@kindex ALIGN(@var{align}) +@kindex ALIGN(@var{exp},@var{align}) +@cindex round up location counter +@cindex align location counter +@cindex round up expression +@cindex align expression +Return the location counter (@code{.}) or arbitrary expression aligned +to the next @var{align} boundary. The single operand @code{ALIGN} +doesn't change the value of the location counter---it just does +arithmetic on it. The two operand @code{ALIGN} allows an arbitrary +expression to be aligned upwards (@code{ALIGN(@var{align})} is +equivalent to @code{ALIGN(ABSOLUTE(.), @var{align})}). + +Here is an example which aligns the output @code{.data} section to the +next @code{0x2000} byte boundary after the preceding section and sets a +variable within the section to the next @code{0x8000} boundary after the +input sections: +@smallexample +@group +SECTIONS @{ @dots{} + .data ALIGN(0x2000): @{ + *(.data) + variable = ALIGN(0x8000); + @} +@dots{} @} +@end group +@end smallexample +@noindent +The first use of @code{ALIGN} in this example specifies the location of +a section because it is used as the optional @var{address} attribute of +a section definition (@pxref{Output Section Address}). The second use +of @code{ALIGN} is used to defines the value of a symbol. + +The builtin function @code{NEXT} is closely related to @code{ALIGN}. + +@item ALIGNOF(@var{section}) +@kindex ALIGNOF(@var{section}) +@cindex section alignment +Return the alignment in bytes of the named @var{section}, if that section has +been allocated. If the section has not been allocated when this is +evaluated, the linker will report an error. In the following example, +the alignment of the @code{.output} section is stored as the first +value in that section. +@smallexample +@group +SECTIONS@{ @dots{} + .output @{ + LONG (ALIGNOF (.output)) + @dots{} + @} +@dots{} @} +@end group +@end smallexample + +@item BLOCK(@var{exp}) +@kindex BLOCK(@var{exp}) +This is a synonym for @code{ALIGN}, for compatibility with older linker +scripts. It is most often seen when setting the address of an output +section. + +@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize}) +@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize}) +This is equivalent to either +@smallexample +(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1))) +@end smallexample +or +@smallexample +(ALIGN(@var{maxpagesize}) + + ((. + @var{commonpagesize} - 1) & (@var{maxpagesize} - @var{commonpagesize}))) +@end smallexample +@noindent +depending on whether the latter uses fewer @var{commonpagesize} sized pages +for the data segment (area between the result of this expression and +@code{DATA_SEGMENT_END}) than the former or not. +If the latter form is used, it means @var{commonpagesize} bytes of runtime +memory will be saved at the expense of up to @var{commonpagesize} wasted +bytes in the on-disk file. + +This expression can only be used directly in @code{SECTIONS} commands, not in +any output section descriptions and only once in the linker script. +@var{commonpagesize} should be less or equal to @var{maxpagesize} and should +be the system page size the object wants to be optimized for while still +running on system page sizes up to @var{maxpagesize}. Note however +that @samp{-z relro} protection will not be effective if the system +page size is larger than @var{commonpagesize}. + +@noindent +Example: +@smallexample + . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); +@end smallexample + +@item DATA_SEGMENT_END(@var{exp}) +@kindex DATA_SEGMENT_END(@var{exp}) +This defines the end of data segment for @code{DATA_SEGMENT_ALIGN} +evaluation purposes. + +@smallexample + . = DATA_SEGMENT_END(.); +@end smallexample + +@item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp}) +@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp}) +This defines the end of the @code{PT_GNU_RELRO} segment when +@samp{-z relro} option is used. +When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END} +does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that +@var{exp} + @var{offset} is aligned to the @var{commonpagesize} +argument given to @code{DATA_SEGMENT_ALIGN}. If present in the linker +script, it must be placed between @code{DATA_SEGMENT_ALIGN} and +@code{DATA_SEGMENT_END}. Evaluates to the second argument plus any +padding needed at the end of the @code{PT_GNU_RELRO} segment due to +section alignment. + +@smallexample + . = DATA_SEGMENT_RELRO_END(24, .); +@end smallexample + +@item DEFINED(@var{symbol}) +@kindex DEFINED(@var{symbol}) +@cindex symbol defaults +Return 1 if @var{symbol} is in the linker global symbol table and is +defined before the statement using DEFINED in the script, otherwise +return 0. You can use this function to provide +default values for symbols. For example, the following script fragment +shows how to set a global symbol @samp{begin} to the first location in +the @samp{.text} section---but if a symbol called @samp{begin} already +existed, its value is preserved: + +@smallexample +@group +SECTIONS @{ @dots{} + .text : @{ + begin = DEFINED(begin) ? begin : . ; + @dots{} + @} + @dots{} +@} +@end group +@end smallexample + +@item LENGTH(@var{memory}) +@kindex LENGTH(@var{memory}) +Return the length of the memory region named @var{memory}. + +@item LOADADDR(@var{section}) +@kindex LOADADDR(@var{section}) +@cindex section load address in expression +Return the absolute LMA of the named @var{section}. (@pxref{Output +Section LMA}). + +@item LOG2CEIL(@var{exp}) +@kindex LOG2CEIL(@var{exp}) +Return the binary logarithm of @var{exp} rounded towards infinity. +@code{LOG2CEIL(0)} returns 0. + +@kindex MAX +@item MAX(@var{exp1}, @var{exp2}) +Returns the maximum of @var{exp1} and @var{exp2}. + +@kindex MIN +@item MIN(@var{exp1}, @var{exp2}) +Returns the minimum of @var{exp1} and @var{exp2}. + +@item NEXT(@var{exp}) +@kindex NEXT(@var{exp}) +@cindex unallocated address, next +Return the next unallocated address that is a multiple of @var{exp}. +This function is closely related to @code{ALIGN(@var{exp})}; unless you +use the @code{MEMORY} command to define discontinuous memory for the +output file, the two functions are equivalent. + +@item ORIGIN(@var{memory}) +@kindex ORIGIN(@var{memory}) +Return the origin of the memory region named @var{memory}. + +@item SEGMENT_START(@var{segment}, @var{default}) +@kindex SEGMENT_START(@var{segment}, @var{default}) +Return the base address of the named @var{segment}. If an explicit +value has already been given for this segment (with a command-line +@samp{-T} option) then that value will be returned otherwise the value +will be @var{default}. At present, the @samp{-T} command-line option +can only be used to set the base address for the ``text'', ``data'', and +``bss'' sections, but you can use @code{SEGMENT_START} with any segment +name. + +@item SIZEOF(@var{section}) +@kindex SIZEOF(@var{section}) +@cindex section size +Return the size in bytes of the named @var{section}, if that section has +been allocated. If the section has not been allocated when this is +evaluated, the linker will report an error. In the following example, +@code{symbol_1} and @code{symbol_2} are assigned identical values: +@smallexample +@group +SECTIONS@{ @dots{} + .output @{ + .start = . ; + @dots{} + .end = . ; + @} + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); +@dots{} @} +@end group +@end smallexample + +@item SIZEOF_HEADERS +@itemx sizeof_headers +@kindex SIZEOF_HEADERS +@cindex header size +Return the size in bytes of the output file's headers. This is +information which appears at the start of the output file. You can use +this number when setting the start address of the first section, if you +choose, to facilitate paging. + +@cindex not enough room for program headers +@cindex program headers, not enough room +When producing an ELF output file, if the linker script uses the +@code{SIZEOF_HEADERS} builtin function, the linker must compute the +number of program headers before it has determined all the section +addresses and sizes. If the linker later discovers that it needs +additional program headers, it will report an error @samp{not enough +room for program headers}. To avoid this error, you must avoid using +the @code{SIZEOF_HEADERS} function, or you must rework your linker +script to avoid forcing the linker to use additional program headers, or +you must define the program headers yourself using the @code{PHDRS} +command (@pxref{PHDRS}). +@end table + +@node Implicit Linker Scripts +@section Implicit Linker Scripts +@cindex implicit linker scripts +If you specify a linker input file which the linker can not recognize as +an object file or an archive file, it will try to read the file as a +linker script. If the file can not be parsed as a linker script, the +linker will report an error. + +An implicit linker script will not replace the default linker script. + +Typically an implicit linker script would contain only symbol +assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION} +commands. + +Any input files read because of an implicit linker script will be read +at the position in the command line where the implicit linker script was +read. This can affect archive searching. + +@ifset GENERIC +@node Machine Dependent +@chapter Machine Dependent Features + +@cindex machine dependencies +@command{ld} has additional features on some platforms; the following +sections describe them. Machines where @command{ld} has no additional +functionality are not listed. + +@menu +@ifset H8300 +* H8/300:: @command{ld} and the H8/300 +@end ifset +@ifset M68HC11 +* M68HC11/68HC12:: @code{ld} and the Motorola 68HC11 and 68HC12 families +@end ifset +@ifset ARM +* ARM:: @command{ld} and the ARM family +@end ifset +@ifset HPPA +* HPPA ELF32:: @command{ld} and HPPA 32-bit ELF +@end ifset +@ifset M68K +* M68K:: @command{ld} and the Motorola 68K family +@end ifset +@ifset MIPS +* MIPS:: @command{ld} and the MIPS family +@end ifset +@ifset MMIX +* MMIX:: @command{ld} and MMIX +@end ifset +@ifset MSP430 +* MSP430:: @command{ld} and MSP430 +@end ifset +@ifset NDS32 +* NDS32:: @command{ld} and NDS32 +@end ifset +@ifset NIOSII +* Nios II:: @command{ld} and the Altera Nios II +@end ifset +@ifset POWERPC +* PowerPC ELF32:: @command{ld} and PowerPC 32-bit ELF Support +@end ifset +@ifset POWERPC64 +* PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support +@end ifset +@ifset S/390 +* S/390 ELF:: @command{ld} and S/390 ELF Support +@end ifset +@ifset SPU +* SPU ELF:: @command{ld} and SPU ELF Support +@end ifset +@ifset TICOFF +* TI COFF:: @command{ld} and TI COFF +@end ifset +@ifset WIN32 +* WIN32:: @command{ld} and WIN32 (cygwin/mingw) +@end ifset +@ifset XTENSA +* Xtensa:: @command{ld} and Xtensa Processors +@end ifset +@end menu +@end ifset + +@ifset H8300 +@ifclear GENERIC +@raisesections +@end ifclear + +@node H8/300 +@section @command{ld} and the H8/300 + +@cindex H8/300 support +For the H8/300, @command{ld} can perform these global optimizations when +you specify the @samp{--relax} command-line option. + +@table @emph +@cindex relaxing on H8/300 +@item relaxing address modes +@command{ld} finds all @code{jsr} and @code{jmp} instructions whose +targets are within eight bits, and turns them into eight-bit +program-counter relative @code{bsr} and @code{bra} instructions, +respectively. + +@cindex synthesizing on H8/300 +@item synthesizing instructions +@c FIXME: specifically mov.b, or any mov instructions really? -> mov.b only, at least on H8, H8H, H8S +@command{ld} finds all @code{mov.b} instructions which use the +sixteen-bit absolute address form, but refer to the top +page of memory, and changes them to use the eight-bit address form. +(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into +@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the +top page of memory). + +@command{ld} finds all @code{mov} instructions which use the register +indirect with 32-bit displacement addressing mode, but use a small +displacement inside 16-bit displacement range, and changes them to use +the 16-bit displacement form. (That is: the linker turns @samp{mov.b +@code{@@}@var{d}:32,ERx} into @samp{mov.b @code{@@}@var{d}:16,ERx} +whenever the displacement @var{d} is in the 16 bit signed integer +range. Only implemented in ELF-format ld). + +@item bit manipulation instructions +@command{ld} finds all bit manipulation instructions like @code{band, bclr, +biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor} +which use 32 bit and 16 bit absolute address form, but refer to the top +page of memory, and changes them to use the 8 bit address form. +(That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into +@samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in +the top page of memory). + +@item system control instructions +@command{ld} finds all @code{ldc.w, stc.w} instructions which use the +32 bit absolute address form, but refer to the top page of memory, and +changes them to use 16 bit address form. +(That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into +@samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in +the top page of memory). +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifclear GENERIC +@ifset Renesas +@c This stuff is pointless to say unless you're especially concerned +@c with Renesas chips; don't enable it for generic case, please. +@node Renesas +@chapter @command{ld} and Other Renesas Chips + +@command{ld} also supports the Renesas (formerly Hitachi) H8/300H, +H8/500, and SH chips. No special features, commands, or command-line +options are required for these chips. +@end ifset +@end ifclear + +@ifset ARM +@ifclear GENERIC +@raisesections +@end ifclear + +@ifset M68HC11 +@ifclear GENERIC +@raisesections +@end ifclear + +@node M68HC11/68HC12 +@section @command{ld} and the Motorola 68HC11 and 68HC12 families + +@cindex M68HC11 and 68HC12 support + +@subsection Linker Relaxation + +For the Motorola 68HC11, @command{ld} can perform these global +optimizations when you specify the @samp{--relax} command-line option. + +@table @emph +@cindex relaxing on M68HC11 +@item relaxing address modes +@command{ld} finds all @code{jsr} and @code{jmp} instructions whose +targets are within eight bits, and turns them into eight-bit +program-counter relative @code{bsr} and @code{bra} instructions, +respectively. + +@command{ld} also looks at all 16-bit extended addressing modes and +transforms them in a direct addressing mode when the address is in +page 0 (between 0 and 0x0ff). + +@item relaxing gcc instruction group +When @command{gcc} is called with @option{-mrelax}, it can emit group +of instructions that the linker can optimize to use a 68HC11 direct +addressing mode. These instructions consists of @code{bclr} or +@code{bset} instructions. + +@end table + +@subsection Trampoline Generation + +@cindex trampoline generation on M68HC11 +@cindex trampoline generation on M68HC12 +For 68HC11 and 68HC12, @command{ld} can generate trampoline code to +call a far function using a normal @code{jsr} instruction. The linker +will also change the relocation to some far function to use the +trampoline address instead of the function address. This is typically the +case when a pointer to a function is taken. The pointer will in fact +point to the function trampoline. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@node ARM +@section @command{ld} and the ARM family + +@cindex ARM interworking support +@kindex --support-old-code +For the ARM, @command{ld} will generate code stubs to allow functions calls +between ARM and Thumb code. These stubs only work with code that has +been compiled and assembled with the @samp{-mthumb-interwork} command +line option. If it is necessary to link with old ARM object files or +libraries, which have not been compiled with the -mthumb-interwork +option then the @samp{--support-old-code} command line switch should be +given to the linker. This will make it generate larger stub functions +which will work with non-interworking aware ARM code. Note, however, +the linker does not support generating stubs for function calls to +non-interworking aware Thumb code. + +@cindex thumb entry point +@cindex entry point, thumb +@kindex --thumb-entry=@var{entry} +The @samp{--thumb-entry} switch is a duplicate of the generic +@samp{--entry} switch, in that it sets the program's starting address. +But it also sets the bottom bit of the address, so that it can be +branched to using a BX instruction, and the program will start +executing in Thumb mode straight away. + +@cindex PE import table prefixing +@kindex --use-nul-prefixed-import-tables +The @samp{--use-nul-prefixed-import-tables} switch is specifying, that +the import tables idata4 and idata5 have to be generated with a zero +element prefix for import libraries. This is the old style to generate +import tables. By default this option is turned off. + +@cindex BE8 +@kindex --be8 +The @samp{--be8} switch instructs @command{ld} to generate BE8 format +executables. This option is only valid when linking big-endian +objects - ie ones which have been assembled with the @option{-EB} +option. The resulting image will contain big-endian data and +little-endian code. + +@cindex TARGET1 +@kindex --target1-rel +@kindex --target1-abs +The @samp{R_ARM_TARGET1} relocation is typically used for entries in the +@samp{.init_array} section. It is interpreted as either @samp{R_ARM_REL32} +or @samp{R_ARM_ABS32}, depending on the target. The @samp{--target1-rel} +and @samp{--target1-abs} switches override the default. + +@cindex TARGET2 +@kindex --target2=@var{type} +The @samp{--target2=type} switch overrides the default definition of the +@samp{R_ARM_TARGET2} relocation. Valid values for @samp{type}, their +meanings, and target defaults are as follows: +@table @samp +@item rel +@samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi) +@item abs +@samp{R_ARM_ABS32} (arm*-*-symbianelf) +@item got-rel +@samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd) +@end table + +@cindex FIX_V4BX +@kindex --fix-v4bx +The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF +specification) enables objects compiled for the ARMv4 architecture to be +interworking-safe when linked with other objects compiled for ARMv4t, but +also allows pure ARMv4 binaries to be built from the same ARMv4 objects. + +In the latter case, the switch @option{--fix-v4bx} must be passed to the +linker, which causes v4t @code{BX rM} instructions to be rewritten as +@code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction. + +In the former case, the switch should not be used, and @samp{R_ARM_V4BX} +relocations are ignored. + +@cindex FIX_V4BX_INTERWORKING +@kindex --fix-v4bx-interworking +Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX} +relocations with a branch to the following veneer: + +@smallexample +TST rM, #1 +MOVEQ PC, rM +BX Rn +@end smallexample + +This allows generation of libraries/applications that work on ARMv4 cores +and are still interworking safe. Note that the above veneer clobbers the +condition flags, so may cause incorrect program behavior in rare cases. + +@cindex USE_BLX +@kindex --use-blx +The @samp{--use-blx} switch enables the linker to use ARM/Thumb +BLX instructions (available on ARMv5t and above) in various +situations. Currently it is used to perform calls via the PLT from Thumb +code using BLX rather than using BX and a mode-switching stub before +each PLT entry. This should lead to such calls executing slightly faster. + +This option is enabled implicitly for SymbianOS, so there is no need to +specify it if you are using that target. + +@cindex VFP11_DENORM_FIX +@kindex --vfp11-denorm-fix +The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a +bug in certain VFP11 coprocessor hardware, which sometimes allows +instructions with denorm operands (which must be handled by support code) +to have those operands overwritten by subsequent instructions before +the support code can read the intended values. + +The bug may be avoided in scalar mode if you allow at least one +intervening instruction between a VFP11 instruction which uses a register +and another instruction which writes to the same register, or at least two +intervening instructions if vector mode is in use. The bug only affects +full-compliance floating-point mode: you do not need this workaround if +you are using "runfast" mode. Please contact ARM for further details. + +If you know you are using buggy VFP11 hardware, you can +enable this workaround by specifying the linker option +@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar +mode only, or @samp{--vfp-denorm-fix=vector} if you are using +vector mode (the latter also works for scalar code). The default is +@samp{--vfp-denorm-fix=none}. + +If the workaround is enabled, instructions are scanned for +potentially-troublesome sequences, and a veneer is created for each +such sequence which may trigger the erratum. The veneer consists of the +first instruction of the sequence and a branch back to the subsequent +instruction. The original instruction is then replaced with a branch to +the veneer. The extra cycles required to call and return from the veneer +are sufficient to avoid the erratum in both the scalar and vector cases. + +@cindex ARM1176 erratum workaround +@kindex --fix-arm1176 +@kindex --no-fix-arm1176 +The @samp{--fix-arm1176} switch enables a link-time workaround for an erratum +in certain ARM1176 processors. The workaround is enabled by default if you +are targeting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled +unconditionally by specifying @samp{--no-fix-arm1176}. + +Further information is available in the ``ARM1176JZ-S and ARM1176JZF-S +Programmer Advice Notice'' available on the ARM documentation website at: +http://infocenter.arm.com/. + +@cindex STM32L4xx erratum workaround +@kindex --fix-stm32l4xx-629360 + +The @samp{--fix-stm32l4xx-629360} switch enables a link-time +workaround for a bug in the bus matrix / memory controller for some of +the STM32 Cortex-M4 based products (STM32L4xx). When accessing +off-chip memory via the affected bus for bus reads of 9 words or more, +the bus can generate corrupt data and/or abort. These are only +core-initiated accesses (not DMA), and might affect any access: +integer loads such as LDM, POP and floating-point loads such as VLDM, +VPOP. Stores are not affected. + +The bug can be avoided by splitting memory accesses into the +necessary chunks to keep bus reads below 8 words. + +The workaround is not enabled by default, this is equivalent to use +@samp{--fix-stm32l4xx-629360=none}. If you know you are using buggy +STM32L4xx hardware, you can enable the workaround by specifying the +linker option @samp{--fix-stm32l4xx-629360}, or the equivalent +@samp{--fix-stm32l4xx-629360=default}. + +If the workaround is enabled, instructions are scanned for +potentially-troublesome sequences, and a veneer is created for each +such sequence which may trigger the erratum. The veneer consists in a +replacement sequence emulating the behaviour of the original one and a +branch back to the subsequent instruction. The original instruction is +then replaced with a branch to the veneer. + +The workaround does not always preserve the memory access order for +the LDMDB instruction, when the instruction loads the PC. + +The workaround is not able to handle problematic instructions when +they are in the middle of an IT block, since a branch is not allowed +there. In that case, the linker reports a warning and no replacement +occurs. + +The workaround is not able to replace problematic instructions with a +PC-relative branch instruction if the @samp{.text} section is too +large. In that case, when the branch that replaces the original code +cannot be encoded, the linker reports a warning and no replacement +occurs. + +@cindex NO_ENUM_SIZE_WARNING +@kindex --no-enum-size-warning +The @option{--no-enum-size-warning} switch prevents the linker from +warning when linking object files that specify incompatible EABI +enumeration size attributes. For example, with this switch enabled, +linking of an object file using 32-bit enumeration values with another +using enumeration values fitted into the smallest possible space will +not be diagnosed. + +@cindex NO_WCHAR_SIZE_WARNING +@kindex --no-wchar-size-warning +The @option{--no-wchar-size-warning} switch prevents the linker from +warning when linking object files that specify incompatible EABI +@code{wchar_t} size attributes. For example, with this switch enabled, +linking of an object file using 32-bit @code{wchar_t} values with another +using 16-bit @code{wchar_t} values will not be diagnosed. + +@cindex PIC_VENEER +@kindex --pic-veneer +The @samp{--pic-veneer} switch makes the linker use PIC sequences for +ARM/Thumb interworking veneers, even if the rest of the binary +is not PIC. This avoids problems on uClinux targets where +@samp{--emit-relocs} is used to generate relocatable binaries. + +@cindex STUB_GROUP_SIZE +@kindex --stub-group-size=@var{N} +The linker will automatically generate and insert small sequences of +code into a linked ARM ELF executable whenever an attempt is made to +perform a function call to a symbol that is too far away. The +placement of these sequences of instructions - called stubs - is +controlled by the command line option @option{--stub-group-size=N}. +The placement is important because a poor choice can create a need for +duplicate stubs, increasing the code size. The linker will try to +group stubs together in order to reduce interruptions to the flow of +code, but it needs guidance as to how big these groups should be and +where they should be placed. + +The value of @samp{N}, the parameter to the +@option{--stub-group-size=} option controls where the stub groups are +placed. If it is negative then all stubs are placed after the first +branch that needs them. If it is positive then the stubs can be +placed either before or after the branches that need them. If the +value of @samp{N} is 1 (either +1 or -1) then the linker will choose +exactly where to place groups of stubs, using its built in heuristics. +A value of @samp{N} greater than 1 (or smaller than -1) tells the +linker that a single group of stubs can service at most @samp{N} bytes +from the input sections. + +The default, if @option{--stub-group-size=} is not specified, is +@samp{N = +1}. + +Farcalls stubs insertion is fully supported for the ARM-EABI target +only, because it relies on object files properties not present +otherwise. + +@cindex Cortex-A8 erratum workaround +@kindex --fix-cortex-a8 +@kindex --no-fix-cortex-a8 +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}. + +The erratum only affects Thumb-2 code. Please contact ARM for further details. + +@cindex Cortex-A53 erratum 835769 workaround +@kindex --fix-cortex-a53-835769 +@kindex --no-fix-cortex-a53-835769 +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}. + +Please contact ARM for further details. + +@kindex --merge-exidx-entries +@kindex --no-merge-exidx-entries +@cindex Merging exidx entries +The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo. + +@kindex --long-plt +@cindex 32-bit PLT entries +The @samp{--long-plt} option enables the use of 16 byte PLT entries +which support up to 4Gb of code. The default is to use 12 byte PLT +entries which only support 512Mb of code. + +@kindex --no-apply-dynamic-relocs +@cindex AArch64 rela addend +The @samp{--no-apply-dynamic-relocs} option makes AArch64 linker do not apply +link-time values for dynamic relocations. + +@cindex Placement of SG veneers +All SG veneers are placed in the special output section @code{.gnu.sgstubs}. +Its start address must be set, either with the command line option +@samp{--section-start} or in a linker script, to indicate where to place these +veneers in memory. + +@kindex --cmse-implib +@cindex Secure gateway import library +The @samp{--cmse-implib} option requests that the import libraries +specified by the @samp{--out-implib} and @samp{--in-implib} options are +secure gateway import libraries, suitable for linking a non-secure +executable against secure code as per ARMv8-M Security Extensions. + +@kindex --in-implib=@var{file} +@cindex Input import library +The @samp{--in-implib=file} specifies an input import library whose symbols +must keep the same address in the executable being produced. A warning is +given if no @samp{--out-implib} is given but new symbols have been introduced +in the executable that should be listed in its import library. Otherwise, if +@samp{--out-implib} is specified, the symbols are added to the output import +library. A warning is also given if some symbols present in the input import +library have disappeared from the executable. This option is only effective +for Secure Gateway import libraries, ie. when @samp{--cmse-implib} is +specified. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset HPPA +@ifclear GENERIC +@raisesections +@end ifclear + +@node HPPA ELF32 +@section @command{ld} and HPPA 32-bit ELF Support +@cindex HPPA multiple sub-space stubs +@kindex --multi-subspace +When generating a shared library, @command{ld} will by default generate +import stubs suitable for use with a single sub-space application. +The @samp{--multi-subspace} switch causes @command{ld} to generate export +stubs, and different (larger) import stubs suitable for use with +multiple sub-spaces. + +@cindex HPPA stub grouping +@kindex --stub-group-size=@var{N} +Long branch stubs and import/export stubs are placed by @command{ld} in +stub sections located between groups of input sections. +@samp{--stub-group-size} specifies the maximum size of a group of input +sections handled by one stub section. Since branch offsets are signed, +a stub section may serve two groups of input sections, one group before +the stub section, and one group after it. However, when using +conditional branches that require stubs, it may be better (for branch +prediction) that stub sections only serve one group of input sections. +A negative value for @samp{N} chooses this scheme, ensuring that +branches to stubs always use a negative offset. Two special values of +@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct +@command{ld} to automatically size input section groups for the branch types +detected, with the same behaviour regarding stub placement as other +positive or negative values of @samp{N} respectively. + +Note that @samp{--stub-group-size} does not split input sections. A +single input section larger than the group size specified will of course +create a larger group (of one section). If input sections are too +large, it may not be possible for a branch to reach its stub. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset M68K +@ifclear GENERIC +@raisesections +@end ifclear + +@node M68K +@section @command{ld} and the Motorola 68K family + +@cindex Motorola 68K GOT generation +@kindex --got=@var{type} +The @samp{--got=@var{type}} option lets you choose the GOT generation scheme. +The choices are @samp{single}, @samp{negative}, @samp{multigot} and +@samp{target}. When @samp{target} is selected the linker chooses +the default GOT generation scheme for the current target. +@samp{single} tells the linker to generate a single GOT with +entries only at non-negative offsets. +@samp{negative} instructs the linker to generate a single GOT with +entries at both negative and positive offsets. Not all environments +support such GOTs. +@samp{multigot} allows the linker to generate several GOTs in the +output file. All GOT references from a single input object +file access the same GOT, but references from different input object +files might access different GOTs. Not all environments support such GOTs. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset MIPS +@ifclear GENERIC +@raisesections +@end ifclear + +@node MIPS +@section @command{ld} and the MIPS family + +@cindex MIPS microMIPS instruction choice selection +@kindex --insn32 +@kindex --no-insn32 +The @samp{--insn32} and @samp{--no-insn32} options control the choice of +microMIPS instructions used in code generated by the linker, such as that +in the PLT or lazy binding stubs, or in relaxation. If @samp{--insn32} is +used, then the linker only uses 32-bit instruction encodings. By default +or if @samp{--no-insn32} is used, all instruction encodings are used, +including 16-bit ones where possible. + +@cindex MIPS branch relocation check control +@kindex --ignore-branch-isa +@kindex --no-ignore-branch-isa +The @samp{--ignore-branch-isa} and @samp{--no-ignore-branch-isa} options +control branch relocation checks for invalid ISA mode transitions. If +@samp{--ignore-branch-isa} is used, then the linker accepts any branch +relocations and any ISA mode transition required is lost in relocation +calculation, except for some cases of @code{BAL} instructions which meet +relaxation conditions and are converted to equivalent @code{JALX} +instructions as the associated relocation is calculated. By default +or if @samp{--no-ignore-branch-isa} is used a check is made causing +the loss of an ISA mode transition to produce an error. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset MMIX +@ifclear GENERIC +@raisesections +@end ifclear + +@node MMIX +@section @code{ld} and MMIX +For MMIX, there is a choice of generating @code{ELF} object files or +@code{mmo} object files when linking. The simulator @code{mmix} +understands the @code{mmo} format. The binutils @code{objcopy} utility +can translate between the two formats. + +There is one special section, the @samp{.MMIX.reg_contents} section. +Contents in this section is assumed to correspond to that of global +registers, and symbols referring to it are translated to special symbols, +equal to registers. In a final link, the start address of the +@samp{.MMIX.reg_contents} section corresponds to the first allocated +global register multiplied by 8. Register @code{$255} is not included in +this section; it is always set to the program entry, which is at the +symbol @code{Main} for @code{mmo} files. + +Global symbols with the prefix @code{__.MMIX.start.}, for example +@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special. +The default linker script uses these to set the default start address +of a section. + +Initial and trailing multiples of zero-valued 32-bit words in a section, +are left out from an mmo file. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset MSP430 +@ifclear GENERIC +@raisesections +@end ifclear + +@node MSP430 +@section @code{ld} and MSP430 +For the MSP430 it is possible to select the MPU architecture. The flag @samp{-m [mpu type]} +will select an appropriate linker script for selected MPU type. (To get a list of known MPUs +just pass @samp{-m help} option to the linker). + +@cindex MSP430 extra sections +The linker will recognize some extra sections which are MSP430 specific: + +@table @code +@item @samp{.vectors} +Defines a portion of ROM where interrupt vectors located. + +@item @samp{.bootloader} +Defines the bootloader portion of the ROM (if applicable). Any code +in this section will be uploaded to the MPU. + +@item @samp{.infomem} +Defines an information memory section (if applicable). Any code in +this section will be uploaded to the MPU. + +@item @samp{.infomemnobits} +This is the same as the @samp{.infomem} section except that any code +in this section will not be uploaded to the MPU. + +@item @samp{.noinit} +Denotes a portion of RAM located above @samp{.bss} section. + +The last two sections are used by gcc. +@end table + +@table @option +@cindex MSP430 Options +@kindex --code-region +@item --code-region=[either,lower,upper,none] +This will transform .text* sections to [either,lower,upper].text* sections. The +argument passed to GCC for -mcode-region is propagated to the linker +using this option. + +@kindex --data-region +@item --data-region=[either,lower,upper,none] +This will transform .data*, .bss* and .rodata* sections to +[either,lower,upper].[data,bss,rodata]* sections. The argument passed to GCC +for -mdata-region is propagated to the linker using this option. + +@kindex --disable-sec-transformation +@item --disable-sec-transformation +Prevent the transformation of sections as specified by the @code{--code-region} +and @code{--data-region} options. +This is useful if you are compiling and linking using a single call to the GCC +wrapper, and want to compile the source files using -m[code,data]-region but +not transform the sections for prebuilt libraries and objects. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset NDS32 +@ifclear GENERIC +@raisesections +@end ifclear + +@node NDS32 +@section @code{ld} and NDS32 +@kindex relaxing on NDS32 +For NDS32, there are some options to select relaxation behavior. The linker +relaxes objects according to these options. + +@table @code +@item @samp{--m[no-]fp-as-gp} +Disable/enable fp-as-gp relaxation. + +@item @samp{--mexport-symbols=FILE} +Exporting symbols and their address into FILE as linker script. + +@item @samp{--m[no-]ex9} +Disable/enable link-time EX9 relaxation. + +@item @samp{--mexport-ex9=FILE} +Export the EX9 table after linking. + +@item @samp{--mimport-ex9=FILE} +Import the Ex9 table for EX9 relaxation. + +@item @samp{--mupdate-ex9} +Update the existing EX9 table. + +@item @samp{--mex9-limit=NUM} +Maximum number of entries in the ex9 table. + +@item @samp{--mex9-loop-aware} +Avoid generating the EX9 instruction inside the loop. + +@item @samp{--m[no-]ifc} +Disable/enable the link-time IFC optimization. + +@item @samp{--mifc-loop-aware} +Avoid generating the IFC instruction inside the loop. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset NIOSII +@ifclear GENERIC +@raisesections +@end ifclear + +@node Nios II +@section @command{ld} and the Altera Nios II +@cindex Nios II call relaxation +@kindex --relax on Nios II + +Call and immediate jump instructions on Nios II processors are limited to +transferring control to addresses in the same 256MB memory segment, +which may result in @command{ld} giving +@samp{relocation truncated to fit} errors with very large programs. +The command-line option @option{--relax} enables the generation of +trampolines that can access the entire 32-bit address space for calls +outside the normal @code{call} and @code{jmpi} address range. These +trampolines are inserted at section boundaries, so may not themselves +be reachable if an input section and its associated call trampolines are +larger than 256MB. + +The @option{--relax} option is enabled by default unless @option{-r} +is also specified. You can disable trampoline generation by using the +@option{--no-relax} linker option. You can also disable this optimization +locally by using the @samp{set .noat} directive in assembly-language +source files, as the linker-inserted trampolines use the @code{at} +register as a temporary. + +Note that the linker @option{--relax} option is independent of assembler +relaxation options, and that using the GNU assembler's @option{-relax-all} +option interferes with the linker's more selective call instruction relaxation. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset POWERPC +@ifclear GENERIC +@raisesections +@end ifclear + +@node PowerPC ELF32 +@section @command{ld} and PowerPC 32-bit ELF Support +@cindex PowerPC long branches +@kindex --relax on PowerPC +Branches on PowerPC processors are limited to a signed 26-bit +displacement, which may result in @command{ld} giving +@samp{relocation truncated to fit} errors with very large programs. +@samp{--relax} enables the generation of trampolines that can access +the entire 32-bit address space. These trampolines are inserted at +section boundaries, so may not themselves be reachable if an input +section exceeds 33M in size. You may combine @samp{-r} and +@samp{--relax} to add trampolines in a partial link. In that case +both branches to undefined symbols and inter-section branches are also +considered potentially out of range, and trampolines inserted. + +@cindex PowerPC ELF32 options +@table @option +@cindex PowerPC PLT +@kindex --bss-plt +@item --bss-plt +Current PowerPC GCC accepts a @samp{-msecure-plt} option that +generates code capable of using a newer PLT and GOT layout that has +the security advantage of no executable section ever needing to be +writable and no writable section ever being executable. PowerPC +@command{ld} will generate this layout, including stubs to access the +PLT, if all input files (including startup and static libraries) were +compiled with @samp{-msecure-plt}. @samp{--bss-plt} forces the old +BSS PLT (and GOT layout) which can give slightly better performance. + +@kindex --secure-plt +@item --secure-plt +@command{ld} will use the new PLT and GOT layout if it is linking new +@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically +when linking non-PIC code. This option requests the new PLT and GOT +layout. A warning will be given if some object file requires the old +style BSS PLT. + +@cindex PowerPC GOT +@kindex --sdata-got +@item --sdata-got +The new secure PLT and GOT are placed differently relative to other +sections compared to older BSS PLT and GOT placement. The location of +@code{.plt} must change because the new secure PLT is an initialized +section while the old PLT is uninitialized. The reason for the +@code{.got} change is more subtle: The new placement allows +@code{.got} to be read-only in applications linked with +@samp{-z relro -z now}. However, this placement means that +@code{.sdata} cannot always be used in shared libraries, because the +PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT +pointer. @samp{--sdata-got} forces the old GOT placement. PowerPC +GCC doesn't use @code{.sdata} in shared libraries, so this option is +really only useful for other compilers that may do so. + +@cindex PowerPC stub symbols +@kindex --emit-stub-syms +@item --emit-stub-syms +This option causes @command{ld} to label linker stubs with a local +symbol that encodes the stub type and destination. + +@cindex PowerPC TLS optimization +@kindex --no-tls-optimize +@item --no-tls-optimize +PowerPC @command{ld} normally performs some optimization of code +sequences used to access Thread-Local Storage. Use this option to +disable the optimization. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset POWERPC64 +@ifclear GENERIC +@raisesections +@end ifclear + +@node PowerPC64 ELF64 +@section @command{ld} and PowerPC64 64-bit ELF Support + +@cindex PowerPC64 ELF64 options +@table @option +@cindex PowerPC64 stub grouping +@kindex --stub-group-size +@item --stub-group-size +Long branch stubs, PLT call stubs and TOC adjusting stubs are placed +by @command{ld} in stub sections located between groups of input sections. +@samp{--stub-group-size} specifies the maximum size of a group of input +sections handled by one stub section. Since branch offsets are signed, +a stub section may serve two groups of input sections, one group before +the stub section, and one group after it. However, when using +conditional branches that require stubs, it may be better (for branch +prediction) that stub sections only serve one group of input sections. +A negative value for @samp{N} chooses this scheme, ensuring that +branches to stubs always use a negative offset. Two special values of +@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct +@command{ld} to automatically size input section groups for the branch types +detected, with the same behaviour regarding stub placement as other +positive or negative values of @samp{N} respectively. + +Note that @samp{--stub-group-size} does not split input sections. A +single input section larger than the group size specified will of course +create a larger group (of one section). If input sections are too +large, it may not be possible for a branch to reach its stub. + +@cindex PowerPC64 stub symbols +@kindex --emit-stub-syms +@item --emit-stub-syms +This option causes @command{ld} to label linker stubs with a local +symbol that encodes the stub type and destination. + +@cindex PowerPC64 dot symbols +@kindex --dotsyms +@kindex --no-dotsyms +@item --dotsyms +@itemx --no-dotsyms +These two options control how @command{ld} interprets version patterns +in a version script. Older PowerPC64 compilers emitted both a +function descriptor symbol with the same name as the function, and a +code entry symbol with the name prefixed by a dot (@samp{.}). To +properly version a function @samp{foo}, the version script thus needs +to control both @samp{foo} and @samp{.foo}. The option +@samp{--dotsyms}, on by default, automatically adds the required +dot-prefixed patterns. Use @samp{--no-dotsyms} to disable this +feature. + +@cindex PowerPC64 register save/restore functions +@kindex --save-restore-funcs +@kindex --no-save-restore-funcs +@item --save-restore-funcs +@itemx --no-save-restore-funcs +These two options control whether PowerPC64 @command{ld} automatically +provides out-of-line register save and restore functions used by +@samp{-Os} code. The default is to provide any such referenced +function for a normal final link, and to not do so for a relocatable +link. + +@cindex PowerPC64 TLS optimization +@kindex --no-tls-optimize +@item --no-tls-optimize +PowerPC64 @command{ld} normally performs some optimization of code +sequences used to access Thread-Local Storage. Use this option to +disable the optimization. + +@cindex PowerPC64 __tls_get_addr optimization +@kindex --tls-get-addr-optimize +@kindex --no-tls-get-addr-optimize +@item --tls-get-addr-optimize +@itemx --no-tls-get-addr-optimize +These options control whether PowerPC64 @command{ld} uses a special +stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support +an optimization that allows the second and subsequent calls to +@code{__tls_get_addr} for a given symbol to be resolved by the special +stub without calling in to glibc. By default the linker enables this +option when glibc advertises the availability of __tls_get_addr_opt. +Forcing this option on when using an older glibc won't do much besides +slow down your applications, but may be useful if linking an +application against an older glibc with the expectation that it will +normally be used on systems having a newer glibc. + +@cindex PowerPC64 OPD optimization +@kindex --no-opd-optimize +@item --no-opd-optimize +PowerPC64 @command{ld} normally removes @code{.opd} section entries +corresponding to deleted link-once functions, or functions removed by +the action of @samp{--gc-sections} or linker script @code{/DISCARD/}. +Use this option to disable @code{.opd} optimization. + +@cindex PowerPC64 OPD spacing +@kindex --non-overlapping-opd +@item --non-overlapping-opd +Some PowerPC64 compilers have an option to generate compressed +@code{.opd} entries spaced 16 bytes apart, overlapping the third word, +the static chain pointer (unused in C) with the first word of the next +entry. This option expands such entries to the full 24 bytes. + +@cindex PowerPC64 TOC optimization +@kindex --no-toc-optimize +@item --no-toc-optimize +PowerPC64 @command{ld} normally removes unused @code{.toc} section +entries. Such entries are detected by examining relocations that +reference the TOC in code sections. A reloc in a deleted code section +marks a TOC word as unneeded, while a reloc in a kept code section +marks a TOC word as needed. Since the TOC may reference itself, TOC +relocs are also examined. TOC words marked as both needed and +unneeded will of course be kept. TOC words without any referencing +reloc are assumed to be part of a multi-word entry, and are kept or +discarded as per the nearest marked preceding word. This works +reliably for compiler generated code, but may be incorrect if assembly +code is used to insert TOC entries. Use this option to disable the +optimization. + +@cindex PowerPC64 multi-TOC +@kindex --no-multi-toc +@item --no-multi-toc +If given any toc option besides @code{-mcmodel=medium} or +@code{-mcmodel=large}, PowerPC64 GCC generates code for a TOC model +where TOC +entries are accessed with a 16-bit offset from r2. This limits the +total TOC size to 64K. PowerPC64 @command{ld} extends this limit by +grouping code sections such that each group uses less than 64K for its +TOC entries, then inserts r2 adjusting stubs between inter-group +calls. @command{ld} does not split apart input sections, so cannot +help if a single input file has a @code{.toc} section that exceeds +64K, most likely from linking multiple files with @command{ld -r}. +Use this option to turn off this feature. + +@cindex PowerPC64 TOC sorting +@kindex --no-toc-sort +@item --no-toc-sort +By default, @command{ld} sorts TOC sections so that those whose file +happens to have a section called @code{.init} or @code{.fini} are +placed first, followed by TOC sections referenced by code generated +with PowerPC64 gcc's @code{-mcmodel=small}, and lastly TOC sections +referenced only by code generated with PowerPC64 gcc's +@code{-mcmodel=medium} or @code{-mcmodel=large} options. Doing this +results in better TOC grouping for multi-TOC. Use this option to turn +off this feature. + +@cindex PowerPC64 PLT stub alignment +@kindex --plt-align +@kindex --no-plt-align +@item --plt-align +@itemx --no-plt-align +Use these options to control whether individual PLT call stubs are +aligned to a 32-byte boundary, or to the specified power of two +boundary when using @code{--plt-align=}. A negative value may be +specified to pad PLT call stubs so that they do not cross the +specified power of two boundary (or the minimum number of boundaries +if a PLT stub is so large that it must cross a boundary). By default +PLT call stubs are aligned to 32-byte boundaries. + +@cindex PowerPC64 PLT call stub static chain +@kindex --plt-static-chain +@kindex --no-plt-static-chain +@item --plt-static-chain +@itemx --no-plt-static-chain +Use these options to control whether PLT call stubs load the static +chain pointer (r11). @code{ld} defaults to not loading the static +chain since there is never any need to do so on a PLT call. + +@cindex PowerPC64 PLT call stub thread safety +@kindex --plt-thread-safe +@kindex --no-plt-thread-safe +@item --plt-thread-safe +@itemx --no-plt-thread-safe +With power7's weakly ordered memory model, it is possible when using +lazy binding for ld.so to update a plt entry in one thread and have +another thread see the individual plt entry words update in the wrong +order, despite ld.so carefully writing in the correct order and using +memory write barriers. To avoid this we need some sort of read +barrier in the call stub, or use LD_BIND_NOW=1. By default, @code{ld} +looks for calls to commonly used functions that create threads, and if +seen, adds the necessary barriers. Use these options to change the +default behaviour. + +@cindex PowerPC64 ELFv2 PLT localentry optimization +@kindex --plt-localentry +@kindex --no-plt-localentry +@item --plt-localentry +@itemx --no-localentry +ELFv2 functions with localentry:0 are those with a single entry point, +ie. global entry == local entry, and that have no requirement on r2 +(the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return. +Such an external function can be called via the PLT without saving r2 +or restoring it on return, avoiding a common load-hit-store for small +functions. The optimization is attractive, with up to 40% reduction +in execution time for a small function, but can result in symbol +interposition failures. Also, minor changes in a shared library, +including system libraries, can cause a function that was localentry:0 +to become localentry:8. This will result in a dynamic loader +complaint and failure to run. The option is experimental, use with +care. @option{--no-plt-localentry} is the default. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset S/390 +@ifclear GENERIC +@raisesections +@end ifclear + +@node S/390 ELF +@section @command{ld} and S/390 ELF Support + +@cindex S/390 ELF options +@table @option + +@cindex S/390 +@kindex --s390-pgste +@item --s390-pgste +This option marks the result file with a @code{PT_S390_PGSTE} +segment. The Linux kernel is supposed to allocate 4k page tables for +binaries marked that way. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset SPU +@ifclear GENERIC +@raisesections +@end ifclear + +@node SPU ELF +@section @command{ld} and SPU ELF Support + +@cindex SPU ELF options +@table @option + +@cindex SPU plugins +@kindex --plugin +@item --plugin +This option marks an executable as a PIC plugin module. + +@cindex SPU overlays +@kindex --no-overlays +@item --no-overlays +Normally, @command{ld} recognizes calls to functions within overlay +regions, and redirects such calls to an overlay manager via a stub. +@command{ld} also provides a built-in overlay manager. This option +turns off all this special overlay handling. + +@cindex SPU overlay stub symbols +@kindex --emit-stub-syms +@item --emit-stub-syms +This option causes @command{ld} to label overlay stubs with a local +symbol that encodes the stub type and destination. + +@cindex SPU extra overlay stubs +@kindex --extra-overlay-stubs +@item --extra-overlay-stubs +This option causes @command{ld} to add overlay call stubs on all +function calls out of overlay regions. Normally stubs are not added +on calls to non-overlay regions. + +@cindex SPU local store size +@kindex --local-store=lo:hi +@item --local-store=lo:hi +@command{ld} usually checks that a final executable for SPU fits in +the address range 0 to 256k. This option may be used to change the +range. Disable the check entirely with @option{--local-store=0:0}. + +@cindex SPU +@kindex --stack-analysis +@item --stack-analysis +SPU local store space is limited. Over-allocation of stack space +unnecessarily limits space available for code and data, while +under-allocation results in runtime failures. If given this option, +@command{ld} will provide an estimate of maximum stack usage. +@command{ld} does this by examining symbols in code sections to +determine the extents of functions, and looking at function prologues +for stack adjusting instructions. A call-graph is created by looking +for relocations on branch instructions. The graph is then searched +for the maximum stack usage path. Note that this analysis does not +find calls made via function pointers, and does not handle recursion +and other cycles in the call graph. Stack usage may be +under-estimated if your code makes such calls. Also, stack usage for +dynamic allocation, e.g. alloca, will not be detected. If a link map +is requested, detailed information about each function's stack usage +and calls will be given. + +@cindex SPU +@kindex --emit-stack-syms +@item --emit-stack-syms +This option, if given along with @option{--stack-analysis} will result +in @command{ld} emitting stack sizing symbols for each function. +These take the form @code{__stack_<function_name>} for global +functions, and @code{__stack_<number>_<function_name>} for static +functions. @code{<number>} is the section id in hex. The value of +such symbols is the stack requirement for the corresponding function. +The symbol size will be zero, type @code{STT_NOTYPE}, binding +@code{STB_LOCAL}, and section @code{SHN_ABS}. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset TICOFF +@ifclear GENERIC +@raisesections +@end ifclear + +@node TI COFF +@section @command{ld}'s Support for Various TI COFF Versions +@cindex TI COFF versions +@kindex --format=@var{version} +The @samp{--format} switch allows selection of one of the various +TI COFF versions. The latest of this writing is 2; versions 0 and 1 are +also supported. The TI COFF versions also vary in header byte-order +format; @command{ld} will read any version or byte order, but the output +header format depends on the default specified by the specific target. + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset WIN32 +@ifclear GENERIC +@raisesections +@end ifclear + +@node WIN32 +@section @command{ld} and WIN32 (cygwin/mingw) + +This section describes some of the win32 specific @command{ld} issues. +See @ref{Options,,Command Line Options} for detailed description of the +command line options mentioned here. + +@table @emph +@cindex import libraries +@item import libraries +The standard Windows linker creates and uses so-called import +libraries, which contains information for linking to dll's. They are +regular static archives and are handled as any other static +archive. The cygwin and mingw ports of @command{ld} have specific +support for creating such libraries provided with the +@samp{--out-implib} command line option. + +@item exporting DLL symbols +@cindex exporting DLL symbols +The cygwin/mingw @command{ld} has several ways to export symbols for dll's. + +@table @emph +@item using auto-export functionality +@cindex using auto-export functionality +By default @command{ld} exports symbols with the auto-export functionality, +which is controlled by the following command line options: + +@itemize +@item --export-all-symbols [This is the default] +@item --exclude-symbols +@item --exclude-libs +@item --exclude-modules-for-implib +@item --version-script +@end itemize + +When auto-export is in operation, @command{ld} will export all the non-local +(global and common) symbols it finds in a DLL, with the exception of a few +symbols known to belong to the system's runtime and libraries. As it will +often not be desirable to export all of a DLL's symbols, which may include +private functions that are not part of any public interface, the command-line +options listed above may be used to filter symbols out from the list for +exporting. The @samp{--output-def} option can be used in order to see the +final list of exported symbols with all exclusions taken into effect. + +If @samp{--export-all-symbols} is not given explicitly on the +command line, then the default auto-export behavior will be @emph{disabled} +if either of the following are true: + +@itemize +@item A DEF file is used. +@item Any symbol in any object file was marked with the __declspec(dllexport) attribute. +@end itemize + +@item using a DEF file +@cindex using a DEF file +Another way of exporting symbols is using a DEF file. A DEF file is +an ASCII file containing definitions of symbols which should be +exported when a dll is created. Usually it is named @samp{<dll +name>.def} and is added as any other object file to the linker's +command line. The file's name must end in @samp{.def} or @samp{.DEF}. + +@example +gcc -o <output> <objectfiles> <dll name>.def +@end example + +Using a DEF file turns off the normal auto-export behavior, unless the +@samp{--export-all-symbols} option is also used. + +Here is an example of a DEF file for a shared library called @samp{xyz.dll}: + +@example +LIBRARY "xyz.dll" BASE=0x20000000 + +EXPORTS +foo +bar +_bar = bar +another_foo = abc.dll.afoo +var1 DATA +doo = foo == foo2 +eoo DATA == var1 +@end example + +This example defines a DLL with a non-default base address and seven +symbols in the export table. The third exported symbol @code{_bar} is an +alias for the second. The fourth symbol, @code{another_foo} is resolved +by "forwarding" to another module and treating it as an alias for +@code{afoo} exported from the DLL @samp{abc.dll}. The final symbol +@code{var1} is declared to be a data object. The @samp{doo} symbol in +export library is an alias of @samp{foo}, which gets the string name +in export table @samp{foo2}. The @samp{eoo} symbol is an data export +symbol, which gets in export table the name @samp{var1}. + +The optional @code{LIBRARY <name>} command indicates the @emph{internal} +name of the output DLL. If @samp{<name>} does not include a suffix, +the default library suffix, @samp{.DLL} is appended. + +When the .DEF file is used to build an application, rather than a +library, the @code{NAME <name>} command should be used instead of +@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default +executable suffix, @samp{.EXE} is appended. + +With either @code{LIBRARY <name>} or @code{NAME <name>} the optional +specification @code{BASE = <number>} may be used to specify a +non-default base address for the image. + +If neither @code{LIBRARY <name>} nor @code{NAME <name>} is specified, +or they specify an empty string, the internal name is the same as the +filename specified on the command line. + +The complete specification of an export symbol is: + +@example +EXPORTS + ( ( ( <name1> [ = <name2> ] ) + | ( <name1> = <module-name> . <external-name>)) + [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) * +@end example + +Declares @samp{<name1>} as an exported symbol from the DLL, or declares +@samp{<name1>} as an exported alias for @samp{<name2>}; or declares +@samp{<name1>} as a "forward" alias for the symbol +@samp{<external-name>} in the DLL @samp{<module-name>}. +Optionally, the symbol may be exported by the specified ordinal +@samp{<integer>} alias. The optional @samp{<name3>} is the to be used +string in import/export table for the symbol. + +The optional keywords that follow the declaration indicate: + +@code{NONAME}: Do not put the symbol name in the DLL's export table. It +will still be exported by its ordinal alias (either the value specified +by the .def specification or, otherwise, the value assigned by the +linker). The symbol name, however, does remain visible in the import +library (if any), unless @code{PRIVATE} is also specified. + +@code{DATA}: The symbol is a variable or object, rather than a function. +The import lib will export only an indirect reference to @code{foo} as +the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as +@code{*_imp__foo}). + +@code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as +well as @code{_imp__foo} into the import library. Both refer to the +read-only import address table's pointer to the variable, not to the +variable itself. This can be dangerous. If the user code fails to add +the @code{dllimport} attribute and also fails to explicitly add the +extra indirection that the use of the attribute enforces, the +application will behave unexpectedly. + +@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put +it into the static import library used to resolve imports at link time. The +symbol can still be imported using the @code{LoadLibrary/GetProcAddress} +API at runtime or by using the GNU ld extension of linking directly to +the DLL without an import library. + +See ld/deffilep.y in the binutils sources for the full specification of +other DEF file statements + +@cindex creating a DEF file +While linking a shared dll, @command{ld} is able to create a DEF file +with the @samp{--output-def <file>} command line option. + +@item Using decorations +@cindex Using decorations +Another way of marking symbols for export is to modify the source code +itself, so that when building the DLL each symbol to be exported is +declared as: + +@example +__declspec(dllexport) int a_variable +__declspec(dllexport) void a_function(int with_args) +@end example + +All such symbols will be exported from the DLL. If, however, +any of the object files in the DLL contain symbols decorated in +this way, then the normal auto-export behavior is disabled, unless +the @samp{--export-all-symbols} option is also used. + +Note that object files that wish to access these symbols must @emph{not} +decorate them with dllexport. Instead, they should use dllimport, +instead: + +@example +__declspec(dllimport) int a_variable +__declspec(dllimport) void a_function(int with_args) +@end example + +This complicates the structure of library header files, because +when included by the library itself the header must declare the +variables and functions as dllexport, but when included by client +code the header must declare them as dllimport. There are a number +of idioms that are typically used to do this; often client code can +omit the __declspec() declaration completely. See +@samp{--enable-auto-import} and @samp{automatic data imports} for more +information. +@end table + +@cindex automatic data imports +@item automatic data imports +The standard Windows dll format supports data imports from dlls only +by adding special decorations (dllimport/dllexport), which let the +compiler produce specific assembler instructions to deal with this +issue. This increases the effort necessary to port existing Un*x +code to these platforms, especially for large +c++ libraries and applications. The auto-import feature, which was +initially provided by Paul Sokolovsky, allows one to omit the +decorations to achieve a behavior that conforms to that on POSIX/Un*x +platforms. This feature is enabled with the @samp{--enable-auto-import} +command-line option, although it is enabled by default on cygwin/mingw. +The @samp{--enable-auto-import} option itself now serves mainly to +suppress any warnings that are ordinarily emitted when linked objects +trigger the feature's use. + +auto-import of variables does not always work flawlessly without +additional assistance. Sometimes, you will see this message + +"variable '<var>' can't be auto-imported. Please read the +documentation for ld's @code{--enable-auto-import} for details." + +The @samp{--enable-auto-import} documentation explains why this error +occurs, and several methods that can be used to overcome this difficulty. +One of these methods is the @emph{runtime pseudo-relocs} feature, described +below. + +@cindex runtime pseudo-relocation +For complex variables imported from DLLs (such as structs or classes), +object files typically contain a base address for the variable and an +offset (@emph{addend}) within the variable--to specify a particular +field or public member, for instance. Unfortunately, the runtime loader used +in win32 environments is incapable of fixing these references at runtime +without the additional information supplied by dllimport/dllexport decorations. +The standard auto-import feature described above is unable to resolve these +references. + +The @samp{--enable-runtime-pseudo-relocs} switch allows these references to +be resolved without error, while leaving the task of adjusting the references +themselves (with their non-zero addends) to specialized code provided by the +runtime environment. Recent versions of the cygwin and mingw environments and +compilers provide this runtime support; older versions do not. However, the +support is only necessary on the developer's platform; the compiled result will +run without error on an older system. + +@samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly +enabled as needed. + +@cindex direct linking to a dll +@item direct linking to a dll +The cygwin/mingw ports of @command{ld} support the direct linking, +including data symbols, to a dll without the usage of any import +libraries. This is much faster and uses much less memory than does the +traditional import library method, especially when linking large +libraries or applications. When @command{ld} creates an import lib, each +function or variable exported from the dll is stored in its own bfd, even +though a single bfd could contain many exports. The overhead involved in +storing, loading, and processing so many bfd's is quite large, and explains the +tremendous time, memory, and storage needed to link against particularly +large or complex libraries when using import libs. + +Linking directly to a dll uses no extra command-line switches other than +@samp{-L} and @samp{-l}, because @command{ld} already searches for a number +of names to match each library. All that is needed from the developer's +perspective is an understanding of this search, in order to force ld to +select the dll instead of an import library. + + +For instance, when ld is called with the argument @samp{-lxxx} it will attempt +to find, in the first directory of its search path, + +@example +libxxx.dll.a +xxx.dll.a +libxxx.a +xxx.lib +libxxx.lib +cygxxx.dll (*) +libxxx.dll +xxx.dll +@end example + +before moving on to the next directory in the search path. + +(*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll}, +where @samp{<prefix>} is set by the @command{ld} option +@samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec +file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for +@samp{cygxxx.dll}. + +Other win32-based unix environments, such as mingw or pw32, may use other +@samp{<prefix>}es, although at present only cygwin makes use of this feature. It +was originally intended to help avoid name conflicts among dll's built for the +various win32/un*x environments, so that (for example) two versions of a zlib dll +could coexist on the same machine. + +The generic cygwin/mingw path layout uses a @samp{bin} directory for +applications and dll's and a @samp{lib} directory for the import +libraries (using cygwin nomenclature): + +@example +bin/ + cygxxx.dll +lib/ + libxxx.dll.a (in case of dll's) + libxxx.a (in case of static archive) +@end example + +Linking directly to a dll without using the import library can be +done two ways: + +1. Use the dll directly by adding the @samp{bin} path to the link line +@example +gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx +@end example + +However, as the dll's often have version numbers appended to their names +(@samp{cygncurses-5.dll}) this will often fail, unless one specifies +@samp{-L../bin -lncurses-5} to include the version. Import libs are generally +not versioned, and do not have this difficulty. + +2. Create a symbolic link from the dll to a file in the @samp{lib} +directory according to the above mentioned search pattern. This +should be used to avoid unwanted changes in the tools needed for +making the app/dll. + +@example +ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] +@end example + +Then you can link without any make environment changes. + +@example +gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx +@end example + +This technique also avoids the version number problems, because the following is +perfectly legal + +@example +bin/ + cygxxx-5.dll +lib/ + libxxx.dll.a -> ../bin/cygxxx-5.dll +@end example + +Linking directly to a dll without using an import lib will work +even when auto-import features are exercised, and even when +@samp{--enable-runtime-pseudo-relocs} is used. + +Given the improvements in speed and memory usage, one might justifiably +wonder why import libraries are used at all. There are three reasons: + +1. Until recently, the link-directly-to-dll functionality did @emph{not} +work with auto-imported data. + +2. Sometimes it is necessary to include pure static objects within the +import library (which otherwise contains only bfd's for indirection +symbols that point to the exports of a dll). Again, the import lib +for the cygwin kernel makes use of this ability, and it is not +possible to do this without an import lib. + +3. Symbol aliases can only be resolved using an import lib. This is +critical when linking against OS-supplied dll's (eg, the win32 API) +in which symbols are usually exported as undecorated aliases of their +stdcall-decorated assembly names. + +So, import libs are not going away. But the ability to replace +true import libs with a simple symbolic link to (or a copy of) +a dll, in many cases, is a useful addition to the suite of tools +binutils makes available to the win32 developer. Given the +massive improvements in memory requirements during linking, storage +requirements, and linking speed, we expect that many developers +will soon begin to use this feature whenever possible. + +@item symbol aliasing +@table @emph +@item adding additional names +Sometimes, it is useful to export symbols with additional names. +A symbol @samp{foo} will be exported as @samp{foo}, but it can also be +exported as @samp{_foo} by using special directives in the DEF file +when creating the dll. This will affect also the optional created +import library. Consider the following DEF file: + +@example +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +foo +_foo = foo +@end example + +The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}. + +Another method for creating a symbol alias is to create it in the +source code using the "weak" attribute: + +@example +void foo () @{ /* Do something. */; @} +void _foo () __attribute__ ((weak, alias ("foo"))); +@end example + +See the gcc manual for more information about attributes and weak +symbols. + +@item renaming symbols +Sometimes it is useful to rename exports. For instance, the cygwin +kernel does this regularly. A symbol @samp{_foo} can be exported as +@samp{foo} but not as @samp{_foo} by using special directives in the +DEF file. (This will also affect the import library, if it is +created). In the following example: + +@example +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +_foo = foo +@end example + +The line @samp{_foo = foo} maps the exported symbol @samp{foo} to +@samp{_foo}. +@end table + +Note: using a DEF file disables the default auto-export behavior, +unless the @samp{--export-all-symbols} command line option is used. +If, however, you are trying to rename symbols, then you should list +@emph{all} desired exports in the DEF file, including the symbols +that are not being renamed, and do @emph{not} use the +@samp{--export-all-symbols} option. If you list only the +renamed symbols in the DEF file, and use @samp{--export-all-symbols} +to handle the other symbols, then the both the new names @emph{and} +the original names for the renamed symbols will be exported. +In effect, you'd be aliasing those symbols, not renaming them, +which is probably not what you wanted. + +@cindex weak externals +@item weak externals +The Windows object format, PE, specifies a form of weak symbols called +weak externals. When a weak symbol is linked and the symbol is not +defined, the weak symbol becomes an alias for some other symbol. There +are three variants of weak externals: +@itemize +@item Definition is searched for in objects and libraries, historically +called lazy externals. +@item Definition is searched for only in other objects, not in libraries. +This form is not presently implemented. +@item No search; the symbol is an alias. This form is not presently +implemented. +@end itemize +As a GNU extension, weak symbols that do not specify an alternate symbol +are supported. If the symbol is undefined when linking, the symbol +uses a default value. + +@cindex aligned common symbols +@item aligned common symbols +As a GNU extension to the PE file format, it is possible to specify the +desired alignment for a common symbol. This information is conveyed from +the assembler or compiler to the linker by means of GNU-specific commands +carried in the object file's @samp{.drectve} section, which are recognized +by @command{ld} and respected when laying out the common symbols. Native +tools will be able to process object files employing this GNU extension, +but will fail to respect the alignment instructions, and may issue noisy +warnings about unknown linker directives. + +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifset XTENSA +@ifclear GENERIC +@raisesections +@end ifclear + +@node Xtensa +@section @code{ld} and Xtensa Processors + +@cindex Xtensa processors +The default @command{ld} behavior for Xtensa processors is to interpret +@code{SECTIONS} commands so that lists of explicitly named sections in a +specification with a wildcard file will be interleaved when necessary to +keep literal pools within the range of PC-relative load offsets. For +example, with the command: + +@smallexample +SECTIONS +@{ + .text : @{ + *(.literal .text) + @} +@} +@end smallexample + +@noindent +@command{ld} may interleave some of the @code{.literal} +and @code{.text} sections from different object files to ensure that the +literal pools are within the range of PC-relative load offsets. A valid +interleaving might place the @code{.literal} sections from an initial +group of files followed by the @code{.text} sections of that group of +files. Then, the @code{.literal} sections from the rest of the files +and the @code{.text} sections from the rest of the files would follow. + +@cindex @option{--relax} on Xtensa +@cindex relaxing on Xtensa +Relaxation is enabled by default for the Xtensa version of @command{ld} and +provides two important link-time optimizations. The first optimization +is to combine identical literal values to reduce code size. A redundant +literal will be removed and all the @code{L32R} instructions that use it +will be changed to reference an identical literal, as long as the +location of the replacement literal is within the offset range of all +the @code{L32R} instructions. The second optimization is to remove +unnecessary overhead from assembler-generated ``longcall'' sequences of +@code{L32R}/@code{CALLX@var{n}} when the target functions are within +range of direct @code{CALL@var{n}} instructions. + +For each of these cases where an indirect call sequence can be optimized +to a direct call, the linker will change the @code{CALLX@var{n}} +instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R} +instruction, and remove the literal referenced by the @code{L32R} +instruction if it is not used for anything else. Removing the +@code{L32R} instruction always reduces code size but can potentially +hurt performance by changing the alignment of subsequent branch targets. +By default, the linker will always preserve alignments, either by +switching some instructions between 24-bit encodings and the equivalent +density instructions or by inserting a no-op in place of the @code{L32R} +instruction that was removed. If code size is more important than +performance, the @option{--size-opt} option can be used to prevent the +linker from widening density instructions or inserting no-ops, except in +a few cases where no-ops are required for correctness. + +The following Xtensa-specific command-line options can be used to +control the linker: + +@cindex Xtensa options +@table @option +@item --size-opt +When optimizing indirect calls to direct calls, optimize for code size +more than performance. With this option, the linker will not insert +no-ops or widen density instructions to preserve branch target +alignment. There may still be some cases where no-ops are required to +preserve the correctness of the code. +@end table + +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifclear SingleFormat +@node BFD +@chapter BFD + +@cindex back end +@cindex object file management +@cindex object formats available +@kindex objdump -i +The linker accesses object and archive files using the BFD libraries. +These libraries allow the linker to use the same routines to operate on +object files whatever the object file format. A different object file +format can be supported simply by creating a new BFD back end and adding +it to the library. To conserve runtime memory, however, the linker and +associated tools are usually configured to support only a subset of the +object file formats available. You can use @code{objdump -i} +(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to +list all the formats available for your configuration. + +@cindex BFD requirements +@cindex requirements for BFD +As with most implementations, BFD is a compromise between +several conflicting requirements. The major factor influencing +BFD design was efficiency: any time used converting between +formats is time which would not have been spent had BFD not +been involved. This is partly offset by abstraction payback; since +BFD simplifies applications and back ends, more time and care +may be spent optimizing algorithms for a greater speed. + +One minor artifact of the BFD solution which you should bear in +mind is the potential for information loss. There are two places where +useful information can be lost using the BFD mechanism: during +conversion and during output. @xref{BFD information loss}. + +@menu +* BFD outline:: How it works: an outline of BFD +@end menu + +@node BFD outline +@section How It Works: An Outline of BFD +@cindex opening object files +@include bfdsumm.texi +@end ifclear + +@node Reporting Bugs +@chapter Reporting Bugs +@cindex bugs in @command{ld} +@cindex reporting bugs in @command{ld} + +Your bug reports play an essential role in making @command{ld} reliable. + +Reporting a bug may help you by bringing a solution to your problem, or +it may not. But in any case the principal function of a bug report is +to help the entire community by making the next version of @command{ld} +work better. Bug reports are your contribution to the maintenance of +@command{ld}. + +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +@menu +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs +@end menu + +@node Bug Criteria +@section Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex linker crash +@cindex crash of linker +@item +If the linker gets a fatal signal, for any input whatever, that is a +@command{ld} bug. Reliable linkers never crash. + +@cindex error on valid input +@item +If @command{ld} produces an error message for valid input, that is a bug. + +@cindex invalid input +@item +If @command{ld} does not produce an error message for invalid input, that +may be a bug. In the general case, the linker can not verify that +object files are correct. + +@item +If you are an experienced user of linkers, your suggestions for +improvement of @command{ld} are welcome in any case. +@end itemize + +@node Bug Reporting +@section How to Report Bugs +@cindex bug reports +@cindex @command{ld} bugs, reporting + +A number of companies and individuals offer support for @sc{gnu} +products. If you obtained @command{ld} from a support organization, we +recommend you contact that organization first. + +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. + +@ifset BUGURL +Otherwise, send bug reports for @command{ld} to +@value{BUGURL}. +@end ifset + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of a symbol you use in an example does not +matter. Well, probably it does not, but one cannot be sure. Perhaps +the bug is a stray memory reference which happens to fetch from the +location where that name is stored in memory; perhaps, if the name +were different, the contents of that location would fool the linker +into doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + +Keep in mind that the purpose of a bug report is to enable us to fix +the bug if it is new to us. Therefore, always write your bug reports +on the assumption that the bug has not been reported previously. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. +You might as well expedite matters by sending them to begin with. + +To enable us to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of @command{ld}. @command{ld} announces it if you start it with +the @samp{--version} argument. + +Without this, we will not know whether there is any point in looking for +the bug in the current version of @command{ld}. + +@item +Any patches you may have applied to the @command{ld} source, including any +patches made to the @code{BFD} library. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +What compiler (and its version) was used to compile @command{ld}---e.g. +``@code{gcc-2.7}''. + +@item +The command arguments you gave the linker to link your example and +observe the bug. To guarantee you will not omit something important, +list them all. A copy of the Makefile (or the output from make) is +sufficient. + +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. + +@item +A complete input file, or set of input files, that will reproduce the +bug. It is generally most helpful to send the actual object files +provided that they are reasonably small. Say no more than 10K. For +bigger files you can either make them available by FTP or HTTP or else +state that you are willing to send the object file(s) to whomever +requests them. (Note - your email will be going to a mailing list, so +we do not want to clog it up with large attachments). But small +attachments are best. + +If the source files were assembled using @code{gas} or compiled using +@code{gcc}, then it may be OK to send the source files rather than the +object files. In this case, be sure to say exactly what version of +@code{gas} or @code{gcc} was used to produce the object files. Also say +how @code{gas} or @code{gcc} were configured. + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal.'' + +Of course, if the bug is that @command{ld} gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might +not notice unless it is glaringly wrong. You might as well not give us +a chance to make a mistake. + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of @command{ld} is out of sync, or you have encountered a bug in the +C library on your system. (This has happened!) Your copy might crash +and ours would not. If you told us to expect a crash, then when ours +fails to crash, we would know that the bug was not happening for us. If +you had not told us to expect a crash, then we would not be able to draw +any conclusion from our observations. + +@item +If you wish to suggest changes to the @command{ld} source, send us context +diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or +@samp{-p} option. Always send diffs from the old file to the new file. +If you even discuss something in the @command{ld} source, refer to it by +context, not by line number. + +The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. + +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. + +However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. + +@item +A patch for the bug. + +A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. + +Sometimes with a program as complicated as @command{ld} it is very hard to +construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be +able to construct one, so we will not be able to verify that the bug is +fixed. + +And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +@end itemize + +@node MRI +@appendix MRI Compatible Script Files +@cindex MRI compatibility +To aid users making the transition to @sc{gnu} @command{ld} from the MRI +linker, @command{ld} can use MRI compatible linker scripts as an +alternative to the more general-purpose linker scripting language +described in @ref{Scripts}. MRI compatible linker scripts have a much +simpler command set than the scripting language otherwise used with +@command{ld}. @sc{gnu} @command{ld} supports the most commonly used MRI +linker commands; these commands are described here. + +In general, MRI scripts aren't of much use with the @code{a.out} object +file format, since it only has three sections and MRI scripts lack some +features to make use of them. + +You can specify a file containing an MRI-compatible script using the +@samp{-c} command-line option. + +Each command in an MRI-compatible script occupies its own line; each +command line starts with the keyword that identifies the command (though +blank lines are also allowed for punctuation). If a line of an +MRI-compatible script begins with an unrecognized keyword, @command{ld} +issues a warning message, but continues processing the script. + +Lines beginning with @samp{*} are comments. + +You can write these commands using all upper-case letters, or all +lower case; for example, @samp{chip} is the same as @samp{CHIP}. +The following list shows only the upper-case form of each command. + +@table @code +@cindex @code{ABSOLUTE} (MRI) +@item ABSOLUTE @var{secname} +@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname} +Normally, @command{ld} includes in the output file all sections from all +the input files. However, in an MRI-compatible script, you can use the +@code{ABSOLUTE} command to restrict the sections that will be present in +your output program. If the @code{ABSOLUTE} command is used at all in a +script, then only the sections named explicitly in @code{ABSOLUTE} +commands will appear in the linker output. You can still use other +input sections (whatever you select on the command line, or using +@code{LOAD}) to resolve addresses in the output file. + +@cindex @code{ALIAS} (MRI) +@item ALIAS @var{out-secname}, @var{in-secname} +Use this command to place the data from input section @var{in-secname} +in a section called @var{out-secname} in the linker output file. + +@var{in-secname} may be an integer. + +@cindex @code{ALIGN} (MRI) +@item ALIGN @var{secname} = @var{expression} +Align the section called @var{secname} to @var{expression}. The +@var{expression} should be a power of two. + +@cindex @code{BASE} (MRI) +@item BASE @var{expression} +Use the value of @var{expression} as the lowest address (other than +absolute addresses) in the output file. + +@cindex @code{CHIP} (MRI) +@item CHIP @var{expression} +@itemx CHIP @var{expression}, @var{expression} +This command does nothing; it is accepted only for compatibility. + +@cindex @code{END} (MRI) +@item END +This command does nothing whatever; it's only accepted for compatibility. + +@cindex @code{FORMAT} (MRI) +@item FORMAT @var{output-format} +Similar to the @code{OUTPUT_FORMAT} command in the more general linker +language, but restricted to S-records, if @var{output-format} is @samp{S} + +@cindex @code{LIST} (MRI) +@item LIST @var{anything}@dots{} +Print (to the standard output file) a link map, as produced by the +@command{ld} command-line option @samp{-M}. + +The keyword @code{LIST} may be followed by anything on the +same line, with no change in its effect. + +@cindex @code{LOAD} (MRI) +@item LOAD @var{filename} +@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename} +Include one or more object file @var{filename} in the link; this has the +same effect as specifying @var{filename} directly on the @command{ld} +command line. + +@cindex @code{NAME} (MRI) +@item NAME @var{output-name} +@var{output-name} is the name for the program produced by @command{ld}; the +MRI-compatible command @code{NAME} is equivalent to the command-line +option @samp{-o} or the general script language command @code{OUTPUT}. + +@cindex @code{ORDER} (MRI) +@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname} +@itemx ORDER @var{secname} @var{secname} @var{secname} +Normally, @command{ld} orders the sections in its output file in the +order in which they first appear in the input files. In an MRI-compatible +script, you can override this ordering with the @code{ORDER} command. The +sections you list with @code{ORDER} will appear first in your output +file, in the order specified. + +@cindex @code{PUBLIC} (MRI) +@item PUBLIC @var{name}=@var{expression} +@itemx PUBLIC @var{name},@var{expression} +@itemx PUBLIC @var{name} @var{expression} +Supply a value (@var{expression}) for external symbol +@var{name} used in the linker input files. + +@cindex @code{SECT} (MRI) +@item SECT @var{secname}, @var{expression} +@itemx SECT @var{secname}=@var{expression} +@itemx SECT @var{secname} @var{expression} +You can use any of these three forms of the @code{SECT} command to +specify the start address (@var{expression}) for section @var{secname}. +If you have more than one @code{SECT} statement for the same +@var{secname}, only the @emph{first} sets the start address. +@end table + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include fdl.texi + +@node LD Index +@unnumbered LD Index + +@printindex cp + +@tex +% I think something like @@colophon should be in texinfo. In the +% meantime: +\long\def\colophon{\hbox to0pt{}\vfill +\centerline{The body of this manual is set in} +\centerline{\fontname\tenrm,} +\centerline{with headings in {\bf\fontname\tenbf}} +\centerline{and examples in {\tt\fontname\tentt}.} +\centerline{{\it\fontname\tenit\/} and} +\centerline{{\sl\fontname\tensl\/}} +\centerline{are used for emphasis.}\vfill} +\page\colophon +% Blame: doc@@cygnus.com, 28mar91. +@end tex + +@bye |