arm-linux-ld.1

arm-linux.rar

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 \s-1ELF\s0
platforms which support shared libraries.
.IP "\fB\-\-check\-sections\fR" 4
.IX Item "--check-sections"
.PD 0
.IP "\fB\-\-no\-check\-sections\fR" 4
.IX Item "--no-check-sections"
.PD
Asks the linker \fInot\fR to check section addresses after they have
been assigned to see if there any overlaps.  Normally the linker will
perform this check, and if it finds any overlaps it will produce
suitable error messages.  The linker does know about, and does make
allowances for sections in overlays.  The default behaviour can be
restored by using the command line switch \fB\-\-check\-sections\fR.
.IP "\fB\-\-cref\fR" 4
.IX 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.
.Sp
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.
.IP "\fB\-\-no\-define\-common\fR" 4
.IX Item "--no-define-common"
This option inhibits the assignment of addresses to common symbols.
The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect.
.Sp
The \fB\-\-no\-define\-common\fR option allows decoupling
the decision to assign addresses to Common symbols from the choice
of the output file type; otherwise a non-Relocatable output type
forces assigning addresses to Common symbols.
Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced
from a shared library to be assigned addresses only in the main program.
This eliminates the unused duplicate space in the shared library,
and also prevents any possible confusion over resolving to the wrong
duplicate when there are many dynamic modules with specialized search
paths for runtime symbol resolution.
.IP "\fB\-\-defsym\fR \fIsymbol\fR\fB=\fR\fIexpression\fR" 4
.IX Item "--defsym symbol=expression"
Create a global symbol in the output file, containing the absolute
address given by \fIexpression\fR.  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 \fIexpression\fR in this
context: you may give a hexadecimal constant or the name of an existing
symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal
constants or symbols.  If you need more elaborate expressions, consider
using the linker command language from a script.  \fINote:\fR there should be no white
space between \fIsymbol\fR, the equals sign (``\fB=\fR''), and
\&\fIexpression\fR.
.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
.IX Item "--demangle[=style]"
.PD 0
.IP "\fB\-\-no\-demangle\fR" 4
.IX Item "--no-demangle"
.PD
These options control whether to demangle symbol names in error messages
and other output.  When the linker is told to demangle, it tries to
present symbol names in a readable fashion: it strips leading
underscores if they are used by the object file format, and converts \*(C+
mangled symbol names into user readable names.  Different compilers have
different mangling styles.  The optional demangling style argument can be used
to choose an appropriate demangling style for your compiler.  The linker will
demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR
is set.  These options may be used to override the default.
.IP "\fB\-\-dynamic\-linker\fR \fIfile\fR" 4
.IX Item "--dynamic-linker file"
Set the name of the dynamic linker.  This is only meaningful when
generating dynamically linked \s-1ELF\s0 executables.  The default dynamic
linker is normally correct; don't use this unless you know what you are
doing.
.IP "\fB\-\-fatal\-warnings\fR" 4
.IX Item "--fatal-warnings"
Treat all warnings as errors.
.IP "\fB\-\-force\-exe\-suffix\fR" 4
.IX Item "--force-exe-suffix"
Make sure that an output file has a .exe suffix.
.Sp
If a successfully built fully linked output file does not have a
\&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy
the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR 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 \f(CW\*(C`.exe\*(C'\fR suffix.
.IP "\fB\-\-no\-gc\-sections\fR" 4
.IX Item "--no-gc-sections"
.PD 0
.IP "\fB\-\-gc\-sections\fR" 4
.IX Item "--gc-sections"
.PD
Enable garbage collection of unused input sections.  It is ignored on
targets that do not support this option.  This option is not compatible
with \fB\-r\fR. The default behaviour (of not performing this garbage
collection) can be restored by specifying \fB\-\-no\-gc\-sections\fR on
the command line.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Print a summary of the command-line options on the standard output and exit.
.IP "\fB\-\-target\-help\fR" 4
.IX Item "--target-help"
Print a summary of all target specific options on the standard output and exit.
.IP "\fB\-Map\fR \fImapfile\fR" 4
.IX Item "-Map mapfile"
Print a link map to the file \fImapfile\fR.  See the description of the
\&\fB\-M\fR option, above.
.IP "\fB\-\-no\-keep\-memory\fR" 4
.IX Item "--no-keep-memory"
\&\fBld\fR normally optimizes for speed over memory usage by caching the
symbol tables of input files in memory.  This option tells \fBld\fR to
instead optimize for memory usage, by rereading the symbol tables as
necessary.  This may be required if \fBld\fR runs out of memory space
while linking a large executable.
.IP "\fB\-\-no\-undefined\fR" 4
.IX Item "--no-undefined"
.PD 0
.IP "\fB\-z defs\fR" 4
.IX Item "-z defs"
.PD
Report unresolved symbol references from regular object files.  This
is done even if the linker is creating a non-symbolic shared library.
The switch \fB\-\-[no\-]allow\-shlib\-undefined\fR controls the
behaviour for reporting unresolved references found in shared
libraries being linked in.  
.IP "\fB\-\-allow\-multiple\-definition\fR" 4
.IX Item "--allow-multiple-definition"
.PD 0
.IP "\fB\-z muldefs\fR" 4
.IX Item "-z muldefs"
.PD
Normally when a symbol is defined multiple times, the linker will
report a fatal error. These options allow multiple definitions and the
first definition will be used.
.IP "\fB\-\-allow\-shlib\-undefined\fR" 4
.IX Item "--allow-shlib-undefined"
.PD 0
.IP "\fB\-\-no\-allow\-shlib\-undefined\fR" 4
.IX Item "--no-allow-shlib-undefined"
.PD
Allows (the default) or disallows undefined symbols in shared libraries.
This switch is similar to \fB\-\-no\-undefined\fR except that it
determines the behaviour when the undefined symbols are in a
shared library rather than a regular object file.  It does not affect
how undefined symbols in regular object files are handled.
.Sp
The reason that \fB\-\-allow\-shlib\-undefined\fR is the default is that
the shared library being specified at link time may not be the same as
the one that is available at load time, so the symbols might actually be
resolvable at load time.  Plus there are some systems, (eg BeOS) where
undefined symbols in shared libraries is normal.  (The kernel patches
them at load time to select which function is most appropriate 
for the current architecture.  This is used for example to dynamically
select an appropriate memset function).  Apparently it is also normal
for \s-1HPPA\s0 shared libraries to have undefined symbols.
.IP "\fB\-\-no\-undefined\-version\fR" 4
.IX Item "--no-undefined-version"
Normally when a symbol has an undefined version, the linker will ignore
it. This option disallows symbols with undefined version and a fatal error
will be issued instead.
.IP "\fB\-\-default\-symver\fR" 4
.IX Item "--default-symver"
Create and use a default symbol version (the soname) for unversioned
exported symbols.
.IP "\fB\-\-default\-imported\-symver\fR" 4
.IX Item "--default-imported-symver"
Create and use a default symbol version (the soname) for unversioned
imported symbols.
.IP "\fB\-\-no\-warn\-mismatch\fR" 4
.IX Item "--no-warn-mismatch"
Normally \fBld\fR will give an error if you try to link together input
files that are mismatched for some reason, perhaps because they have
been compiled for different processors or for different endiannesses.
This option tells \fBld\fR that it should silently permit such possible
errors.  This option should only be used with care, in cases when you
have taken some special action that ensures that the linker errors are
inappropriate.
.IP "\fB\-\-no\-whole\-archive\fR" 4
.IX Item "--no-whole-archive"
Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent
archive files.
.IP "\fB\-\-noinhibit\-exec\fR" 4
.IX 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.
.IP "\fB\-nostdlib\fR" 4
.IX Item "-nostdlib"
Only search library directories explicitly specified on the
command line.  Library directories specified in linker scripts
(including linker scripts specified on the command line) are ignored.
.IP "\fB\-\-oformat\fR \fIoutput-format\fR" 4
.IX Item "--oformat output-format"
\&\fBld\fR may be configured to support more than one kind of object
file.  If your \fBld\fR is configured this way, you can use the
\&\fB\-\-oformat\fR option to specify the binary format for the output
object file.  Even when \fBld\fR is configured to support alternative
object formats, you don't usually need to specify this, as \fBld\fR
should be configured to produce as a default output format the most
usual format on each machine.  \fIoutput-format\fR is a text string, the
name of a particular format supported by the \s-1BFD\s0 libraries.  (You can
list the available binary formats with \fBobjdump \-i\fR.)  The script
command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but
this option overrides it.  
.IP "\fB\-pie\fR" 4
.IX Item "-pie"
.PD 0
.IP "\fB\-\-pic\-executable\fR" 4
.IX Item "--pic-executable"
.PD
Create a position independent executable.  This is currently only supported on
\&\s-1ELF\s0 platforms.  Position independent executables are similar to shared
libraries in that they are relocated by the dynamic linker to the virtual
address the \s-1OS\s0 chooses for them (which can vary between invocations).  Like
normal dynamically linked executables they can be executed and symbols
defined in the executable cannot be overridden by shared libraries.
.IP "\fB\-qmagic\fR" 4
.IX Item "-qmagic"
This option is ignored for Linux compatibility.
.IP "\fB\-Qy\fR" 4
.IX Item "-Qy"
This option is ignored for \s-1SVR4\s0 compatibility.
.IP "\fB\-\-relax\fR" 4
.IX Item "--relax"
An option with machine dependent effects.
This option is only supported on a few targets.
.Sp
On some platforms, the \fB\-\-relax\fR 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.
.Sp
On some platforms these link time global optimizations may make symbolic
debugging of the resulting executable impossible.
This is known to be
the case for the Matsushita \s-1MN10200\s0 and \s-1MN10300\s0 family of processors.
.Sp
On platforms where this is not supported, \fB\-\-relax\fR is accepted,
but ignored.
.IP "\fB\-\-retain\-symbols\-file\fR \fIfilename\fR" 4
.IX Item "--retain-symbols-file filename"
Retain \fIonly\fR the symbols listed in the file \fIfilename\fR,
discarding all others.  \fIfilename\fR is simply a flat file, with one
symbol name per line.  This option is especially useful in environments
(such as VxWorks)
where a large global symbol table is accumulated gradually, to conserve
run-time memory.
.Sp
\&\fB\-\-retain\-symbols\-file\fR does \fInot\fR discard undefined symbols,
or symbols needed for relocations.
.Sp
You may only specify \fB\-\-retain\-symbols\-file\fR once in the command
line.  It overrides \fB\-s\fR and \fB\-S\fR.
.IP "\fB\-rpath\fR \fIdir\fR" 4
.IX Item "-rpath dir"
Add a directory to the runtime library search path.  This is used when
linking an \s-1ELF\s0 executable with shared objects.  All \fB\-rpath\fR
arguments are concatenated and passed to the runtime linker, which uses
them to locate shared objects at runtime.  The \fB\-rpath\fR option is
also used when locating shared objects which are needed by shared
objects explicitly included in the link; see the description of the
\&\fB\-rpath\-link\fR option.  If \fB\-rpath\fR is not used when linking an
\&\s-1ELF\s0 executable, the contents of the environment variable
\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it is defined.
.Sp
The \fB\-rpath\fR option may also be used on SunOS.  By default, on
SunOS, the linker will form a runtime search patch out of all the
\&\fB\-L\fR options it is given.  If a \fB\-rpath\fR option is used, the
runtime search path will be formed exclusively using the \fB\-rpath\fR
options, ignoring the \fB\-L\fR options.  This can be useful when using
gcc, which adds many \fB\-L\fR options which may be on \s-1NFS\s0 mounted
filesystems.
.Sp
For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
followed by a directory name, rather than a file name, it is treated as
the \fB\-rpath\fR option.
.IP "\fB\-rpath\-link\fR \fI\s-1DIR\s0\fR" 4
.IX Item "-rpath-link DIR"
When using \s-1ELF\s0 or SunOS, one shared library may require another.  This
happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one
of the input files.
.Sp
When the linker encounters such a dependency when doing a non\-shared,
non-relocatable link, it will automatically try to locate the required
shared library and include it in the link, if it is not included
explicitly.  In such a case, the \fB\-rpath\-link\fR option
specifies the first set of directories to search.  The
\&\fB\-rpath\-link\fR option may specify a sequence of directory names
either by specifying a list of names separated by colons, or by
appearing multiple times.
.Sp
This option should be used with caution as it overrides the search path
that may have been hard compiled into a shared library. In such a case it
is possible to use unintentionally a different search path than the
runtime linker would do.
.Sp
The linker uses the following search paths to locate required shared
libraries.
.RS 4
.IP "1." 4
Any directories specified by \fB\-rpath\-link\fR options.