diff options
Diffstat (limited to 'contrib/binutils/ld/ld.texinfo')
| -rw-r--r-- | contrib/binutils/ld/ld.texinfo | 3620 |
1 files changed, 3620 insertions, 0 deletions
diff --git a/contrib/binutils/ld/ld.texinfo b/contrib/binutils/ld/ld.texinfo new file mode 100644 index 0000000..0a5d17a --- /dev/null +++ b/contrib/binutils/ld/ld.texinfo @@ -0,0 +1,3620 @@ +\input texinfo +@setfilename ld.info +@syncodeindex ky cp +@include configdoc.texi +@c (configdoc.texi is generated by the Makefile) + +@c @smallbook + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Ld: (ld). The GNU linker. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +This file documents the @sc{gnu} linker LD. + +Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +@end ifinfo +@iftex +@finalout +@setchapternewpage odd +@settitle Using LD, the GNU linker +@titlepage +@title Using ld +@subtitle The GNU linker +@sp 1 +@subtitle @code{ld} version 2 +@subtitle January 1994 +@author Steve Chamberlain +@author Cygnus Support +@page + +@tex +{\parskip=0pt +\hfill Cygnus Support\par +\hfill steve\@cygnus.com, doc\@cygnus.com\par +\hfill {\it Using LD, 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 +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@end iftex +@c FIXME: Talk about importance of *order* of args, cmds to linker! + +@ifinfo +@node Top +@top Using ld +This file documents the @sc{gnu} linker ld. + +@menu +* Overview:: Overview +* Invocation:: Invocation +* Commands:: Command Language +@ifset GENERIC +* Machine Dependent:: Machine Dependent Features +@end ifset +@ifclear GENERIC +@ifset H8300 +* H8/300:: ld and the H8/300 +@end ifset +@ifset Hitachi +* Hitachi:: ld and other Hitachi micros +@end ifset +@ifset I960 +* i960:: ld and the Intel 960 family +@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 +* Index:: Index +@end menu +@end ifinfo + +@node Overview +@chapter Overview + +@cindex @sc{gnu} linker +@cindex what is this? +@code{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 @code{ld}. + +@code{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. + +@ifclear SingleFormat +This version of @code{ld} uses the general purpose BFD libraries +to operate on object files. This allows @code{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, +@code{ld} continues executing, allowing you to identify other errors +(or, in some cases, to get an output file in spite of the error). + +@node Invocation +@chapter Invocation + +The @sc{gnu} linker @code{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. + +@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 +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 @code{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 @code{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.) + +The command-line options to @code{ld} may be specified in any order, and +may be repeated at will. Repeating most 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 objects files 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 can not 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. Note that +specifying a script in this way should only be used to augment the main +linker script; if you want to use some command that logically can only +appear once, such as the @code{SECTIONS} or @code{MEMORY} command, you +must replace the default linker script using the @samp{-T} option. +@xref{Commands}. + +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{--oformat} and +@samp{--oformat} are equivalent. 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{--oformat srec} and +@samp{--oformat=srec} are equivalent. Unique abbreviations of the names +of multiple-letter options are accepted. + +@table @code +@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. + +@ifset I960 +@cindex architectures +@kindex -A@var{arch} +@item -A@var{architecture} +@kindex --architecture=@var{arch} +@itemx --architecture=@var{architecture} +In the current release of @code{ld}, this option is useful only for the +Intel 960 family of architectures. In that @code{ld} configuration, the +@var{architecture} argument identifies the particular architecture in +the 960 family, enabling some safeguards and modifying the +archive-library search path. @xref{i960,,@code{ld} and the Intel 960 +family}, for details. + +Future releases of @code{ld} may support similar functionality for +other architecture families. +@end ifset + +@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} +@code{ld} may be configured to support more than one kind of object +file. If your @code{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 @code{ld} is +configured to support alternative object formats, you don't usually need +to specify this, as @code{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}; see @ref{Option +Commands}. +@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, @code{ld} accepts script +files written in an alternate, restricted command language, described in +@ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with +the option @samp{-c}; use the @samp{-T} option to run linker +scripts written in the general-purpose @code{ld} scripting language. +If @var{MRI-cmdfile} does not exist, @code{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{Option +Commands}. + +@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. @xref{Entry Point}, for a +discussion of defaults and other ways of specifying the +entry point. + +@cindex dynamic symbol table +@kindex -E +@kindex --export-dynamic +@item -E +@itemx --export-dynamic +When creating a dynamically linked executable, add all symbols to the +dynamic symbol table. Normally, the dynamic symbol table contains only +symbols which are used by a dynamic object. This option is needed for +some uses of @code{dlopen}. + +@kindex -f +@kindex --auxiliary +@item -f +@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 +@kindex --filter +@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 @code{-F} option throughout a compilation +toolchain for specifying object-file format for both input and output +object files. The @sc{gnu} linker uses other mechanisms for this +purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the +@code{TARGET} command in linker scripts, and the @code{GNUTARGET} +environment variable. The @sc{gnu} linker will ignore the @code{-F} +option when not creating an ELF shared object. + +@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 -g +@item -g +Ignored. Provided for compatibility with other tools. + +@kindex -G +@kindex --gpsize +@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 ECOFF which supports 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 archive files, from cmd line +@kindex -l@var{archive} +@kindex --library=@var{archive} +@item -l@var{archive} +@itemx --library=@var{archive} +Add archive file @var{archive} to the list of files to link. This +option may be used any number of times. @code{ld} will search its +path-list for occurrences of @code{lib@var{archive}.a} for every +@var{archive} specified. + +On systems which support shared libraries, @code{ld} may also search for +libraries with extensions other than @code{.a}. Specifically, on ELF +and SunOS systems, @code{ld} will search a directory for a library with +an extension of @code{.so} before searching for one with an extension of +@code{.a}. By convention, a @code{.so} extension indicates a shared +library. + +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 @code{-(} 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 @code{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 @code{ld} will search +for archive libraries and @code{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 +@code{-L} options apply to all @code{-l} options, regardless of the +order in which the options appear. + +@ifset UsesEnvVars +The default set of paths searched (without being specified with +@samp{-L}) depends on which emulation mode @code{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. The default +depends on how your @code{ld} was configured. + +@cindex link map +@kindex -M +@kindex --print-map +@item -M +@itemx --print-map +Print (to the standard output) a link map---diagnostic information about +where symbols are mapped by @code{ld}, and information on global common +storage allocation. + +@kindex -n +@cindex read-only text +@cindex NMAGIC +@kindex --nmagic +@item -n +@itemx --nmagic +Set the text segment to be read only, and mark the output as +@code{NMAGIC} if possible. + +@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. If the output format supports Unix +style magic numbers, mark the output as @code{OMAGIC}. + +@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 @code{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. + +@cindex partial link +@cindex relocatable output +@kindex -r +@kindex --relocateable +@item -r +@itemx --relocateable +Generate relocatable output---i.e., generate an output file that can in +turn serve as input to @code{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 @code{-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}. + +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 @code{-R} option is +followed by a directory name, rather than a file name, it is treated as +the @code{-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 -t +@kindex --trace +@cindex input files, displaying +@item -t +@itemx --trace +Print the names of the input files as @code{ld} processes them. + +@kindex -T @var{script} +@kindex --script=@var{script} +@cindex script files +@item -T @var{commandfile} +@itemx --script=@var{commandfile} +Read link commands from the file @var{commandfile}. These commands +replace @code{ld}'s default link script (rather than adding to it), so +@var{commandfile} must specify everything necessary to describe the +target format. You must use this option if you want to use a command +which can only appear once in a linker script, such as the +@code{SECTIONS} or @code{MEMORY} command. @xref{Commands}. If +@var{commandfile} does not exist, @code{ld} looks for it in the +directories specified by any preceding @samp{-L} options. Multiple +@samp{-T} options accumulate. + +@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. +@c Nice idea, but no such command: This option is equivalent +@c to the @code{EXTERN} linker command. + +@kindex -v +@kindex -V +@kindex --version +@cindex version +@item -v +@itemx --version +@itemx -V +Display the version number for @code{ld}. The @code{-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 +@cindex L, deleting symbols beginning +@item -X +@itemx --discard-locals +Delete all temporary local symbols. For most targets, this is all local +symbols whose names begin with @samp{L}. + +@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} +This option is 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 -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 +@code{-l} options which follow it. + +@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 @code{-l} options which follow it. + +@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 is only meaningful on ELF +platforms which support shared libraries. + +@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. The remaining files contain references to the symbol. + +@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{Assignment, , +Assignment: Symbol Definitions}). @emph{Note:} there should be no +white space between @var{symbol}, the equals sign (``@key{=}''), and +@var{expression}. + +@cindex dynamic linker, from command line +@kindex --dynamic-linker @var{file} +@item --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. + +@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. + +@cindex MIPS embedded PIC code +@kindex --embedded-relocs +@item --embedded-relocs +This option is only meaningful when linking MIPS embedded PIC code, +generated by the -membedded-pic option to the @sc{gnu} compiler and +assembler. It causes the linker to create a table which may be used at +runtime to relocate any data which was statically initialized to pointer +values. See the code in testsuite/ld-empic for details. + +@cindex help +@cindex usage +@kindex --help +@item --help +Print a summary of the command-line options on the standard output and exit. + +@cindex link map +@kindex -Map +@item -Map @var{mapfile} +Print to the file @var{mapfile} a link map---diagnostic information +about where symbols are mapped by @code{ld}, and information on global +common storage allocation. + +@cindex memory usage +@kindex --no-keep-memory +@item --no-keep-memory +@code{ld} normally optimizes for speed over memory usage by caching the +symbol tables of input files in memory. This option tells @code{ld} to +instead optimize for memory usage, by rereading the symbol tables as +necessary. This may be required if @code{ld} runs out of memory space +while linking a large executable. + +@kindex --no-whole-archive +@item --no-whole-archive +Turn off the effect of the @code{--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. + +@ifclear SingleFormat +@kindex --oformat +@item --oformat @var{output-format} +@code{ld} may be configured to support more than one kind of object +file. If your @code{ld} is configured this way, you can use the +@samp{--oformat} option to specify the binary format for the output +object file. Even when @code{ld} is configured to support alternative +object formats, you don't usually need to specify this, as @code{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 -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 +@item --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,,@code{ld} and the H8/300}. +@end ifset +@ifset I960 +@xref{i960,, @code{ld} and the Intel 960 family}. +@end ifset + +On some platforms, the @samp{--relax} option performs global +optimizations that become possible when the linker resolves addressing +in the program, such as relaxing address modes and synthesizing new +instructions in the output object file. + +@ifset GENERIC +On platforms where this is not supported, @samp{--relax} is accepted, +but ignored. +@end ifset + +@cindex retaining specified symbols +@cindex stripping all but some symbols +@cindex symbols, retaining selectively +@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 +Add a directory to the runtime library search path. This is used when +linking an ELF executable with shared objects. All @code{-rpath} +arguments are concatenated and passed to the runtime linker, which uses +them to locate shared objects at runtime. The @code{-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 +@code{-rpath-link} option. If @code{-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 @code{-rpath} option may also be used on SunOS. By default, on +SunOS, the linker will form a runtime search patch out of all the +@code{-L} options it is given. If a @code{-rpath} option is used, the +runtime search path will be formed exclusively using the @code{-rpath} +options, ignoring the @code{-L} options. This can be useful when using +gcc, which adds many @code{-L} options which may be on NFS mounted +filesystems. + +For compatibility with other ELF linkers, if the @code{-R} option is +followed by a directory name, rather than a file name, it is treated as +the @code{-rpath} option. +@end ifset + +@ifset GENERIC +@cindex link-time runtime library search path +@kindex -rpath-link +@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-relocateable 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 @code{-rpath-link} option +specifies the first set of directories to search. The +@code{-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 linker uses the following search paths to locate required shared +libraries. +@enumerate +@item +Any directories specified by @code{-rpath-link} options. +@item +Any directories specified by @code{-rpath} options. The difference +between @code{-rpath} and @code{-rpath-link} is that directories +specified by @code{-rpath} options are included in the executable and +used at runtime, whereas the @code{-rpath-link} option is only effective +at link time. +@item +On an ELF system, if the @code{-rpath} and @code{rpath-link} options +were not used, search the contents of the environment variable +@code{LD_RUN_PATH}. +@item +On SunOS, if the @code{-rpath} option was not used, search any +directories specified using @code{-L} options. +@item +For a native linker, the contents of the environment variable +@code{LD_LIBRARY_PATH}. +@item +The default directories, normally @file{/lib} and @file{/usr/lib}. +@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 @code{-e} option is not used and there are +undefined symbols in the link. + +@item --sort-common +@kindex --sort-common +This option tells @code{ld} to sort the common symbols by size when it +places them in the appropriate output sections. First come all the one +byte symbols, then all the two bytes, then all the four bytes, and then +everything else. This is to prevent gaps between symbols due to +alignment constraints. + +@kindex --split-by-file +@item --split-by-file +Similar to @code{--split-by-reloc} but creates a new output section for +each input file. + +@kindex --split-by-reloc +@item --split-by-reloc @var{count} +Trys 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 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. + +@kindex --stats +@item --stats +Compute and display statistics about the operation of the linker, such +as execution time and memory usage. + +@kindex --traditional-format +@cindex traditional format +@item --traditional-format +For some targets, the output of @code{ld} is different in some ways from +the output of some existing linker. This switch requests @code{ld} to +use the traditional format instead. + +@cindex dbx +For example, on SunOS, @code{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 @code{ld} to not +combine duplicate entries. + +@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} +Use @var{org} as the starting address for---respectively---the +@code{bss}, @code{data}, or the @code{text} segment of the output file. +@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. + +@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 @code{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 --verbose +@cindex verbose +@item --verbose +Display the version number for @code{ld} and list the linker emulations +supported. Display which input files can and cannot be opened. Display +the linker script if using a default builtin script. + +@kindex --version-script=@var{version-scriptfile} +@cindex version script, symbol versions +@itemx --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 heirarchy for the library being created. This option +is only meaningful on ELF platforms which support shared libraries. +@xref{Version Script}. + +@kindex --warn-comon +@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 --whole-archive +@cindex including an entire archive +@item --whole-archive +For each archive mentioned on the command line after the +@code{--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. + +@kindex --wrap +@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 (int c) +@{ + printf ("malloc called with %ld\n", c); + return __real_malloc (c); +@} +@end smallexample + +If you link other code with this file using @code{--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 @code{--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}. + +@end table + +@ifset UsesEnvVars +@node Environment +@section Environment Variables + +You can change the behavior of @code{ld} with the environment +variable @code{GNUTARGET}. + +@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, @code{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 ifset + +@node Commands +@chapter Command Language + +@cindex command files +The command language provides explicit control over the link process, +allowing complete specification of the mapping between the linker's +input files and its output. It controls: +@itemize @bullet +@item +input files +@item +file formats +@item +output file layout +@item +addresses of sections +@item +placement of common blocks +@end itemize + +You may supply a command file (also known as a linker script) to the +linker either explicitly through the @samp{-T} option, or implicitly as +an ordinary file. Normally you should use the @samp{-T} option. An +implicit linker script should only be used when you want to augment, +rather than replace, the default linker script; typically an implicit +linker script would consist only of @code{INPUT} or @code{GROUP} +commands. + +If the linker opens a file which it cannot recognize as a supported +object or archive format, nor as a linker script, it reports an error. + +@menu +* Scripts:: Linker Scripts +* Expressions:: Expressions +* MEMORY:: MEMORY Command +* SECTIONS:: SECTIONS Command +* PHDRS:: PHDRS Command +* Entry Point:: The Entry Point +* Version Script:: Version Script +* Option Commands:: Option Commands +@end menu + +@node Scripts +@section Linker Scripts +The @code{ld} command language is a collection of statements; some are +simple keywords setting a particular option, some are used to select and +group input files or name output files; and two statement +types have a fundamental and pervasive impact on the linking process. + +@cindex fundamental script commands +@cindex commands, fundamental +@cindex output file layout +@cindex layout of output file +The most fundamental command of the @code{ld} command language is the +@code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command +script must have a @code{SECTIONS} command: it specifies a +``picture'' of the output file's layout, in varying degrees of detail. +No other command is required in all cases. + +The @code{MEMORY} command complements @code{SECTIONS} by describing the +available memory in the target architecture. This command is optional; +if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient +memory is available in a contiguous block for all output. +@xref{MEMORY}. + +@cindex comments +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 Expressions +@section Expressions +@cindex expression syntax +@cindex arithmetic +Many useful commands involve arithmetic expressions. The syntax for +expressions in the command language is identical to that of C +expressions, with the following features: +@itemize @bullet +@item +All expressions evaluated as integers and +are of ``long'' or ``unsigned long'' type. +@item +All constants are integers. +@item +All of the C arithmetic operators are provided. +@item +You may reference, define, and create global variables. +@item +You may call special purpose built-in functions. +@end itemize + +@menu +* Integers:: Integers +* Symbols:: Symbol Names +* Location Counter:: The Location Counter +* Operators:: Operators +* Evaluation:: Evaluation +* Assignment:: Assignment: Defining Symbols +* Arithmetic Functions:: Built-In Functions +* Semicolons:: Semicolon Usage +@end menu + +@node Integers +@subsection Integers +@cindex integer notation +@cindex octal integers +An octal integer is @samp{0} followed by zero or more of the octal +digits (@samp{01234567}). +@smallexample +_as_octal = 0157255; +@end smallexample + +@cindex decimal integers +A decimal integer starts with a non-zero digit followed by zero or +more digits (@samp{0123456789}). +@smallexample +_as_decimal = 57005; +@end smallexample + +@cindex hexadecimal integers +@kindex 0x +A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or +more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. +@smallexample +_as_hex = 0xdead; +@end smallexample + +@cindex negative integers +To write a negative integer, use +the prefix operator @samp{-} (@pxref{Operators}). +@smallexample +_as_neg = -57005; +@end smallexample + +@cindex scaled integers +@cindex K and M integer suffixes +@cindex M and K integer suffixes +@cindex suffixes for integers +@cindex integer suffixes +Additionally the suffixes @code{K} and @code{M} may be used to scale a +constant by +@c TEXI2ROFF-KILL +@ifinfo +@c END TEXI2ROFF-KILL +@code{1024} or @code{1024*1024} +@c TEXI2ROFF-KILL +@end ifinfo +@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; +@end smallexample + +@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 point +and may include any letters, underscores, digits, points, +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 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 must always appear in an +expression within a @code{SECTIONS} command. The @code{.} symbol +may appear anywhere that an ordinary symbol is allowed in an +expression, but its assignments have a side effect. Assigning a value +to the @code{.} symbol will cause the location counter to be moved. +@cindex holes +This may be used to create holes in the output section. The location +counter may never be moved backwards. +@smallexample +SECTIONS +@{ + output : + @{ + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + @} = 0x1234; +@} +@end smallexample +@noindent +In the previous example, @code{file1} is located at the beginning of the +output section, then there is a 1000 byte gap. Then @code{file2} +appears, also with a 1000 byte gap following before @code{file3} is +loaded. The notation @samp{= 0x1234} specifies what data to write in +the gaps (@pxref{Section Options}). + +@iftex +@vfill +@end iftex + +@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 +@ifinfo +@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{Assignment}. +@c TEXI2ROFF-KILL +@end ifinfo +@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{Assignment}. +} +@end iftex +@c END TEXI2ROFF-KILL + +@node Evaluation +@subsection Evaluation + +@cindex lazy evaluation +@cindex expression evaluation order +The linker uses ``lazy evaluation'' for expressions; it only calculates +an expression when absolutely necessary. The linker needs the value of +the start address, and the 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 command file. 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. + +@node Assignment +@subsection Assignment: Defining Symbols +@cindex assignment in scripts +@cindex symbol definition, scripts +@cindex variables, defining +You may create global symbols, and assign values (addresses) to global +symbols, 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} ; +@end table + +Two things distinguish assignment from other operators in @code{ld} +expressions. +@itemize @bullet +@item +Assignment may only be used at the root of an expression; +@samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error. + +@kindex ; +@cindex semicolon +@item +You must place a trailing semicolon (``@key{;}'') at the end of an +assignment statement. +@end itemize + +Assignment statements may appear: +@itemize @bullet +@item +as commands in their own right in an @code{ld} script; or +@item +as independent statements within a @code{SECTIONS} command; or +@item +as part of the contents of a section definition in a +@code{SECTIONS} command. +@end itemize + +The first two cases are equivalent in effect---both define a symbol with +an absolute address. The last case defines a symbol whose address is +relative to a particular section (@pxref{SECTIONS}). + +@cindex absolute and relocatable symbols +@cindex relocatable and absolute symbols +@cindex symbols, relocatable and absolute +When a linker expression is evaluated and assigned to a variable, it is +given either an absolute or a relocatable type. An absolute expression +type is one in which the symbol contains the value that it will have in +the output file; a relocatable expression type is one in which the +value is expressed as a fixed offset from the base of a section. + +The type of the expression is controlled by its position in the script +file. A symbol assigned within a section definition is created relative +to the base of the section; a symbol assigned in any other place is +created as an absolute symbol. Since a symbol created within a +section definition is relative to the base of the section, it +will remain relocatable if relocatable output is requested. A symbol +may be created with an absolute value even when assigned to within a +section definition by using the absolute assignment function +@code{ABSOLUTE}. For example, to create an absolute symbol whose address +is the last byte of an output section named @code{.data}: +@smallexample +SECTIONS@{ @dots{} + .data : + @{ + *(.data) + _edata = ABSOLUTE(.) ; + @} +@dots{} @} +@end smallexample + +The linker tries to put off the evaluation of an assignment until all +the terms in the source expression are known (@pxref{Evaluation}). For +instance, 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 @dfn{dot}, @samp{.} must be evaluated during 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 +SECTIONS @{ @dots{} + text 9+this_isnt_constant : + @{ @dots{} + @} +@dots{} @} +@end smallexample +@kindex Non constant expression +@noindent +will cause the error message ``@code{Non constant expression for initial +address}''. + +@cindex provide +In some cases, it is desirable for a linker script to define a symbol +only if it is referenced, and only if it 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})}. + +@node Arithmetic Functions +@subsection Arithmetic Functions +@cindex functions in expression language +The command language includes a number of built-in +functions for use in link script expressions. +@table @code +@kindex ABSOLUTE(@var{exp}) +@cindex expression, absolute +@item ABSOLUTE(@var{exp}) +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. + +@kindex ADDR(@var{section}) +@cindex section address +@item ADDR(@var{section}) +Return the absolute address of the named @var{section}. Your script must +previously have defined the location of that section. In the following +example, @code{symbol_1} and @code{symbol_2} are assigned identical +values: +@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 + +@kindex LOADADDR(@var{section}) +@cindex section load address +@item LOADADDR(@var{section}) +Return the absolute load address of the named @var{section}. This is +normally the same as @code{ADDR}, but it may be different if the +@code{AT} keyword is used in the section definition (@pxref{Section +Options}). + +@kindex ALIGN(@var{exp}) +@cindex rounding up location counter +@item ALIGN(@var{exp}) +Return the result of the current location counter (@code{.}) aligned to +the next @var{exp} boundary. @var{exp} must be an expression whose +value is a power of two. This is equivalent to +@smallexample +(. + @var{exp} - 1) & ~(@var{exp} - 1) +@end smallexample + +@code{ALIGN} doesn't change the value of the location counter---it just +does arithmetic on it. As an example, to align the output @code{.data} +section to the next @code{0x2000} byte boundary after the preceding +section and to set 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{start} attribute of a +section definition (@pxref{Section Options}). The second use simply +defines the value of a variable. + +The built-in @code{NEXT} is closely related to @code{ALIGN}. + +@kindex DEFINED(@var{symbol}) +@cindex symbol defaults +@item DEFINED(@var{symbol}) +Return 1 if @var{symbol} is in the linker global symbol table and is +defined, otherwise return 0. You can use this function to provide default +values for symbols. For example, the following command-file fragment shows how +to set a global symbol @code{begin} to the first location in the +@code{.text} section---but if a symbol called @code{begin} already +existed, its value is preserved: + +@smallexample +@group +SECTIONS@{ @dots{} + .text : @{ + begin = DEFINED(begin) ? begin : . ; + @dots{} + @} +@dots{} @} +@end group +@end smallexample + +@kindex NEXT(@var{exp}) +@cindex unallocated address, next +@item NEXT(@var{exp}) +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. + +@kindex SIZEOF(@var{section}) +@cindex section size +@item SIZEOF(@var{section}) +Return the size in bytes of the named @var{section}, if that section has +been allocated. In the following example, @code{symbol_1} and +@code{symbol_2} are assigned identical values: +@c What does it return if the section hasn't been allocated? 0? +@smallexample +@group +SECTIONS@{ @dots{} + .output @{ + .start = . ; + @dots{} + .end = . ; + @} + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); +@dots{} @} +@end group +@end smallexample + +@kindex SIZEOF_HEADERS +@cindex header size +@kindex sizeof_headers +@item SIZEOF_HEADERS +@itemx sizeof_headers +Return the size in bytes of the output file's headers. You can use this number +as the start address of the first section, if you choose, to facilitate +paging. + +@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}. + +@end table + +@node Semicolons +@subsection Semicolons + +Semicolons (``@key{;}'') are required in the following places. In all +other places they can appear for aesthetic reasons but are otherwise ignored. + +@table @code +@item Assignment +Semicolons must appear at the end of assignment expressions. +@xref{Assignment} + +@item PHDRS +Semicolons must appear at the end of a @code{PHDRS} statement. +@xref{PHDRS} +@end table + +@node MEMORY +@section Memory Layout +@kindex MEMORY +@cindex regions of memory +@cindex discontinuous memory +@cindex allocating memory +The linker's default configuration permits allocation of all available memory. +You can override this configuration by using the @code{MEMORY} command. The +@code{MEMORY} command describes the location and size of blocks of +memory in the target. By using it carefully, you can describe which +memory regions may be used by the linker, and which memory regions it +must avoid. The linker does not shuffle sections to fit into the +available regions, but does move the requested sections into the correct +regions and issue errors when the regions become too full. + +A command file may contain at most one use of the @code{MEMORY} +command; however, you can define as many blocks of memory within it as +you wish. The syntax is: + +@smallexample +@group +MEMORY + @{ + @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len} + @dots{} + @} +@end group +@end smallexample +@table @code +@cindex naming memory regions +@item @var{name} +is a name used internally by the linker to refer to the region. Any +symbol name may be used. The region names are stored in a separate +name space, and will not conflict with symbols, file names or section +names. Use distinct names to specify multiple regions. + +@cindex memory region attributes +@item (@var{attr}) +is an optional list of attributes, permitted for compatibility with the +AT&T linker but not used by @code{ld} beyond checking that the +attribute list is valid. Valid attribute lists must be made up of the +characters ``@code{LIRWX}''. If you omit the attribute list, you may +omit the parentheses around it as well. + +@kindex ORIGIN = +@kindex o = +@kindex org = +@item @var{origin} +is the start address of the region in physical memory. It is +an expression that must evaluate to a constant before +memory allocation is performed. The keyword @code{ORIGIN} may be +abbreviated to @code{org} or @code{o} (but not, for example, @samp{ORG}). + +@kindex LENGTH = +@kindex len = +@kindex l = +@item @var{len} +is the size in bytes of the region (an expression). +The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}. +@end table + +For example, to specify that memory has two regions available for +allocation---one starting at 0 for 256 kilobytes, and the other +starting at @code{0x40000000} for four megabytes: + +@smallexample +@group +MEMORY + @{ + rom : ORIGIN = 0, LENGTH = 256K + ram : org = 0x40000000, l = 4M + @} +@end group +@end smallexample + +Once you have defined a region of memory named @var{mem}, you can direct +specific output sections there by using a command ending in +@samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section +Options}). If the combined output sections directed to a region are too +big for the region, the linker will issue an error message. + +@node SECTIONS +@section Specifying Output Sections + +@kindex SECTIONS +The @code{SECTIONS} command controls exactly where input sections are +placed into output sections, their order in the output file, and to +which output sections they are allocated. + +You may use at most one @code{SECTIONS} command in a script file, +but you can have as many statements within it as you wish. Statements +within the @code{SECTIONS} command can do one of three things: + +@itemize @bullet +@item +define the entry point; + +@item +assign a value to a symbol; + +@item +describe the placement of a named output section, and which input +sections go into it. +@end itemize + +You can also use the first two operations---defining the entry point and +defining symbols---outside the @code{SECTIONS} command: @pxref{Entry +Point}, and @ref{Assignment}. They are permitted here as well for +your convenience in reading the script, so that symbols and the entry +point can be defined at meaningful points in your output-file layout. + +If you do not use a @code{SECTIONS} command, the linker places 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. + +@menu +* Section Definition:: Section Definitions +* Section Placement:: Section Placement +* Section Data Expressions:: Section Data Expressions +* Section Options:: Optional Section Attributes +* Overlays:: Overlays +@end menu + +@node Section Definition +@subsection Section Definitions +@cindex section definition +The most frequently used statement in the @code{SECTIONS} command is +the @dfn{section definition}, which specifies the +properties of an output section: its location, alignment, contents, +fill pattern, and target memory region. Most of +these specifications are optional; the simplest form of a section +definition is +@smallexample +SECTIONS @{ @dots{} + @var{secname} : @{ + @var{contents} + @} +@dots{} @} +@end smallexample +@cindex naming output sections +@noindent +@var{secname} is the name of the output section, and @var{contents} a +specification of what goes there---for example, a list of input files or +sections of input files (@pxref{Section Placement}). As you might +assume, the whitespace shown is optional. You do need the colon +@samp{:} and the braces @samp{@{@}}, however. + +@var{secname} 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 @code{.text}, @code{.data} or +@code{.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 any name which does not conform to the standard +@code{ld} symbol name syntax must be quoted. +@xref{Symbols, , Symbol Names}. + +The special @var{secname} @samp{/DISCARD/} may be used to discard input +sections. Any sections which are assigned to an output section named +@samp{/DISCARD/} are not included in the final link output. + +The linker will not create output sections which do not have any +contents. This is for convenience when referring to input sections that +may or may not exist. For example, +@smallexample +.foo @{ *(.foo) @} +@end smallexample +will only create a @samp{.foo} section in the output file if there is a +@samp{.foo} section in at least one input file. + +@node Section Placement +@subsection Section Placement + +@cindex contents of a section +In a section definition, you can specify the contents of an output +section by listing particular input files, by listing particular +input-file sections, or by a combination of the two. You can also place +arbitrary data in the section, and define symbols relative to the +beginning of the section. + +The @var{contents} of a section definition may include any of the +following kinds of statement. You can include as many of these as you +like in a single section definition, separated from one another by +whitespace. + +@table @code +@kindex @var{filename} +@cindex input files, section defn +@cindex files, including in output sections +@item @var{filename} +You may simply name a particular input file to be placed in the current +output section; @emph{all} sections from that file are placed in the +current section definition. If the file name has already been mentioned +in another section definition, with an explicit section name list, then +only those sections which have not yet been allocated are used. + +To specify a list of particular files by name: +@smallexample +.data : @{ afile.o bfile.o cfile.o @} +@end smallexample +@noindent +The example also illustrates that multiple statements can be included in +the contents of a section definition, since each file name is a separate +statement. + +@kindex @var{filename}(@var{section}) +@cindex files and sections, section defn +@item @var{filename}( @var{section} ) +@itemx @var{filename}( @var{section} , @var{section}, @dots{} ) +@itemx @var{filename}( @var{section} @var{section} @dots{} ) +You can name one or more sections from your input files, for +insertion in the current output section. If you wish to specify a list +of input-file sections inside the parentheses, you may separate the +section names by either commas or whitespace. + +@cindex input sections to output section +@kindex *(@var{section}) +@item * (@var{section}) +@itemx * (@var{section}, @var{section}, @dots{}) +@itemx * (@var{section} @var{section} @dots{}) +Instead of explicitly naming particular input files in a link control +script, you can refer to @emph{all} files from the @code{ld} command +line: use @samp{*} instead of a particular file name before the +parenthesized input-file section list. + +If you have already explicitly included some files by name, @samp{*} +refers to all @emph{remaining} files---those whose places in the output +file have not yet been defined. + +For example, to copy sections @code{1} through @code{4} from an Oasys file +into the @code{.text} section of an @code{a.out} file, and sections @code{13} +and @code{14} into the @code{.data} section: +@smallexample +@group +SECTIONS @{ + .text :@{ + *("1" "2" "3" "4") + @} + + .data :@{ + *("13" "14") + @} +@} +@end group +@end smallexample + +@cindex @code{[@var{section}@dots{}]}, not supported +@samp{[ @var{section} @dots{} ]} used to be accepted as an alternate way +to specify named sections from all unallocated input files. Because +some operating systems (VMS) allow brackets in file names, that notation +is no longer supported. + +@cindex uninitialized data +@cindex commons in output +@kindex *( COMMON ) +@item @var{filename}@code{( COMMON )} +@itemx *( COMMON ) +Specify where in your output file to place uninitialized data +with this notation. @code{*(COMMON)} by itself refers to all +uninitialized data from all input files (so far as it is not yet +allocated); @var{filename}@code{(COMMON)} refers to uninitialized data +from a particular file. Both are special cases of the general +mechanisms for specifying where to place input-file sections: +@code{ld} permits you to refer to uninitialized data as if it +were in an input-file section named @code{COMMON}, regardless of the +input file's format. +@end table + +In any place where you may use a specific file or section name, you may +also use a wildcard pattern. The linker handles wildcards much as the +Unix shell does. A @samp{*} character matches any number of characters. +A @samp{?} character matches any single character. The sequence +@samp{[@var{chars}]} will match 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. A +@samp{\} character may be used to quote the following character. + +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. In a section name, the +wildcard characters will match a @samp{/} character. + +Wildcards only match files which are explicitly specified on the command +line. The linker does not search directories to expand wildcards. +However, if you specify a simple file name---a name with no wildcard +characters---in a linker script, and the file name is not also specified +on the command line, the linker will attempt to open the file as though +it appeared on the command line. + +In the following example, the command script arranges the output file +into three consecutive sections, named @code{.text}, @code{.data}, and +@code{.bss}, taking the input for each from the correspondingly named +sections of all the input files: + +@smallexample +@group +SECTIONS @{ + .text : @{ *(.text) @} + .data : @{ *(.data) @} + .bss : @{ *(.bss) *(COMMON) @} +@} +@end group +@end smallexample + +The following example reads all of the sections from file @code{all.o} +and places them at the start of output section @code{outputa} which +starts at location @code{0x10000}. All of section @code{.input1} from +file @code{foo.o} follows immediately, in the same output section. All +of section @code{.input2} from @code{foo.o} goes into output section +@code{outputb}, followed by section @code{.input1} from @code{foo1.o}. +All of the remaining @code{.input1} and @code{.input2} sections from any +files are written to output section @code{outputc}. + +@smallexample +@group +SECTIONS @{ + outputa 0x10000 : + @{ + all.o + foo.o (.input1) + @} + outputb : + @{ + foo.o (.input2) + foo1.o (.input1) + @} + outputc : + @{ + *(.input1) + *(.input2) + @} +@} +@end group +@end smallexample + +This example shows how wildcard patterns might be used to partition +files. All @code{.text} sections are placed in @code{.text}, and all +@code{.bss} sections are placed in @code{.bss}. For all files beginning +with an upper case character, the @code{.data} section is placed into +@code{.DATA}; for all other files, the @code{.data} section is placed +into @code{.data}. + +@smallexample +@group +SECTIONS @{ + .text : @{ *(.text) @} + .DATA : @{ [A-Z]*(.data) @} + .data : @{ *(.data) @} + .bss : @{ *(.bss) @} +@} +@end group +@end smallexample + +@node Section Data Expressions +@subsection Section Data Expressions + +@cindex expressions in a section +The foregoing statements arrange, in your output file, data originating +from your input files. You can also place data directly in an output +section from the link command script. Most of these additional +statements involve expressions (@pxref{Expressions}). Although these +statements are shown separately here for ease of presentation, no such +segregation is needed within a section definition in the @code{SECTIONS} +command; you can intermix them freely with any of the statements we've +just described. + +@table @code +@cindex input filename symbols +@cindex filename symbols +@kindex CREATE_OBJECT_SYMBOLS +@item CREATE_OBJECT_SYMBOLS +Create a symbol for each input file +in the current section, set to the address of the first byte of +data written from that input file. For instance, with @code{a.out} +files it is conventional to have a symbol for each input file. You can +accomplish this by defining the output @code{.text} section as follows: +@smallexample +@group +SECTIONS @{ + .text 0x2020 : + @{ + CREATE_OBJECT_SYMBOLS + *(.text) + _etext = ALIGN(0x2000); + @} + @dots{} +@} +@end group +@end smallexample + +If @code{sample.ld} is a file containing this script, and @code{a.o}, +@code{b.o}, @code{c.o}, and @code{d.o} are four input files with +contents like the following--- +@smallexample +@group +/* a.c */ + +afunction() @{ @} +int adata=1; +int abss; +@end group +@end smallexample + +@noindent +@samp{ld -M -T sample.ld a.o b.o c.o d.o} would create a map like this, +containing symbols matching the object file names: +@smallexample +00000000 A __DYNAMIC +00004020 B _abss +00004000 D _adata +00002020 T _afunction +00004024 B _bbss +00004008 D _bdata +00002038 T _bfunction +00004028 B _cbss +00004010 D _cdata +00002050 T _cfunction +0000402c B _dbss +00004018 D _ddata +00002068 T _dfunction +00004020 D _edata +00004030 B _end +00004000 T _etext +00002020 t a.o +00002038 t b.o +00002050 t c.o +00002068 t d.o +@end smallexample + +@kindex @var{symbol} = @var{expression} ; +@kindex @var{symbol} @var{f}= @var{expression} ; +@item @var{symbol} = @var{expression} ; +@itemx @var{symbol} @var{f}= @var{expression} ; +@var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}='' +refers to any of the operators @code{&= += -= *= /=} which combine +arithmetic and assignment. + +@cindex assignment, in section defn +When you assign a value to a symbol within a particular section +definition, the value is relative to the beginning of the section +(@pxref{Assignment}). If you write + +@smallexample +@group +SECTIONS @{ + abs = 14 ; + @dots{} + .data : @{ @dots{} rel = 14 ; @dots{} @} + abs2 = 14 + ADDR(.data); + @dots{} +@} +@end group +@end smallexample + +@c FIXME: Try above example! +@noindent +@code{abs} and @code{rel} do not have the same value; @code{rel} has the +same value as @code{abs2}. + +@kindex BYTE(@var{expression}) +@kindex SHORT(@var{expression}) +@kindex LONG(@var{expression}) +@kindex QUAD(@var{expression}) +@cindex direct output +@item BYTE(@var{expression}) +@itemx SHORT(@var{expression}) +@itemx LONG(@var{expression}) +@itemx QUAD(@var{expression}) +By including one of these four statements in a section definition, you +can explicitly place one, two, four, or eight bytes (respectively) at +the current address of that section. @code{QUAD} is only supported when +using a 64 bit host or target. + +@ifclear SingleFormat +Multiple-byte quantities are represented in whatever byte order is +appropriate for the output file format (@pxref{BFD}). +@end ifclear + +@kindex FILL(@var{expression}) +@cindex holes, filling +@cindex unspecified memory +@item FILL(@var{expression}) +Specify the ``fill pattern'' for the current section. Any otherwise +unspecified regions of memory within the section (for example, regions +you skip over by assigning a new value to the location counter @samp{.}) +are filled with the two least significant bytes from the +@var{expression} argument. A @code{FILL} statement covers memory +locations @emph{after} the point 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. +@end table + +@node Section Options +@subsection Optional Section Attributes +@cindex section defn, full syntax +Here is the full syntax of a section definition, including all the +optional portions: + +@smallexample +@group +SECTIONS @{ +@dots{} +@var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : AT ( @var{ldadr} ) + @{ @var{contents} @} >@var{region} :@var{phdr} =@var{fill} +@dots{} +@} +@end group +@end smallexample + +@var{secname} and @var{contents} are required. @xref{Section +Definition}, and @ref{Section Placement}, for details on +@var{contents}. The remaining elements---@var{start}, +@code{BLOCK(@var{align)}}, @code{(NOLOAD)}, @code{AT ( @var{ldadr} )}, +@code{>@var{region}}, @code{:@var{phdr}}, and @code{=@var{fill}}---are +all optional. + +@table @code +@cindex start address, section +@cindex section start +@cindex section address +@item @var{start} +You can force the output section to be loaded at a specified address by +specifying @var{start} immediately following the section name. +@var{start} can be represented as any expression. The following +example generates section @var{output} at location +@code{0x40000000}: + +@smallexample +@group +SECTIONS @{ + @dots{} + output 0x40000000: @{ + @dots{} + @} + @dots{} +@} +@end group +@end smallexample + +@kindex BLOCK(@var{align}) +@cindex section alignment +@cindex aligning sections +@item BLOCK(@var{align}) +You can include @code{BLOCK()} specification to advance +the location counter @code{.} prior to the beginning of the section, so +that the section will begin at the specified alignment. @var{align} is +an expression. + +@kindex NOLOAD +@cindex prevent unnecessary loading +@cindex loading, preventing +@item (NOLOAD) +Use @samp{(NOLOAD)} to prevent a section from being loaded into memory +each time it is accessed. For example, in the script sample below, the +@code{ROM} segment is addressed at memory location @samp{0} and does not +need to be loaded into each object file: + +@smallexample +@group +SECTIONS @{ + ROM 0 (NOLOAD) : @{ @dots{} @} + @dots{} +@} +@end group +@end smallexample + +@kindex AT ( @var{ldadr} ) +@cindex specify load address +@cindex load address, specifying +@item AT ( @var{ldadr} ) +The expression @var{ldadr} that follows the @code{AT} keyword specifies +the load address of the section. The default (if you do not use the +@code{AT} keyword) is to make the load address the same as the +relocation address. This feature is designed to make it easy to build a +ROM image. For example, this @code{SECTIONS} definition creates two +output sections: one called @samp{.text}, which starts at @code{0x1000}, +and one called @samp{.mdata}, which is loaded at the end of the +@samp{.text} section even though its relocation address is +@code{0x2000}. The symbol @code{_data} is defined with the value +@code{0x2000}: + +@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 C programs, usually @code{crt0}) +for use with a ROM generated this way has to include something like +the following, to copy the initialized data from the ROM image to its runtime +address: + +@smallexample +@group +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 + +@kindex >@var{region} +@cindex section, assigning to memory region +@cindex memory regions and sections +@item >@var{region} +Assign this section to a previously defined region of memory. +@xref{MEMORY}. + +@kindex :@var{phdr} +@cindex section, assigning to program header +@cindex program headers and sections +@item :@var{phdr} +Assign this section to a segment described by a program header. +@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. To +prevent a section from being assigned to a segment when it would +normally default to one, use @code{:NONE}. + +@kindex =@var{fill} +@cindex section fill pattern +@cindex fill pattern, entire section +@item =@var{fill} +Including @code{=@var{fill}} in a section definition specifies the +initial fill value for that section. You may use any expression to +specify @var{fill}. Any unallocated holes in the current output section +when written to the output file will be filled with the two least +significant bytes of the value, repeated as necessary. You can also +change the fill value with a @code{FILL} statement in the @var{contents} +of a section definition. + +@end table + +@node Overlays +@subsection Overlays +@kindex OVERLAY +@cindex overlays + +The @code{OVERLAY} command 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. + +The @code{OVERLAY} command is used within a @code{SECTIONS} command. It +appears as follows: +@smallexample +@group + OVERLAY @var{start} : [ NOCROSSREFS ] AT ( @var{ldaddr} ) + @{ + @var{secname1} @{ @var{contents} @} :@var{phdr} =@var{fill} + @var{secname2} @{ @var{contents} @} :@var{phdr} =@var{fill} + @dots{} + @} >@var{region} :@var{phdr} =@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} contruct (@pxref{SECTIONS}), +except that no addresses and no memory regions may be defined for +sections within an @code{OVERLAY}. + +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 @code{.}). + +If the @code{NOCROSSREFS} keyword is used, and there 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{Option Commands, +NOCROSSREFS}. + +For each section within the @code{OVERLAY}, the linker automatically +defines 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 @code{.} 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 + +This will define both @code{.text0} and @code{.text1} to start at +address 0x1000. @code{.text0} will be loaded at address 0x4000, and +@code{.text1} will be loaded immediately after @code{.text0}. The +following symbols will be defined: @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) @} + __load_start_text0 = LOADADDR (.text0); + __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @} + __load_start_text1 = LOADADDR (.text1); + __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); +@end group +@end smallexample + +@node PHDRS +@section ELF Program Headers +@kindex PHDRS +@cindex program headers +@cindex ELF program headers + +The ELF object file format uses @dfn{program headers}, which are read by +the system loader and describe how the program should be loaded into +memory. These program headers must be set correctly in order to run the +program on a native ELF system. The linker will create reasonable +program headers by default. However, in some cases, it is desirable to +specify the program headers more precisely; the @code{PHDRS} command may +be used for this purpose. When the @code{PHDRS} command is used, the +linker will not generate any program headers itself. + +The @code{PHDRS} command is only meaningful when generating an ELF +output file. It is ignored in other cases. This manual does not +describe the details of how the system loader interprets program +headers; for more information, see the ELF ABI. The program headers of +an ELF file may be displayed using the @samp{-p} option of the +@code{objdump} command. + +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 does not get put into the output file. + +Certain program header types describe segments of memory which are +loaded from the file by the system loader. In the linker script, the +contents of these segments are specified by directing allocated output +sections to be placed in the segment. To do this, the command +describing the output section in the @code{SECTIONS} command should use +@samp{:@var{name}}, where @var{name} is the name of the program header +as it appears in the @code{PHDRS} command. @xref{Section Options}. + +It is normal for certain sections to appear in more than one segment. +This merely implies that one segment of memory contains another. This +is specified by repeating @samp{:@var{name}}, using it once for each +program header in which the section is to appear. + +If a section is placed in one or more segments using @samp{:@var{name}}, +then all subsequent allocated sections which do not specify +@samp{:@var{name}} are placed in the same segments. This is for +convenience, since generally a whole set of contiguous sections will be +placed in a single segment. To prevent a section from being assigned to +a segment when it would normally default to one, use @code{:NONE}. + +The @code{FILEHDR} and @code{PHDRS} keywords which may appear after the +program header type also indicate contents of the segment of memory. +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. + +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 @var{expression} +An expression giving the numeric type of the program header. This may +be used for types not defined above. +@end table + +It is possible to specify that a segment should be loaded at a +particular address in memory. This is done using an @code{AT} +expression. This is identical to the @code{AT} command used in the +@code{SECTIONS} command (@pxref{Section Options}). Using the @code{AT} +command for a program header overrides any information in the +@code{SECTIONS} command. + +Normally the segment flags are set based on the sections. The +@code{FLAGS} keyword may be used 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 the use 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 Entry Point +@section The Entry Point +@kindex ENTRY(@var{symbol}) +@cindex start of execution +@cindex first instruction +The linker command language includes a command specifically for +defining the first executable instruction in an output file (its +@dfn{entry point}). Its argument is a symbol name: +@smallexample +ENTRY(@var{symbol}) +@end smallexample + +Like symbol assignments, the @code{ENTRY} command may be placed either +as an independent command in the command file, or among the section +definitions within the @code{SECTIONS} command---whatever makes the most +sense for your layout. + +@cindex entry point, defaults +@code{ENTRY} is only one of several ways of choosing the entry point. +You may indicate it in any of the following ways (shown in descending +order of priority: methods higher in the list override methods lower down). +@itemize @bullet +@item +the @samp{-e} @var{entry} command-line option; +@item +the @code{ENTRY(@var{symbol})} command in a linker control script; +@item +the value of the symbol @code{start}, if present; +@item +the address of the first byte of the @code{.text} section, if present; +@item +The address @code{0}. +@end itemize + +For example, you can use these rules to generate an entry point with an +assignment statement: if no symbol @code{start} is defined within your +input files, you can simply define it, assigning it an appropriate +value--- + +@smallexample +start = 0x2020; +@end smallexample + +@noindent +The example shows an absolute address, but you can use any expression. +For example, if your input object files use some other symbol-name +convention for the entry point, you can just assign the value of +whatever symbol contains the start address to @code{start}: + +@smallexample +start = other_symbol ; +@end smallexample + +@node Version Script +@section Version Script +@kindex VERSION @{script text@} +@cindex symbol versions +@cindex version script +@cindex versions of symbols +The linker command script includes a command specifically for +specifying a version script, and is only meaningful for ELF platforms +that support shared libraries. A version script can be +build directly into the linker script that you are using, or you +can supply the version script as just another input file to the linker +at the time that you link. The command script syntax is: +@smallexample +VERSION @{ version script contents @} +@end smallexample +The version script can also be specified to the linker by means of the +@samp{--version-script} linker command line option. +Version scripts are only meaningful when creating shared libraries. + +The format of the version script itself is identical to that used by +Sun's linker in Solaris 2.5. Versioning is done by defining a tree of +version nodes with the names and interdependencies specified in the +version script. The version script can specify which symbols are bound +to which version nodes, and it 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; +@} VERS_1.2; +@end smallexample + +In this example, three version nodes are defined. @samp{VERS_1.1} is the +first version node defined, and has no other dependencies. The symbol +@samp{foo1} is bound to this version node, and a number of symbols +that have appeared within various object files are reduced in scope to +local so that they are not visible outside of the shared library. + +Next, the node @samp{VERS_1.2} is defined. It depends upon +@samp{VERS_1.1}. The symbol @samp{foo2} is bound to this version node. + +Finally, the node @samp{VERS_2.0} is defined. It depends upon +@samp{VERS_1.2}. The symbols @samp{bar1} and @samp{bar2} are bound to +this version node. + +Symbols defined in the library which aren't specifically bound to a +version node are effectively bound to an unspecified base version of the +library. It is possible to bind all otherwise unspecified symbols to a +given version node using @samp{global: *} somewhere in the version +script. + +Lexically 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. + +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. This can be done by putting something like: + +@smallexample +__asm__(".symver original_foo,foo@@VERS_1.1"); +@end smallexample + +in the C source file. This renamed 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. + +The second GNU extension is to allow multiple versions of the same function +to appear in a given shared library. In this way an incompatible change to +an interface can take place without increasing the major version number of +the shared library, while still allowing applications linked against the old +interface to continue to function. + +This can only be accomplished by using multiple @samp{.symver} +directives in the assembler. An example of this would be: + +@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. This can be accomplished with the +@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. Only one version of +a symbol can be declared '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. + +@node Option Commands +@section Option Commands +The command language includes a number of other commands that you can +use for specialized purposes. They are similar in purpose to +command-line options. + +@table @code +@kindex CONSTRUCTORS +@cindex C++ constructors, arranging in link +@cindex constructors, arranging in link +@item CONSTRUCTORS +When linking using the @code{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 @code{ECOFF} and @code{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 where this information should be placed. 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{__DTOR_LIST}} marks the end. 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++ 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++ 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 +multiple sections, @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 + +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. + +@need 1000 +@kindex FLOAT +@kindex NOFLOAT +@item FLOAT +@itemx NOFLOAT +These keywords were used in some older linkers to request a particular +math subroutine library. @code{ld} doesn't use the keywords, assuming +instead that any necessary subroutines are in libraries specified using +the general mechanisms for linking to archives; but to permit the use of +scripts that were written for the older linkers, the keywords +@code{FLOAT} and @code{NOFLOAT} are accepted and ignored. + +@kindex FORCE_COMMON_ALLOCATION +@cindex common allocation +@item FORCE_COMMON_ALLOCATION +This command has the same effect as the @samp{-d} command-line option: +to make @code{ld} assign space to common symbols even if a relocatable +output file is specified (@samp{-r}). + +@kindex INCLUDE @var{filename} +@cindex including a linker script +@item INCLUDE @var{filename} +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 @code{-L} option. You can nest calls to @code{INCLUDE} up to +10 levels deep. + +@kindex INPUT ( @var{files} ) +@cindex binary input files +@item INPUT ( @var{file}, @var{file}, @dots{} ) +@itemx INPUT ( @var{file} @var{file} @dots{} ) +Use this command to include binary input files in the link, without +including them in a particular section definition. +Specify the full name for each @var{file}, including @samp{.a} if +required. + +@code{ld} searches for each @var{file} through the archive-library +search path, just as for files you specify on the command line. +See the description of @samp{-L} in @ref{Options,,Command Line +Options}. + +If you use @samp{-l@var{file}}, @code{ld} will transform the name to +@code{lib@var{file}.a} as with the command line argument @samp{-l}. + +@kindex GROUP ( @var{files} ) +@cindex grouping input files +@item GROUP ( @var{file}, @var{file}, @dots{} ) +@itemx GROUP ( @var{file} @var{file} @dots{} ) +This 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}. + +@ignore +@kindex MAP ( @var{name} ) +@item MAP ( @var{name} ) +@c MAP(...) appears to look for an F in the arg, ignoring all other +@c chars; if it finds one, it sets "map_option_f" to true. But nothing +@c checks map_option_f. Apparently a stub for the future... +@end ignore + +@kindex OUTPUT ( @var{filename} ) +@cindex naming the output file +@item OUTPUT ( @var{filename} ) +Use this command to name the link output file @var{filename}. The +effect of @code{OUTPUT(@var{filename})} is identical to the effect of +@w{@samp{-o @var{filename}}}, which overrides it. You can use this +command to supply a default output-file name other than @code{a.out}. + +@ifclear SingleFormat +@kindex OUTPUT_ARCH ( @var{bfdname} ) +@cindex machine architecture, output +@item OUTPUT_ARCH ( @var{bfdname} ) +Specify a particular output machine architecture, with one of the names +used by the BFD back-end routines (@pxref{BFD}). This command is often +unnecessary; the architecture is most often set implicitly by either the +system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT} +command. + +@kindex OUTPUT_FORMAT ( @var{bfdname} ) +@cindex format, output file +@item OUTPUT_FORMAT ( @var{bfdname} ) +When @code{ld} is configured to support multiple object code formats, +you can use this command to specify a particular output format. +@var{bfdname} is one of the names used by the BFD back-end routines +(@pxref{BFD}). The effect is identical to the effect of the +@samp{--oformat} command-line option. This selection affects only the +output file; the related command @code{TARGET} affects primarily input +files. +@end ifclear + +@kindex SEARCH_DIR ( @var{path} ) +@cindex path for libraries +@cindex search path, libraries +@item SEARCH_DIR ( @var{path} ) +Add @var{path} to the list of paths where @code{ld} looks for +archive libraries. @code{SEARCH_DIR(@var{path})} has the same +effect as @samp{-L@var{path}} on the command line. + +@kindex STARTUP ( @var{filename} ) +@cindex first input file +@item STARTUP ( @var{filename} ) +Ensure that @var{filename} is the first input file used in the link +process. + +@ifclear SingleFormat +@cindex input file format +@kindex TARGET ( @var{format} ) +@item TARGET ( @var{format} ) +When @code{ld} is configured to support multiple object code formats, +you can use this command to change the input-file object code format +(like the command-line option @samp{-b} or its synonym @samp{--format}). +The argument @var{format} is one of the strings used by BFD to name +binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT} +is not, the last @code{TARGET} argument is also used as the default +format for the @code{ld} output file. @xref{BFD}. + +@kindex GNUTARGET +If you don't use the @code{TARGET} command, @code{ld} uses the value of +the environment variable @code{GNUTARGET}, if available, to select the +output file format. If that variable is also absent, @code{ld} uses +the default format configured for your machine in the BFD libraries. +@end ifclear + +@cindex cross references +@kindex NOCROSSREFS ( @var{sections} ) +@item NOCROSSREFS ( @var{section} @var{section} @dots{} ) +This command may be used to tell @code{ld} to issue an error about any +references among certain sections. + +In certain types of programs, particularly on embedded systems, 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 section names. If +@code{ld} detects any cross references between the sections, it reports +an error and returns a non-zero exit status. The @code{NOCROSSREFS} +command uses output section names, defined in the @code{SECTIONS} +command. It does not use the names of input sections. +@end table + +@ifset GENERIC +@node Machine Dependent +@chapter Machine Dependent Features + +@cindex machine dependencies +@code{ld} has additional features on some platforms; the following +sections describe them. Machines where @code{ld} has no additional +functionality are not listed. + +@menu +* H8/300:: @code{ld} and the H8/300 +* i960:: @code{ld} and the Intel 960 family +@end menu +@end ifset + +@c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict +@c between those and node-defaulting. +@ifset H8300 +@ifclear GENERIC +@raisesections +@end ifclear +@node H8/300 +@section @code{ld} and the H8/300 + +@cindex H8/300 support +For the H8/300, @code{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 +@code{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? +@code{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). +@end table +@ifclear GENERIC +@lowersections +@end ifclear +@end ifset + +@ifclear GENERIC +@ifset Hitachi +@c This stuff is pointless to say unless you're especially concerned +@c with Hitachi chips; don't enable it for generic case, please. +@node Hitachi +@chapter @code{ld} and other Hitachi chips + +@code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No +special features, commands, or command-line options are required for +these chips. +@end ifset +@end ifclear + +@ifset I960 +@ifclear GENERIC +@raisesections +@end ifclear +@node i960 +@section @code{ld} and the Intel 960 family + +@cindex i960 support + +You can use the @samp{-A@var{architecture}} command line option to +specify one of the two-letter names identifying members of the 960 +family; the option specifies the desired output target, and warns of any +incompatible instructions in the input files. It also modifies the +linker's search strategy for archive libraries, to support the use of +libraries specific to each particular architecture, by including in the +search loop names suffixed with the string identifying the architecture. + +For example, if your @code{ld} command line included @w{@samp{-ACA}} as +well as @w{@samp{-ltry}}, the linker would look (in its built-in search +paths, and in any paths you specify with @samp{-L}) for a library with +the names + +@smallexample +@group +try +libtry.a +tryca +libtryca.a +@end group +@end smallexample + +@noindent +The first two possibilities would be considered in any event; the last +two are due to the use of @w{@samp{-ACA}}. + +You can meaningfully use @samp{-A} more than once on a command line, since +the 960 architecture family allows combination of target architectures; each +use will add another pair of name variants to search for when @w{@samp{-l}} +specifies a library. + +@cindex @code{--relax} on i960 +@cindex relaxing on i960 +@code{ld} supports the @samp{--relax} option for the i960 family. If +you specify @samp{--relax}, @code{ld} finds all @code{balx} and +@code{calx} instructions whose targets are within 24 bits, and turns +them into 24-bit program-counter relative @code{bal} and @code{cal} +instructions, respectively. @code{ld} also turns @code{cal} +instructions into @code{bal} instructions when it determines that the +target subroutine is a leaf routine (that is, the target subroutine does +not itself call any subroutines). + +@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 @code{ld} +@cindex reporting bugs in @code{ld} + +Your bug reports play an essential role in making @code{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 @code{ld} +work better. Bug reports are your contribution to the maintenance of +@code{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 +@code{ld} bug. Reliable linkers never crash. + +@cindex error on valid input +@item +If @code{ld} produces an error message for valid input, that is a bug. + +@cindex invalid input +@item +If @code{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 @code{ld} are welcome in any case. +@end itemize + +@node Bug Reporting +@section How to report bugs +@cindex bug reports +@cindex @code{ld} bugs, reporting + +A number of companies and individuals offer support for @sc{gnu} +products. If you obtained @code{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. + +In any event, we also recommend that you send bug reports for @code{ld} +to @samp{bug-gnu-utils@@prep.ai.mit.edu}. + +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?'' Those bug reports are useless, and we urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. + +To enable us to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of @code{ld}. @code{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 @code{ld}. + +@item +Any patches you may have applied to the @code{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 @code{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, +uuencoded if necessary to get them through the mail system. Making them +available for anonymous FTP is not as good, but may be the only +reasonable choice for large object files. + +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 @code{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 @code{ld} is out of synch, 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 @code{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 @code{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 @code{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} @code{ld} from the MRI +linker, @code{ld} can use MRI compatible linker scripts as an +alternative to the more general-purpose linker scripting language +described in @ref{Commands,,Command Language}. MRI compatible linker +scripts have a much simpler command set than the scripting language +otherwise used with @code{ld}. @sc{gnu} @code{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, @code{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, @code{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 one of these output formats: + +@enumerate +@item +S-records, if @var{output-format} is @samp{S} + +@item +IEEE, if @var{output-format} is @samp{IEEE} + +@item +COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is +@samp{COFF} +@end enumerate + +@cindex @code{LIST} (MRI) +@item LIST @var{anything}@dots{} +Print (to the standard output file) a link map, as produced by the +@code{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 @code{ld} +command line. + +@cindex @code{NAME} (MRI) +@item NAME @var{output-name} +@var{output-name} is the name for the program produced by @code{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, @code{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 Index +@unnumbered 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 + + +@contents +@bye + + |
