@samp{-Bstatic}, and the other two keywords are functionally equivalent
to @samp{-Bdynamic}. This option may be used any number of times.
+@kindex --audit @var{AUDITLIB}
+@item --audit @var{AUDITLIB}
+Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
+@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
+specified in the library. If specified multiple times @code{DT_AUDIT}
+will contain a colon separated list of audit interfaces to use. If the linker
+finds an object with an audit entry while searching for shared libraries,
+it will add a corresponding @code{DT_DEPAUDIT} entry in the output file.
+This option is only meaningful on ELF platforms supporting the rtld-audit
+interface.
+
@ifset I960
@cindex architectures
@kindex -A @var{arch}
script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
@xref{Miscellaneous Commands}.
+@kindex --depaudit @var{AUDITLIB}
+@kindex -P @var{AUDITLIB}
+@item --depaudit @var{AUDITLIB}
+@itemx -P @var{AUDITLIB}
+Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
+@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
+specified in the library. If specified multiple times @code{DT_DEPAUDIT}
+will contain a colon separated list of audit interfaces to use. This
+option is only meaningful on ELF platforms supporting the rtld-audit interface.
+The -P option is provided for Solaris compatibility.
+
@cindex entry point, from command line
@kindex -e @var{entry}
@kindex --entry=@var{entry}
Add the archive or object file specified by @var{namespec} to the
list of files to link. This option may be used any number of times.
If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
-will search the library path for a file called @var{filename}, otherise it
+will search the library path for a file called @var{filename}, otherwise it
will search the library path for a file called @file{lib@var{namespec}.a}.
On systems which support shared libraries, @command{ld} may also search for
@item --as-needed
@itemx --no-as-needed
This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
-on the command line after the @option{--as-needed} option. Normally,
+on the command line after the @option{--as-needed} option. Normally
the linker will add a DT_NEEDED tag for each dynamic library mentioned
on the command line, regardless of whether the library is actually
-needed. @option{--as-needed} causes a DT_NEEDED 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 DT_NEEDED lists of other libraries
-linked up to that point, a reference from another dynamic library.
+needed or not. @option{--as-needed} causes a DT_NEEDED tag to only be
+emitted for a library that satisfies an undefined symbol reference
+from a regular object file or, if the library is not found in the
+DT_NEEDED lists of other libraries linked up to that point, an
+undefined symbol reference from another dynamic library.
@option{--no-as-needed} restores the default behaviour.
@kindex --add-needed
@kindex --no-add-needed
@item --add-needed
@itemx --no-add-needed
-This option affects the treatment of dynamic libraries from ELF
-DT_NEEDED tags in dynamic libraries mentioned on the command line after
-the @option{--no-add-needed} option. Normally, the linker will add
-a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
-@option{--no-add-needed} causes DT_NEEDED tags will never be emitted
-for those libraries from DT_NEEDED tags. @option{--add-needed} restores
-the default behaviour.
+These two options have been deprecated because of the similarity of
+their names to the @option{--as-needed} and @option{--no-as-needed}
+options. They have been replaced by @option{--copy-dt-needed-entries}
+and @option{--no-copy-dt-needed-entries}.
@kindex -assert @var{keyword}
@item -assert @var{keyword}
force checking in that case by using the @option{--check-sections}
option.
+@kindex --copy-dt-needed-entries
+@kindex --no-copy-dt-needed-entries
+@item --copy-dt-needed-entries
+@itemx --no-copy-dt-needed-entries
+This option affects the treatment of dynamic libraries referred to
+by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
+command line. Normally the linker will add a DT_NEEDED tag to the
+output binary for each library mentioned in a DT_NEEDED tag in an
+input dynamic library. With @option{--no-copy-dt-needed-entries}
+specified on the command line however any dynamic libraries that
+follow it will have their DT_NEEDED entries ignored. The default
+behaviour can be restored with @option{--copy-dt-needed-entries}.
+
+This option also has an effect on the resolution of symbols in dynamic
+libraries. With the default setting dynamic libraries mentioned on
+the command line will be recursively searched, following their
+DT_NEEDED tags to other libraries, in order to resolve symbols
+required by the output binary. With
+@option{--no-copy-dt-needed-entries} specified however the searching
+of dynamic libraries that follow it will stop with the dynamic
+library itself. No DT_NEEDED links will be traversed to resolve
+symbols.
+
@cindex cross reference table
@kindex --cref
@item --cref
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 ELF platforms which support shared libraries.
-@xref{VERSION}.
+is only fully supported on ELF platforms which support shared libraries;
+see @ref{VERSION}. It is partially supported on PE platforms, which can
+use version scripts to filter symbol visibility in auto-export mode: any
+symbols marked @samp{local} in the version script will not be exported.
+@xref{WIN32}.
@kindex --warn-common
@cindex warnings, on combining symbols
exported. The symbol names may be delimited by commas or colons.
[This option is specific to the i386 PE targeted port of the linker]
+@kindex --exclude-all-symbols
+@item --exclude-all-symbols
+Specifies no symbols should be automatically exported.
+[This option is specific to the i386 PE targeted port of the linker]
+
@kindex --file-alignment
@item --file-alignment
Specify the file alignment. Sections in the file will always begin at
of the linker script. It is not put into the output file. Program
header names are stored in a separate name space, and will not conflict
with symbol names, file names, or section names. Each program header
-must have a distinct name.
+must have a distinct name. The headers are processed in order and it
+is usual for them to map to sections in ascending load address order.
Certain program header types describe segments of memory which the
system loader will load from the file. In the linker script, you
@kindex FILEHDR
@kindex PHDRS
-You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after
+You may use the @code{FILEHDR} and @code{PHDRS} keywords after
the program header type to further describe the contents of the segment.
The @code{FILEHDR} keyword means that the segment should include the ELF
file header. The @code{PHDRS} keyword means that the segment should
-include the ELF program headers themselves.
+include the ELF program headers themselves. If applied to a loadable
+segment (@code{PT_LOAD}), all prior loadable segments must have one of
+these keywords.
The @var{type} may be one of the following. The numbers indicate the
value of the keyword.
target subroutine is a leaf routine (that is, the target subroutine does
not itself call any subroutines).
+@cindex Cortex-A8 erratum workaround
+@kindex --fix-cortex-a8
+@kindex --no-fix-cortex-a8
+The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors. The workaround is enabled by default if you are targeting the ARM v7-A architecture profile. It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
+
+The erratum only affects Thumb-2 code. Please contact ARM for further details.
+
@ifclear GENERIC
@lowersections
@end ifclear
@samp{--relax} enables the generation of trampolines that can access
the entire 32-bit address space. These trampolines are inserted at
section boundaries, so may not themselves be reachable if an input
-section exceeds 33M in size.
+section exceeds 33M in size. You may combine @samp{-r} and
+@samp{--relax} to add trampolines in a partial link. In that case
+both branches to undefined symbols and inter-section branches are also
+considered potentially out of range, and trampolines inserted.
@cindex PowerPC ELF32 options
@table @option
@item --exclude-symbols
@item --exclude-libs
@item --exclude-modules-for-implib
+@item --version-script
@end itemize
-If, however, @samp{--export-all-symbols} is not given explicitly on the
+When auto-export is in operation, @command{ld} will export all the non-local
+(global and common) symbols it finds in a DLL, with the exception of a few
+symbols known to belong to the system's runtime and libraries. As it will
+often not be desirable to export all of a DLL's symbols, which may include
+private functions that are not part of any public interface, the command-line
+options listed above may be used to filter symbols out from the list for
+exporting. The @samp{--output-def} option can be used in order to see the
+final list of exported symbols with all exclusions taken into effect.
+
+If @samp{--export-all-symbols} is not given explicitly on the
command line, then the default auto-export behavior will be @emph{disabled}
if either of the following are true:
_bar = bar
another_foo = abc.dll.afoo
var1 DATA
+doo = foo == foo2
+eoo DATA == var1
@end example
-This example defines a DLL with a non-default base address and five
+This example defines a DLL with a non-default base address and seven
symbols in the export table. The third exported symbol @code{_bar} is an
alias for the second. The fourth symbol, @code{another_foo} is resolved
by "forwarding" to another module and treating it as an alias for
@code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
-@code{var1} is declared to be a data object.
+@code{var1} is declared to be a data object. The @samp{doo} symbol in
+export library is an alias of @samp{foo}, which gets the string name
+in export table @samp{foo2}. The @samp{eoo} symbol is an data export
+symbol, which gets in export table the name @samp{var1}.
The optional @code{LIBRARY <name>} command indicates the @emph{internal}
name of the output DLL. If @samp{<name>} does not include a suffix,
EXPORTS
( ( ( <name1> [ = <name2> ] )
| ( <name1> = <module-name> . <external-name>))
- [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
+ [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
@end example
Declares @samp{<name1>} as an exported symbol from the DLL, or declares
@samp{<name1>} as a "forward" alias for the symbol
@samp{<external-name>} in the DLL @samp{<module-name>}.
Optionally, the symbol may be exported by the specified ordinal
-@samp{<integer>} alias.
+@samp{<integer>} alias. The optional @samp{<name3>} is the to be used
+string in import/export table for the symbol.
The optional keywords that follow the declaration indicate:
As a GNU extension, weak symbols that do not specify an alternate symbol
are supported. If the symbol is undefined when linking, the symbol
uses a default value.
+
+@cindex aligned common symbols
+@item aligned common symbols
+As a GNU extension to the PE file format, it is possible to specify the
+desired alignment for a common symbol. This information is conveyed from
+the assembler or compiler to the linker by means of GNU-specific commands
+carried in the object file's @samp{.drectve} section, which are recognized
+by @command{ld} and respected when laying out the common symbols. Native
+tools will be able to process object files employing this GNU extension,
+but will fail to respect the alignment instructions, and may issue noisy
+warnings about unknown linker directives.
@end table
@ifclear GENERIC
projects / deliverable / binutils-gdb.git / blobdiff