Google Git
Sign in
fuchsia / third_party / binutils-gdb / 740c6d499b4aa491dac06247ee3bb988755dcd9e / . / ld / ld.info-5
blob: 8869b3668368349fd3af19015bc89937b21ada70 [file] [log] [blame]
This is ld.info, produced by makeinfo version 4.3 from ./ld.texinfo.
START-INFO-DIR-ENTRY
* Ld: (ld). The GNU linker.
END-INFO-DIR-ENTRY
This file documents the GNU linker LD version 2.14.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
2002, 2003 Free Software Foundation, Inc.

File: ld.info, Node: WIN32, Next: Xtensa, Prev: TI COFF, Up: Machine Dependent
`ld' and WIN32 (cygwin/mingw)
=============================
This section describes some of the win32 specific `ld' issues. See
*Note Command Line Options: Options for detailed decription of the
command line options mentioned here.
_import libraries_
The standard Windows linker creates and uses so-called import
libraries, which contains information for linking to dll's. They
are regular static archives and are handled as any other static
archive. The cygwin and mingw ports of `ld' have specific support
for creating such libraries provided with the `--out-implib'
command line option.
_exporting DLL symbols_
The cygwin/mingw `ld' has several ways to export symbols for dll's.
_using auto-export functionality_
By default `ld' exports symbols with the auto-export
functionality, which is controlled by the following command
line options:
* -export-all-symbols [This is the default]
* -exclude-symbols
* -exclude-libs
If, however, `--export-all-symbols' is not given explicitly
on the command line, then the default auto-export behavior
will be _disabled_ if either of the following are true:
* A DEF file is used.
* Any symbol in any object file was marked with the
__declspec(dllexport) attribute.
_using a DEF file_
Another way of exporting symbols is using a DEF file. A DEF
file is an ASCII file containing definitions of symbols which
should be exported when a dll is created. Usually it is
named `<dll name>.def' and is added as any other object file
to the linker's command line. The file's name must end in
`.def' or `.DEF'.
gcc -o <output> <objectfiles> <dll name>.def
Using a DEF file turns off the normal auto-export behavior,
unless the `--export-all-symbols' option is also used.
Here is an example of a DEF file for a shared library called
`xyz.dll':
LIBRARY "xyz.dll" BASE=0x10000000
EXPORTS
foo
bar
_bar = bar
This example defines a base address and three symbols. The
third symbol is an alias for the second. For the complete
format specification see ld/deffilep.y in the binutils
sources.
While linking a shared dll, `ld' is able to create a DEF file
with the `--output-def <file>' command line option.
_Using decorations_
Another way of marking symbols for export is to modify the
source code itself, so that when building the DLL each symbol
to be exported is declared as:
__declspec(dllexport) int a_variable
__declspec(dllexport) void a_function(int with_args)
All such symbols will be exported from the DLL. If, however,
any of the object files in the DLL contain symbols decorated
in this way, then the normal auto-export behavior is
disabled, unless the `--export-all-symbols' option is also
used.
Note that object files that wish to access these symbols must
_not_ decorate them with dllexport. Instead, they should use
dllimport, instead:
__declspec(dllimport) int a_variable
__declspec(dllimport) void a_function(int with_args)
This complicates the structure of library header files,
because when included by the library itself the header must
declare the variables and functions as dllexport, but when
included by client code the header must declare them as
dllimport. There are a number of idioms that are typically
used to do this; often client code can omit the __declspec()
declaration completely. See `--enable-auto-import' and
`automatic data imports' for more imformation.
_automatic data imports_
The standard Windows dll format supports data imports from dlls
only by adding special decorations (dllimport/dllexport), which
let the compiler produce specific assembler instructions to deal
with this issue. This increases the effort necessary to port
existing Un*x code to these platforms, especially for large c++
libraries and applications. The auto-import feature, which was
initially provided by Paul Sokolovsky, allows one to omit the
decorations to archieve a behavior that conforms to that on
POSIX/Un*x platforms. This feature is enabled with the
`--enable-auto-import' command-line option, although it is enabled
by default on cygwin/mingw. The `--enable-auto-import' option
itself now serves mainly to suppress any warnings that are
ordinarily emitted when linked objects trigger the feature's use.
auto-import of variables does not always work flawlessly without
additional assistance. Sometimes, you will see this message
"variable '<var>' can't be auto-imported. Please read the
documentation for ld's `--enable-auto-import' for details."
The `--enable-auto-import' documentation explains why this error
occurs, and several methods that can be used to overcome this
difficulty. One of these methods is the _runtime pseudo-relocs_
feature, described below.
For complex variables imported from DLLs (such as structs or
classes), object files typically contain a base address for the
variable and an offset (_addend_) within the variable-to specify a
particular field or public member, for instance. Unfortunately,
the runtime loader used in win32 environments is incapable of
fixing these references at runtime without the additional
information supplied by dllimport/dllexport decorations. The
standard auto-import feature described above is unable to resolve
these references.
The `--enable-runtime-pseudo-relocs' switch allows these
references to be resolved without error, while leaving the task of
adjusting the references themselves (with their non-zero addends)
to specialized code provided by the runtime environment. Recent
versions of the cygwin and mingw environments and compilers
provide this runtime support; older versions do not. However, the
support is only necessary on the developer's platform; the
compiled result will run without error on an older system.
`--enable-runtime-pseudo-relocs' is not the default; it must be
explicitly enabled as needed.
_direct linking to a dll_
The cygwin/mingw ports of `ld' support the direct linking,
including data symbols, to a dll without the usage of any import
libraries. This is much faster and uses much less memory than
does the traditional import library method, expecially when
linking large libraries or applications. When `ld' creates an
import lib, each function or variable exported from the dll is
stored in its own bfd, even though a single bfd could contain many
exports. The overhead involved in storing, loading, and
processing so many bfd's is quite large, and explains the
tremendous time, memory, and storage needed to link against
particularly large or complex libraries when using import libs.
Linking directly to a dll uses no extra command-line switches
other than `-L' and `-l', because `ld' already searches for a
number of names to match each library. All that is needed from
the developer's perspective is an understanding of this search, in
order to force ld to select the dll instead of an import library.
For instance, when ld is called with the argument `-lxxx' it will
attempt to find, in the first directory of its search path,
libxxx.dll.a
xxx.dll.a
libxxx.a
cygxxx.dll (*)
libxxx.dll
xxx.dll
before moving on to the next directory in the search path.
(*) Actually, this is not `cygxxx.dll' but in fact is
`<prefix>xxx.dll', where `<prefix>' is set by the `ld' option
`--dll-search-prefix=<prefix>'. In the case of cygwin, the
standard gcc spec file includes `--dll-search-prefix=cyg', so in
effect we actually search for `cygxxx.dll'.
Other win32-based unix environments, such as mingw or pw32, may
use other `<prefix>'es, although at present only cygwin makes use
of this feature. It was originally intended to help avoid name
conflicts among dll's built for the various win32/un*x
environments, so that (for example) two versions of a zlib dll
could coexist on the same machine.
The generic cygwin/mingw path layout uses a `bin' directory for
applications and dll's and a `lib' directory for the import
libraries (using cygwin nomenclature):
bin/
cygxxx.dll
lib/
libxxx.dll.a (in case of dll's)
libxxx.a (in case of static archive)
Linking directly to a dll without using the import library can be
done two ways:
1. Use the dll directly by adding the `bin' path to the link line
gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
However, as the dll's often have version numbers appended to their
names (`cygncurses-5.dll') this will often fail, unless one
specifies `-L../bin -lncurses-5' to include the version. Import
libs are generally not versioned, and do not have this difficulty.
2. Create a symbolic link from the dll to a file in the `lib'
directory according to the above mentioned search pattern. This
should be used to avoid unwanted changes in the tools needed for
making the app/dll.
ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
Then you can link without any make environment changes.
gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
This technique also avoids the version number problems, because
the following is perfectly legal
bin/
cygxxx-5.dll
lib/
libxxx.dll.a -> ../bin/cygxxx-5.dll
Linking directly to a dll without using an import lib will work
even when auto-import features are exercised, and even when
`--enable-runtime-pseudo-relocs' is used.
Given the improvements in speed and memory usage, one might
justifiably wonder why import libraries are used at all. There
are two reasons:
1. Until recently, the link-directly-to-dll functionality did _not_
work with auto-imported data.
2. Sometimes it is necessary to include pure static objects within
the import library (which otherwise contains only bfd's for
indirection symbols that point to the exports of a dll). Again,
the import lib for the cygwin kernel makes use of this ability,
and it is not possible to do this without an import lib.
So, import libs are not going away. But the ability to replace
true import libs with a simple symbolic link to (or a copy of) a
dll, in most cases, is a useful addition to the suite of tools
binutils makes available to the win32 developer. Given the
massive improvements in memory requirements during linking, storage
requirements, and linking speed, we expect that many developers
will soon begin to use this feature whenever possible.
_symbol aliasing_
_adding additional names_
Sometimes, it is useful to export symbols with additional
names. A symbol `foo' will be exported as `foo', but it can
also be exported as `_foo' by using special directives in the
DEF file when creating the dll. This will affect also the
optional created import library. Consider the following DEF
file:
LIBRARY "xyz.dll" BASE=0x61000000
EXPORTS
foo
_foo = foo
The line `_foo = foo' maps the symbol `foo' to `_foo'.
Another method for creating a symbol alias is to create it in
the source code using the "weak" attribute:
void foo () { /* Do something. */; }
void _foo () __attribute__ ((weak, alias ("foo")));
See the gcc manual for more information about attributes and
weak symbols.
_renaming symbols_
Sometimes it is useful to rename exports. For instance, the
cygwin kernel does this regularly. A symbol `_foo' can be
exported as `foo' but not as `_foo' by using special
directives in the DEF file. (This will also affect the import
library, if it is created). In the following example:
LIBRARY "xyz.dll" BASE=0x61000000
EXPORTS
_foo = foo
The line `_foo = foo' maps the exported symbol `foo' to
`_foo'.
Note: using a DEF file disables the default auto-export behavior,
unless the `--export-all-symbols' command line option is used.
If, however, you are trying to rename symbols, then you should list
_all_ desired exports in the DEF file, including the symbols that
are not being renamed, and do _not_ use the `--export-all-symbols'
option. If you list only the renamed symbols in the DEF file, and
use `--export-all-symbols' to handle the other symbols, then the
both the new names _and_ the original names for the the renamed
symbols will be exported. In effect, you'd be aliasing those
symbols, not renaming them, which is probably not what you wanted.

File: ld.info, Node: Xtensa, Prev: WIN32, Up: Machine Dependent
`ld' and Xtensa Processors
==========================
The default `ld' behavior for Xtensa processors is to interpret
`SECTIONS' commands so that lists of explicitly named sections in a
specification with a wildcard file will be interleaved when necessary to
keep literal pools within the range of PC-relative load offsets. For
example, with the command:
SECTIONS
{
.text : {
*(.literal .text)
}
}
`ld' may interleave some of the `.literal' and `.text' sections from
different object files to ensure that the literal pools are within the
range of PC-relative load offsets. A valid interleaving might place
the `.literal' sections from an initial group of files followed by the
`.text' sections of that group of files. Then, the `.literal' sections
from the rest of the files and the `.text' sections from the rest of
the files would follow. The non-interleaved order can still be
specified as:
SECTIONS
{
.text : {
*(.literal) *(.text)
}
}
The Xtensa version of `ld' enables the `--relax' option by default
to attempt to reduce space in the output image by combining literals
with identical values. It also provides the `--no-relax' option to
disable this optimization. When enabled, the relaxation algorithm
ensures that a literal will only be merged with another literal when
the new merged literal location is within the offset range of all of
its uses.
The relaxation mechanism will also attempt to optimize
assembler-generated "longcall" sequences of `L32R'/`CALLXN' when the
target is known to fit into a `CALLN' instruction encoding. The
current optimization converts the sequence into `NOP'/`CALLN' and
removes the literal referenced by the `L32R' instruction.

File: ld.info, Node: BFD, Next: Reporting Bugs, Prev: Machine Dependent, Up: Top
BFD
***
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 `objdump -i' (*note
objdump: (binutils.info)objdump.) to list all the formats available for
your configuration.
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. *Note BFD information loss::.
* Menu:
* BFD outline:: How it works: an outline of BFD

