X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=ld%2Fld.texi;h=ecdbf775eb3e9669e18b20634c99326beb7d4d0c;hb=1e92785005ce880a5fac9d022f05cdcff91c3091;hp=3b2d05411f45e7d84ae8f11970783e086b4cecdd;hpb=1914e26482b6d60a0a9fd7fb981ca1ce5e75919b;p=deliverable%2Fbinutils-gdb.git diff --git a/ld/ld.texi b/ld/ld.texi index 3b2d05411f..ecdbf775eb 100644 --- a/ld/ld.texi +++ b/ld/ld.texi @@ -1,6 +1,6 @@ \input texinfo @setfilename ld.info -@c Copyright (C) 1991-2019 Free Software Foundation, Inc. +@c Copyright (C) 1991-2020 Free Software Foundation, Inc. @syncodeindex ky cp @c man begin INCLUDE @include configdoc.texi @@ -31,6 +31,7 @@ @set MSP430 @set NDS32 @set NIOSII +@set PDP11 @set POWERPC @set POWERPC64 @set Renesas @@ -56,7 +57,7 @@ This file documents the @sc{gnu} linker LD @end ifset version @value{VERSION}. -Copyright @copyright{} 1991-2019 Free Software Foundation, Inc. +Copyright @copyright{} 1991-2020 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 @@ -93,7 +94,7 @@ section entitled ``GNU Free Documentation License''. @vskip 0pt plus 1filll @c man begin COPYRIGHT -Copyright @copyright{} 1991-2019 Free Software Foundation, Inc. +Copyright @copyright{} 1991-2020 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 @@ -459,6 +460,48 @@ 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. +@kindex --enable-non-contiguous-regions +@item --enable-non-contiguous-regions +This option avoids generating an error if an input section does not +fit a matching output section. The linker tries to allocate the input +section to subseque nt matching output sections, and generates an +error only if no output section is large enough. This is useful when +several non-contiguous memory regions are available and the input +section does not require a particular one. The order in which input +sections are evaluated does not change, for instance: + +@smallexample + MEMORY @{ + MEM1 (rwx) : ORIGIN : 0x1000, LENGTH = 0x14 + MEM2 (rwx) : ORIGIN : 0x1000, LENGTH = 0x40 + MEM3 (rwx) : ORIGIN : 0x2000, LENGTH = 0x40 + @} + SECTIONS @{ + mem1 : @{ *(.data.*); @} > MEM1 + mem2 : @{ *(.data.*); @} > MEM2 + mem3 : @{ *(.data.*); @} > MEM2 + @} + + with input sections: + .data.1: size 8 + .data.2: size 0x10 + .data.3: size 4 + + results in .data.1 affected to mem1, and .data.2 and .data.3 + affected to mem2, even though .data.3 would fit in mem3. +@end smallexample + +This option is incompatible with INSERT statements because it changes +the way input sections are mapped to output sections. + +@kindex --enable-non-contiguous-regions-warnings +@item --enable-non-contiguous-regions-warnings +This option enables warnings when +@code{--enable-non-contiguous-regions} allows possibly unexpected +matches in sections mapping, potentially leading to silently +discarding a section instead of failing because it does not fit any +output region. + @cindex entry point, from command line @kindex -e @var{entry} @kindex --entry=@var{entry} @@ -526,6 +569,24 @@ 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. +@kindex --export-dynamic-symbol=@var{glob} +@cindex export dynamic symbol +@item --export-dynamic-symbol=@var{glob} +When creating a dynamically linked executable, symbols matching +@var{glob} will be added to the dynamic symbol table. When creating a +shared library, references to symbols matching @var{glob} will not be +bound to the definitions within the shared library. This option is a +no-op when creating a shared library and @samp{-Bsymbolic} or +@samp{--dynamic-list} are not specified. This option is only meaningful +on ELF platforms which support shared libraries. + +@kindex --export-dynamic-symbol-list=@var{file} +@cindex export dynamic symbol list +@item --export-dynamic-symbol-list=@var{file} +Specify a @samp{--export-dynamic-symbol} for each pattern in the file. +The format of the file is the same as the version node without +scope and node name. See @ref{VERSION} for more information. + @ifclear SingleFormat @cindex big-endian objects @cindex endianness @@ -1312,12 +1373,25 @@ Specify a stack size for an ELF @code{PT_GNU_STACK} segment. Specifying zero will override any default non-zero sized @code{PT_GNU_STACK} segment creation. +@item start-stop-visibility=@var{value} +@cindex visibility +@cindex ELF symbol visibility +Specify the ELF symbol visibility for synthesized +@code{__start_SECNAME} and @code{__stop_SECNAME} symbols (@pxref{Input +Section Example}). @var{value} must be exactly @samp{default}, +@samp{internal}, @samp{hidden}, or @samp{protected}. If no @samp{-z +start-stop-visibility} option is given, @samp{protected} is used for +compatibility with historical practice. However, it's highly +recommended to use @samp{-z start-stop-visibility=hidden} in new +programs and shared libraries so that these symbols are not exported +between shared objects, which is not usually what's intended. + @item text @itemx notext @itemx textoff -Report an error if DT_TEXTREL is set, i.e., if the binary has dynamic -relocations in read-only sections. Don't report an error if -@samp{notext} or @samp{textoff}. +Report an error if DT_TEXTREL is set, i.e., if the position-independent +or shared object has dynamic relocations in read-only sections. Don't +report an error if @samp{notext} or @samp{textoff}. @item undefs Do not report unresolved symbol references from regular object files, @@ -1717,7 +1791,10 @@ Print a summary of all target-specific options on the standard output and exit. @kindex -Map=@var{mapfile} @item -Map=@var{mapfile} Print a link map to the file @var{mapfile}. See the description of the -@option{-M} option, above. +@option{-M} option, above. Specifying a directory as @var{mapfile} +causes the linker map to be written into a file inside the directory. +The name of the file is based upon the @var{output} filename with +@code{.map} appended. @cindex memory usage @kindex --no-keep-memory @@ -2011,6 +2088,7 @@ runtime linker would do. The linker uses the following search paths to locate required shared libraries: + @enumerate @item Any directories specified by @option{-rpath-link} options. @@ -2040,8 +2118,18 @@ libraries needed by it. The @code{DT_RPATH} entries are ignored if @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} -exists, the list of directories found in that file. +For a linker for a Linux system, if the file @file{/etc/ld.so.conf} +exists, the list of directories found in that file. Note: the path +to this file is prefixed with the @code{sysroot} value, if that is +defined, and then any @code{prefix} string if the linker was +configured with the @command{--prefix=} option. +@item +For a native linker on a FreeBSD system, any directories specified by +the @code{_PATH_ELF_HINTS} macro defined in the @file{elf-hints.h} +header file. +@item +Any directories specifed by a @code{SEARCH_DIR} command in the +linker script being used. @end enumerate If the required shared library is not found, the linker will issue a @@ -2350,9 +2438,10 @@ The address will only be changed if it not explicitly specified; that is, if the @code{SECTIONS} command does not specify a start address for the section (@pxref{SECTIONS}). -@kindex --warn-shared-textrel -@item --warn-shared-textrel -Warn if the linker adds a DT_TEXTREL to a shared object. +@kindex --warn-textrel +@item --warn-textrel +Warn if the linker adds DT_TEXTREL to a position-independent executable +or shared object. @kindex --warn-alternate-em @item --warn-alternate-em @@ -2995,12 +3084,15 @@ of the PE file header: @item --high-entropy-va Image is compatible with 64-bit address space layout randomization (ASLR). +This option also implies @option{--dynamicbase} and +@option{--enable-reloc-section}. @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. +This option also implies @option{--enable-reloc-section}. @kindex --forceinteg @item --forceinteg @@ -3043,6 +3135,11 @@ same sources are linked. The option @option{--no-insert-timestamp} can be used to insert a zero value for the timestamp, this ensuring that binaries produced from identical sources will compare identically. + +@kindex --enable-reloc-section +@item --enable-reloc-section +Create the base relocation table, which is necessary if the image +is loaded at a different image base than specified in the PE header. @end table @c man end @@ -3199,7 +3296,7 @@ an error. @kindex --compact-branches @item --compact-branches @kindex --no-compact-branches -@item --compact-branches +@itemx --no-compact-branches These options control the generation of compact instructions by the linker in the PLT entries for MIPS R6. @@ -3208,6 +3305,73 @@ in the PLT entries for MIPS R6. @c man end @end ifset + +@ifset PDP11 +@subsection Options specific to PDP11 targets + +@c man begin OPTIONS + +For the pdp11-aout target, three variants of the output format can be +produced as selected by the following options. The default variant +for pdp11-aout is the @samp{--omagic} option, whereas for other +targets @samp{--nmagic} is the default. The @samp{--imagic} option is +defined only for the pdp11-aout target, while the others are described +here as they apply to the pdp11-aout target. + +@table @gcctabopt + +@kindex -N +@item -N +@kindex --omagic +@itemx --omagic + +Mark the output as @code{OMAGIC} (0407) in the @file{a.out} header to +indicate that the text segment is not to be write-protected and +shared. Since the text and data sections are both readable and +writable, the data section is allocated immediately contiguous after +the text segment. This is the oldest format for PDP11 executable +programs and is the default for @command{ld} on PDP11 Unix systems +from the beginning through 2.11BSD. + +@kindex -n +@item -n +@kindex --nmagic +@itemx --nmagic + +Mark the output as @code{NMAGIC} (0410) in the @file{a.out} header to +indicate that when the output file is executed, the text portion will +be read-only and shareable among all processes executing the same +file. This involves moving the data areas up to the first possible 8K +byte page boundary following the end of the text. This option creates +a @emph{pure executable} format. + +@kindex -z +@item -z +@kindex --imagic +@itemx --imagic + +Mark the output as @code{IMAGIC} (0411) in the @file{a.out} header to +indicate that when the output file is executed, the program text and +data areas will be loaded into separate address spaces using the split +instruction and data space feature of the memory management unit in +larger models of the PDP11. This doubles the address space available +to the program. The text segment is again pure, write-protected, and +shareable. The only difference in the output format between this +option and the others, besides the magic number, is that both the text +and data sections start at location 0. The @samp{-z} option selected +this format in 2.11BSD. This option creates a @emph{separate +executable} format. + +@kindex --no-omagic +@item --no-omagic + +Equivalent to @samp{--nmagic} for pdp11-aout. + +@end table + +@c man end +@end ifset + @ifset UsesEnvVars @node Environment @section Environment Variables @@ -3528,13 +3692,16 @@ script, and then invoke the linker with nothing but a @samp{-T} option. In case a @dfn{sysroot prefix} is configured, and the filename starts with the @samp{/} character, and the script being processed was located inside the @dfn{sysroot prefix}, the filename will be looked -for in the @dfn{sysroot prefix}. Otherwise, the linker will try to -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, or prefixing the filename -path with @code{$SYSROOT}. See also the description of @samp{-L} in -@ref{Options,,Command-line Options}. +for in the @dfn{sysroot prefix}. The @dfn{sysroot prefix} can also be forced by specifying +@code{=} 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 a @dfn{sysroot prefix} is not used then the linker will try to open +the file in the directory containing the linker script. If it is not +found the linker will then search the current directory. If it is still +not found the linker will search through the archive library search +path. 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 @@ -4994,6 +5161,11 @@ The special output section name @samp{/DISCARD/} may be used to discard input sections. Any input sections which are assigned to an output section named @samp{/DISCARD/} are not included in the output file. +Note, sections that match the @samp{/DISCARD/} output section will be +discarded even if they are in an ELF section group which has other +members which are not being discarded. This is deliberate. +Discarding takes precedence over grouping. + @node Output Section Attributes @subsection Output Section Attributes @cindex output section attributes @@ -7582,18 +7754,27 @@ disable the optimization. @cindex PowerPC64 __tls_get_addr optimization @kindex --tls-get-addr-optimize @kindex --no-tls-get-addr-optimize +@kindex --tls-get-addr-regsave +@kindex --no-tls-get-addr-regsave @item --tls-get-addr-optimize @itemx --no-tls-get-addr-optimize -These options control whether PowerPC64 @command{ld} uses a special +These options control how PowerPC64 @command{ld} uses a special stub to call __tls_get_addr. PowerPC64 glibc 2.22 and later support an optimization that allows the second and subsequent calls to @code{__tls_get_addr} for a given symbol to be resolved by the special -stub without calling in to glibc. By default the linker enables this -option when glibc advertises the availability of __tls_get_addr_opt. -Forcing this option on when using an older glibc won't do much besides -slow down your applications, but may be useful if linking an -application against an older glibc with the expectation that it will -normally be used on systems having a newer glibc. +stub without calling in to glibc. By default the linker enables +generation of the stub when glibc advertises the availability of +__tls_get_addr_opt. +Using @option{--tls-get-addr-optimize} with an older glibc won't do +much besides slow down your applications, but may be useful if linking +an application against an older glibc with the expectation that it +will normally be used on systems having a newer glibc. +@option{--tls-get-addr-regsave} forces generation of a stub that saves +and restores volatile registers around the call into glibc. Normally, +this is done when the linker detects a call to __tls_get_addr_desc. +Such calls then go via the register saving stub to __tls_get_addr_opt. +@option{--no-tls-get-addr-regsave} disables generation of the +register saves. @cindex PowerPC64 OPD optimization @kindex --no-opd-optimize @@ -8384,6 +8565,17 @@ more than performance. With this option, the linker will not insert no-ops or widen density instructions to preserve branch target alignment. There may still be some cases where no-ops are required to preserve the correctness of the code. + +@item --abi-windowed +@itemx --abi-call0 +Choose ABI for the output object and for the generated PLT code. +PLT code inserted by the linker must match ABI of the output object +because windowed and call0 ABI use incompatible function call +conventions. +Default ABI is chosen by the ABI tag in the @code{.xtensa.info} section +of the first input object. +A warning is issued if ABI tags of input objects do not match each other +or the chosen output object ABI. @end table @ifclear GENERIC