ld.1

MinGW+MSYS必备的开发工具链

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
file systems.
.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. Searching \fB\-rpath\fR in this way is only supported
by native linkers and cross linkers which have been configured with
the \fB\-\-with\-sysroot\fR option.
.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