-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "LD 1"
-.TH LD 1 "2007-08-28" "binutils-2.18" "GNU Development Tools"
+.TH LD 1 "2009-10-16" "binutils-2.20" "GNU Development Tools"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
ld \- The GNU linker
.SH "SYNOPSIS"
to operate on object files. This allows \fBld\fR to read, combine, and
write object files in many different formats\-\-\-for example, \s-1COFF\s0 or
\&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any
-available kind of object file.
+available kind of object file.
.PP
Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other
linkers in providing diagnostic information. Many linkers abandon
linker script or the one specified by using \fB\-T\fR). This feature
permits the linker to link against a file which appears to be an object
or an archive, but actually merely defines some symbol values, or uses
-\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Note that
-specifying a script in this way merely augments the main linker script;
-use the \fB\-T\fR option to replace the default linker script entirely.
+\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Specifying a
+script in this way merely augments the main linker script, with the
+extra commands placed after the main script; use the \fB\-T\fR option
+to replace the default linker script entirely, but note the effect of
+the \f(CW\*(C`INSERT\*(C'\fR command.
.PP
For options whose names are a single letter,
option arguments must either follow the option letter without intervening
compiler driver) like this:
.PP
.Vb 1
-\& gcc \-Wl,\-\-startgroup foo.o bar.o \-Wl,\-\-endgroup
+\& gcc \-Wl,\-\-start\-group foo.o bar.o \-Wl,\-\-end\-group
.Ve
.PP
This is important, because otherwise the compiler driver program may
-silently drop the linker options, resulting in a bad link.
+silently drop the linker options, resulting in a bad link. Confusion
+may also arise when passing options that require values through a
+driver, as the use of a space between option and argument acts as
+a separator, and causes the driver to pass only the option to the linker
+and the argument to the compiler. In this case, it is simplest to use
+the joined forms of both single\- and multiple-letter options, such as:
+.PP
+.Vb 1
+\& gcc foo.o bar.o \-Wl,\-eENTRY \-Wl,\-Map=a.map
+.Ve
.PP
Here is a table of the generic command line switches accepted by the \s-1GNU\s0
linker:
Read command-line options from \fIfile\fR. The options read are
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
does not exist, or cannot be read, then the option will be treated
-literally, and not removed.
+literally, and not removed.
.Sp
Options in \fIfile\fR are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
backslash) may be included by prefixing the character to be included
with a backslash. The \fIfile\fR may itself contain additional
@\fIfile\fR options; any such options will be processed recursively.
-.IP "\fB\-a\fR\fIkeyword\fR" 4
-.IX Item "-akeyword"
+.IP "\fB\-a\fR \fIkeyword\fR" 4
+.IX Item "-a keyword"
This option is supported for \s-1HP/UX\s0 compatibility. The \fIkeyword\fR
argument must be one of the strings \fBarchive\fR, \fBshared\fR, or
\&\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to
\&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent
to \fB\-Bdynamic\fR. This option may be used any number of times.
-.IP "\fB\-A\fR\fIarchitecture\fR" 4
-.IX Item "-Aarchitecture"
+.IP "\fB\-A\fR \fIarchitecture\fR" 4
+.IX Item "-A architecture"
.PD 0
.IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4
.IX Item "--architecture=architecture"
Intel 960 family of architectures. In that \fBld\fR configuration, the
\&\fIarchitecture\fR argument identifies the particular architecture in
the 960 family, enabling some safeguards and modifying the
-archive-library search path.
+archive-library search path.
.Sp
Future releases of \fBld\fR may support similar functionality for
other architecture families.
named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
and use that as the entry address (the number will be interpreted in
base 10; you may use a leading \fB0x\fR for base 16, or a leading
-\&\fB0\fR for base 8).
+\&\fB0\fR for base 8).
.IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4
.IX Item "--exclude-libs lib,lib,..."
Specifies a list of archive libraries from which symbols should not be automatically
-exported. The library names may be delimited by commas or colons. Specifying
+exported. The library names may be delimited by commas or colons. Specifying
\&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from
automatic export. This option is available only for the i386 \s-1PE\s0 targeted
port of the linker and for \s-1ELF\s0 targeted ports. For i386 \s-1PE\s0, symbols
explicitly listed in a .def file are still exported, regardless of this
option. For \s-1ELF\s0 targeted ports, symbols affected by this option will
be treated as hidden.
+.IP "\fB\-\-exclude\-modules\-for\-implib\fR \fImodule\fR\fB,\fR\fImodule\fR\fB,...\fR" 4
+.IX Item "--exclude-modules-for-implib module,module,..."
+Specifies a list of object files or archive members, from which symbols
+should not be automatically exported, but which should be copied wholesale
+into the import library being generated during the link. The module names
+may be delimited by commas or colons, and must match exactly the filenames
+used by \fBld\fR to open the files; for archive members, this is simply
+the member name, but for object files the name listed must include and
+match precisely any path used to specify the input file on the linker's
+command-line. This option is available only for the i386 \s-1PE\s0 targeted port
+of the linker. Symbols explicitly listed in a .def file are still exported,
+regardless of this option.
.IP "\fB\-E\fR" 4
.IX Item "-E"
.PD 0
.IP "\fB\-\-export\-dynamic\fR" 4
.IX Item "--export-dynamic"
+.IP "\fB\-\-no\-export\-dynamic\fR" 4
+.IX Item "--no-export-dynamic"
.PD
-When creating a dynamically linked executable, add all symbols to the
-dynamic symbol table. The dynamic symbol table is the set of symbols
-which are visible from dynamic objects at run time.
+When creating a dynamically linked executable, using the \fB\-E\fR
+option or the \fB\-\-export\-dynamic\fR option causes the linker to add
+all symbols to the dynamic symbol table. The dynamic symbol table is the
+set of symbols which are visible from dynamic objects at run time.
.Sp
-If you do not use this option, the dynamic symbol table will normally
-contain only those symbols which are referenced by some dynamic object
-mentioned in the link.
+If you do not use either of these options (or use the
+\&\fB\-\-no\-export\-dynamic\fR option to restore the default behavior), the
+dynamic symbol table will normally contain only those symbols which are
+referenced by some dynamic object mentioned in the link.
.Sp
If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer
back to the symbols defined by the program, rather than some other
You can also use the dynamic list to control what symbols should
be added to the dynamic symbol table if the output format supports it.
See the description of \fB\-\-dynamic\-list\fR.
+.Sp
+Note that this option is specific to \s-1ELF\s0 targeted ports. \s-1PE\s0 targets
+support a similar function to export all symbols from a \s-1DLL\s0 or \s-1EXE\s0; see
+the description of \fB\-\-export\-all\-symbols\fR below.
.IP "\fB\-EB\fR" 4
.IX Item "-EB"
Link big-endian objects. This affects the default output format.
.IP "\fB\-EL\fR" 4
.IX Item "-EL"
Link little-endian objects. This affects the default output format.
-.IP "\fB\-f\fR" 4
-.IX Item "-f"
+.IP "\fB\-f\fR \fIname\fR" 4
+.IX Item "-f name"
.PD 0
-.IP "\fB\-\-auxiliary\fR \fIname\fR" 4
-.IX Item "--auxiliary name"
+.IP "\fB\-\-auxiliary=\fR\fIname\fR" 4
+.IX Item "--auxiliary=name"
.PD
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field
to the specified name. This tells the dynamic linker that the symbol
.IP "\fB\-F\fR \fIname\fR" 4
.IX Item "-F name"
.PD 0
-.IP "\fB\-\-filter\fR \fIname\fR" 4
-.IX Item "--filter name"
+.IP "\fB\-\-filter=\fR\fIname\fR" 4
+.IX Item "--filter=name"
.PD
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to
the specified name. This tells the dynamic linker that the symbol table
environment variable.
The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not
creating an \s-1ELF\s0 shared object.
-.IP "\fB\-fini\fR \fIname\fR" 4
-.IX Item "-fini name"
+.IP "\fB\-fini=\fR\fIname\fR" 4
+.IX Item "-fini=name"
When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
address of the function. By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as
.IP "\fB\-g\fR" 4
.IX Item "-g"
Ignored. Provided for compatibility with other tools.
-.IP "\fB\-G\fR\fIvalue\fR" 4
-.IX Item "-Gvalue"
+.IP "\fB\-G\fR \fIvalue\fR" 4
+.IX Item "-G value"
.PD 0
.IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4
.IX Item "--gpsize=value"
\&\fIsize\fR. This is only meaningful for object file formats such as
\&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different
sections. This is ignored for other object file formats.
-.IP "\fB\-h\fR\fIname\fR" 4
-.IX Item "-hname"
+.IP "\fB\-h\fR \fIname\fR" 4
+.IX Item "-h name"
.PD 0
.IP "\fB\-soname=\fR\fIname\fR" 4
.IX Item "-soname=name"
.IP "\fB\-i\fR" 4
.IX Item "-i"
Perform an incremental link (same as option \fB\-r\fR).
-.IP "\fB\-init\fR \fIname\fR" 4
-.IX Item "-init name"
+.IP "\fB\-init=\fR\fIname\fR" 4
+.IX Item "-init=name"
When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
of the function. By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the
function to call.
-.IP "\fB\-l\fR\fInamespec\fR" 4
-.IX Item "-lnamespec"
+.IP "\fB\-l\fR \fInamespec\fR" 4
+.IX Item "-l namespec"
.PD 0
.IP "\fB\-\-library=\fR\fInamespec\fR" 4
.IX Item "--library=namespec"
Add the archive or object file specified by \fInamespec\fR to the
list of files to link. This option may be used any number of times.
If \fInamespec\fR is of the form \fI:\fIfilename\fI\fR, \fBld\fR
-will search the library path for a file called \fIfilename\fR, otherise it
+will search the library path for a file called \fIfilename\fR, otherwise it
will search the library path for a file called \fIlib\fInamespec\fI.a\fR.
.Sp
On systems which support shared libraries, \fBld\fR may also search for
This type of archive searching is standard for Unix linkers. However,
if you are using \fBld\fR on \s-1AIX\s0, note that it is different from the
behaviour of the \s-1AIX\s0 linker.
-.IP "\fB\-L\fR\fIsearchdir\fR" 4
-.IX Item "-Lsearchdir"
+.IP "\fB\-L\fR \fIsearchdir\fR" 4
+.IX Item "-L searchdir"
.PD 0
.IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4
.IX Item "--library-path=searchdir"
in which they are specified on the command line. Directories specified
on the command line are searched before the default directories. All
\&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the
-order in which the options appear.
+order in which the options appear. \fB\-L\fR options do not affect
+how \fBld\fR searches for a linker script unless \fB\-T\fR
+option is specified.
.Sp
If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced
by the \fIsysroot prefix\fR, a path specified when the linker is configured.
.Sp
The default set of paths searched (without being specified with
\&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in
-some cases also on how it was configured.
+some cases also on how it was configured.
.Sp
The paths can also be specified in a link script with the
\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched
at the point in which the linker script appears in the command line.
-.IP "\fB\-m\fR\fIemulation\fR" 4
-.IX Item "-memulation"
+.IP "\fB\-m\fR \fIemulation\fR" 4
+.IX Item "-m emulation"
Emulate the \fIemulation\fR linker. You can list the available
emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.
.Sp
Print a link map to the standard output. A link map provides
information about the link, including the following:
.RS 4
-.IP "*" 4
+.IP "\(bu" 4
Where object files are mapped into memory.
-.IP "*" 4
+.IP "\(bu" 4
How common symbols are allocated.
-.IP "*" 4
+.IP "\(bu" 4
All archive members included in the link, with a mention of the symbol
which caused the archive member to be brought in.
-.IP "*" 4
+.IP "\(bu" 4
The values assigned to symbols.
.Sp
Note \- symbols whose values are computed by an expression which
.IP "\fB\-\-no\-omagic\fR" 4
.IX Item "--no-omagic"
This option negates most of the effects of the \fB\-N\fR option. It
-sets the text section to be read\-only, and forces the data segment to
-be page\-aligned. Note \- this option does not enable linking against
+sets the text section to be read-only, and forces the data segment to
+be page-aligned. Note \- this option does not enable linking against
shared libraries. Use \fB\-Bdynamic\fR for this.
.IP "\fB\-o\fR \fIoutput\fR" 4
.IX Item "-o output"
.IP "\fB\-\-default\-script=\fR\fIscriptfile\fR" 4
.IX Item "--default-script=scriptfile"
.PD
-Use \fIscriptfile\fR as the default linker script.
+Use \fIscriptfile\fR as the default linker script.
.Sp
This option is similar to the \fB\-\-script\fR option except that
processing of the script is delayed until after the rest of the
on the command line after the \fB\-\-as\-needed\fR option. Normally,
the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned
on the command line, regardless of whether the library is actually
-needed. \fB\-\-as\-needed\fR causes \s-1DT_NEEDED\s0 tags to only be emitted
-for libraries that satisfy some symbol reference from regular objects
-which is undefined at the point that the library was linked.
+needed. \fB\-\-as\-needed\fR causes a \s-1DT_NEEDED\s0 tag to only be emitted
+for a library that satisfies a symbol reference from regular objects
+which is undefined at the point that the library was linked, or, if
+the library is not found in the \s-1DT_NEEDED\s0 lists of other libraries
+linked up to that point, a reference from another dynamic library.
\&\fB\-\-no\-as\-needed\fR restores the default behaviour.
.IP "\fB\-\-add\-needed\fR" 4
.IX Item "--add-needed"
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.
+Section overlap is not usually checked for relocatable links. You can
+force checking in that case by using the \fB\-\-check\-sections\fR
+option.
.IP "\fB\-\-cref\fR" 4
.IX Item "--cref"
Output a cross reference table. If a linker map file is being
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"
+.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
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"
+.IP "\fB\-I\fR\fIfile\fR" 4
+.IX Item "-Ifile"
+.PD 0
+.IP "\fB\-\-dynamic\-linker=\fR\fIfile\fR" 4
+.IX Item "--dynamic-linker=file"
+.PD
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.
+.PD 0
+.IP "\fB\-\-no\-fatal\-warnings\fR" 4
+.IX Item "--no-fatal-warnings"
+.PD
+Treat all warnings as errors. The default behaviour can be restored
+with the option \fB\-\-no\-fatal\-warnings\fR.
.IP "\fB\-\-force\-exe\-suffix\fR" 4
.IX Item "--force-exe-suffix"
Make sure that an output file has a .exe suffix.
.IX Item "--no-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 or \fB\-\-emit\-relocs\fR. The default behaviour (of not
+targets that do not support this option. The default behaviour (of not
performing this garbage collection) can be restored by specifying
\&\fB\-\-no\-gc\-sections\fR on the command line.
+.Sp
+\&\fB\-\-gc\-sections\fR decides which input sections are used by
+examining symbols and relocations. The section containing the entry
+symbol and all sections containing symbols undefined on the
+command-line will be kept, as will sections containing symbols
+referenced by dynamic objects. Note that when building shared
+libraries, the linker must assume that any visible symbol is
+referenced. Once this initial set of sections has been determined,
+the linker recursively marks as used any section referenced by their
+relocations. See \fB\-\-entry\fR and \fB\-\-undefined\fR.
+.Sp
+This option can be set when doing a partial link (enabled with option
+\&\fB\-r\fR). In this case the root of symbols kept must be explicitely
+specified either by an \fB\-\-entry\fR or \fB\-\-undefined\fR option or by
+a \f(CW\*(C`ENTRY\*(C'\fR command in the linker script.
.IP "\fB\-\-print\-gc\-sections\fR" 4
.IX Item "--print-gc-sections"
.PD 0
.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"
+.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
.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.
+Allows 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.
+The default behaviour is to report errors for any undefined symbols
+referenced in shared libraries if the linker is being used to create
+an executable, but to allow them if the linker is being used to create
+a shared library.
+.Sp
+The reasons for allowing undefined symbol references in shared
+libraries specified at link time are that:
+.RS 4
+.IP "\(bu" 4
+A shared library specified at link time may not be the same as the one
+that is available at load time, so the symbol might actually be
+resolvable at load time.
+.IP "\(bu" 4
+There are some operating systems, eg BeOS and \s-1HPPA\s0, where undefined
+symbols in shared libraries are normal.
+.Sp
+The BeOS kernel for example patches shared libraries at load time to
+select whichever function is most appropriate for the current
+architecture. This is used, for example, to dynamically select an
+appropriate memset function.
+.RE
+.RS 4
+.RE
.IP "\fB\-\-no\-undefined\-version\fR" 4
.IX Item "--no-undefined-version"
Normally when a symbol has an undefined version, the linker will ignore
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"
+.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
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.
+this option overrides it.
.IP "\fB\-pie\fR" 4
.IX Item "-pie"
.PD 0
.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"
+.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
.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"
+.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
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"
+.IP "\fB\-rpath\-link=\fR\fIdir\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,
+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
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.
+On an \s-1ELF\s0 system, for native linkers, if the \fB\-rpath\fR and
+\&\fB\-rpath\-link\fR options were not used, search the contents of the
+environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR.
.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.
+For a native linker, the search 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
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"
+.PD 0
+.IP "\fB\-\-sort\-common=ascending\fR" 4
+.IX Item "--sort-common=ascending"
+.IP "\fB\-\-sort\-common=descending\fR" 4
+.IX Item "--sort-common=descending"
+.PD
+This option tells \fBld\fR to sort the common symbols by alignment in
+ascending or descending order when it places them in the appropriate output
+sections. The symbol alignments considered are sixteen-byte or larger,
+eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
+between symbols due to alignment constraints. If no sorting order is
+specified, then descending order is assumed.
+.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"
+.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]"
+.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]"
+.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
\&\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"
+.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
\&\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"
+.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"
+.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
+Same as \fB\-\-section\-start\fR, 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\-Ttext\-segment=\fR\fIorg\fR" 4
+.IX Item "-Ttext-segment=org"
+When creating an \s-1ELF\s0 executable or shared object, it will set the address
+of the first byte of the text segment.
.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4
.IX Item "--unresolved-symbols=method"
Determine how to handle unresolved symbols. There are four possible
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.
+is only fully supported on \s-1ELF\s0 platforms which support shared libraries;
+see \fB\s-1VERSION\s0\fR. It is partially supported on \s-1PE\s0 platforms, which can
+use version scripts to filter symbol visibility in auto-export mode: any
+symbols marked \fBlocal\fR in the version script will not be exported.
.IP "\fB\-\-warn\-common\fR" 4
.IX Item "--warn-common"
Warn when a common symbol is combined with another common symbol or with
definition for the symbol.
.Sp
.Vb 3
-\& <file>(<section>): warning: common of `<symbol>'
+\& <file>(<section>): warning: common of \`<symbol>\*(Aq
\& overridden by definition
\& <file>(<section>): warning: defined here
.Ve
except that the symbols are encountered in a different order.
.Sp
.Vb 3
-\& <file>(<section>): warning: definition of `<symbol>'
+\& <file>(<section>): warning: definition of \`<symbol>\*(Aq
\& overriding common
\& <file>(<section>): warning: common is here
.Ve
.Sp
.Vb 3
\& <file>(<section>): warning: multiple common
-\& of `<symbol>'
+\& of \`<symbol>\*(Aq
\& <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>'
+\& <file>(<section>): warning: common of \`<symbol>\*(Aq
\& overridden by larger common
\& <file>(<section>): warning: larger common is here
.Ve
encountered in a different order.
.Sp
.Vb 3
-\& <file>(<section>): warning: common of `<symbol>'
+\& <file>(<section>): warning: common of \`<symbol>\*(Aq
\& overriding smaller common
\& <file>(<section>): warning: smaller common is here
.Ve
.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\-alternate\-em\fR" 4
+.IX Item "--warn-alternate-em"
+Warn if an object has alternate \s-1ELF\s0 machine code.
.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
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"
+.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
.Sp
.Vb 6
\& void *
-\& __wrap_malloc (size_t c)
+\& _\|_wrap_malloc (size_t c)
\& {
\& printf ("malloc called with %zu\en", c);
-\& return __real_malloc (c);
+\& return _\|_real_malloc (c);
\& }
.Ve
.Sp
\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR
file.
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.IP "\fB\-\-enable\-long\-section\-names\fR" 4
+.IX Item "--enable-long-section-names"
+.PD 0
+.IP "\fB\-\-disable\-long\-section\-names\fR" 4
+.IX Item "--disable-long-section-names"
+.PD
+The \s-1PE\s0 variants of the Coff object format add an extension that permits
+the use of section names longer than eight characters, the normal limit
+for Coff. By default, these names are only allowed in object files, as
+fully-linked executable images do not carry the Coff string table required
+to support the longer names. As a \s-1GNU\s0 extension, it is possible to
+allow their use in executable images as well, or to (probably pointlessly!)
+disallow it in object files, by using these two options. Executable images
+generated with these long section names are slightly non-standard, carrying
+as they do a string table, and may generate confusing output when examined
+with non-GNU PE-aware tools, such as file viewers and dumpers. However,
+\&\s-1GDB\s0 relies on the use of \s-1PE\s0 long section names to find Dwarf\-2 debug
+information sections in an executable image at runtime, and so if neither
+option is specified on the command-line, \fBld\fR will enable long
+section names, overriding the default and technically correct behaviour,
+when it finds the presence of debug information while linking an executable
+image and not stripping symbols.
+[This option is valid for all \s-1PE\s0 targeted ports of the linker]
.IP "\fB\-\-enable\-stdcall\-fixup\fR" 4
.IX Item "--enable-stdcall-fixup"
.PD 0
\&\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
+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.
to be made writable. This does not conform to the PE-COFF format
specification published by Microsoft.
.Sp
+Note \- use of the 'auto\-import' extension will also cause read only
+data which would normally be placed into the .rdata section to be
+placed into the .data section instead. This is in order to work
+around a problem with consts that is described here:
+http://www.cygwin.com/ml/cygwin/2004\-09/msg01101.html
+.Sp
Using 'auto\-import' generally will 'just work' \*(-- but sometimes you may
see this message:
.Sp
-"variable '<var>' can't be auto\-imported. Please read the
+"variable '<var>' can't be auto-imported. Please read the
documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details."
.Sp
This message occurs when some (sub)expression accesses an address
.Sp
Solution 2:
.Sp
-.Vb 14
+.Vb 10
\& \-\-foo.h
-\& /* Note: auto\-export is assumed (no __declspec(dllexport)) */
-\& #if (defined(_WIN32) || defined(__CYGWIN__)) && \e
+\& /* Note: auto\-export is assumed (no _\|_declspec(dllexport)) */
+\& #if (defined(_WIN32) || defined(_\|_CYGWIN_\|_)) && \e
\& !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
-\& #define FOO_IMPORT __declspec(dllimport)
+\& #define FOO_IMPORT _\|_declspec(dllimport)
\& #else
\& #define FOO_IMPORT
\& #endif
the subsystem version also. Numeric values are also accepted for
\&\fIwhich\fR.
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
+.Sp
+The following options set flags in the \f(CW\*(C`DllCharacteristics\*(C'\fR field
+of the \s-1PE\s0 file header:
+[These options are specific to \s-1PE\s0 targeted ports of the linker]
+.IP "\fB\-\-dynamicbase\fR" 4
+.IX Item "--dynamicbase"
+The image base address may be relocated using address space layout
+randomization (\s-1ASLR\s0). This feature was introduced with \s-1MS\s0 Windows
+Vista for i386 \s-1PE\s0 targets.
+.IP "\fB\-\-forceinteg\fR" 4
+.IX Item "--forceinteg"
+Code integrity checks are enforced.
+.IP "\fB\-\-nxcompat\fR" 4
+.IX Item "--nxcompat"
+The image is compatible with the Data Execution Prevention.
+This feature was introduced with \s-1MS\s0 Windows \s-1XP\s0 \s-1SP2\s0 for i386 \s-1PE\s0 targets.
+.IP "\fB\-\-no\-isolation\fR" 4
+.IX Item "--no-isolation"
+Although the image understands isolation, do not isolate the image.
+.IP "\fB\-\-no\-seh\fR" 4
+.IX Item "--no-seh"
+The image does not use \s-1SEH\s0. No \s-1SE\s0 handler may be called from
+this image.
+.IP "\fB\-\-no\-bind\fR" 4
+.IX Item "--no-bind"
+Do not bind this image.
+.IP "\fB\-\-wdmdriver\fR" 4
+.IX Item "--wdmdriver"
+The driver uses the \s-1MS\s0 Windows Driver Model.
+.IP "\fB\-\-tsaware\fR" 4
+.IX Item "--tsaware"
+The image is Terminal Server aware.
.PP
The 68HC11 and 68HC12 linkers support specific options to control the
memory bank switching mapping and trampoline code generation.
the \fB\s-1MEMORY\s0\fR specification that describes the memory bank window.
The definition of such region is then used by the linker to compute
paging and addresses within the memory window.
+.PP
+The following options are supported to control handling of \s-1GOT\s0 generation
+when linking for 68K targets.
+.IP "\fB\-\-got=\fR\fItype\fR" 4
+.IX Item "--got=type"
+This option tells the linker which \s-1GOT\s0 generation scheme to use.
+\&\fItype\fR should be one of \fBsingle\fR, \fBnegative\fR,
+\&\fBmultigot\fR or \fBtarget\fR. For more information refer to the
+Info entry for \fIld\fR.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
You can change the behaviour of \fBld\fR with the environment variables
there is no method of ensuring that the magic number used to specify
object-file formats is unique. However, the configuration procedure for
\&\s-1BFD\s0 on each system places the conventional format for that system first
-in the search\-list, so ambiguities are resolved in favor of convention.
+in the search-list, so ambiguities are resolved in favor of convention.
.PP
\&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the
\&\fB\-m\fR option. The emulation can affect various aspects of linker
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
-under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
projects / msp430-binutils.git / blobdiff