File: ld.info, Node: BFD outline, Up: BFD
How It Works: An Outline of BFD
===============================
When an object file is opened, BFD subroutines automatically
determine the format of the input object file. They then build a
descriptor in memory with pointers to routines that will be used to
access elements of the object file's data structures.
As different information from the object files is required, BFD
reads from different sections of the file and processes them. For
example, a very common operation for the linker is processing symbol
tables. Each BFD back end provides a routine for converting between
the object file's representation of symbols and an internal canonical
format. When the linker asks for the symbol table of an object file, it
calls through a memory pointer to the routine from the relevant BFD
back end which reads and converts the table into a canonical form. The
linker then operates upon the canonical form. When the link is finished
and the linker writes the output file's symbol table, another BFD back
end routine is called to take the newly created symbol table and
convert it into the chosen output format.
* Menu:
* BFD information loss:: Information Loss
* Canonical format:: The BFD canonical object-file format

File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline
Information Loss
----------------
_Information can be lost during output._ The output formats
supported by BFD do not provide identical facilities, and information
which can be described in one form has nowhere to go in another format.
One example of this is alignment information in `b.out'. There is
nowhere in an `a.out' format file to store alignment information on the
contained data, so when a file is linked from `b.out' and an `a.out'
image is produced, alignment information will not propagate to the
output file. (The linker will still use the alignment information
internally, so the link is performed correctly).
Another example is COFF section names. COFF files may contain an
unlimited number of sections, each one with a textual section name. If
the target of the link is a format which does not have many sections
(e.g., `a.out') or has sections without names (e.g., the Oasys format),
the link cannot be done simply. You can circumvent this problem by
describing the desired input-to-output section mapping with the linker
command language.
_Information can be lost during canonicalization._ The BFD internal
canonical form of the external formats is not exhaustive; there are
structures in input formats for which there is no direct representation
internally. This means that the BFD back ends cannot maintain all
possible data richness through the transformation between external to
internal and back to external formats.
This limitation is only a problem when an application reads one
format and writes another. Each BFD back end is responsible for
maintaining as much data as possible, and the internal BFD canonical
form has structures which are opaque to the BFD core, and exported only
to the back ends. When a file is read in one format, the canonical form
is generated for BFD and the application. At the same time, the back
end saves away any information which may otherwise be lost. If the data
is then written back in the same format, the back end routine will be
able to use the canonical form provided by the BFD core as well as the
information it prepared earlier. Since there is a great deal of
commonality between back ends, there is no information lost when
linking or copying big endian COFF to little endian COFF, or `a.out' to
`b.out'. When a mixture of formats is linked, the information is only
lost from the files whose format differs from the destination.

File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline
The BFD canonical object-file format
------------------------------------
The greatest potential for loss of information occurs when there is
the least overlap between the information provided by the source
format, that stored by the canonical format, and that needed by the
destination format. A brief description of the canonical form may help
you understand which kinds of data you can count on preserving across
conversions.
_files_
Information stored on a per-file basis includes target machine
architecture, particular implementation format type, a demand
pageable bit, and a write protected bit. Information like Unix
magic numbers is not stored here--only the magic numbers' meaning,
so a `ZMAGIC' file would have both the demand pageable bit and the
write protected text bit set. The byte order of the target is
stored on a per-file basis, so that big- and little-endian object
files may be used with one another.
_sections_
Each section in the input file contains the name of the section,
the section's original address in the object file, size and
alignment information, various flags, and pointers into other BFD
data structures.
_symbols_
Each symbol contains a pointer to the information for the object
file which originally defined it, its name, its value, and various
flag bits. When a BFD back end reads in a symbol table, it
relocates all symbols to make them relative to the base of the
section where they were defined. Doing this ensures that each
symbol points to its containing section. Each symbol also has a
varying amount of hidden private data for the BFD back end. Since
the symbol points to the original file, the private data format
for that symbol is accessible. `ld' can operate on a collection
of symbols of wildly different formats without problems.
Normal global and simple local symbols are maintained on output,
so an output file (no matter its format) will retain symbols
pointing to functions and to global, static, and common variables.
Some symbol information is not worth retaining; in `a.out', type
information is stored in the symbol table as long symbol names.
This information would be useless to most COFF debuggers; the
linker has command line switches to allow users to throw it away.
There is one word of type information within the symbol, so if the
format supports symbol type information within symbols (for
example, COFF, IEEE, Oasys) and the type is simple enough to fit
within one word (nearly everything but aggregates), the
information will be preserved.
_relocation level_
Each canonical BFD relocation record contains a pointer to the
symbol to relocate to, the offset of the data to relocate, the
section the data is in, and a pointer to a relocation type
descriptor. Relocation is performed by passing messages through
the relocation type descriptor and the symbol pointer. Therefore,
relocations can be performed on output data using a relocation
method that is only available in one of the input formats. For
instance, Oasys provides a byte relocation format. A relocation
record requesting this relocation type would point indirectly to a
routine to perform this, so the relocation may be performed on a
byte being written to a 68k COFF file, even though 68k COFF has no
such relocation type.
_line numbers_
Object formats can contain, for debugging purposes, some form of
mapping between symbols, source line numbers, and addresses in the
output file. These addresses have to be relocated along with the
symbol information. Each symbol with an associated list of line
number records points to the first record of the list. The head
of a line number list consists of a pointer to the symbol, which
allows finding out the address of the function whose line number
is being described. The rest of the list is made up of pairs:
offsets into the section and line numbers. Any format which can
simply derive this information can pass it successfully between
formats (COFF, IEEE and Oasys).

File: ld.info, Node: Reporting Bugs, Next: MRI, Prev: BFD, Up: Top
Reporting Bugs
**************
Your bug reports play an essential role in making `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 `ld' work
better. Bug reports are your contribution to the maintenance of `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

File: ld.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs
Have You Found a Bug?
=====================
If you are not sure whether you have found a bug, here are some
guidelines:
* If the linker gets a fatal signal, for any input whatever, that is
a `ld' bug. Reliable linkers never crash.
* If `ld' produces an error message for valid input, that is a bug.
* If `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.
* If you are an experienced user of linkers, your suggestions for
improvement of `ld' are welcome in any case.

File: ld.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs
How to Report Bugs
==================
A number of companies and individuals offer support for GNU
products. If you obtained `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 `etc/SERVICE' in the GNU Emacs distribution.
Otherwise, send bug reports for `ld' to `bug-binutils@gnu.org'.
The fundamental principle of reporting bugs usefully is this:
*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?" This cannot help us fix a bug, so it is basically useless. We
respond by asking for enough details to enable us to investigate. You
might as well expedite matters by sending them to begin with.
To enable us to fix the bug, you should include all these things:
* The version of `ld'. `ld' announces it if you start it with the
`--version' argument.
Without this, we will not know whether there is any point in
looking for the bug in the current version of `ld'.
* Any patches you may have applied to the `ld' source, including any
patches made to the `BFD' library.
* The type of machine you are using, and the operating system name
and version number.
* What compiler (and its version) was used to compile `ld'--e.g.
"`gcc-2.7'".
* 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.
* 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 provided that they are reasonably small. Say no more than
10K. For bigger files you can either make them available by FTP
or HTTP or else state that you are willing to send the object
file(s) to whomever requests them. (Note - your email will be
going to a mailing list, so we do not want to clog it up with
large attachments). But small attachments are best.
If the source files were assembled using `gas' or compiled using
`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
`gas' or `gcc' was used to produce the object files. Also say how
`gas' or `gcc' were configured.
* 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 `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 `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.
* If you wish to suggest changes to the `ld' source, send us context
diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
Always send diffs from the old file to the new file. If you even
discuss something in the `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.
Here are some things that are not necessary:
* 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 _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.
* 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 `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.
* 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.

File: ld.info, Node: MRI, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top
MRI Compatible Script Files
***************************
To aid users making the transition to GNU `ld' from the MRI linker,
`ld' can use MRI compatible linker scripts as an alternative to the
more general-purpose linker scripting language described in *Note
Scripts::. MRI compatible linker scripts have a much simpler command
set than the scripting language otherwise used with `ld'. GNU `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 `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
`-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, `ld' issues
a warning message, but continues processing the script.
Lines beginning with `*' are comments.
You can write these commands using all upper-case letters, or all
lower case; for example, `chip' is the same as `CHIP'. The following
list shows only the upper-case form of each command.
`ABSOLUTE SECNAME'
`ABSOLUTE SECNAME, SECNAME, ... SECNAME'
Normally, `ld' includes in the output file all sections from all
the input files. However, in an MRI-compatible script, you can
use the `ABSOLUTE' command to restrict the sections that will be
present in your output program. If the `ABSOLUTE' command is used
at all in a script, then only the sections named explicitly in
`ABSOLUTE' commands will appear in the linker output. You can
still use other input sections (whatever you select on the command
line, or using `LOAD') to resolve addresses in the output file.
`ALIAS OUT-SECNAME, IN-SECNAME'
Use this command to place the data from input section IN-SECNAME
in a section called OUT-SECNAME in the linker output file.
IN-SECNAME may be an integer.
`ALIGN SECNAME = EXPRESSION'
Align the section called SECNAME to EXPRESSION. The EXPRESSION
should be a power of two.
`BASE EXPRESSION'
Use the value of EXPRESSION as the lowest address (other than
absolute addresses) in the output file.
`CHIP EXPRESSION'
`CHIP EXPRESSION, EXPRESSION'
This command does nothing; it is accepted only for compatibility.
`END'
This command does nothing whatever; it's only accepted for
compatibility.
`FORMAT OUTPUT-FORMAT'
Similar to the `OUTPUT_FORMAT' command in the more general linker
language, but restricted to one of these output formats:
1. S-records, if OUTPUT-FORMAT is `S'
2. IEEE, if OUTPUT-FORMAT is `IEEE'
3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
`COFF'
`LIST ANYTHING...'
Print (to the standard output file) a link map, as produced by the
`ld' command-line option `-M'.
The keyword `LIST' may be followed by anything on the same line,
with no change in its effect.
`LOAD FILENAME'
`LOAD FILENAME, FILENAME, ... FILENAME'
Include one or more object file FILENAME in the link; this has the
same effect as specifying FILENAME directly on the `ld' command
line.
`NAME OUTPUT-NAME'
OUTPUT-NAME is the name for the program produced by `ld'; the
MRI-compatible command `NAME' is equivalent to the command-line
option `-o' or the general script language command `OUTPUT'.
`ORDER SECNAME, SECNAME, ... SECNAME'
`ORDER SECNAME SECNAME SECNAME'
Normally, `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
`ORDER' command. The sections you list with `ORDER' will appear
first in your output file, in the order specified.
`PUBLIC NAME=EXPRESSION'
`PUBLIC NAME,EXPRESSION'
`PUBLIC NAME EXPRESSION'
Supply a value (EXPRESSION) for external symbol NAME used in the
linker input files.
`SECT SECNAME, EXPRESSION'
`SECT SECNAME=EXPRESSION'
`SECT SECNAME EXPRESSION'
You can use any of these three forms of the `SECT' command to
specify the start address (EXPRESSION) for section SECNAME. If
you have more than one `SECT' statement for the same SECNAME, only
the _first_ sets the start address.