arm-linux-ld.1

arm-linux.rar

For compatibility with linkers produced by \s-1MRI\s0, \fBld\fR accepts script
files written in an alternate, restricted command language, described in
the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.
Introduce \s-1MRI\s0 script files with
the option \fB\-c\fR; use the \fB\-T\fR option to run linker
scripts written in the general-purpose \fBld\fR scripting language.
If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories
specified by any \fB\-L\fR options.
.IP "\fB\-d\fR" 4
.IX Item "-d"
.PD 0
.IP "\fB\-dc\fR" 4
.IX Item "-dc"
.IP "\fB\-dp\fR" 4
.IX Item "-dp"
.PD
These three options are equivalent; multiple forms are supported for
compatibility with other linkers.  They assign space to common symbols
even if a relocatable output file is specified (with \fB\-r\fR).  The
script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.
.IP "\fB\-e\fR \fIentry\fR" 4
.IX Item "-e entry"
.PD 0
.IP "\fB\-\-entry=\fR\fIentry\fR" 4
.IX Item "--entry=entry"
.PD
Use \fIentry\fR as the explicit symbol for beginning execution of your
program, rather than the default entry point.  If there is no symbol
named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
and use that as the entry address (the number will be interpreted in
base 10; you may use a leading \fB0x\fR for base 16, or a leading
\&\fB0\fR for base 8).  
.IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4
.IX Item "--exclude-libs lib,lib,..."
Specifies a list of archive libraries from which symbols should not be automatically
exported. The library names may be delimited by commas or colons.  Specifying
\&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from
automatic export.  This option is available only for the i386 \s-1PE\s0 targeted
port of the linker and for \s-1ELF\s0 targeted ports.  For i386 \s-1PE\s0, symbols
explicitly listed in a .def file are still exported, regardless of this
option.  For \s-1ELF\s0 targeted ports, symbols affected by this option will
be treated as hidden.
.IP "\fB\-E\fR" 4
.IX Item "-E"
.PD 0
.IP "\fB\-\-export\-dynamic\fR" 4
.IX Item "--export-dynamic"
.PD
When creating a dynamically linked executable, add all symbols to the
dynamic symbol table.  The dynamic symbol table is the set of symbols
which are visible from dynamic objects at run time.
.Sp
If you do not use this option, the dynamic symbol table will normally
contain only those symbols which are referenced by some dynamic object
mentioned in the link.
.Sp
If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer
back to the symbols defined by the program, rather than some other
dynamic object, then you will probably need to use this option when
linking the program itself.
.Sp
You can also use the version script to control what symbols should
be added to the dynamic symbol table if the output format supports it.
See the description of \fB\-\-version\-script\fR in \f(CW@ref\fR{\s-1VERSION\s0}.
.IP "\fB\-EB\fR" 4
.IX Item "-EB"
Link big-endian objects.  This affects the default output format.
.IP "\fB\-EL\fR" 4
.IX Item "-EL"
Link little-endian objects.  This affects the default output format.
.IP "\fB\-f\fR" 4
.IX Item "-f"
.PD 0
.IP "\fB\-\-auxiliary\fR \fIname\fR" 4
.IX Item "--auxiliary name"
.PD
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 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 \fIname\fR.
.Sp
If you later link a program against this filter object, then, when you
run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 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
\&\fIname\fR.  If there is one, it will be used instead of the definition
in the filter object.  The shared object \fIname\fR need not exist.
Thus the shared object \fIname\fR may be used to provide an alternative
implementation of certain functions, perhaps for debugging or for
machine specific performance.
.Sp
This option may be specified more than once.  The \s-1DT_AUXILIARY\s0 entries
will be created in the order in which they appear on the command line.
.IP "\fB\-F\fR \fIname\fR" 4
.IX Item "-F name"
.PD 0
.IP "\fB\-\-filter\fR \fIname\fR" 4
.IX Item "--filter name"
.PD
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 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 \fIname\fR.
.Sp
If you later link a program against this filter object, then, when you
run the program, the dynamic linker will see the \s-1DT_FILTER\s0 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 \fIname\fR.  Thus the filter object can be
used to select a subset of the symbols provided by the object
\&\fIname\fR.
.Sp
Some older linkers used the \fB\-F\fR option throughout a compilation
toolchain for specifying object-file format for both input and output
object files.
The \s-1GNU\s0 linker uses other mechanisms for this purpose: the
\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the 
\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR
environment variable.
The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not
creating an \s-1ELF\s0 shared object.
.IP "\fB\-fini\fR \fIname\fR" 4
.IX Item "-fini name"
When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
address of the function.  By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as
the function to call.
.IP "\fB\-g\fR" 4
.IX Item "-g"
Ignored.  Provided for compatibility with other tools.
.IP "\fB\-G\fR\fIvalue\fR" 4
.IX Item "-Gvalue"
.PD 0
.IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4
.IX Item "--gpsize=value"
.PD
Set the maximum size of objects to be optimized using the \s-1GP\s0 register to
\&\fIsize\fR.  This is only meaningful for object file formats such as
\&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different
sections.  This is ignored for other object file formats.
.IP "\fB\-h\fR\fIname\fR" 4
.IX Item "-hname"
.PD 0
.IP "\fB\-soname=\fR\fIname\fR" 4
.IX Item "-soname=name"
.PD
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to
the specified name.  When an executable is linked with a shared object
which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic
linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0
field rather than the using the file name given to the linker.
.IP "\fB\-i\fR" 4
.IX Item "-i"
Perform an incremental link (same as option \fB\-r\fR).
.IP "\fB\-init\fR \fIname\fR" 4
.IX Item "-init name"
When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
of the function.  By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the
function to call.
.IP "\fB\-l\fR\fIarchive\fR" 4
.IX Item "-larchive"
.PD 0
.IP "\fB\-\-library=\fR\fIarchive\fR" 4
.IX Item "--library=archive"
.PD
Add archive file \fIarchive\fR to the list of files to link.  This
option may be used any number of times.  \fBld\fR will search its
path-list for occurrences of \f(CW\*(C`lib\f(CIarchive\f(CW.a\*(C'\fR for every
\&\fIarchive\fR specified.
.Sp
On systems which support shared libraries, \fBld\fR may also search for
libraries with extensions other than \f(CW\*(C`.a\*(C'\fR.  Specifically, on \s-1ELF\s0
and SunOS systems, \fBld\fR will search a directory for a library with
an extension of \f(CW\*(C`.so\*(C'\fR before searching for one with an extension of
\&\f(CW\*(C`.a\*(C'\fR.  By convention, a \f(CW\*(C`.so\*(C'\fR extension indicates a shared
library.
.Sp
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.
.Sp
See the \fB\-(\fR option for a way to force the linker to search
archives multiple times.
.Sp
You may list the same archive multiple times on the command line.
.Sp
This type of archive searching is standard for Unix linkers.  However,
if you are using \fBld\fR on \s-1AIX\s0, note that it is different from the
behaviour of the \s-1AIX\s0 linker.
.IP "\fB\-L\fR\fIsearchdir\fR" 4
.IX Item "-Lsearchdir"
.PD 0
.IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4
.IX Item "--library-path=searchdir"
.PD
Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search
for archive libraries and \fBld\fR control scripts.  You may use this
option any number of times.  The directories are searched in the order
in which they are specified on the command line.  Directories specified
on the command line are searched before the default directories.  All
\&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the
order in which the options appear.
.Sp
If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced
by the \fIsysroot prefix\fR, a path specified when the linker is configured.
.Sp
The default set of paths searched (without being specified with
\&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in
some cases also on how it was configured.  
.Sp
The paths can also be specified in a link script with the
\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command.  Directories specified this way are searched
at the point in which the linker script appears in the command line.
.IP "\fB\-m\fR\fIemulation\fR" 4
.IX Item "-memulation"
Emulate the \fIemulation\fR linker.  You can list the available
emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.
.Sp
If the \fB\-m\fR option is not used, the emulation is taken from the
\&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.
.Sp
Otherwise, the default emulation depends upon how the linker was
configured.
.IP "\fB\-M\fR" 4
.IX Item "-M"
.PD 0
.IP "\fB\-\-print\-map\fR" 4
.IX Item "--print-map"
.PD
Print a link map to the standard output.  A link map provides
information about the link, including the following:
.RS 4
.IP "*" 4
Where object files and symbols are mapped into memory.
.IP "*" 4
How common symbols are allocated.
.IP "*" 4
All archive members included in the link, with a mention of the symbol
which caused the archive member to be brought in.
.RE
.RS 4
.RE
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-nmagic\fR" 4
.IX Item "--nmagic"
.PD
Turn off page alignment of sections, and mark the output as
\&\f(CW\*(C`NMAGIC\*(C'\fR if possible.
.IP "\fB\-N\fR" 4
.IX Item "-N"
.PD 0
.IP "\fB\-\-omagic\fR" 4
.IX Item "--omagic"
.PD
Set the text and data sections to be readable and writable.  Also, do
not page-align the data segment, and disable linking against shared
libraries.  If the output format supports Unix style magic numbers,
mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section
is allowed for PE-COFF targets, it does not conform to the format
specification published by Microsoft.
.IP "\fB\-\-no\-omagic\fR" 4
.IX Item "--no-omagic"
This option negates most of the effects of the \fB\-N\fR option.  It
sets the text section to be read\-only, and forces the data segment to
be page\-aligned.  Note \- this option does not enable linking against
shared libraries.  Use \fB\-Bdynamic\fR for this.
.IP "\fB\-o\fR \fIoutput\fR" 4
.IX Item "-o output"
.PD 0
.IP "\fB\-\-output=\fR\fIoutput\fR" 4
.IX Item "--output=output"
.PD
Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this
option is not specified, the name \fIa.out\fR is used by default.  The
script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.
.IP "\fB\-O\fR \fIlevel\fR" 4
.IX Item "-O level"
If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes
the output.  This might take significantly longer and therefore probably
should only be enabled for the final binary.
.IP "\fB\-q\fR" 4
.IX Item "-q"
.PD 0
.IP "\fB\-\-emit\-relocs\fR" 4
.IX Item "--emit-relocs"
.PD
Leave relocation sections and contents in fully linked exececutables.
Post link analysis and optimization tools may need this information in
order to perform correct modifications of executables.  This results
in larger executables.
.Sp
This option is currently only supported on \s-1ELF\s0 platforms.
.IP "\fB\-r\fR" 4
.IX Item "-r"
.PD 0
.IP "\fB\-\-relocatable\fR" 4
.IX Item "--relocatable"
.PD