diff options
Diffstat (limited to 'ld/ld.texinfo')
| -rw-r--r-- | ld/ld.texinfo | 4366 |
1 files changed, 0 insertions, 4366 deletions
diff --git a/ld/ld.texinfo b/ld/ld.texinfo deleted file mode 100644 index 4494370aa8b..00000000000 --- a/ld/ld.texinfo +++ /dev/null @@ -1,4366 +0,0 @@ -\input texinfo -@setfilename ld.info -@syncodeindex ky cp -@include configdoc.texi -@c (configdoc.texi is generated by the Makefile) -@include ldver.texi - -@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 version @value{VERSION}. - -Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 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 Version @value{VERSION} -@author Steve Chamberlain -@author Ian Lance Taylor -@author Cygnus Solutions -@page - -@tex -{\parskip=0pt -\hfill Cygnus Solutions\par -\hfill ian\@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, 97, 98, 1999 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 version @value{VERSION}. - -@menu -* Overview:: Overview -* Invocation:: Invocation -* Scripts:: Linker Scripts -@ifset GENERIC -* Machine Dependent:: Machine Dependent Features -@end ifset -@ifclear GENERIC -@ifset H8300 -* H8/300:: ld and the H8/300 -@end ifset -@ifset 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.) - -Some of the command-line options to @code{ld} may be specified at any -point in the command line. However, options which refer to files, such -as @samp{-l} or @samp{-T}, cause the file to be read at the point at -which the option appears in the command line, relative to the object -files and other file options. Repeating non-file options with a -different argument will either have no further effect, or override prior -occurrences (those further to the left on the command line) of that -option. Options which may be meaningfully specified more than once are -noted in the descriptions below. - -@cindex object files -Non-option arguments are object files or archives which are to be linked -together. They may follow, precede, or be mixed in with command-line -options, except that an object file argument may not be placed between -an option and its argument. - -Usually the linker is invoked with at least one object file, but you can -specify other forms of binary input files using @samp{-l}, @samp{-R}, -and the script command language. If @emph{no} binary input files at all -are specified, the linker does not produce any output, and issues the -message @samp{No input files}. - -If the linker 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{Scripts}. - -For options whose names are a single letter, -option arguments must either follow the option letter without intervening -whitespace, or be given as separate arguments immediately following the -option that requires them. - -For options whose names are multiple letters, either one dash or two can -precede the option name; for example, @samp{--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{Format 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{Miscellaneous 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. If there is no symbol -named @var{entry}, the linker will try to parse @var{entry} as a number, -and use that as the entry address (the number will be interpreted in -base 10; you may use a leading @samp{0x} for base 16, or a leading -@samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults -and other ways of specifying the entry point. - -@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. The dynamic symbol table is the set of symbols -which are visible from dynamic objects at run time. - -If you do not use this option, the dynamic symbol table will normally -contain only those symbols which are referenced by some dynamic object -mentioned in the link. - -If you use @code{dlopen} to load a dynamic object which needs to refer -back to the symbols defined by the program, rather than some other -dynamic object, then you will probably need to use this option when -linking the program itself. - -@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. - -@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. - -@cindex finalization function -@kindex -fini -@item -fini @var{name} -When creating an ELF executable or shared object, call NAME when the -executable or shared object is unloaded, by setting DT_FINI to the -address of the function. By default, the linker uses @code{_fini} as -the function to call. - -@kindex -g -@item -g -Ignored. Provided for compatibility with other tools. - -@kindex -G -@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 initialization function -@kindex -init -@item -init @var{name} -When creating an ELF executable or shared object, call NAME when the -executable or shared object is loaded, by setting DT_INIT to the address -of the function. By default, the linker uses @code{_init} as the -function to call. - -@cindex archive files, from cmd line -@kindex -l@var{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. - -If the @samp{-m} option is not used, the emulation is taken from the -@code{LDEMULATION} environment variable, if that is defined. - -Otherwise, the default emulation depends upon how the linker was -configured. - -@cindex link map -@kindex -M -@kindex --print-map -@item -M -@itemx --print-map -Print a link map to the standard output. A link map provides -information about the link, including the following: - -@itemize @bullet -@item -Where object files and symbols are mapped into memory. -@item -How common symbols are allocated. -@item -All archive members included in the link, with a mention of the symbol -which caused the archive member to be brought in. -@end itemize - -@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. - -@kindex -O @var{level} -@cindex generating optimized output -@item -O @var{level} -If @var{level} is a numeric values greater than zero @code{ld} optimizes -the output. This might take significantly longer and therefore probably -should only be enabled for the final binary. - -@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{scriptfile} -@itemx --script=@var{scriptfile} -Use @var{scriptfile} as the linker script. This script replaces -@code{ld}'s default linker script (rather than adding to it), so -@var{commandfile} must specify everything necessary to describe the -output file. 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{Scripts}. If -@var{scriptfile} does not exist in the current directory, @code{ld} -looks for it in the directories specified by any preceding @samp{-L} -options. Multiple @samp{-T} options accumulate. - -@kindex -u @var{symbol} -@kindex --undefined=@var{symbol} -@cindex undefined symbol -@item -u @var{symbol} -@itemx --undefined=@var{symbol} -Force @var{symbol} to be entered in the output file as an undefined -symbol. Doing this may, for example, trigger linking of additional -modules from standard libraries. @samp{-u} may be repeated with -different option arguments to enter additional undefined symbols. This -option is equivalent to the @code{EXTERN} linker script command. - -@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 -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. - -@kindex --check-sections -@kindex --no-check-sections -@item --check-sections -@itemx --no-check-sections -Asks the linker @emph{not} to check section addresses after they have -been assigned to see if there any overlaps. Normally the linker will -perform this check, and if it finds any overlaps it will produce -suitable error messages. The linker does know about, and does make -allowances for sections in overlays. The default behaviour can be -restored by using the command line switch @samp{--check-sections}. - -@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{Assignments,, -Assignment: Symbol Definitions}). @emph{Note:} there should be no white -space between @var{symbol}, the equals sign (``@key{=}''), and -@var{expression}. - -@cindex demangling, from command line -@kindex --demangle -@kindex --no-demangle -@item --demangle -@itemx --no-demangle -These options control whether to demangle symbol names in error messages -and other output. When the linker is told to demangle, it tries to -present symbol names in a readable fashion: it strips leading -underscores if they are used by the object file format, and converts C++ -mangled symbol names into user readable names. The linker will demangle -by default unless the environment variable @samp{COLLECT_NO_DEMANGLE} is -set. These options may be used to override the default. - -@cindex dynamic linker, from command line -@kindex --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 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. - -@kindex --force-exe-suffix -@item --force-exe-suffix -Make sure that an output file has a .exe suffix. - -If a successfully built fully linked output file does not have a -@code{.exe} or @code{.dll} suffix, this option forces the linker to copy -the output file to one of the same name with a @code{.exe} suffix. This -option is useful when using unmodified Unix makefiles on a Microsoft -Windows host, since some versions of Windows won't run an image unless -it ends in a @code{.exe} suffix. - -@kindex --gc-sections -@kindex --no-gc-sections -@cindex garbage collection -@item --no-gc-sections -@itemx --gc-sections -Enable garbage collection of unused input sections. It is ignored on -targets that do not support this option. This option is not compatible -with @samp{-r}, nor should it be used with dynamic linking. The default -behaviour (of not performing this garbage collection) can be restored by -specifying @samp{--no-gc-sections} on the command line. - -@cindex help -@cindex usage -@kindex --help -@item --help -Print a summary of the command-line options on the standard output and exit. - -@kindex -Map -@item -Map @var{mapfile} -Print a link map to the file @var{mapfile}. See the description of the -@samp{-M} option, above. - -@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-undefined -@item --no-undefined -Normally when creating a non-symbolic shared library, undefined symbols -are allowed and left to be resolved by the runtime loader. This option -disallows such undefined symbols. - -@kindex --no-warn-mismatch -@item --no-warn-mismatch -Normally @code{ld} will give an error if you try to link together input -files that are mismatched for some reason, perhaps because they have -been compiled for different processors or for different endiannesses. -This option tells @code{ld} that it should silently permit such possible -errors. This option should only be used with care, in cases when you -have taken some special action that ensures that the linker errors are -inappropriate. - -@kindex --no-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. - -On some platforms these link time global optimizations may make symbolic -debugging of the resulting executable impossible. -@ifset GENERIC -This is known to be -the case for the Matsushita MN10200 and MN10300 family of processors. -@end ifset - -@ifset GENERIC -On platforms where this is not supported, @samp{--relax} is accepted, -but ignored. -@end ifset - -@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-relocatable link, it will automatically try to locate the required -shared library and include it in the link, if it is not included -explicitly. In such a case, the @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}. -@item -For a native linker on an ELF system, if the file @file{/etc/ld.so.conf} -exists, the list of directories found in that file. -@end enumerate - -If the required shared library is not found, the linker will issue a -warning and continue with the link. -@end ifset - -@kindex -shared -@kindex -Bshareable -@item -shared -@itemx -Bshareable -@cindex shared libraries -Create a shared library. This is currently only supported on ELF, XCOFF -and SunOS platforms. On SunOS, the linker will automatically create a -shared library if the @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 --verbose -@cindex verbose -@item --dll-verbose -@itemx --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}. - -@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 - -@subsection Options specific to i386 PE targets - -The i386 PE linker supports the @code{-shared} option, which causes -the output to be a dynamically linked library (DLL) instead of a -normal executable. You should name the output @code{*.dll} when you -use this option. In addition, the linker fully supports the standard -@code{*.def} files, which may be specified on the linker command line -like an object file (in fact, it should precede archives it exports -symbols from, to ensure that they get linked in, just like a normal -object file). - -In addition to the options common to all targets, the i386 PE linker -support additional command line options that are specific to the i386 -PE target. Options that take values may be separated from their -values by either a space or an equals sign. - -@table @code - -@kindex --add-stdcall-alias -@item --add-stdcall-alias -If given, symbols with a stdcall suffix (@@@var{nn}) will be exported -as-is and also with the suffix stripped. - -@kindex --base-file -@item --base-file @var{file} -Use @var{file} as the name of a file in which to save the base -addresses of all the relocations needed for generating DLLs with -@file{dlltool}. - -@kindex --dll -@item --dll -Create a DLL instead of a regular executable. You may also use -@code{-shared} or specify a @code{LIBRARY} in a given @code{.def} -file. - -@kindex --enable-stdcall-fixup -@kindex --disable-stdcall-fixup -@item --enable-stdcall-fixup -@itemx --disable-stdcall-fixup -If the link finds a symbol that it cannot resolve, it will attempt to -do "fuzzy linking" by looking for another defined symbol that differs -only in the format of the symbol name (cdecl vs stdcall) and will -resolve that symbol by linking to the match. For example, the -undefined symbol @code{_foo} might be linked to the function -@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked -to the function @code{_bar}. When the linker does this, it prints a -warning, since it normally should have failed to link, but sometimes -import libraries generated from third-party dlls may need this feature -to be usable. If you specify @code{--enable-stdcall-fixup}, this -feature is fully enabled and warnings are not printed. If you specify -@code{--disable-stdcall-fixup}, this feature is disabled and such -mismatches are considered to be errors. - -@cindex DLLs, creating -@kindex --export-all-symbols -@item --export-all-symbols -If given, all global symbols in the objects used to build a DLL will -be exported by the DLL. Note that this is the default if there -otherwise wouldn't be any exported symbols. When symbols are -explicitly exported via DEF files or implicitly exported via function -attributes, the default is to not export anything else unless this -option is given. Note that the symbols @code{DllMain@@12}, -@code{DllEntryPoint@@0}, and @code{impure_ptr} will not be automatically -exported. - -@kindex --exclude-symbols -@item --exclude-symbols @var{symbol},@var{symbol},... -Specifies a list of symbols which should not be automatically -exported. The symbol names may be delimited by commas or colons. - -@kindex --file-alignment -@item --file-alignment -Specify the file alignment. Sections in the file will always begin at -file offsets which are multiples of this number. This defaults to -512. - -@cindex heap size -@kindex --heap -@item --heap @var{reserve} -@itemx --heap @var{reserve},@var{commit} -Specify the amount of memory to reserve (and optionally commit) to be -used as heap for this program. The default is 1Mb reserved, 4K -committed. - -@cindex image base -@kindex --image-base -@item --image-base @var{value} -Use @var{value} as the base address of your program or dll. This is -the lowest memory location that will be used when your program or dll -is loaded. To reduce the need to relocate and improve performance of -your dlls, each should have a unique base address and not overlap any -other dlls. The default is 0x400000 for executables, and 0x10000000 -for dlls. - -@kindex --kill-at -@item --kill-at -If given, the stdcall suffixes (@@@var{nn}) will be stripped from -symbols before they are exported. - -@kindex --major-image-version -@item --major-image-version @var{value} -Sets the major number of the "image version". Defaults to 1. - -@kindex --major-os-version -@item --major-os-version @var{value} -Sets the major number of the "os version". Defaults to 4. - -@kindex --major-subsystem-version -@item --major-subsystem-version @var{value} -Sets the major number of the "subsystem version". Defaults to 4. - -@kindex --minor-image-version -@item --minor-image-version @var{value} -Sets the minor number of the "image version". Defaults to 0. - -@kindex --minor-os-version -@item --minor-os-version @var{value} -Sets the minor number of the "os version". Defaults to 0. - -@kindex --minor-subsystem-version -@item --minor-subsystem-version @var{value} -Sets the minor number of the "subsystem version". Defaults to 0. - -@cindex DEF files, creating -@cindex DLLs, creating -@kindex --output-def -@item --output-def @var{file} -The linker will create the file @var{file} which will contain a DEF -file corresponding to the DLL the linker is generating. This DEF file -(which should be called @code{*.def}) may be used to create an import -library with @code{dlltool} or may be used as a reference to -automatically or implicitly exported symbols. - -@kindex --section-alignment -@item --section-alignment -Sets the section alignment. Sections in memory will always begin at -addresses which are a multiple of this number. Defaults to 0x1000. - -@cindex stack size -@kindex --stack -@item --stack @var{reserve} -@itemx --stack @var{reserve},@var{commit} -Specify the amount of memory to reserve (and optionally commit) to be -used as stack for this program. The default is 32Mb reserved, 4K -committed. - -@kindex --subsystem -@item --subsystem @var{which} -@itemx --subsystem @var{which}:@var{major} -@itemx --subsystem @var{which}:@var{major}.@var{minor} -Specifies the subsystem under which your program will execute. The -legal values for @var{which} are @code{native}, @code{windows}, -@code{console}, and @code{posix}. You may optionally set the -subsystem version also. - -@end table - -@ifset UsesEnvVars -@node Environment -@section Environment Variables - -You can change the behavior of @code{ld} with the environment variables -@code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}. - -@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. - -@kindex LDEMULATION -@cindex default emulation -@cindex emulation, default -@code{LDEMULATION} determines the default emulation if you don't use the -@samp{-m} option. The emulation can affect various aspects of linker -behaviour, particularly the default linker script. You can list the -available emulations with the @samp{--verbose} or @samp{-V} options. If -the @samp{-m} option is not used, and the @code{LDEMULATION} environment -variable is not defined, the default emulation depends upon how the -linker was configured. -@end ifset - -@kindex COLLECT_NO_DEMANGLE -@cindex demangling, default -Normally, the linker will default to demangling symbols. However, if -@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will -default to not demangling symbols. This environment variable is used in -a similar fashion by the @code{gcc} linker wrapper program. The default -may be overridden by the @samp{--demangle} and @samp{--no-demangle} -options. - -@node Scripts -@chapter Linker Scripts - -@cindex scripts -@cindex linker scripts -@cindex command files -Every link is controlled by a @dfn{linker script}. This script is -written in the linker command language. - -The main purpose of the linker script is to describe how the sections in -the input files should be mapped into the output file, and to control -the memory layout of the output file. Most linker scripts do nothing -more than this. However, when necessary, the linker script can also -direct the linker to perform many other operations, using the commands -described below. - -The linker always uses a linker script. If you do not supply one -yourself, the linker will use a default script that is compiled into the -linker executable. You can use the @samp{--verbose} command line option -to display the default linker script. Certain command line options, -such as @samp{-r} or @samp{-N}, will affect the default linker script. - -You may supply your own linker script by using the @samp{-T} command -line option. When you do this, your linker script will replace the -default linker script. - -You may also use linker scripts implicitly by naming them as input files -to the linker, as though they were files to be linked. @xref{Implicit -Linker Scripts}. - -@menu -* Basic Script Concepts:: Basic Linker Script Concepts -* Script Format:: Linker Script Format -* Simple Example:: Simple Linker Script Example -* Simple Commands:: Simple Linker Script Commands -* Assignments:: Assigning Values to Symbols -* SECTIONS:: SECTIONS Command -* MEMORY:: MEMORY Command -* PHDRS:: PHDRS Command -* VERSION:: VERSION Command -* Expressions:: Expressions in Linker Scripts -* Implicit Linker Scripts:: Implicit Linker Scripts -@end menu - -@node Basic Script Concepts -@section Basic Linker Script Concepts -@cindex linker script concepts -We need to define some basic concepts and vocabulary in order to -describe the linker script language. - -The linker combines input files into a single output file. The output -file and each input file are in a special data format known as an -@dfn{object file format}. Each file is called an @dfn{object file}. -The output file is often called an @dfn{executable}, but for our -purposes we will also call it an object file. Each object file has, -among other things, a list of @dfn{sections}. We sometimes refer to a -section in an input file as an @dfn{input section}; similarly, a section -in the output file is an @dfn{output section}. - -Each section in an object file has a name and a size. Most sections -also have an associated block of data, known as the @dfn{section -contents}. A section may be marked as @dfn{loadable}, which mean that -the contents should be loaded into memory when the output file is run. -A section with no contents may be @dfn{allocatable}, which means that an -area in memory should be set aside, but nothing in particular should be -loaded there (in some cases this memory must be zeroed out). A section -which is neither loadable nor allocatable typically contains some sort -of debugging information. - -Every loadable or allocatable output section has two addresses. The -first is the @dfn{VMA}, or virtual memory address. This is the address -the section will have when the output file is run. The second is the -@dfn{LMA}, or load memory address. This is the address at which the -section will be loaded. In most cases the two addresses will be the -same. An example of when they might be different is when a data section -is loaded into ROM, and then copied into RAM when the program starts up -(this technique is often used to initialize global variables in a ROM -based system). In this case the ROM address would be the LMA, and the -RAM address would be the VMA. - -You can see the sections in an object file by using the @code{objdump} -program with the @samp{-h} option. - -Every object file also has a list of @dfn{symbols}, known as the -@dfn{symbol table}. A symbol may be defined or undefined. Each symbol -has a name, and each defined symbol has an address, among other -information. If you compile a C or C++ program into an object file, you -will get a defined symbol for every defined function and global or -static variable. Every undefined function or global variable which is -referenced in the input file will become an undefined symbol. - -You can see the symbols in an object file by using the @code{nm} -program, or by using the @code{objdump} program with the @samp{-t} -option. - -@node Script Format -@section Linker Script Format -@cindex linker script format -Linker scripts are text files. - -You write a linker script as a series of commands. Each command is -either a keyword, possibly followed by arguments, or an assignment to a -symbol. You may separate commands using semicolons. Whitespace is -generally ignored. - -Strings such as file or format names can normally be entered directly. -If the file name contains a character such as a comma which would -otherwise serve to separate file names, you may put the file name in -double quotes. There is no way to use a double quote character in a -file name. - -You may include comments in linker scripts just as in C, delimited by -@samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent -to whitespace. - -@node Simple Example -@section Simple Linker Script Example -@cindex linker script example -@cindex example of linker script -Many linker scripts are fairly simple. - -The simplest possible linker script has just one command: -@samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the -memory layout of the output file. - -The @samp{SECTIONS} command is a powerful command. Here we will -describe a simple use of it. Let's assume your program consists only of -code, initialized data, and uninitialized data. These will be in the -@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively. -Let's assume further that these are the only sections which appear in -your input files. - -For this example, let's say that the code should be loaded at address -0x10000, and that the data should start at address 0x8000000. Here is a -linker script which will do that: -@smallexample -SECTIONS -@{ - . = 0x10000; - .text : @{ *(.text) @} - . = 0x8000000; - .data : @{ *(.data) @} - .bss : @{ *(.bss) @} -@} -@end smallexample - -You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS}, -followed by a series of symbol assignments and output section -descriptions enclosed in curly braces. - -The first line in the above example sets the special symbol @samp{.}, -which is the location counter. If you do not specify the address of an -output section in some other way (other ways are described later), the -address is set from the current value of the location counter. The -location counter is then incremented by the size of the output section. - -The first line inside the @samp{SECTIONS} command of the above example -sets the value of the special symbol @samp{.}, which is the location -counter. If you do not specify the address of an output section in some -other way (other ways are described later), the address is set from the -current value of the location counter. The location counter is then -incremented by the size of the output section. At the start of the -@samp{SECTIONS} command, the location counter has the value @samp{0}. - -The second line defines an output section, @samp{.text}. The colon is -required syntax which may be ignored for now. Within the curly braces -after the output section name, you list the names of the input sections -which should be placed into this output section. The @samp{*} is a -wildcard which matches any file name. The expression @samp{*(.text)} -means all @samp{.text} input sections in all input files. - -Since the location counter is @samp{0x10000} when the output section -@samp{.text} is defined, the linker will set the address of the -@samp{.text} section in the output file to be @samp{0x10000}. - -The remaining lines define the @samp{.data} and @samp{.bss} sections in -the output file. The linker will place the @samp{.data} output section -at address @samp{0x8000000}. After the linker places the @samp{.data} -output section, the value of the location counter will be -@samp{0x8000000} plus the size of the @samp{.data} output section. The -effect is that the linker will place the @samp{.bss} output section -immediately after the @samp{.data} output section in memory - -The linker will ensure that each output section has the required -alignment, by increasing the location counter if necessary. In this -example, the specified addresses for the @samp{.text} and @samp{.data} -sections will probably satisfy any alignment constraints, but the linker -may have to create a small gap between the @samp{.data} and @samp{.bss} -sections. - -That's it! That's a simple and complete linker script. - -@node Simple Commands -@section Simple Linker Script Commands -@cindex linker script simple commands -In this section we describe the simple linker script commands. - -@menu -* Entry Point:: Setting the entry point -* File Commands:: Commands dealing with files -@ifclear SingleFormat -* Format Commands:: Commands dealing with object file formats -@end ifclear - -* Miscellaneous Commands:: Other linker script commands -@end menu - -@node Entry Point -@subsection Setting the entry point -@kindex ENTRY(@var{symbol}) -@cindex start of execution -@cindex first instruction -@cindex entry point -The first instruction to execute in a program is called the @dfn{entry -point}. You can use the @code{ENTRY} linker script command to set the -entry point. The argument is a symbol name: -@smallexample -ENTRY(@var{symbol}) -@end smallexample - -There are several ways to set the entry point. The linker will set the -entry point by trying each of the following methods in order, and -stopping when one of them succeeds: -@itemize @bullet -@item -the @samp{-e} @var{entry} command-line option; -@item -the @code{ENTRY(@var{symbol})} command in a linker script; -@item -the value of the symbol @code{start}, if defined; -@item -the address of the first byte of the @samp{.text} section, if present; -@item -The address @code{0}. -@end itemize - -@node File Commands -@subsection Commands dealing with files -@cindex linker script file commands -Several linker script commands deal with files. - -@table @code -@item INCLUDE @var{filename} -@kindex INCLUDE @var{filename} -@cindex including a linker script -Include the linker script @var{filename} at this point. The file will -be searched for in the current directory, and in any directory specified -with the @code{-L} option. You can nest calls to @code{INCLUDE} up to -10 levels deep. - -@item INPUT(@var{file}, @var{file}, @dots{}) -@itemx INPUT(@var{file} @var{file} @dots{}) -@kindex INPUT(@var{files}) -@cindex input files in linker scripts -@cindex input object files in linker scripts -@cindex linker script input object files -The @code{INPUT} command directs the linker to include the named files -in the link, as though they were named on the command line. - -For example, if you always want to include @file{subr.o} any time you do -a link, but you can't be bothered to put it on every link command line, -then you can put @samp{INPUT (subr.o)} in your linker script. - -In fact, if you like, you can list all of your input files in the linker -script, and then invoke the linker with nothing but a @samp{-T} option. - -The linker will first try to open the file in the current directory. If -it is not found, the linker will search through the archive library -search path. See the description of @samp{-L} in @ref{Options,,Command -Line Options}. - -If you use @samp{INPUT (-l@var{file})}, @code{ld} will transform the -name to @code{lib@var{file}.a}, as with the command line argument -@samp{-l}. - -When you use the @code{INPUT} command in an implicit linker script, the -files will be included in the link at the point at which the linker -script file is included. This can affect archive searching. - -@item GROUP(@var{file}, @var{file}, @dots{}) -@itemx GROUP(@var{file} @var{file} @dots{}) -@kindex GROUP(@var{files}) -@cindex grouping input files -The @code{GROUP} command is like @code{INPUT}, except that the named -files should all be archives, and they are searched repeatedly until no -new undefined references are created. See the description of @samp{-(} -in @ref{Options,,Command Line Options}. - -@item OUTPUT(@var{filename}) -@kindex OUTPUT(@var{filename}) -@cindex output file name in linker scripot -The @code{OUTPUT} command names the output file. Using -@code{OUTPUT(@var{filename})} in the linker script is exactly like using -@samp{-o @var{filename}} on the command line (@pxref{Options,,Command -Line Options}). If both are used, the command line option takes -precedence. - -You can use the @code{OUTPUT} command to define a default name for the -output file other than the usual default of @file{a.out}. - -@item SEARCH_DIR(@var{path}) -@kindex SEARCH_DIR(@var{path}) -@cindex library search path in linker script -@cindex archive search path in linker script -@cindex search path in linker script -The @code{SEARCH_DIR} command adds @var{path} to the list of paths where -@code{ld} looks for archive libraries. Using -@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}} -on the command line (@pxref{Options,,Command Line Options}). If both -are used, then the linker will search both paths. Paths specified using -the command line option are searched first. - -@item STARTUP(@var{filename}) -@kindex STARTUP(@var{filename}) -@cindex first input file -The @code{STARTUP} command is just like the @code{INPUT} command, except -that @var{filename} will become the first input file to be linked, as -though it were specified first on the command line. This may be useful -when using a system in which the entry point is always the start of the -first file. -@end table - -@ifclear SingleFormat -@node Format Commands -@subsection Commands dealing with object file formats -A couple of linker script commands deal with object file formats. - -@table @code -@item OUTPUT_FORMAT(@var{bfdname}) -@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little}) -@kindex OUTPUT_FORMAT(@var{bfdname}) -@cindex output file format in linker script -The @code{OUTPUT_FORMAT} command names the BFD format to use for the -output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is -exactly like using @samp{-oformat @var{bfdname}} on the command line -(@pxref{Options,,Command Line Options}). If both are used, the command -line option takes precedence. - -You can use @code{OUTPUT_FORMAT} with three arguments to use different -formats based on the @samp{-EB} and @samp{-EL} command line options. -This permits the linker script to set the output format based on the -desired endianness. - -If neither @samp{-EB} nor @samp{-EL} are used, then the output format -will be the first argument, @var{default}. If @samp{-EB} is used, the -output format will be the second argument, @var{big}. If @samp{-EL} is -used, the output format will be the third argument, @var{little}. - -For example, the default linker script for the MIPS ELF target uses this -command: -@smallexample -OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) -@end smallexample -This says that the default format for the output file is -@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line -option, the output file will be created in the @samp{elf32-littlemips} -format. - -@item TARGET(@var{bfdname}) -@kindex TARGET(@var{bfdname}) -@cindex input file format in linker script -The @code{TARGET} command names the BFD format to use when reading input -files. It affects subsequent @code{INPUT} and @code{GROUP} commands. -This command is like using @samp{-b @var{bfdname}} on the command line -(@pxref{Options,,Command Line Options}). If the @code{TARGET} command -is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET} -command is also used to set the format for the output file. @xref{BFD}. -@end table -@end ifclear - -@node Miscellaneous Commands -@subsection Other linker script commands -There are a few other linker scripts commands. - -@table @code -@item ASSERT(@var{exp}, @var{message}) -@kindex ASSERT -@cindex assertion in linker script -Ensure that @var{exp} is non-zero. If it is zero, then exit the linker -with an error code, and print @var{message}. - -@item EXTERN(@var{symbol} @var{symbol} @dots{}) -@kindex EXTERN -@cindex undefined symbol in linker script -Force @var{symbol} to be entered in the output file as an undefined -symbol. Doing this may, for example, trigger linking of additional -modules from standard libraries. You may list several @var{symbol}s for -each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This -command has the same effect as the @samp{-u} command-line option. - -@item FORCE_COMMON_ALLOCATION -@kindex FORCE_COMMON_ALLOCATION -@cindex common allocation in linker script -This command has the same effect as the @samp{-d} command-line option: -to make @code{ld} assign space to common symbols even if a relocatable -output file is specified (@samp{-r}). - -@item NOCROSSREFS(@var{section} @var{section} @dots{}) -@kindex NOCROSSREFS(@var{sections}) -@cindex cross references -This command may be used to tell @code{ld} to issue an error about any -references among certain output sections. - -In certain types of programs, particularly on embedded systems when -using overlays, when one section is loaded into memory, another section -will not be. Any direct references between the two sections would be -errors. For example, it would be an error if code in one section called -a function defined in the other section. - -The @code{NOCROSSREFS} command takes a list of output section names. If -@code{ld} detects any cross references between the sections, it reports -an error and returns a non-zero exit status. Note that the -@code{NOCROSSREFS} command uses output section names, not input section -names. - -@ifclear SingleFormat -@item OUTPUT_ARCH(@var{bfdarch}) -@kindex OUTPUT_ARCH(@var{bfdarch}) -@cindex machine architecture -@cindex architecture -Specify a particular output machine architecture. The argument is one -of the names used by the BFD library (@pxref{BFD}). You can see the -architecture of an object file by using the @code{objdump} program with -the @samp{-f} option. -@end ifclear -@end table - -@node Assignments -@section Assigning Values to Symbols -@cindex assignment in scripts -@cindex symbol definition, scripts -@cindex variables, defining -You may assign a value to a symbol in a linker script. This will define -the symbol as a global symbol. - -@menu -* Simple Assignments:: Simple Assignments -* PROVIDE:: PROVIDE -@end menu - -@node Simple Assignments -@subsection Simple Assignments - -You may assign to a symbol using any of the C assignment operators: - -@table @code -@item @var{symbol} = @var{expression} ; -@itemx @var{symbol} += @var{expression} ; -@itemx @var{symbol} -= @var{expression} ; -@itemx @var{symbol} *= @var{expression} ; -@itemx @var{symbol} /= @var{expression} ; -@itemx @var{symbol} <<= @var{expression} ; -@itemx @var{symbol} >>= @var{expression} ; -@itemx @var{symbol} &= @var{expression} ; -@itemx @var{symbol} |= @var{expression} ; -@end table - -The first case will define @var{symbol} to the value of -@var{expression}. In the other cases, @var{symbol} must already be -defined, and the value will be adjusted accordingly. - -The special symbol name @samp{.} indicates the location counter. You -may only use this within a @code{SECTIONS} command. - -The semicolon after @var{expression} is required. - -Expressions are defined below; see @ref{Expressions}. - -You may write symbol assignments as commands in their own right, or as -statements within a @code{SECTIONS} command, or as part of an output -section description in a @code{SECTIONS} command. - -The section of the symbol will be set from the section of the -expression; for more information, see @ref{Expression Section}. - -Here is an example showing the three different places that symbol -assignments may be used: - -@smallexample -floating_point = 0; -SECTIONS -@{ - .text : - @{ - *(.text) - _etext = .; - @} - _bdata = (. + 3) & ~ 4; - .data : @{ *(.data) @} -@} -@end smallexample -@noindent -In this example, the symbol @samp{floating_point} will be defined as -zero. The symbol @samp{_etext} will be defined as the address following -the last @samp{.text} input section. The symbol @samp{_bdata} will be -defined as the address following the @samp{.text} output section aligned -upward to a 4 byte boundary. - -@node PROVIDE -@subsection PROVIDE -@cindex PROVIDE -In some cases, it is desirable for a linker script to define a symbol -only if it is referenced and is not defined by any object included in -the link. For example, traditional linkers defined the symbol -@samp{etext}. However, ANSI C requires that the user be able to use -@samp{etext} as a function name without encountering an error. The -@code{PROVIDE} keyword may be used to define a symbol, such as -@samp{etext}, only if it is referenced but not defined. The syntax is -@code{PROVIDE(@var{symbol} = @var{expression})}. - -Here is an example of using @code{PROVIDE} to define @samp{etext}: -@smallexample -SECTIONS -@{ - .text : - @{ - *(.text) - _etext = .; - PROVIDE(etext = .); - @} -@} -@end smallexample - -In this example, if the program defines @samp{_etext} (with a leading -underscore), the linker will give a multiple definition error. If, on -the other hand, the program defines @samp{etext} (with no leading -underscore), the linker will silently use the definition in the program. -If the program references @samp{etext} but does not define it, the -linker will use the definition in the linker script. - -@node SECTIONS -@section SECTIONS command -@kindex SECTIONS -The @code{SECTIONS} command tells the linker how to map input sections -into output sections, and how to place the output sections in memory. - -The format of the @code{SECTIONS} command is: -@smallexample -SECTIONS -@{ - @var{sections-command} - @var{sections-command} - @dots{} -@} -@end smallexample - -Each @var{sections-command} may of be one of the following: - -@itemize @bullet -@item -an @code{ENTRY} command (@pxref{Entry Point,,Entry command}) -@item -a symbol assignment (@pxref{Assignments}) -@item -an output section description -@item -an overlay description -@end itemize - -The @code{ENTRY} command and symbol assignments are permitted inside the -@code{SECTIONS} command for convenience in using the location counter in -those commands. This can also make the linker script easier to -understand because you can use those commands at meaningful points in -the layout of the output file. - -Output section descriptions and overlay descriptions are described -below. - -If you do not use a @code{SECTIONS} command in your linker script, the -linker will place each input section into an identically named output -section in the order that the sections are first encountered in the -input files. If all input sections are present in the first file, for -example, the order of sections in the output file will match the order -in the first input file. The first section will be at address zero. - -@menu -* Output Section Description:: Output section description -* Output Section Name:: Output section name -* Output Section Address:: Output section address -* Input Section:: Input section description -* Output Section Data:: Output section data -* Output Section Keywords:: Output section keywords -* Output Section Discarding:: Output section discarding -* Output Section Attributes:: Output section attributes -* Overlay Description:: Overlay description -@end menu - -@node Output Section Description -@subsection Output section description -The full description of an output section looks like this: -@smallexample -@group -@var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})] - @{ - @var{output-section-command} - @var{output-section-command} - @dots{} - @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] -@end group -@end smallexample - -Most output sections do not use most of the optional section attributes. - -The whitespace around @var{section} is required, so that the section -name is unambiguous. The colon and the curly braces are also required. -The line breaks and other white space are optional. - -Each @var{output-section-command} may be one of the following: - -@itemize @bullet -@item -a symbol assignment (@pxref{Assignments}) -@item -an input section description (@pxref{Input Section}) -@item -data values to include directly (@pxref{Output Section Data}) -@item -a special output section keyword (@pxref{Output Section Keywords}) -@end itemize - -@node Output Section Name -@subsection Output section name -@cindex name, section -@cindex section name -The name of the output section is @var{section}. @var{section} must -meet the constraints of your output format. In formats which only -support a limited number of sections, such as @code{a.out}, the name -must be one of the names supported by the format (@code{a.out}, for -example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the -output format supports any number of sections, but with numbers and not -names (as is the case for Oasys), the name should be supplied as a -quoted numeric string. A section name may consist of any sequence of -characters, but a name which contains any unusual characters such as -commas must be quoted. - -The output section name @samp{/DISCARD/} is special; @ref{Output Section -Discarding}. - -@node Output Section Address -@subsection Output section address -@cindex address, section -@cindex section address -The @var{address} is an expression for the VMA (the virtual memory -address) of the output section. If you do not provide @var{address}, -the linker will set it based on @var{region} if present, or otherwise -based on the current value of the location counter. - -If you provide @var{address}, the address of the output section will be -set to precisely that. If you provide neither @var{address} nor -@var{region}, then the address of the output section will be set to the -current value of the location counter aligned to the alignment -requirements of the output section. The alignment requirement of the -output section is the strictest alignment of any input section contained -within the output section. - -For example, -@smallexample -.text . : @{ *(.text) @} -@end smallexample -@noindent -and -@smallexample -.text : @{ *(.text) @} -@end smallexample -@noindent -are subtly different. The first will set the address of the -@samp{.text} output section to the current value of the location -counter. The second will set it to the current value of the location -counter aligned to the strictest alignment of a @samp{.text} input -section. - -The @var{address} may be an arbitrary expression; @ref{Expressions}. -For example, if you want to align the section on a 0x10 byte boundary, -so that the lowest four bits of the section address are zero, you could -do something like this: -@smallexample -.text ALIGN(0x10) : @{ *(.text) @} -@end smallexample -@noindent -This works because @code{ALIGN} returns the current location counter -aligned upward to the specified value. - -Specifying @var{address} for a section will change the value of the -location counter. - -@node Input Section -@subsection Input section description -@cindex input sections -@cindex mapping input sections to output sections -The most common output section command is an input section description. - -The input section description is the most basic linker script operation. -You use output sections to tell the linker how to lay out your program -in memory. You use input section descriptions to tell the linker how to -map the input files into your memory layout. - -@menu -* Input Section Basics:: Input section basics -* Input Section Wildcards:: Input section wildcard patterns -* Input Section Common:: Input section for common symbols -* Input Section Keep:: Input section and garbage collection -* Input Section Example:: Input section example -@end menu - -@node Input Section Basics -@subsubsection Input section basics -@cindex input section basics -An input section description consists of a file name optionally followed -by a list of section names in parentheses. - -The file name and the section name may be wildcard patterns, which we -describe further below (@pxref{Input Section Wildcards}). - -The most common input section description is to include all input -sections with a particular name in the output section. For example, to -include all input @samp{.text} sections, you would write: -@smallexample -*(.text) -@end smallexample -@noindent -Here the @samp{*} is a wildcard which matches any file name. To exclude a file -from matching the file name wildcard, EXCLUDE_FILE may be used to match all files -except the one specified by EXCLUDE_FILE. For example: -@smallexample -(*(EXCLUDE_FILE (*crtend.o) .ctors)) -@end smallexample -will cause all .ctors sections from all files except crtend.o to be included. - -There are two ways to include more than one section: -@smallexample -*(.text .rdata) -*(.text) *(.rdata) -@end smallexample -@noindent -The difference between these is the order in which the @samp{.text} and -@samp{.rdata} input sections will appear in the output section. In the -first example, they will be intermingled. In the second example, all -@samp{.text} input sections will appear first, followed by all -@samp{.rdata} input sections. - -You can specify a file name to include sections from a particular file. -You would do this if one or more of your files contain special data that -needs to be at a particular location in memory. For example: -@smallexample -data.o(.data) -@end smallexample - -If you use a file name without a list of sections, then all sections in -the input file will be included in the output section. This is not -commonly done, but it may by useful on occasion. For example: -@smallexample -data.o -@end smallexample - -When you use a file name which does not contain any wild card -characters, the linker will first see if you also specified the file -name on the linker command line or in an @code{INPUT} command. If you -did not, the linker will attempt to open the file as an input file, as -though it appeared on the command line. Note that this differs from an -@code{INPUT} command, because the linker will not search for the file in -the archive search path. - -@node Input Section Wildcards -@subsubsection Input section wildcard patterns -@cindex input section wildcards -@cindex wildcard file name patterns -@cindex file name wildcard patterns -@cindex section name wildcard patterns -In an input section description, either the file name or the section -name or both may be wildcard patterns. - -The file name of @samp{*} seen in many examples is a simple wildcard -pattern for the file name. - -The wildcard patterns are like those used by the Unix shell. - -@table @samp -@item * -matches any number of characters -@item ? -matches any single character -@item [@var{chars}] -matches a single instance of any of the @var{chars}; the @samp{-} -character may be used to specify a range of characters, as in -@samp{[a-z]} to match any lower case letter -@item \ -quotes the following character -@end table - -When a file name is matched with a wildcard, the wildcard characters -will not match a @samp{/} character (used to separate directory names on -Unix). A pattern consisting of a single @samp{*} character is an -exception; it will always match any file name, whether it contains a -@samp{/} or not. In a section name, the wildcard characters will match -a @samp{/} character. - -File name wildcard patterns only match files which are explicitly -specified on the command line or in an @code{INPUT} command. The linker -does not search directories to expand wildcards. - -If a file name matches more than one wildcard pattern, or if a file name -appears explicitly and is also matched by a wildcard pattern, the linker -will use the first match in the linker script. For example, this -sequence of input section descriptions is probably in error, because the -@file{data.o} rule will not be used: -@smallexample -.data : @{ *(.data) @} -.data1 : @{ data.o(.data) @} -@end smallexample - -@cindex SORT -Normally, the linker will place files and sections matched by wildcards -in the order in which they are seen during the link. You can change -this by using the @code{SORT} keyword, which appears before a wildcard -pattern in parentheses (e.g., @code{SORT(.text*)}). When the -@code{SORT} keyword is used, the linker will sort the files or sections -into ascending order by name before placing them in the output file. - -If you ever get confused about where input sections are going, use the -@samp{-M} linker option to generate a map file. The map file shows -precisely how input sections are mapped to output sections. - -This example shows how wildcard patterns might be used to partition -files. This linker script directs the linker to place all @samp{.text} -sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}. -The linker will place the @samp{.data} section from all files beginning -with an upper case character in @samp{.DATA}; for all other files, the -linker will place the @samp{.data} section in @samp{.data}. -@smallexample -@group -SECTIONS @{ - .text : @{ *(.text) @} - .DATA : @{ [A-Z]*(.data) @} - .data : @{ *(.data) @} - .bss : @{ *(.bss) @} -@} -@end group -@end smallexample - -@node Input Section Common -@subsubsection Input section for common symbols -@cindex common symbol placement -@cindex uninitialized data placement -A special notation is needed for common symbols, because in many object -file formats common symbols do not have a particular input section. The -linker treats common symbols as though they are in an input section -named @samp{COMMON}. - -You may use file names with the @samp{COMMON} section just as with any -other input sections. You can use this to place common symbols from a -particular input file in one section while common symbols from other -input files are placed in another section. - -In most cases, common symbols in input files will be placed in the -@samp{.bss} section in the output file. For example: -@smallexample -.bss @{ *(.bss) *(COMMON) @} -@end smallexample - -@cindex scommon section -@cindex small common symbols -Some object file formats have more than one type of common symbol. For -example, the MIPS ELF object file format distinguishes standard common -symbols and small common symbols. In this case, the linker will use a -different special section name for other types of common symbols. In -the case of MIPS ELF, the linker uses @samp{COMMON} for standard common -symbols and @samp{.scommon} for small common symbols. This permits you -to map the different types of common symbols into memory at different -locations. - -@cindex [COMMON] -You will sometimes see @samp{[COMMON]} in old linker scripts. This -notation is now considered obsolete. It is equivalent to -@samp{*(COMMON)}. - -@node Input Section Keep -@subsubsection Input section and garbage collection -@cindex KEEP -@cindex garbage collection -When link-time garbage collection is in use (@samp{--gc-sections}), -it is often useful to mark sections that should not be eliminated. -This is accomplished by surrounding an input section's wildcard entry -with @code{KEEP()}, as in @code{KEEP(*(.init))} or -@code{KEEP(SORT(*)(.ctors))}. - -@node Input Section Example -@subsubsection Input section example -The following example is a complete linker script. It tells the linker -to read all of the sections from file @file{all.o} and place them at the -start of output section @samp{outputa} which starts at location -@samp{0x10000}. All of section @samp{.input1} from file @file{foo.o} -follows immediately, in the same output section. All of section -@samp{.input2} from @file{foo.o} goes into output section -@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}. -All of the remaining @samp{.input1} and @samp{.input2} sections from any -files are written to output section @samp{outputc}. - -@smallexample -@group -SECTIONS @{ - outputa 0x10000 : - @{ - all.o - foo.o (.input1) - @} - outputb : - @{ - foo.o (.input2) - foo1.o (.input1) - @} - outputc : - @{ - *(.input1) - *(.input2) - @} -@} -@end group -@end smallexample - -@node Output Section Data -@subsection Output section data -@cindex data -@cindex section data -@cindex output section data -@kindex BYTE(@var{expression}) -@kindex SHORT(@var{expression}) -@kindex LONG(@var{expression}) -@kindex QUAD(@var{expression}) -@kindex SQUAD(@var{expression}) -You can include explicit bytes of data in an output section by using -@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as -an output section command. Each keyword is followed by an expression in -parentheses providing the value to store (@pxref{Expressions}). The -value of the expression is stored at the current value of the location -counter. - -The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands -store one, two, four, and eight bytes (respectively). After storing the -bytes, the location counter is incremented by the number of bytes -stored. - -For example, this will store the byte 1 followed by the four byte value -of the symbol @samp{addr}: -@smallexample -BYTE(1) -LONG(addr) -@end smallexample - -When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the -same; they both store an 8 byte, or 64 bit, value. When both host and -target are 32 bits, an expression is computed as 32 bits. In this case -@code{QUAD} stores a 32 bit value zero extended to 64 bits, and -@code{SQUAD} stores a 32 bit value sign extended to 64 bits. - -If the object file format of the output file has an explicit endianness, -which is the normal case, the value will be stored in that endianness. -When the object file format does not have an explicit endianness, as is -true of, for example, S-records, the value will be stored in the -endianness of the first input object file. - -@kindex FILL(@var{expression}) -@cindex holes, filling -@cindex unspecified memory -You may use the @code{FILL} command to set the fill pattern for the -current section. It is followed by an expression in parentheses. Any -otherwise unspecified regions of memory within the section (for example, -gaps left due to the required alignment of input sections) are filled -with the two least significant bytes of the expression, repeated as -necessary. A @code{FILL} statement covers memory locations after the -point at which it occurs in the section definition; by including more -than one @code{FILL} statement, you can have different fill patterns in -different parts of an output section. - -This example shows how to fill unspecified regions of memory with the -value @samp{0x9090}: -@smallexample -FILL(0x9090) -@end smallexample - -The @code{FILL} command is similar to the @samp{=@var{fillexp}} output -section attribute (@pxref{Output Section Fill}), but it only affects the -part of the section following the @code{FILL} command, rather than the -entire section. If both are used, the @code{FILL} command takes -precedence. - -@node Output Section Keywords -@subsection Output section keywords -There are a couple of keywords which can appear as output section -commands. - -@table @code -@kindex CREATE_OBJECT_SYMBOLS -@cindex input filename symbols -@cindex filename symbols -@item CREATE_OBJECT_SYMBOLS -The command tells the linker to create a symbol for each input file. -The name of each symbol will be the name of the corresponding input -file. The section of each symbol will be the output section in which -the @code{CREATE_OBJECT_SYMBOLS} command appears. - -This is conventional for the a.out object file format. It is not -normally used for any other object file format. - -@kindex CONSTRUCTORS -@cindex C++ constructors, arranging in link -@cindex constructors, arranging in link -@item CONSTRUCTORS -When linking using the a.out object file format, the linker uses an -unusual set construct to support C++ global constructors and -destructors. When linking object file formats which do not support -arbitrary sections, such as ECOFF and XCOFF, the linker will -automatically recognize C++ global constructors and destructors by name. -For these object file formats, the @code{CONSTRUCTORS} command tells the -linker to place constructor information in the output section where the -@code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is -ignored for other object file formats. - -The symbol @w{@code{__CTOR_LIST__}} marks the start of the global -constructors, and the symbol @w{@code{__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++ normally calls constructors from a subroutine -@code{__main}; a call to @code{__main} is automatically inserted into -the startup code for @code{main}. @sc{gnu} C++ normally runs -destructors either by using @code{atexit}, or directly from the function -@code{exit}. - -For object file formats such as @code{COFF} or @code{ELF} which support -arbitrary section names, @sc{gnu} C++ will normally arrange to put the -addresses of global constructors and destructors into the @code{.ctors} -and @code{.dtors} sections. Placing the following sequence into your -linker script will build the sort of table which the @sc{gnu} C++ -runtime code expects to see. - -@smallexample - __CTOR_LIST__ = .; - LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) - *(.ctors) - LONG(0) - __CTOR_END__ = .; - __DTOR_LIST__ = .; - LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) - *(.dtors) - LONG(0) - __DTOR_END__ = .; -@end smallexample - -If you are using the @sc{gnu} C++ support for initialization priority, -which provides some control over the order in which global constructors -are run, you must sort the constructors at link time to ensure that they -are executed in the correct order. When using the @code{CONSTRUCTORS} -command, use @samp{SORT(CONSTRUCTORS)} instead. When using the -@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and -@samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and -@samp{*(.dtors)}. - -Normally the compiler and linker will handle these issues automatically, -and you will not need to concern yourself with them. However, you may -need to consider this if you are using C++ and writing your own linker -scripts. - -@end table - -@node Output Section Discarding -@subsection Output section discarding -@cindex discarding sections -@cindex sections, discarding -@cindex removing sections -The linker will not create output section which do not have any -contents. This is for convenience when referring to input sections that -may or may not be present in any of the input files. For example: -@smallexample -.foo @{ *(.foo) @} -@end smallexample -@noindent -will only create a @samp{.foo} section in the output file if there is a -@samp{.foo} section in at least one input file. - -If you use anything other than an input section description as an output -section command, such as a symbol assignment, then the output section -will always be created, even if there are no matching input sections. - -@cindex /DISCARD/ -The special output section name @samp{/DISCARD/} may be used to discard -input sections. Any input sections which are assigned to an output -section named @samp{/DISCARD/} are not included in the output file. - -@node Output Section Attributes -@subsection Output section attributes -@cindex output section attributes -We showed above that the full description of an output section looked -like this: -@smallexample -@group -@var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})] - @{ - @var{output-section-command} - @var{output-section-command} - @dots{} - @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] -@end group -@end smallexample -We've already described @var{section}, @var{address}, and -@var{output-section-command}. In this section we will describe the -remaining section attributes. - -@menu -* Output Section Type:: Output section type -* Output Section LMA:: Output section LMA -* Output Section Region:: Output section region -* Output Section Phdr:: Output section phdr -* Output Section Fill:: Output section fill -@end menu - -@node Output Section Type -@subsubsection Output section type -Each output section may have a type. The type is a keyword in -parentheses. The following types are defined: - -@table @code -@item NOLOAD -The section should be marked as not loadable, so that it will not be -loaded into memory when the program is run. -@item DSECT -@itemx COPY -@itemx INFO -@itemx OVERLAY -These type names are supported for backward compatibility, and are -rarely used. They all have the same effect: the section should be -marked as not allocatable, so that no memory is allocated for the -section when the program is run. -@end table - -@kindex NOLOAD -@cindex prevent unnecessary loading -@cindex loading, preventing -The linker normally sets the attributes of an output section based on -the input sections which map into it. You can override this by using -the section type. For example, in the script sample below, the -@samp{ROM} section is addressed at memory location @samp{0} and does not -need to be loaded when the program is run. The contents of the -@samp{ROM} section will appear in the linker output file as usual. -@smallexample -@group -SECTIONS @{ - ROM 0 (NOLOAD) : @{ @dots{} @} - @dots{} -@} -@end group -@end smallexample - -@node Output Section LMA -@subsubsection Output section LMA -@kindex AT(@var{lma}) -@cindex load address -@cindex section load address -Every section has a virtual address (VMA) and a load address (LMA); see -@ref{Basic Script Concepts}. The address expression which may appear in -an output section description sets the VMA (@pxref{Output Section -Address}). - -The linker will normally set the LMA equal to the VMA. You can change -that by using the @code{AT} keyword. The expression @var{lma} that -follows the @code{AT} keyword specifies the load address of the section. - -@cindex ROM initialized data -@cindex initialized data in ROM -This feature is designed to make it easy to build a ROM image. For -example, the following linker script creates three output sections: one -called @samp{.text}, which starts at @code{0x1000}, one called -@samp{.mdata}, which is loaded at the end of the @samp{.text} section -even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold -uninitialized data at address @code{0x3000}. The symbol @code{_data} is -defined with the value @code{0x2000}, which shows that the location -counter holds the VMA value, not the LMA value. - -@smallexample -@group -SECTIONS - @{ - .text 0x1000 : @{ *(.text) _etext = . ; @} - .mdata 0x2000 : - AT ( ADDR (.text) + SIZEOF (.text) ) - @{ _data = . ; *(.data); _edata = . ; @} - .bss 0x3000 : - @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@} -@} -@end group -@end smallexample - -The run-time initialization code for use with a program generated with -this linker script would include something like the following, to copy -the initialized data from the ROM image to its runtime address. Notice -how this code takes advantage of the symbols defined by the linker -script. - -@smallexample -@group -extern char _etext, _data, _edata, _bstart, _bend; -char *src = &_etext; -char *dst = &_data; - -/* ROM has data at end of text; copy it. */ -while (dst < &_edata) @{ - *dst++ = *src++; -@} - -/* Zero bss */ -for (dst = &_bstart; dst< &_bend; dst++) - *dst = 0; -@end group -@end smallexample - -@node Output Section Region -@subsubsection Output section region -@kindex >@var{region} -@cindex section, assigning to memory region -@cindex memory regions and sections -You can assign a section to a previously defined region of memory by -using @samp{>@var{region}}. @xref{MEMORY}. - -Here is a simple example: -@smallexample -@group -MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @} -SECTIONS @{ ROM : @{ *(.text) @} >rom @} -@end group -@end smallexample - -@node Output Section Phdr -@subsubsection Output section phdr -@kindex :@var{phdr} -@cindex section, assigning to program header -@cindex program headers and sections -You can assign a section to a previously defined program segment by -using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to -one or more segments, then all subsequent allocated sections will be -assigned to those segments as well, unless they use an explicitly -@code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the -linker to not put the section in any segment at all. - -Here is a simple example: -@smallexample -@group -PHDRS @{ text PT_LOAD ; @} -SECTIONS @{ .text : @{ *(.text) @} :text @} -@end group -@end smallexample - -@node Output Section Fill -@subsubsection Output section fill -@kindex =@var{fillexp} -@cindex section fill pattern -@cindex fill pattern, entire section -You can set the fill pattern for an entire section by using -@samp{=@var{fillexp}}. @var{fillexp} is an expression -(@pxref{Expressions}). Any otherwise unspecified regions of memory -within the output section (for example, gaps left due to the required -alignment of input sections) will be filled with the two least -significant bytes of the value, repeated as necessary. - -You can also change the fill value with a @code{FILL} command in the -output section commands; see @ref{Output Section Data}. - -Here is a simple example: -@smallexample -@group -SECTIONS @{ .text : @{ *(.text) @} =0x9090 @} -@end group -@end smallexample - -@node Overlay Description -@subsection Overlay description -@kindex OVERLAY -@cindex overlays -An overlay description provides an easy way to describe sections which -are to be loaded as part of a single memory image but are to be run at -the same memory address. At run time, some sort of overlay manager will -copy the overlaid sections in and out of the runtime memory address as -required, perhaps by simply manipulating addressing bits. This approach -can be useful, for example, when a certain region of memory is faster -than another. - -Overlays are described using the @code{OVERLAY} command. The -@code{OVERLAY} command is used within a @code{SECTIONS} command, like an -output section description. The full syntax of the @code{OVERLAY} -command is as follows: -@smallexample -@group -OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )] - @{ - @var{secname1} - @{ - @var{output-section-command} - @var{output-section-command} - @dots{} - @} [:@var{phdr}@dots{}] [=@var{fill}] - @var{secname2} - @{ - @var{output-section-command} - @var{output-section-command} - @dots{} - @} [:@var{phdr}@dots{}] [=@var{fill}] - @dots{} - @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] -@end group -@end smallexample - -Everything is optional except @code{OVERLAY} (a keyword), and each -section must have a name (@var{secname1} and @var{secname2} above). The -section definitions within the @code{OVERLAY} construct are identical to -those within the general @code{SECTIONS} 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 the current value of the location counter). - -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{Miscellaneous 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 the location counter is set to -the start address of the overlay plus the size of the largest section. - -Here is an example. Remember that this would appear inside a -@code{SECTIONS} construct. -@smallexample -@group - OVERLAY 0x1000 : AT (0x4000) - @{ - .text0 @{ o1/*.o(.text) @} - .text1 @{ o2/*.o(.text) @} - @} -@end group -@end smallexample -@noindent -This will define both @samp{.text0} and @samp{.text1} to start at -address 0x1000. @samp{.text0} will be loaded at address 0x4000, and -@samp{.text1} will be loaded immediately after @samp{.text0}. The -following symbols will be defined: @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 MEMORY -@section MEMORY command -@kindex MEMORY -@cindex memory regions -@cindex regions of memory -@cindex allocating memory -@cindex discontinuous memory -The linker's default configuration permits allocation of all available -memory. You can override this by using the @code{MEMORY} command. - -The @code{MEMORY} command describes the location and size of blocks of -memory in the target. You can use it to describe which memory regions -may be used by the linker, and which memory regions it must avoid. You -can then assign sections to particular memory regions. The linker will -set section addresses based on the memory regions, and will warn about -regions that become too full. The linker will not shuffle sections -around to fit into the available regions. - -A linker script may contain 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 - -The @var{name} is a name used in the linker script to refer to the -region. The region name has no meaning outside of the linker script. -Region names are stored in a separate name space, and will not conflict -with symbol names, file names, or section names. Each memory region -must have a distinct name. - -@cindex memory region attributes -The @var{attr} string is an optional list of attributes that specify -whether to use a particular memory region for an input section which is -not explicitly mapped in the linker script. As described in -@ref{SECTIONS}, if you do not specify an output section for some input -section, the linker will create an output section with the same name as -the input section. If you define region attributes, the linker will use -them to select the memory region for the output section that it creates. - -The @var{attr} string must consist only of the following characters: -@table @samp -@item R -Read-only section -@item W -Read/write section -@item X -Executable section -@item A -Allocatable section -@item I -Initialized section -@item L -Same as @samp{I} -@item ! -Invert the sense of any of the preceding attributes -@end table - -If a unmapped section matches any of the listed attributes other than -@samp{!}, it will be placed in the memory region. The @samp{!} -attribute reverses this test, so that an unmapped section will be placed -in the memory region only if it does not match any of the listed -attributes. - -@kindex ORIGIN = -@kindex o = -@kindex org = -The @var{origin} is an expression for the start address of the memory -region. The expression must evaluate to a constant before memory -allocation is performed, which means that you may not use any section -relative symbols. The keyword @code{ORIGIN} may be abbreviated to -@code{org} or @code{o} (but not, for example, @code{ORG}). - -@kindex LENGTH = -@kindex len = -@kindex l = -The @var{len} is an expression for the size in bytes of the memory -region. As with the @var{origin} expression, the expression must -evaluate to a constant before memory allocation is performed. The -keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}. - -In the following example, we specify that there are two memory regions -available for allocation: one starting at @samp{0} for 256 kilobytes, -and the other starting at @samp{0x40000000} for four megabytes. The -linker will place into the @samp{rom} memory region every section which -is not explicitly mapped into a memory region, and is either read-only -or executable. The linker will place other sections which are not -explicitly mapped into a memory region into the @samp{ram} memory -region. - -@smallexample -@group -MEMORY - @{ - rom (rx) : ORIGIN = 0, LENGTH = 256K - ram (!rx) : org = 0x40000000, l = 4M - @} -@end group -@end smallexample - -Once you define a memory region, you can direct the linker to place -specific output sections into that memory region by using the -@samp{>@var{region}} output section attribute. For example, if you have -a memory region named @samp{mem}, you would use @samp{>mem} in the -output section definition. @xref{Output Section Region}. If no address -was specified for the output section, the linker will set the address to -the next available address within the memory region. If the combined -output sections directed to a memory region are too large for the -region, the linker will issue an error message. - -@node PHDRS -@section PHDRS Command -@kindex PHDRS -@cindex program headers -@cindex ELF program headers -@cindex program segments -@cindex segments, ELF -The ELF object file format uses @dfn{program headers}, also knows as -@dfn{segments}. The program headers describe how the program should be -loaded into memory. You can print them out by using the @code{objdump} -program with the @samp{-p} option. - -When you run an ELF program on a native ELF system, the system loader -reads the program headers in order to figure out how to load the -program. This will only work if the program headers are set correctly. -This manual does not describe the details of how the system loader -interprets program headers; for more information, see the ELF ABI. - -The linker will create reasonable program headers by default. However, -in some cases, you may need to specify the program headers more -precisely. You may use the @code{PHDRS} command for this purpose. When -the linker sees the @code{PHDRS} command in the linker script, it will -not create any program headers other than the ones specified. - -The linker only pays attention to the @code{PHDRS} command when -generating an ELF output file. In other cases, the linker will simply -ignore @code{PHDRS}. - -This is the syntax of the @code{PHDRS} command. The words @code{PHDRS}, -@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords. - -@smallexample -@group -PHDRS -@{ - @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ] - [ FLAGS ( @var{flags} ) ] ; -@} -@end group -@end smallexample - -The @var{name} is used only for reference in the @code{SECTIONS} command -of the linker script. It is not put into the output file. Program -header names are stored in a separate name space, and will not conflict -with symbol names, file names, or section names. Each program header -must have a distinct name. - -Certain program header types describe segments of memory which the -system loader will load from the file. In the linker script, you -specify the contents of these segments by placing allocatable output -sections in the segments. You use the @samp{:@var{phdr}} output section -attribute to place a section in a particular segment. @xref{Output -Section Phdr}. - -It is normal to put certain sections in more than one segment. This -merely implies that one segment of memory contains another. You may -repeat @samp{:@var{phdr}}, using it once for each segment which should -contain the section. - -If you place a section in one or more segments using @samp{:@var{phdr}}, -then the linker will place all subsequent allocatable sections which do -not specify @samp{:@var{phdr}} in the same segments. This is for -convenience, since generally a whole set of contiguous sections will be -placed in a single segment. You can use @code{:NONE} to override the -default segment and tell the linker to not put the section in any -segment at all. - -@kindex FILEHDR -@kindex PHDRS -You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after -the program header type to further describe the contents of the segment. -The @code{FILEHDR} keyword means that the segment should include the ELF -file header. The @code{PHDRS} keyword means that the segment should -include the ELF program headers themselves. - -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 - -You can specify that a segment should be loaded at a particular address -in memory by using an @code{AT} expression. This is identical to the -@code{AT} command used as an output section attribute (@pxref{Output -Section LMA}). The @code{AT} command for a program header overrides the -output section attribute. - -The linker will normally set the segment flags based on the sections -which comprise the segment. You may use the @code{FLAGS} keyword to -explicitly specify the segment flags. The value of @var{flags} must be -an integer. It is used to set the @code{p_flags} field of the program -header. - -Here is an example of @code{PHDRS}. This shows a typical set of program -headers used on a native ELF system. - -@example -@group -PHDRS -@{ - headers PT_PHDR PHDRS ; - interp PT_INTERP ; - text PT_LOAD FILEHDR PHDRS ; - data PT_LOAD ; - dynamic PT_DYNAMIC ; -@} - -SECTIONS -@{ - . = SIZEOF_HEADERS; - .interp : @{ *(.interp) @} :text :interp - .text : @{ *(.text) @} :text - .rodata : @{ *(.rodata) @} /* defaults to :text */ - @dots{} - . = . + 0x1000; /* move to a new page in memory */ - .data : @{ *(.data) @} :data - .dynamic : @{ *(.dynamic) @} :data :dynamic - @dots{} -@} -@end group -@end example - -@node VERSION -@section VERSION Command -@kindex VERSION @{script text@} -@cindex symbol versions -@cindex version script -@cindex versions of symbols -The linker supports symbol versions when using ELF. Symbol versions are -only useful when using shared libraries. The dynamic linker can use -symbol versions to select a specific version of a function when it runs -a program that may have been linked against an earlier version of the -shared library. - -You can include a version script directly in the main linker script, or -you can supply the version script as an implicit linker script. You can -also use the @samp{--version-script} linker option. - -The syntax of the @code{VERSION} command is simply -@smallexample -VERSION @{ version-script-commands @} -@end smallexample - -The format of the version script commands is identical to that used by -Sun's linker in Solaris 2.5. The version script defines a tree of -version nodes. You specify the node names and interdependencies in the -version script. You can specify which symbols are bound to which -version nodes, and you can reduce a specified set of symbols to local -scope so that they are not globally visible outside of the shared -library. - -The easiest way to demonstrate the version script language is with a few -examples. - -@smallexample -VERS_1.1 @{ - global: - foo1; - local: - old*; - original*; - new*; -@}; - -VERS_1.2 @{ - foo2; -@} VERS_1.1; - -VERS_2.0 @{ - bar1; bar2; -@} VERS_1.2; -@end smallexample - -This example version script defines three version nodes. The first -version node defined is @samp{VERS_1.1}; it has no other dependencies. -The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces -a number of symbols to local scope so that they are not visible outside -of the shared library. - -Next, the version script defines node @samp{VERS_1.2}. This node -depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2} -to the version node @samp{VERS_1.2}. - -Finally, the version script defines node @samp{VERS_2.0}. This node -depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1} -and @samp{bar2} are bound to the version node @samp{VERS_2.0}. - -When the linker finds a symbol defined in a library which is not -specifically bound to a version node, it will effectively bind it to an -unspecified base version of the library. You can bind all otherwise -unspecified symbols to a given version node by using @samp{global: *} -somewhere in the version script. - -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. You can do this by putting something like: -@smallexample -__asm__(".symver original_foo,foo@@VERS_1.1"); -@end smallexample -@noindent -in the C source file. This renames the function @samp{original_foo} to -be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}. -The @samp{local:} directive can be used to prevent the symbol -@samp{original_foo} from being exported. - -The second GNU extension is to allow multiple versions of the same -function to appear in a given shared library. In this way you can make -an incompatible change to an interface without increasing the major -version number of the shared library, while still allowing applications -linked against the old interface to continue to function. - -To do this, you must use multiple @samp{.symver} directives in the -source file. Here is an example: - -@smallexample -__asm__(".symver original_foo,foo@@"); -__asm__(".symver old_foo,foo@@VERS_1.1"); -__asm__(".symver old_foo1,foo@@VERS_1.2"); -__asm__(".symver new_foo,foo@@@@VERS_2.0"); -@end smallexample - -In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the -unspecified base version of the symbol. The source file that contains this -example would define 4 C functions: @samp{original_foo}, @samp{old_foo}, -@samp{old_foo1}, and @samp{new_foo}. - -When you have multiple definitions of a given symbol, there needs to be -some way to specify a default version to which external references to -this symbol will be bound. You can do this with the -@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only -declare one version of a symbol as the default in this manner; otherwise -you would effectively have multiple definitions of the same symbol. - -If you wish to bind a reference to a specific version of the symbol -within the shared library, you can use the aliases of convenience -(i.e. @samp{old_foo}), or you can use the @samp{.symver} directive to -specifically bind to an external version of the function in question. - -@node Expressions -@section Expressions in Linker Scripts -@cindex expressions -@cindex arithmetic -The syntax for expressions in the linker script language is identical to -that of C expressions. All expressions are evaluated as integers. All -expressions are evaluated in the same size, which is 32 bits if both the -host and target are 32 bits, and is otherwise 64 bits. - -You can use and set symbol values in expressions. - -The linker defines several special purpose builtin functions for use in -expressions. - -@menu -* Constants:: Constants -* Symbols:: Symbol Names -* Location Counter:: The Location Counter -* Operators:: Operators -* Evaluation:: Evaluation -* Expression Section:: The Section of an Expression -* Builtin Functions:: Builtin Functions -@end menu - -@node Constants -@subsection Constants -@cindex integer notation -@cindex constants in linker scripts -All constants are integers. - -As in C, the linker considers an integer beginning with @samp{0} to be -octal, and an integer beginning with @samp{0x} or @samp{0X} to be -hexadecimal. The linker considers other integers to be decimal. - -@cindex scaled integers -@cindex K and M integer suffixes -@cindex M and K integer suffixes -@cindex suffixes for integers -@cindex integer suffixes -In addition, you can use the suffixes @code{K} and @code{M} to scale a -constant by -@c TEXI2ROFF-KILL -@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 period -and may include letters, digits, underscores, periods, and hyphens. -Unquoted symbol names must not conflict with any keywords. You can -specify a symbol which contains odd characters or has the same name as a -keyword by surrounding the symbol name in double quotes: -@smallexample - "SECTION" = 9; - "with a space" = "also with a space" + 10; -@end smallexample - -Since symbols can contain many non-alphabetic characters, it is safest -to delimit symbols with spaces. For example, @samp{A-B} is one symbol, -whereas @samp{A - B} is an expression involving subtraction. - -@node Location Counter -@subsection The Location Counter -@kindex . -@cindex dot -@cindex location counter -@cindex current output location -The special linker variable @dfn{dot} @samp{.} always contains the -current output location counter. Since the @code{.} always refers to a -location in an output section, it may only appear in an expression -within a @code{SECTIONS} command. The @code{.} symbol may appear -anywhere that an ordinary symbol is allowed in an expression. - -@cindex holes -Assigning a value to @code{.} will cause the location counter to be -moved. This may be used to create holes in the output section. The -location counter may never be moved backwards. - -@smallexample -SECTIONS -@{ - output : - @{ - file1(.text) - . = . + 1000; - file2(.text) - . += 1000; - file3(.text) - @} = 0x1234; -@} -@end smallexample -@noindent -In the previous example, the @samp{.text} section from @file{file1} is -located at the beginning of the output section @samp{output}. It is -followed by a 1000 byte gap. Then the @samp{.text} section from -@file{file2} appears, also with a 1000 byte gap following before the -@samp{.text} section from @file{file3}. The notation @samp{= 0x1234} -specifies what data to write in the gaps (@pxref{Output Section Fill}). - -@cindex dot inside sections -Note: @code{.} actually refers to the byte offset from the start of the -current containing object. Normally this is the @code{SECTIONS} -statement, whoes start address is 0, hence @code{.} can be used as an -absolute address. If @code{.} is used inside a section description -however, it refers to the byte offset from the start of that section, -not an absolute address. Thus in a script like this: - -@smallexample -SECTIONS -@{ - . = 0x100 - .text: @{ - *(.text) - . = 0x200 - @} - . = 0x500 - .data: @{ - *(.data) - . += 0x600 - @} -@} -@end smallexample - -The @samp{.text} section will be assigned a starting address of 0x100 -and a size of exactly 0x200 bytes, even if there is not enough data in -the @samp{.text} input sections to fill this area. (If there is too -much data, an error will be produced because this would be an attempt to -move @code{.} backwards). The @samp{.data} section will start at 0x500 -and it will have an extra 0x600 bytes worth of space after the end of -the values from the @samp{.data} input sections and before the end of -the @samp{.data} output section itself. - -@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{Assignments}. -@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{Assignments}. -} -@end iftex -@c END TEXI2ROFF-KILL - -@node Evaluation -@subsection Evaluation -@cindex lazy evaluation -@cindex expression evaluation order -The linker evaluates expressions lazily. It only computes the value of -an expression when absolutely necessary. - -The linker needs some information, such as the value of the start -address of the first section, and the origins and lengths of memory -regions, in order to do any linking at all. These values are computed -as soon as possible when the linker reads in the linker script. - -However, other values (such as symbol values) are not known or needed -until after storage allocation. Such values are evaluated later, when -other information (such as the sizes of output sections) is available -for use in the symbol assignment expression. - -The sizes of sections cannot be known until after allocation, so -assignments dependent upon these are not performed until after -allocation. - -Some expressions, such as those depending upon the location counter -@samp{.}, must be evaluated during section allocation. - -If the result of an expression is required, but the value is not -available, then an error results. For example, a script like the -following -@smallexample -@group -SECTIONS - @{ - .text 9+this_isnt_constant : - @{ *(.text) @} - @} -@end group -@end smallexample -@noindent -will cause the error message @samp{non constant expression for initial -address}. - -@node Expression Section -@subsection The Section of an Expression -@cindex expression sections -@cindex absolute expressions -@cindex relative expressions -@cindex absolute and relocatable symbols -@cindex relocatable and absolute symbols -@cindex symbols, relocatable and absolute -When the linker evaluates an expression, the result is either absolute -or relative to some section. A relative expression is expressed as a -fixed offset from the base of a section. - -The position of the expression within the linker script determines -whether it is absolute or relative. An expression which appears within -an output section definition is relative to the base of the output -section. An expression which appears elsewhere will be absolute. - -A symbol set to a relative expression will be relocatable if you request -relocatable output using the @samp{-r} option. That means that a -further link operation may change the value of the symbol. The symbol's -section will be the section of the relative expression. - -A symbol set to an absolute expression will retain the same value -through any further link operation. The symbol will be absolute, and -will not have any particular associated section. - -You can use the builtin function @code{ABSOLUTE} to force an expression -to be absolute when it would otherwise be relative. For example, to -create an absolute symbol set to the address of the end of the output -section @samp{.data}: -@smallexample -SECTIONS - @{ - .data : @{ *(.data) _edata = ABSOLUTE(.); @} - @} -@end smallexample -@noindent -If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the -@samp{.data} section. - -@node Builtin Functions -@subsection Builtin Functions -@cindex functions in expressions -The linker script language includes a number of builtin functions for -use in linker script expressions. - -@table @code -@item ABSOLUTE(@var{exp}) -@kindex ABSOLUTE(@var{exp}) -@cindex expression, absolute -Return the absolute (non-relocatable, as opposed to non-negative) value -of the expression @var{exp}. Primarily useful to assign an absolute -value to a symbol within a section definition, where symbol values are -normally section relative. @xref{Expression Section}. - -@item ADDR(@var{section}) -@kindex ADDR(@var{section}) -@cindex section address in expression -Return the absolute address (the VMA) 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 - -@item ALIGN(@var{exp}) -@kindex ALIGN(@var{exp}) -@cindex round up location counter -@cindex align location counter -Return the 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. Here is an example which aligns the output -@code{.data} section to the next @code{0x2000} byte boundary after the -preceding section and sets a variable within the section to the next -@code{0x8000} boundary after the input sections: -@smallexample -@group -SECTIONS @{ @dots{} - .data ALIGN(0x2000): @{ - *(.data) - variable = ALIGN(0x8000); - @} -@dots{} @} -@end group -@end smallexample -@noindent -The first use of @code{ALIGN} in this example specifies the location of -a section because it is used as the optional @var{address} attribute of -a section definition (@pxref{Output Section Address}). The second use -of @code{ALIGN} is used to defines the value of a symbol. - -The builtin function @code{NEXT} is closely related to @code{ALIGN}. - -@item BLOCK(@var{exp}) -@kindex BLOCK(@var{exp}) -This is a synonym for @code{ALIGN}, for compatibility with older linker -scripts. It is most often seen when setting the address of an output -section. - -@item DEFINED(@var{symbol}) -@kindex DEFINED(@var{symbol}) -@cindex symbol defaults -Return 1 if @var{symbol} is in the linker global symbol table and is -defined, otherwise return 0. You can use this function to provide -default values for symbols. For example, the following script fragment -shows how to set a global symbol @samp{begin} to the first location in -the @samp{.text} section---but if a symbol called @samp{begin} already -existed, its value is preserved: - -@smallexample -@group -SECTIONS @{ @dots{} - .text : @{ - begin = DEFINED(begin) ? begin : . ; - @dots{} - @} - @dots{} -@} -@end group -@end smallexample - -@item LOADADDR(@var{section}) -@kindex LOADADDR(@var{section}) -@cindex section load address in expression -Return the absolute LMA of the named @var{section}. This is normally -the same as @code{ADDR}, but it may be different if the @code{AT} -attribute is used in the output section definition (@pxref{Output -Section LMA}). - -@kindex MAX -@item MAX(@var{exp1}, @var{exp2}) -Returns the maximum of @var{exp1} and @var{exp2}. - -@kindex MIN -@item MIN(@var{exp1}, @var{exp2}) -Returns the minimum of @var{exp1} and @var{exp2}. - -@item NEXT(@var{exp}) -@kindex NEXT(@var{exp}) -@cindex unallocated address, next -Return the next unallocated address that is a multiple of @var{exp}. -This function is closely related to @code{ALIGN(@var{exp})}; unless you -use the @code{MEMORY} command to define discontinuous memory for the -output file, the two functions are equivalent. - -@item SIZEOF(@var{section}) -@kindex SIZEOF(@var{section}) -@cindex section size -Return the size in bytes of the named @var{section}, if that section has -been allocated. If the section has not been allocated when this is -evaluated, the linker will report an error. In the following example, -@code{symbol_1} and @code{symbol_2} are assigned identical values: -@smallexample -@group -SECTIONS@{ @dots{} - .output @{ - .start = . ; - @dots{} - .end = . ; - @} - symbol_1 = .end - .start ; - symbol_2 = SIZEOF(.output); -@dots{} @} -@end group -@end smallexample - -@item SIZEOF_HEADERS -@itemx sizeof_headers -@kindex SIZEOF_HEADERS -@cindex header size -Return the size in bytes of the output file's headers. This is -information which appears at the start of the output file. You can use -this number when setting the start address of the first section, if you -choose, to facilitate paging. - -@cindex not enough room for program headers -@cindex program headers, not enough room -When producing an ELF output file, if the linker script uses the -@code{SIZEOF_HEADERS} builtin function, the linker must compute the -number of program headers before it has determined all the section -addresses and sizes. If the linker later discovers that it needs -additional program headers, it will report an error @samp{not enough -room for program headers}. To avoid this error, you must avoid using -the @code{SIZEOF_HEADERS} function, or you must rework your linker -script to avoid forcing the linker to use additional program headers, or -you must define the program headers yourself using the @code{PHDRS} -command (@pxref{PHDRS}). -@end table - -@node Implicit Linker Scripts -@section Implicit Linker Scripts -@cindex implicit linker scripts -If you specify a linker input file which the linker can not recognize as -an object file or an archive file, it will try to read the file as a -linker script. If the file can not be parsed as a linker script, the -linker will report an error. - -An implicit linker script will not replace the default linker script. - -Typically an implicit linker script would contain only symbol -assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION} -commands. - -Any input files read because of an implicit linker script will be read -at the position in the command line where the implicit linker script was -read. This can affect archive searching. - -@ifset GENERIC -@node Machine Dependent -@chapter Machine Dependent Features - -@cindex machine dependencies -@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 -* ARM:: @code{ld} and the ARM 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 GENERIC -@raisesections -@end ifclear - -@node ARM -@section @code{ld}'s support for interworking between ARM and Thumb code - -@cindex ARM interworking support -@kindex --support-old-code -For the ARM, @code{ld} will generate code stubs to allow functions calls -betweem ARM and Thumb code. These stubs only work with code that has -been compiled and assembled with the @samp{-mthumb-interwork} command -line option. If it is necessary to link with old ARM object files or -libraries, which have not been compiled with the -mthumb-interwork -option then the @samp{--support-old-code} command line switch should be -given to the linker. This will make it generate larger stub functions -which will work with non-interworking aware ARM code. Note, however, -the linker does not support generating stubs for function calls to -non-interworking aware Thumb code. - -@cindex thumb entry point -@cindex entry point, thumb -@kindex --thumb-entry=@var{entry} -The @samp{--thumb-entry} switch is a duplicate of the generic -@samp{--entry} switch, in that it sets the program's starting address. -But it also sets the bottom bit of the address, so that it can be -branched to using a BX instruction, and the program will start -executing in Thumb mode straight away. - -@ifclear GENERIC -@lowersections -@end ifclear - -@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. - -Otherwise, send bug reports for @code{ld} to -@samp{bug-gnu-utils@@gnu.org}. - -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{Scripts}. 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 - - |