arm-linux-ld.1

arm-linux.rar

.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\-\-sort\-section name\fR" 4
.IX Item "--sort-section name"
This option will apply \f(CW\*(C`SORT_BY_NAME\*(C'\fR to all wildcard section
patterns in the linker script.
.IP "\fB\-\-sort\-section alignment\fR" 4
.IX Item "--sort-section alignment"
This option will apply \f(CW\*(C`SORT_BY_ALIGNMENT\*(C'\fR to all wildcard section
patterns in the linker script.
.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\-\-sysroot=\fR\fIdirectory\fR" 4
.IX Item "--sysroot=directory"
Use \fIdirectory\fR as the location of the sysroot, overriding the
configure-time default.  This option is only supported by linkers
that were configured using \fB\-\-with\-sysroot\fR.
.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
.IP "\fB\-Tdata\fR \fIorg\fR" 4
.IX Item "-Tdata org"
.IP "\fB\-Ttext\fR \fIorg\fR" 4
.IX Item "-Ttext org"
.PD
Same as \-\-section\-start, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or
\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR.
.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4
.IX Item "--unresolved-symbols=method"
Determine how to handle unresolved symbols.  There are four possible
values for \fBmethod\fR:
.RS 4
.IP "\fBignore-all\fR" 4
.IX Item "ignore-all"
Do not report any unresolved symbols.
.IP "\fBreport-all\fR" 4
.IX Item "report-all"
Report all unresolved symbols.  This is the default.
.IP "\fBignore-in-object-files\fR" 4
.IX Item "ignore-in-object-files"
Report unresolved symbols that are contained in shared libraries, but
ignore them if they come from regular object files.
.IP "\fBignore-in-shared-libs\fR" 4
.IX Item "ignore-in-shared-libs"
Report unresolved symbols that come from regular object files, but
ignore them if they come from shared libraries.  This can be useful
when creating a dynamic binary and it is known that all the shared
libraries that it should be referencing are included on the linker's
command line.
.RE
.RS 4
.Sp
The behaviour for shared libraries on their own can also be controlled
by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option.
.Sp
Normally the linker will generate an error message for each reported
unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR
can change this to a warning.
.RE
.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 hierarchy 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 practise,
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 practise, 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
\&        <file>(<section>): warning: common of `<symbol>'
\&           overridden by definition
\&        <file>(<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
\&        <file>(<section>): warning: definition of `<symbol>'
\&           overriding common
\&        <file>(<section>): warning: common is here
.Ve
.IP "3." 4
Merging a common symbol with a previous same-sized common symbol.
.Sp
.Vb 3
\&        <file>(<section>): warning: multiple common
\&           of `<symbol>'
\&        <file>(<section>): warning: previous common is here
.Ve
.IP "4." 4
Merging a common symbol with a previous larger common symbol.
.Sp
.Vb 3
\&        <file>(<section>): warning: common of `<symbol>'
\&           overridden by larger common
\&        <file>(<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
\&        <file>(<section>): warning: common of `<symbol>'
\&           overriding smaller common
\&        <file>(<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\-\-warn\-shared\-textrel\fR" 4
.IX Item "--warn-shared-textrel"
Warn if the linker adds a \s-1DT_TEXTREL\s0 to a shared object.  
.IP "\fB\-\-warn\-unresolved\-symbols\fR" 4
.IX Item "--warn-unresolved-symbols"
If the linker is going to report an unresolved symbol (see the option
\&\fB\-\-unresolved\-symbols\fR) it will normally generate an error.
This option makes it generate a warning instead.
.IP "\fB\-\-error\-unresolved\-symbols\fR" 4
.IX Item "--error-unresolved-symbols"
This restores the linker's default behaviour of generating errors when
it is reporting unresolved symbols.
.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\-whol