@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
@cindex command line
@cindex options
-Here is a summary of the options you can use on the @code{ld} command
-line:
-
-@c FIXME! -relax only avail h8/300, i960. Conditionals screwed in examples.
-@smallexample
-ld [ -o @var{output} ] @var{objfile}@dots{}
- [ -A@var{architecture} ] [ -b @var{input-format} ]
- [ -Bstatic ] [ -Bdynamic ] [ -Bsymbolic ]
- [ -c @var{MRI-commandfile} ] [ -d | -dc | -dp ]
- [ -defsym @var{symbol}=@var{expression} ]
- [ -dynamic-linker @var{file} ] [ -embedded-relocs ] [ -E ]
- [ -export-dynamic ] [ -e @var{entry} ] [ -F ] [ -F @var{format} ]
- [ -format @var{input-format} ] [ -g ] [ -G @var{size} ]
- [ -help ] [ -i ] [ -l@var{archive} ] [ -L@var{searchdir} ]
- [ -M ] [ -Map @var{mapfile} ] [ -m @var{emulation} ]
- [ -N | -n ] [ -noinhibit-exec ] [ -no-keep-memory ]
- [ -oformat @var{output-format} ] [ -R @var{filename} ]
- [ -relax ] [ -retain-symbols-file @var{filename} ]
- [ -r | -Ur ] [ -rpath @var{dir} ] [-rpath-link @var{dir} ]
- [ -S ] [ -s ] [ -soname @var{name} ] [ -shared ]
- [ -sort-common ] [ -stats ] [ -T @var{commandfile} ]
- [ -Ttext @var{org} ] [ -Tdata @var{org} ]
- [ -Tbss @var{org} ] [ -t ] [ -traditional-format ]
- [ -u @var{symbol}] [-V] [-v] [ -verbose] [ -version ]
- [ -warn-common ] [ -warn-constructors] [ -warn-multiple-gp ]
- [ -warn-once ] [ -y @var{symbol} ] [ -X ] [-x ]
- [ -( [ archives ] -) ]
- [ --start-group [ archives ] --end-group ]
- [ -split-by-reloc @var{count} ] [ -split-by-file ]
- [ --whole-archive ] [ --no-whole-archive ] [ --wrap @var{symbol} ]
-@end smallexample
-
-This plethora of command-line options may seem intimidating, but in
-actual practice few of them are used in any particular context.
+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
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
+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.
-
-@ifclear SingleFormat
-The exceptions---which may meaningfully be used more than once---are
-@samp{-A}, @samp{-b} (or its synonym @samp{-format}), @samp{-defsym},
-@samp{-L}, @samp{-l}, @samp{-R}, @samp{-u}, and @samp{-(} (or its
-synonym @samp{--start-group}).
-@end ifclear
-@ifset SingleFormat
-The exceptions---which may meaningfully be used more than once---are
-@samp{-A}, @samp{-defsym}, @samp{-L}, @samp{-l}, @samp{-R}, @samp{-u},
-and @samp{-(} (or its synonym @samp{--start-group}).
-@end ifset
+option. Options which may be meaningfully specified more than once are
+noted in the descriptions below.
@cindex object files
-The list of object files to be linked together, shown as @var{objfile}@dots{},
-may follow, precede, or be mixed in with command-line options, except that
-an @var{objfile} argument may not be placed between an option and
-its argument.
+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},
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. @xref{Commands}.
+@code{INPUT} or @code{GROUP} to load other objects. Note that
+specifying a script in this way should only be used to augment the main
+linker script; if you want to use some command that logically can only
+appear once, such as the @code{SECTIONS} or @code{MEMORY} command, you
+must replace the default linker script using the @samp{-T} option.
+@xref{Commands}.
For options whose names are a single letter,
option arguments must either follow the option letter without intervening
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
+@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
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
@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
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}.) @w{@samp{-format @var{input-format}}}
-has the same effect, as does the script command @code{TARGET}.
+formats with @samp{objdump -i}.)
@xref{BFD}.
You may want to use this option if you are linking files with an unusual
Commands}.
@end ifclear
-@kindex -Bstatic
-@item -Bstatic
-Do not link against shared libraries. This is only meaningful on
-platforms for which shared libraries are supported.
-
-@kindex -Bdynamic
-@item -Bdynamic
-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.
-
-@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 -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
@code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Option
Commands}.
-@cindex symbols, from command line
-@kindex -defsym @var{symbol}=@var{exp}
-@item -defsym @var{symbol}=@var{expression}
-Create a global symbol in the output file, containing the absolute
-address given by @var{expression}. You may use this option as many
-times as necessary to define multiple symbols in the command line. A
-limited form of arithmetic is supported for the @var{expression} in this
-context: you may give a hexadecimal constant or the name of an existing
-symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
-constants or symbols. If you need more elaborate expressions, consider
-using the linker command language from a script (@pxref{Assignment, ,
-Assignment: Symbol Definitions}). @emph{Note:} there should be no
-white space between @var{symbol}, the equals sign (``@key{=}''), and
-@var{expression}.
-
-@ifset GENERIC
-@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.
-@end ifset
-
-@cindex MIPS embedded PIC code
-@kindex -embedded-relocs
-@item -embedded-relocs
-This option is only meaningful when linking MIPS embedded PIC code,
-generated by the -membedded-pic option to the @sc{gnu} compiler and
-assembler. It causes the linker to create a table which may be used at
-runtime to relocate any data which was statically initialized to pointer
-values. See the code in testsuite/ld-empic for details.
-
@cindex entry point, from command line
@kindex -e @var{entry}
+@kindex --entry=@var{entry}
@item -e @var{entry}
+@itemx --entry=@var{entry}
Use @var{entry} as the explicit symbol for beginning execution of your
program, rather than the default entry point. @xref{Entry Point}, for a
discussion of defaults and other ways of specifying the
@cindex dynamic symbol table
@kindex -E
-@kindex -export-dynamic
+@kindex --export-dynamic
@item -E
-@itemx -export-dynamic
-When creating an ELF file, add all symbols to the dynamic symbol table.
-Normally, the dynamic symbol table contains only symbols which are used
-by a dynamic object. This option is needed for some uses of
-@code{dlopen}.
+@itemx --export-dynamic
+When creating a dynamically linked executable, add all symbols to the
+dynamic symbol table. Normally, the dynamic symbol table contains only
+symbols which are used by a dynamic object. This option is needed for
+some uses of @code{dlopen}.
+
+@kindex -f
+@kindex --auxiliary
+@item -f
+@itemx --auxiliary @var{name}
+When creating an ELF shared object, set the internal DT_AUXILIARY field
+to the specified name. This tells the dynamic linker that the symbol
+table of the shared object should be used as an auxiliary filter on the
+symbol table of the shared object @var{name}.
+
+If you later link a program against this filter object, then, when you
+run the program, the dynamic linker will see the DT_AUXILIARY field. If
+the dynamic linker resolves any symbols from the filter object, it will
+first check whether there is a definition in the shared object
+@var{name}. If there is one, it will be used instead of the definition
+in the filter object. The shared object @var{name} need not exist.
+Thus the shared object @var{name} may be used to provide an alternative
+implementation of certain functions, perhaps for debugging or for
+machine specific performance.
-@ifclear SingleFormat
@kindex -F
-@item -F
-@itemx -F@var{format}
-Ignored. Some older linkers used this option throughout a compilation
+@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 mechanisms @code{ld} uses for this purpose (the
-@samp{-b} or @samp{-format} options for input files, @samp{-oformat}
-option or the @code{TARGET} command in linker scripts for output files,
-the @code{GNUTARGET} environment variable) are more flexible, but
-@code{ld} accepts the @samp{-F} option for compatibility with scripts
-written to call the old linker.
-
-@kindex -format
-@item -format @var{input-format}
-Synonym for @samp{-b @var{input-format}}.
-@end ifclear
+object files. The @sc{gnu} linker uses other mechanisms for this
+purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the
+@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
+environment variable. The @sc{gnu} linker will ignore the @code{-F}
+option when not creating an ELF shared object.
+
+@kindex --force-exe-suffix
+@item --force-exe-suffix
+Make sure that an output file has a .exe suffix.
+
+If a successfully built fully linked output file does not have a
+@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
+the output file to one of the same name with a @code{.exe} suffix. This
+option is useful when using unmodified Unix makefiles on a Microsoft
+Windows host, since some versions of Windows won't run an image unless
+it ends in a @code{.exe} suffix.
@kindex -g
@item -g
Ignored. Provided for compatibility with other tools.
@kindex -G
+@kindex --gpsize
@cindex object size
@item -G@var{value}
-@itemx -G @var{value}
+@itemx --gpsize=@var{value}
Set the maximum size of objects to be optimized using the GP register to
-@var{size} under MIPS ECOFF. Ignored for other object file formats.
+@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 help
-@cindex usage
-@kindex -help
-@item -help
-Print a summary of the command-line options on the standard output and exit.
+@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
@cindex archive files, from cmd line
@kindex -l@var{archive}
-@item -l@var{ar}
-Add archive file @var{archive} to the list of files to link. This
+@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{ar}.a} for every @var{archive}
-specified.
+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 -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
@code{SEARCH_DIR} command. Directories specified this way are searched
at the point in which the linker script appears in the command line.
-@cindex link map
-@kindex -M
-@item -M
-Print (to the standard output) a link map---diagnostic information about
-where symbols are mapped by @code{ld}, and information on global common
-storage allocation.
-
-@cindex link map
-@kindex -Map
-@item -Map @var{mapfile}
-Print to the file @var{mapfile} a link map---diagnostic information
-about where symbols are mapped by @code{ld}, and information on global
-common storage allocation.
-
@cindex emulation
@kindex -m @var{emulation}
@item -m@var{emulation}
-@itemx -m @var{emulation}
Emulate the @var{emulation} linker. You can list the available
emulations with the @samp{--verbose} or @samp{-V} options. The default
depends on how your @code{ld} was configured.
+@cindex link map
+@kindex -M
+@kindex --print-map
+@item -M
+@itemx --print-map
+Print (to the standard output) a link map---diagnostic information about
+where symbols are mapped by @code{ld}, and information on global common
+storage allocation.
+
+@kindex -n
+@cindex read-only text
+@cindex NMAGIC
+@kindex --nmagic
+@item -n
+@itemx --nmagic
+Set the text segment to be read only, and mark the output as
+@code{NMAGIC} if possible.
+
@kindex -N
+@kindex --omagic
@cindex read/write from cmd line
-@kindex OMAGIC
+@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 -n
-@cindex read-only text
-@kindex NMAGIC
-@item -n
-Set the text segment to be read only, and mark the output as
-@code{NMAGIC} if possible.
+@kindex -o @var{output}
+@kindex --output=@var{output}
+@cindex naming the output file
+@item -o @var{output}
+@itemx --output=@var{output}
+Use @var{output} as the name for the program produced by @code{ld}; if this
+option is not specified, the name @file{a.out} is used by default. The
+script command @code{OUTPUT} can also specify the output file name.
-@cindex 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.
+@cindex partial link
+@cindex relocatable output
+@kindex -r
+@kindex --relocateable
+@item -r
+@itemx --relocateable
+Generate relocatable output---i.e., generate an output file that can in
+turn serve as input to @code{ld}. This is often called @dfn{partial
+linking}. As a side effect, in environments that support standard Unix
+magic numbers, this option also sets the output file's magic number to
+@code{OMAGIC}.
+@c ; see @code{-N}.
+If this option is not specified, an absolute file is produced. When
+linking C++ programs, this option @emph{will not} resolve references to
+constructors; to do that, use @samp{-Ur}.
+
+This option does the same thing as @samp{-i}.
+
+@kindex -R @var{file}
+@kindex --just-symbols=@var{file}
+@cindex symbol-only input
+@item -R @var{filename}
+@itemx --just-symbols=@var{filename}
+Read symbol names and their addresses from @var{filename}, but do not
+relocate it or include it in the output. This allows your output file
+to refer symbolically to absolute locations of memory defined in other
+programs. You may use this option more than once.
+
+For compatibility with other ELF linkers, if the @code{-R} option is
+followed by a directory name, rather than a file name, it is treated as
+the @code{-rpath} option.
+
+@kindex -s
+@kindex --strip-all
+@cindex strip all symbols
+@item -s
+@itemx --strip-all
+Omit all symbol information from the output file.
+
+@kindex -S
+@kindex --strip-debug
+@cindex strip debugger symbols
+@item -S
+@itemx --strip-debug
+Omit debugger symbol information (but not all symbols) from the output file.
+
+@kindex -t
+@kindex --trace
+@cindex input files, displaying
+@item -t
+@itemx --trace
+Print the names of the input files as @code{ld} processes them.
+
+@kindex -T @var{script}
+@kindex --script=@var{script}
+@cindex script files
+@item -T @var{commandfile}
+@itemx --script=@var{commandfile}
+Read link commands from the file @var{commandfile}. These commands
+replace @code{ld}'s default link script (rather than adding to it), so
+@var{commandfile} must specify everything necessary to describe the
+target format. You must use this option if you want to use a command
+which can only appear once in a linker script, such as the
+@code{SECTIONS} or @code{MEMORY} command. @xref{Commands}. If
+@var{commandfile} does not exist, @code{ld} looks for it in the
+directories specified by any preceding @samp{-L} options. Multiple
+@samp{-T} options accumulate.
+
+@kindex -u @var{symbol}
+@kindex --undefined=@var{symbol}
+@cindex undefined symbol
+@item -u @var{symbol}
+@itemx --undefined=@var{symbol}
+Force @var{symbol} to be entered in the output file as an undefined symbol.
+Doing this may, for example, trigger linking of additional modules from
+standard libraries. @samp{-u} may be repeated with different option
+arguments to enter additional undefined symbols.
+@c Nice idea, but no such command: This option is equivalent
+@c to the @code{EXTERN} linker command.
+
+@kindex -v
+@kindex -V
+@kindex --version
+@cindex version
+@item -v
+@itemx --version
+@itemx -V
+Display the version number for @code{ld}. The @code{-V} option also
+lists the supported emulations.
+
+@kindex -x
+@kindex --discard-all
+@cindex deleting local symbols
+@item -x
+@itemx --discard-all
+Delete all local symbols.
+
+@kindex -X
+@kindex --discard-locals
+@cindex local symbols, deleting
+@cindex L, deleting symbols beginning
+@item -X
+@itemx --discard-locals
+Delete all temporary local symbols. For most targets, this is all local
+symbols whose names begin with @samp{L}.
+
+@kindex -y @var{symbol}
+@kindex --trace-symbol=@var{symbol}
+@cindex symbol tracing
+@item -y @var{symbol}
+@itemx --trace-symbol=@var{symbol}
+Print the name of each linked file in which @var{symbol} appears. This
+option may be given any number of times. On many systems it is necessary
+to prepend an underscore.
+
+This option is useful when you have an undefined symbol in your link but
+don't know where the reference is coming from.
+
+@kindex -Y @var{path}
+@item -Y @var{path}
+Add @var{path} to the default library search path. This option exists
+for Solaris compatibility.
+
+@kindex -z @var{keyword}
+@item -z @var{keyword}
+This option is ignored for Solaris compatibility.
+
+@kindex -(
+@cindex groups of archives
+@item -( @var{archives} -)
+@itemx --start-group @var{archives} --end-group
+The @var{archives} should be a list of archive files. They may be
+either explicit file names, or @samp{-l} options.
+
+The specified archives are searched repeatedly until no new undefined
+references are created. Normally, an archive is searched only once in
+the order that it is specified on the command line. If a symbol in that
+archive is needed to resolve an undefined symbol referred to by an
+object in an archive that appears later on the command line, the linker
+would not be able to resolve that reference. By grouping the archives,
+they all be searched repeatedly until all possible references are
+resolved.
+
+Using this option has a significant performance cost. It is best to use
+it only when there are unavoidable circular references between two or
+more archives.
+
+@kindex -assert @var{keyword}
+@item -assert @var{keyword}
+This option is ignored for SunOS compatibility.
+
+@kindex -Bdynamic
+@kindex -dy
+@kindex -call_shared
+@item -Bdynamic
+@itemx -dy
+@itemx -call_shared
+Link against dynamic libraries. This is only meaningful on platforms
+for which shared libraries are supported. This option is normally the
+default on such platforms. The different variants of this option are
+for compatibility with various systems. You may use this option
+multiple times on the command line: it affects library searching for
+@code{-l} options which follow it.
+
+@kindex -Bstatic
+@kindex -dn
+@kindex -non_shared
+@kindex -static
+@item -Bstatic
+@itemx -dn
+@itemx -non_shared
+@itemx -static
+Do not link against shared libraries. This is only meaningful on
+platforms for which shared libraries are supported. The different
+variants of this option are for compatibility with various systems. You
+may use this option multiple times on the command line: it affects
+library searching for @code{-l} options which follow it.
+
+@kindex -Bsymbolic
+@item -Bsymbolic
+When creating a shared library, bind references to global symbols to the
+definition within the shared library, if any. Normally, it is possible
+for a program linked against a shared library to override the definition
+within the shared library. This option is only meaningful on ELF
+platforms which support shared libraries.
+
+@cindex cross reference table
+@kindex --cref
+@item --cref
+Output a cross reference table. If a linker map file is being
+generated, the cross reference table is printed to the map file.
+Otherwise, it is printed on the standard output.
+
+The format of the table is intentionally simple, so that it may be
+easily processed by a script if necessary. The symbols are printed out,
+sorted by name. For each symbol, a list of file names is given. If the
+symbol is defined, the first file listed is the location of the
+definition. The remaining files contain references to the symbol.
+
+@cindex symbols, from command line
+@kindex --defsym @var{symbol}=@var{exp}
+@item --defsym @var{symbol}=@var{expression}
+Create a global symbol in the output file, containing the absolute
+address given by @var{expression}. You may use this option as many
+times as necessary to define multiple symbols in the command line. A
+limited form of arithmetic is supported for the @var{expression} in this
+context: you may give a hexadecimal constant or the name of an existing
+symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
+constants or symbols. If you need more elaborate expressions, consider
+using the linker command language from a script (@pxref{Assignment, ,
+Assignment: Symbol Definitions}). @emph{Note:} there should be no
+white space between @var{symbol}, the equals sign (``@key{=}''), and
+@var{expression}.
+
+@cindex dynamic linker, from command line
+@kindex --dynamic-linker @var{file}
+@item --dynamic-linker @var{file}
+Set the name of the dynamic linker. This is only meaningful when
+generating dynamically linked ELF executables. The default dynamic
+linker is normally correct; don't use this unless you know what you are
+doing.
+
+@cindex big-endian objects
+@cindex endianness
+@kindex -EB
+@item -EB
+Link big-endian objects. This affects the default output format.
+
+@cindex little-endian objects
+@kindex -EL
+@item -EL
+Link little-endian objects. This affects the default output format.
+
+@cindex MIPS embedded PIC code
+@kindex --embedded-relocs
+@item --embedded-relocs
+This option is only meaningful when linking MIPS embedded PIC code,
+generated by the -membedded-pic option to the @sc{gnu} compiler and
+assembler. It causes the linker to create a table which may be used at
+runtime to relocate any data which was statically initialized to pointer
+values. See the code in testsuite/ld-empic for details.
+
+@cindex help
+@cindex usage
+@kindex --help
+@item --help
+Print a summary of the command-line options on the standard output and exit.
+
+@cindex link map
+@kindex -Map
+@item -Map @var{mapfile}
+Print to the file @var{mapfile} a link map---diagnostic information
+about where symbols are mapped by @code{ld}, and information on global
+common storage allocation.
@cindex memory usage
-@kindex -no-keep-memory
-@item -no-keep-memory
+@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 -o @var{output}
-@cindex naming the output file
-@item -o @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 --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}
+@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
+@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 -R @var{file}
-@cindex symbol-only input
-@item -R @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.
+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
-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 -qmagic
+@item -qmagic
+This option is ignored for Linux compatibility.
+
+@kindex -Qy
+@item -Qy
+This option is ignored for SVR4 compatibility.
-@kindex -relax
+@kindex --relax
@cindex synthesizing linker
@cindex relaxing addressing modes
-@item -relax
+@item --relax
An option with machine dependent effects.
@ifset GENERIC
-Currently this option is only supported on the H8/300 and the Intel 960.
+This option is only supported on a few targets.
@end ifset
@ifset H8300
@xref{H8/300,,@code{ld} and the H8/300}.
@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, the @samp{--relax} option performs global
+optimizations that become possible when the linker resolves addressing
+in the program, such as relaxing address modes and synthesizing new
+instructions in the output object file.
@ifset GENERIC
-On platforms where this is not supported, @samp{-relax} is accepted, but
-ignored.
+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}
+@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
where a large global symbol table is accumulated gradually, to conserve
run-time memory.
-@samp{-retain-symbols-file} does @emph{not} discard undefined symbols,
+@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
+You may only specify @samp{--retain-symbols-file} once in the command
line. It overrides @samp{-s} and @samp{-S}.
@ifset GENERIC
warning and continue with the link.
@end ifset
-@cindex partial link
-@cindex relocatable output
-@kindex -r
-@item -r
-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 -S
-@cindex strip debugger symbols
-@item -S
-Omit debugger symbol information (but not all symbols) from the output file.
-
-@kindex -s
-@cindex strip all symbols
-@item -s
-Omit all symbol information from the output file.
-
-@ifset GENERIC
-@cindex runtime library name
-@kindex -soname
-@item -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.
-@end ifset
-
+@kindex -shared
+@kindex -Bshareable
@item -shared
+@itemx -Bshareable
@cindex shared libraries
-@kindex -shared
-Create a shared library. This is currently only supported on ELF and
-SunOS platforms. On SunOS, the linker will automatically create a
+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
-Normally, when @code{ld} places the global common symbols in the
-appropriate output sections, it sorts them by size. 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. This option disables that sorting.
-
-@kindex split
-@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
+@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 split
-@item -split-by-file
-Similar to -split-by-reloc but creates a new output section for each
-input file.
+@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.
-@item -stats
-Compute and display statistics about the operation of the linker,
-such as execution time and memory usage.
+@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}
for compatibility with other linkers, you may omit the leading
@samp{0x} usually associated with hexadecimal values.
-@kindex -T @var{script}
-@cindex script files
-@item -T @var{commandfile}
-@itemx -T@var{commandfile}
-Read link commands from the file @var{commandfile}. These commands
-replace @code{ld}'s default link script (rather than adding
-to it), so @var{commandfile} must specify everything necessary to describe
-the target format. @xref{Commands}. If @var{commandfile} does not
-exist, @code{ld} looks for it in the directories specified by any
-preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
-
-@kindex -t
-@cindex input files, displaying
-@item -t
-Print the names of the input files as @code{ld} processes them.
-
-@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 -u @var{symbol}
-@cindex undefined symbol
-@item -u @var{symbol}
-Force @var{symbol} to be entered in the output file as an undefined symbol.
-Doing this may, for example, trigger linking of additional modules from
-standard libraries. @samp{-u} may be repeated with different option
-arguments to enter additional undefined symbols.
-@c Nice idea, but no such command: This option is equivalent
-@c to the @code{EXTERN} linker command.
-
@kindex -Ur
@cindex constructors
@item -Ur
supported. Display which input files can and cannot be opened. Display
the linker script if using a default builtin script.
-@kindex -v
-@kindex -V
-@cindex version
-@item -v
-@itemx -V
-Display the version number for @code{ld}. The @code{-V} option also
-lists the supported emulations.
-
-@kindex -version
-@item -version
-Display the version number for @code{ld} and exit.
-
-@kindex -warn-comon
+@kindex --warn-comon
@cindex warnings, on combining symbols
@cindex combining symbols, warnings on
-@item -warn-common
+@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
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.
+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
@end smallexample
@end enumerate
-@kindex -warn-constructors
-@item -warn-constructors
+@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
+@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
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
+@kindex --warn-once
@cindex warnings, on undefined symbols
@cindex undefined symbols, warnings on
-@item -warn-once
+@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
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.
-
-@kindex --no-whole-archive
-@item --no-whole-archive
-Turn off the effect of the @code{--whole-archive} option for archives
-which appear later on the command line.
+library. This option may be used more than once.
@kindex --wrap
@item --wrap @var{symbol}
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
call before the linker has a chance to wrap it to @code{malloc}.
-@kindex -X
-@cindex local symbols, deleting
-@cindex L, deleting symbols beginning
-@item -X
-Delete all temporary local symbols. For most targets, this is all local
-symbols whose names begin with @samp{L}.
-
-@kindex -x
-@cindex deleting local symbols
-@item -x
-Delete all local symbols.
-
-@kindex -y @var{symbol}
-@cindex symbol tracing
-@item -y @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 -(
-@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.
@end table
@ifset UsesEnvVars
@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
+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.
+of the target. If @code{GNUTARGET} is set to @code{default} then BFD
+attempts to discover the input format by examining binary input files;
+this method often succeeds, but there are potential ambiguities, since
+there is no method of ensuring that the magic number used to specify
+object-file formats is unique. However, the configuration procedure for
+BFD on each system places the conventional format for that system first
+in the search-list, so ambiguities are resolved in favor of convention.
@end ifset
@node Commands
placement of common blocks
@end itemize
-You may supply a command file (also known as a link script) to the
+You may supply a command file (also known as a linker script) to the
linker either explicitly through the @samp{-T} option, or implicitly as
-an ordinary file. If the linker opens a file which it cannot recognize
-as a supported object or archive format, it reports an error.
+an ordinary file. Normally you should use the @samp{-T} option. An
+implicit linker script should only be used when you want to augment,
+rather than replace, the default linker script; typically an implicit
+linker script would consist only of @code{INPUT} or @code{GROUP}
+commands.
+
+If the linker opens a file which it cannot recognize as a supported
+object or archive format, nor as a linker script, it reports an error.
@menu
* Scripts:: Linker Scripts
* Evaluation:: Evaluation
* Assignment:: Assignment: Defining Symbols
* Arithmetic Functions:: Built-In Functions
+* Semicolons:: Semicolon Usage
@end menu
@node Integers
@end ifinfo
@tex
\vskip \baselineskip
-%"lispnarrowing" is the extra indent used generally for @smallexample
+%"lispnarrowing" is the extra indent used generally for smallexample
\hskip\lispnarrowing\vbox{\offinterlineskip
\hrule
\halign
@end group
@end smallexample
+@kindex LOADADDR(@var{section})
+@cindex section load address
+@item LOADADDR(@var{section})
+Return the absolute load address of the named @var{section}. This is
+normally the same as @code{ADDR}, but it may be different if the
+@code{AT} keyword is used in the section definition (@pxref{Section
+Options}).
+
@kindex ALIGN(@var{exp})
@cindex rounding up location counter
@item ALIGN(@var{exp})
as the start address of the first section, if you choose, to facilitate
paging.
+@kindex MAX
+@item MAX(@var{exp1}, @var{exp2})
+Returns the maximum of @var{exp1} and @var{exp2}.
+
+@kindex MIN
+@item MIN(@var{exp1}, @var{exp2})
+Returns the minimum of @var{exp1} and @var{exp2}.
+
+@end table
+
+@node Semicolons
+@subsection Semicolons
+
+Semicolons (``@key{;}'') are required in the following places. In all
+other places they can appear for aesthetic reasons but are otherwise ignored.
+
+@table @code
+@item Assignment
+Semicolons must appear at the end of assignment expressions.
+@xref{Assignment}
+
+@item PHDRS
+Semicolons must appear at the end of a @code{PHDRS} statement.
+@xref{PHDRS}
@end table
@node MEMORY
* Section Placement:: Section Placement
* Section Data Expressions:: Section Data Expressions
* Section Options:: Optional Section Attributes
+* Overlays:: Overlays
@end menu
@node Section Definition
The @var{contents} of a section definition may include any of the
following kinds of statement. You can include as many of these as you
like in a single section definition, separated from one another by
-whitespace.
+whitespace.
@table @code
@kindex @var{filename}
input file's format.
@end table
-For example, the following command script arranges the output file into
-three consecutive sections, named @code{.text}, @code{.data}, and
+In any place where you may use a specific file or section name, you may
+also use a wildcard pattern. The linker handles wildcards much as the
+Unix shell does. A @samp{*} character matches any number of characters.
+A @samp{?} character matches any single character. The sequence
+@samp{[@var{chars}]} will match a single instance of any of the
+@var{chars}; the @samp{-} character may be used to specify a range of
+characters, as in @samp{[a-z]} to match any lower case letter. A
+@samp{\} character may be used to quote the following character.
+
+When a file name is matched with a wildcard, the wildcard characters
+will not match a @samp{/} character (used to separate directory names on
+Unix). A pattern consisting of a single @samp{*} character is an
+exception; it will always match any file name. In a section name, the
+wildcard characters will match a @samp{/} character.
+
+Wildcards only match files which are explicitly specified on the command
+line. The linker does not search directories to expand wildcards.
+However, if you specify a simple file name---a name with no wildcard
+characters---in a linker script, and the file name is not also specified
+on the command line, the linker will attempt to open the file as though
+it appeared on the command line.
+
+In the following example, the command script arranges the output file
+into three consecutive sections, named @code{.text}, @code{.data}, and
@code{.bss}, taking the input for each from the correspondingly named
sections of all the input files:
@end group
@end smallexample
+This example shows how wildcard patterns might be used to partition
+files. All @code{.text} sections are placed in @code{.text}, and all
+@code{.bss} sections are placed in @code{.bss}. For all files beginning
+with an upper case character, the @code{.data} section is placed into
+@code{.DATA}; for all other files, the @code{.data} section is placed
+into @code{.data}.
+
+@smallexample
+@group
+SECTIONS @{
+ .text : @{ *(.text) @}
+ .DATA : @{ [A-Z]*(.data) @}
+ .data : @{ *(.data) @}
+ .bss : @{ *(.bss) @}
+@}
+@end group
+@end smallexample
+
@node Section Data Expressions
@subsection Section Data Expressions
@end table
+@node Overlays
+@subsection Overlays
+@kindex OVERLAY
+@cindex overlays
+
+The @code{OVERLAY} command provides an easy way to describe sections
+which are to be loaded as part of a single memory image but are to be
+run at the same memory address. At run time, some sort of overlay
+manager will copy the overlaid sections in and out of the runtime memory
+address as required, perhaps by simply manipulating addressing bits.
+This approach can be useful, for example, when a certain region of
+memory is faster than another.
+
+The @code{OVERLAY} command is used within a @code{SECTIONS} command. It
+appears as follows:
+@smallexample
+@group
+ OVERLAY @var{start} : [ NOCROSSREFS ] AT ( @var{ldaddr} )
+ @{
+ @var{secname1} @{ @var{contents} @} :@var{phdr} =@var{fill}
+ @var{secname2} @{ @var{contents} @} :@var{phdr} =@var{fill}
+ @dots{}
+ @} >@var{region} :@var{phdr} =@var{fill}
+@end group
+@end smallexample
+
+Everything is optional except @code{OVERLAY} (a keyword), and each
+section must have a name (@var{secname1} and @var{secname2} above). The
+section definitions within the @code{OVERLAY} construct are identical to
+those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
+except that no addresses and no memory regions may be defined for
+sections within an @code{OVERLAY}.
+
+The sections are all defined with the same starting address. The load
+addresses of the sections are arranged such that they are consecutive in
+memory starting at the load address used for the @code{OVERLAY} as a
+whole (as with normal section definitions, the load address is optional,
+and defaults to the start address; the start address is also optional,
+and defaults to @code{.}).
+
+If the @code{NOCROSSREFS} keyword is used, and there any references
+among the sections, the linker will report an error. Since the sections
+all run at the same address, it normally does not make sense for one
+section to refer directly to another. @xref{Option Commands,
+NOCROSSREFS}.
+
+For each section within the @code{OVERLAY}, the linker automatically
+defines two symbols. The symbol @code{__load_start_@var{secname}} is
+defined as the starting load address of the section. The symbol
+@code{__load_stop_@var{secname}} is defined as the final load address of
+the section. Any characters within @var{secname} which are not legal
+within C identifiers are removed. C (or assembler) code may use these
+symbols to move the overlaid sections around as necessary.
+
+At the end of the overlay, the value of @code{.} is set to the start
+address of the overlay plus the size of the largest section.
+
+Here is an example. Remember that this would appear inside a
+@code{SECTIONS} construct.
+
+@smallexample
+@group
+ OVERLAY 0x1000 : AT (0x4000)
+ @{
+ .text0 @{ o1/*.o(.text) @}
+ .text1 @{ o2/*.o(.text) @}
+ @}
+@end group
+@end smallexample
+
+This will define both @code{.text0} and @code{.text1} to start at
+address 0x1000. @code{.text0} will be loaded at address 0x4000, and
+@code{.text1} will be loaded immediately after @code{.text0}. The
+following symbols will be defined: @code{__load_start_text0},
+@code{__load_stop_text0}, @code{__load_start_text1},
+@code{__load_stop_text1}.
+
+C code to copy overlay @code{.text1} into the overlay area might look
+like the following.
+
+@smallexample
+@group
+ extern char __load_start_text1, __load_stop_text1;
+ memcpy ((char *) 0x1000, &__load_start_text1,
+ &__load_stop_text1 - &__load_start_text1);
+@end group
+@end smallexample
+
+Note that the @code{OVERLAY} command is just syntactic sugar, since
+everything it does can be done using the more basic commands. The above
+example could have been written identically as follows.
+
+@smallexample
+@group
+ .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
+ __load_start_text0 = LOADADDR (.text0);
+ __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
+ .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
+ __load_start_text1 = LOADADDR (.text1);
+ __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
+ . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
+@end group
+@end smallexample
+
@node PHDRS
@section ELF Program Headers
@kindex PHDRS
-@kindex program headers
-@kindex ELF program headers
+@cindex program headers
+@cindex ELF program headers
The ELF object file format uses @dfn{program headers}, which are read by
the system loader and describe how the program should be loaded into
@cindex C++ constructors, arranging in link
@cindex constructors, arranging in link
@item CONSTRUCTORS
-This command ties up C++ style constructor and destructor records. The
-details of the constructor representation vary from one object format to
-another, but usually lists of constructors and destructors appear as
-special sections. The @code{CONSTRUCTORS} command specifies where the
-linker is to place the data from these sections, relative to the rest of
-the linked output. Constructor data is marked by the symbol
-@w{@code{__CTOR_LIST__}} at the start, and @w{@code{__CTOR_LIST_END}} at
-the end; destructor data is bracketed similarly, between
-@w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_LIST_END}}. (The compiler
-must arrange to actually run this code; @sc{gnu} C++ calls constructors from
-a subroutine @code{__main}, which it inserts automatically into the
-startup code for @code{main}, and destructors from @code{_exit}.)
+When linking using the @code{a.out} object file format, the linker uses
+an unusual set construct to support C++ global constructors and
+destructors. When linking object file formats which do not support
+arbitrary sections, such as @code{ECOFF} and @code{XCOFF}, the linker
+will automatically recognize C++ global constructors and destructors by
+name. For these object file formats, the @code{CONSTRUCTORS} command
+tells the linker where this information should be placed. The
+@code{CONSTRUCTORS} command is ignored for other object file formats.
+
+The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
+constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The
+first word in the list is the number of entries, followed by the address
+of each constructor or destructor, followed by a zero word. The
+compiler must arrange to actually run the code. For these object file
+formats @sc{gnu} C++ calls constructors from a subroutine @code{__main};
+a call to @code{__main} is automatically inserted into the startup code
+for @code{main}. @sc{gnu} C++ runs destructors either by using
+@code{atexit}, or directly from the function @code{exit}.
+
+For object file formats such as @code{COFF} or @code{ELF} which support
+multiple sections, @sc{gnu} C++ will normally arrange to put the
+addresses of global constructors and destructors into the @code{.ctors}
+and @code{.dtors} sections. Placing the following sequence into your
+linker script will build the sort of table which the @sc{gnu} C++
+runtime code expects to see.
+
+@smallexample
+ __CTOR_LIST__ = .;
+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
+ *(.ctors)
+ LONG(0)
+ __CTOR_END__ = .;
+ __DTOR_LIST__ = .;
+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
+ *(.dtors)
+ LONG(0)
+ __DTOR_END__ = .;
+@end smallexample
+
+Normally the compiler and linker will handle these issues automatically,
+and you will not need to concern yourself with them. However, you may
+need to consider this if you are using C++ and writing your own linker
+scripts.
@need 1000
@kindex FLOAT
you can use this command to specify a particular output format.
@var{bfdname} is one of the names used by the BFD back-end routines
(@pxref{BFD}). The effect is identical to the effect of the
-@samp{-oformat} command-line option. This selection affects only
-the output file; the related command @code{TARGET} affects primarily
-input files.
+@samp{--oformat} command-line option. This selection affects only the
+output file; the related command @code{TARGET} affects primarily input
+files.
@end ifclear
@kindex SEARCH_DIR ( @var{path} )
@item TARGET ( @var{format} )
When @code{ld} is configured to support multiple object code formats,
you can use this command to change the input-file object code format
-(like the command-line option @samp{-b} or its synonym @samp{-format}).
+(like the command-line option @samp{-b} or its synonym @samp{--format}).
The argument @var{format} is one of the strings used by BFD to name
binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT}
is not, the last @code{TARGET} argument is also used as the default
output file format. If that variable is also absent, @code{ld} uses
the default format configured for your machine in the BFD libraries.
@end ifclear
+
+@cindex cross references
+@kindex NOCROSSREFS ( @var{sections} )
+@item NOCROSSREFS ( @var{section} @var{section} @dots{} )
+This command may be used to tell @code{ld} to issue an error about any
+references among certain sections.
+
+In certain types of programs, particularly on embedded systems, when one
+section is loaded into memory, another section will not be. Any direct
+references between the two sections would be errors. For example, it
+would be an error if code in one section called a function defined in
+the other section.
+
+The @code{NOCROSSREFS} command takes a list of section names. If
+@code{ld} detects any cross references between the sections, it reports
+an error and returns a non-zero exit status. The @code{NOCROSSREFS}
+command uses output section names, defined in the @code{SECTIONS}
+command. It does not use the names of input sections.
@end table
@ifset GENERIC
@cindex H8/300 support
For the H8/300, @code{ld} can perform these global optimizations when
-you specify the @samp{-relax} command-line option.
+you specify the @samp{--relax} command-line option.
@table @emph
@cindex relaxing on H8/300
use will add another pair of name variants to search for when @w{@samp{-l}}
specifies a library.
-@cindex @code{-relax} on i960
+@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}
+@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
@include bfdsumm.texi
@end ifclear
+@node Reporting Bugs
+@chapter Reporting Bugs
+@cindex bugs in @code{ld}
+@cindex reporting bugs in @code{ld}
+
+Your bug reports play an essential role in making @code{ld} reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or
+it may not. But in any case the principal function of a bug report is
+to help the entire community by making the next version of @code{ld}
+work better. Bug reports are your contribution to the maintenance of
+@code{ld}.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+@end menu
+
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex linker crash
+@cindex crash of linker
+@item
+If the linker gets a fatal signal, for any input whatever, that is a
+@code{ld} bug. Reliable linkers never crash.
+
+@cindex error on valid input
+@item
+If @code{ld} produces an error message for valid input, that is a bug.
+
+@cindex invalid input
+@item
+If @code{ld} does not produce an error message for invalid input, that
+may be a bug. In the general case, the linker can not verify that
+object files are correct.
+
+@item
+If you are an experienced user of linkers, your suggestions for
+improvement of @code{ld} are welcome in any case.
+@end itemize
+
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex @code{ld} bugs, reporting
+
+A number of companies and individuals offer support for @sc{gnu}
+products. If you obtained @code{ld} from a support organization, we
+recommend you contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+
+In any event, we also recommend that you send bug reports for @code{ld}
+to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}. If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter. Thus, you might
+assume that the name of a symbol you use in an example does not matter.
+Well, probably it does not, but one cannot be sure. Perhaps the bug is
+a stray memory reference which happens to fetch from the location where
+that name is stored in memory; perhaps, if the name were different, the
+contents of that location would fool the linker into doing the right
+thing despite the bug. Play it safe and give a specific, complete
+example. That is the easiest thing for you to do, and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the bug if
+it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?'' Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of @code{ld}. @code{ld} announces it if you start it with
+the @samp{--version} argument.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of @code{ld}.
+
+@item
+Any patches you may have applied to the @code{ld} source, including any
+patches made to the @code{BFD} library.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+What compiler (and its version) was used to compile @code{ld}---e.g.
+``@code{gcc-2.7}''.
+
+@item
+The command arguments you gave the linker to link your example and
+observe the bug. To guarantee you will not omit something important,
+list them all. A copy of the Makefile (or the output from make) is
+sufficient.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input file, or set of input files, that will reproduce the
+bug. It is generally most helpful to send the actual object files,
+uuencoded if necessary to get them through the mail system. Making them
+available for anonymous FTP is not as good, but may be the only
+reasonable choice for large object files.
+
+If the source files were assembled using @code{gas} or compiled using
+@code{gcc}, then it may be OK to send the source files rather than the
+object files. In this case, be sure to say exactly what version of
+@code{gas} or @code{gcc} was used to produce the object files. Also say
+how @code{gas} or @code{gcc} were configured.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that @code{ld} gets a fatal signal, then we
+will certainly notice it. But if the bug is incorrect output, we might
+not notice unless it is glaringly wrong. You might as well not give us
+a chance to make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly. Suppose something strange is going on, such as, your
+copy of @code{ld} is out of synch, or you have encountered a bug in the
+C library on your system. (This has happened!) Your copy might crash
+and ours would not. If you told us to expect a crash, then when ours
+fails to crash, we would know that the bug was not happening for us. If
+you had not told us to expect a crash, then we would not be able to draw
+any conclusion from our observations.
+
+@item
+If you wish to suggest changes to the @code{ld} source, send us context
+diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
+@samp{-p} option. Always send diffs from the old file to the new file.
+If you even discuss something in the @code{ld} source, refer to it by
+context, not by line number.
+
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us. Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one. But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need. We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as @code{ld} it is very hard to
+construct an example that will make the program follow a certain path
+through the code. If you do not send us the example, we will not be
+able to construct one, so we will not be able to verify that the bug is
+fixed.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it. A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
@node MRI
@appendix MRI Compatible Script Files
@cindex MRI compatibility
@var{secname}, only the @emph{first} sets the start address.
@end table
-
@node Index
@unnumbered Index
projects / deliverable / binutils-gdb.git / blobdiff