diff options
Diffstat (limited to 'ld/ld.texi')
| -rw-r--r-- | ld/ld.texi | 114 |
1 files changed, 105 insertions, 9 deletions
@@ -531,7 +531,9 @@ named @var{entry}, the linker will try to parse @var{entry} as a number, and use that as the entry address (the number will be interpreted in base 10; you may use a leading @samp{0x} for base 16, or a leading @samp{0} for base 8). @xref{Entry Point}, for a discussion of defaults -and other ways of specifying the entry point. +and other ways of specifying the entry point. For i386 PE, @var{entry} +can be also the original function name (without the leading underscore +and/or the trailing stdcall @samp{@@number} when applicable). @kindex --exclude-libs @item --exclude-libs @var{lib},@var{lib},... @@ -1022,7 +1024,7 @@ Write a @dfn{dependency file} to @var{depfile}. This file contains a rule suitable for @code{make} describing the output file and all the input files that were read to produce it. The output is similar to the compiler's output with @samp{-M -MP} (@pxref{Preprocessor Options,, Options -Controlling the Preprocessor, gcc.info, Using the GNU Compiler +Controlling the Preprocessor, gcc, Using the GNU Compiler Collection}). Note that there is no option like the compiler's @samp{-MM}, to exclude ``system files'' (which is not a well-specified concept in the linker, unlike ``system headers'' in the compiler). So the output from @@ -2184,6 +2186,9 @@ Memory region Used Size Region Size %age Used RAM: 32 B 2 GB 0.00% @end smallexample +Note: if you want to find out about the memory usage of the linker +itself, then the @option{--stats} option will do this. + @cindex help @cindex usage @kindex --help @@ -2706,10 +2711,76 @@ more than @var{count} relocations one output section will contain that many relocations. @var{count} defaults to a value of 32768. @kindex --stats -@item --stats +@item --stats[=@var{filename}] Compute and display statistics about the operation of the linker, such as execution time and memory usage. +If the optional @var{filename} argument is not supplied then only +basic information is reported, and it is sent to the standard error +output stream. If the @var{filename} argument is supplied then +extended information is written to the named file. If @var{filename} +is set to just the @var{-} symbol, then the extended information is +sent to the standard output stream. If the @var{filename} starts with +@var{+} then the file is opened in append mode rather than overwrite +mode. + +If the @option{-Map} option has been enabled then the information is +also recorded in the map file as well. Note: if both the +@option{--stats} option and the @option{-Map} options have been given +@var{filename} arguments and they match, then the information will +only be written out once not twice. + +If the @code{LD_STATS} environment variable is defined then this +behaves likes the @option{--stats} option. If the variable's value is +a string then this will used as the name of a file into which the +information should be recorded. Otherwise the information +will be sent to the standard output stream. Using the environment +variable allows stats to be recorded without having to alter the +linker's command line. Note: if both the environment variable and the +@option{--stats} option are used then the @option{--stats} option +takes precedence. + +The extended information reported includes the cpu time used and, if +the @var{getrusage()} system library call is available then memory use +is recorded as well. This information is reported for individual +parts of the linking process which are referred to as @emph{phases}. +In addition the information is also reported for a special phase +called @emph{ALL} which covers the entire linking process. Note that +individual phases can contain or overlap with each other so it should +not be assumed that the overall resources used by the linker is the +sum of the resources used by the individual phases. + +In addition when extended information is being reported the linker +version, command line arguments and linker start time are also +included. This makes it easier to handle the situation where multiple +links are being invoked by a build system and to indentify exactly +which arguments were responsible for producing the statistics that are +reported. + +The extended output looks something like this: + +@smallexample +Stats: linker version: (GNU Binutils) 2.44.50.20250401 +Stats: linker started: Wed Apr 2 09:36:41 2025 +Stats: args: ld -z norelro -z nomemory-seal -z no-separate-code -o a.out [...] + +Stats: phase cpu time memory user time system time +Stats: name (microsec) (KiB) (seconds) (seconds) +Stats: ALL 390082 217740 0 0 +Stats: ctf processing 12 0 0 0 +Stats: string merge 1324 0 0 0 +Stats: parsing 349 288 0 0 +Stats: plugins 1 0 0 0 +Stats: processing files 259616 214524 0 0 +Stats: write 116493 0 0 0 +@end smallexample + +@kindex --no-stats +@item --no-stats +Disables the reporting of usage statistics, should it have been +enabled via the @option{--stats} command line option or the +@var{LD_STATS} environment variable. + @kindex --sysroot=@var{directory} @item --sysroot=@var{directory} Use @var{directory} as the location of the sysroot, overriding the @@ -3712,7 +3783,8 @@ of the PE file header: @item --high-entropy-va @itemx --disable-high-entropy-va Image is compatible with 64-bit address space layout randomization -(ASLR). This option is enabled by default for 64-bit PE images. +(ASLR). This option is enabled by default for 64-bit PE images in +MinGW targets. This option also implies @option{--dynamicbase} and @option{--enable-reloc-section}. @@ -3722,9 +3794,9 @@ This option also implies @option{--dynamicbase} and @itemx --disable-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 is enabled by default but -can be disabled via the @option{--disable-dynamicbase} option. -This option also implies @option{--enable-reloc-section}. +Vista for i386 PE targets. This option is enabled by default for MinGW +targets but can be disabled via the @option{--disable-dynamicbase} +option. This option also implies @option{--enable-reloc-section}. @kindex --forceinteg @item --forceinteg @@ -3737,7 +3809,7 @@ default. @item --disable-nxcompat The image is compatible with the Data Execution Prevention. This feature was introduced with MS Windows XP SP2 for i386 PE -targets. The option is enabled by default. +targets. The option is enabled by default for MinGW targets. @kindex --no-isolation @item --no-isolation @@ -4078,6 +4150,15 @@ If the PE/COFF specific @option{--insert-timestamp} is active and the timestamp value in this variable will be inserted into the COFF header instead of the current time. +@kindex LD_STATS +@cindex LD_STATS +If the @code{LD_STATS} environment variable is defined then linker +resource use information will be recorded, just as if the +@option{--stats} option had been used. If the @code{LD_STATS} +variable has a string value then this will used as the name of a file +into which the information should be stored. Otherwise the information +will be sent to the standard output stream. + @c man end @end ifset @@ -8293,6 +8374,21 @@ GCS markings. If issues are found, a maximum of 20 messages will be emitted, and then a summary with the total number of issues will be displayed at the end. +@kindex -z memtag-mode=@var{mode} +@cindex MTE modes of operation +The @samp{-z memtag-mode=mode} specifies the MTE mode of operation. +The value of @samp{mode} can be one of @samp{none}, @samp{sync} or +@samp{async}. The specified modes determine the value of the +@samp{DT_AARCH64_MEMTAG_MODE} dynamic tag. The @samp{sync} mode +implies precise exceptions, with the runtime providing the exact +instruction where the fault occurred, and the exact faulting address. +The @samp{async} mode implies imprecise exceptions. + +@kindex -z memtag-stack +@cindex Mark program stack for MTE protection +The @samp{-z memtag-stack} specifies that output object uses MTE +instructions for stack memory usage. + @ifclear GENERIC @lowersections @end ifclear @@ -9605,7 +9701,7 @@ format can be supported simply by creating a new BFD back end and adding it to the library. To conserve runtime memory, however, the linker and associated tools are usually configured to support only a subset of the object file formats available. You can use @code{objdump -i} -(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to +(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}) to list all the formats available for your configuration. @cindex BFD requirements |