@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}
@cindex dynamic symbol table
@kindex -E
@kindex --export-dynamic
+@kindex --no-export-dynamic
@item -E
@itemx --export-dynamic
-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.
+@itemx --no-export-dynamic
+When creating a dynamically linked executable, using the @option{-E}
+option or the @option{--export-dynamic} 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.
-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
+@option{--no-export-dynamic} 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.
If you use @code{dlopen} to load a dynamic object which needs to refer
back to the symbols defined by the program, rather than some other
be added to the dynamic symbol table if the output format supports it.
See the description of @samp{--dynamic-list}.
+Note that this option is specific to ELF targeted ports. PE targets
+support a similar function to export all symbols from a DLL or EXE; see
+the description of @samp{--export-all-symbols} below.
+
@ifclear SingleFormat
@cindex big-endian objects
@cindex endianness
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
in which they are specified on the command line. Directories specified
on the command line are searched before the default directories. All
@option{-L} options apply to all @option{-l} options, regardless of the
-order in which the options appear.
+order in which the options appear. @option{-L} options do not affect
+how @command{ld} searches for a linker script unless @option{-T}
+option is specified.
If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
by the @dfn{sysroot prefix}, a path specified when the linker is configured.
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
@item --warn-shared-textrel
Warn if the linker adds a DT_TEXTREL to a shared object.
+@kindex --warn-alternate-em
+@item --warn-alternate-em
+Warn if an object has alternate ELF machine code.
+
@kindex --warn-unresolved-symbols
@item --warn-unresolved-symbols
If the linker is going to report an unresolved symbol (see the option
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.
+with non-GNU PE-aware tools, such as file viewers and dumpers. However,
+GDB relies on the use of PE 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, @command{ld} 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 PE targeted ports of the linker]
@kindex --enable-stdcall-fixup
@var{which}.
[This option is specific to the i386 PE targeted port of the linker]
+The following options set flags in the @code{DllCharacteristics} field
+of the PE file header:
+[These options are specific to PE targeted ports of the linker]
+
+@kindex --dynamicbase
+@item --dynamicbase
+The image base address may be relocated using address space layout
+randomization (ASLR). This feature was introduced with MS Windows
+Vista for i386 PE targets.
+
+@kindex --forceinteg
+@item --forceinteg
+Code integrity checks are enforced.
+
+@kindex --nxcompat
+@item --nxcompat
+The image is compatible with the Data Execution Prevention.
+This feature was introduced with MS Windows XP SP2 for i386 PE targets.
+
+@kindex --no-isolation
+@item --no-isolation
+Although the image understands isolation, do not isolate the image.
+
+@kindex --no-seh
+@item --no-seh
+The image does not use SEH. No SE handler may be called from
+this image.
+
+@kindex --no-bind
+@item --no-bind
+Do not bind this image.
+
+@kindex --wdmdriver
+@item --wdmdriver
+The driver uses the MS Windows Driver Model.
+
+@kindex --tsaware
+@item --tsaware
+The image is Terminal Server aware.
+
@end table
@c man end
* Format Commands:: Commands dealing with object file formats
@end ifclear
+* REGION_ALIAS:: Assign alias names to memory regions
* Miscellaneous Commands:: Other linker script commands
@end menu
@end table
@end ifclear
+@node REGION_ALIAS
+@subsection Assign alias names to memory regions
+@kindex REGION_ALIAS(@var{alias}, @var{region})
+@cindex region alias
+@cindex region names
+
+Alias names can be added to existing memory regions created with the
+@ref{MEMORY} command. Each name corresponds to at most one memory region.
+
+@smallexample
+REGION_ALIAS(@var{alias}, @var{region})
+@end smallexample
+
+The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
+memory region @var{region}. This allows a flexible mapping of output sections
+to memory regions. An example follows.
+
+Suppose we have an application for embedded systems which come with various
+memory storage devices. All have a general purpose, volatile memory @code{RAM}
+that allows code execution or data storage. Some may have a read-only,
+non-volatile memory @code{ROM} that allows code execution and read-only data
+access. The last variant is a read-only, non-volatile memory @code{ROM2} with
+read-only data access and no code execution capability. We have four output
+sections:
+
+@itemize @bullet
+@item
+@code{.text} program code;
+@item
+@code{.rodata} read-only data;
+@item
+@code{.data} read-write initialized data;
+@item
+@code{.bss} read-write zero initialized data.
+@end itemize
+
+The goal is to provide a linker command file that contains a system independent
+part defining the output sections and a system dependent part mapping the
+output sections to the memory regions available on the system. Our embedded
+systems come with three different memory setups @code{A}, @code{B} and
+@code{C}:
+@multitable @columnfractions .25 .25 .25 .25
+@item Section @tab Variant A @tab Variant B @tab Variant C
+@item .text @tab RAM @tab ROM @tab ROM
+@item .rodata @tab RAM @tab ROM @tab ROM2
+@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
+@item .bss @tab RAM @tab RAM @tab RAM
+@end multitable
+The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
+loaded into region @code{ROM} or @code{ROM2} respectively. Please note that
+the load address of the @code{.data} section starts in all three variants at
+the end of the @code{.rodata} section.
+
+The base linker script that deals with the output sections follows. It
+includes the system dependent @code{linkcmds.memory} file that describes the
+memory layout:
+@smallexample
+INCLUDE linkcmds.memory
+
+SECTIONS
+ @{
+ .text :
+ @{
+ *(.text)
+ @} > REGION_TEXT
+ .rodata :
+ @{
+ *(.rodata)
+ rodata_end = .;
+ @} > REGION_RODATA
+ .data : AT (rodata_end)
+ @{
+ data_start = .;
+ *(.data)
+ @} > REGION_DATA
+ data_size = SIZEOF(.data);
+ data_load_start = LOADADDR(.data);
+ .bss :
+ @{
+ *(.bss)
+ @} > REGION_BSS
+ @}
+@end smallexample
+
+Now we need three different @code{linkcmds.memory} files to define memory
+regions and alias names. The content of @code{linkcmds.memory} for the three
+variants @code{A}, @code{B} and @code{C}:
+@table @code
+@item A
+Here everything goes into the @code{RAM}.
+@smallexample
+MEMORY
+ @{
+ RAM : ORIGIN = 0, LENGTH = 4M
+ @}
+
+REGION_ALIAS("REGION_TEXT", RAM);
+REGION_ALIAS("REGION_RODATA", RAM);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@item B
+Program code and read-only data go into the @code{ROM}. Read-write data goes
+into the @code{RAM}. An image of the initialized data is loaded into the
+@code{ROM} and will be copied during system start into the @code{RAM}.
+@smallexample
+MEMORY
+ @{
+ ROM : ORIGIN = 0, LENGTH = 3M
+ RAM : ORIGIN = 0x10000000, LENGTH = 1M
+ @}
+
+REGION_ALIAS("REGION_TEXT", ROM);
+REGION_ALIAS("REGION_RODATA", ROM);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@item C
+Program code goes into the @code{ROM}. Read-only data goes into the
+@code{ROM2}. Read-write data goes into the @code{RAM}. An image of the
+initialized data is loaded into the @code{ROM2} and will be copied during
+system start into the @code{RAM}.
+@smallexample
+MEMORY
+ @{
+ ROM : ORIGIN = 0, LENGTH = 2M
+ ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
+ RAM : ORIGIN = 0x20000000, LENGTH = 1M
+ @}
+
+REGION_ALIAS("REGION_TEXT", ROM);
+REGION_ALIAS("REGION_RODATA", ROM2);
+REGION_ALIAS("REGION_DATA", RAM);
+REGION_ALIAS("REGION_BSS", RAM);
+@end smallexample
+@end table
+
+It is possible to write a common system initialization routine to copy the
+@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
+necessary:
+@smallexample
+#include <string.h>
+
+extern char data_start [];
+extern char data_size [];
+extern char data_load_start [];
+
+void copy_data(void)
+@{
+ if (data_start != data_load_start)
+ @{
+ memcpy(data_start, data_load_start, (size_t) data_size);
+ @}
+@}
+@end smallexample
+
@node Miscellaneous Commands
@subsection Other Linker Script Commands
There are a few other linker scripts commands.
@smallexample
@group
@var{section} [@var{address}] [(@var{type})] :
- [AT(@var{lma})] [ALIGN(@var{section_align})] [SUBALIGN(@var{subsection_align})]
+ [AT(@var{lma})]
+ [ALIGN(@var{section_align})]
+ [SUBALIGN(@var{subsection_align})]
+ [@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
aligned upward to the specified value.
Specifying @var{address} for a section will change the value of the
-location counter.
+location counter, provided that the section is non-empty. (Empty
+sections are ignored).
@node Input Section
@subsection Input Section Description
@cindex output section attributes
We showed above that the full description of an output section looked
like this:
+
@smallexample
@group
@var{section} [@var{address}] [(@var{type})] :
- [AT(@var{lma})] [ALIGN(@var{section_align})] [SUBALIGN(@var{subsection_align})]
+ [AT(@var{lma})]
+ [ALIGN(@var{section_align})]
+ [SUBALIGN(@var{subsection_align})]
+ [@var{constraint}]
@{
@var{output-section-command}
@var{output-section-command}
@} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
@end group
@end smallexample
+
We've already described @var{section}, @var{address}, and
@var{output-section-command}. In this section we will describe the
remaining section attributes.
* Output Section LMA:: Output section LMA
* Forced Output Alignment:: Forced Output Alignment
* Forced Input Alignment:: Forced Input Alignment
+* Output Section Constraint:: Output section constraint
* Output Section Region:: Output section region
* Output Section Phdr:: Output section phdr
* Output Section Fill:: Output section fill
SUBALIGN. The value specified overrides any alignment given by input
sections, whether larger or smaller.
+@node Output Section Constraint
+@subsubsection Output Section Constraint
+@kindex ONLY_IF_RO
+@kindex ONLY_IF_RW
+@cindex constraints on output sections
+You can specify that an output section should only be created if all
+of its input sections are read-only or all of its input sections are
+read-write by using the keyword @code{ONLY_IF_RO} and
+@code{ONLY_IF_RW} respectively.
+
@node Output Section Region
@subsubsection Output Section Region
@kindex >@var{region}
region. The region name has no meaning outside of the linker script.
Region names are stored in a separate name space, and will not conflict
with symbol names, file names, or section names. Each memory region
-must have a distinct name.
+must have a distinct name within the @code{MEMORY} command. However you can
+add later alias names to existing memory regions with the @ref{REGION_ALIAS}
+command.
@cindex memory region attributes
The @var{attr} string is an optional list of attributes that specify
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}), it must be the first loadable segment.
The @var{type} may be one of the following. The numbers indicate the
value of the keyword.
@menu
* Constants:: Constants
+* Symbolic Constants:: Symbolic constants
* Symbols:: Symbol Names
* Orphan Sections:: Orphan Sections
* Location Counter:: The Location Counter
Note - the @code{K} and @code{M} suffixes cannot be used in
conjunction with the base suffixes mentioned above.
+@node Symbolic Constants
+@subsection Symbolic Constants
+@cindex symbolic constants
+@kindex CONSTANT
+It is possible to refer to target specific constants via the use of
+the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
+
+@table @code
+@item MAXPAGESIZE
+@kindex MAXPAGESIZE
+The target's maximum page size.
+
+@item COMMONPAGESIZE
+@kindex COMMONPAGESIZE
+The target's default page size.
+@end table
+
+So for example:
+
+@smallexample
+ .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
+@end smallexample
+
+will create a text section aligned to the largest page boundary
+supported by the target.
+
@node Symbols
@subsection Symbol Names
@cindex symbol names
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:
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