@set POWERPC
@set POWERPC64
@set Renesas
+@set S/390
@set SPU
@set TICOFF
@set WIN32
@ifset POWERPC64
* PowerPC64 ELF64:: ld and PowerPC64 64-bit ELF Support
@end ifset
+@ifset S/390
+* S/390 ELF:: ld and S/390 ELF Support
+@end ifset
@ifset SPU
* SPU ELF:: ld and SPU ELF Support
@end ifset
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}, controlled by the @samp{--sysroot} option, or
-specified when the linker is configured.
+If @var{searchdir} begins with @code{=} or @code{$SYSROOT}, then this
+prefix will be replaced by the @dfn{sysroot prefix}, controlled by the
+@samp{--sysroot} option, or specified when the linker is configured.
@ifset UsesEnvVars
The default set of paths searched (without being specified with
@kindex --pop-state
@cindex pop state governing input file handling
+@item --pop-state
Undoes the effect of --push-state, restores the previous values of the
flags governing input file handling.
@itemx --strip-debug
Omit debugger symbol information (but not all symbols) from the output file.
+@kindex --strip-discarded
+@kindex --no-strip-discarded
+@item --strip-discarded
+@itemx --no-strip-discarded
+Omit (or do not omit) global symbols defined in discarded sections.
+Enabled by default.
+
@kindex -t
@kindex --trace
@cindex input files, displaying
@item place
Orphan sections are placed into a suitable output section following
the strategy described in @ref{Orphan Sections}. The option
-@samp{--unique} also effects how sections are placed.
+@samp{--unique} also affects how sections are placed.
@item discard
All orphan sections are discarded, by placing them in the
the symbols defined by this shared object available for symbol resolution
of subsequently loaded libraries.
+@item globalaudit
+This option is only meaningful when building a dynamic executable.
+This option marks the executable as requiring global auditing by
+setting the @code{DF_1_GLOBAUDIT} bit in the @code{DT_FLAGS_1} dynamic
+tag. Global auditing requires that any auditing library defined via
+the @option{--depaudit} or @option{-P} command line options be run for
+all dynamic objects loaded by the application.
+
@item initfirst
This option is only meaningful when building a shared object.
It marks the object so that its runtime initialization will occur
module aren't visible to the resulting shared library. Supported for
i386 and x86-64.
+@item dynamic-undefined-weak
+Make undefined weak symbols dynamic when building a dynamic object,
+if they are referenced from a regular object file and not forced local
+by symbol visibility or versioning. Not all targets support this
+option.
+
@item nodynamic-undefined-weak
-Don't treat undefined weak symbols as dynamic when building executable.
-This option overrides linker backend default. It can be used to avoid
-dynamic relocations against undefined weak symbols in executable.
-Supported for i386 and x86-64.
+Do not make undefined weak symbols dynamic when building a dynamic
+object. Not all targets support this option. If neither
+@option{-z nodynamic-undefined-weak} nor @option{-z dynamic-undefined-weak}
+are given, a target may default to either option being in force, or
+make some other selection of undefined weak symbols dynamic.
@item noreloc-overflow
Disable relocation overflow check. This can be used to disable
overflow at run-time. Supported for x86_64.
@item call-nop=prefix-addr
-@itemx call-nop=prefix-nop
@itemx call-nop=suffix-nop
@itemx call-nop=prefix-@var{byte}
@itemx call-nop=suffix-@var{byte}
Specify the 1-byte @code{NOP} padding when transforming indirect call
to a locally defined function, foo, via its GOT slot.
@option{call-nop=prefix-addr} generates @code{0x67 call foo}.
-@option{call-nop=prefix-nop} generates @code{0x90 call foo}.
@option{call-nop=suffix-nop} generates @code{call foo 0x90}.
@option{call-nop=prefix-@var{byte}} generates @code{@var{byte} call foo}.
@option{call-nop=suffix-@var{byte}} generates @code{call foo @var{byte}}.
Supported for i386 and x86_64.
+@item ibtplt
+Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
+Supported for Linux/i386 and Linux/x86_64.
+
+@item IBT
+Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
+to indicate compatibility with IBT. This also implies @option{ibtplt}.
+Supported for Linux/i386 and Linux/x86_64.
+
+@item shstk
+Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
+to indicate compatibility with Intel Shadow Stack. Supported for
+Linux/i386 and Linux/x86_64.
+
@end table
Other keywords are ignored for Solaris compatibility.
duplicate when there are many dynamic modules with specialized search
paths for runtime symbol resolution.
+@cindex group allocation in linker script
+@cindex section groups
+@cindex COMDAT
+@kindex --force-group-allocation
+@item --force-group-allocation
+This option causes the linker to place section group members like
+normal input sections, and to delete the section groups. This is the
+default behaviour for a final link but this option can be used to
+change the behaviour of a relocatable link (@samp{-r}). The script
+command @code{FORCE_GROUP_ALLOCATION} has the same
+effect. @xref{Miscellaneous Commands}.
+
@cindex symbols, from command line
@kindex --defsym=@var{symbol}=@var{exp}
@item --defsym=@var{symbol}=@var{expression}
executables that contain dynamic relocations, and usually requires
entry point code that is capable of processing these relocations.
+@kindex --embedded-relocs
+@item --embedded-relocs
+This option is similar to the @option{--emit-relocs} option except
+that the relocs are stored in a target specific section. This option
+is only supported by the @samp{BFIN}, @samp{CR16} and @emph{M68K}
+targets.
+
@kindex --fatal-warnings
@kindex --no-fatal-warnings
@item --fatal-warnings
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
patterns in the linker script.
+@kindex --spare-dynamic-tags
+@item --spare-dynamic-tags=@var{count}
+This option specifies the number of empty slots to leave in the
+.dynamic section of ELF shared objects. Empty slots may be needed by
+post processing tools, such as the prelinker. The default is 5.
+
@kindex --split-by-file
@item --split-by-file[=@var{size}]
Similar to @option{--split-by-reloc} but creates a new output section for
configure-time default. This option is only supported by linkers
that were configured using @option{--with-sysroot}.
+@kindex --task-link
+@item --task-link
+This is used by COFF/PE based targets to create a task-linked object
+file where all of the global symbols have been converted to statics.
+
@kindex --traditional-format
@cindex traditional format
@item --traditional-format
open the file in the current directory. If it is not found, the
linker will search through the archive library search path.
The @dfn{sysroot prefix} can also be forced by specifying @code{=}
-as the first character in the filename path. See also the
-description of @samp{-L} in @ref{Options,,Command Line Options}.
+as the first character in the filename path, or prefixing the filename
+path with @code{$SYSROOT}. See also the description of @samp{-L} in
+@ref{Options,,Command Line Options}.
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
name to @code{lib@var{file}.a}, as with the command line argument
command-line option: to make @code{ld} omit the assignment of addresses
to common symbols even for a non-relocatable output file.
+@item FORCE_GROUP_ALLOCATION
+@kindex FORCE_GROUP_ALLOCATION
+@cindex group allocation in linker script
+@cindex section groups
+@cindex COMDAT
+This command has the same effect as the
+@samp{--force-group-allocation} command-line option: to make
+@command{ld} place section group members like normal input sections,
+and to delete the section groups even if a relocatable output file is
+specified (@samp{-r}).
+
@item INSERT [ AFTER | BEFORE ] @var{output_section}
@kindex INSERT
@cindex insert user script into default script
@end group
@end smallexample
+If an output section's name is the same as the input section's name
+and is representable as a C identifier, then the linker will
+automatically @pxref{PROVIDE} two symbols: __start_SECNAME and
+__stop_SECNAME, where SECNAME is the name of the section. These
+indicate the start address and end address of the output section
+respectively. Note: most section names are not representable as
+C identifiers because they contain a @samp{.} character.
+
@node Output Section Data
@subsection Output Section Data
@cindex data
Orphan sections are sections present in the input files which
are not explicitly placed into the output file by the linker
script. The linker will still copy these sections into the
-output file, but it has to guess as to where they should be
-placed. The linker uses a simple heuristic to do this. It
-attempts to place orphan sections after non-orphan sections of the
-same attribute, such as code vs data, loadable vs non-loadable, etc.
-If there is not enough room to do this then it places
-at the end of the file.
-
-For ELF targets, the attribute of the section includes section type as
-well as section flag.
+output file by either finding, or creating a suitable output section
+in which to place the orphaned input section.
+
+If the name of an orphaned input section exactly matches the name of
+an existing output section, then the orphaned input section will be
+placed at the end of that output section.
+
+If there is no output section with a matching name then new output
+sections will be created. Each new output section will have the same
+name as the orphan section placed within it. If there are multiple
+orphan sections with the same name, these will all be combined into
+one new output section.
+
+If new output sections are created to hold orphaned input sections,
+then the linker must decide where to place these new output sections
+in relation to existing output sections. On most modern targets, the
+linker attempts to place orphan sections after sections of the same
+attribute, such as code vs data, loadable vs non-loadable, etc. If no
+sections with matching attributes are found, or your target lacks this
+support, the orphan section is placed at the end of the file.
The command line options @samp{--orphan-handling} and @samp{--unique}
(@pxref{Options,,Command Line Options}) can be used to control which
output sections an orphan is placed in.
-If an orphaned section's name is representable as a C identifier then
-the linker will automatically @pxref{PROVIDE} two symbols:
-__start_SECNAME and __stop_SECNAME, where SECNAME is the name of the
-section. These indicate the start address and end address of the
-orphaned section respectively. Note: most section names are not
-representable as C identifiers because they contain a @samp{.}
-character.
-
@node Location Counter
@subsection The Location Counter
@kindex .
@ifset POWERPC64
* PowerPC64 ELF64:: @command{ld} and PowerPC64 64-bit ELF Support
@end ifset
+@ifset S/390
+* S/390 ELF:: @command{ld} and S/390 ELF Support
+@end ifset
@ifset SPU
* SPU ELF:: @command{ld} and SPU ELF Support
@end ifset
The last two sections are used by gcc.
@end table
+@table @option
+@cindex MSP430 Options
+@kindex --code-region
+@item --code-region=[either,lower,upper,none]
+This will transform .text* sections to [either,lower,upper].text* sections. The
+argument passed to GCC for -mcode-region is propagated to the linker
+using this option.
+
+@kindex --data-region
+@item --data-region=[either,lower,upper,none]
+This will transform .data*, .bss* and .rodata* sections to
+[either,lower,upper].[data,bss,rodata]* sections. The argument passed to GCC
+for -mdata-region is propagated to the linker using this option.
+
+@kindex --disable-sec-transformation
+@item --disable-sec-transformation
+Prevent the transformation of sections as specified by the @code{--code-region}
+and @code{--data-region} options.
+This is useful if you are compiling and linking using a single call to the GCC
+wrapper, and want to compile the source files using -m[code,data]-region but
+not transform the sections for prebuilt libraries and objects.
+@end table
+
@ifclear GENERIC
@lowersections
@end ifclear
looks for calls to commonly used functions that create threads, and if
seen, adds the necessary barriers. Use these options to change the
default behaviour.
+
+@cindex PowerPC64 ELFv2 PLT localentry optimization
+@kindex --plt-localentry
+@kindex --no-plt-localentry
+@item --plt-localentry
+@itemx --no-localentry
+ELFv2 functions with localentry:0 are those with a single entry point,
+ie. global entry == local entry, and that have no requirement on r2
+(the TOC/GOT pointer) or r12, and guarantee r2 is unchanged on return.
+Such an external function can be called via the PLT without saving r2
+or restoring it on return, avoiding a common load-hit-store for small
+functions. The optimization is attractive, with up to 40% reduction
+in execution time for a small function, but can result in symbol
+interposition failures. Also, minor changes in a shared library,
+including system libraries, can cause a function that was localentry:0
+to become localentry:8. This will result in a dynamic loader
+complaint and failure to run. The option is experimental, use with
+care. @option{--no-plt-localentry} is the default.
+@end table
+
+@ifclear GENERIC
+@lowersections
+@end ifclear
+@end ifset
+
+@ifset S/390
+@ifclear GENERIC
+@raisesections
+@end ifclear
+
+@node S/390 ELF
+@section @command{ld} and S/390 ELF Support
+
+@cindex S/390 ELF options
+@table @option
+
+@cindex S/390
+@kindex --s390-pgste
+@item --s390-pgste
+This option marks the result file with a @code{PT_S390_PGSTE}
+segment. The Linux kernel is supposed to allocate 4k page tables for
+binaries marked that way.
@end table
@ifclear GENERIC
@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
it into the static import library used to resolve imports at link time. The
symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
-API at runtime or by by using the GNU ld extension of linking directly to
+API at runtime or by using the GNU ld extension of linking directly to
the DLL without an import library.
See ld/deffilep.y in the binutils sources for the full specification of
projects / deliverable / binutils-gdb.git / blobdiff