xscale_be-ld.1

Intel ixp425 toolchain

.IP "\fB\-Tdata\fR \fIorg\fR" 4
.IX Item "-Tdata org"
.IP "\fB\-Ttext\fR \fIorg\fR" 4
.IX Item "-Ttext org"
.PD
Use \fIorg\fR as the starting address for\-\-\-respectively\-\-\-the
\&\f(CW\*(C`bss\*(C'\fR, \f(CW\*(C`data\*(C'\fR, or the \f(CW\*(C`text\*(C'\fR segment of the output file.
\&\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.
.IP "\fB\-\-dll\-verbose\fR" 4
.IX Item "--dll-verbose"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Display the version number for \fBld\fR and list the linker emulations
supported.  Display which input files can and cannot be opened.  Display
the linker script being used by the linker.
.IP "\fB\-\-version\-script=\fR\fIversion-scriptfile\fR" 4
.IX Item "--version-script=version-scriptfile"
Specify the name of a version script to the linker.  This is typically
used when creating shared libraries to specify additional information
about the version heirarchy for the library being created.  This option
is only meaningful on \s-1ELF\s0 platforms which support shared libraries.
.IP "\fB\-\-warn\-common\fR" 4
.IX 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
you to find potential problems from combining global symbols.
Unfortunately, some C libraries use this practice, so you may get some
warnings about symbols in the libraries as well as in your programs.
.Sp
There are three kinds of global symbols, illustrated here by C examples:
.RS 4
.IP "\fBint i = 1;\fR" 4
.IX Item "int i = 1;"
A definition, which goes in the initialized data section of the output
file.
.IP "\fBextern int i;\fR" 4
.IX Item "extern int i;"
An undefined reference, which does not allocate space.
There must be either a definition or a common symbol for the
variable somewhere.
.IP "\fBint i;\fR" 4
.IX Item "int i;"
A common symbol.  If there are only (one or more) common symbols for a
variable, it goes in the uninitialized data area of the output file.
The linker merges multiple common symbols for the same variable into a
single symbol.  If they are of different sizes, it picks the largest
size.  The linker turns a common symbol into a declaration, if there is
a definition of the same variable.
.RE
.RS 4
.Sp
The \fB\-\-warn\-common\fR 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.
.IP "1." 4
Turning a common symbol into a reference, because there is already a
definition for the symbol.
.Sp
.Vb 3
\&        I<file>(I<section>): warning: common of `I<symbol>'
\&           overridden by definition
\&        I<file>(I<section>): warning: defined here
.Ve
.IP "2." 4
Turning a common symbol into a reference, because a later definition for
the symbol is encountered.  This is the same as the previous case,
except that the symbols are encountered in a different order.
.Sp
.Vb 3
\&        I<file>(I<section>): warning: definition of `I<symbol>'
\&           overriding common
\&        I<file>(I<section>): warning: common is here
.Ve
.IP "3." 4
Merging a common symbol with a previous same-sized common symbol.
.Sp
.Vb 3
\&        I<file>(I<section>): warning: multiple common
\&           of `I<symbol>'
\&        I<file>(I<section>): warning: previous common is here
.Ve
.IP "4." 4
Merging a common symbol with a previous larger common symbol.
.Sp
.Vb 3
\&        I<file>(I<section>): warning: common of `I<symbol>'
\&           overridden by larger common
\&        I<file>(I<section>): warning: larger common is here
.Ve
.IP "5." 4
Merging a common symbol with a previous smaller common symbol.  This is
the same as the previous case, except that the symbols are
encountered in a different order.
.Sp
.Vb 3
\&        I<file>(I<section>): warning: common of `I<symbol>'
\&           overriding smaller common
\&        I<file>(I<section>): warning: smaller common is here
.Ve
.RE
.RS 4
.RE
.IP "\fB\-\-warn\-constructors\fR" 4
.IX Item "--warn-constructors"
Warn if any global constructors are used.  This is only useful for a few
object file formats.  For formats like \s-1COFF\s0 or \s-1ELF\s0, the linker can not
detect the use of global constructors.
.IP "\fB\-\-warn\-multiple\-gp\fR" 4
.IX 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
section.  A special register (the global pointer) points into the middle
of this section, so that constants can be loaded efficiently via a
base-register relative addressing mode.  Since the offset in
base-register relative mode is fixed and relatively small (e.g., 16
bits), this limits the maximum size of the constant pool.  Thus, in
large programs, it is often necessary to use multiple global pointer
values in order to be able to address all possible constants.  This
option causes a warning to be issued whenever this case occurs.
.IP "\fB\-\-warn\-once\fR" 4
.IX Item "--warn-once"
Only warn once for each undefined symbol, rather than once per module
which refers to it.
.IP "\fB\-\-warn\-section\-align\fR" 4
.IX 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 \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for
the section.
.IP "\fB\-\-whole\-archive\fR" 4
.IX Item "--whole-archive"
For each archive mentioned on the command line after the
\&\fB\-\-whole\-archive\fR option, include every object file in the 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.  This option may be used more than once.
.Sp
Two notes when using this option from gcc: First, gcc doesn't know
about this option, so you have to use \fB\-Wl,\-whole\-archive\fR.
Second, don't forget to use \fB\-Wl,\-no\-whole\-archive\fR after your
list of archives, because gcc will add its own list of archives to
your link and you may not want this flag to affect those as well.
.IP "\fB\-\-wrap\fR \fIsymbol\fR" 4
.IX Item "--wrap symbol"
Use a wrapper function for \fIsymbol\fR.  Any undefined reference to
\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  Any
undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR will be resolved to
\&\fIsymbol\fR.
.Sp
This can be used to provide a wrapper for a system function.  The
wrapper function should be called \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  If it
wishes to call the system function, it should call
\&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR.
.Sp
Here is a trivial example:
.Sp
.Vb 6
\&        void *
\&        __wrap_malloc (int c)
\&        {
\&          printf ("malloc called with %ld\en", c);
\&          return __real_malloc (c);
\&        }
.Ve
If you link other code with this file using \fB\-\-wrap malloc\fR, then
all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR
instead.  The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will
call the real \f(CW\*(C`malloc\*(C'\fR function.
.Sp
You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that
links without the \fB\-\-wrap\fR option will succeed.  If you do this,
you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same
file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the
call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR.
.IP "\fB\-\-enable\-new\-dtags\fR" 4
.IX Item "--enable-new-dtags"
.PD 0
.IP "\fB\-\-disable\-new\-dtags\fR" 4
.IX Item "--disable-new-dtags"
.PD
This linker can create the new dynamic tags in \s-1ELF\s0. But the older \s-1ELF\s0
systems may not understand them. If you specify
\&\fB\-\-enable\-new\-dtags\fR, the dynamic tags will be created as needed.
If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be
created. By default, the new dynamic tags are not created. Note that
those options are only available for \s-1ELF\s0 systems.
.PP
The i386 \s-1PE\s0 linker supports the \fB\-shared\fR option, which causes
the output to be a dynamically linked library (\s-1DLL\s0) instead of a
normal executable.  You should name the output \f(CW\*(C`*.dll\*(C'\fR when you
use this option.  In addition, the linker fully supports the standard
\&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line
like an object file (in fact, it should precede archives it exports
symbols from, to ensure that they get linked in, just like a normal
object file).
.PP
In addition to the options common to all targets, the i386 \s-1PE\s0 linker
support additional command line options that are specific to the i386
\&\s-1PE\s0 target.  Options that take values may be separated from their
values by either a space or an equals sign.
.IP "\fB\-\-add\-stdcall\-alias\fR" 4
.IX Item "--add-stdcall-alias"
If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
as-is and also with the suffix stripped.
.IP "\fB\-\-base\-file\fR \fIfile\fR" 4
.IX Item "--base-file file"
Use \fIfile\fR as the name of a file in which to save the base
addresses of all the relocations needed for generating DLLs with
\&\fIdlltool\fR.
.IP "\fB\-\-dll\fR" 4
.IX Item "--dll"
Create a \s-1DLL\s0 instead of a regular executable.  You may also use
\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR
file.
.IP "\fB\-\-enable\-stdcall\-fixup\fR" 4
.IX Item "--enable-stdcall-fixup"
.PD 0
.IP "\fB\-\-disable\-stdcall\-fixup\fR" 4
.IX Item "--disable-stdcall-fixup"
.PD
If the link finds a symbol that it cannot resolve, it will attempt to
do \*(L"fuzzy linking\*(R" by looking for another defined symbol that differs
only in the format of the symbol name (cdecl vs stdcall) and will
resolve that symbol by linking to the match.  For example, the
undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function
\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked
to the function \f(CW\*(C`_bar\*(C'\fR.  When the linker does this, it prints a
warning, since it normally should have failed to link, but sometimes
import libraries generated from third-party dlls may need this feature
to be usable.  If you specify \fB\-\-enable\-stdcall\-fixup\fR, this
feature is fully enabled and warnings are not printed.  If you specify
\&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such
mismatches are considered to be errors.
.IP "\fB\-\-export\-all\-symbols\fR" 4
.IX Item "--export-all-symbols"
If given, all global symbols in the objects used to build a \s-1DLL\s0 will
be exported by the \s-1DLL\s0.  Note that this is the default if there
otherwise wouldn't be any exported symbols.  When symbols are
explicitly exported via \s-1DEF\s0 files or implicitly exported via function
attributes, the default is to not export anything else unless this
option is given.  Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR,
\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and 
\&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically
exported.  Also, symbols imported from other DLLs will not be 
re\-exported, nor will symbols specifying the \s-1DLL\s0's internal layout 
such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with 
\&\f(CW\*(C`_iname\*(C'\fR.  In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR, 
\&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported.
Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will
not be exported, to help with \*(C+ DLLs.  Finally, there is an
extensive list of cygwin-private symbols that are not exported 
(obviously, this applies on when building DLLs for cygwin targets).
These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR, 
\&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_dll_entry@12\*(C'\fR,
\&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR, 
\&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR,
\&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR. 
.IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4
.IX Item "--exclude-symbols symbol,symbol,..."
Specifies a list of symbols which should not be automatically
exported.  The symbol names may be delimited by commas or colons.
.IP "\fB\-\-file\-alignment\fR" 4
.IX Item "--file-alignment"
Specify the file alignment.  Sections in the file will always begin at
file offsets which are multiples of this number.  This defaults to
512.
.IP "\fB\-\-heap\fR \fIreserve\fR" 4
.IX Item "--heap reserve"
.PD 0
.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
.IX Item "--heap reserve,commit"
.PD
Specify the amount of memory to reserve (and optionally commit) to be
used as heap for this program.  The default is 1Mb reserved, 4K
committed.
.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4
.IX Item "--image-base value"
Use \fIvalue\fR as the base address of your program or dll.  This is
the lowest memory location that will be used when your program or dll
is loaded.  To reduce the need to relocate and improve performance of
your dlls, each should have a unique base addr