xscale_be-ld.1

Intel ixp425 toolchain

.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\-\-embedded\-relocs\fR" 4
.IX Item "--embedded-relocs"
This option is only meaningful when linking \s-1MIPS\s0 embedded \s-1PIC\s0 code,
generated by the \-membedded\-pic option to the \s-1GNU\s0 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.
.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, nor should it be used with dynamic linking.  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
Normally when creating a non-symbolic shared library, undefined symbols
are allowed and left to be resolved by the runtime loader.  These options
disallows such undefined symbols.
.IP "\fB\-\-allow\-shlib\-undefined\fR" 4
.IX Item "--allow-shlib-undefined"
Allow undefined symbols in shared objects even  when \-\-no\-undefined is
set. The net result will be that undefined symbols in regular objects
will still trigger an error, but undefined symbols in shared objects
will be ignored.  The implementation of no_undefined makes the
assumption that the runtime linker will choke on undefined symbols.
However there is at least one system (BeOS) where undefined symbols in
shared libraries is normal since the kernel patches them at load time to
select which function is most appropriate for the current architecture.
I.E. dynamically select an appropriate memset function.  Apparently it
is also normal for \s-1HPPA\s0 shared libraries to have undefined 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\-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.
.IP "2." 4
Any directories specified by \fB\-rpath\fR options.  The difference
between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories
specified by \fB\-rpath\fR options are included in the executable and
used at runtime, whereas the \fB\-rpath\-link\fR option is only effective
at link time. It is for the native linker only.
.IP "3." 4
On an \s-1ELF\s0 system, if the \fB\-rpath\fR and \f(CW\*(C`rpath\-link\*(C'\fR options
were not used, search the contents of the environment variable
\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR. It is for the native linker only.
.IP "4." 4
On SunOS, if the \fB\-rpath\fR option was not used, search any
directories specified using \fB\-L\fR options.
.IP "5." 4
For a native linker, the contents of the environment variable
\&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR.
.IP "6." 4
For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or
\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared
libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if
\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist.
.IP "7." 4
The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
.IP "8." 4
For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR
exists, the list of directories found in that file.
.RE
.RS 4
.Sp
If the required shared library is not found, the linker will issue a
warning and continue with the link.
.RE
.IP "\fB\-shared\fR" 4
.IX Item "-shared"
.PD 0
.IP "\fB\-Bshareable\fR" 4
.IX Item "-Bshareable"
.PD
Create a shared library.  This is currently only supported on \s-1ELF\s0, \s-1XCOFF\s0
and SunOS platforms.  On SunOS, the linker will automatically create a
shared library if the \fB\-e\fR option is not used and there are
undefined symbols in the link.
.IP "\fB\-\-sort\-common\fR" 4
.IX Item "--sort-common"
This option tells \fBld\fR 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 byte, then all the four byte, and then
everything else.  This is to prevent gaps between symbols due to
alignment constraints.
.IP "\fB\-\-split\-by\-file [\fR\fIsize\fR\fB]\fR" 4
.IX Item "--split-by-file [size]"
Similar to \fB\-\-split\-by\-reloc\fR but creates a new output section for
each input file when \fIsize\fR is reached.  \fIsize\fR defaults to a
size of 1 if not given.
.IP "\fB\-\-split\-by\-reloc [\fR\fIcount\fR\fB]\fR" 4
.IX Item "--split-by-reloc [count]"
Tries to creates extra sections in the output file so that no single
output section in the file contains more than \fIcount\fR relocations.
This is useful when generating huge relocatable files for downloading into
certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0
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 \fIcount\fR relocations one output section will contain that
many relocations.  \fIcount\fR defaults to a value of 32768.
.IP "\fB\-\-stats\fR" 4
.IX Item "--stats"
Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
.IP "\fB\-\-traditional\-format\fR" 4
.IX Item "--traditional-format"
For some targets, the output of \fBld\fR is different in some ways from
the output of some existing linker.  This switch requests \fBld\fR to
use the traditional format instead.
.Sp
For example, on SunOS, \fBld\fR 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
\&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no
trouble).  The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not
combine duplicate entries.
.IP "\fB\-\-section\-start\fR \fIsectionname\fR\fB=\fR\fIorg\fR" 4
.IX Item "--section-start sectionname=org"
Locate a section in the output file at the absolute
address given by \fIorg\fR.  You may use this option as many
times as necessary to locate multiple sections in the command
line.
\&\fIorg\fR must be a single hexadecimal integer;
for compatibility with other linkers, you may omit the leading
\&\fB0x\fR usually associated with hexadecimal values.  \fINote:\fR there
should be no white space between \fIsectionname\fR, the equals
sign (``\fB=\fR''), and \fIorg\fR.
.IP "\fB\-Tbss\fR \fIorg\fR" 4
.IX Item "-Tbss org"
.PD 0