@ifset I960
* i960:: ld and the Intel 960 family
@end ifset
+@ifset TICOFF
+* TI COFF:: ld and the TI COFF
+@end ifset
@end ifclear
@ifclear SingleFormat
* BFD:: BFD
the output. This might take significantly longer and therefore probably
should only be enabled for the final binary.
+@kindex -q
+@kindex --emit-relocs
+@cindex retain relocations in final executable
+@item -q
+@itemx --emit-relocs
+Leave relocation sections and contents in fully linked exececutables.
+Post link analysis and optimization tools may need this information in
+order to perform correct modifications of executables. This results
+in larger executables.
+
@cindex partial link
@cindex relocatable output
@kindex -r
be added to. Use @samp{-Ur} only for the last partial link, and
@samp{-r} for the others.
+@kindex --unique
+@item --unique
+Creates a separate output section for every orphan input section. This
+option prevents the normal merging of orphan input sections with the same
+name. An orphan section is one not specifically mentioned in a linker
+script, so this option along with a custom linker script allows any
+selection of input sections to be merged while others are kept separate.
+
@kindex -v
@kindex -V
@kindex --version
@kindex -z @var{keyword}
@item -z @var{keyword}
-This option is ignored for Solaris compatibility.
+The recognized keywords are @code{initfirst}, @code{interpose},
+@code{loadfltr}, @code{nodefaultlib}, @code{nodelete}, @code{nodlopen},
+@code{nodump}, @code{now} and @code{origin}. The other keywords are
+ignored for Solaris compatibility. @code{initfirst} marks the object
+to be initialized first at runtime before any other objects.
+@code{interpose} marks the object that its symbol table interposes
+before all symbols but the primary executable. @code{loadfltr} marks
+the object that its filtees be processed immediately at runtime.
+@code{nodefaultlib} marks the object that the search for dependencies
+of this object will ignore any default library search paths.
+@code{nodelete} marks the object shouldn't be unloaded at runtime.
+@code{nodlopen} marks the object not available to @code{dlopen}.
+@code{nodump} marks the object can not be dumped by @code{dldump}.
+@code{now} marks the object with the non-lazy runtime binding.
+@code{origin} marks the object may contain $ORIGIN.
@kindex -(
@cindex groups of archives
@var{expression}.
@cindex demangling, from command line
-@kindex --demangle
+@kindex --demangle[=@var{style}]
@kindex --no-demangle
-@item --demangle
+@item --demangle[=@var{style}]
@itemx --no-demangle
These options control whether to demangle symbol names in error messages
and other output. When the linker is told to demangle, it tries to
present symbol names in a readable fashion: it strips leading
underscores if they are used by the object file format, and converts C++
-mangled symbol names into user readable names. The linker will demangle
-by default unless the environment variable @samp{COLLECT_NO_DEMANGLE} is
-set. These options may be used to override the default.
+mangled symbol names into user readable names. Different compilers have
+different mangling styles. The optional demangling style argument can be used
+to choose an appropriate demangling style for your compiler. The linker will
+demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
+is set. These options may be used to override the default.
@cindex dynamic linker, from command line
@kindex --dynamic-linker @var{file}
either by specifying a list of names separated by colons, or by
appearing multiple times.
+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.
+
The linker uses the following search paths to locate required shared
libraries.
@enumerate
between @code{-rpath} and @code{-rpath-link} is that directories
specified by @code{-rpath} options are included in the executable and
used at runtime, whereas the @code{-rpath-link} option is only effective
-at link time.
+at link time. It is for the native linker only.
@item
On an ELF system, if the @code{-rpath} and @code{rpath-link} options
were not used, search the contents of the environment variable
-@code{LD_RUN_PATH}.
+@code{LD_RUN_PATH}. It is for the native linker only.
@item
On SunOS, if the @code{-rpath} option was not used, search any
directories specified using @code{-L} options.
For a native linker, the contents of the environment variable
@code{LD_LIBRARY_PATH}.
@item
+For a native ELF linker, the directories in @code{DT_RUNPATH} or
+@code{DT_RPATH} of a shared library are searched for shared
+libraries needed by it. The @code{DT_RPATH} entries are ignored if
+@code{DT_RUNPATH} entries exist.
+@item
The default directories, normally @file{/lib} and @file{/usr/lib}.
@item
For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
alignment constraints.
@kindex --split-by-file
-@item --split-by-file
+@item --split-by-file [@var{size}]
Similar to @code{--split-by-reloc} but creates a new output section for
-each input file.
+each input file when @var{size} is reached. @var{size} defaults to a
+size of 1 if not given.
@kindex --split-by-reloc
-@item --split-by-reloc @var{count}
-Trys to creates extra sections in the output file so that no single
+@item --split-by-reloc [@var{count}]
+Tries to creates extra sections in the output file so that no single
output section in the file contains more than @var{count} relocations.
-This is useful when generating huge relocatable for downloading into
+This is useful when generating huge relocatable files for downloading into
certain real time kernels with the COFF object file format; since COFF
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 @var{count} relocations one output section will contain that
-many relocations.
+many relocations. @var{count} defaults to a value of 32768.
@kindex --stats
@item --stats
trouble). The @samp{--traditional-format} switch tells @code{ld} to not
combine duplicate entries.
+@kindex --section-start @var{sectionname}=@var{org}
+@item --section-start @var{sectionname}=@var{org}
+Locate a section in the output file at the absolute
+address given by @var{org}. You may use this option as many
+times as necessary to locate multiple sections in the command
+line.
+@var{org} must be a single hexadecimal integer;
+for compatibility with other linkers, you may omit the leading
+@samp{0x} usually associated with hexadecimal values. @emph{Note:} there
+should be no white space between @var{sectionname}, the equals
+sign (``@key{=}''), and @var{org}.
+
@kindex -Tbss @var{org}
@kindex -Tdata @var{org}
@kindex -Ttext @var{org}
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
call before the linker has a chance to wrap it to @code{malloc}.
+@kindex --enable-new-dtags
+@kindex --disable-new-dtags
+@item --enable-new-dtags
+@itemx --disable-new-dtags
+This linker can create the new dynamic tags in ELF. But the older ELF
+systems may not understand them. If you specify
+@code{--enable-new-dtags}, the dynamic tags will be created as needed.
+If you specify @code{--disable-new-dtags}, no new dynamic tags will be
+created. By default, the new dynamic tags are not created. Note that
+those options are only available for ELF systems.
+
@end table
@subsection Options specific to i386 PE targets
followed by a series of symbol assignments and output section
descriptions enclosed in curly braces.
-The first line in the above example sets the special symbol @samp{.},
-which is the location counter. If you do not specify the address of an
-output section in some other way (other ways are described later), the
-address is set from the current value of the location counter. The
-location counter is then incremented by the size of the output section.
-
The first line inside the @samp{SECTIONS} command of the above example
sets the value of the special symbol @samp{.}, which is the location
counter. If you do not specify the address of an output section in some
@var{output-section-command}
@var{output-section-command}
@dots{}
- @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+ @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
@end group
@end smallexample
match all files except the ones specified in the EXCLUDE_FILE list. For
example:
@smallexample
-(*(EXCLUDE_FILE (*crtend.o, *otherfile.o) .ctors))
+(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
@end smallexample
-will cause all .ctors sections from all files except crtend.o and otherfile.o
-to be included.
+will cause all .ctors sections from all files except @file{crtend.o} and
+@file{otherfile.o} to be included.
There are two ways to include more than one section:
@smallexample
true of, for example, S-records, the value will be stored in the
endianness of the first input object file.
+Note - these commands only work inside a section description and not
+between them, so the following will produce an error from the linker:
+@smallexample
+SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
+@end smallexample
+whereas this will work:
+@smallexample
+SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
+@end smallexample
+
@kindex FILL(@var{expression})
@cindex holes, filling
@cindex unspecified memory
@var{output-section-command}
@var{output-section-command}
@dots{}
- @} [>@var{region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
+ @} [>@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
@node Output Section LMA
@subsubsection Output section LMA
+@kindex AT>@var{lma_region}
@kindex AT(@var{lma})
@cindex load address
@cindex section load address
The linker will normally set the LMA equal to the VMA. You can change
that by using the @code{AT} keyword. The expression @var{lma} that
-follows the @code{AT} keyword specifies the load address of the section.
+follows the @code{AT} keyword specifies the load address of the
+section. Alternatively, with @samp{AT>@var{lma_region}} expression,
+you may specify a memory region for the section's load address. @xref{MEMORY}.
@cindex ROM initialized data
@cindex initialized data in ROM
* H8/300:: @code{ld} and the H8/300
* i960:: @code{ld} and the Intel 960 family
* ARM:: @code{ld} and the ARM family
+* HPPA ELF32:: @code{ld} and HPPA 32-bit ELF
+@ifset TICOFF
+* TI COFF:: @code{ld} and TI COFF
+@end ifset
@end menu
@end ifset
branched to using a BX instruction, and the program will start
executing in Thumb mode straight away.
+@node HPPA ELF32
+@section @code{ld} and HPPA 32-bit ELF support
+@cindex HPPA multiple sub-space stubs
+@kindex --multi-subspace
+When generating a shared library, @code{ld} will by default generate
+import stubs suitable for use with a single sub-space application.
+The @samp{--multi-subspace} switch causes @code{ld} to generate export
+stubs, and different (larger) import stubs suitable for use with
+multiple sub-spaces.
+
+@cindex HPPA stub grouping
+@kindex --stub-group-size=@var{N}
+Long branch stubs and import/export stubs are placed by @code{ld} in
+stub sections located between groups of input sections.
+@samp{--stub-group-size} specifies the maximum size of a group of input
+sections handled by one stub section. Since branch offsets are signed,
+a stub section may serve two groups of input sections, one group before
+the stub section, and one group after it. However, when using
+conditional branches that require stubs, it may be better (for branch
+prediction) that stub sections only serve one group of input sections.
+A negative value for @samp{N} chooses this scheme, ensuring that
+branches to stubs always use a negative offset. Two special values of
+@samp{N} are recognized, @samp{1} and @samp{-1}. These both instruct
+@code{ld} to automatically size input section groups for the branch types
+detected, with the same behaviour regarding stub placement as other
+positive or negative values of @samp{N} respectively.
+
+Note that @samp{--stub-group-size} does not split input sections. A
+single input section larger than the group size specified will of course
+create a larger group (of one section). If input sections are too
+large, it may not be possible for a branch to reach its stub.
+
+@ifset TICOFF
+@node TI COFF
+@section @code{ld}'s support for various TI COFF versions
+@cindex TI COFF versions
+@kindex --format=@var{version}
+The @samp{--format} switch allows selection of one of the various
+TI COFF versions. The latest of this writing is 2; versions 0 and 1 are
+also supported. The TI COFF versions also vary in header byte-order
+format; @code{ld} will read any version or byte order, but the output
+header format depends on the default specified by the specific target.
+@end ifset
+
@ifclear GENERIC
@lowersections
@end ifclear
projects / deliverable / binutils-gdb.git / blobdiff