| \input texinfo |
| @setfilename ld.info |
| @syncodeindex ky cp |
| @include configdoc.texi |
| @c (configdoc.texi is generated by the Makefile) |
| @include ldver.texi |
| |
| @c @smallbook |
| |
| @ifinfo |
| @format |
| START-INFO-DIR-ENTRY |
| * Ld: (ld). The GNU linker. |
| END-INFO-DIR-ENTRY |
| @end format |
| @end ifinfo |
| |
| @ifinfo |
| This file documents the @sc{gnu} linker LD version @value{VERSION}. |
| |
| Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that |
| the entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| |
| @ignore |
| Permission is granted to process this file through Tex and print the |
| results, provided the printed document carries copying permission |
| notice identical to this one except for the removal of this paragraph |
| (this paragraph not being relevant to the printed manual). |
| |
| @end ignore |
| @end ifinfo |
| @iftex |
| @finalout |
| @setchapternewpage odd |
| @settitle Using LD, the GNU linker |
| @titlepage |
| @title Using ld |
| @subtitle The GNU linker |
| @sp 1 |
| @subtitle @code{ld} version 2 |
| @subtitle Version @value{VERSION} |
| @author Steve Chamberlain |
| @author Ian Lance Taylor |
| @author Cygnus Solutions |
| @page |
| |
| @tex |
| {\parskip=0pt |
| \hfill Cygnus Solutions\par |
| \hfill ian\@cygnus.com, doc\@cygnus.com\par |
| \hfill {\it Using LD, the GNU linker}\par |
| \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par |
| } |
| \global\parindent=0pt % Steve likes it this way. |
| @end tex |
| |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that |
| the entire resulting derived work is distributed under the terms of a |
| permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions. |
| @end titlepage |
| @end iftex |
| @c FIXME: Talk about importance of *order* of args, cmds to linker! |
| |
| @ifinfo |
| @node Top |
| @top Using ld |
| This file documents the @sc{gnu} linker ld version @value{VERSION}. |
| |
| @menu |
| * Overview:: Overview |
| * Invocation:: Invocation |
| * Scripts:: Linker Scripts |
| @ifset GENERIC |
| * Machine Dependent:: Machine Dependent Features |
| @end ifset |
| @ifclear GENERIC |
| @ifset H8300 |
| * H8/300:: ld and the H8/300 |
| @end ifset |
| @ifset Hitachi |
| * Hitachi:: ld and other Hitachi micros |
| @end ifset |
| @ifset I960 |
| * i960:: ld and the Intel 960 family |
| @end ifset |
| @end ifclear |
| @ifclear SingleFormat |
| * BFD:: BFD |
| @end ifclear |
| @c Following blank line required for remaining bug in makeinfo conds/menus |
| |
| * Reporting Bugs:: Reporting Bugs |
| * MRI:: MRI Compatible Script Files |
| * Index:: Index |
| @end menu |
| @end ifinfo |
| |
| @node Overview |
| @chapter Overview |
| |
| @cindex @sc{gnu} linker |
| @cindex what is this? |
| @code{ld} combines a number of object and archive files, relocates |
| their data and ties up symbol references. Usually the last step in |
| compiling a program is to run @code{ld}. |
| |
| @code{ld} accepts Linker Command Language files written in |
| a superset of AT&T's Link Editor Command Language syntax, |
| to provide explicit and total control over the linking process. |
| |
| @ifclear SingleFormat |
| This version of @code{ld} uses the general purpose BFD libraries |
| to operate on object files. This allows @code{ld} to read, combine, and |
| write object files in many different formats---for example, COFF or |
| @code{a.out}. Different formats may be linked together to produce any |
| available kind of object file. @xref{BFD}, for more information. |
| @end ifclear |
| |
| Aside from its flexibility, the @sc{gnu} linker is more helpful than other |
| linkers in providing diagnostic information. Many linkers abandon |
| execution immediately upon encountering an error; whenever possible, |
| @code{ld} continues executing, allowing you to identify other errors |
| (or, in some cases, to get an output file in spite of the error). |
| |
| @node Invocation |
| @chapter Invocation |
| |
| The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations, |
| and to be as compatible as possible with other linkers. As a result, |
| you have many choices to control its behavior. |
| |
| @ifset UsesEnvVars |
| @menu |
| * Options:: Command Line Options |
| * Environment:: Environment Variables |
| @end menu |
| |
| @node Options |
| @section Command Line Options |
| @end ifset |
| |
| @cindex command line |
| @cindex options |
| The linker supports a plethora of command-line options, but in actual |
| practice few of them are used in any particular context. |
| @cindex standard Unix system |
| For instance, a frequent use of @code{ld} is to link standard Unix |
| object files on a standard, supported Unix system. On such a system, to |
| link a file @code{hello.o}: |
| |
| @smallexample |
| ld -o @var{output} /lib/crt0.o hello.o -lc |
| @end smallexample |
| |
| This tells @code{ld} to produce a file called @var{output} as the |
| result of linking the file @code{/lib/crt0.o} with @code{hello.o} and |
| the library @code{libc.a}, which will come from the standard search |
| directories. (See the discussion of the @samp{-l} option below.) |
| |
| 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{Scripts}. |
| |
| For options whose names are a single letter, |
| option arguments must either follow the option letter without intervening |
| whitespace, or be given as separate arguments immediately following the |
| option that requires them. |
| |
| For options whose names are multiple letters, either one dash or two can |
| precede the option name; for example, @samp{--oformat} and |
| @samp{--oformat} are equivalent. Arguments to multiple-letter options |
| must either be separated from the option name by an equals sign, or be |
| given as separate arguments immediately following the option that |
| requires them. For example, @samp{--oformat srec} and |
| @samp{--oformat=srec} are equivalent. Unique abbreviations of the names |
| of multiple-letter options are accepted. |
| |
| @table @code |
| @kindex -a@var{keyword} |
| @item -a@var{keyword} |
| This option is supported for HP/UX compatibility. The @var{keyword} |
| argument must be one of the strings @samp{archive}, @samp{shared}, or |
| @samp{default}. @samp{-aarchive} is functionally equivalent to |
| @samp{-Bstatic}, and the other two keywords are functionally equivalent |
| to @samp{-Bdynamic}. This option may be used any number of times. |
| |
| @ifset I960 |
| @cindex architectures |
| @kindex -A@var{arch} |
| @item -A@var{architecture} |
| @kindex --architecture=@var{arch} |
| @itemx --architecture=@var{architecture} |
| In the current release of @code{ld}, this option is useful only for the |
| Intel 960 family of architectures. In that @code{ld} configuration, the |
| @var{architecture} argument identifies the particular architecture in |
| the 960 family, enabling some safeguards and modifying the |
| archive-library search path. @xref{i960,,@code{ld} and the Intel 960 |
| family}, for details. |
| |
| Future releases of @code{ld} may support similar functionality for |
| other architecture families. |
| @end ifset |
| |
| @ifclear SingleFormat |
| @cindex binary input format |
| @kindex -b @var{format} |
| @kindex --format=@var{format} |
| @cindex input format |
| @cindex input format |
| @item -b @var{input-format} |
| @itemx --format=@var{input-format} |
| @code{ld} may be configured to support more than one kind of object |
| file. If your @code{ld} is configured this way, you can use the |
| @samp{-b} option to specify the binary format for input object files |
| that follow this option on the command line. Even when @code{ld} is |
| configured to support alternative object formats, you don't usually need |
| to specify this, as @code{ld} should be configured to expect as a |
| default input format the most usual format on each machine. |
| @var{input-format} is a text string, the name of a particular format |
| supported by the BFD libraries. (You can list the available binary |
| formats with @samp{objdump -i}.) |
| @xref{BFD}. |
| |
| You may want to use this option if you are linking files with an unusual |
| binary format. You can also use @samp{-b} to switch formats explicitly (when |
| linking object files of different formats), by including |
| @samp{-b @var{input-format}} before each group of object files in a |
| particular format. |
| |
| The default format is taken from the environment variable |
| @code{GNUTARGET}. |
| @ifset UsesEnvVars |
| @xref{Environment}. |
| @end ifset |
| You can also define the input format from a script, using the command |
| @code{TARGET}; see @ref{Format Commands}. |
| @end ifclear |
| |
| @kindex -c @var{MRI-cmdfile} |
| @kindex --mri-script=@var{MRI-cmdfile} |
| @cindex compatibility, MRI |
| @item -c @var{MRI-commandfile} |
| @itemx --mri-script=@var{MRI-commandfile} |
| For compatibility with linkers produced by MRI, @code{ld} accepts script |
| files written in an alternate, restricted command language, described in |
| @ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with |
| the option @samp{-c}; use the @samp{-T} option to run linker |
| scripts written in the general-purpose @code{ld} scripting language. |
| If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories |
| specified by any @samp{-L} options. |
| |
| @cindex common allocation |
| @kindex -d |
| @kindex -dc |
| @kindex -dp |
| @item -d |
| @itemx -dc |
| @itemx -dp |
| These three options are equivalent; multiple forms are supported for |
| compatibility with other linkers. They assign space to common symbols |
| even if a relocatable output file is specified (with @samp{-r}). The |
| script command @code{FORCE_COMMON_ALLOCATION} has the same effect. |
| @xref{Miscellaneous Commands}. |
| |
| @cindex entry point, from command line |
| @kindex -e @var{entry} |
| @kindex --entry=@var{entry} |
| @item -e @var{entry} |
| @itemx --entry=@var{entry} |
| Use @var{entry} as the explicit symbol for beginning execution of your |
| program, rather than the default entry point. If there is no symbol |
| named @var{entry}, the linker will try to parse @var{entry} as a number, |
| and use that as the entry address (the number will be interpreted in |
| base 10; you may use a leading @samp{0x} for base 16, or a leading |
| @samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults |
| and other ways of specifying the entry point. |
| |
| @cindex dynamic symbol table |
| @kindex -E |
| @kindex --export-dynamic |
| @item -E |
| @itemx --export-dynamic |
| When creating a dynamically linked executable, add all symbols to the |
| dynamic symbol table. The dynamic symbol table is the set of symbols |
| which are visible from dynamic objects at run time. |
| |
| If you do not use this option, the dynamic symbol table will normally |
| contain only those symbols which are referenced by some dynamic object |
| mentioned in the link. |
| |
| If you use @code{dlopen} to load a dynamic object which needs to refer |
| back to the symbols defined by the program, rather than some other |
| dynamic object, then you will probably need to use this option when |
| linking the program itself. |
| |
| @cindex big-endian objects |
| @cindex endianness |
| @kindex -EB |
| @item -EB |
| Link big-endian objects. This affects the default output format. |
| |
| @cindex little-endian objects |
| @kindex -EL |
| @item -EL |
| Link little-endian objects. This affects the default output format. |
| |
| @kindex -f |
| @kindex --auxiliary |
| @item -f |
| @itemx --auxiliary @var{name} |
| When creating an ELF shared object, set the internal DT_AUXILIARY field |
| to the specified name. This tells the dynamic linker that the symbol |
| table of the shared object should be used as an auxiliary filter on the |
| symbol table of the shared object @var{name}. |
| |
| If you later link a program against this filter object, then, when you |
| run the program, the dynamic linker will see the DT_AUXILIARY field. If |
| the dynamic linker resolves any symbols from the filter object, it will |
| first check whether there is a definition in the shared object |
| @var{name}. If there is one, it will be used instead of the definition |
| in the filter object. The shared object @var{name} need not exist. |
| Thus the shared object @var{name} may be used to provide an alternative |
| implementation of certain functions, perhaps for debugging or for |
| machine specific performance. |
| |
| This option may be specified more than once. The DT_AUXILIARY entries |
| will be created in the order in which they appear on the command line. |
| |
| @kindex -F |
| @kindex --filter |
| @item -F @var{name} |
| @itemx --filter @var{name} |
| When creating an ELF shared object, set the internal DT_FILTER field to |
| the specified name. This tells the dynamic linker that the symbol table |
| of the shared object which is being created should be used as a filter |
| on the symbol table of the shared object @var{name}. |
| |
| If you later link a program against this filter object, then, when you |
| run the program, the dynamic linker will see the DT_FILTER field. The |
| dynamic linker will resolve symbols according to the symbol table of the |
| filter object as usual, but it will actually link to the definitions |
| found in the shared object @var{name}. Thus the filter object can be |
| used to select a subset of the symbols provided by the object |
| @var{name}. |
| |
| Some older linkers used the @code{-F} option throughout a compilation |
| toolchain for specifying object-file format for both input and output |
| object files. The @sc{gnu} linker uses other mechanisms for this |
| purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the |
| @code{TARGET} command in linker scripts, and the @code{GNUTARGET} |
| environment variable. The @sc{gnu} linker will ignore the @code{-F} |
| option when not creating an ELF shared object. |
| |
| @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. |
| |
| @kindex -O @var{level} |
| @cindex generating optimized output |
| @item -O @var{level} |
| If @var{level} is a numeric values greater than zero @code{ld} optimizes |
| the output. This might take significantly longer and therefore probably |
| should only be enabled for the final binary. |
| |
| @cindex partial link |
| @cindex relocatable output |
| @kindex -r |
| @kindex --relocateable |
| @item -r |
| @itemx --relocateable |
| Generate relocatable output---i.e., generate an output file that can in |
| turn serve as input to @code{ld}. This is often called @dfn{partial |
| linking}. As a side effect, in environments that support standard Unix |
| magic numbers, this option also sets the output file's magic number to |
| @code{OMAGIC}. |
| @c ; see @code{-N}. |
| If this option is not specified, an absolute file is produced. When |
| linking C++ programs, this option @emph{will not} resolve references to |
| constructors; to do that, use @samp{-Ur}. |
| |
| This option does the same thing as @samp{-i}. |
| |
| @kindex -R @var{file} |
| @kindex --just-symbols=@var{file} |
| @cindex symbol-only input |
| @item -R @var{filename} |
| @itemx --just-symbols=@var{filename} |
| Read symbol names and their addresses from @var{filename}, but do not |
| relocate it or include it in the output. This allows your output file |
| to refer symbolically to absolute locations of memory defined in other |
| programs. You may use this option more than once. |
| |
| For compatibility with other ELF linkers, if the @code{-R} option is |
| followed by a directory name, rather than a file name, it is treated as |
| the @code{-rpath} option. |
| |
| @kindex -s |
| @kindex --strip-all |
| @cindex strip all symbols |
| @item -s |
| @itemx --strip-all |
| Omit all symbol information from the output file. |
| |
| @kindex -S |
| @kindex --strip-debug |
| @cindex strip debugger symbols |
| @item -S |
| @itemx --strip-debug |
| Omit debugger symbol information (but not all symbols) from the output file. |
| |
| @kindex -t |
| @kindex --trace |
| @cindex input files, displaying |
| @item -t |
| @itemx --trace |
| Print the names of the input files as @code{ld} processes them. |
| |
| @kindex -T @var{script} |
| @kindex --script=@var{script} |
| @cindex script files |
| @item -T @var{scriptfile} |
| @itemx --script=@var{scriptfile} |
| Use @var{scriptfile} as the linker script. This script replaces |
| @code{ld}'s default linker script (rather than adding to it), so |
| @var{commandfile} must specify everything necessary to describe the |
| output file. You must use this option if you want to use a command |
| which can only appear once in a linker script, such as the |
| @code{SECTIONS} or @code{MEMORY} command. @xref{Scripts}. If |
| @var{scriptfile} does not exist in the current directory, @code{ld} |
| looks for it in the directories specified by any preceding @samp{-L} |
| options. Multiple @samp{-T} options accumulate. |
| |
| @kindex -u @var{symbol} |
| @kindex --undefined=@var{symbol} |
| @cindex undefined symbol |
| @item -u @var{symbol} |
| @itemx --undefined=@var{symbol} |
| Force @var{symbol} to be entered in the output file as an undefined |
| symbol. Doing this may, for example, trigger linking of additional |
| modules from standard libraries. @samp{-u} may be repeated with |
| different option arguments to enter additional undefined symbols. This |
| option is equivalent to the @code{EXTERN} linker script command. |
| |
| @kindex -Ur |
| @cindex constructors |
| @item -Ur |
| For anything other than C++ programs, this option is equivalent to |
| @samp{-r}: it generates relocatable output---i.e., an output file that can in |
| turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur} |
| @emph{does} resolve references to constructors, unlike @samp{-r}. |
| It does not work to use @samp{-Ur} on files that were themselves linked |
| with @samp{-Ur}; once the constructor table has been built, it cannot |
| be added to. Use @samp{-Ur} only for the last partial link, and |
| @samp{-r} for the others. |
| |
| @kindex -v |
| @kindex -V |
| @kindex --version |
| @cindex version |
| @item -v |
| @itemx --version |
| @itemx -V |
| Display the version number for @code{ld}. The @code{-V} option also |
| lists the supported emulations. |
| |
| @kindex -x |
| @kindex --discard-all |
| @cindex deleting local symbols |
| @item -x |
| @itemx --discard-all |
| Delete all local symbols. |
| |
| @kindex -X |
| @kindex --discard-locals |
| @cindex local symbols, deleting |
| @cindex L, deleting symbols beginning |
| @item -X |
| @itemx --discard-locals |
| Delete all temporary local symbols. For most targets, this is all local |
| symbols whose names begin with @samp{L}. |
| |
| @kindex -y @var{symbol} |
| @kindex --trace-symbol=@var{symbol} |
| @cindex symbol tracing |
| @item -y @var{symbol} |
| @itemx --trace-symbol=@var{symbol} |
| Print the name of each linked file in which @var{symbol} appears. This |
| option may be given any number of times. On many systems it is necessary |
| to prepend an underscore. |
| |
| This option is useful when you have an undefined symbol in your link but |
| don't know where the reference is coming from. |
| |
| @kindex -Y @var{path} |
| @item -Y @var{path} |
| Add @var{path} to the default library search path. This option exists |
| for Solaris compatibility. |
| |
| @kindex -z @var{keyword} |
| @item -z @var{keyword} |
| This option is ignored for Solaris compatibility. |
| |
| @kindex -( |
| @cindex groups of archives |
| @item -( @var{archives} -) |
| @itemx --start-group @var{archives} --end-group |
| The @var{archives} should be a list of archive files. They may be |
| either explicit file names, or @samp{-l} options. |
| |
| The specified archives are searched repeatedly until no new undefined |
| references are created. Normally, an archive is searched only once in |
| the order that it is specified on the command line. If a symbol in that |
| archive is needed to resolve an undefined symbol referred to by an |
| object in an archive that appears later on the command line, the linker |
| would not be able to resolve that reference. By grouping the archives, |
| they all be searched repeatedly until all possible references are |
| resolved. |
| |
| Using this option has a significant performance cost. It is best to use |
| it only when there are unavoidable circular references between two or |
| more archives. |
| |
| @kindex -assert @var{keyword} |
| @item -assert @var{keyword} |
| This option is ignored for SunOS compatibility. |
| |
| @kindex -Bdynamic |
| @kindex -dy |
| @kindex -call_shared |
| @item -Bdynamic |
| @itemx -dy |
| @itemx -call_shared |
| Link against dynamic libraries. This is only meaningful on platforms |
| for which shared libraries are supported. This option is normally the |
| default on such platforms. The different variants of this option are |
| for compatibility with various systems. You may use this option |
| multiple times on the command line: it affects library searching for |
| @code{-l} options which follow it. |
| |
| @kindex -Bstatic |
| @kindex -dn |
| @kindex -non_shared |
| @kindex -static |
| @item -Bstatic |
| @itemx -dn |
| @itemx -non_shared |
| @itemx -static |
| Do not link against shared libraries. This is only meaningful on |
| platforms for which shared libraries are supported. The different |
| variants of this option are for compatibility with various systems. You |
| may use this option multiple times on the command line: it affects |
| library searching for @code{-l} options which follow it. |
| |
| @kindex -Bsymbolic |
| @item -Bsymbolic |
| When creating a shared library, bind references to global symbols to the |
| definition within the shared library, if any. Normally, it is possible |
| for a program linked against a shared library to override the definition |
| within the shared library. This option is only meaningful on ELF |
| platforms which support shared libraries. |
| |
| @kindex --check-sections |
| @kindex --no-check-sections |
| @item --check-sections |
| @item --no-check-sections |
| Asks the linker @emph{not} to check section addresses after they have |
| been assigned to see if there any overlaps. Normally the linker will |
| perform this check, and if it finds any overlaps it will produce |
| suitable error messages. The linker does know about, and does make |
| allowances for sections in overlays. The default behaviour can be |
| restored by using the command line switch @samp{--check-sections}. |
| |
| @cindex cross reference table |
| @kindex --cref |
| @item --cref |
| Output a cross reference table. If a linker map file is being |
| generated, the cross reference table is printed to the map file. |
| Otherwise, it is printed on the standard output. |
| |
| The format of the table is intentionally simple, so that it may be |
| easily processed by a script if necessary. The symbols are printed out, |
| sorted by name. For each symbol, a list of file names is given. If the |
| symbol is defined, the first file listed is the location of the |
| definition. The remaining files contain references to the symbol. |
| |
| @cindex symbols, from command line |
| @kindex --defsym @var{symbol}=@var{exp} |
| @item --defsym @var{symbol}=@var{expression} |
| Create a global symbol in the output file, containing the absolute |
| address given by @var{expression}. You may use this option as many |
| times as necessary to define multiple symbols in the command line. A |
| limited form of arithmetic is supported for the @var{expression} in this |
| context: you may give a hexadecimal constant or the name of an existing |
| symbol, or use @code{+} and @code{-} to add or subtract hexadecimal |
| constants or symbols. If you need more elaborate expressions, consider |
| using the linker command language from a script (@pxref{Assignments,, |
| Assignment: Symbol Definitions}). @emph{Note:} there should be no white |
| space between @var{symbol}, the equals sign (``@key{=}''), and |
| @var{expression}. |
| |
| @cindex demangling, from command line |
| @kindex --demangle |
| @kindex --no-demangle |
| @item --demangle |
| @itemx --no-demangle |
| These options control whether to demangle symbol names in error messages |
| and other output. When the linker is told to demangle, it tries to |
| present symbol names in a readable fashion: it strips leading |
| underscores if they are used by the object file format, and converts C++ |
| mangled symbol names into user readable names. The linker will demangle |
| by default unless the environment variable @samp{COLLECT_NO_DEMANGLE} is |
| set. These options may be used to override the default. |
| |
| @cindex dynamic linker, from command line |
| @kindex --dynamic-linker @var{file} |
| @item --dynamic-linker @var{file} |
| Set the name of the dynamic linker. This is only meaningful when |
| generating dynamically linked ELF executables. The default dynamic |
| linker is normally correct; don't use this unless you know what you are |
| doing. |
| |
| @cindex MIPS embedded PIC code |
| @kindex --embedded-relocs |
| @item --embedded-relocs |
| This option is only meaningful when linking MIPS embedded PIC code, |
| generated by the -membedded-pic option to the @sc{gnu} compiler and |
| assembler. It causes the linker to create a table which may be used at |
| runtime to relocate any data which was statically initialized to pointer |
| values. See the code in testsuite/ld-empic for details. |
| |
| @kindex --force-exe-suffix |
| @item --force-exe-suffix |
| Make sure that an output file has a .exe suffix. |
| |
| If a successfully built fully linked output file does not have a |
| @code{.exe} or @code{.dll} suffix, this option forces the linker to copy |
| the output file to one of the same name with a @code{.exe} suffix. This |
| option is useful when using unmodified Unix makefiles on a Microsoft |
| Windows host, since some versions of Windows won't run an image unless |
| it ends in a @code{.exe} suffix. |
| |
| @kindex --gc-sections |
| @kindex --no-gc-sections |
| @cindex garbage collection |
| @item --no-gc-sections |
| @itemx --gc-sections |
| Enable garbage collection of unused input sections. It is ignored on |
| targets that do not support this option. This option is not compatible |
| with @samp{-r}, nor should it be used with dynamic linking. The default |
| behaviour (of not performing this garbage collection) can be restored by |
| specifying @samp{--no-gc-sections} on the command line. |
| |
| @cindex help |
| @cindex usage |
| @kindex --help |
| @item --help |
| Print a summary of the command-line options on the standard output and exit. |
| |
| @kindex -Map |
| @item -Map @var{mapfile} |
| Print a link map to the file @var{mapfile}. See the description of the |
| @samp{-M} option, above. |
| |
| @cindex memory usage |
| @kindex --no-keep-memory |
| @item --no-keep-memory |
| @code{ld} normally optimizes for speed over memory usage by caching the |
| symbol tables of input files in memory. This option tells @code{ld} to |
| instead optimize for memory usage, by rereading the symbol tables as |
| necessary. This may be required if @code{ld} runs out of memory space |
| while linking a large executable. |
| |
| @kindex --no-undefined |
| @item --no-undefined |
| Normally when creating a non-symbolic shared library, undefined symbols |
| are allowed and left to be resolved by the runtime loader. This option |
| disallows such undefined symbols. |
| |
| @kindex --no-warn-mismatch |
| @item --no-warn-mismatch |
| Normally @code{ld} will give an error if you try to link together input |
| files that are mismatched for some reason, perhaps because they have |
| been compiled for different processors or for different endiannesses. |
| This option tells @code{ld} that it should silently permit such possible |
| errors. This option should only be used with care, in cases when you |
| have taken some special action that ensures that the linker errors are |
| inappropriate. |
| |
| @kindex --no-whole-archive |
| @item --no-whole-archive |
| Turn off the effect of the @code{--whole-archive} option for subsequent |
| archive files. |
| |
| @cindex output file after errors |
| @kindex --noinhibit-exec |
| @item --noinhibit-exec |
| Retain the executable output file whenever it is still usable. |
| Normally, the linker will not produce an output file if it encounters |
| errors during the link process; it exits without writing an output file |
| when it issues any error whatsoever. |
| |
| @ifclear SingleFormat |
| @kindex --oformat |
| @item --oformat @var{output-format} |
| @code{ld} may be configured to support more than one kind of object |
| file. If your @code{ld} is configured this way, you can use the |
| @samp{--oformat} option to specify the binary format for the output |
| object file. Even when @code{ld} is configured to support alternative |
| object formats, you don't usually need to specify this, as @code{ld} |
| should be configured to produce as a default output format the most |
| usual format on each machine. @var{output-format} is a text string, the |
| name of a particular format supported by the BFD libraries. (You can |
| list the available binary formats with @samp{objdump -i}.) The script |
| command @code{OUTPUT_FORMAT} can also specify the output format, but |
| this option overrides it. @xref{BFD}. |
| @end ifclear |
| |
| @kindex -qmagic |
| @item -qmagic |
| This option is ignored for Linux compatibility. |
| |
| @kindex -Qy |
| @item -Qy |
| This option is ignored for SVR4 compatibility. |
| |
| @kindex --relax |
| @cindex synthesizing linker |
| @cindex relaxing addressing modes |
| @item --relax |
| An option with machine dependent effects. |
| @ifset GENERIC |
| This option is only supported on a few targets. |
| @end ifset |
| @ifset H8300 |
| @xref{H8/300,,@code{ld} and the H8/300}. |
| @end ifset |
| @ifset I960 |
| @xref{i960,, @code{ld} and the Intel 960 family}. |
| @end ifset |
| |
| |
| On some platforms, the @samp{--relax} option performs global |
| optimizations that become possible when the linker resolves addressing |
| in the program, such as relaxing address modes and synthesizing new |
| instructions in the output object file. |
| |
| On some platforms these link time global optimizations may make symbolic |
| debugging of the resulting executable impossible. |
| @ifset GENERIC |
| This is known to be |
| the case for the Matsushita MN10200 and MN10300 family of processors. |
| @end ifset |
| |
| @ifset GENERIC |
| On platforms where this is not supported, @samp{--relax} is accepted, |
| but ignored. |
| @end ifset |
| |
| @cindex retaining specified symbols |
| @cindex stripping all but some symbols |
| @cindex symbols, retaining selectively |
| @item --retain-symbols-file @var{filename} |
| Retain @emph{only} the symbols listed in the file @var{filename}, |
| discarding all others. @var{filename} is simply a flat file, with one |
| symbol name per line. This option is especially useful in environments |
| @ifset GENERIC |
| (such as VxWorks) |
| @end ifset |
| where a large global symbol table is accumulated gradually, to conserve |
| run-time memory. |
| |
| @samp{--retain-symbols-file} does @emph{not} discard undefined symbols, |
| or symbols needed for relocations. |
| |
| You may only specify @samp{--retain-symbols-file} once in the command |
| line. It overrides @samp{-s} and @samp{-S}. |
| |
| @ifset GENERIC |
| @item -rpath @var{dir} |
| @cindex runtime library search path |
| @kindex -rpath |
| Add a directory to the runtime library search path. This is used when |
| linking an ELF executable with shared objects. All @code{-rpath} |
| arguments are concatenated and passed to the runtime linker, which uses |
| them to locate shared objects at runtime. The @code{-rpath} option is |
| also used when locating shared objects which are needed by shared |
| objects explicitly included in the link; see the description of the |
| @code{-rpath-link} option. If @code{-rpath} is not used when linking an |
| ELF executable, the contents of the environment variable |
| @code{LD_RUN_PATH} will be used if it is defined. |
| |
| The @code{-rpath} option may also be used on SunOS. By default, on |
| SunOS, the linker will form a runtime search patch out of all the |
| @code{-L} options it is given. If a @code{-rpath} option is used, the |
| runtime search path will be formed exclusively using the @code{-rpath} |
| options, ignoring the @code{-L} options. This can be useful when using |
| gcc, which adds many @code{-L} options which may be on NFS mounted |
| filesystems. |
| |
| For compatibility with other ELF linkers, if the @code{-R} option is |
| followed by a directory name, rather than a file name, it is treated as |
| the @code{-rpath} option. |
| @end ifset |
| |
| @ifset GENERIC |
| @cindex link-time runtime library search path |
| @kindex -rpath-link |
| @item -rpath-link @var{DIR} |
| When using ELF or SunOS, one shared library may require another. This |
| happens when an @code{ld -shared} link includes a shared library as one |
| of the input files. |
| |
| When the linker encounters such a dependency when doing a non-shared, |
| non-relocatable link, it will automatically try to locate the required |
| shared library and include it in the link, if it is not included |
| explicitly. In such a case, the @code{-rpath-link} option |
| specifies the first set of directories to search. The |
| @code{-rpath-link} option may specify a sequence of directory names |
| either by specifying a list of names separated by colons, or by |
| appearing multiple times. |
| |
| The linker uses the following search paths to locate required shared |
| libraries. |
| @enumerate |
| @item |
| Any directories specified by @code{-rpath-link} options. |
| @item |
| Any directories specified by @code{-rpath} options. The difference |
| between @code{-rpath} and @code{-rpath-link} is that directories |
| specified by @code{-rpath} options are included in the executable and |
| used at runtime, whereas the @code{-rpath-link} option is only effective |
| at link time. |
| @item |
| On an ELF system, if the @code{-rpath} and @code{rpath-link} options |
| were not used, search the contents of the environment variable |
| @code{LD_RUN_PATH}. |
| @item |
| On SunOS, if the @code{-rpath} option was not used, search any |
| directories specified using @code{-L} options. |
| @item |
| For a native linker, the contents of the environment variable |
| @code{LD_LIBRARY_PATH}. |
| @item |
| The default directories, normally @file{/lib} and @file{/usr/lib}. |
| @item |
| For a native linker on an ELF system, if the file @file{/etc/ld.so.conf} |
| exists, the list of directories found in that file. |
| @end enumerate |
| |
| If the required shared library is not found, the linker will issue a |
| warning and continue with the link. |
| @end ifset |
| |
| @kindex -shared |
| @kindex -Bshareable |
| @item -shared |
| @itemx -Bshareable |
| @cindex shared libraries |
| Create a shared library. This is currently only supported on ELF, XCOFF |
| and SunOS platforms. On SunOS, the linker will automatically create a |
| shared library if the @code{-e} option is not used and there are |
| undefined symbols in the link. |
| |
| @item --sort-common |
| @kindex --sort-common |
| This option tells @code{ld} to sort the common symbols by size when it |
| places them in the appropriate output sections. First come all the one |
| byte symbols, then all the two bytes, then all the four bytes, and then |
| everything else. This is to prevent gaps between symbols due to |
| alignment constraints. |
| |
| @kindex --split-by-file |
| @item --split-by-file |
| Similar to @code{--split-by-reloc} but creates a new output section for |
| each input file. |
| |
| @kindex --split-by-reloc |
| @item --split-by-reloc @var{count} |
| Trys to creates extra sections in the output file so that no single |
| output section in the file contains more than @var{count} relocations. |
| This is useful when generating huge relocatable for downloading into |
| certain real time kernels with the COFF object file format; since COFF |
| cannot represent more than 65535 relocations in a single section. Note |
| that this will fail to work with object file formats which do not |
| support arbitrary sections. The linker will not split up individual |
| input sections for redistribution, so if a single input section contains |
| more than @var{count} relocations one output section will contain that |
| many relocations. |
| |
| @kindex --stats |
| @item --stats |
| Compute and display statistics about the operation of the linker, such |
| as execution time and memory usage. |
| |
| @kindex --traditional-format |
| @cindex traditional format |
| @item --traditional-format |
| For some targets, the output of @code{ld} is different in some ways from |
| the output of some existing linker. This switch requests @code{ld} to |
| use the traditional format instead. |
| |
| @cindex dbx |
| For example, on SunOS, @code{ld} combines duplicate entries in the |
| symbol string table. This can reduce the size of an output file with |
| full debugging information by over 30 percent. Unfortunately, the SunOS |
| @code{dbx} program can not read the resulting program (@code{gdb} has no |
| trouble). The @samp{--traditional-format} switch tells @code{ld} to not |
| combine duplicate entries. |
| |
| @kindex -Tbss @var{org} |
| @kindex -Tdata @var{org} |
| @kindex -Ttext @var{org} |
| @cindex segment origins, cmd line |
| @item -Tbss @var{org} |
| @itemx -Tdata @var{org} |
| @itemx -Ttext @var{org} |
| Use @var{org} as the starting address for---respectively---the |
| @code{bss}, @code{data}, or the @code{text} segment of the output file. |
| @var{org} must be a single hexadecimal integer; |
| for compatibility with other linkers, you may omit the leading |
| @samp{0x} usually associated with hexadecimal values. |
| |
| @kindex --verbose |
| @cindex verbose |
| @item --dll-verbose |
| @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}. |
| |
| @kindex --warn-comon |
| @cindex warnings, on combining symbols |
| @cindex combining symbols, warnings on |
| @item --warn-common |
| Warn when a common symbol is combined with another common symbol or with |
| a symbol definition. Unix linkers allow this somewhat sloppy practice, |
| but linkers on some other operating systems do not. This option allows |
| you to find potential problems from combining global symbols. |
| Unfortunately, some C libraries use this practice, so you may get some |
| warnings about symbols in the libraries as well as in your programs. |
| |
| There are three kinds of global symbols, illustrated here by C examples: |
| |
| @table @samp |
| @item int i = 1; |
| A definition, which goes in the initialized data section of the output |
| file. |
| |
| @item extern int i; |
| An undefined reference, which does not allocate space. |
| There must be either a definition or a common symbol for the |
| variable somewhere. |
| |
| @item int i; |
| A common symbol. If there are only (one or more) common symbols for a |
| variable, it goes in the uninitialized data area of the output file. |
| The linker merges multiple common symbols for the same variable into a |
| single symbol. If they are of different sizes, it picks the largest |
| size. The linker turns a common symbol into a declaration, if there is |
| a definition of the same variable. |
| @end table |
| |
| The @samp{--warn-common} option can produce five kinds of warnings. |
| Each warning consists of a pair of lines: the first describes the symbol |
| just encountered, and the second describes the previous symbol |
| encountered with the same name. One or both of the two symbols will be |
| a common symbol. |
| |
| @enumerate |
| @item |
| Turning a common symbol into a reference, because there is already a |
| definition for the symbol. |
| @smallexample |
| @var{file}(@var{section}): warning: common of `@var{symbol}' |
| overridden by definition |
| @var{file}(@var{section}): warning: defined here |
| @end smallexample |
| |
| @item |
| Turning a common symbol into a reference, because a later definition for |
| the symbol is encountered. This is the same as the previous case, |
| except that the symbols are encountered in a different order. |
| @smallexample |
| @var{file}(@var{section}): warning: definition of `@var{symbol}' |
| overriding common |
| @var{file}(@var{section}): warning: common is here |
| @end smallexample |
| |
| @item |
| Merging a common symbol with a previous same-sized common symbol. |
| @smallexample |
| @var{file}(@var{section}): warning: multiple common |
| of `@var{symbol}' |
| @var{file}(@var{section}): warning: previous common is here |
| @end smallexample |
| |
| @item |
| Merging a common symbol with a previous larger common symbol. |
| @smallexample |
| @var{file}(@var{section}): warning: common of `@var{symbol}' |
| overridden by larger common |
| @var{file}(@var{section}): warning: larger common is here |
| @end smallexample |
| |
| @item |
| Merging a common symbol with a previous smaller common symbol. This is |
| the same as the previous case, except that the symbols are |
| encountered in a different order. |
| @smallexample |
| @var{file}(@var{section}): warning: common of `@var{symbol}' |
| overriding smaller common |
| @var{file}(@var{section}): warning: smaller common is here |
| @end smallexample |
| @end enumerate |
| |
| @kindex --warn-constructors |
| @item --warn-constructors |
| Warn if any global constructors are used. This is only useful for a few |
| object file formats. For formats like COFF or ELF, the linker can not |
| detect the use of global constructors. |
| |
| @kindex --warn-multiple-gp |
| @item --warn-multiple-gp |
| Warn if multiple global pointer values are required in the output file. |
| This is only meaningful for certain processors, such as the Alpha. |
| Specifically, some processors put large-valued constants in a special |
| section. A special register (the global pointer) points into the middle |
| of this section, so that constants can be loaded efficiently via a |
| base-register relative addressing mode. Since the offset in |
| base-register relative mode is fixed and relatively small (e.g., 16 |
| bits), this limits the maximum size of the constant pool. Thus, in |
| large programs, it is often necessary to use multiple global pointer |
| values in order to be able to address all possible constants. This |
| option causes a warning to be issued whenever this case occurs. |
| |
| @kindex --warn-once |
| @cindex warnings, on undefined symbols |
| @cindex undefined symbols, warnings on |
| @item --warn-once |
| Only warn once for each undefined symbol, rather than once per module |
| which refers to it. |
| |
| @kindex --warn-section-align |
| @cindex warnings, on section alignment |
| @cindex section alignment, warnings on |
| @item --warn-section-align |
| Warn if the address of an output section is changed because of |
| alignment. Typically, the alignment will be set by an input section. |
| The address will only be changed if it not explicitly specified; that |
| is, if the @code{SECTIONS} command does not specify a start address for |
| the section (@pxref{SECTIONS}). |
| |
| @kindex --whole-archive |
| @cindex including an entire archive |
| @item --whole-archive |
| For each archive mentioned on the command line after the |
| @code{--whole-archive} option, include every object file in the archive |
| in the link, rather than searching the archive for the required object |
| files. This is normally used to turn an archive file into a shared |
| library, forcing every object to be included in the resulting shared |
| library. This option may be used more than once. |
| |
| @kindex --wrap |
| @item --wrap @var{symbol} |
| Use a wrapper function for @var{symbol}. Any undefined reference to |
| @var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any |
| undefined reference to @code{__real_@var{symbol}} will be resolved to |
| @var{symbol}. |
| |
| This can be used to provide a wrapper for a system function. The |
| wrapper function should be called @code{__wrap_@var{symbol}}. If it |
| wishes to call the system function, it should call |
| @code{__real_@var{symbol}}. |
| |
| Here is a trivial example: |
| |
| @smallexample |
| void * |
| __wrap_malloc (int c) |
| @{ |
| printf ("malloc called with %ld\n", c); |
| return __real_malloc (c); |
| @} |
| @end smallexample |
| |
| If you link other code with this file using @code{--wrap malloc}, then |
| all calls to @code{malloc} will call the function @code{__wrap_malloc} |
| instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will |
| call the real @code{malloc} function. |
| |
| You may wish to provide a @code{__real_malloc} function as well, so that |
| links without the @code{--wrap} option will succeed. If you do this, |
| you should not put the definition of @code{__real_malloc} in the same |
| file as @code{__wrap_malloc}; if you do, the assembler may resolve the |
| call before the linker has a chance to wrap it to @code{malloc}. |
| |
| @end table |
| |
| @subsection Options specific to i386 PE targets |
| |
| The i386 PE linker supports the @code{-shared} option, which causes |
| the output to be a dynamically linked library (DLL) instead of a |
| normal executable. You should name the output @code{*.dll} when you |
| use this option. In addition, the linker fully supports the standard |
| @code{*.def} files, which may be specified on the linker command line |
| like an object file (in fact, it should precede archives it exports |
| symbols from, to ensure that they get linked in, just like a normal |
| object file). |
| |
| In addition to the options common to all targets, the i386 PE linker |
| support additional command line options that are specific to the i386 |
| PE target. Options that take values may be separated from their |
| values by either a space or an equals sign. |
| |
| @table @code |
| |
| @kindex --add-stdcall-alias |
| @item --add-stdcall-alias |
| If given, symbols with a stdcall suffix (@@@var{nn}) will be exported |
| as-is and also with the suffix stripped. |
| |
| @kindex --base-file |
| @item --base-file @var{file} |
| Use @var{file} as the name of a file in which to save the base |
| addresses of all the relocations needed for generating DLLs with |
| @file{dlltool}. |
| |
| @kindex --dll |
| @item --dll |
| Create a DLL instead of a regular executable. You may also use |
| @code{-shared} or specify a @code{LIBRARY} in a given @code{.def} |
| file. |
| |
| @kindex --enable-stdcall-fixup |
| @kindex --disable-stdcall-fixup |
| @item --enable-stdcall-fixup |
| @itemx --disable-stdcall-fixup |
| If the link finds a symbol that it cannot resolve, it will attempt to |
| do "fuzzy linking" by looking for another defined symbol that differs |
| only in the format of the symbol name (cdecl vs stdcall) and will |
| resolve that symbol by linking to the match. For example, the |
| undefined symbol @code{_foo} might be linked to the function |
| @code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked |
| to the function @code{_bar}. When the linker does this, it prints a |
| warning, since it normally should have failed to link, but sometimes |
| import libraries generated from third-party dlls may need this feature |
| to be usable. If you specify @code{--enable-stdcall-fixup}, this |
| feature is fully enabled and warnings are not printed. If you specify |
| @code{--disable-stdcall-fixup}, this feature is disabled and such |
| mismatches are considered to be errors. |
| |
| @cindex DLLs, creating |
| @kindex --export-all-symbols |
| @item --export-all-symbols |
| If given, all global symbols in the objects used to build a DLL will |
| be exported by the DLL. Note that this is the default if there |
| otherwise wouldn't be any exported symbols. When symbols are |
| explicitly exported via DEF files or implicitly exported via function |
| attributes, the default is to not export anything else unless this |
| option is given. Note that the symbols @code{DllMain@@12}, |
| @code{DllEntryPoint@@0}, and @code{impure_ptr} will not be automatically |
| exported. |
| |
| @kindex --exclude-symbols |
| @item --exclude-symbols @var{symbol,symbol,...} |
| Specifies a list of symbols which should not be automatically |
| exported. The symbol names may be delimited by commas or colons. |
| |
| @kindex --file-alignment |
| @item --file-alignment |
| Specify the file alignment. Sections in the file will always begin at |
| file offsets which are multiples of this number. This defaults to |
| 512. |
| |
| @cindex heap size |
| @kindex --heap |
| @item --heap @var{reserve} |
| @itemx --heap @var{reserve},@var{commit} |
| Specify the amount of memory to reserve (and optionally commit) to be |
| used as heap for this program. The default is 1Mb reserved, 4K |
| committed. |
| |
| @cindex image base |
| @kindex --image-base |
| @item --image-base @var{value} |
| Use @var{value} as the base address of your program or dll. This is |
| the lowest memory location that will be used when your program or dll |
| is loaded. To reduce the need to relocate and improve performance of |
| your dlls, each should have a unique base address and not overlap any |
| other dlls. The default is 0x400000 for executables, and 0x10000000 |
| for dlls. |
| |
| @kindex --kill-at |
| @item --kill-at |
| If given, the stdcall suffixes (@@@var{nn}) will be stripped from |
| symbols before they are exported. |
| |
| @kindex --major-image-version |
| @item --major-image-version @var{value} |
| Sets the major number of the "image version". Defaults to 1. |
| |
| @kindex --major-os-version |
| @item --major-os-version @var{value} |
| Sets the major number of the "os version". Defaults to 4. |
| |
| @kindex --major-subsystem-version |
| @item --major-subsystem-version @var{value} |
| Sets the major number of the "subsystem version". Defaults to 4. |
| |
| @kindex --minor-image-version |
| @item --minor-image-version @var{value} |
| Sets the minor number of the "image version". Defaults to 0. |
| |
| @kindex --minor-os-version |
| @item --minor-os-version @var{value} |
| Sets the minor number of the "os version". Defaults to 0. |
| |
| @kindex --minor-subsystem-version |
| @item --minor-subsystem-version @var{value} |
| Sets the minor number of the "subsystem version". Defaults to 0. |
| |
| @cindex DEF files, creating |
| @cindex DLLs, creating |
| @kindex --output-def |
| @item --output-def @var{file} |
| The linker will create the file @var{file} which will contain a DEF |
| file corresponding to the DLL the linker is generating. This DEF file |
| (which should be called @code{*.def}) may be used to create an import |
| library with @code{dlltool} or may be used as a reference to |
| automatically or implicitly exported symbols. |
| |
| @kindex --section-alignment |
| @item --section-alignment |
| Sets the section alignment. Sections in memory will always begin at |
| addresses which are a multiple of this number. Defaults to 0x1000. |
| |
| @cindex stack size |
| @kindex --stack |
| @item --stack @var{reserve} |
| @itemx --stack @var{reserve},@var{commit} |
| Specify the amount of memory to reserve (and optionally commit) to be |
| used as stack for this program. The default is 32Mb reserved, 4K |
| committed. |
| |
| @kindex --subsystem |
| @item --subsystem @var{which} |
| @itemx --subsystem @var{which}:@var{major} |
| @itemx --subsystem @var{which}:@var{major}.@var{minor} |
| Specifies the subsystem under which your program will execute. The |
| legal values for @var{which} are @code{native}, @code{windows}, |
| @code{console}, and @code{posix}. You may optionally set the |
| subsystem version also. |
| |
| @end table |
| |
| @ifset UsesEnvVars |
| @node Environment |
| @section Environment Variables |
| |
| You can change the behavior of @code{ld} with the environment variables |
| @code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}. |
| |
| @kindex GNUTARGET |
| @cindex default input format |
| @code{GNUTARGET} determines the input-file object format if you don't |
| use @samp{-b} (or its synonym @samp{--format}). Its value should be one |
| of the BFD names for an input format (@pxref{BFD}). If there is no |
| @code{GNUTARGET} in the environment, @code{ld} uses the natural format |
| of the target. If @code{GNUTARGET} is set to @code{default} then BFD |
| attempts to discover the input format by examining binary input files; |
| this method often succeeds, but there are potential ambiguities, since |
| there is no method of ensuring that the magic number used to specify |
| object-file formats is unique. However, the configuration procedure for |
| BFD on each system places the conventional format for that system first |
| in the search-list, so ambiguities are resolved in favor of convention. |
| |
| @kindex LDEMULATION |
| @cindex default emulation |
| @cindex emulation, default |
| @code{LDEMULATION} determines the default emulation if you don't use the |
| @samp{-m} option. The emulation can affect various aspects of linker |
| behaviour, particularly the default linker script. You can list the |
| available emulations with the @samp{--verbose} or @samp{-V} options. If |
| the @samp{-m} option is not used, and the @code{LDEMULATION} environment |
| variable is not defined, the default emulation depends upon how the |
| linker was configured. |
| @end ifset |
| |
| @kindex COLLECT_NO_DEMANGLE |
| @cindex demangling, default |
| Normally, the linker will default to demangling symbols. However, if |
| @code{COLLECT_NO_DEMANGLE} is set in the environment, then it will |
| default to not demangling symbols. This environment variable is used in |
| a similar fashion by the @code{gcc} linker wrapper program. The default |
| may be overridden by the @samp{--demangle} and @samp{--no-demangle} |
| options. |
| |
| @node Scripts |
| @chapter Linker Scripts |
| |
| @cindex scripts |
| @cindex linker scripts |
| @cindex command files |
| Every link is controlled by a @dfn{linker script}. This script is |
| written in the linker command language. |
| |
| The main purpose of the linker script is to describe how the sections in |
| the input files should be mapped into the output file, and to control |
| the memory layout of the output file. Most linker scripts do nothing |
| more than this. However, when necessary, the linker script can also |
| direct the linker to perform many other operations, using the commands |
| described below. |
| |
| The linker always uses a linker script. If you do not supply one |
| yourself, the linker will use a default script that is compiled into the |
| linker executable. You can use the @samp{--verbose} command line option |
| to display the default linker script. Certain command line options, |
| such as @samp{-r} or @samp{-N}, will affect the default linker script. |
| |
| You may supply your own linker script by using the @samp{-T} command |
| line option. When you do this, your linker script will replace the |
| default linker script. |
| |
| You may also use linker scripts implicitly by naming them as input files |
| to the linker, as though they were files to be linked. @xref{Implicit |
| Linker Scripts}. |
| |
| @menu |
| * Basic Script Concepts:: Basic Linker Script Concepts |
| * Script Format:: Linker Script Format |
| * Simple Example:: Simple Linker Script Example |
| * Simple Commands:: Simple Linker Script Commands |
| * Assignments:: Assigning Values to Symbols |
| * SECTIONS:: SECTIONS Command |
| * MEMORY:: MEMORY Command |
| * PHDRS:: PHDRS Command |
| * VERSION:: VERSION Command |
| * Expressions:: Expressions in Linker Scripts |
| * Implicit Linker Scripts:: Implicit Linker Scripts |
| @end menu |
| |
| @node Basic Script Concepts |
| @section Basic Linker Script Concepts |
| @cindex linker script concepts |
| We need to define some basic concepts and vocabulary in order to |
| describe the linker script language. |
| |
| The linker combines input files into a single output file. The output |
| file and each input file are in a special data format known as an |
| @dfn{object file format}. Each file is called an @dfn{object file}. |
| The output file is often called an @dfn{executable}, but for our |
| purposes we will also call it an object file. Each object file has, |
| among other things, a list of @dfn{sections}. We sometimes refer to a |
| section in an input file as an @dfn{input section}; similarly, a section |
| in the output file is an @dfn{output section}. |
| |
| Each section in an object file has a name and a size. Most sections |
| also have an associated block of data, known as the @dfn{section |
| contents}. A section may be marked as @dfn{loadable}, which mean that |
| the contents should be loaded into memory when the output file is run. |
| A section with no contents may be @dfn{allocatable}, which means that an |
| area in memory should be set aside, but nothing in particular should be |
| loaded there (in some cases this memory must be zeroed out). A section |
| which is neither loadable nor allocatable typically contains some sort |
| of debugging information. |
| |
| Every loadable or allocatable output section has two addresses. The |
| first is the @dfn{VMA}, or virtual memory address. This is the address |
| the section will have when the output file is run. The second is the |
| @dfn{LMA}, or load memory address. This is the address at which the |
| section will be loaded. In most cases the two addresses will be the |
| same. An example of when they might be different is when a data section |
| is loaded into ROM, and then copied into RAM when the program starts up |
| (this technique is often used to initialize global variables in a ROM |
| based system). In this case the ROM address would be the LMA, and the |
| RAM address would be the VMA. |
| |
| You can see the sections in an object file by using the @code{objdump} |
| program with the @samp{-h} option. |
| |
| Every object file also has a list of @dfn{symbols}, known as the |
| @dfn{symbol table}. A symbol may be defined or undefined. Each symbol |
| has a name, and each defined symbol has an address, among other |
| information. If you compile a C or C++ program into an object file, you |
| will get a defined symbol for every defined function and global or |
| static variable. Every undefined function or global variable which is |
| referenced in the input file will become an undefined symbol. |
| |
| You can see the symbols in an object file by using the @code{nm} |
| program, or by using the @code{objdump} program with the @samp{-t} |
| option. |
| |
| @node Script Format |
| @section Linker Script Format |
| @cindex linker script format |
| Linker scripts are text files. |
| |
| You write a linker script as a series of commands. Each command is |
| either a keyword, possibly followed by arguments, or an assignment to a |
| symbol. You may separate commands using semicolons. Whitespace is |
| generally ignored. |
| |
| Strings such as file or format names can normally be entered directly. |
| If the file name contains a character such as a comma which would |
| otherwise serve to separate file names, you may put the file name in |
| double quotes. There is no way to use a double quote character in a |
| file name. |
| |
| You may include comments in linker scripts just as in C, delimited by |
| @samp{/*} and @samp{*/}. As in C, comments are syntactically equivalent |
| to whitespace. |
| |
| @node Simple Example |
| @section Simple Linker Script Example |
| @cindex linker script example |
| @cindex example of linker script |
| Many linker scripts are fairly simple. |
| |
| The simplest possible linker script has just one command: |
| @samp{SECTIONS}. You use the @samp{SECTIONS} command to describe the |
| memory layout of the output file. |
| |
| The @samp{SECTIONS} command is a powerful command. Here we will |
| describe a simple use of it. Let's assume your program consists only of |
| code, initialized data, and uninitialized data. These will be in the |
| @samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively. |
| Let's assume further that these are the only sections which appear in |
| your input files. |
| |
| For this example, let's say that the code should be loaded at address |
| 0x10000, and that the data should start at address 0x8000000. Here is a |
| linker script which will do that: |
| @smallexample |
| SECTIONS |
| @{ |
| . = 0x10000; |
| .text : @{ *(.text) @} |
| . = 0x8000000; |
| .data : @{ *(.data) @} |
| .bss : @{ *(.bss) @} |
| @} |
| @end smallexample |
| |
| You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS}, |
| followed by a series of symbol assignments and output section |
| descriptions enclosed in curly braces. |
| |
| The first line in the above example sets the special symbol @samp{.}, |
| which is the location counter. If you do not specify the address of an |
| output section in some other way (other ways are described later), the |
| address is set from the current value of the location counter. The |
| location counter is then incremented by the size of the output section. |
| |
| The first line inside the @samp{SECTIONS} command of the above example |
| sets the value of the special symbol @samp{.}, which is the location |
| counter. If you do not specify the address of an output section in some |
| other way (other ways are described later), the address is set from the |
| current value of the location counter. The location counter is then |
| incremented by the size of the output section. At the start of the |
| @samp{SECTIONS} command, the location counter has the value @samp{0}. |
| |
| The second line defines an output section, @samp{.text}. The colon is |
| required syntax which may be ignored for now. Within the curly braces |
| after the output section name, you list the names of the input sections |
| which should be placed into this output section. The @samp{*} is a |
| wildcard which matches any file name. The expression @samp{*(.text)} |
| means all @samp{.text} input sections in all input files. |
| |
| Since the location counter is @samp{0x10000} when the output section |
| @samp{.text} is defined, the linker will set the address of the |
| @samp{.text} section in the output file to be @samp{0x10000}. |
| |
| The remaining lines define the @samp{.data} and @samp{.bss} sections in |
| the output file. The linker will place the @samp{.data} output section |
| at address @samp{0x8000000}. After the linker places the @samp{.data} |
| output section, the value of the location counter will be |
| @samp{0x8000000} plus the size of the @samp{.data} output section. The |
| effect is that the linker will place the @samp{.bss} output section |
| immediately after the @samp{.data} output section in memory |
| |
| The linker will ensure that each output section has the required |
| alignment, by increasing the location counter if necessary. In this |
| example, the specified addresses for the @samp{.text} and @samp{.data} |
| sections will probably satisfy any alignment constraints, but the linker |
| may have to create a small gap between the @samp{.data} and @samp{.bss} |
| sections. |
| |
| That's it! That's a simple and complete linker script. |
| |
| @node Simple Commands |
| @section Simple Linker Script Commands |
| @cindex linker script simple commands |
| In this section we describe the simple linker script commands. |
| |
| @menu |
| * Entry Point:: Setting the entry point |
| * File Commands:: Commands dealing with files |
| @ifclear SingleFormat |
| * Format Commands:: Commands dealing with object file formats |
| @end ifclear |
| |
| * Miscellaneous Commands:: Other linker script commands |
| @end menu |
| |
| @node Entry Point |
| @subsection Setting the entry point |
| @kindex ENTRY(@var{symbol}) |
| @cindex start of execution |
| @cindex first instruction |
| @cindex entry point |
| The first instruction to execute in a program is called the @dfn{entry |
| point}. You can use the @code{ENTRY} linker script command to set the |
| entry point. The argument is a symbol name: |
| @smallexample |
| ENTRY(@var{symbol}) |
| @end smallexample |
| |
| There are several ways to set the entry point. The linker will set the |
| entry point by trying each of the following methods in order, and |
| stopping when one of them succeeds: |
| @itemize @bullet |
| @item |
| the @samp{-e} @var{entry} command-line option; |
| @item |
| the @code{ENTRY(@var{symbol})} command in a linker script; |
| @item |
| the value of the symbol @code{start}, if defined; |
| @item |
| the address of the first byte of the @samp{.text} section, if present; |
| @item |
| The address @code{0}. |
| @end itemize |
| |
| @node File Commands |
| @subsection Commands dealing with files |
| @cindex linker script file commands |
| Several linker script commands deal with files. |
| |
| @table @code |
| @item INCLUDE @var{filename} |
| @kindex INCLUDE @var{filename} |
| @cindex including a linker script |
| Include the linker script @var{filename} at this point. The file will |
| be searched for in the current directory, and in any directory specified |
| with the @code{-L} option. You can nest calls to @code{INCLUDE} up to |
| 10 levels deep. |
| |
| @item INPUT(@var{file}, @var{file}, @dots{}) |
| @itemx INPUT(@var{file} @var{file} @dots{}) |
| @kindex INPUT(@var{files}) |
| @cindex input files in linker scripts |
| @cindex input object files in linker scripts |
| @cindex linker script input object files |
| The @code{INPUT} command directs the linker to include the named files |
| in the link, as though they were named on the command line. |
| |
| For example, if you always want to include @file{subr.o} any time you do |
| a link, but you can't be bothered to put it on every link command line, |
| then you can put @samp{INPUT (subr.o)} in your linker script. |
| |
| In fact, if you like, you can list all of your input files in the linker |
| script, and then invoke the linker with nothing but a @samp{-T} option. |
| |
| The linker will first try to open the file in the current directory. If |
| it is not found, the linker will search through the archive library |
| search path. See the description of @samp{-L} in @ref{Options,,Command |
| Line Options}. |
| |
| If you use @samp{INPUT (-l@var{file})}, @code{ld} will transform the |
| name to @code{lib@var{file}.a}, as with the command line argument |
| @samp{-l}. |
| |
| When you use the @code{INPUT} command in an implicit linker script, the |
| files will be included in the link at the point at which the linker |
| script file is included. This can affect archive searching. |
| |
| @item GROUP(@var{file}, @var{file}, @dots{}) |
| @itemx GROUP(@var{file} @var{file} @dots{}) |
| @kindex GROUP(@var{files}) |
| @cindex grouping input files |
| The @code{GROUP} command is like @code{INPUT}, except that the named |
| files should all be archives, and they are searched repeatedly until no |
| new undefined references are created. See the description of @samp{-(} |
| in @ref{Options,,Command Line Options}. |
| |
| @item OUTPUT(@var{filename}) |
| @kindex OUTPUT(@var{filename}) |
| @cindex output file name in linker scripot |
| The @code{OUTPUT} command names the output file. Using |
| @code{OUTPUT(@var{filename})} in the linker script is exactly like using |
| @samp{-o @var{filename}} on the command line (@pxref{Options,,Command |
| Line Options}). If both are used, the command line option takes |
| precedence. |
| |
| You can use the @code{OUTPUT} command to define a default name for the |
| output file other than the usual default of @file{a.out}. |
| |
| @item SEARCH_DIR(@var{path}) |
| @kindex SEARCH_DIR(@var{path}) |
| @cindex library search path in linker script |
| @cindex archive search path in linker script |
| @cindex search path in linker script |
| The @code{SEARCH_DIR} command adds @var{path} to the list of paths where |
| @code{ld} looks for archive libraries. Using |
| @code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}} |
| on the command line (@pxref{Options,,Command Line Options}). If both |
| are used, then the linker will search both paths. Paths specified using |
| the command line option are searched first. |
| |
| @item STARTUP(@var{filename}) |
| @kindex STARTUP(@var{filename}) |
| @cindex first input file |
| The @code{STARTUP} command is just like the @code{INPUT} command, except |
| that @var{filename} will become the first input file to be linked, as |
| though it were specified first on the command line. This may be useful |
| when using a system in which the entry point is always the start of the |
| first file. |
| @end table |
| |
| @ifclear SingleFormat |
| @node Format Commands |
| @subsection Commands dealing with object file formats |
| A couple of linker script commands deal with object file formats. |
| |
| @table @code |
| @item OUTPUT_FORMAT(@var{bfdname}) |
| @itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little}) |
| @kindex OUTPUT_FORMAT(@var{bfdname}) |
| @cindex output file format in linker script |
| The @code{OUTPUT_FORMAT} command names the BFD format to use for the |
| output file (@pxref{BFD}). Using @code{OUTPUT_FORMAT(@var{bfdname})} is |
| exactly like using @samp{-oformat @var{bfdname}} on the command line |
| (@pxref{Options,,Command Line Options}). If both are used, the command |
| line option takes precedence. |
| |
| You can use @code{OUTPUT_FORMAT} with three arguments to use different |
| formats based on the @samp{-EB} and @samp{-EL} command line options. |
| This permits the linker script to set the output format based on the |
| desired endianness. |
| |
| If neither @samp{-EB} nor @samp{-EL} are used, then the output format |
| will be the first argument, @var{default}. If @samp{-EB} is used, the |
| output format will be the second argument, @var{big}. If @samp{-EL} is |
| used, the output format will be the third argument, @var{little}. |
| |
| For example, the default linker script for the MIPS ELF target uses this |
| command: |
| @smallexample |
| OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) |
| @end smallexample |
| This says that the default format for the output file is |
| @samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line |
| option, the output file will be created in the @samp{elf32-littlemips} |
| format. |
| |
| @item TARGET(@var{bfdname}) |
| @kindex TARGET(@var{bfdname}) |
| @cindex input file format in linker script |
| The @code{TARGET} command names the BFD format to use when reading input |
| files. It affects subsequent @code{INPUT} and @code{GROUP} commands. |
| This command is like using @samp{-b @var{bfdname}} on the command line |
| (@pxref{Options,,Command Line Options}). If the @code{TARGET} command |
| is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET} |
| command is also used to set the format for the output file. @xref{BFD}. |
| @end table |
| @end ifclear |
| |
| @node Miscellaneous Commands |
| @subsection Other linker script commands |
| There are a few other linker scripts commands. |
| |
| @table @code |
| @item ASSERT(@var{exp}, @var{message}) |
| @kindex ASSERT |
| @cindex assertion in linker script |
| Ensure that @var{exp} is non-zero. If it is zero, then exit the linker |
| with an error code, and print @var{message}. |
| |
| @item EXTERN(@var{symbol} @var{symbol} @dots{}) |
| @kindex EXTERN |
| @cindex undefined symbol in linker script |
| Force @var{symbol} to be entered in the output file as an undefined |
| symbol. Doing this may, for example, trigger linking of additional |
| modules from standard libraries. You may list several @var{symbol}s for |
| each @code{EXTERN}, and you may use @code{EXTERN} multiple times. This |
| command has the same effect as the @samp{-u} command-line option. |
| |
| @item FORCE_COMMON_ALLOCATION |
| @kindex FORCE_COMMON_ALLOCATION |
| @cindex common allocation in linker script |
| This command has the same effect as the @samp{-d} command-line option: |
| to make @code{ld} assign space to common symbols even if a relocatable |
| output file is specified (@samp{-r}). |
| |
| @item NOCROSSREFS(@var{section} @var{section} @dots{}) |
| @kindex NOCROSSREFS(@var{sections}) |
| @cindex cross references |
| This command may be used to tell @code{ld} to issue an error about any |
| references among certain output sections. |
| |
| In certain types of programs, particularly on embedded systems when |
| using overlays, when one section is loaded into memory, another section |
| will not be. Any direct references between the two sections would be |
| errors. For example, it would be an error if code in one section called |
| a function defined in the other section. |
| |
| The @code{NOCROSSREFS} command takes a list of output section names. If |
| @code{ld} detects any cross references between the sections, it reports |
| an error and returns a non-zero exit status. Note that the |
| @code{NOCROSSREFS} command uses output section names, not input section |
| names. |
| |
| @ifclear SingleFormat |
| @item OUTPUT_ARCH(@var{bfdarch}) |
| @kindex OUTPUT_ARCH(@var{bfdarch}) |
| @cindex machine architecture |
| @cindex architecture |
| Specify a particular output machine architecture. The argument is one |
| of the names used by the BFD library (@pxref{BFD}). You can see the |
| architecture of an object file by using the @code{objdump} program with |
| the @samp{-f} option. |
| @end ifclear |
| @end table |
| |
| @node Assignments |
| @section Assigning Values to Symbols |
| @cindex assignment in scripts |
| @cindex symbol definition, scripts |
| @cindex variables, defining |
| You may assign a value to a symbol in a linker script. This will define |
| the symbol as a global symbol. |
| |
| @menu |
| * Simple Assignments:: Simple Assignments |
| * PROVIDE:: PROVIDE |
| @end menu |
| |
| @node Simple Assignments |
| @subsection Simple Assignments |
| |
| You may assign to a symbol using any of the C assignment operators: |
| |
| @table @code |
| @item @var{symbol} = @var{expression} ; |
| @itemx @var{symbol} += @var{expression} ; |
| @itemx @var{symbol} -= @var{expression} ; |
| @itemx @var{symbol} *= @var{expression} ; |
| @itemx @var{symbol} /= @var{expression} ; |
| @itemx @var{symbol} <<= @var{expression} ; |
| @itemx @var{symbol} >>= @var{expression} ; |
| @itemx @var{symbol} &= @var{expression} ; |
| @itemx @var{symbol} |= @var{expression} ; |
| @end table |
| |
| The first case will define @var{symbol} to the value of |
| @var{expression}. In the other cases, @var{symbol} must already be |
| defined, and the value will be adjusted accordingly. |
| |
| The special symbol name @samp{.} indicates the location counter. You |
| may only use this within a @code{SECTIONS} command. |
| |
| The semicolon after @var{expression} is required. |
| |
| Expressions are defined below; see @ref{Expressions}. |
| |
| You may write symbol assignments as commands in their own right, or as |
| statements within a @code{SECTIONS} command, or as part of an output |
| section description in a @code{SECTIONS} command. |
| |
| The section of the symbol will be set from the section of the |
| expression; for more information, see @ref{Expression Section}. |
| |
| Here is an example showing the three different places that symbol |
| assignments may be used: |
| |
| @smallexample |
| floating_point = 0; |
| SECTIONS |
| @{ |
| .text : |
| @{ |
| *(.text) |
| _etext = .; |
| @} |
| _bdata = (. + 3) & ~ 4; |
| .data : @{ *(.data) @} |
| @} |
| @end smallexample |
| @noindent |
| In this example, the symbol @samp{floating_point} will be defined as |
| zero. The symbol @samp{_etext} will be defined as the address following |
| the last @samp{.text} input section. The symbol @samp{_bdata} will be |
| defined as the address following the @samp{.text} output section aligned |
| upward to a 4 byte boundary. |
| |
| @node PROVIDE |
| @subsection PROVIDE |
| @cindex PROVIDE |
| In some cases, it is desirable for a linker script to define a symbol |
| only if it is referenced and is not defined by any object included in |
| the link. For example, traditional linkers defined the symbol |
| @samp{etext}. However, ANSI C requires that the user be able to use |
| @samp{etext} as a function name without encountering an error. The |
| @code{PROVIDE} keyword may be used to define a symbol, such as |
| @samp{etext}, only if it is referenced but not defined. The syntax is |
| @code{PROVIDE(@var{symbol} = @var{expression})}. |
| |
| Here is an example of using @code{PROVIDE} to define @samp{etext}: |
| @smallexample |
| SECTIONS |
| @{ |
| .text : |
| @{ |
| *(.text) |
| _etext = .; |
| PROVIDE(etext = .); |
| @} |
| @} |
| @end smallexample |
| |
| In this example, if the program defines @samp{_etext} (with a leading |
| underscore), the linker will give a multiple definition error. If, on |
| the other hand, the program defines @samp{etext} (with no leading |
| underscore), the linker will silently use the definition in the program. |
| If the program references @samp{etext} but does not define it, the |
| linker will use the definition in the linker script. |
| |
| @node SECTIONS |
| @section SECTIONS command |
| @kindex SECTIONS |
| The @code{SECTIONS} command tells the linker how to map input sections |
| into output sections, and how to place the output sections in memory. |
| |
| The format of the @code{SECTIONS} command is: |
| @smallexample |
| SECTIONS |
| @{ |
| @var{sections-command} |
| @var{sections-command} |
| @dots{} |
| @} |
| @end smallexample |
| |
| Each @var{sections-command} may of be one of the following: |
| |
| @itemize @bullet |
| @item |
| an @code{ENTRY} command (@pxref{Entry Point,,Entry command}) |
| @item |
| a symbol assignment (@pxref{Assignments}) |
| @item |
| an output section description |
| @item |
| an overlay description |
| @end itemize |
| |
| The @code{ENTRY} command and symbol assignments are permitted inside the |
| @code{SECTIONS} command for convenience in using the location counter in |
| those commands. This can also make the linker script easier to |
| understand because you can use those commands at meaningful points in |
| the layout of the output file. |
| |
| Output section descriptions and overlay descriptions are described |
| below. |
| |
| If you do not use a @code{SECTIONS} command in your linker script, the |
| linker will place each input section into an identically named output |
| section in the order that the sections are first encountered in the |
| input files. If all input sections are present in the first file, for |
| example, the order of sections in the output file will match the order |
| in the first input file. The first section will be at address zero. |
| |
| @menu |
| * Output Section Description:: Output section description |
| * Output Section Name:: Output section name |
| * Output Section Address:: Output section address |
| * Input Section:: Input section description |
| * Output Section Data:: Output section data |
| * Output Section Keywords:: Output section keywords |
| * Output Section Discarding:: Output section discarding |
| * Output Section Attributes:: Output section attributes |
| * Overlay Description:: Overlay description |
| @end menu |
| |
| @node Output Section Description |
| @subsection Output section description |
| The full description of an output section looks like this: |
| @smallexample |
| @group |
| @var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})] |
| @{ |
| @var{output-section-command} |
| @var{output-section-command} |
| @dots{} |
| @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] |
| @end group |
| @end smallexample |
| |
| Most output sections do not use most of the optional section attributes. |
| |
| The whitespace around @var{section} is required, so that the section |
| name is unambiguous. The colon and the curly braces are also required. |
| The line breaks and other white space are optional. |
| |
| Each @var{output-section-command} may be one of the following: |
| |
| @itemize @bullet |
| @item |
| a symbol assignment (@pxref{Assignments}) |
| @item |
| an input section description (@pxref{Input Section}) |
| @item |
| data values to include directly (@pxref{Output Section Data}) |
| @item |
| a special output section keyword (@pxref{Output Section Keywords}) |
| @end itemize |
| |
| @node Output Section Name |
| @subsection Output section name |
| @cindex name, section |
| @cindex section name |
| The name of the output section is @var{section}. @var{section} must |
| meet the constraints of your output format. In formats which only |
| support a limited number of sections, such as @code{a.out}, the name |
| must be one of the names supported by the format (@code{a.out}, for |
| example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the |
| output format supports any number of sections, but with numbers and not |
| names (as is the case for Oasys), the name should be supplied as a |
| quoted numeric string. A section name may consist of any sequence of |
| characters, but a name which contains any unusual characters such as |
| commas must be quoted. |
| |
| The output section name @samp{/DISCARD/} is special; @ref{Output Section |
| Discarding}. |
| |
| @node Output Section Address |
| @subsection Output section address |
| @cindex address, section |
| @cindex section address |
| The @var{address} is an expression for the VMA (the virtual memory |
| address) of the output section. If you do not provide @var{address}, |
| the linker will set it based on @var{region} if present, or otherwise |
| based on the current value of the location counter. |
| |
| If you provide @var{address}, the address of the output section will be |
| set to precisely that. If you provide neither @var{address} nor |
| @var{region}, then the address of the output section will be set to the |
| current value of the location counter aligned to the alignment |
| requirements of the output section. The alignment requirement of the |
| output section is the strictest alignment of any input section contained |
| within the output section. |
| |
| For example, |
| @smallexample |
| .text . : @{ *(.text) @} |
| @end smallexample |
| @noindent |
| and |
| @smallexample |
| .text : @{ *(.text) @} |
| @end smallexample |
| @noindent |
| are subtly different. The first will set the address of the |
| @samp{.text} output section to the current value of the location |
| counter. The second will set it to the current value of the location |
| counter aligned to the strictest alignment of a @samp{.text} input |
| section. |
| |
| The @var{address} may be an arbitrary expression; @ref{Expressions}. |
| For example, if you want to align the section on a 0x10 byte boundary, |
| so that the lowest four bits of the section address are zero, you could |
| do something like this: |
| @smallexample |
| .text ALIGN(0x10) : @{ *(.text) @} |
| @end smallexample |
| @noindent |
| This works because @code{ALIGN} returns the current location counter |
| aligned upward to the specified value. |
| |
| Specifying @var{address} for a section will change the value of the |
| location counter. |
| |
| @node Input Section |
| @subsection Input section description |
| @cindex input sections |
| @cindex mapping input sections to output sections |
| The most common output section command is an input section description. |
| |
| The input section description is the most basic linker script operation. |
| You use output sections to tell the linker how to lay out your program |
| in memory. You use input section descriptions to tell the linker how to |
| map the input files into your memory layout. |
| |
| @menu |
| * Input Section Basics:: Input section basics |
| * Input Section Wildcards:: Input section wildcard patterns |
| * Input Section Common:: Input section for common symbols |
| * Input Section Keep:: Input section and garbage collection |
| * Input Section Example:: Input section example |
| @end menu |
| |
| @node Input Section Basics |
| @subsubsection Input section basics |
| @cindex input section basics |
| An input section description consists of a file name optionally followed |
| by a list of section names in parentheses. |
| |
| The file name and the section name may be wildcard patterns, which we |
| describe further below (@pxref{Input Section Wildcards}). |
| |
| The most common input section description is to include all input |
| sections with a particular name in the output section. For example, to |
| include all input @samp{.text} sections, you would write: |
| @smallexample |
| *(.text) |
| @end smallexample |
| @noindent |
| Here the @samp{*} is a wildcard which matches any file name. To exclude a file |
| from matching the file name wildcard, EXCLUDE_FILE may be used to match all files |
| except the one specified by EXCLUDE_FILE. For example: |
| @smallexample |
| (*(EXCLUDE_FILE (*crtend.o) .ctors)) |
| @end smallexample |
| will cause all .ctors sections from all files except crtend.o to be included. |
| |
| There are two ways to include more than one section: |
| @smallexample |
| *(.text .rdata) |
| *(.text) *(.rdata) |
| @end smallexample |
| @noindent |
| The difference between these is the order in which the @samp{.text} and |
| @samp{.rdata} input sections will appear in the output section. In the |
| first example, they will be intermingled. In the second example, all |
| @samp{.text} input sections will appear first, followed by all |
| @samp{.rdata} input sections. |
| |
| You can specify a file name to include sections from a particular file. |
| You would do this if one or more of your files contain special data that |
| needs to be at a particular location in memory. For example: |
| @smallexample |
| data.o(.data) |
| @end smallexample |
| |
| If you use a file name without a list of sections, then all sections in |
| the input file will be included in the output section. This is not |
| commonly done, but it may by useful on occasion. For example: |
| @smallexample |
| data.o |
| @end smallexample |
| |
| When you use a file name which does not contain any wild card |
| characters, the linker will first see if you also specified the file |
| name on the linker command line or in an @code{INPUT} command. If you |
| did not, the linker will attempt to open the file as an input file, as |
| though it appeared on the command line. Note that this differs from an |
| @code{INPUT} command, because the linker will not search for the file in |
| the archive search path. |
| |
| @node Input Section Wildcards |
| @subsubsection Input section wildcard patterns |
| @cindex input section wildcards |
| @cindex wildcard file name patterns |
| @cindex file name wildcard patterns |
| @cindex section name wildcard patterns |
| In an input section description, either the file name or the section |
| name or both may be wildcard patterns. |
| |
| The file name of @samp{*} seen in many examples is a simple wildcard |
| pattern for the file name. |
| |
| The wildcard patterns are like those used by the Unix shell. |
| |
| @table @samp |
| @item * |
| matches any number of characters |
| @item ? |
| matches any single character |
| @item [@var{chars}] |
| matches a single instance of any of the @var{chars}; the @samp{-} |
| character may be used to specify a range of characters, as in |
| @samp{[a-z]} to match any lower case letter |
| @item \ |
| quotes the following character |
| @end table |
| |
| When a file name is matched with a wildcard, the wildcard characters |
| will not match a @samp{/} character (used to separate directory names on |
| Unix). A pattern consisting of a single @samp{*} character is an |
| exception; it will always match any file name, whether it contains a |
| @samp{/} or not. In a section name, the wildcard characters will match |
| a @samp{/} character. |
| |
| File name wildcard patterns only match files which are explicitly |
| specified on the command line or in an @code{INPUT} command. The linker |
| does not search directories to expand wildcards. |
| |
| If a file name matches more than one wildcard pattern, or if a file name |
| appears explicitly and is also matched by a wildcard pattern, the linker |
| will use the first match in the linker script. For example, this |
| sequence of input section descriptions is probably in error, because the |
| @file{data.o} rule will not be used: |
| @smallexample |
| .data : @{ *(.data) @} |
| .data1 : @{ data.o(.data) @} |
| @end smallexample |
| |
| @cindex SORT |
| Normally, the linker will place files and sections matched by wildcards |
| in the order in which they are seen during the link. You can change |
| this by using the @code{SORT} keyword, which appears before a wildcard |
| pattern in parentheses (e.g., @code{SORT(.text*)}). When the |
| @code{SORT} keyword is used, the linker will sort the files or sections |
| into ascending order by name before placing them in the output file. |
| |
| If you ever get confused about where input sections are going, use the |
| @samp{-M} linker option to generate a map file. The map file shows |
| precisely how input sections are mapped to output sections. |
| |
| This example shows how wildcard patterns might be used to partition |
| files. This linker script directs the linker to place all @samp{.text} |
| sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}. |
| The linker will place the @samp{.data} section from all files beginning |
| with an upper case character in @samp{.DATA}; for all other files, the |
| linker will place the @samp{.data} section in @samp{.data}. |
| @smallexample |
| @group |
| SECTIONS @{ |
| .text : @{ *(.text) @} |
| .DATA : @{ [A-Z]*(.data) @} |
| .data : @{ *(.data) @} |
| .bss : @{ *(.bss) @} |
| @} |
| @end group |
| @end smallexample |
| |
| @node Input Section Common |
| @subsubsection Input section for common symbols |
| @cindex common symbol placement |
| @cindex uninitialized data placement |
| A special notation is needed for common symbols, because in many object |
| file formats common symbols do not have a particular input section. The |
| linker treats common symbols as though they are in an input section |
| named @samp{COMMON}. |
| |
| You may use file names with the @samp{COMMON} section just as with any |
| other input sections. You can use this to place common symbols from a |
| particular input file in one section while common symbols from other |
| input files are placed in another section. |
| |
| In most cases, common symbols in input files will be placed in the |
| @samp{.bss} section in the output file. For example: |
| @smallexample |
| .bss @{ *(.bss) *(COMMON) @} |
| @end smallexample |
| |
| @cindex scommon section |
| @cindex small common symbols |
| Some object file formats have more than one type of common symbol. For |
| example, the MIPS ELF object file format distinguishes standard common |
| symbols and small common symbols. In this case, the linker will use a |
| different special section name for other types of common symbols. In |
| the case of MIPS ELF, the linker uses @samp{COMMON} for standard common |
| symbols and @samp{.scommon} for small common symbols. This permits you |
| to map the different types of common symbols into memory at different |
| locations. |
| |
| @cindex [COMMON] |
| You will sometimes see @samp{[COMMON]} in old linker scripts. This |
| notation is now considered obsolete. It is equivalent to |
| @samp{*(COMMON)}. |
| |
| @node Input Section Keep |
| @subsubsection Input section and garbage collection |
| @cindex KEEP |
| @cindex garbage collection |
| When link-time garbage collection is in use (@samp{--gc-sections}), |
| it is often useful to mark sections that should not be eliminated. |
| This is accomplished by surrounding an input section's wildcard entry |
| with @code{KEEP()}, as in @code{KEEP(*(.init))} or |
| @code{KEEP(SORT(*)(.ctors))}. |
| |
| @node Input Section Example |
| @subsubsection Input section example |
| The following example is a complete linker script. It tells the linker |
| to read all of the sections from file @file{all.o} and place them at the |
| start of output section @samp{outputa} which starts at location |
| @samp{0x10000}. All of section @samp{.input1} from file @file{foo.o} |
| follows immediately, in the same output section. All of section |
| @samp{.input2} from @file{foo.o} goes into output section |
| @samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}. |
| All of the remaining @samp{.input1} and @samp{.input2} sections from any |
| files are written to output section @samp{outputc}. |
| |
| @smallexample |
| @group |
| SECTIONS @{ |
| outputa 0x10000 : |
| @{ |
| all.o |
| foo.o (.input1) |
| @} |
| outputb : |
| @{ |
| foo.o (.input2) |
| foo1.o (.input1) |
| @} |
| outputc : |
| @{ |
| *(.input1) |
| *(.input2) |
| @} |
| @} |
| @end group |
| @end smallexample |
| |
| @node Output Section Data |
| @subsection Output section data |
| @cindex data |
| @cindex section data |
| @cindex output section data |
| @kindex BYTE(@var{expression}) |
| @kindex SHORT(@var{expression}) |
| @kindex LONG(@var{expression}) |
| @kindex QUAD(@var{expression}) |
| @kindex SQUAD(@var{expression}) |
| You can include explicit bytes of data in an output section by using |
| @code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as |
| an output section command. Each keyword is followed by an expression in |
| parentheses providing the value to store (@pxref{Expressions}). The |
| value of the expression is stored at the current value of the location |
| counter. |
| |
| The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands |
| store one, two, four, and eight bytes (respectively). After storing the |
| bytes, the location counter is incremented by the number of bytes |
| stored. |
| |
| For example, this will store the byte 1 followed by the four byte value |
| of the symbol @samp{addr}: |
| @smallexample |
| BYTE(1) |
| LONG(addr) |
| @end smallexample |
| |
| When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the |
| same; they both store an 8 byte, or 64 bit, value. When both host and |
| target are 32 bits, an expression is computed as 32 bits. In this case |
| @code{QUAD} stores a 32 bit value zero extended to 64 bits, and |
| @code{SQUAD} stores a 32 bit value sign extended to 64 bits. |
| |
| If the object file format of the output file has an explicit endianness, |
| which is the normal case, the value will be stored in that endianness. |
| When the object file format does not have an explicit endianness, as is |
| true of, for example, S-records, the value will be stored in the |
| endianness of the first input object file. |
| |
| @kindex FILL(@var{expression}) |
| @cindex holes, filling |
| @cindex unspecified memory |
| You may use the @code{FILL} command to set the fill pattern for the |
| current section. It is followed by an expression in parentheses. Any |
| otherwise unspecified regions of memory within the section (for example, |
| gaps left due to the required alignment of input sections) are filled |
| with the two least significant bytes of the expression, repeated as |
| necessary. A @code{FILL} statement covers memory locations after the |
| point at which it occurs in the section definition; by including more |
| than one @code{FILL} statement, you can have different fill patterns in |
| different parts of an output section. |
| |
| This example shows how to fill unspecified regions of memory with the |
| value @samp{0x9090}: |
| @smallexample |
| FILL(0x9090) |
| @end smallexample |
| |
| The @code{FILL} command is similar to the @samp{=@var{fillexp}} output |
| section attribute (@pxref{Output Section Fill}), but it only affects the |
| part of the section following the @code{FILL} command, rather than the |
| entire section. If both are used, the @code{FILL} command takes |
| precedence. |
| |
| @node Output Section Keywords |
| @subsection Output section keywords |
| There are a couple of keywords which can appear as output section |
| commands. |
| |
| @table @code |
| @kindex CREATE_OBJECT_SYMBOLS |
| @cindex input filename symbols |
| @cindex filename symbols |
| @item CREATE_OBJECT_SYMBOLS |
| The command tells the linker to create a symbol for each input file. |
| The name of each symbol will be the name of the corresponding input |
| file. The section of each symbol will be the output section in which |
| the @code{CREATE_OBJECT_SYMBOLS} command appears. |
| |
| This is conventional for the a.out object file format. It is not |
| normally used for any other object file format. |
| |
| @kindex CONSTRUCTORS |
| @cindex C++ constructors, arranging in link |
| @cindex constructors, arranging in link |
| @item CONSTRUCTORS |
| When linking using the a.out object file format, the linker uses an |
| unusual set construct to support C++ global constructors and |
| destructors. When linking object file formats which do not support |
| arbitrary sections, such as ECOFF and XCOFF, the linker will |
| automatically recognize C++ global constructors and destructors by name. |
| For these object file formats, the @code{CONSTRUCTORS} command tells the |
| linker to place constructor information in the output section where the |
| @code{CONSTRUCTORS} command appears. The @code{CONSTRUCTORS} command is |
| ignored for other object file formats. |
| |
| The symbol @w{@code{__CTOR_LIST__}} marks the start of the global |
| constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The |
| first word in the list is the number of entries, followed by the address |
| of each constructor or destructor, followed by a zero word. The |
| compiler must arrange to actually run the code. For these object file |
| formats @sc{gnu} C++ normally calls constructors from a subroutine |
| @code{__main}; a call to @code{__main} is automatically inserted into |
| the startup code for @code{main}. @sc{gnu} C++ normally runs |
| destructors either by using @code{atexit}, or directly from the function |
| @code{exit}. |
| |
| For object file formats such as @code{COFF} or @code{ELF} which support |
| arbitrary section names, @sc{gnu} C++ will normally arrange to put the |
| addresses of global constructors and destructors into the @code{.ctors} |
| and @code{.dtors} sections. Placing the following sequence into your |
| linker script will build the sort of table which the @sc{gnu} C++ |
| runtime code expects to see. |
| |
| @smallexample |
| __CTOR_LIST__ = .; |
| LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) |
| *(.ctors) |
| LONG(0) |
| __CTOR_END__ = .; |
| __DTOR_LIST__ = .; |
| LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) |
| *(.dtors) |
| LONG(0) |
| __DTOR_END__ = .; |
| @end smallexample |
| |
| If you are using the @sc{gnu} C++ support for initialization priority, |
| which provides some control over the order in which global constructors |
| are run, you must sort the constructors at link time to ensure that they |
| are executed in the correct order. When using the @code{CONSTRUCTORS} |
| command, use @samp{SORT(CONSTRUCTORS)} instead. When using the |
| @code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and |
| @samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and |
| @samp{*(.dtors)}. |
| |
| Normally the compiler and linker will handle these issues automatically, |
| and you will not need to concern yourself with them. However, you may |
| need to consider this if you are using C++ and writing your own linker |
| scripts. |
| |
| @end table |
| |
| @node Output Section Discarding |
| @subsection Output section discarding |
| @cindex discarding sections |
| @cindex sections, discarding |
| @cindex removing sections |
| The linker will not create output section which do not have any |
| contents. This is for convenience when referring to input sections that |
| may or may not be present in any of the input files. For example: |
| @smallexample |
| .foo @{ *(.foo) @} |
| @end smallexample |
| @noindent |
| will only create a @samp{.foo} section in the output file if there is a |
| @samp{.foo} section in at least one input file. |
| |
| If you use anything other than an input section description as an output |
| section command, such as a symbol assignment, then the output section |
| will always be created, even if there are no matching input sections. |
| |
| @cindex /DISCARD/ |
| The special output section name @samp{/DISCARD/} may be used to discard |
| input sections. Any input sections which are assigned to an output |
| section named @samp{/DISCARD/} are not included in the output file. |
| |
| @node Output Section Attributes |
| @subsection Output section attributes |
| @cindex output section attributes |
| We showed above that the full description of an output section looked |
| like this: |
| @smallexample |
| @group |
| @var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})] |
| @{ |
| @var{output-section-command} |
| @var{output-section-command} |
| @dots{} |
| @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}] |
| @end group |
| @end smallexample |
| We've already described @var{section}, @var{address}, and |
| @var{output-section-command}. In this section we will describe the |
| remaining section attributes. |
| |
| @menu |
| * Output Section Type:: Output section type |
| * Output Section LMA:: Output section LMA |
| * Output Section Region:: Output section region |
| * Output Section Phdr:: Output section phdr |
| * Output Section Fill:: Output section fill |
| @end menu |
| |
| @node Output Section Type |
| @subsubsection Output section type |
| Each output section may have a type. The type is a keyword in |
| parentheses. The following types are defined: |
| |
| @table @code |
| @item NOLOAD |
| The section should be marked as not loadable, so that it will not be |
| loaded into memory when the program is run. |
| @item DSECT |
| @itemx COPY |
| @itemx INFO |
| @itemx OVERLAY |
| These type names are supported for backward compatibility, and are |
| rarely used. They all have the same effect: the section should be |
| marked as not allocatable, so that no memory is allocated for the |
| section when the program is run. |
| @end table |
| |
| @kindex NOLOAD |
| @cindex prevent unnecessary loading |
| @cindex loading, preventing |
| The linker normally sets the attributes of an output section based on |
| the input sections which map into it. You can override this by using |
| the section type. For example, in the script sample below, the |
| @samp{ROM} section is addressed at memory location @samp{0} and does not |
| need to be loaded when the program is run. The contents of the |
| @samp{ROM} section will appear in the linker output file as usual. |
| @smallexample |
| @group |
| SECTIONS @{ |
| ROM 0 (NOLOAD) : @{ @dots{} @} |
| @dots{} |
| @} |
| @end group |
| @end smallexample |
| |
| @node Output Section LMA |
| @subsubsection Output section LMA |
| @kindex AT(@var{lma}) |
| @cindex load address |
| @cindex section load address |
| Every section has a virtual address (VMA) and a load address (LMA); see |
| @ref{Basic Script Concepts}. The address expression which may appear in |
| an output section description sets the VMA (@pxref{Output Section |
| Address}). |
| |
| The linker will normally set the LMA equal to the VMA. You can change |
| that by using the @code{AT} keyword. The expression @var{lma} that |
| follows the @code{AT} keyword specifies the load address of the section. |
| |
| @cindex ROM initialized data |
| @cindex initialized data in ROM |
| This feature is designed to make it easy to build a ROM image. For |
| example, the following linker script creates three output sections: one |
| called @samp{.text}, which starts at @code{0x1000}, one called |
| @samp{.mdata}, which is loaded at the end of the @samp{.text} section |
| even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold |
| uninitialized data at address @code{0x3000}. The symbol @code{_data} is |
| defined with the value @code{0x2000}, which shows that the location |
| counter holds the VMA value, not the LMA value. |
| |
| @smallexample |
| @group |
| SECTIONS |
| @{ |
| .text 0x1000 : @{ *(.text) _etext = . ; @} |
| .mdata 0x2000 : |
| AT ( ADDR (.text) + SIZEOF (.text) ) |
| @{ _data = . ; *(.data); _edata = . ; @} |
| .bss 0x3000 : |
| @{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@} |
| @} |
| @end group |
| @end smallexample |
| |
| The run-time initialization code for use with a program generated with |
| this linker script would include something like the following, to copy |
| the initialized data from the ROM image to its runtime address. Notice |
| how this code takes advantage of the symbols defined by the linker |
| script. |
| |
| @smallexample |
| @group |
| extern char _etext, _data, _edata, _bstart, _bend; |
| char *src = &_etext; |
| char *dst = &_data; |
| |
| /* ROM has data at end of text; copy it. */ |
| while (dst < &_edata) @{ |
| *dst++ = *src++; |
| @} |
| |
| /* Zero bss */ |
| for (dst = &_bstart; dst< &_bend; dst++) |
| *dst = 0; |
| @end group |
| @end smallexample |
| |
| @node Output Section Region |
| @subsubsection Output section region |
| @kindex >@var{region} |
| @cindex section, assigning to memory region |
| @cindex memory regions and sections |
| You can assign a section to a previously defined region of memory by |
| using @samp{>@var{region}}. @xref{MEMORY}. |
| |
| Here is a simple example: |
| @smallexample |
| @group |
| MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @} |
| SECTIONS @{ ROM : @{ *(.text) @} >rom @} |
| @end group |
| @end smallexample |
| |
| @node Output Section Phdr |
| @subsubsection Output section phdr |
| @kindex :@var{phdr} |
| @cindex section, assigning to program header |
| @cindex program headers and sections |
| You can assign a section to a previously defined program segment by |
| using @samp{:@var{phdr}}. @xref{PHDRS}. If a section is assigned to |
| one or more segments, then all subsequent allocated sections will be |
| assigned to those segments as well, unless they use an explicitly |
| @code{:@var{phdr}} modifier. You can use @code{:NONE} to tell the |
| linker to not put the section in any segment at all. |
| |
| Here is a simple example: |
| @smallexample |
| @group |
| PHDRS @{ text PT_LOAD ; @} |
| SECTIONS @{ .text : @{ *(.text) @} :text @} |
| @end group |
| @end smallexample |
| |
| @node Output Section Fill |
| @subsubsection Output section fill |
| @kindex =@var{fillexp} |
| @cindex section fill pattern |
| @cindex fill pattern, entire section |
| You can set the fill pattern for an entire section by using |
| @samp{=@var{fillexp}}. @var{fillexp} is an expression |
| (@pxref{Expressions}). Any otherwise unspecified regions of memory |
| within the output section (for example, gaps left due to the required |
| alignment of input sections) will be filled with the two least |
| significant bytes of the value, repeated as necessary. |
| |
| You can also change the fill value with a @code{FILL} command in the |
| output section commands; see @ref{Output Section Data}. |
| |
| Here is a simple example: |
| @smallexample |
| @group |
| SECTIONS @{ .text : @{ *(.text) @} =0x9090 @} |
| @end group |
| @end smallexample |
| |
| @node Overlay Description |
| @subsection Overlay description |
| @kindex OVERLAY |
| @cindex overlays |
| An overlay description provides an easy way to describe sections which |
| are to be loaded as part of a single memory image but are to be run at |
| the same memory address. At run time, some sort of overlay manager will |
| copy the overlaid sections in and out of the runtime memory address as |
| required, perhaps by simply manipulating addressing bits. This approach |
| can be useful, for example, when a certain region of memory is faster |
| than another. |
| |
| Overlays are described using the @code{OVERLAY} command. The |
| @code{OVERLAY} command is used within a @code{SECTIONS} command, like an |
| output section description. The full syntax of the @code{OVERLAY} |
| command is as follows: |
| @smallexample |
| @group |
| OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )] |
| @{ |
| @var{secname1} |
| @{ |
| @var{output-section-command} |
| @var{output-section-command} |
| @dots{} |
| @} [:@var{phdr}@dots{}] [=@var{fill}] |
| @var{secname2} |
| @{ |
| @var{output-section-command} |
| @var{output-section-command} |
| @dots{} |
| @} [:@var{phdr}@dots{}] [=@var{fill}] |
| @dots{} |
| @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}] |
| @end group |
| @end smallexample |
| |
| Everything is optional except @code{OVERLAY} (a keyword), and each |
| section must have a name (@var{secname1} and @var{secname2} above). The |
| section definitions within the @code{OVERLAY} construct are identical to |
| those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}), |
| except that no addresses and no memory regions may be defined for |
| sections within an @code{OVERLAY}. |
| |
| The sections are all defined with the same starting address. The load |
| addresses of the sections are arranged such that they are consecutive in |
| memory starting at the load address used for the @code{OVERLAY} as a |
| whole (as with normal section definitions, the load address is optional, |
| and defaults to the start address; the start address is also optional, |
| and defaults to the current value of the location counter). |
| |
| If the @code{NOCROSSREFS} keyword is used, and there any references |
| among the sections, the linker will report an error. Since the sections |
| all run at the same address, it normally does not make sense for one |
| section to refer directly to another. @xref{Miscellaneous Commands, |
| NOCROSSREFS}. |
| |
| For each section within the @code{OVERLAY}, the linker automatically |
| defines two symbols. The symbol @code{__load_start_@var{secname}} is |
| defined as the starting load address of the section. The symbol |
| @code{__load_stop_@var{secname}} is defined as the final load address of |
| the section. Any characters within @var{secname} which are not legal |
| within C identifiers are removed. C (or assembler) code may use these |
| symbols to move the overlaid sections around as necessary. |
| |
| At the end of the overlay, the value of the location counter is set to |
| the start address of the overlay plus the size of the largest section. |
| |
| Here is an example. Remember that this would appear inside a |
| @code{SECTIONS} construct. |
| @smallexample |
| @group |
| OVERLAY 0x1000 : AT (0x4000) |
| @{ |
| .text0 @{ o1/*.o(.text) @} |
| .text1 @{ o2/*.o(.text) @} |
| @} |
| @end group |
| @end smallexample |
| @noindent |
| This will define both @samp{.text0} and @samp{.text1} to start at |
| address 0x1000. @samp{.text0} will be loaded at address 0x4000, and |
| @samp{.text1} will be loaded immediately after @samp{.text0}. The |
| following symbols will be defined: @code{__load_start_text0}, |
| @code{__load_stop_text0}, @code{__load_start_text1}, |
| @code{__load_stop_text1}. |
| |
| C code to copy overlay @code{.text1} into the overlay area might look |
| like the following. |
| |
| @smallexample |
| @group |
| extern char __load_start_text1, __load_stop_text1; |
| memcpy ((char *) 0x1000, &__load_start_text1, |
| &__load_stop_text1 - &__load_start_text1); |
| @end group |
| @end smallexample |
| |
| Note that the @code{OVERLAY} command is just syntactic sugar, since |
| everything it does can be done using the more basic commands. The above |
| example could have been written identically as follows. |
| |
| @smallexample |
| @group |
| .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @} |
| __load_start_text0 = LOADADDR (.text0); |
| __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0); |
| .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @} |
| __load_start_text1 = LOADADDR (.text1); |
| __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1); |
| . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); |
| @end group |
| @end smallexample |
| |
| @node MEMORY |
| @section MEMORY command |
| @kindex MEMORY |
| @cindex memory regions |
| @cindex regions of memory |
| @cindex allocating memory |
| @cindex discontinuous memory |
| The linker's default configuration permits allocation of all available |
| memory. You can override this by using the @code{MEMORY} command. |
| |
| The @code{MEMORY} command describes the location and size of blocks of |
| memory in the target. You can use it to describe which memory regions |
| may be used by the linker, and which memory regions it must avoid. You |
| can then assign sections to particular memory regions. The linker will |
| set section addresses based on the memory regions, and will warn about |
| regions that become too full. The linker will not shuffle sections |
| around to fit into the available regions. |
| |
| A linker script may contain at most one use of the @code{MEMORY} |
| command. However, you can define as many blocks of memory within it as |
| you wish. The syntax is: |
| @smallexample |
| @group |
| MEMORY |
| @{ |
| @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len} |
| @dots{} |
| @} |
| @end group |
| @end smallexample |
| |
| The @var{name} is a name used in the linker script to refer to the |
| region. The region name has no meaning outside of the linker script. |
| Region names are stored in a separate name space, and will not conflict |
| with symbol names, file names, or section names. Each memory region |
| must have a distinct name. |
| |
| @cindex memory region attributes |
| The @var{attr} string is an optional list of attributes that specify |
| whether to use a particular memory region for an input section which is |
| not explicitly mapped in the linker script. As described in |
| @ref{SECTIONS}, if you do not specify an output section for some input |
| section, the linker will create an output section with the same name as |
| the input section. If you define region attributes, the linker will use |
| them to select the memory region for the output section that it creates. |
| |
| The @var{attr} string must consist only of the following characters: |
| @table @samp |
| @item R |
| Read-only section |
| @item W |
| Read/write section |
| @item X |
| Executable section |
| @item A |
| Allocatable section |
| @item I |
| Initialized section |
| @item L |
| Same as @samp{I} |
| @item ! |
| Invert the sense of any of the preceding attributes |
| @end table |
| |
| If a unmapped section matches any of the listed attributes other than |
| @samp{!}, it will be placed in the memory region. The @samp{!} |
| attribute reverses this test, so that an unmapped section will be placed |
| in the memory region only if it does not match any of the listed |
| attributes. |
| |
| @kindex ORIGIN = |
| @kindex o = |
| @kindex org = |
| The @var{origin} is an expression for the start address of the memory |
| region. The expression must evaluate to a constant before memory |
| allocation is performed, which means that you may not use any section |
| relative symbols. The keyword @code{ORIGIN} may be abbreviated to |
| @code{org} or @code{o} (but not, for example, @code{ORG}). |
| |
| @kindex LENGTH = |
| @kindex len = |
| @kindex l = |
| The @var{len} is an expression for the size in bytes of the memory |
| region. As with the @var{origin} expression, the expression must |
| evaluate to a constant before memory allocation is performed. The |
| keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}. |
| |
| In the following example, we specify that there are two memory regions |
| available for allocation: one starting at @samp{0} for 256 kilobytes, |
| and the other starting at @samp{0x40000000} for four megabytes. The |
| linker will place into the @samp{rom} memory region every section which |
| is not explicitly mapped into a memory region, and is either read-only |
| or executable. The linker will place other sections which are not |
| explicitly mapped into a memory region into the @samp{ram} memory |
| region. |
| |
| @smallexample |
| @group |
| MEMORY |
| @{ |
| rom (rx) : ORIGIN = 0, LENGTH = 256K |
| ram (!rx) : org = 0x40000000, l = 4M |
| @} |
| @end group |
| @end smallexample |
| |
| Once you define a memory region, you can direct the linker to place |
| specific output sections into that memory region by using the |
| @samp{>@var{region}} output section attribute. For example, if you have |
| a memory region named @samp{mem}, you would use @samp{>mem} in the |
| output section definition. @xref{Output Section Region}. If no address |
| was specified for the output section, the linker will set the address to |
| the next available address within the memory region. If the combined |
| output sections directed to a memory region are too large for the |
| region, the linker will issue an error message. |
| |
| @node PHDRS |
| @section PHDRS Command |
| @kindex PHDRS |
| @cindex program headers |
| @cindex ELF program headers |
| @cindex program segments |
| @cindex segments, ELF |
| The ELF object file format uses @dfn{program headers}, also knows as |
| @dfn{segments}. The program headers describe how the program should be |
| loaded into memory. You can print them out by using the @code{objdump} |
| program with the @samp{-p} option. |
| |
| When you run an ELF program on a native ELF system, the system loader |
| reads the program headers in order to figure out how to load the |
| program. This will only work if the program headers are set correctly. |
| This manual does not describe the details of how the system loader |
| interprets program headers; for more information, see the ELF ABI. |
| |
| The linker will create reasonable program headers by default. However, |
| in some cases, you may need to specify the program headers more |
| precisely. You may use the @code{PHDRS} command for this purpose. When |
| the linker sees the @code{PHDRS} command in the linker script, it will |
| not create any program headers other than the ones specified. |
| |
| The linker only pays attention to the @code{PHDRS} command when |
| generating an ELF output file. In other cases, the linker will simply |
| ignore @code{PHDRS}. |
| |
| This is the syntax of the @code{PHDRS} command. The words @code{PHDRS}, |
| @code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords. |
| |
| @smallexample |
| @group |
| PHDRS |
| @{ |
| @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ] |
| [ FLAGS ( @var{flags} ) ] ; |
| @} |
| @end group |
| @end smallexample |
| |
| The @var{name} is used only for reference in the @code{SECTIONS} command |
| of the linker script. It is not put into the output file. Program |
| header names are stored in a separate name space, and will not conflict |
| with symbol names, file names, or section names. Each program header |
| must have a distinct name. |
| |
| Certain program header types describe segments of memory which the |
| system loader will load from the file. In the linker script, you |
| specify the contents of these segments by placing allocatable output |
| sections in the segments. You use the @samp{:@var{phdr}} output section |
| attribute to place a section in a particular segment. @xref{Output |
| Section Phdr}. |
| |
| It is normal to put certain sections in more than one segment. This |
| merely implies that one segment of memory contains another. You may |
| repeat @samp{:@var{phdr}}, using it once for each segment which should |
| contain the section. |
| |
| If you place a section in one or more segments using @samp{:@var{phdr}}, |
| then the linker will place all subsequent allocatable sections which do |
| not specify @samp{:@var{phdr}} in the same segments. This is for |
| convenience, since generally a whole set of contiguous sections will be |
| placed in a single segment. You can use @code{:NONE} to override the |
| default segment and tell the linker to not put the section in any |
| segment at all. |
| |
| @kindex FILEHDR |
| @kindex PHDRS |
| You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after |
| the program header type to further describe the contents of the segment. |
| The @code{FILEHDR} keyword means that the segment should include the ELF |
| file header. The @code{PHDRS} keyword means that the segment should |
| include the ELF program headers themselves. |
| |
| The @var{type} may be one of the following. The numbers indicate the |
| value of the keyword. |
| |
| @table @asis |
| @item @code{PT_NULL} (0) |
| Indicates an unused program header. |
| |
| @item @code{PT_LOAD} (1) |
| Indicates that this program header describes a segment to be loaded from |
| the file. |
| |
| @item @code{PT_DYNAMIC} (2) |
| Indicates a segment where dynamic linking information can be found. |
| |
| @item @code{PT_INTERP} (3) |
| Indicates a segment where the name of the program interpreter may be |
| found. |
| |
| @item @code{PT_NOTE} (4) |
| Indicates a segment holding note information. |
| |
| @item @code{PT_SHLIB} (5) |
| A reserved program header type, defined but not specified by the ELF |
| ABI. |
| |
| @item @code{PT_PHDR} (6) |
| Indicates a segment where the program headers may be found. |
| |
| @item @var{expression} |
| An expression giving the numeric type of the program header. This may |
| be used for types not defined above. |
| @end table |
| |
| You can specify that a segment should be loaded at a particular address |
| in memory by using an @code{AT} expression. This is identical to the |
| @code{AT} command used as an output section attribute (@pxref{Output |
| Section LMA}). The @code{AT} command for a program header overrides the |
| output section attribute. |
| |
| The linker will normally set the segment flags based on the sections |
| which comprise the segment. You may use the @code{FLAGS} keyword to |
| explicitly specify the segment flags. The value of @var{flags} must be |
| an integer. It is used to set the @code{p_flags} field of the program |
| header. |
| |
| Here is an example of @code{PHDRS}. This shows a typical set of program |
| headers used on a native ELF system. |
| |
| @example |
| @group |
| PHDRS |
| @{ |
| headers PT_PHDR PHDRS ; |
| interp PT_INTERP ; |
| text PT_LOAD FILEHDR PHDRS ; |
| data PT_LOAD ; |
| dynamic PT_DYNAMIC ; |
| @} |
| |
| SECTIONS |
| @{ |
| . = SIZEOF_HEADERS; |
| .interp : @{ *(.interp) @} :text :interp |
| .text : @{ *(.text) @} :text |
| .rodata : @{ *(.rodata) @} /* defaults to :text */ |
| @dots{} |
| . = . + 0x1000; /* move to a new page in memory */ |
| .data : @{ *(.data) @} :data |
| .dynamic : @{ *(.dynamic) @} :data :dynamic |
| @dots{} |
| @} |
| @end group |
| @end example |
| |
| @node VERSION |
| @section VERSION Command |
| @kindex VERSION @{script text@} |
| @cindex symbol versions |
| @cindex version script |
| @cindex versions of symbols |
| The linker supports symbol versions when using ELF. Symbol versions are |
| only useful when using shared libraries. The dynamic linker can use |
| symbol versions to select a specific version of a function when it runs |
| a program that may have been linked against an earlier version of the |
| shared library. |
| |
| You can include a version script directly in the main linker script, or |
| you can supply the version script as an implicit linker script. You can |
| also use the @samp{--version-script} linker option. |
| |
| The syntax of the @code{VERSION} command is simply |
| @smallexample |
| VERSION @{ version-script-commands @} |
| @end smallexample |
| |
| The format of the version script commands is identical to that used by |
| Sun's linker in Solaris 2.5. The version script defines a tree of |
| version nodes. You specify the node names and interdependencies in the |
| version script. You can specify which symbols are bound to which |
| version nodes, and you can reduce a specified set of symbols to local |
| scope so that they are not globally visible outside of the shared |
| library. |
| |
| The easiest way to demonstrate the version script language is with a few |
| examples. |
| |
| @smallexample |
| VERS_1.1 @{ |
| global: |
| foo1; |
| local: |
| old*; |
| original*; |
| new*; |
| @}; |
| |
| VERS_1.2 @{ |
| foo2; |
| @} VERS_1.1; |
| |
| VERS_2.0 @{ |
| bar1; bar2; |
| @} VERS_1.2; |
| @end smallexample |
| |
| This example version script defines three version nodes. The first |
| version node defined is @samp{VERS_1.1}; it has no other dependencies. |
| The script binds the symbol @samp{foo1} to @samp{VERS_1.1}. It reduces |
| a number of symbols to local scope so that they are not visible outside |
| of the shared library. |
| |
| Next, the version script defines node @samp{VERS_1.2}. This node |
| depends upon @samp{VERS_1.1}. The script binds the symbol @samp{foo2} |
| to the version node @samp{VERS_1.2}. |
| |
| Finally, the version script defines node @samp{VERS_2.0}. This node |
| depends upon @samp{VERS_1.2}. The scripts binds the symbols @samp{bar1} |
| and @samp{bar2} are bound to the version node @samp{VERS_2.0}. |
| |
| When the linker finds a symbol defined in a library which is not |
| specifically bound to a version node, it will effectively bind it to an |
| unspecified base version of the library. You can bind all otherwise |
| unspecified symbols to a given version node by using @samp{global: *} |
| somewhere in the version script. |
| |
| The names of the version nodes have no specific meaning other than what |
| they might suggest to the person reading them. The @samp{2.0} version |
| could just as well have appeared in between @samp{1.1} and @samp{1.2}. |
| However, this would be a confusing way to write a version script. |
| |
| When you link an application against a shared library that has versioned |
| symbols, the application itself knows which version of each symbol it |
| requires, and it also knows which version nodes it needs from each |
| shared library it is linked against. Thus at runtime, the dynamic |
| loader can make a quick check to make sure that the libraries you have |
| linked against do in fact supply all of the version nodes that the |
| application will need to resolve all of the dynamic symbols. In this |
| way it is possible for the dynamic linker to know with certainty that |
| all external symbols that it needs will be resolvable without having to |
| search for each symbol reference. |
| |
| The symbol versioning is in effect a much more sophisticated way of |
| doing minor version checking that SunOS does. The fundamental problem |
| that is being addressed here is that typically references to external |
| functions are bound on an as-needed basis, and are not all bound when |
| the application starts up. If a shared library is out of date, a |
| required interface may be missing; when the application tries to use |
| that interface, it may suddenly and unexpectedly fail. With symbol |
| versioning, the user will get a warning when they start their program if |
| the libraries being used with the application are too old. |
| |
| There are several GNU extensions to Sun's versioning approach. The |
| first of these is the ability to bind a symbol to a version node in the |
| source file where the symbol is defined instead of in the versioning |
| script. This was done mainly to reduce the burden on the library |
| maintainer. You can do this by putting something like: |
| @smallexample |
| __asm__(".symver original_foo,foo@@VERS_1.1"); |
| @end smallexample |
| @noindent |
| in the C source file. This renames the function @samp{original_foo} to |
| be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}. |
| The @samp{local:} directive can be used to prevent the symbol |
| @samp{original_foo} from being exported. |
| |
| The second GNU extension is to allow multiple versions of the same |
| function to appear in a given shared library. In this way you can make |
| an incompatible change to an interface without increasing the major |
| version number of the shared library, while still allowing applications |
| linked against the old interface to continue to function. |
| |
| To do this, you must use multiple @samp{.symver} directives in the |
| source file. Here is an example: |
| |
| @smallexample |
| __asm__(".symver original_foo,foo@@"); |
| __asm__(".symver old_foo,foo@@VERS_1.1"); |
| __asm__(".symver old_foo1,foo@@VERS_1.2"); |
| __asm__(".symver new_foo,foo@@@@VERS_2.0"); |
| @end smallexample |
| |
| In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the |
| unspecified base version of the symbol. The source file that contains this |
| example would define 4 C functions: @samp{original_foo}, @samp{old_foo}, |
| @samp{old_foo1}, and @samp{new_foo}. |
| |
| When you have multiple definitions of a given symbol, there needs to be |
| some way to specify a default version to which external references to |
| this symbol will be bound. You can do this with the |
| @samp{foo@@@@VERS_2.0} type of @samp{.symver} directive. You can only |
| declare one version of a symbol as the default in this manner; otherwise |
| you would effectively have multiple definitions of the same symbol. |
| |
| If you wish to bind a reference to a specific version of the symbol |
| within the shared library, you can use the aliases of convenience |
| (i.e. @samp{old_foo}), or you can use the @samp{.symver} directive to |
| specifically bind to an external version of the function in question. |
| |
| @node Expressions |
| @section Expressions in Linker Scripts |
| @cindex expressions |
| @cindex arithmetic |
| The syntax for expressions in the linker script language is identical to |
| that of C expressions. All expressions are evaluated as integers. All |
| expressions are evaluated in the same size, which is 32 bits if both the |
| host and target are 32 bits, and is otherwise 64 bits. |
| |
| You can use and set symbol values in expressions. |
| |
| The linker defines several special purpose builtin functions for use in |
| expressions. |
| |
| @menu |
| * Constants:: Constants |
| * Symbols:: Symbol Names |
| * Location Counter:: The Location Counter |
| * Operators:: Operators |
| * Evaluation:: Evaluation |
| * Expression Section:: The Section of an Expression |
| * Builtin Functions:: Builtin Functions |
| @end menu |
| |
| @node Constants |
| @subsection Constants |
| @cindex integer notation |
| @cindex constants in linker scripts |
| All constants are integers. |
| |
| As in C, the linker considers an integer beginning with @samp{0} to be |
| octal, and an integer beginning with @samp{0x} or @samp{0X} to be |
| hexadecimal. The linker considers other integers to be decimal. |
| |
| @cindex scaled integers |
| @cindex K and M integer suffixes |
| @cindex M and K integer suffixes |
| @cindex suffixes for integers |
| @cindex integer suffixes |
| In addition, you can use the suffixes @code{K} and @code{M} to scale a |
| constant by |
| @c TEXI2ROFF-KILL |
| @ifinfo |
| @c END TEXI2ROFF-KILL |
| @code{1024} or @code{1024*1024} |
| @c TEXI2ROFF-KILL |
| @end ifinfo |
| @tex |
| ${\rm 1024}$ or ${\rm 1024}^2$ |
| @end tex |
| @c END TEXI2ROFF-KILL |
| respectively. For example, the following all refer to the same quantity: |
| @smallexample |
| _fourk_1 = 4K; |
| _fourk_2 = 4096; |
| _fourk_3 = 0x1000; |
| @end smallexample |
| |
| @node Symbols |
| @subsection Symbol Names |
| @cindex symbol names |
| @cindex names |
| @cindex quoted symbol names |
| @kindex " |
| Unless quoted, symbol names start with a letter, underscore, or period |
| and may include letters, digits, underscores, periods, and hyphens. |
| Unquoted symbol names must not conflict with any keywords. You can |
| specify a symbol which contains odd characters or has the same name as a |
| keyword by surrounding the symbol name in double quotes: |
| @smallexample |
| "SECTION" = 9; |
| "with a space" = "also with a space" + 10; |
| @end smallexample |
| |
| Since symbols can contain many non-alphabetic characters, it is safest |
| to delimit symbols with spaces. For example, @samp{A-B} is one symbol, |
| whereas @samp{A - B} is an expression involving subtraction. |
| |
| @node Location Counter |
| @subsection The Location Counter |
| @kindex . |
| @cindex dot |
| @cindex location counter |
| @cindex current output location |
| The special linker variable @dfn{dot} @samp{.} always contains the |
| current output location counter. Since the @code{.} always refers to a |
| location in an output section, it may only appear in an expression |
| within a @code{SECTIONS} command. The @code{.} symbol may appear |
| anywhere that an ordinary symbol is allowed in an expression. |
| |
| @cindex holes |
| Assigning a value to @code{.} will cause the location counter to be |
| moved. This may be used to create holes in the output section. The |
| location counter may never be moved backwards. |
| |
| @smallexample |
| SECTIONS |
| @{ |
| output : |
| @{ |
| file1(.text) |
| . = . + 1000; |
| file2(.text) |
| . += 1000; |
| file3(.text) |
| @} = 0x1234; |
| @} |
| @end smallexample |
| @noindent |
| In the previous example, the @samp{.text} section from @file{file1} is |
| located at the beginning of the output section @samp{output}. It is |
| followed by a 1000 byte gap. Then the @samp{.text} section from |
| @file{file2} appears, also with a 1000 byte gap following before the |
| @samp{.text} section from @file{file3}. The notation @samp{= 0x1234} |
| specifies what data to write in the gaps (@pxref{Output Section Fill}). |
| |
| @need 2000 |
| @node Operators |
| @subsection Operators |
| @cindex operators for arithmetic |
| @cindex arithmetic operators |
| @cindex precedence in expressions |
| The linker recognizes the standard C set of arithmetic operators, with |
| the standard bindings and precedence levels: |
| @c TEXI2ROFF-KILL |
| @ifinfo |
| @c END TEXI2ROFF-KILL |
| @smallexample |
| precedence associativity Operators Notes |
| (highest) |
| 1 left ! - ~ (1) |
| 2 left * / % |
| 3 left + - |
| 4 left >> << |
| 5 left == != > < <= >= |
| 6 left & |
| 7 left | |
| 8 left && |
| 9 left || |
| 10 right ? : |
| 11 right &= += -= *= /= (2) |
| (lowest) |
| @end smallexample |
| Notes: |
| (1) Prefix operators |
| (2) @xref{Assignments}. |
| @c TEXI2ROFF-KILL |
| @end ifinfo |
| @tex |
| \vskip \baselineskip |
| %"lispnarrowing" is the extra indent used generally for smallexample |
| \hskip\lispnarrowing\vbox{\offinterlineskip |
| \hrule |
| \halign |
| {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr |
| height2pt&\omit&&\omit&&\omit&\cr |
| &Precedence&& Associativity &&{\rm Operators}&\cr |
| height2pt&\omit&&\omit&&\omit&\cr |
| \noalign{\hrule} |
| height2pt&\omit&&\omit&&\omit&\cr |
| &highest&&&&&\cr |
| % '176 is tilde, '~' in tt font |
| &1&&left&&\qquad- \char'176\ !\qquad\dag&\cr |
| &2&&left&&* / \%&\cr |
| &3&&left&&+ -&\cr |
| &4&&left&&>> <<&\cr |
| &5&&left&&== != > < <= >=&\cr |
| &6&&left&&\&&\cr |
| &7&&left&&|&\cr |
| &8&&left&&{\&\&}&\cr |
| &9&&left&&||&\cr |
| &10&&right&&? :&\cr |
| &11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr |
| &lowest&&&&&\cr |
| height2pt&\omit&&\omit&&\omit&\cr} |
| \hrule} |
| @end tex |
| @iftex |
| { |
| @obeylines@parskip=0pt@parindent=0pt |
| @dag@quad Prefix operators. |
| @ddag@quad @xref{Assignments}. |
| } |
| @end iftex |
| @c END TEXI2ROFF-KILL |
| |
| @node Evaluation |
| @subsection Evaluation |
| @cindex lazy evaluation |
| @cindex expression evaluation order |
| The linker evaluates expressions lazily. It only computes the value of |
| an expression when absolutely necessary. |
| |
| The linker needs some information, such as the value of the start |
| address of the first section, and the origins and lengths of memory |
| regions, in order to do any linking at all. These values are computed |
| as soon as possible when the linker reads in the linker script. |
| |
| However, other values (such as symbol values) are not known or needed |
| until after storage allocation. Such values are evaluated later, when |
| other information (such as the sizes of output sections) is available |
| for use in the symbol assignment expression. |
| |
| The sizes of sections cannot be known until after allocation, so |
| assignments dependent upon these are not performed until after |
| allocation. |
| |
| Some expressions, such as those depending upon the location counter |
| @samp{.}, must be evaluated during section allocation. |
| |
| If the result of an expression is required, but the value is not |
| available, then an error results. For example, a script like the |
| following |
| @smallexample |
| @group |
| SECTIONS |
| @{ |
| .text 9+this_isnt_constant : |
| @{ *(.text) @} |
| @} |
| @end group |
| @end smallexample |
| @noindent |
| will cause the error message @samp{non constant expression for initial |
| address}. |
| |
| @node Expression Section |
| @subsection The Section of an Expression |
| @cindex expression sections |
| @cindex absolute expressions |
| @cindex relative expressions |
| @cindex absolute and relocatable symbols |
| @cindex relocatable and absolute symbols |
| @cindex symbols, relocatable and absolute |
| When the linker evaluates an expression, the result is either absolute |
| or relative to some section. A relative expression is expressed as a |
| fixed offset from the base of a section. |
| |
| The position of the expression within the linker script determines |
| whether it is absolute or relative. An expression which appears within |
| an output section definition is relative to the base of the output |
| section. An expression which appears elsewhere will be absolute. |
| |
| A symbol set to a relative expression will be relocatable if you request |
| relocatable output using the @samp{-r} option. That means that a |
| further link operation may change the value of the symbol. The symbol's |
| section will be the section of the relative expression. |
| |
| A symbol set to an absolute expression will retain the same value |
| through any further link operation. The symbol will be absolute, and |
| will not have any particular associated section. |
| |
| You can use the builtin function @code{ABSOLUTE} to force an expression |
| to be absolute when it would otherwise be relative. For example, to |
| create an absolute symbol set to the address of the end of the output |
| section @samp{.data}: |
| @smallexample |
| SECTIONS |
| @{ |
| .data : @{ *(.data) _edata = ABSOLUTE(.); @} |
| @} |
| @end smallexample |
| @noindent |
| If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the |
| @samp{.data} section. |
| |
| @node Builtin Functions |
| @subsection Builtin Functions |
| @cindex functions in expressions |
| The linker script language includes a number of builtin functions for |
| use in linker script expressions. |
| |
| @table @code |
| @item ABSOLUTE(@var{exp}) |
| @kindex ABSOLUTE(@var{exp}) |
| @cindex expression, absolute |
| Return the absolute (non-relocatable, as opposed to non-negative) value |
| of the expression @var{exp}. Primarily useful to assign an absolute |
| value to a symbol within a section definition, where symbol values are |
| normally section relative. @xref{Expression Section}. |
| |
| @item ADDR(@var{section}) |
| @kindex ADDR(@var{section}) |
| @cindex section address in expression |
| Return the absolute address (the VMA) of the named @var{section}. Your |
| script must previously have defined the location of that section. In |
| the following example, @code{symbol_1} and @code{symbol_2} are assigned |
| identical values: |
| @smallexample |
| @group |
| SECTIONS @{ @dots{} |
| .output1 : |
| @{ |
| start_of_output_1 = ABSOLUTE(.); |
| @dots{} |
| @} |
| .output : |
| @{ |
| symbol_1 = ADDR(.output1); |
| symbol_2 = start_of_output_1; |
| @} |
| @dots{} @} |
| @end group |
| @end smallexample |
| |
| @item ALIGN(@var{exp}) |
| @kindex ALIGN(@var{exp}) |
| @cindex round up location counter |
| @cindex align location counter |
| Return the location counter (@code{.}) aligned to the next @var{exp} |
| boundary. @var{exp} must be an expression whose value is a power of |
| two. This is equivalent to |
| @smallexample |
| (. + @var{exp} - 1) & ~(@var{exp} - 1) |
| @end smallexample |
| |
| @code{ALIGN} doesn't change the value of the location counter---it just |
| does arithmetic on it. Here is an example which aligns the output |
| @code{.data} section to the next @code{0x2000} byte boundary after the |
| preceding section and sets a variable within the section to the next |
| @code{0x8000} boundary after the input sections: |
| @smallexample |
| @group |
| SECTIONS @{ @dots{} |
| .data ALIGN(0x2000): @{ |
| *(.data) |
| variable = ALIGN(0x8000); |
| @} |
| @dots{} @} |
| @end group |
| @end smallexample |
| @noindent |
| The first use of @code{ALIGN} in this example specifies the location of |
| a section because it is used as the optional @var{address} attribute of |
| a section definition (@pxref{Output Section Address}). The second use |
| of @code{ALIGN} is used to defines the value of a symbol. |
| |
| The builtin function @code{NEXT} is closely related to @code{ALIGN}. |
| |
| @item BLOCK(@var{exp}) |
| @kindex BLOCK(@var{exp}) |
| This is a synonym for @code{ALIGN}, for compatibility with older linker |
| scripts. It is most often seen when setting the address of an output |
| section. |
| |
| @item DEFINED(@var{symbol}) |
| @kindex DEFINED(@var{symbol}) |
| @cindex symbol defaults |
| Return 1 if @var{symbol} is in the linker global symbol table and is |
| defined, otherwise return 0. You can use this function to provide |
| default values for symbols. For example, the following script fragment |
| shows how to set a global symbol @samp{begin} to the first location in |
| the @samp{.text} section---but if a symbol called @samp{begin} already |
| existed, its value is preserved: |
| |
| @smallexample |
| @group |
| SECTIONS @{ @dots{} |
| .text : @{ |
| begin = DEFINED(begin) ? begin : . ; |
| @dots{} |
| @} |
| @dots{} |
| @} |
| @end group |
| @end smallexample |
| |
| @item LOADADDR(@var{section}) |
| @kindex LOADADDR(@var{section}) |
| @cindex section load address in expression |
| Return the absolute LMA of the named @var{section}. This is normally |
| the same as @code{ADDR}, but it may be different if the @code{AT} |
| attribute is used in the output section definition (@pxref{Output |
| Section LMA}). |
| |
| @kindex MAX |
| @item MAX(@var{exp1}, @var{exp2}) |
| Returns the maximum of @var{exp1} and @var{exp2}. |
| |
| @kindex MIN |
| @item MIN(@var{exp1}, @var{exp2}) |
| Returns the minimum of @var{exp1} and @var{exp2}. |
| |
| @item NEXT(@var{exp}) |
| @kindex NEXT(@var{exp}) |
| @cindex unallocated address, next |
| Return the next unallocated address that is a multiple of @var{exp}. |
| This function is closely related to @code{ALIGN(@var{exp})}; unless you |
| use the @code{MEMORY} command to define discontinuous memory for the |
| output file, the two functions are equivalent. |
| |
| @item SIZEOF(@var{section}) |
| @kindex SIZEOF(@var{section}) |
| @cindex section size |
| Return the size in bytes of the named @var{section}, if that section has |
| been allocated. If the section has not been allocated when this is |
| evaluated, the linker will report an error. In the following example, |
| @code{symbol_1} and @code{symbol_2} are assigned identical values: |
| @smallexample |
| @group |
| SECTIONS@{ @dots{} |
| .output @{ |
| .start = . ; |
| @dots{} |
| .end = . ; |
| @} |
| symbol_1 = .end - .start ; |
| symbol_2 = SIZEOF(.output); |
| @dots{} @} |
| @end group |
| @end smallexample |
| |
| @item SIZEOF_HEADERS |
| @itemx sizeof_headers |
| @kindex SIZEOF_HEADERS |
| @cindex header size |
| Return the size in bytes of the output file's headers. This is |
| information which appears at the start of the output file. You can use |
| this number when setting the start address of the first section, if you |
| choose, to facilitate paging. |
| |
| @cindex not enough room for program headers |
| @cindex program headers, not enough room |
| When producing an ELF output file, if the linker script uses the |
| @code{SIZEOF_HEADERS} builtin function, the linker must compute the |
| number of program headers before it has determined all the section |
| addresses and sizes. If the linker later discovers that it needs |
| additional program headers, it will report an error @samp{not enough |
| room for program headers}. To avoid this error, you must avoid using |
| the @code{SIZEOF_HEADERS} function, or you must rework your linker |
| script to avoid forcing the linker to use additional program headers, or |
| you must define the program headers yourself using the @code{PHDRS} |
| command (@pxref{PHDRS}). |
| @end table |
| |
| @node Implicit Linker Scripts |
| @section Implicit Linker Scripts |
| @cindex implicit linker scripts |
| If you specify a linker input file which the linker can not recognize as |
| an object file or an archive file, it will try to read the file as a |
| linker script. If the file can not be parsed as a linker script, the |
| linker will report an error. |
| |
| An implicit linker script will not replace the default linker script. |
| |
| Typically an implicit linker script would contain only symbol |
| assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION} |
| commands. |
| |
| Any input files read because of an implicit linker script will be read |
| at the position in the command line where the implicit linker script was |
| read. This can affect archive searching. |
| |
| @ifset GENERIC |
| @node Machine Dependent |
| @chapter Machine Dependent Features |
| |
| @cindex machine dependencies |
| @code{ld} has additional features on some platforms; the following |
| sections describe them. Machines where @code{ld} has no additional |
| functionality are not listed. |
| |
| @menu |
| * H8/300:: @code{ld} and the H8/300 |
| * i960:: @code{ld} and the Intel 960 family |
| * ARM:: @code{ld} and the ARM family |
| @end menu |
| @end ifset |
| |
| @c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict |
| @c between those and node-defaulting. |
| @ifset H8300 |
| @ifclear GENERIC |
| @raisesections |
| @end ifclear |
| |
| @node H8/300 |
| @section @code{ld} and the H8/300 |
| |
| @cindex H8/300 support |
| For the H8/300, @code{ld} can perform these global optimizations when |
| you specify the @samp{--relax} command-line option. |
| |
| @table @emph |
| @cindex relaxing on H8/300 |
| @item relaxing address modes |
| @code{ld} finds all @code{jsr} and @code{jmp} instructions whose |
| targets are within eight bits, and turns them into eight-bit |
| program-counter relative @code{bsr} and @code{bra} instructions, |
| respectively. |
| |
| @cindex synthesizing on H8/300 |
| @item synthesizing instructions |
| @c FIXME: specifically mov.b, or any mov instructions really? |
| @code{ld} finds all @code{mov.b} instructions which use the |
| sixteen-bit absolute address form, but refer to the top |
| page of memory, and changes them to use the eight-bit address form. |
| (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into |
| @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the |
| top page of memory). |
| @end table |
| |
| @ifclear GENERIC |
| @lowersections |
| @end ifclear |
| @end ifset |
| |
| @ifclear GENERIC |
| @ifset Hitachi |
| @c This stuff is pointless to say unless you're especially concerned |
| @c with Hitachi chips; don't enable it for generic case, please. |
| @node Hitachi |
| @chapter @code{ld} and other Hitachi chips |
| |
| @code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No |
| special features, commands, or command-line options are required for |
| these chips. |
| @end ifset |
| @end ifclear |
| |
| @ifset I960 |
| @ifclear GENERIC |
| @raisesections |
| @end ifclear |
| |
| @node i960 |
| @section @code{ld} and the Intel 960 family |
| |
| @cindex i960 support |
| |
| You can use the @samp{-A@var{architecture}} command line option to |
| specify one of the two-letter names identifying members of the 960 |
| family; the option specifies the desired output target, and warns of any |
| incompatible instructions in the input files. It also modifies the |
| linker's search strategy for archive libraries, to support the use of |
| libraries specific to each particular architecture, by including in the |
| search loop names suffixed with the string identifying the architecture. |
| |
| For example, if your @code{ld} command line included @w{@samp{-ACA}} as |
| well as @w{@samp{-ltry}}, the linker would look (in its built-in search |
| paths, and in any paths you specify with @samp{-L}) for a library with |
| the names |
| |
| @smallexample |
| @group |
| try |
| libtry.a |
| tryca |
| libtryca.a |
| @end group |
| @end smallexample |
| |
| @noindent |
| The first two possibilities would be considered in any event; the last |
| two are due to the use of @w{@samp{-ACA}}. |
| |
| You can meaningfully use @samp{-A} more than once on a command line, since |
| the 960 architecture family allows combination of target architectures; each |
| use will add another pair of name variants to search for when @w{@samp{-l}} |
| specifies a library. |
| |
| @cindex @code{--relax} on i960 |
| @cindex relaxing on i960 |
| @code{ld} supports the @samp{--relax} option for the i960 family. If |
| you specify @samp{--relax}, @code{ld} finds all @code{balx} and |
| @code{calx} instructions whose targets are within 24 bits, and turns |
| them into 24-bit program-counter relative @code{bal} and @code{cal} |
| instructions, respectively. @code{ld} also turns @code{cal} |
| instructions into @code{bal} instructions when it determines that the |
| target subroutine is a leaf routine (that is, the target subroutine does |
| not itself call any subroutines). |
| |
| @ifclear GENERIC |
| @lowersections |
| @end ifclear |
| @end ifset |
| |
| @ifclear GENERIC |
| @raisesections |
| @end ifclear |
| |
| @node ARM |
| @section @code{ld}'s support for interworking between ARM and Thumb code |
| |
| @cindex ARM interworking support |
| @cindex --support-old-code |
| For the ARM, @code{ld} will generate code stubs to allow functions calls |
| betweem ARM and Thumb code. These stubs only work with code that has |
| been compiled and assembled with the @samp{-mthumb-interwork} command |
| line option. If it is necessary to link with old ARM object files or |
| libraries, which have not been compiled with the -mthumb-interwork |
| option then the @samp{--support-old-code} command line switch should be |
| given to the linker. This will make it generate larger stub functions |
| which will work with non-interworking aware ARM code. Note, however, |
| the linker does not support generating stubs for function calls to |
| non-interworking aware Thumb code. |
| |
| @ifclear GENERIC |
| @lowersections |
| @end ifclear |
| |
| @ifclear SingleFormat |
| @node BFD |
| @chapter BFD |
| |
| @cindex back end |
| @cindex object file management |
| @cindex object formats available |
| @kindex objdump -i |
| The linker accesses object and archive files using the BFD libraries. |
| These libraries allow the linker to use the same routines to operate on |
| object files whatever the object file format. A different object file |
| format can be supported simply by creating a new BFD back end and adding |
| it to the library. To conserve runtime memory, however, the linker and |
| associated tools are usually configured to support only a subset of the |
| object file formats available. You can use @code{objdump -i} |
| (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to |
| list all the formats available for your configuration. |
| |
| @cindex BFD requirements |
| @cindex requirements for BFD |
| As with most implementations, BFD is a compromise between |
| several conflicting requirements. The major factor influencing |
| BFD design was efficiency: any time used converting between |
| formats is time which would not have been spent had BFD not |
| been involved. This is partly offset by abstraction payback; since |
| BFD simplifies applications and back ends, more time and care |
| may be spent optimizing algorithms for a greater speed. |
| |
| One minor artifact of the BFD solution which you should bear in |
| mind is the potential for information loss. There are two places where |
| useful information can be lost using the BFD mechanism: during |
| conversion and during output. @xref{BFD information loss}. |
| |
| @menu |
| * BFD outline:: How it works: an outline of BFD |
| @end menu |
| |
| @node BFD outline |
| @section How it works: an outline of BFD |
| @cindex opening object files |
| @include bfdsumm.texi |
| @end ifclear |
| |
| @node Reporting Bugs |
| @chapter Reporting Bugs |
| @cindex bugs in @code{ld} |
| @cindex reporting bugs in @code{ld} |
| |
| Your bug reports play an essential role in making @code{ld} reliable. |
| |
| Reporting a bug may help you by bringing a solution to your problem, or |
| it may not. But in any case the principal function of a bug report is |
| to help the entire community by making the next version of @code{ld} |
| work better. Bug reports are your contribution to the maintenance of |
| @code{ld}. |
| |
| In order for a bug report to serve its purpose, you must include the |
| information that enables us to fix the bug. |
| |
| @menu |
| * Bug Criteria:: Have you found a bug? |
| * Bug Reporting:: How to report bugs |
| @end menu |
| |
| @node Bug Criteria |
| @section Have you found a bug? |
| @cindex bug criteria |
| |
| If you are not sure whether you have found a bug, here are some guidelines: |
| |
| @itemize @bullet |
| @cindex fatal signal |
| @cindex linker crash |
| @cindex crash of linker |
| @item |
| If the linker gets a fatal signal, for any input whatever, that is a |
| @code{ld} bug. Reliable linkers never crash. |
| |
| @cindex error on valid input |
| @item |
| If @code{ld} produces an error message for valid input, that is a bug. |
| |
| @cindex invalid input |
| @item |
| If @code{ld} does not produce an error message for invalid input, that |
| may be a bug. In the general case, the linker can not verify that |
| object files are correct. |
| |
| @item |
| If you are an experienced user of linkers, your suggestions for |
| improvement of @code{ld} are welcome in any case. |
| @end itemize |
| |
| @node Bug Reporting |
| @section How to report bugs |
| @cindex bug reports |
| @cindex @code{ld} bugs, reporting |
| |
| A number of companies and individuals offer support for @sc{gnu} |
| products. If you obtained @code{ld} from a support organization, we |
| recommend you contact that organization first. |
| |
| You can find contact information for many support companies and |
| individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs |
| distribution. |
| |
| Otherwise, send bug reports for @code{ld} to |
| @samp{bug-gnu-utils@@gnu.org}. |
| |
| The fundamental principle of reporting bugs usefully is this: |
| @strong{report all the facts}. If you are not sure whether to state a |
| fact or leave it out, state it! |
| |
| Often people omit facts because they think they know what causes the |
| problem and assume that some details do not matter. Thus, you might |
| assume that the name of a symbol you use in an example does not matter. |
| Well, probably it does not, but one cannot be sure. Perhaps the bug is |
| a stray memory reference which happens to fetch from the location where |
| that name is stored in memory; perhaps, if the name were different, the |
| contents of that location would fool the linker into doing the right |
| thing despite the bug. Play it safe and give a specific, complete |
| example. That is the easiest thing for you to do, and the most helpful. |
| |
| Keep in mind that the purpose of a bug report is to enable us to fix the bug if |
| it is new to us. Therefore, always write your bug reports on the assumption |
| that the bug has not been reported previously. |
| |
| Sometimes people give a few sketchy facts and ask, ``Does this ring a |
| bell?'' Those bug reports are useless, and we urge everyone to |
| @emph{refuse to respond to them} except to chide the sender to report |
| bugs properly. |
| |
| To enable us to fix the bug, you should include all these things: |
| |
| @itemize @bullet |
| @item |
| The version of @code{ld}. @code{ld} announces it if you start it with |
| the @samp{--version} argument. |
| |
| Without this, we will not know whether there is any point in looking for |
| the bug in the current version of @code{ld}. |
| |
| @item |
| Any patches you may have applied to the @code{ld} source, including any |
| patches made to the @code{BFD} library. |
| |
| @item |
| The type of machine you are using, and the operating system name and |
| version number. |
| |
| @item |
| What compiler (and its version) was used to compile @code{ld}---e.g. |
| ``@code{gcc-2.7}''. |
| |
| @item |
| The command arguments you gave the linker to link your example and |
| observe the bug. To guarantee you will not omit something important, |
| list them all. A copy of the Makefile (or the output from make) is |
| sufficient. |
| |
| If we were to try to guess the arguments, we would probably guess wrong |
| and then we might not encounter the bug. |
| |
| @item |
| A complete input file, or set of input files, that will reproduce the |
| bug. It is generally most helpful to send the actual object files, |
| uuencoded if necessary to get them through the mail system. Making them |
| available for anonymous FTP is not as good, but may be the only |
| reasonable choice for large object files. |
| |
| If the source files were assembled using @code{gas} or compiled using |
| @code{gcc}, then it may be OK to send the source files rather than the |
| object files. In this case, be sure to say exactly what version of |
| @code{gas} or @code{gcc} was used to produce the object files. Also say |
| how @code{gas} or @code{gcc} were configured. |
| |
| @item |
| A description of what behavior you observe that you believe is |
| incorrect. For example, ``It gets a fatal signal.'' |
| |
| Of course, if the bug is that @code{ld} gets a fatal signal, then we |
| will certainly notice it. But if the bug is incorrect output, we might |
| not notice unless it is glaringly wrong. You might as well not give us |
| a chance to make a mistake. |
| |
| Even if the problem you experience is a fatal signal, you should still |
| say so explicitly. Suppose something strange is going on, such as, your |
| copy of @code{ld} is out of synch, or you have encountered a bug in the |
| C library on your system. (This has happened!) Your copy might crash |
| and ours would not. If you told us to expect a crash, then when ours |
| fails to crash, we would know that the bug was not happening for us. If |
| you had not told us to expect a crash, then we would not be able to draw |
| any conclusion from our observations. |
| |
| @item |
| If you wish to suggest changes to the @code{ld} source, send us context |
| diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or |
| @samp{-p} option. Always send diffs from the old file to the new file. |
| If you even discuss something in the @code{ld} source, refer to it by |
| context, not by line number. |
| |
| The line numbers in our development sources will not match those in your |
| sources. Your line numbers would convey no useful information to us. |
| @end itemize |
| |
| Here are some things that are not necessary: |
| |
| @itemize @bullet |
| @item |
| A description of the envelope of the bug. |
| |
| Often people who encounter a bug spend a lot of time investigating |
| which changes to the input file will make the bug go away and which |
| changes will not affect it. |
| |
| This is often time consuming and not very useful, because the way we |
| will find the bug is by running a single example under the debugger |
| with breakpoints, not by pure deduction from a series of examples. |
| We recommend that you save your time for something else. |
| |
| Of course, if you can find a simpler example to report @emph{instead} |
| of the original one, that is a convenience for us. Errors in the |
| output will be easier to spot, running under the debugger will take |
| less time, and so on. |
| |
| However, simplification is not vital; if you do not want to do this, |
| report the bug anyway and send us the entire test case you used. |
| |
| @item |
| A patch for the bug. |
| |
| A patch for the bug does help us if it is a good one. But do not omit |
| the necessary information, such as the test case, on the assumption that |
| a patch is all we need. We might see problems with your patch and decide |
| to fix the problem another way, or we might not understand it at all. |
| |
| Sometimes with a program as complicated as @code{ld} it is very hard to |
| construct an example that will make the program follow a certain path |
| through the code. If you do not send us the example, we will not be |
| able to construct one, so we will not be able to verify that the bug is |
| fixed. |
| |
| And if we cannot understand what bug you are trying to fix, or why your |
| patch should be an improvement, we will not install it. A test case will |
| help us to understand. |
| |
| @item |
| A guess about what the bug is or what it depends on. |
| |
| Such guesses are usually wrong. Even we cannot guess right about such |
| things without first using the debugger to find the facts. |
| @end itemize |
| |
| @node MRI |
| @appendix MRI Compatible Script Files |
| @cindex MRI compatibility |
| To aid users making the transition to @sc{gnu} @code{ld} from the MRI |
| linker, @code{ld} can use MRI compatible linker scripts as an |
| alternative to the more general-purpose linker scripting language |
| described in @ref{Scripts}. MRI compatible linker scripts have a much |
| simpler command set than the scripting language otherwise used with |
| @code{ld}. @sc{gnu} @code{ld} supports the most commonly used MRI |
| linker commands; these commands are described here. |
| |
| In general, MRI scripts aren't of much use with the @code{a.out} object |
| file format, since it only has three sections and MRI scripts lack some |
| features to make use of them. |
| |
| You can specify a file containing an MRI-compatible script using the |
| @samp{-c} command-line option. |
| |
| Each command in an MRI-compatible script occupies its own line; each |
| command line starts with the keyword that identifies the command (though |
| blank lines are also allowed for punctuation). If a line of an |
| MRI-compatible script begins with an unrecognized keyword, @code{ld} |
| issues a warning message, but continues processing the script. |
| |
| Lines beginning with @samp{*} are comments. |
| |
| You can write these commands using all upper-case letters, or all |
| lower case; for example, @samp{chip} is the same as @samp{CHIP}. |
| The following list shows only the upper-case form of each command. |
| |
| @table @code |
| @cindex @code{ABSOLUTE} (MRI) |
| @item ABSOLUTE @var{secname} |
| @itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname} |
| Normally, @code{ld} includes in the output file all sections from all |
| the input files. However, in an MRI-compatible script, you can use the |
| @code{ABSOLUTE} command to restrict the sections that will be present in |
| your output program. If the @code{ABSOLUTE} command is used at all in a |
| script, then only the sections named explicitly in @code{ABSOLUTE} |
| commands will appear in the linker output. You can still use other |
| input sections (whatever you select on the command line, or using |
| @code{LOAD}) to resolve addresses in the output file. |
| |
| @cindex @code{ALIAS} (MRI) |
| @item ALIAS @var{out-secname}, @var{in-secname} |
| Use this command to place the data from input section @var{in-secname} |
| in a section called @var{out-secname} in the linker output file. |
| |
| @var{in-secname} may be an integer. |
| |
| @cindex @code{ALIGN} (MRI) |
| @item ALIGN @var{secname} = @var{expression} |
| Align the section called @var{secname} to @var{expression}. The |
| @var{expression} should be a power of two. |
| |
| @cindex @code{BASE} (MRI) |
| @item BASE @var{expression} |
| Use the value of @var{expression} as the lowest address (other than |
| absolute addresses) in the output file. |
| |
| @cindex @code{CHIP} (MRI) |
| @item CHIP @var{expression} |
| @itemx CHIP @var{expression}, @var{expression} |
| This command does nothing; it is accepted only for compatibility. |
| |
| @cindex @code{END} (MRI) |
| @item END |
| This command does nothing whatever; it's only accepted for compatibility. |
| |
| @cindex @code{FORMAT} (MRI) |
| @item FORMAT @var{output-format} |
| Similar to the @code{OUTPUT_FORMAT} command in the more general linker |
| language, but restricted to one of these output formats: |
| |
| @enumerate |
| @item |
| S-records, if @var{output-format} is @samp{S} |
| |
| @item |
| IEEE, if @var{output-format} is @samp{IEEE} |
| |
| @item |
| COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is |
| @samp{COFF} |
| @end enumerate |
| |
| @cindex @code{LIST} (MRI) |
| @item LIST @var{anything}@dots{} |
| Print (to the standard output file) a link map, as produced by the |
| @code{ld} command-line option @samp{-M}. |
| |
| The keyword @code{LIST} may be followed by anything on the |
| same line, with no change in its effect. |
| |
| @cindex @code{LOAD} (MRI) |
| @item LOAD @var{filename} |
| @itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename} |
| Include one or more object file @var{filename} in the link; this has the |
| same effect as specifying @var{filename} directly on the @code{ld} |
| command line. |
| |
| @cindex @code{NAME} (MRI) |
| @item NAME @var{output-name} |
| @var{output-name} is the name for the program produced by @code{ld}; the |
| MRI-compatible command @code{NAME} is equivalent to the command-line |
| option @samp{-o} or the general script language command @code{OUTPUT}. |
| |
| @cindex @code{ORDER} (MRI) |
| @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname} |
| @itemx ORDER @var{secname} @var{secname} @var{secname} |
| Normally, @code{ld} orders the sections in its output file in the |
| order in which they first appear in the input files. In an MRI-compatible |
| script, you can override this ordering with the @code{ORDER} command. The |
| sections you list with @code{ORDER} will appear first in your output |
| file, in the order specified. |
| |
| @cindex @code{PUBLIC} (MRI) |
| @item PUBLIC @var{name}=@var{expression} |
| @itemx PUBLIC @var{name},@var{expression} |
| @itemx PUBLIC @var{name} @var{expression} |
| Supply a value (@var{expression}) for external symbol |
| @var{name} used in the linker input files. |
| |
| @cindex @code{SECT} (MRI) |
| @item SECT @var{secname}, @var{expression} |
| @itemx SECT @var{secname}=@var{expression} |
| @itemx SECT @var{secname} @var{expression} |
| You can use any of these three forms of the @code{SECT} command to |
| specify the start address (@var{expression}) for section @var{secname}. |
| If you have more than one @code{SECT} statement for the same |
| @var{secname}, only the @emph{first} sets the start address. |
| @end table |
| |
| @node Index |
| @unnumbered Index |
| |
| @printindex cp |
| |
| @tex |
| % I think something like @colophon should be in texinfo. In the |
| % meantime: |
| \long\def\colophon{\hbox to0pt{}\vfill |
| \centerline{The body of this manual is set in} |
| \centerline{\fontname\tenrm,} |
| \centerline{with headings in {\bf\fontname\tenbf}} |
| \centerline{and examples in {\tt\fontname\tentt}.} |
| \centerline{{\it\fontname\tenit\/} and} |
| \centerline{{\sl\fontname\tensl\/}} |
| \centerline{are used for emphasis.}\vfill} |
| \page\colophon |
| % Blame: doc@cygnus.com, 28mar91. |
| @end tex |
| |
| |
| @contents |
| @bye |
| |
| |