diff options
Diffstat (limited to 'contrib/binutils/ld/ld.texinfo')
| -rw-r--r-- | contrib/binutils/ld/ld.texinfo | 3700 |
1 files changed, 0 insertions, 3700 deletions
diff --git a/contrib/binutils/ld/ld.texinfo b/contrib/binutils/ld/ld.texinfo deleted file mode 100644 index 05f3984ef86a..000000000000 --- a/contrib/binutils/ld/ld.texinfo +++ /dev/null @@ -1,3700 +0,0 @@ -\input texinfo -@setfilename ld.info -@syncodeindex ky cp -@include configdoc.texi -@c (configdoc.texi is generated by the Makefile) - -@c @smallbook - -@ifinfo -@format -START-INFO-DIR-ENTRY -* Ld: (ld). The GNU linker. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@ifinfo -This file documents the @sc{gnu} linker LD. - -Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -@end ifinfo -@iftex -@finalout -@setchapternewpage odd -@settitle Using LD, the GNU linker -@titlepage -@title Using ld -@subtitle The GNU linker -@sp 1 -@subtitle @code{ld} version 2 -@subtitle January 1994 -@author Steve Chamberlain -@author Cygnus Support -@page - -@tex -{\parskip=0pt -\hfill Cygnus Support\par -\hfill steve\@cygnus.com, doc\@cygnus.com\par -\hfill {\it Using LD, the GNU linker}\par -\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par -} -\global\parindent=0pt % Steve likes it this way. -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end titlepage -@end iftex -@c FIXME: Talk about importance of *order* of args, cmds to linker! - -@ifinfo -@node Top -@top Using ld -This file documents the @sc{gnu} linker ld. - -@menu -* Overview:: Overview -* Invocation:: Invocation -* Commands:: Command Language -@ifset GENERIC -* Machine Dependent:: Machine Dependent Features -@end ifset -@ifclear GENERIC -@ifset H8300 -* H8/300:: ld and the H8/300 -@end ifset -@ifset Hitachi -* Hitachi:: ld and other Hitachi micros -@end ifset -@ifset I960 -* i960:: ld and the Intel 960 family -@end ifset -@end ifclear -@ifclear SingleFormat -* BFD:: BFD -@end ifclear -@c Following blank line required for remaining bug in makeinfo conds/menus - -* Reporting Bugs:: Reporting Bugs -* MRI:: MRI Compatible Script Files -* Index:: Index -@end menu -@end ifinfo - -@node Overview -@chapter Overview - -@cindex @sc{gnu} linker -@cindex what is this? -@code{ld} combines a number of object and archive files, relocates -their data and ties up symbol references. Usually the last step in -compiling a program is to run @code{ld}. - -@code{ld} accepts Linker Command Language files written in -a superset of AT&T's Link Editor Command Language syntax, -to provide explicit and total control over the linking process. - -@ifclear SingleFormat -This version of @code{ld} uses the general purpose BFD libraries -to operate on object files. This allows @code{ld} to read, combine, and -write object files in many different formats---for example, COFF or -@code{a.out}. Different formats may be linked together to produce any -available kind of object file. @xref{BFD}, for more information. -@end ifclear - -Aside from its flexibility, the @sc{gnu} linker is more helpful than other -linkers in providing diagnostic information. Many linkers abandon -execution immediately upon encountering an error; whenever possible, -@code{ld} continues executing, allowing you to identify other errors -(or, in some cases, to get an output file in spite of the error). - -@node Invocation -@chapter Invocation - -The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations, -and to be as compatible as possible with other linkers. As a result, -you have many choices to control its behavior. - -@ifset UsesEnvVars -@menu -* Options:: Command Line Options -* Environment:: Environment Variables -@end menu - -@node Options -@section Command Line Options -@end ifset - -@cindex command line -@cindex options -The linker supports a plethora of command-line options, but in actual -practice few of them are used in any particular context. -@cindex standard Unix system -For instance, a frequent use of @code{ld} is to link standard Unix -object files on a standard, supported Unix system. On such a system, to -link a file @code{hello.o}: - -@smallexample -ld -o @var{output} /lib/crt0.o hello.o -lc -@end smallexample - -This tells @code{ld} to produce a file called @var{output} as the -result of linking the file @code{/lib/crt0.o} with @code{hello.o} and -the library @code{libc.a}, which will come from the standard search -directories. (See the discussion of the @samp{-l} option below.) - -The command-line options to @code{ld} may be specified in any order, and -may be repeated at will. Repeating most options with a different -argument will either have no further effect, or override prior -occurrences (those further to the left on the command line) of that -option. Options which may be meaningfully specified more than once are -noted in the descriptions below. - -@cindex object files -Non-option arguments are objects files which are to be linked together. -They may follow, precede, or be mixed in with command-line options, -except that an object file argument may not be placed between an option -and its argument. - -Usually the linker is invoked with at least one object file, but you can -specify other forms of binary input files using @samp{-l}, @samp{-R}, -and the script command language. If @emph{no} binary input files at all -are specified, the linker does not produce any output, and issues the -message @samp{No input files}. - -If the linker can not recognize the format of an object file, it will -assume that it is a linker script. A script specified in this way -augments the main linker script used for the link (either the default -linker script or the one specified by using @samp{-T}). This feature -permits the linker to link against a file which appears to be an object -or an archive, but actually merely defines some symbol values, or uses -@code{INPUT} or @code{GROUP} to load other objects. Note that -specifying a script in this way should only be used to augment the main -linker script; if you want to use some command that logically can only -appear once, such as the @code{SECTIONS} or @code{MEMORY} command, you -must replace the default linker script using the @samp{-T} option. -@xref{Commands}. - -For options whose names are a single letter, -option arguments must either follow the option letter without intervening -whitespace, or be given as separate arguments immediately following the -option that requires them. - -For options whose names are multiple letters, either one dash or two can -precede the option name; for example, @samp{--oformat} and -@samp{--oformat} are equivalent. Arguments to multiple-letter options -must either be separated from the option name by an equals sign, or be -given as separate arguments immediately following the option that -requires them. For example, @samp{--oformat srec} and -@samp{--oformat=srec} are equivalent. Unique abbreviations of the names -of multiple-letter options are accepted. - -@table @code -@kindex -a@var{keyword} -@item -a@var{keyword} -This option is supported for HP/UX compatibility. The @var{keyword} -argument must be one of the strings @samp{archive}, @samp{shared}, or -@samp{default}. @samp{-aarchive} is functionally equivalent to -@samp{-Bstatic}, and the other two keywords are functionally equivalent -to @samp{-Bdynamic}. This option may be used any number of times. - -@ifset I960 -@cindex architectures -@kindex -A@var{arch} -@item -A@var{architecture} -@kindex --architecture=@var{arch} -@itemx --architecture=@var{architecture} -In the current release of @code{ld}, this option is useful only for the -Intel 960 family of architectures. In that @code{ld} configuration, the -@var{architecture} argument identifies the particular architecture in -the 960 family, enabling some safeguards and modifying the -archive-library search path. @xref{i960,,@code{ld} and the Intel 960 -family}, for details. - -Future releases of @code{ld} may support similar functionality for -other architecture families. -@end ifset - -@ifclear SingleFormat -@cindex binary input format -@kindex -b @var{format} -@kindex --format=@var{format} -@cindex input format -@cindex input format -@item -b @var{input-format} -@itemx --format=@var{input-format} -@code{ld} may be configured to support more than one kind of object -file. If your @code{ld} is configured this way, you can use the -@samp{-b} option to specify the binary format for input object files -that follow this option on the command line. Even when @code{ld} is -configured to support alternative object formats, you don't usually need -to specify this, as @code{ld} should be configured to expect as a -default input format the most usual format on each machine. -@var{input-format} is a text string, the name of a particular format -supported by the BFD libraries. (You can list the available binary -formats with @samp{objdump -i}.) -@xref{BFD}. - -You may want to use this option if you are linking files with an unusual -binary format. You can also use @samp{-b} to switch formats explicitly (when -linking object files of different formats), by including -@samp{-b @var{input-format}} before each group of object files in a -particular format. - -The default format is taken from the environment variable -@code{GNUTARGET}. -@ifset UsesEnvVars -@xref{Environment}. -@end ifset -You can also define the input -format from a script, using the command @code{TARGET}; see @ref{Option -Commands}. -@end ifclear - -@kindex -c @var{MRI-cmdfile} -@kindex --mri-script=@var{MRI-cmdfile} -@cindex compatibility, MRI -@item -c @var{MRI-commandfile} -@itemx --mri-script=@var{MRI-commandfile} -For compatibility with linkers produced by MRI, @code{ld} accepts script -files written in an alternate, restricted command language, described in -@ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with -the option @samp{-c}; use the @samp{-T} option to run linker -scripts written in the general-purpose @code{ld} scripting language. -If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories -specified by any @samp{-L} options. - -@cindex common allocation -@kindex -d -@kindex -dc -@kindex -dp -@item -d -@itemx -dc -@itemx -dp -These three options are equivalent; multiple forms are supported for -compatibility with other linkers. They -assign space to common symbols even if a relocatable output file is -specified (with @samp{-r}). The script command -@code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Option -Commands}. - -@cindex entry point, from command line -@kindex -e @var{entry} -@kindex --entry=@var{entry} -@item -e @var{entry} -@itemx --entry=@var{entry} -Use @var{entry} as the explicit symbol for beginning execution of your -program, rather than the default entry point. @xref{Entry Point}, for a -discussion of defaults and other ways of specifying the -entry point. - -@cindex dynamic symbol table -@kindex -E -@kindex --export-dynamic -@item -E -@itemx --export-dynamic -When creating a dynamically linked executable, add all symbols to the -dynamic symbol table. 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. - -@kindex -f -@kindex --auxiliary -@item -f -@itemx --auxiliary @var{name} -When creating an ELF shared object, set the internal DT_AUXILIARY field -to the specified name. This tells the dynamic linker that the symbol -table of the shared object should be used as an auxiliary filter on the -symbol table of the shared object @var{name}. - -If you later link a program against this filter object, then, when you -run the program, the dynamic linker will see the DT_AUXILIARY field. If -the dynamic linker resolves any symbols from the filter object, it will -first check whether there is a definition in the shared object -@var{name}. If there is one, it will be used instead of the definition -in the filter object. The shared object @var{name} need not exist. -Thus the shared object @var{name} may be used to provide an alternative -implementation of certain functions, perhaps for debugging or for -machine specific performance. - -This option may be specified more than once. The DT_AUXILIARY entries -will be created in the order in which they appear on the command line. - -@kindex -F -@kindex --filter -@item -F @var{name} -@itemx --filter @var{name} -When creating an ELF shared object, set the internal DT_FILTER field to -the specified name. This tells the dynamic linker that the symbol table -of the shared object which is being created should be used as a filter -on the symbol table of the shared object @var{name}. - -If you later link a program against this filter object, then, when you -run the program, the dynamic linker will see the DT_FILTER field. The -dynamic linker will resolve symbols according to the symbol table of the -filter object as usual, but it will actually link to the definitions -found in the shared object @var{name}. Thus the filter object can be -used to select a subset of the symbols provided by the object -@var{name}. - -Some older linkers used the @code{-F} option throughout a compilation -toolchain for specifying object-file format for both input and output -object files. The @sc{gnu} linker uses other mechanisms for this -purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the -@code{TARGET} command in linker scripts, and the @code{GNUTARGET} -environment variable. The @sc{gnu} linker will ignore the @code{-F} -option when not creating an ELF shared object. - -@kindex --force-exe-suffix -@item --force-exe-suffix -Make sure that an output file has a .exe suffix. - -If a successfully built fully linked output file does not have a -@code{.exe} or @code{.dll} suffix, this option forces the linker to copy -the output file to one of the same name with a @code{.exe} suffix. This -option is useful when using unmodified Unix makefiles on a Microsoft -Windows host, since some versions of Windows won't run an image unless -it ends in a @code{.exe} suffix. - -@kindex -g -@item -g -Ignored. Provided for compatibility with other tools. - -@kindex -G -@kindex --gpsize -@cindex object size -@item -G@var{value} -@itemx --gpsize=@var{value} -Set the maximum size of objects to be optimized using the GP register to -@var{size}. This is only meaningful for object file formats such as -MIPS ECOFF which supports putting large and small objects into different -sections. This is ignored for other object file formats. - -@cindex runtime library name -@kindex -h@var{name} -@kindex -soname=@var{name} -@item -h@var{name} -@itemx -soname=@var{name} -When creating an ELF shared object, set the internal DT_SONAME field to -the specified name. When an executable is linked with a shared object -which has a DT_SONAME field, then when the executable is run the dynamic -linker will attempt to load the shared object specified by the DT_SONAME -field rather than the using the file name given to the linker. - -@kindex -i -@cindex incremental link -@item -i -Perform an incremental link (same as option @samp{-r}). - -@cindex archive files, from cmd line -@kindex -l@var{archive} -@kindex --library=@var{archive} -@item -l@var{archive} -@itemx --library=@var{archive} -Add archive file @var{archive} to the list of files to link. This -option may be used any number of times. @code{ld} will search its -path-list for occurrences of @code{lib@var{archive}.a} for every -@var{archive} specified. - -On systems which support shared libraries, @code{ld} may also search for -libraries with extensions other than @code{.a}. Specifically, on ELF -and SunOS systems, @code{ld} will search a directory for a library with -an extension of @code{.so} before searching for one with an extension of -@code{.a}. By convention, a @code{.so} extension indicates a shared -library. - -The linker will search an archive only once, at the location where it is -specified on the command line. If the archive defines a symbol which -was undefined in some object which appeared before the archive on the -command line, the linker will include the appropriate file(s) from the -archive. However, an undefined symbol in an object appearing later on -the command line will not cause the linker to search the archive again. - -See the @code{-(} option for a way to force the linker to search -archives multiple times. - -You may list the same archive multiple times on the command line. - -@ifset GENERIC -This type of archive searching is standard for Unix linkers. However, -if you are using @code{ld} on AIX, note that it is different from the -behaviour of the AIX linker. -@end ifset - -@cindex search directory, from cmd line -@kindex -L@var{dir} -@kindex --library-path=@var{dir} -@item -L@var{searchdir} -@itemx --library-path=@var{searchdir} -Add path @var{searchdir} to the list of paths that @code{ld} will search -for archive libraries and @code{ld} control scripts. You may use this -option any number of times. The directories are searched in the order -in which they are specified on the command line. Directories specified -on the command line are searched before the default directories. All -@code{-L} options apply to all @code{-l} options, regardless of the -order in which the options appear. - -@ifset UsesEnvVars -The default set of paths searched (without being specified with -@samp{-L}) depends on which emulation mode @code{ld} is using, and in -some cases also on how it was configured. @xref{Environment}. -@end ifset - -The paths can also be specified in a link script with the -@code{SEARCH_DIR} command. Directories specified this way are searched -at the point in which the linker script appears in the command line. - -@cindex emulation -@kindex -m @var{emulation} -@item -m@var{emulation} -Emulate the @var{emulation} linker. You can list the available -emulations with the @samp{--verbose} or @samp{-V} options. - -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. - -@cindex partial link -@cindex relocatable output -@kindex -r -@kindex --relocateable -@item -r -@itemx --relocateable -Generate relocatable output---i.e., generate an output file that can in -turn serve as input to @code{ld}. This is often called @dfn{partial -linking}. As a side effect, in environments that support standard Unix -magic numbers, this option also sets the output file's magic number to -@code{OMAGIC}. -@c ; see @code{-N}. -If this option is not specified, an absolute file is produced. When -linking C++ programs, this option @emph{will not} resolve references to -constructors; to do that, use @samp{-Ur}. - -This option does the same thing as @samp{-i}. - -@kindex -R @var{file} -@kindex --just-symbols=@var{file} -@cindex symbol-only input -@item -R @var{filename} -@itemx --just-symbols=@var{filename} -Read symbol names and their addresses from @var{filename}, but do not -relocate it or include it in the output. This allows your output file -to refer symbolically to absolute locations of memory defined in other -programs. You may use this option more than once. - -For compatibility with other ELF linkers, if the @code{-R} option is -followed by a directory name, rather than a file name, it is treated as -the @code{-rpath} option. - -@kindex -s -@kindex --strip-all -@cindex strip all symbols -@item -s -@itemx --strip-all -Omit all symbol information from the output file. - -@kindex -S -@kindex --strip-debug -@cindex strip debugger symbols -@item -S -@itemx --strip-debug -Omit debugger symbol information (but not all symbols) from the output file. - -@kindex -t -@kindex --trace -@cindex input files, displaying -@item -t -@itemx --trace -Print the names of the input files as @code{ld} processes them. - -@kindex -T @var{script} -@kindex --script=@var{script} -@cindex script files -@item -T @var{commandfile} -@itemx --script=@var{commandfile} -Read link commands from the file @var{commandfile}. These commands -replace @code{ld}'s default link script (rather than adding to it), so -@var{commandfile} must specify everything necessary to describe the -target format. You must use this option if you want to use a command -which can only appear once in a linker script, such as the -@code{SECTIONS} or @code{MEMORY} command. @xref{Commands}. If -@var{commandfile} does not exist, @code{ld} looks for it in the -directories specified by any preceding @samp{-L} options. Multiple -@samp{-T} options accumulate. - -@kindex -u @var{symbol} -@kindex --undefined=@var{symbol} -@cindex undefined symbol -@item -u @var{symbol} -@itemx --undefined=@var{symbol} -Force @var{symbol} to be entered in the output file as an undefined symbol. -Doing this may, for example, trigger linking of additional modules from -standard libraries. @samp{-u} may be repeated with different option -arguments to enter additional undefined symbols. -@c Nice idea, but no such command: This option is equivalent -@c to the @code{EXTERN} linker command. - -@kindex -v -@kindex -V -@kindex --version -@cindex version -@item -v -@itemx --version -@itemx -V -Display the version number for @code{ld}. The @code{-V} option also -lists the supported emulations. - -@kindex -x -@kindex --discard-all -@cindex deleting local symbols -@item -x -@itemx --discard-all -Delete all local symbols. - -@kindex -X -@kindex --discard-locals -@cindex local symbols, deleting -@cindex L, deleting symbols beginning -@item -X -@itemx --discard-locals -Delete all temporary local symbols. For most targets, this is all local -symbols whose names begin with @samp{L}. - -@kindex -y @var{symbol} -@kindex --trace-symbol=@var{symbol} -@cindex symbol tracing -@item -y @var{symbol} -@itemx --trace-symbol=@var{symbol} -Print the name of each linked file in which @var{symbol} appears. This -option may be given any number of times. On many systems it is necessary -to prepend an underscore. - -This option is useful when you have an undefined symbol in your link but -don't know where the reference is coming from. - -@kindex -Y @var{path} -@item -Y @var{path} -Add @var{path} to the default library search path. This option exists -for Solaris compatibility. - -@kindex -z @var{keyword} -@item -z @var{keyword} -This option is ignored for Solaris compatibility. - -@kindex -( -@cindex groups of archives -@item -( @var{archives} -) -@itemx --start-group @var{archives} --end-group -The @var{archives} should be a list of archive files. They may be -either explicit file names, or @samp{-l} options. - -The specified archives are searched repeatedly until no new undefined -references are created. Normally, an archive is searched only once in -the order that it is specified on the command line. If a symbol in that -archive is needed to resolve an undefined symbol referred to by an -object in an archive that appears later on the command line, the linker -would not be able to resolve that reference. By grouping the archives, -they all be searched repeatedly until all possible references are -resolved. - -Using this option has a significant performance cost. It is best to use -it only when there are unavoidable circular references between two or -more archives. - -@kindex -assert @var{keyword} -@item -assert @var{keyword} -This option is ignored for SunOS compatibility. - -@kindex -Bdynamic -@kindex -dy -@kindex -call_shared -@item -Bdynamic -@itemx -dy -@itemx -call_shared -Link against dynamic libraries. This is only meaningful on platforms -for which shared libraries are supported. This option is normally the -default on such platforms. The different variants of this option are -for compatibility with various systems. You may use this option -multiple times on the command line: it affects library searching for -@code{-l} options which follow it. - -@kindex -Bstatic -@kindex -dn -@kindex -non_shared -@kindex -static -@item -Bstatic -@itemx -dn -@itemx -non_shared -@itemx -static -Do not link against shared libraries. This is only meaningful on -platforms for which shared libraries are supported. The different -variants of this option are for compatibility with various systems. You -may use this option multiple times on the command line: it affects -library searching for @code{-l} options which follow it. - -@kindex -Bsymbolic -@item -Bsymbolic -When creating a shared library, bind references to global symbols to the -definition within the shared library, if any. Normally, it is possible -for a program linked against a shared library to override the definition -within the shared library. This option is only meaningful on ELF -platforms which support shared libraries. - -@cindex cross reference table -@kindex --cref -@item --cref -Output a cross reference table. If a linker map file is being -generated, the cross reference table is printed to the map file. -Otherwise, it is printed on the standard output. - -The format of the table is intentionally simple, so that it may be -easily processed by a script if necessary. The symbols are printed out, -sorted by name. For each symbol, a list of file names is given. If the -symbol is defined, the first file listed is the location of the -definition. The remaining files contain references to the symbol. - -@cindex symbols, from command line -@kindex --defsym @var{symbol}=@var{exp} -@item --defsym @var{symbol}=@var{expression} -Create a global symbol in the output file, containing the absolute -address given by @var{expression}. You may use this option as many -times as necessary to define multiple symbols in the command line. A -limited form of arithmetic is supported for the @var{expression} in this -context: you may give a hexadecimal constant or the name of an existing -symbol, or use @code{+} and @code{-} to add or subtract hexadecimal -constants or symbols. If you need more elaborate expressions, consider -using the linker command language from a script (@pxref{Assignment, , -Assignment: Symbol Definitions}). @emph{Note:} there should be no -white space between @var{symbol}, the equals sign (``@key{=}''), and -@var{expression}. - -@cindex dynamic linker, from command line -@kindex --dynamic-linker @var{file} -@item --dynamic-linker @var{file} -Set the name of the dynamic linker. This is only meaningful when -generating dynamically linked ELF executables. The default dynamic -linker is normally correct; don't use this unless you know what you are -doing. - -@cindex big-endian objects -@cindex endianness -@kindex -EB -@item -EB -Link big-endian objects. This affects the default output format. - -@cindex little-endian objects -@kindex -EL -@item -EL -Link little-endian objects. This affects the default output format. - -@cindex MIPS embedded PIC code -@kindex --embedded-relocs -@item --embedded-relocs -This option is only meaningful when linking MIPS embedded PIC code, -generated by the -membedded-pic option to the @sc{gnu} compiler and -assembler. It causes the linker to create a table which may be used at -runtime to relocate any data which was statically initialized to pointer -values. See the code in testsuite/ld-empic for details. - -@cindex help -@cindex usage -@kindex --help -@item --help -Print a summary of the command-line options on the standard output and exit. - -@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-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. - -@ifset GENERIC -On platforms where this is not supported, @samp{--relax} is accepted, -but ignored. -@end ifset - -@cindex retaining specified symbols -@cindex stripping all but some symbols -@cindex symbols, retaining selectively -@item --retain-symbols-file @var{filename} -Retain @emph{only} the symbols listed in the file @var{filename}, -discarding all others. @var{filename} is simply a flat file, with one -symbol name per line. This option is especially useful in environments -@ifset GENERIC -(such as VxWorks) -@end ifset -where a large global symbol table is accumulated gradually, to conserve -run-time memory. - -@samp{--retain-symbols-file} does @emph{not} discard undefined symbols, -or symbols needed for relocations. - -You may only specify @samp{--retain-symbols-file} once in the command -line. It overrides @samp{-s} and @samp{-S}. - -@ifset GENERIC -@item -rpath @var{dir} -@cindex runtime library search path -@kindex -rpath -Add a directory to the runtime library search path. This is used when -linking an ELF executable with shared objects. All @code{-rpath} -arguments are concatenated and passed to the runtime linker, which uses -them to locate shared objects at runtime. The @code{-rpath} option is -also used when locating shared objects which are needed by shared -objects explicitly included in the link; see the description of the -@code{-rpath-link} option. If @code{-rpath} is not used when linking an -ELF executable, the contents of the environment variable -@code{LD_RUN_PATH} will be used if it is defined. - -The @code{-rpath} option may also be used on SunOS. By default, on -SunOS, the linker will form a runtime search patch out of all the -@code{-L} options it is given. If a @code{-rpath} option is used, the -runtime search path will be formed exclusively using the @code{-rpath} -options, ignoring the @code{-L} options. This can be useful when using -gcc, which adds many @code{-L} options which may be on NFS mounted -filesystems. - -For compatibility with other ELF linkers, if the @code{-R} option is -followed by a directory name, rather than a file name, it is treated as -the @code{-rpath} option. -@end ifset - -@ifset GENERIC -@cindex link-time runtime library search path -@kindex -rpath-link -@item -rpath-link @var{DIR} -When using ELF or SunOS, one shared library may require another. This -happens when an @code{ld -shared} link includes a shared library as one -of the input files. - -When the linker encounters such a dependency when doing a non-shared, -non-relocateable link, it will automatically try to locate the required -shared library and include it in the link, if it is not included -explicitly. In such a case, the @code{-rpath-link} option -specifies the first set of directories to search. The -@code{-rpath-link} option may specify a sequence of directory names -either by specifying a list of names separated by colons, or by -appearing multiple times. - -The linker uses the following search paths to locate required shared -libraries. -@enumerate -@item -Any directories specified by @code{-rpath-link} options. -@item -Any directories specified by @code{-rpath} options. The difference -between @code{-rpath} and @code{-rpath-link} is that directories -specified by @code{-rpath} options are included in the executable and -used at runtime, whereas the @code{-rpath-link} option is only effective -at link time. -@item -On an ELF system, if the @code{-rpath} and @code{rpath-link} options -were not used, search the contents of the environment variable -@code{LD_RUN_PATH}. -@item -On SunOS, if the @code{-rpath} option was not used, search any -directories specified using @code{-L} options. -@item -For a native linker, the contents of the environment variable -@code{LD_LIBRARY_PATH}. -@item -The default directories, normally @file{/lib} and @file{/usr/lib}. -@end enumerate - -If the required shared library is not found, the linker will issue a -warning and continue with the link. -@end ifset - -@kindex -shared -@kindex -Bshareable -@item -shared -@itemx -Bshareable -@cindex shared libraries -Create a shared library. This is currently only supported on ELF, XCOFF -and SunOS platforms. On SunOS, the linker will automatically create a -shared library if the @code{-e} option is not used and there are -undefined symbols in the link. - -@item --sort-common -@kindex --sort-common -This option tells @code{ld} to sort the common symbols by size when it -places them in the appropriate output sections. First come all the one -byte symbols, then all the two bytes, then all the four bytes, and then -everything else. This is to prevent gaps between symbols due to -alignment constraints. - -@kindex --split-by-file -@item --split-by-file -Similar to @code{--split-by-reloc} but creates a new output section for -each input file. - -@kindex --split-by-reloc -@item --split-by-reloc @var{count} -Trys to creates extra sections in the output file so that no single -output section in the file contains more than @var{count} relocations. -This is useful when generating huge relocatable for downloading into -certain real time kernels with the COFF object file format; since COFF -cannot represent more than 65535 relocations in a single section. Note -that this will fail to work with object file formats which do not -support arbitrary sections. The linker will not split up individual -input sections for redistribution, so if a single input section contains -more than @var{count} relocations one output section will contain that -many relocations. - -@kindex --stats -@item --stats -Compute and display statistics about the operation of the linker, such -as execution time and memory usage. - -@kindex --traditional-format -@cindex traditional format -@item --traditional-format -For some targets, the output of @code{ld} is different in some ways from -the output of some existing linker. This switch requests @code{ld} to -use the traditional format instead. - -@cindex dbx -For example, on SunOS, @code{ld} combines duplicate entries in the -symbol string table. This can reduce the size of an output file with -full debugging information by over 30 percent. Unfortunately, the SunOS -@code{dbx} program can not read the resulting program (@code{gdb} has no -trouble). The @samp{--traditional-format} switch tells @code{ld} to not -combine duplicate entries. - -@kindex -Tbss @var{org} -@kindex -Tdata @var{org} -@kindex -Ttext @var{org} -@cindex segment origins, cmd line -@item -Tbss @var{org} -@itemx -Tdata @var{org} -@itemx -Ttext @var{org} -Use @var{org} as the starting address for---respectively---the -@code{bss}, @code{data}, or the @code{text} segment of the output file. -@var{org} must be a single hexadecimal integer; -for compatibility with other linkers, you may omit the leading -@samp{0x} usually associated with hexadecimal values. - -@kindex -Ur -@cindex constructors -@item -Ur -For anything other than C++ programs, this option is equivalent to -@samp{-r}: it generates relocatable output---i.e., an output file that can in -turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur} -@emph{does} resolve references to constructors, unlike @samp{-r}. -It does not work to use @samp{-Ur} on files that were themselves linked -with @samp{-Ur}; once the constructor table has been built, it cannot -be added to. Use @samp{-Ur} only for the last partial link, and -@samp{-r} for the others. - -@kindex --verbose -@cindex verbose -@item --verbose -Display the version number for @code{ld} and list the linker emulations -supported. Display which input files can and cannot be opened. Display -the linker script if using a default builtin script. - -@kindex --version-script=@var{version-scriptfile} -@cindex version script, symbol versions -@itemx --version-script=@var{version-scriptfile} -Specify the name of a version script to the linker. This is typically -used when creating shared libraries to specify additional information -about the version heirarchy for the library being created. This option -is only meaningful on ELF platforms which support shared libraries. -@xref{Version Script}. - -@kindex --warn-comon -@cindex warnings, on combining symbols -@cindex combining symbols, warnings on -@item --warn-common -Warn when a common symbol is combined with another common symbol or with -a symbol definition. Unix linkers allow this somewhat sloppy practice, -but linkers on some other operating systems do not. This option allows -you to find potential problems from combining global symbols. -Unfortunately, some C libraries use this practice, so you may get some -warnings about symbols in the libraries as well as in your programs. - -There are three kinds of global symbols, illustrated here by C examples: - -@table @samp -@item int i = 1; -A definition, which goes in the initialized data section of the output -file. - -@item extern int i; -An undefined reference, which does not allocate space. -There must be either a definition or a common symbol for the -variable somewhere. - -@item int i; -A common symbol. If there are only (one or more) common symbols for a -variable, it goes in the uninitialized data area of the output file. -The linker merges multiple common symbols for the same variable into a -single symbol. If they are of different sizes, it picks the largest -size. The linker turns a common symbol into a declaration, if there is -a definition of the same variable. -@end table - -The @samp{--warn-common} option can produce five kinds of warnings. -Each warning consists of a pair of lines: the first describes the symbol -just encountered, and the second describes the previous symbol -encountered with the same name. One or both of the two symbols will be -a common symbol. - -@enumerate -@item -Turning a common symbol into a reference, because there is already a -definition for the symbol. -@smallexample -@var{file}(@var{section}): warning: common of `@var{symbol}' - overridden by definition -@var{file}(@var{section}): warning: defined here -@end smallexample - -@item -Turning a common symbol into a reference, because a later definition for -the symbol is encountered. This is the same as the previous case, -except that the symbols are encountered in a different order. -@smallexample -@var{file}(@var{section}): warning: definition of `@var{symbol}' - overriding common -@var{file}(@var{section}): warning: common is here -@end smallexample - -@item -Merging a common symbol with a previous same-sized common symbol. -@smallexample -@var{file}(@var{section}): warning: multiple common - of `@var{symbol}' -@var{file}(@var{section}): warning: previous common is here -@end smallexample - -@item -Merging a common symbol with a previous larger common symbol. -@smallexample -@var{file}(@var{section}): warning: common of `@var{symbol}' - overridden by larger common -@var{file}(@var{section}): warning: larger common is here -@end smallexample - -@item -Merging a common symbol with a previous smaller common symbol. This is -the same as the previous case, except that the symbols are -encountered in a different order. -@smallexample -@var{file}(@var{section}): warning: common of `@var{symbol}' - overriding smaller common -@var{file}(@var{section}): warning: smaller common is here -@end smallexample -@end enumerate - -@kindex --warn-constructors -@item --warn-constructors -Warn if any global constructors are used. This is only useful for a few -object file formats. For formats like COFF or ELF, the linker can not -detect the use of global constructors. - -@kindex --warn-multiple-gp -@item --warn-multiple-gp -Warn if multiple global pointer values are required in the output file. -This is only meaningful for certain processors, such as the Alpha. -Specifically, some processors put large-valued constants in a special -section. A special register (the global pointer) points into the middle -of this section, so that constants can be loaded efficiently via a -base-register relative addressing mode. Since the offset in -base-register relative mode is fixed and relatively small (e.g., 16 -bits), this limits the maximum size of the constant pool. Thus, in -large programs, it is often necessary to use multiple global pointer -values in order to be able to address all possible constants. This -option causes a warning to be issued whenever this case occurs. - -@kindex --warn-once -@cindex warnings, on undefined symbols -@cindex undefined symbols, warnings on -@item --warn-once -Only warn once for each undefined symbol, rather than once per module -which refers to it. - -@kindex --warn-section-align -@cindex warnings, on section alignment -@cindex section alignment, warnings on -@item --warn-section-align -Warn if the address of an output section is changed because of -alignment. Typically, the alignment will be set by an input section. -The address will only be changed if it not explicitly specified; that -is, if the @code{SECTIONS} command does not specify a start address for -the section (@pxref{SECTIONS}). - -@kindex --whole-archive -@cindex including an entire archive -@item --whole-archive -For each archive mentioned on the command line after the -@code{--whole-archive} option, include every object file in the archive -in the link, rather than searching the archive for the required object -files. This is normally used to turn an archive file into a shared -library, forcing every object to be included in the resulting shared -library. This option may be used more than once. - -@kindex --wrap -@item --wrap @var{symbol} -Use a wrapper function for @var{symbol}. Any undefined reference to -@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any -undefined reference to @code{__real_@var{symbol}} will be resolved to -@var{symbol}. - -This can be used to provide a wrapper for a system function. The -wrapper function should be called @code{__wrap_@var{symbol}}. If it -wishes to call the system function, it should call -@code{__real_@var{symbol}}. - -Here is a trivial example: - -@smallexample -void * -__wrap_malloc (int c) -@{ - printf ("malloc called with %ld\n", c); - return __real_malloc (c); -@} -@end smallexample - -If you link other code with this file using @code{--wrap malloc}, then -all calls to @code{malloc} will call the function @code{__wrap_malloc} -instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will -call the real @code{malloc} function. - -You may wish to provide a @code{__real_malloc} function as well, so that -links without the @code{--wrap} option will succeed. If you do this, -you should not put the definition of @code{__real_malloc} in the same -file as @code{__wrap_malloc}; if you do, the assembler may resolve the -call before the linker has a chance to wrap it to @code{malloc}. - -@end table - -@ifset UsesEnvVars -@node Environment -@section Environment Variables - -You can change the behavior of @code{ld} with the environment variables -@code{GNUTARGET} and @code{LDEMULATION}. - -@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 - -@node Commands -@chapter Command Language - -@cindex command files -The command language provides explicit control over the link process, -allowing complete specification of the mapping between the linker's -input files and its output. It controls: -@itemize @bullet -@item -input files -@item -file formats -@item -output file layout -@item -addresses of sections -@item -placement of common blocks -@end itemize - -You may supply a command file (also known as a linker script) to the -linker either explicitly through the @samp{-T} option, or implicitly as -an ordinary file. Normally you should use the @samp{-T} option. An -implicit linker script should only be used when you want to augment, -rather than replace, the default linker script; typically an implicit -linker script would consist only of @code{INPUT} or @code{GROUP} -commands. - -If the linker opens a file which it cannot recognize as a supported -object or archive format, nor as a linker script, it reports an error. - -@menu -* Scripts:: Linker Scripts -* Expressions:: Expressions -* MEMORY:: MEMORY Command -* SECTIONS:: SECTIONS Command -* PHDRS:: PHDRS Command -* Entry Point:: The Entry Point -* Version Script:: Version Script -* Option Commands:: Option Commands -@end menu - -@node Scripts -@section Linker Scripts -The @code{ld} command language is a collection of statements; some are -simple keywords setting a particular option, some are used to select and -group input files or name output files; and two statement -types have a fundamental and pervasive impact on the linking process. - -@cindex fundamental script commands -@cindex commands, fundamental -@cindex output file layout -@cindex layout of output file -The most fundamental command of the @code{ld} command language is the -@code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command -script must have a @code{SECTIONS} command: it specifies a -``picture'' of the output file's layout, in varying degrees of detail. -No other command is required in all cases. - -The @code{MEMORY} command complements @code{SECTIONS} by describing the -available memory in the target architecture. This command is optional; -if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient -memory is available in a contiguous block for all output. -@xref{MEMORY}. - -@cindex comments -You may include comments in linker scripts just as in C: delimited -by @samp{/*} and @samp{*/}. As in C, comments are syntactically -equivalent to whitespace. - -@node Expressions -@section Expressions -@cindex expression syntax -@cindex arithmetic -Many useful commands involve arithmetic expressions. The syntax for -expressions in the command language is identical to that of C -expressions, with the following features: -@itemize @bullet -@item -All expressions evaluated as integers and -are of ``long'' or ``unsigned long'' type. -@item -All constants are integers. -@item -All of the C arithmetic operators are provided. -@item -You may reference, define, and create global variables. -@item -You may call special purpose built-in functions. -@end itemize - -@menu -* Integers:: Integers -* Symbols:: Symbol Names -* Location Counter:: The Location Counter -* Operators:: Operators -* Evaluation:: Evaluation -* Assignment:: Assignment: Defining Symbols -* Arithmetic Functions:: Built-In Functions -* Semicolons:: Semicolon Usage -@end menu - -@node Integers -@subsection Integers -@cindex integer notation -@cindex octal integers -An octal integer is @samp{0} followed by zero or more of the octal -digits (@samp{01234567}). -@smallexample -_as_octal = 0157255; -@end smallexample - -@cindex decimal integers -A decimal integer starts with a non-zero digit followed by zero or -more digits (@samp{0123456789}). -@smallexample -_as_decimal = 57005; -@end smallexample - -@cindex hexadecimal integers -@kindex 0x -A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or -more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. -@smallexample -_as_hex = 0xdead; -@end smallexample - -@cindex negative integers -To write a negative integer, use -the prefix operator @samp{-} (@pxref{Operators}). -@smallexample -_as_neg = -57005; -@end smallexample - -@cindex scaled integers -@cindex K and M integer suffixes -@cindex M and K integer suffixes -@cindex suffixes for integers -@cindex integer suffixes -Additionally the suffixes @code{K} and @code{M} may be used to scale a -constant by -@c TEXI2ROFF-KILL -@ifinfo -@c END TEXI2ROFF-KILL -@code{1024} or @code{1024*1024} -@c TEXI2ROFF-KILL -@end ifinfo -@tex -${\rm 1024}$ or ${\rm 1024}^2$ -@end tex -@c END TEXI2ROFF-KILL -respectively. For example, the following all refer to the same quantity: - -@smallexample - _fourk_1 = 4K; - _fourk_2 = 4096; - _fourk_3 = 0x1000; -@end smallexample - -@node Symbols -@subsection Symbol Names -@cindex symbol names -@cindex names -@cindex quoted symbol names -@kindex " -Unless quoted, symbol names start with a letter, underscore, or point -and may include any letters, underscores, digits, points, -and hyphens. Unquoted symbol names must not conflict with any -keywords. You can specify a symbol which contains odd characters or has -the same name as a keyword, by surrounding the symbol name in double quotes: -@smallexample - "SECTION" = 9; - "with a space" = "also with a space" + 10; -@end smallexample - -Since symbols can contain many non-alphabetic characters, it is safest -to delimit symbols with spaces. For example, @samp{A-B} is one symbol, -whereas @samp{A - B} is an expression involving subtraction. - -@node Location Counter -@subsection The Location Counter -@kindex . -@cindex dot -@cindex location counter -@cindex current output location -The special linker variable @dfn{dot} @samp{.} always contains the -current output location counter. Since the @code{.} always refers to -a location in an output section, it must always appear in an -expression within a @code{SECTIONS} command. The @code{.} symbol -may appear anywhere that an ordinary symbol is allowed in an -expression, but its assignments have a side effect. Assigning a value -to the @code{.} symbol will cause the location counter to be moved. -@cindex holes -This may be used to create holes in the output section. The location -counter may never be moved backwards. -@smallexample -SECTIONS -@{ - output : - @{ - file1(.text) - . = . + 1000; - file2(.text) - . += 1000; - file3(.text) - @} = 0x1234; -@} -@end smallexample -@noindent -In the previous example, @code{file1} is located at the beginning of the -output section, then there is a 1000 byte gap. Then @code{file2} -appears, also with a 1000 byte gap following before @code{file3} is -loaded. The notation @samp{= 0x1234} specifies what data to write in -the gaps (@pxref{Section Options}). - -@iftex -@vfill -@end iftex - -@need 2000 -@node Operators -@subsection Operators -@cindex Operators for arithmetic -@cindex arithmetic operators -@cindex precedence in expressions -The linker recognizes the standard C set of arithmetic operators, with -the standard bindings and precedence levels: -@c TEXI2ROFF-KILL -@ifinfo -@c END TEXI2ROFF-KILL -@smallexample -precedence associativity Operators Notes -(highest) -1 left ! - ~ (1) -2 left * / % -3 left + - -4 left >> << -5 left == != > < <= >= -6 left & -7 left | -8 left && -9 left || -10 right ? : -11 right &= += -= *= /= (2) -(lowest) -@end smallexample -Notes: -(1) Prefix operators -(2) @xref{Assignment}. -@c TEXI2ROFF-KILL -@end ifinfo -@tex -\vskip \baselineskip -%"lispnarrowing" is the extra indent used generally for smallexample -\hskip\lispnarrowing\vbox{\offinterlineskip -\hrule -\halign -{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr -height2pt&\omit&&\omit&&\omit&\cr -&Precedence&& Associativity &&{\rm Operators}&\cr -height2pt&\omit&&\omit&&\omit&\cr -\noalign{\hrule} -height2pt&\omit&&\omit&&\omit&\cr -&highest&&&&&\cr -% '176 is tilde, '~' in tt font -&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr -&2&&left&&* / \%&\cr -&3&&left&&+ -&\cr -&4&&left&&>> <<&\cr -&5&&left&&== != > < <= >=&\cr -&6&&left&&\&&\cr -&7&&left&&|&\cr -&8&&left&&{\&\&}&\cr -&9&&left&&||&\cr -&10&&right&&? :&\cr -&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr -&lowest&&&&&\cr -height2pt&\omit&&\omit&&\omit&\cr} -\hrule} -@end tex -@iftex -{ -@obeylines@parskip=0pt@parindent=0pt -@dag@quad Prefix operators. -@ddag@quad @xref{Assignment}. -} -@end iftex -@c END TEXI2ROFF-KILL - -@node Evaluation -@subsection Evaluation - -@cindex lazy evaluation -@cindex expression evaluation order -The linker uses ``lazy evaluation'' for expressions; it only calculates -an expression when absolutely necessary. The linker needs the value of -the start address, and the lengths of memory regions, in order to do any -linking at all; these values are computed as soon as possible when the -linker reads in the command file. However, other values (such as symbol -values) are not known or needed until after storage allocation. Such -values are evaluated later, when other information (such as the sizes of -output sections) is available for use in the symbol assignment -expression. - -@node Assignment -@subsection Assignment: Defining Symbols -@cindex assignment in scripts -@cindex symbol definition, scripts -@cindex variables, defining -You may create global symbols, and assign values (addresses) to global -symbols, using any of the C assignment operators: - -@table @code -@item @var{symbol} = @var{expression} ; -@itemx @var{symbol} &= @var{expression} ; -@itemx @var{symbol} += @var{expression} ; -@itemx @var{symbol} -= @var{expression} ; -@itemx @var{symbol} *= @var{expression} ; -@itemx @var{symbol} /= @var{expression} ; -@end table - -Two things distinguish assignment from other operators in @code{ld} -expressions. -@itemize @bullet -@item -Assignment may only be used at the root of an expression; -@samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error. - -@kindex ; -@cindex semicolon -@item -You must place a trailing semicolon (``@key{;}'') at the end of an -assignment statement. -@end itemize - -Assignment statements may appear: -@itemize @bullet -@item -as commands in their own right in an @code{ld} script; or -@item -as independent statements within a @code{SECTIONS} command; or -@item -as part of the contents of a section definition in a -@code{SECTIONS} command. -@end itemize - -The first two cases are equivalent in effect---both define a symbol with -an absolute address. The last case defines a symbol whose address is -relative to a particular section (@pxref{SECTIONS}). - -@cindex absolute and relocatable symbols -@cindex relocatable and absolute symbols -@cindex symbols, relocatable and absolute -When a linker expression is evaluated and assigned to a variable, it is -given either an absolute or a relocatable type. An absolute expression -type is one in which the symbol contains the value that it will have in -the output file; a relocatable expression type is one in which the -value is expressed as a fixed offset from the base of a section. - -The type of the expression is controlled by its position in the script -file. A symbol assigned within a section definition is created relative -to the base of the section; a symbol assigned in any other place is -created as an absolute symbol. Since a symbol created within a -section definition is relative to the base of the section, it -will remain relocatable if relocatable output is requested. A symbol -may be created with an absolute value even when assigned to within a -section definition by using the absolute assignment function -@code{ABSOLUTE}. For example, to create an absolute symbol whose address -is the last byte of an output section named @code{.data}: -@smallexample -SECTIONS@{ @dots{} - .data : - @{ - *(.data) - _edata = ABSOLUTE(.) ; - @} -@dots{} @} -@end smallexample - -The linker tries to put off the evaluation of an assignment until all -the terms in the source expression are known (@pxref{Evaluation}). For -instance, the sizes of sections cannot be known until after allocation, -so assignments dependent upon these are not performed until after -allocation. Some expressions, such as those depending upon the location -counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the -result of an expression is required, but the value is not available, -then an error results. For example, a script like the following -@smallexample -SECTIONS @{ @dots{} - text 9+this_isnt_constant : - @{ @dots{} - @} -@dots{} @} -@end smallexample -@kindex Non constant expression -@noindent -will cause the error message ``@code{Non constant expression for initial -address}''. - -@cindex provide -In some cases, it is desirable for a linker script to define a symbol -only if it is referenced, and only if it is not defined by any object -included in the link. For example, traditional linkers defined the -symbol @samp{etext}. However, ANSI C requires that the user be able to -use @samp{etext} as a function name without encountering an error. -The @code{PROVIDE} keyword may be used to define a symbol, such as -@samp{etext}, only if it is referenced but not defined. The syntax is -@code{PROVIDE(@var{symbol} = @var{expression})}. - -@node Arithmetic Functions -@subsection Arithmetic Functions -@cindex functions in expression language -The command language includes a number of built-in -functions for use in link script expressions. -@table @code -@kindex ABSOLUTE(@var{exp}) -@cindex expression, absolute -@item ABSOLUTE(@var{exp}) -Return the absolute (non-relocatable, as opposed to non-negative) value -of the expression @var{exp}. Primarily useful to assign an absolute -value to a symbol within a section definition, where symbol values are -normally section-relative. - -@kindex ADDR(@var{section}) -@cindex section address -@item ADDR(@var{section}) -Return the absolute address of the named @var{section}. Your script must -previously have defined the location of that section. In the following -example, @code{symbol_1} and @code{symbol_2} are assigned identical -values: -@smallexample -@group -SECTIONS@{ @dots{} - .output1 : - @{ - start_of_output_1 = ABSOLUTE(.); - @dots{} - @} - .output : - @{ - symbol_1 = ADDR(.output1); - symbol_2 = start_of_output_1; - @} -@dots{} @} -@end group -@end smallexample - -@kindex LOADADDR(@var{section}) -@cindex section load address -@item LOADADDR(@var{section}) -Return the absolute load address of the named @var{section}. This is -normally the same as @code{ADDR}, but it may be different if the -@code{AT} keyword is used in the section definition (@pxref{Section -Options}). - -@kindex ALIGN(@var{exp}) -@cindex rounding up location counter -@item ALIGN(@var{exp}) -Return the result of the current location counter (@code{.}) aligned to -the next @var{exp} boundary. @var{exp} must be an expression whose -value is a power of two. This is equivalent to -@smallexample -(. + @var{exp} - 1) & ~(@var{exp} - 1) -@end smallexample - -@code{ALIGN} doesn't change the value of the location counter---it just -does arithmetic on it. As an example, to align the output @code{.data} -section to the next @code{0x2000} byte boundary after the preceding -section and to set a variable within the section to the next -@code{0x8000} boundary after the input sections: -@smallexample -@group -SECTIONS@{ @dots{} - .data ALIGN(0x2000): @{ - *(.data) - variable = ALIGN(0x8000); - @} -@dots{} @} -@end group -@end smallexample -@noindent -The first use of @code{ALIGN} in this example specifies the location of -a section because it is used as the optional @var{start} attribute of a -section definition (@pxref{Section Options}). The second use simply -defines the value of a variable. - -The built-in @code{NEXT} is closely related to @code{ALIGN}. - -@kindex DEFINED(@var{symbol}) -@cindex symbol defaults -@item DEFINED(@var{symbol}) -Return 1 if @var{symbol} is in the linker global symbol table and is -defined, otherwise return 0. You can use this function to provide default -values for symbols. For example, the following command-file fragment shows how -to set a global symbol @code{begin} to the first location in the -@code{.text} section---but if a symbol called @code{begin} already -existed, its value is preserved: - -@smallexample -@group -SECTIONS@{ @dots{} - .text : @{ - begin = DEFINED(begin) ? begin : . ; - @dots{} - @} -@dots{} @} -@end group -@end smallexample - -@kindex NEXT(@var{exp}) -@cindex unallocated address, next -@item NEXT(@var{exp}) -Return the next unallocated address that is a multiple of @var{exp}. -This function is closely related to @code{ALIGN(@var{exp})}; unless you -use the @code{MEMORY} command to define discontinuous memory for the -output file, the two functions are equivalent. - -@kindex SIZEOF(@var{section}) -@cindex section size -@item SIZEOF(@var{section}) -Return the size in bytes of the named @var{section}, if that section has -been allocated. In the following example, @code{symbol_1} and -@code{symbol_2} are assigned identical values: -@c What does it return if the section hasn't been allocated? 0? -@smallexample -@group -SECTIONS@{ @dots{} - .output @{ - .start = . ; - @dots{} - .end = . ; - @} - symbol_1 = .end - .start ; - symbol_2 = SIZEOF(.output); -@dots{} @} -@end group -@end smallexample - -@kindex SIZEOF_HEADERS -@cindex header size -@kindex sizeof_headers -@item SIZEOF_HEADERS -@itemx sizeof_headers -Return the size in bytes of the output file's headers. You can use this number -as the start address of the first section, if you choose, to facilitate -paging. - -@kindex MAX -@item MAX(@var{exp1}, @var{exp2}) -Returns the maximum of @var{exp1} and @var{exp2}. - -@kindex MIN -@item MIN(@var{exp1}, @var{exp2}) -Returns the minimum of @var{exp1} and @var{exp2}. - -@end table - -@node Semicolons -@subsection Semicolons - -Semicolons (``@key{;}'') are required in the following places. In all -other places they can appear for aesthetic reasons but are otherwise ignored. - -@table @code -@item Assignment -Semicolons must appear at the end of assignment expressions. -@xref{Assignment} - -@item PHDRS -Semicolons must appear at the end of a @code{PHDRS} statement. -@xref{PHDRS} -@end table - -@node MEMORY -@section Memory Layout -@kindex MEMORY -@cindex regions of memory -@cindex discontinuous memory -@cindex allocating memory -The linker's default configuration permits allocation of all available memory. -You can override this configuration by using the @code{MEMORY} command. The -@code{MEMORY} command describes the location and size of blocks of -memory in the target. By using it carefully, you can describe which -memory regions may be used by the linker, and which memory regions it -must avoid. The linker does not shuffle sections to fit into the -available regions, but does move the requested sections into the correct -regions and issue errors when the regions become too full. - -A command file may contain at most one use of the @code{MEMORY} -command; however, you can define as many blocks of memory within it as -you wish. The syntax is: - -@smallexample -@group -MEMORY - @{ - @var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len} - @dots{} - @} -@end group -@end smallexample -@table @code -@cindex naming memory regions -@item @var{name} -is a name used internally by the linker to refer to the region. Any -symbol name may be used. The region names are stored in a separate -name space, and will not conflict with symbols, file names or section -names. Use distinct names to specify multiple regions. - -@cindex memory region attributes -@item (@var{attr}) -is an optional list of attributes that specify whether to use a -particular memory to place sections that are not listed in the linker -script. Valid attribute lists must be made up of the characters -``@code{ALIRWX}'' that match section attributes. If you omit the -attribute list, you may omit the parentheses around it as well. The -attributes currently supported are: - -@table @samp -@item @code{Letter} -@code{Section Attribute} - -@item @code{R} -Read-only sections. - -@item @code{W} -Read/write sections. - -@item @code{X} -Sections containing executable code. - -@item @code{A} -Allocated sections. - -@item @code{I} -Initialized sections. - -@item @code{L} -Same as @code{I}. - -@item @code{!} -Invert the sense of any of the following attributes. -@end table - -@kindex ORIGIN = -@kindex o = -@kindex org = -@item @var{origin} -is the start address of the region in physical memory. It is -an expression that must evaluate to a constant before -memory allocation is performed. The keyword @code{ORIGIN} may be -abbreviated to @code{org} or @code{o} (but not, for example, @samp{ORG}). - -@kindex LENGTH = -@kindex len = -@kindex l = -@item @var{len} -is the size in bytes of the region (an expression). -The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}. -@end table - -For example, to specify that memory has two regions available for -allocation---one starting at 0 for 256 kilobytes, and the other starting -at @code{0x40000000} for four megabytes. The @code{rom} memory region -will get all sections without an explicit memory register that are -either read-only or contain code, while the @code{ram} memory region -will get the sections. - -@smallexample -@group -MEMORY - @{ - rom (rx) : ORIGIN = 0, LENGTH = 256K - ram (!rx) : org = 0x40000000, l = 4M - @} -@end group -@end smallexample - -Once you have defined a region of memory named @var{mem}, you can direct -specific output sections there by using a command ending in -@samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section -Options}). If the combined output sections directed to a region are too -big for the region, the linker will issue an error message. - -@node SECTIONS -@section Specifying Output Sections - -@kindex SECTIONS -The @code{SECTIONS} command controls exactly where input sections are -placed into output sections, their order in the output file, and to -which output sections they are allocated. - -You may use at most one @code{SECTIONS} command in a script file, -but you can have as many statements within it as you wish. Statements -within the @code{SECTIONS} command can do one of three things: - -@itemize @bullet -@item -define the entry point; - -@item -assign a value to a symbol; - -@item -describe the placement of a named output section, and which input -sections go into it. -@end itemize - -You can also use the first two operations---defining the entry point and -defining symbols---outside the @code{SECTIONS} command: @pxref{Entry -Point}, and @ref{Assignment}. They are permitted here as well for -your convenience in reading the script, so that symbols and the entry -point can be defined at meaningful points in your output-file layout. - -If you do not use a @code{SECTIONS} command, the linker places each input -section into an identically named output section in the order that the -sections are first encountered in the input files. If all input sections -are present in the first file, for example, the order of sections in the -output file will match the order in the first input file. - -@menu -* Section Definition:: Section Definitions -* Section Placement:: Section Placement -* Section Data Expressions:: Section Data Expressions -* Section Options:: Optional Section Attributes -* Overlays:: Overlays -@end menu - -@node Section Definition -@subsection Section Definitions -@cindex section definition -The most frequently used statement in the @code{SECTIONS} command is -the @dfn{section definition}, which specifies the -properties of an output section: its location, alignment, contents, -fill pattern, and target memory region. Most of -these specifications are optional; the simplest form of a section -definition is -@smallexample -SECTIONS @{ @dots{} - @var{secname} : @{ - @var{contents} - @} -@dots{} @} -@end smallexample -@cindex naming output sections -@noindent -@var{secname} is the name of the output section, and @var{contents} a -specification of what goes there---for example, a list of input files or -sections of input files (@pxref{Section Placement}). The whitespace -around @var{secname} is required, so that the section name is -unambiguous. The other whitespace shown is optional. You do need the -colon @samp{:} and the braces @samp{@{@}}, however. - -@var{secname} must meet the constraints of your output format. In -formats which only support a limited number of sections, such as -@code{a.out}, the name must be one of the names supported by the format -(@code{a.out}, for example, allows only @code{.text}, @code{.data} or -@code{.bss}). If the output format supports any number of sections, but -with numbers and not names (as is the case for Oasys), the name should be -supplied as a quoted numeric string. A section name may consist of any -sequence of characters, but any name which does not conform to the standard -@code{ld} symbol name syntax must be quoted. -@xref{Symbols, , Symbol Names}. - -The special @var{secname} @samp{/DISCARD/} may be used to discard input -sections. Any sections which are assigned to an output section named -@samp{/DISCARD/} are not included in the final link output. - -The linker will not create output sections which do not have any -contents. This is for convenience when referring to input sections that -may or may not exist. For example, -@smallexample -.foo @{ *(.foo) @} -@end smallexample -will only create a @samp{.foo} section in the output file if there is a -@samp{.foo} section in at least one input file. - -@node Section Placement -@subsection Section Placement - -@cindex contents of a section -In a section definition, you can specify the contents of an output -section by listing particular input files, by listing particular -input-file sections, or by a combination of the two. You can also place -arbitrary data in the section, and define symbols relative to the -beginning of the section. - -The @var{contents} of a section definition may include any of the -following kinds of statement. You can include as many of these as you -like in a single section definition, separated from one another by -whitespace. - -@table @code -@kindex @var{filename} -@cindex input files, section defn -@cindex files, including in output sections -@item @var{filename} -You may simply name a particular input file to be placed in the current -output section; @emph{all} sections from that file are placed in the -current section definition. If the file name has already been mentioned -in another section definition, with an explicit section name list, then -only those sections which have not yet been allocated are used. - -To specify a list of particular files by name: -@smallexample -.data : @{ afile.o bfile.o cfile.o @} -@end smallexample -@noindent -The example also illustrates that multiple statements can be included in -the contents of a section definition, since each file name is a separate -statement. - -@kindex @var{filename}(@var{section}) -@cindex files and sections, section defn -@item @var{filename}( @var{section} ) -@itemx @var{filename}( @var{section} , @var{section}, @dots{} ) -@itemx @var{filename}( @var{section} @var{section} @dots{} ) -You can name one or more sections from your input files, for insertion -in the current output section. If you wish to specify a list of -input-file sections inside the parentheses, separate the section names -with whitespace. - -@cindex input sections to output section -@kindex *(@var{section}) -@item * (@var{section}) -@itemx * (@var{section}, @var{section}, @dots{}) -@itemx * (@var{section} @var{section} @dots{}) -Instead of explicitly naming particular input files in a link control -script, you can refer to @emph{all} files from the @code{ld} command -line: use @samp{*} instead of a particular file name before the -parenthesized input-file section list. - -If you have already explicitly included some files by name, @samp{*} -refers to all @emph{remaining} files---those whose places in the output -file have not yet been defined. - -For example, to copy sections @code{1} through @code{4} from an Oasys file -into the @code{.text} section of an @code{a.out} file, and sections @code{13} -and @code{14} into the @code{.data} section: -@smallexample -@group -SECTIONS @{ - .text :@{ - *("1" "2" "3" "4") - @} - - .data :@{ - *("13" "14") - @} -@} -@end group -@end smallexample - -@cindex @code{[@var{section}@dots{}]}, not supported -@samp{[ @var{section} @dots{} ]} used to be accepted as an alternate way -to specify named sections from all unallocated input files. Because -some operating systems (VMS) allow brackets in file names, that notation -is no longer supported. - -@cindex uninitialized data -@cindex commons in output -@kindex *( COMMON ) -@item @var{filename}@code{( COMMON )} -@itemx *( COMMON ) -Specify where in your output file to place uninitialized data -with this notation. @code{*(COMMON)} by itself refers to all -uninitialized data from all input files (so far as it is not yet -allocated); @var{filename}@code{(COMMON)} refers to uninitialized data -from a particular file. Both are special cases of the general -mechanisms for specifying where to place input-file sections: -@code{ld} permits you to refer to uninitialized data as if it -were in an input-file section named @code{COMMON}, regardless of the -input file's format. -@end table - -In any place where you may use a specific file or section name, you may -also use a wildcard pattern. The linker handles wildcards much as the -Unix shell does. A @samp{*} character matches any number of characters. -A @samp{?} character matches any single character. The sequence -@samp{[@var{chars}]} will match a single instance of any of the -@var{chars}; the @samp{-} character may be used to specify a range of -characters, as in @samp{[a-z]} to match any lower case letter. A -@samp{\} character may be used to quote the following character. - -When a file name is matched with a wildcard, the wildcard characters -will not match a @samp{/} character (used to separate directory names on -Unix). A pattern consisting of a single @samp{*} character is an -exception; it will always match any file name. In a section name, the -wildcard characters will match a @samp{/} character. - -Wildcards only match files which are explicitly specified on the command -line. The linker does not search directories to expand wildcards. -However, if you specify a simple file name---a name with no wildcard -characters---in a linker script, and the file name is not also specified -on the command line, the linker will attempt to open the file as though -it appeared on the command line. - -In the following example, the command script arranges the output file -into three consecutive sections, named @code{.text}, @code{.data}, and -@code{.bss}, taking the input for each from the correspondingly named -sections of all the input files: - -@smallexample -@group -SECTIONS @{ - .text : @{ *(.text) @} - .data : @{ *(.data) @} - .bss : @{ *(.bss) *(COMMON) @} -@} -@end group -@end smallexample - -The following example reads all of the sections from file @code{all.o} -and places them at the start of output section @code{outputa} which -starts at location @code{0x10000}. All of section @code{.input1} from -file @code{foo.o} follows immediately, in the same output section. All -of section @code{.input2} from @code{foo.o} goes into output section -@code{outputb}, followed by section @code{.input1} from @code{foo1.o}. -All of the remaining @code{.input1} and @code{.input2} sections from any -files are written to output section @code{outputc}. - -@smallexample -@group -SECTIONS @{ - outputa 0x10000 : - @{ - all.o - foo.o (.input1) - @} - outputb : - @{ - foo.o (.input2) - foo1.o (.input1) - @} - outputc : - @{ - *(.input1) - *(.input2) - @} -@} -@end group -@end smallexample - -This example shows how wildcard patterns might be used to partition -files. All @code{.text} sections are placed in @code{.text}, and all -@code{.bss} sections are placed in @code{.bss}. For all files beginning -with an upper case character, the @code{.data} section is placed into -@code{.DATA}; for all other files, the @code{.data} section is placed -into @code{.data}. - -@smallexample -@group -SECTIONS @{ - .text : @{ *(.text) @} - .DATA : @{ [A-Z]*(.data) @} - .data : @{ *(.data) @} - .bss : @{ *(.bss) @} -@} -@end group -@end smallexample - -@node Section Data Expressions -@subsection Section Data Expressions - -@cindex expressions in a section -The foregoing statements arrange, in your output file, data originating -from your input files. You can also place data directly in an output -section from the link command script. Most of these additional -statements involve expressions (@pxref{Expressions}). Although these -statements are shown separately here for ease of presentation, no such -segregation is needed within a section definition in the @code{SECTIONS} -command; you can intermix them freely with any of the statements we've -just described. - -@table @code -@cindex input filename symbols -@cindex filename symbols -@kindex CREATE_OBJECT_SYMBOLS -@item CREATE_OBJECT_SYMBOLS -Create a symbol for each input file -in the current section, set to the address of the first byte of -data written from that input file. For instance, with @code{a.out} -files it is conventional to have a symbol for each input file. You can -accomplish this by defining the output @code{.text} section as follows: -@smallexample -@group -SECTIONS @{ - .text 0x2020 : - @{ - CREATE_OBJECT_SYMBOLS - *(.text) - _etext = ALIGN(0x2000); - @} - @dots{} -@} -@end group -@end smallexample - -If @code{sample.ld} is a file containing this script, and @code{a.o}, -@code{b.o}, @code{c.o}, and @code{d.o} are four input files with -contents like the following--- -@smallexample -@group -/* a.c */ - -afunction() @{ @} -int adata=1; -int abss; -@end group -@end smallexample - -@noindent -@samp{ld -M -T sample.ld a.o b.o c.o d.o} would create a map like this, -containing symbols matching the object file names: -@smallexample -00000000 A __DYNAMIC -00004020 B _abss -00004000 D _adata -00002020 T _afunction -00004024 B _bbss -00004008 D _bdata -00002038 T _bfunction -00004028 B _cbss -00004010 D _cdata -00002050 T _cfunction -0000402c B _dbss -00004018 D _ddata -00002068 T _dfunction -00004020 D _edata -00004030 B _end -00004000 T _etext -00002020 t a.o -00002038 t b.o -00002050 t c.o -00002068 t d.o -@end smallexample - -@kindex @var{symbol} = @var{expression} ; -@kindex @var{symbol} @var{f}= @var{expression} ; -@item @var{symbol} = @var{expression} ; -@itemx @var{symbol} @var{f}= @var{expression} ; -@var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}='' -refers to any of the operators @code{&= += -= *= /=} which combine -arithmetic and assignment. - -@cindex assignment, in section defn -When you assign a value to a symbol within a particular section -definition, the value is relative to the beginning of the section -(@pxref{Assignment}). If you write - -@smallexample -@group -SECTIONS @{ - abs = 14 ; - @dots{} - .data : @{ @dots{} rel = 14 ; @dots{} @} - abs2 = 14 + ADDR(.data); - @dots{} -@} -@end group -@end smallexample - -@c FIXME: Try above example! -@noindent -@code{abs} and @code{rel} do not have the same value; @code{rel} has the -same value as @code{abs2}. - -@kindex BYTE(@var{expression}) -@kindex SHORT(@var{expression}) -@kindex LONG(@var{expression}) -@kindex QUAD(@var{expression}) -@kindex SQUAD(@var{expression}) -@cindex direct output -@item BYTE(@var{expression}) -@itemx SHORT(@var{expression}) -@itemx LONG(@var{expression}) -@itemx QUAD(@var{expression}) -@itemx SQUAD(@var{expression}) -By including one of these four statements in a section definition, you -can explicitly place one, two, four, eight unsigned, or eight signed -bytes (respectively) at the current address of that section. When using -a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the same. -When both host and target are 32 bits, @code{QUAD} uses an unsigned 32 -bit value, and @code{SQUAD} sign extends the value. Both will use the -correct endianness when writing out the value. - -@ifclear SingleFormat -Multiple-byte quantities are represented in whatever byte order is -appropriate for the output file format (@pxref{BFD}). -@end ifclear - -@kindex FILL(@var{expression}) -@cindex holes, filling -@cindex unspecified memory -@item FILL(@var{expression}) -Specify the ``fill pattern'' for the current section. Any otherwise -unspecified regions of memory within the section (for example, regions -you skip over by assigning a new value to the location counter @samp{.}) -are filled with the two least significant bytes from the -@var{expression} argument. A @code{FILL} statement covers memory -locations @emph{after} the point it occurs in the section definition; by -including more than one @code{FILL} statement, you can have different -fill patterns in different parts of an output section. -@end table - -@node Section Options -@subsection Optional Section Attributes -@cindex section defn, full syntax -Here is the full syntax of a section definition, including all the -optional portions: - -@smallexample -@group -SECTIONS @{ -@dots{} -@var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : AT ( @var{ldadr} ) - @{ @var{contents} @} >@var{region} :@var{phdr} =@var{fill} -@dots{} -@} -@end group -@end smallexample - -@var{secname} and @var{contents} are required. @xref{Section -Definition}, and @ref{Section Placement}, for details on -@var{contents}. The remaining elements---@var{start}, -@code{BLOCK(@var{align)}}, @code{(NOLOAD)}, @code{AT ( @var{ldadr} )}, -@code{>@var{region}}, @code{:@var{phdr}}, and @code{=@var{fill}}---are -all optional. - -@table @code -@cindex start address, section -@cindex section start -@cindex section address -@item @var{start} -You can force the output section to be loaded at a specified address by -specifying @var{start} immediately following the section name. -@var{start} can be represented as any expression. The following -example generates section @var{output} at location -@code{0x40000000}: - -@smallexample -@group -SECTIONS @{ - @dots{} - output 0x40000000: @{ - @dots{} - @} - @dots{} -@} -@end group -@end smallexample - -@kindex BLOCK(@var{align}) -@cindex section alignment -@cindex aligning sections -@item BLOCK(@var{align}) -You can include @code{BLOCK()} specification to advance -the location counter @code{.} prior to the beginning of the section, so -that the section will begin at the specified alignment. @var{align} is -an expression. - -@kindex NOLOAD -@cindex prevent unnecessary loading -@cindex loading, preventing -@item (NOLOAD) -The @samp{(NOLOAD)} directive will mark a section to not be loaded at -run time. The linker will process the section normally, but will mark -it so that a program loader will not load it into memory. For example, -in the script sample below, the @code{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 @code{ROM} section will appear in the -linker output file as usual. - -@smallexample -@group -SECTIONS @{ - ROM 0 (NOLOAD) : @{ @dots{} @} - @dots{} -@} -@end group -@end smallexample - -@kindex AT ( @var{ldadr} ) -@cindex specify load address -@cindex load address, specifying -@item AT ( @var{ldadr} ) -The expression @var{ldadr} that follows the @code{AT} keyword specifies -the load address of the section. The default (if you do not use the -@code{AT} keyword) is to make the load address the same as the -relocation address. This feature is designed to make it easy to build a -ROM image. For example, this @code{SECTIONS} definition creates two -output sections: one called @samp{.text}, which starts at @code{0x1000}, -and one called @samp{.mdata}, which is loaded at the end of the -@samp{.text} section even though its relocation address is -@code{0x2000}. The symbol @code{_data} is defined with the value -@code{0x2000}: - -@smallexample -@group -SECTIONS - @{ - .text 0x1000 : @{ *(.text) _etext = . ; @} - .mdata 0x2000 : - AT ( ADDR(.text) + SIZEOF ( .text ) ) - @{ _data = . ; *(.data); _edata = . ; @} - .bss 0x3000 : - @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@} -@} -@end group -@end smallexample - -The run-time initialization code (for C programs, usually @code{crt0}) -for use with a ROM generated this way has to include something like -the following, to copy the initialized data from the ROM image to its runtime -address: - -@smallexample -@group -char *src = _etext; -char *dst = _data; - -/* ROM has data at end of text; copy it. */ -while (dst < _edata) @{ - *dst++ = *src++; -@} - -/* Zero bss */ -for (dst = _bstart; dst< _bend; dst++) - *dst = 0; -@end group -@end smallexample - -@kindex >@var{region} -@cindex section, assigning to memory region -@cindex memory regions and sections -@item >@var{region} -Assign this section to a previously defined region of memory. -@xref{MEMORY}. - -@kindex :@var{phdr} -@cindex section, assigning to program header -@cindex program headers and sections -@item :@var{phdr} -Assign this section to a segment described by a program header. -@xref{PHDRS}. If a section is assigned to one or more segments, then -all subsequent allocated sections will be assigned to those segments as -well, unless they use an explicitly @code{:@var{phdr}} modifier. To -prevent a section from being assigned to a segment when it would -normally default to one, use @code{:NONE}. - -@kindex =@var{fill} -@cindex section fill pattern -@cindex fill pattern, entire section -@item =@var{fill} -Including @code{=@var{fill}} in a section definition specifies the -initial fill value for that section. You may use any expression to -specify @var{fill}. Any unallocated holes in the current output section -when written to the output file will be filled with the two least -significant bytes of the value, repeated as necessary. You can also -change the fill value with a @code{FILL} statement in the @var{contents} -of a section definition. - -@end table - -@node Overlays -@subsection Overlays -@kindex OVERLAY -@cindex overlays - -The @code{OVERLAY} command provides an easy way to describe sections -which are to be loaded as part of a single memory image but are to be -run at the same memory address. At run time, some sort of overlay -manager will copy the overlaid sections in and out of the runtime memory -address as required, perhaps by simply manipulating addressing bits. -This approach can be useful, for example, when a certain region of -memory is faster than another. - -The @code{OVERLAY} command is used within a @code{SECTIONS} command. It -appears as follows: -@smallexample -@group - OVERLAY @var{start} : [ NOCROSSREFS ] AT ( @var{ldaddr} ) - @{ - @var{secname1} @{ @var{contents} @} :@var{phdr} =@var{fill} - @var{secname2} @{ @var{contents} @} :@var{phdr} =@var{fill} - @dots{} - @} >@var{region} :@var{phdr} =@var{fill} -@end group -@end smallexample - -Everything is optional except @code{OVERLAY} (a keyword), and each -section must have a name (@var{secname1} and @var{secname2} above). The -section definitions within the @code{OVERLAY} construct are identical to -those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}), -except that no addresses and no memory regions may be defined for -sections within an @code{OVERLAY}. - -The sections are all defined with the same starting address. The load -addresses of the sections are arranged such that they are consecutive in -memory starting at the load address used for the @code{OVERLAY} as a -whole (as with normal section definitions, the load address is optional, -and defaults to the start address; the start address is also optional, -and defaults to @code{.}). - -If the @code{NOCROSSREFS} keyword is used, and there any references -among the sections, the linker will report an error. Since the sections -all run at the same address, it normally does not make sense for one -section to refer directly to another. @xref{Option Commands, -NOCROSSREFS}. - -For each section within the @code{OVERLAY}, the linker automatically -defines two symbols. The symbol @code{__load_start_@var{secname}} is -defined as the starting load address of the section. The symbol -@code{__load_stop_@var{secname}} is defined as the final load address of -the section. Any characters within @var{secname} which are not legal -within C identifiers are removed. C (or assembler) code may use these -symbols to move the overlaid sections around as necessary. - -At the end of the overlay, the value of @code{.} is set to the start -address of the overlay plus the size of the largest section. - -Here is an example. Remember that this would appear inside a -@code{SECTIONS} construct. - -@smallexample -@group - OVERLAY 0x1000 : AT (0x4000) - @{ - .text0 @{ o1/*.o(.text) @} - .text1 @{ o2/*.o(.text) @} - @} -@end group -@end smallexample - -This will define both @code{.text0} and @code{.text1} to start at -address 0x1000. @code{.text0} will be loaded at address 0x4000, and -@code{.text1} will be loaded immediately after @code{.text0}. The -following symbols will be defined: @code{__load_start_text0}, -@code{__load_stop_text0}, @code{__load_start_text1}, -@code{__load_stop_text1}. - -C code to copy overlay @code{.text1} into the overlay area might look -like the following. - -@smallexample -@group - extern char __load_start_text1, __load_stop_text1; - memcpy ((char *) 0x1000, &__load_start_text1, - &__load_stop_text1 - &__load_start_text1); -@end group -@end smallexample - -Note that the @code{OVERLAY} command is just syntactic sugar, since -everything it does can be done using the more basic commands. The above -example could have been written identically as follows. - -@smallexample -@group - .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @} - __load_start_text0 = LOADADDR (.text0); - __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0); - .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @} - __load_start_text1 = LOADADDR (.text1); - __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1); - . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); -@end group -@end smallexample - -@node PHDRS -@section ELF Program Headers -@kindex PHDRS -@cindex program headers -@cindex ELF program headers - -The ELF object file format uses @dfn{program headers}, which are read by -the system loader and describe how the program should be loaded into -memory. These program headers must be set correctly in order to run the -program on a native ELF system. The linker will create reasonable -program headers by default. However, in some cases, it is desirable to -specify the program headers more precisely; the @code{PHDRS} command may -be used for this purpose. When the @code{PHDRS} command is used, the -linker will not generate any program headers itself. - -The @code{PHDRS} command is only meaningful when generating an ELF -output file. It is ignored in other cases. This manual does not -describe the details of how the system loader interprets program -headers; for more information, see the ELF ABI. The program headers of -an ELF file may be displayed using the @samp{-p} option of the -@code{objdump} command. - -This is the syntax of the @code{PHDRS} command. The words @code{PHDRS}, -@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords. - -@smallexample -@group -PHDRS -@{ - @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ] - [ FLAGS ( @var{flags} ) ] ; -@} -@end group -@end smallexample - -The @var{name} is used only for reference in the @code{SECTIONS} command -of the linker script. It does not get put into the output file. - -Certain program header types describe segments of memory which are -loaded from the file by the system loader. In the linker script, the -contents of these segments are specified by directing allocated output -sections to be placed in the segment. To do this, the command -describing the output section in the @code{SECTIONS} command should use -@samp{:@var{name}}, where @var{name} is the name of the program header -as it appears in the @code{PHDRS} command. @xref{Section Options}. - -It is normal for certain sections to appear in more than one segment. -This merely implies that one segment of memory contains another. This -is specified by repeating @samp{:@var{name}}, using it once for each -program header in which the section is to appear. - -If a section is placed in one or more segments using @samp{:@var{name}}, -then all subsequent allocated sections which do not specify -@samp{:@var{name}} are placed in the same segments. This is for -convenience, since generally a whole set of contiguous sections will be -placed in a single segment. To prevent a section from being assigned to -a segment when it would normally default to one, use @code{:NONE}. - -The @code{FILEHDR} and @code{PHDRS} keywords which may appear after the -program header type also indicate contents of the segment of memory. -The @code{FILEHDR} keyword means that the segment should include the ELF -file header. The @code{PHDRS} keyword means that the segment should -include the ELF program headers themselves. - -The @var{type} may be one of the following. The numbers indicate the -value of the keyword. - -@table @asis -@item @code{PT_NULL} (0) -Indicates an unused program header. - -@item @code{PT_LOAD} (1) -Indicates that this program header describes a segment to be loaded from -the file. - -@item @code{PT_DYNAMIC} (2) -Indicates a segment where dynamic linking information can be found. - -@item @code{PT_INTERP} (3) -Indicates a segment where the name of the program interpreter may be -found. - -@item @code{PT_NOTE} (4) -Indicates a segment holding note information. - -@item @code{PT_SHLIB} (5) -A reserved program header type, defined but not specified by the ELF -ABI. - -@item @code{PT_PHDR} (6) -Indicates a segment where the program headers may be found. - -@item @var{expression} -An expression giving the numeric type of the program header. This may -be used for types not defined above. -@end table - -It is possible to specify that a segment should be loaded at a -particular address in memory. This is done using an @code{AT} -expression. This is identical to the @code{AT} command used in the -@code{SECTIONS} command (@pxref{Section Options}). Using the @code{AT} -command for a program header overrides any information in the -@code{SECTIONS} command. - -Normally the segment flags are set based on the sections. The -@code{FLAGS} keyword may be used to explicitly specify the segment -flags. The value of @var{flags} must be an integer. It is used to -set the @code{p_flags} field of the program header. - -Here is an example of the use of @code{PHDRS}. This shows a typical set -of program headers used on a native ELF system. - -@example -@group -PHDRS -@{ - headers PT_PHDR PHDRS ; - interp PT_INTERP ; - text PT_LOAD FILEHDR PHDRS ; - data PT_LOAD ; - dynamic PT_DYNAMIC ; -@} - -SECTIONS -@{ - . = SIZEOF_HEADERS; - .interp : @{ *(.interp) @} :text :interp - .text : @{ *(.text) @} :text - .rodata : @{ *(.rodata) @} /* defaults to :text */ - @dots{} - . = . + 0x1000; /* move to a new page in memory */ - .data : @{ *(.data) @} :data - .dynamic : @{ *(.dynamic) @} :data :dynamic - @dots{} -@} -@end group -@end example - -@node Entry Point -@section The Entry Point -@kindex ENTRY(@var{symbol}) -@cindex start of execution -@cindex first instruction -The linker command language includes a command specifically for -defining the first executable instruction in an output file (its -@dfn{entry point}). Its argument is a symbol name: -@smallexample -ENTRY(@var{symbol}) -@end smallexample - -Like symbol assignments, the @code{ENTRY} command may be placed either -as an independent command in the command file, or among the section -definitions within the @code{SECTIONS} command---whatever makes the most -sense for your layout. - -@cindex entry point, defaults -@code{ENTRY} is only one of several ways of choosing the entry point. -You may indicate it in any of the following ways (shown in descending -order of priority: methods higher in the list override methods lower down). -@itemize @bullet -@item -the @samp{-e} @var{entry} command-line option; -@item -the @code{ENTRY(@var{symbol})} command in a linker control script; -@item -the value of the symbol @code{start}, if present; -@item -the address of the first byte of the @code{.text} section, if present; -@item -The address @code{0}. -@end itemize - -For example, you can use these rules to generate an entry point with an -assignment statement: if no symbol @code{start} is defined within your -input files, you can simply define it, assigning it an appropriate -value--- - -@smallexample -start = 0x2020; -@end smallexample - -@noindent -The example shows an absolute address, but you can use any expression. -For example, if your input object files use some other symbol-name -convention for the entry point, you can just assign the value of -whatever symbol contains the start address to @code{start}: - -@smallexample -start = other_symbol ; -@end smallexample - -@node Version Script -@section Version Script -@kindex VERSION @{script text@} -@cindex symbol versions -@cindex version script -@cindex versions of symbols -The linker command script includes a command specifically for -specifying a version script, and is only meaningful for ELF platforms -that support shared libraries. A version script can be -build directly into the linker script that you are using, or you -can supply the version script as just another input file to the linker -at the time that you link. The command script syntax is: -@smallexample -VERSION @{ version script contents @} -@end smallexample -The version script can also be specified to the linker by means of the -@samp{--version-script} linker command line option. -Version scripts are only meaningful when creating shared libraries. - -The format of the version script itself is identical to that used by -Sun's linker in Solaris 2.5. Versioning is done by defining a tree of -version nodes with the names and interdependencies specified in the -version script. The version script can specify which symbols are bound -to which version nodes, and it can reduce a specified set of symbols to -local scope so that they are not globally visible outside of the shared -library. - -The easiest way to demonstrate the version script language is with a few -examples. - -@smallexample -VERS_1.1 @{ - global: - foo1; - local: - old*; - original*; - new*; -@}; - -VERS_1.2 @{ - foo2; -@} VERS_1.1; - -VERS_2.0 @{ - bar1; bar2; -@} VERS_1.2; -@end smallexample - -In this example, three version nodes are defined. @samp{VERS_1.1} is the -first version node defined, and has no other dependencies. The symbol -@samp{foo1} is bound to this version node, and a number of symbols -that have appeared within various object files are reduced in scope to -local so that they are not visible outside of the shared library. - -Next, the node @samp{VERS_1.2} is defined. It depends upon -@samp{VERS_1.1}. The symbol @samp{foo2} is bound to this version node. - -Finally, the node @samp{VERS_2.0} is defined. It depends upon -@samp{VERS_1.2}. The symbols @samp{bar1} and @samp{bar2} are bound to -this version node. - -Symbols defined in the library which aren't specifically bound to a -version node are effectively bound to an unspecified base version of the -library. It is possible to bind all otherwise unspecified symbols to a -given version node using @samp{global: *} somewhere in the version -script. - -Lexically the names of the version nodes have no specific meaning other -than what they might suggest to the person reading them. The @samp{2.0} -version could just as well have appeared in between @samp{1.1} and -@samp{1.2}. However, this would be a confusing way to write a version -script. - -When you link an application against a shared library that has versioned -symbols, the application itself knows which version of each symbol it requires, -and it also knows which version nodes it needs from each shared library it is -linked against. Thus at runtime, the dynamic loader can make a quick check to -make sure that the libraries you have linked against do in fact supply all -of the version nodes that the application will need to resolve all of the -dynamic symbols. In this way it is possible for the dynamic linker to know -with certainty that all external symbols that it needs will be resolvable -without having to search for each symbol reference. - -The symbol versioning is in effect a much more sophisticated way of -doing minor version checking that SunOS does. The fundamental problem -that is being addressed here is that typically references to external -functions are bound on an as-needed basis, and are not all bound when -the application starts up. If a shared library is out of date, a -required interface may be missing; when the application tries to use -that interface, it may suddenly and unexpectedly fail. With symbol -versioning, the user will get a warning when they start their program if -the libraries being used with the application are too old. - -There are several GNU extensions to Sun's versioning approach. The -first of these is the ability to bind a symbol to a version node in the -source file where the symbol is defined instead of in the versioning -script. This was done mainly to reduce the burden on the library -maintainer. This can be done by putting something like: - -@smallexample -__asm__(".symver original_foo,foo@@VERS_1.1"); -@end smallexample - -in the C source file. This renamed the function @samp{original_foo} to -be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}. -The @samp{local:} directive can be used to prevent the symbol -@samp{original_foo} from being exported. - -The second GNU extension is to allow multiple versions of the same function -to appear in a given shared library. In this way an incompatible change to -an interface can take place without increasing the major version number of -the shared library, while still allowing applications linked against the old -interface to continue to function. - -This can only be accomplished by using multiple @samp{.symver} -directives in the assembler. An example of this would be: - -@smallexample -__asm__(".symver original_foo,foo@@"); -__asm__(".symver old_foo,foo@@VERS_1.1"); -__asm__(".symver old_foo1,foo@@VERS_1.2"); -__asm__(".symver new_foo,foo@@@@VERS_2.0"); -@end smallexample - -In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the -unspecified base version of the symbol. The source file that contains this -example would define 4 C functions: @samp{original_foo}, @samp{old_foo}, -@samp{old_foo1}, and @samp{new_foo}. - -When you have multiple definitions of a given symbol, there needs to be -some way to specify a default version to which external references to -this symbol will be bound. This can be accomplished with the -@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. Only one version of -a symbol can be declared 'default' in this manner - otherwise you would -effectively have multiple definitions of the same symbol. - -If you wish to bind a reference to a specific version of the symbol -within the shared library, you can use the aliases of convenience -(i.e. @samp{old_foo}), or you can use the @samp{.symver} directive to -specifically bind to an external version of the function in question. - -@node Option Commands -@section Option Commands -The command language includes a number of other commands that you can -use for specialized purposes. They are similar in purpose to -command-line options. - -@table @code -@kindex CONSTRUCTORS -@cindex C++ constructors, arranging in link -@cindex constructors, arranging in link -@item CONSTRUCTORS -When linking using the @code{a.out} object file format, the linker uses -an unusual set construct to support C++ global constructors and -destructors. When linking object file formats which do not support -arbitrary sections, such as @code{ECOFF} and @code{XCOFF}, the linker -will automatically recognize C++ global constructors and destructors by -name. For these object file formats, the @code{CONSTRUCTORS} command -tells the linker where this information should be placed. The -@code{CONSTRUCTORS} command is ignored for other object file formats. - -The symbol @w{@code{__CTOR_LIST__}} marks the start of the global -constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The -first word in the list is the number of entries, followed by the address -of each constructor or destructor, followed by a zero word. The -compiler must arrange to actually run the code. For these object file -formats @sc{gnu} C++ calls constructors from a subroutine @code{__main}; -a call to @code{__main} is automatically inserted into the startup code -for @code{main}. @sc{gnu} C++ runs destructors either by using -@code{atexit}, or directly from the function @code{exit}. - -For object file formats such as @code{COFF} or @code{ELF} which support -multiple sections, @sc{gnu} C++ will normally arrange to put the -addresses of global constructors and destructors into the @code{.ctors} -and @code{.dtors} sections. Placing the following sequence into your -linker script will build the sort of table which the @sc{gnu} C++ -runtime code expects to see. - -@smallexample - __CTOR_LIST__ = .; - LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) - *(.ctors) - LONG(0) - __CTOR_END__ = .; - __DTOR_LIST__ = .; - LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) - *(.dtors) - LONG(0) - __DTOR_END__ = .; -@end smallexample - -Normally the compiler and linker will handle these issues automatically, -and you will not need to concern yourself with them. However, you may -need to consider this if you are using C++ and writing your own linker -scripts. - -@need 1000 -@kindex FLOAT -@kindex NOFLOAT -@item FLOAT -@itemx NOFLOAT -These keywords were used in some older linkers to request a particular -math subroutine library. @code{ld} doesn't use the keywords, assuming -instead that any necessary subroutines are in libraries specified using -the general mechanisms for linking to archives; but to permit the use of -scripts that were written for the older linkers, the keywords -@code{FLOAT} and @code{NOFLOAT} are accepted and ignored. - -@kindex FORCE_COMMON_ALLOCATION -@cindex common allocation -@item FORCE_COMMON_ALLOCATION -This command has the same effect as the @samp{-d} command-line option: -to make @code{ld} assign space to common symbols even if a relocatable -output file is specified (@samp{-r}). - -@kindex INCLUDE @var{filename} -@cindex including a linker script -@item INCLUDE @var{filename} -Include the linker script @var{filename} at this point. The file will -be searched for in the current directory, and in any directory specified -with the @code{-L} option. You can nest calls to @code{INCLUDE} up to -10 levels deep. - -@kindex INPUT ( @var{files} ) -@cindex binary input files -@item INPUT ( @var{file}, @var{file}, @dots{} ) -@itemx INPUT ( @var{file} @var{file} @dots{} ) -Use this command to include binary input files in the link, without -including them in a particular section definition. -Specify the full name for each @var{file}, including @samp{.a} if -required. - -@code{ld} searches for each @var{file} through the archive-library -search path, just as for files you specify on the command line. -See the description of @samp{-L} in @ref{Options,,Command Line -Options}. - -If you use @samp{-l@var{file}}, @code{ld} will transform the name to -@code{lib@var{file}.a} as with the command line argument @samp{-l}. - -@kindex GROUP ( @var{files} ) -@cindex grouping input files -@item GROUP ( @var{file}, @var{file}, @dots{} ) -@itemx GROUP ( @var{file} @var{file} @dots{} ) -This command is like @code{INPUT}, except that the named files should -all be archives, and they are searched repeatedly until no new undefined -references are created. See the description of @samp{-(} in -@ref{Options,,Command Line Options}. - -@ignore -@kindex MAP ( @var{name} ) -@item MAP ( @var{name} ) -@c MAP(...) appears to look for an F in the arg, ignoring all other -@c chars; if it finds one, it sets "map_option_f" to true. But nothing -@c checks map_option_f. Apparently a stub for the future... -@end ignore - -@kindex OUTPUT ( @var{filename} ) -@cindex naming the output file -@item OUTPUT ( @var{filename} ) -Use this command to name the link output file @var{filename}. The -effect of @code{OUTPUT(@var{filename})} is identical to the effect of -@w{@samp{-o @var{filename}}}, which overrides it. You can use this -command to supply a default output-file name other than @code{a.out}. - -@ifclear SingleFormat -@kindex OUTPUT_ARCH ( @var{bfdname} ) -@cindex machine architecture, output -@item OUTPUT_ARCH ( @var{bfdname} ) -Specify a particular output machine architecture, with one of the names -used by the BFD back-end routines (@pxref{BFD}). This command is often -unnecessary; the architecture is most often set implicitly by either the -system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT} -command. - -@kindex OUTPUT_FORMAT ( @var{bfdname} ) -@cindex format, output file -@item OUTPUT_FORMAT ( @var{bfdname} ) -When @code{ld} is configured to support multiple object code formats, -you can use this command to specify a particular output format. -@var{bfdname} is one of the names used by the BFD back-end routines -(@pxref{BFD}). The effect is identical to the effect of the -@samp{--oformat} command-line option. This selection affects only the -output file; the related command @code{TARGET} affects primarily input -files. -@end ifclear - -@kindex SEARCH_DIR ( @var{path} ) -@cindex path for libraries -@cindex search path, libraries -@item SEARCH_DIR ( @var{path} ) -Add @var{path} to the list of paths where @code{ld} looks for -archive libraries. @code{SEARCH_DIR(@var{path})} has the same -effect as @samp{-L@var{path}} on the command line. - -@kindex STARTUP ( @var{filename} ) -@cindex first input file -@item STARTUP ( @var{filename} ) -Ensure that @var{filename} is the first input file used in the link -process. - -@ifclear SingleFormat -@cindex input file format -@kindex TARGET ( @var{format} ) -@item TARGET ( @var{format} ) -When @code{ld} is configured to support multiple object code formats, -you can use this command to change the input-file object code format -(like the command-line option @samp{-b} or its synonym @samp{--format}). -The argument @var{format} is one of the strings used by BFD to name -binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT} -is not, the last @code{TARGET} argument is also used as the default -format for the @code{ld} output file. @xref{BFD}. - -@kindex GNUTARGET -If you don't use the @code{TARGET} command, @code{ld} uses the value of -the environment variable @code{GNUTARGET}, if available, to select the -output file format. If that variable is also absent, @code{ld} uses -the default format configured for your machine in the BFD libraries. -@end ifclear - -@cindex cross references -@kindex NOCROSSREFS ( @var{sections} ) -@item NOCROSSREFS ( @var{section} @var{section} @dots{} ) -This command may be used to tell @code{ld} to issue an error about any -references among certain sections. - -In certain types of programs, particularly on embedded systems, when one -section is loaded into memory, another section will not be. Any direct -references between the two sections would be errors. For example, it -would be an error if code in one section called a function defined in -the other section. - -The @code{NOCROSSREFS} command takes a list of section names. If -@code{ld} detects any cross references between the sections, it reports -an error and returns a non-zero exit status. The @code{NOCROSSREFS} -command uses output section names, defined in the @code{SECTIONS} -command. It does not use the names of input sections. -@end table - -@ifset GENERIC -@node Machine Dependent -@chapter Machine Dependent Features - -@cindex machine dependencies -@code{ld} has additional features on some platforms; the following -sections describe them. Machines where @code{ld} has no additional -functionality are not listed. - -@menu -* H8/300:: @code{ld} and the H8/300 -* i960:: @code{ld} and the Intel 960 family -@end menu -@end ifset - -@c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict -@c between those and node-defaulting. -@ifset H8300 -@ifclear GENERIC -@raisesections -@end ifclear -@node H8/300 -@section @code{ld} and the H8/300 - -@cindex H8/300 support -For the H8/300, @code{ld} can perform these global optimizations when -you specify the @samp{--relax} command-line option. - -@table @emph -@cindex relaxing on H8/300 -@item relaxing address modes -@code{ld} finds all @code{jsr} and @code{jmp} instructions whose -targets are within eight bits, and turns them into eight-bit -program-counter relative @code{bsr} and @code{bra} instructions, -respectively. - -@cindex synthesizing on H8/300 -@item synthesizing instructions -@c FIXME: specifically mov.b, or any mov instructions really? -@code{ld} finds all @code{mov.b} instructions which use the -sixteen-bit absolute address form, but refer to the top -page of memory, and changes them to use the eight-bit address form. -(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into -@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the -top page of memory). -@end table -@ifclear GENERIC -@lowersections -@end ifclear -@end ifset - -@ifclear GENERIC -@ifset Hitachi -@c This stuff is pointless to say unless you're especially concerned -@c with Hitachi chips; don't enable it for generic case, please. -@node Hitachi -@chapter @code{ld} and other Hitachi chips - -@code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No -special features, commands, or command-line options are required for -these chips. -@end ifset -@end ifclear - -@ifset I960 -@ifclear GENERIC -@raisesections -@end ifclear -@node i960 -@section @code{ld} and the Intel 960 family - -@cindex i960 support - -You can use the @samp{-A@var{architecture}} command line option to -specify one of the two-letter names identifying members of the 960 -family; the option specifies the desired output target, and warns of any -incompatible instructions in the input files. It also modifies the -linker's search strategy for archive libraries, to support the use of -libraries specific to each particular architecture, by including in the -search loop names suffixed with the string identifying the architecture. - -For example, if your @code{ld} command line included @w{@samp{-ACA}} as -well as @w{@samp{-ltry}}, the linker would look (in its built-in search -paths, and in any paths you specify with @samp{-L}) for a library with -the names - -@smallexample -@group -try -libtry.a -tryca -libtryca.a -@end group -@end smallexample - -@noindent -The first two possibilities would be considered in any event; the last -two are due to the use of @w{@samp{-ACA}}. - -You can meaningfully use @samp{-A} more than once on a command line, since -the 960 architecture family allows combination of target architectures; each -use will add another pair of name variants to search for when @w{@samp{-l}} -specifies a library. - -@cindex @code{--relax} on i960 -@cindex relaxing on i960 -@code{ld} supports the @samp{--relax} option for the i960 family. If -you specify @samp{--relax}, @code{ld} finds all @code{balx} and -@code{calx} instructions whose targets are within 24 bits, and turns -them into 24-bit program-counter relative @code{bal} and @code{cal} -instructions, respectively. @code{ld} also turns @code{cal} -instructions into @code{bal} instructions when it determines that the -target subroutine is a leaf routine (that is, the target subroutine does -not itself call any subroutines). - -@ifclear GENERIC -@lowersections -@end ifclear -@end ifset - -@ifclear SingleFormat -@node BFD -@chapter BFD - -@cindex back end -@cindex object file management -@cindex object formats available -@kindex objdump -i -The linker accesses object and archive files using the BFD libraries. -These libraries allow the linker to use the same routines to operate on -object files whatever the object file format. A different object file -format can be supported simply by creating a new BFD back end and adding -it to the library. To conserve runtime memory, however, the linker and -associated tools are usually configured to support only a subset of the -object file formats available. You can use @code{objdump -i} -(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to -list all the formats available for your configuration. - -@cindex BFD requirements -@cindex requirements for BFD -As with most implementations, BFD is a compromise between -several conflicting requirements. The major factor influencing -BFD design was efficiency: any time used converting between -formats is time which would not have been spent had BFD not -been involved. This is partly offset by abstraction payback; since -BFD simplifies applications and back ends, more time and care -may be spent optimizing algorithms for a greater speed. - -One minor artifact of the BFD solution which you should bear in -mind is the potential for information loss. There are two places where -useful information can be lost using the BFD mechanism: during -conversion and during output. @xref{BFD information loss}. - -@menu -* BFD outline:: How it works: an outline of BFD -@end menu - -@node BFD outline -@section How it works: an outline of BFD -@cindex opening object files -@include bfdsumm.texi -@end ifclear - -@node Reporting Bugs -@chapter Reporting Bugs -@cindex bugs in @code{ld} -@cindex reporting bugs in @code{ld} - -Your bug reports play an essential role in making @code{ld} reliable. - -Reporting a bug may help you by bringing a solution to your problem, or -it may not. But in any case the principal function of a bug report is -to help the entire community by making the next version of @code{ld} -work better. Bug reports are your contribution to the maintenance of -@code{ld}. - -In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -@menu -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs -@end menu - -@node Bug Criteria -@section Have you found a bug? -@cindex bug criteria - -If you are not sure whether you have found a bug, here are some guidelines: - -@itemize @bullet -@cindex fatal signal -@cindex linker crash -@cindex crash of linker -@item -If the linker gets a fatal signal, for any input whatever, that is a -@code{ld} bug. Reliable linkers never crash. - -@cindex error on valid input -@item -If @code{ld} produces an error message for valid input, that is a bug. - -@cindex invalid input -@item -If @code{ld} does not produce an error message for invalid input, that -may be a bug. In the general case, the linker can not verify that -object files are correct. - -@item -If you are an experienced user of linkers, your suggestions for -improvement of @code{ld} are welcome in any case. -@end itemize - -@node Bug Reporting -@section How to report bugs -@cindex bug reports -@cindex @code{ld} bugs, reporting - -A number of companies and individuals offer support for @sc{gnu} -products. If you obtained @code{ld} from a support organization, we -recommend you contact that organization first. - -You can find contact information for many support companies and -individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs -distribution. - -In any event, we also recommend that you send bug reports for @code{ld} -to @samp{bug-gnu-utils@@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{Commands,,Command Language}. MRI compatible linker -scripts have a much simpler command set than the scripting language -otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most -commonly used MRI linker commands; these commands are described here. - -In general, MRI scripts aren't of much use with the @code{a.out} object -file format, since it only has three sections and MRI scripts lack some -features to make use of them. - -You can specify a file containing an MRI-compatible script using the -@samp{-c} command-line option. - -Each command in an MRI-compatible script occupies its own line; each -command line starts with the keyword that identifies the command (though -blank lines are also allowed for punctuation). If a line of an -MRI-compatible script begins with an unrecognized keyword, @code{ld} -issues a warning message, but continues processing the script. - -Lines beginning with @samp{*} are comments. - -You can write these commands using all upper-case letters, or all -lower case; for example, @samp{chip} is the same as @samp{CHIP}. -The following list shows only the upper-case form of each command. - -@table @code -@cindex @code{ABSOLUTE} (MRI) -@item ABSOLUTE @var{secname} -@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname} -Normally, @code{ld} includes in the output file all sections from all -the input files. However, in an MRI-compatible script, you can use the -@code{ABSOLUTE} command to restrict the sections that will be present in -your output program. If the @code{ABSOLUTE} command is used at all in a -script, then only the sections named explicitly in @code{ABSOLUTE} -commands will appear in the linker output. You can still use other -input sections (whatever you select on the command line, or using -@code{LOAD}) to resolve addresses in the output file. - -@cindex @code{ALIAS} (MRI) -@item ALIAS @var{out-secname}, @var{in-secname} -Use this command to place the data from input section @var{in-secname} -in a section called @var{out-secname} in the linker output file. - -@var{in-secname} may be an integer. - -@cindex @code{ALIGN} (MRI) -@item ALIGN @var{secname} = @var{expression} -Align the section called @var{secname} to @var{expression}. The -@var{expression} should be a power of two. - -@cindex @code{BASE} (MRI) -@item BASE @var{expression} -Use the value of @var{expression} as the lowest address (other than -absolute addresses) in the output file. - -@cindex @code{CHIP} (MRI) -@item CHIP @var{expression} -@itemx CHIP @var{expression}, @var{expression} -This command does nothing; it is accepted only for compatibility. - -@cindex @code{END} (MRI) -@item END -This command does nothing whatever; it's only accepted for compatibility. - -@cindex @code{FORMAT} (MRI) -@item FORMAT @var{output-format} -Similar to the @code{OUTPUT_FORMAT} command in the more general linker -language, but restricted to one of these output formats: - -@enumerate -@item -S-records, if @var{output-format} is @samp{S} - -@item -IEEE, if @var{output-format} is @samp{IEEE} - -@item -COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is -@samp{COFF} -@end enumerate - -@cindex @code{LIST} (MRI) -@item LIST @var{anything}@dots{} -Print (to the standard output file) a link map, as produced by the -@code{ld} command-line option @samp{-M}. - -The keyword @code{LIST} may be followed by anything on the -same line, with no change in its effect. - -@cindex @code{LOAD} (MRI) -@item LOAD @var{filename} -@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename} -Include one or more object file @var{filename} in the link; this has the -same effect as specifying @var{filename} directly on the @code{ld} -command line. - -@cindex @code{NAME} (MRI) -@item NAME @var{output-name} -@var{output-name} is the name for the program produced by @code{ld}; the -MRI-compatible command @code{NAME} is equivalent to the command-line -option @samp{-o} or the general script language command @code{OUTPUT}. - -@cindex @code{ORDER} (MRI) -@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname} -@itemx ORDER @var{secname} @var{secname} @var{secname} -Normally, @code{ld} orders the sections in its output file in the -order in which they first appear in the input files. In an MRI-compatible -script, you can override this ordering with the @code{ORDER} command. The -sections you list with @code{ORDER} will appear first in your output -file, in the order specified. - -@cindex @code{PUBLIC} (MRI) -@item PUBLIC @var{name}=@var{expression} -@itemx PUBLIC @var{name},@var{expression} -@itemx PUBLIC @var{name} @var{expression} -Supply a value (@var{expression}) for external symbol -@var{name} used in the linker input files. - -@cindex @code{SECT} (MRI) -@item SECT @var{secname}, @var{expression} -@itemx SECT @var{secname}=@var{expression} -@itemx SECT @var{secname} @var{expression} -You can use any of these three forms of the @code{SECT} command to -specify the start address (@var{expression}) for section @var{secname}. -If you have more than one @code{SECT} statement for the same -@var{secname}, only the @emph{first} sets the start address. -@end table - -@node Index -@unnumbered Index - -@printindex cp - -@tex -% I think something like @colophon should be in texinfo. In the -% meantime: -\long\def\colophon{\hbox to0pt{}\vfill -\centerline{The body of this manual is set in} -\centerline{\fontname\tenrm,} -\centerline{with headings in {\bf\fontname\tenbf}} -\centerline{and examples in {\tt\fontname\tentt}.} -\centerline{{\it\fontname\tenit\/} and} -\centerline{{\sl\fontname\tensl\/}} -\centerline{are used for emphasis.}\vfill} -\page\colophon -% Blame: doc@cygnus.com, 28mar91. -@end tex - - -@contents -@bye - - |