diff options
Diffstat (limited to 'share/doc/ld.html')
| -rw-r--r-- | share/doc/ld.html | 11908 |
1 files changed, 11908 insertions, 0 deletions
diff --git a/share/doc/ld.html b/share/doc/ld.html new file mode 100644 index 0000000..92f6b62 --- /dev/null +++ b/share/doc/ld.html @@ -0,0 +1,11908 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the GNU linker LD +(Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) +version 2.41.0. + +Copyright (C) 1991-2023 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 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled "GNU Free Documentation License". --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>LD</title> + +<meta name="description" content="LD"> +<meta name="keywords" content="LD"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="#Top" rel="start" title="Top"> +<link href="#LD-Index" rel="index" title="LD Index"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="dir.html#Top" rel="up" title="(dir)"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + + + + + + + + + +<a name="SEC_Contents"></a> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a name="toc-Overview-1" href="#Overview">1 Overview</a></li> + <li><a name="toc-Invocation-1" href="#Invocation">2 Invocation</a> + <ul class="no-bullet"> + <li><a name="toc-Command_002dline-Options" href="#Options">2.1 Command-line Options</a> + <ul class="no-bullet"> + <li><a name="toc-Options-Specific-to-i386-PE-Targets" href="#Options-Specific-to-i386-PE-Targets">2.1.1 Options Specific to i386 PE Targets</a></li> + <li><a name="toc-Options-specific-to-C6X-uClinux-targets" href="#Options-specific-to-C6X-uClinux-targets">2.1.2 Options specific to C6X uClinux targets</a></li> + <li><a name="toc-Options-specific-to-C_002dSKY-targets" href="#Options-specific-to-C_002dSKY-targets">2.1.3 Options specific to C-SKY targets</a></li> + <li><a name="toc-Options-specific-to-Motorola-68HC11-and-68HC12-targets" href="#Options-specific-to-Motorola-68HC11-and-68HC12-targets">2.1.4 Options specific to Motorola 68HC11 and 68HC12 targets</a></li> + <li><a name="toc-Options-specific-to-Motorola-68K-target" href="#Options-specific-to-Motorola-68K-target">2.1.5 Options specific to Motorola 68K target</a></li> + <li><a name="toc-Options-specific-to-MIPS-targets" href="#Options-specific-to-MIPS-targets">2.1.6 Options specific to MIPS targets</a></li> + <li><a name="toc-Options-specific-to-PDP11-targets" href="#Options-specific-to-PDP11-targets">2.1.7 Options specific to PDP11 targets</a></li> + </ul></li> + <li><a name="toc-Environment-Variables" href="#Environment">2.2 Environment Variables</a></li> + </ul></li> + <li><a name="toc-Linker-Scripts" href="#Scripts">3 Linker Scripts</a> + <ul class="no-bullet"> + <li><a name="toc-Basic-Linker-Script-Concepts" href="#Basic-Script-Concepts">3.1 Basic Linker Script Concepts</a></li> + <li><a name="toc-Linker-Script-Format" href="#Script-Format">3.2 Linker Script Format</a></li> + <li><a name="toc-Simple-Linker-Script-Example" href="#Simple-Example">3.3 Simple Linker Script Example</a></li> + <li><a name="toc-Simple-Linker-Script-Commands" href="#Simple-Commands">3.4 Simple Linker Script Commands</a> + <ul class="no-bullet"> + <li><a name="toc-Setting-the-Entry-Point" href="#Entry-Point">3.4.1 Setting the Entry Point</a></li> + <li><a name="toc-Commands-Dealing-with-Files" href="#File-Commands">3.4.2 Commands Dealing with Files</a></li> + <li><a name="toc-Commands-Dealing-with-Object-File-Formats" href="#Format-Commands">3.4.3 Commands Dealing with Object File Formats</a></li> + <li><a name="toc-Assign-alias-names-to-memory-regions" href="#REGION_005fALIAS">3.4.4 Assign alias names to memory regions</a></li> + <li><a name="toc-Other-Linker-Script-Commands" href="#Miscellaneous-Commands">3.4.5 Other Linker Script Commands</a></li> + </ul></li> + <li><a name="toc-Assigning-Values-to-Symbols" href="#Assignments">3.5 Assigning Values to Symbols</a> + <ul class="no-bullet"> + <li><a name="toc-Simple-Assignments-1" href="#Simple-Assignments">3.5.1 Simple Assignments</a></li> + <li><a name="toc-HIDDEN-1" href="#HIDDEN">3.5.2 HIDDEN</a></li> + <li><a name="toc-PROVIDE-1" href="#PROVIDE">3.5.3 PROVIDE</a></li> + <li><a name="toc-PROVIDE_005fHIDDEN-1" href="#PROVIDE_005fHIDDEN">3.5.4 PROVIDE_HIDDEN</a></li> + <li><a name="toc-Source-Code-Reference-1" href="#Source-Code-Reference">3.5.5 Source Code Reference</a></li> + </ul></li> + <li><a name="toc-SECTIONS-Command" href="#SECTIONS">3.6 SECTIONS Command</a> + <ul class="no-bullet"> + <li><a name="toc-Output-Section-Description-1" href="#Output-Section-Description">3.6.1 Output Section Description</a></li> + <li><a name="toc-Output-Section-Name-1" href="#Output-Section-Name">3.6.2 Output Section Name</a></li> + <li><a name="toc-Output-Section-Address-1" href="#Output-Section-Address">3.6.3 Output Section Address</a></li> + <li><a name="toc-Input-Section-Description" href="#Input-Section">3.6.4 Input Section Description</a> + <ul class="no-bullet"> + <li><a name="toc-Input-Section-Basics-1" href="#Input-Section-Basics">3.6.4.1 Input Section Basics</a></li> + <li><a name="toc-Input-Section-Wildcard-Patterns" href="#Input-Section-Wildcards">3.6.4.2 Input Section Wildcard Patterns</a></li> + <li><a name="toc-Input-Section-for-Common-Symbols" href="#Input-Section-Common">3.6.4.3 Input Section for Common Symbols</a></li> + <li><a name="toc-Input-Section-and-Garbage-Collection" href="#Input-Section-Keep">3.6.4.4 Input Section and Garbage Collection</a></li> + <li><a name="toc-Input-Section-Example-1" href="#Input-Section-Example">3.6.4.5 Input Section Example</a></li> + </ul></li> + <li><a name="toc-Output-Section-Data-1" href="#Output-Section-Data">3.6.5 Output Section Data</a></li> + <li><a name="toc-Output-Section-Keywords-1" href="#Output-Section-Keywords">3.6.6 Output Section Keywords</a></li> + <li><a name="toc-Output-Section-Discarding-1" href="#Output-Section-Discarding">3.6.7 Output Section Discarding</a></li> + <li><a name="toc-Output-Section-Attributes-1" href="#Output-Section-Attributes">3.6.8 Output Section Attributes</a> + <ul class="no-bullet"> + <li><a name="toc-Output-Section-Type-1" href="#Output-Section-Type">3.6.8.1 Output Section Type</a></li> + <li><a name="toc-Output-Section-LMA-1" href="#Output-Section-LMA">3.6.8.2 Output Section LMA</a></li> + <li><a name="toc-Forced-Output-Alignment-1" href="#Forced-Output-Alignment">3.6.8.3 Forced Output Alignment</a></li> + <li><a name="toc-Forced-Input-Alignment-1" href="#Forced-Input-Alignment">3.6.8.4 Forced Input Alignment</a></li> + <li><a name="toc-Output-Section-Constraint-1" href="#Output-Section-Constraint">3.6.8.5 Output Section Constraint</a></li> + <li><a name="toc-Output-Section-Region-1" href="#Output-Section-Region">3.6.8.6 Output Section Region</a></li> + <li><a name="toc-Output-Section-Phdr-1" href="#Output-Section-Phdr">3.6.8.7 Output Section Phdr</a></li> + <li><a name="toc-Output-Section-Fill-1" href="#Output-Section-Fill">3.6.8.8 Output Section Fill</a></li> + </ul></li> + <li><a name="toc-Overlay-Description-1" href="#Overlay-Description">3.6.9 Overlay Description</a></li> + </ul></li> + <li><a name="toc-MEMORY-Command" href="#MEMORY">3.7 MEMORY Command</a></li> + <li><a name="toc-PHDRS-Command" href="#PHDRS">3.8 PHDRS Command</a></li> + <li><a name="toc-VERSION-Command" href="#VERSION">3.9 VERSION Command</a></li> + <li><a name="toc-Expressions-in-Linker-Scripts" href="#Expressions">3.10 Expressions in Linker Scripts</a> + <ul class="no-bullet"> + <li><a name="toc-Constants-1" href="#Constants">3.10.1 Constants</a></li> + <li><a name="toc-Symbolic-Constants-1" href="#Symbolic-Constants">3.10.2 Symbolic Constants</a></li> + <li><a name="toc-Symbol-Names" href="#Symbols">3.10.3 Symbol Names</a></li> + <li><a name="toc-Orphan-Sections-1" href="#Orphan-Sections">3.10.4 Orphan Sections</a></li> + <li><a name="toc-The-Location-Counter" href="#Location-Counter">3.10.5 The Location Counter</a></li> + <li><a name="toc-Operators-1" href="#Operators">3.10.6 Operators</a></li> + <li><a name="toc-Evaluation-1" href="#Evaluation">3.10.7 Evaluation</a></li> + <li><a name="toc-The-Section-of-an-Expression" href="#Expression-Section">3.10.8 The Section of an Expression</a></li> + <li><a name="toc-Builtin-Functions-1" href="#Builtin-Functions">3.10.9 Builtin Functions</a></li> + </ul></li> + <li><a name="toc-Implicit-Linker-Scripts-1" href="#Implicit-Linker-Scripts">3.11 Implicit Linker Scripts</a></li> + </ul></li> + <li><a name="toc-Linker-Plugins" href="#Plugins">4 Linker Plugins</a> + <ul class="no-bullet"> + <li><a name="toc-Static-Library-Dependencies-Plugin" href="#libdep-Plugin">4.1 Static Library Dependencies Plugin</a></li> + </ul></li> + <li><a name="toc-Machine-Dependent-Features" href="#Machine-Dependent">5 Machine Dependent Features</a> + <ul class="no-bullet"> + <li><a name="toc-ld-and-the-H8_002f300" href="#H8_002f300">5.1 <code>ld</code> and the H8/300</a></li> + <li><a name="toc-ld-and-the-Motorola-68HC11-and-68HC12-families" href="#M68HC11_002f68HC12">5.2 <code>ld</code> and the Motorola 68HC11 and 68HC12 families</a> + <ul class="no-bullet"> + <li><a name="toc-Linker-Relaxation" href="#Linker-Relaxation">5.2.1 Linker Relaxation</a></li> + <li><a name="toc-Trampoline-Generation" href="#Trampoline-Generation">5.2.2 Trampoline Generation</a></li> + </ul></li> + <li><a name="toc-ld-and-the-ARM-family" href="#ARM">5.3 <code>ld</code> and the ARM family</a></li> + <li><a name="toc-ld-and-HPPA-32_002dbit-ELF-Support" href="#HPPA-ELF32">5.4 <code>ld</code> and HPPA 32-bit ELF Support</a></li> + <li><a name="toc-ld-and-the-Motorola-68K-family" href="#M68K">5.5 <code>ld</code> and the Motorola 68K family</a></li> + <li><a name="toc-ld-and-the-MIPS-family" href="#MIPS">5.6 <code>ld</code> and the MIPS family</a></li> + <li><a name="toc-ld-and-MMIX" href="#MMIX">5.7 <code>ld</code> and MMIX</a></li> + <li><a name="toc-ld-and-MSP430" href="#MSP430">5.8 <code>ld</code> and MSP430</a></li> + <li><a name="toc-ld-and-NDS32" href="#NDS32">5.9 <code>ld</code> and NDS32</a></li> + <li><a name="toc-ld-and-the-Altera-Nios-II" href="#Nios-II">5.10 <code>ld</code> and the Altera Nios II</a></li> + <li><a name="toc-ld-and-PowerPC-32_002dbit-ELF-Support" href="#PowerPC-ELF32">5.11 <code>ld</code> and PowerPC 32-bit ELF Support</a></li> + <li><a name="toc-ld-and-PowerPC64-64_002dbit-ELF-Support" href="#PowerPC64-ELF64">5.12 <code>ld</code> and PowerPC64 64-bit ELF Support</a></li> + <li><a name="toc-ld-and-S_002f390-ELF-Support" href="#S_002f390-ELF">5.13 <code>ld</code> and S/390 ELF Support</a></li> + <li><a name="toc-ld-and-SPU-ELF-Support" href="#SPU-ELF">5.14 <code>ld</code> and SPU ELF Support</a></li> + <li><a name="toc-ld_0027s-Support-for-Various-TI-COFF-Versions" href="#TI-COFF">5.15 <code>ld</code>’s Support for Various TI COFF Versions</a></li> + <li><a name="toc-ld-and-WIN32-_0028cygwin_002fmingw_0029" href="#WIN32">5.16 <code>ld</code> and WIN32 (cygwin/mingw)</a></li> + <li><a name="toc-ld-and-Xtensa-Processors" href="#Xtensa">5.17 <code>ld</code> and Xtensa Processors</a></li> + </ul></li> + <li><a name="toc-BFD-1" href="#BFD">6 BFD</a> + <ul class="no-bullet"> + <li><a name="toc-How-It-Works_003a-An-Outline-of-BFD" href="#BFD-outline">6.1 How It Works: An Outline of BFD</a> + <ul class="no-bullet"> + <li><a name="toc-Information-Loss" href="#BFD-information-loss">6.1.1 Information Loss</a></li> + <li><a name="toc-The-BFD-canonical-object_002dfile-format" href="#Canonical-format">6.1.2 The BFD canonical object-file format</a></li> + </ul></li> + </ul></li> + <li><a name="toc-Reporting-Bugs-1" href="#Reporting-Bugs">7 Reporting Bugs</a> + <ul class="no-bullet"> + <li><a name="toc-Have-You-Found-a-Bug_003f" href="#Bug-Criteria">7.1 Have You Found a Bug?</a></li> + <li><a name="toc-How-to-Report-Bugs" href="#Bug-Reporting">7.2 How to Report Bugs</a></li> + </ul></li> + <li><a name="toc-MRI-Compatible-Script-Files" href="#MRI">Appendix A MRI Compatible Script Files</a></li> + <li><a name="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix B GNU Free Documentation License</a></li> + <li><a name="toc-LD-Index-1" href="#LD-Index">LD Index</a></li> +</ul> +</div> + + +<a name="Top"></a> +<div class="header"> +<p> +Next: <a href="#Overview" accesskey="n" rel="next">Overview</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="LD"></a> +<h1 class="top">LD</h1> +<p>This file documents the <small>GNU</small> linker ld +(Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) +version 2.41.0. +</p> +<p>This document is distributed under the terms of the GNU Free +Documentation License version 1.3. A copy of the license is included +in the section entitled “GNU Free Documentation License”. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Overview" accesskey="1">Overview</a>:</td><td> </td><td align="left" valign="top">Overview +</td></tr> +<tr><td align="left" valign="top">• <a href="#Invocation" accesskey="2">Invocation</a>:</td><td> </td><td align="left" valign="top">Invocation +</td></tr> +<tr><td align="left" valign="top">• <a href="#Scripts" accesskey="3">Scripts</a>:</td><td> </td><td align="left" valign="top">Linker Scripts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Plugins" accesskey="4">Plugins</a>:</td><td> </td><td align="left" valign="top">Linker Plugins +</td></tr> +<tr><td align="left" valign="top">• <a href="#Machine-Dependent" accesskey="5">Machine Dependent</a>:</td><td> </td><td align="left" valign="top">Machine Dependent Features +</td></tr> +<tr><td align="left" valign="top">• <a href="#BFD" accesskey="6">BFD</a>:</td><td> </td><td align="left" valign="top">BFD +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Reporting-Bugs" accesskey="7">Reporting Bugs</a>:</td><td> </td><td align="left" valign="top">Reporting Bugs +</td></tr> +<tr><td align="left" valign="top">• <a href="#MRI" accesskey="8">MRI</a>:</td><td> </td><td align="left" valign="top">MRI Compatible Script Files +</td></tr> +<tr><td align="left" valign="top">• <a href="#GNU-Free-Documentation-License" accesskey="9">GNU Free Documentation License</a>:</td><td> </td><td align="left" valign="top">GNU Free Documentation License +</td></tr> +<tr><td align="left" valign="top">• <a href="#LD-Index">LD Index</a>:</td><td> </td><td align="left" valign="top">LD Index +</td></tr> +</table> + +<hr> +<a name="Overview"></a> +<div class="header"> +<p> +Next: <a href="#Invocation" accesskey="n" rel="next">Invocation</a>, Previous: <a href="#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Overview-1"></a> +<h2 class="chapter">1 Overview</h2> + +<a name="index-GNU-linker"></a> +<a name="index-what-is-this_003f"></a> + + + +<p><code>ld</code> combines a number of object and archive files, relocates +their data and ties up symbol references. Usually the last step in +compiling a program is to run <code>ld</code>. +</p> +<p><code>ld</code> accepts Linker Command Language files written in +a superset of AT&T’s Link Editor Command Language syntax, +to provide explicit and total control over the linking process. +</p> + +<p>This version of <code>ld</code> uses the general purpose BFD libraries +to operate on object files. This allows <code>ld</code> to read, combine, and +write object files in many different formats—for example, COFF or +<code>a.out</code>. Different formats may be linked together to produce any +available kind of object file. See <a href="#BFD">BFD</a>, for more information. +</p> +<p>Aside from its flexibility, the <small>GNU</small> linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +<code>ld</code> continues executing, allowing you to identify other errors +(or, in some cases, to get an output file in spite of the error). +</p> + +<hr> +<a name="Invocation"></a> +<div class="header"> +<p> +Next: <a href="#Scripts" accesskey="n" rel="next">Scripts</a>, Previous: <a href="#Overview" accesskey="p" rel="previous">Overview</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Invocation-1"></a> +<h2 class="chapter">2 Invocation</h2> + + +<p>The <small>GNU</small> linker <code>ld</code> is meant to cover a broad range of situations, +and to be as compatible as possible with other linkers. As a result, +you have many choices to control its behavior. +</p> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Options" accesskey="1">Options</a>:</td><td> </td><td align="left" valign="top">Command-line Options +</td></tr> +<tr><td align="left" valign="top">• <a href="#Environment" accesskey="2">Environment</a>:</td><td> </td><td align="left" valign="top">Environment Variables +</td></tr> +</table> + +<hr> +<a name="Options"></a> +<div class="header"> +<p> +Next: <a href="#Environment" accesskey="n" rel="next">Environment</a>, Up: <a href="#Invocation" accesskey="u" rel="up">Invocation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Command_002dline-Options"></a> +<h3 class="section">2.1 Command-line Options</h3> + +<a name="index-command-line"></a> +<a name="index-options"></a> + + +<p>The linker supports a plethora of command-line options, but in actual +practice few of them are used in any particular context. +<a name="index-standard-Unix-system"></a> +For instance, a frequent use of <code>ld</code> is to link standard Unix +object files on a standard, supported Unix system. On such a system, to +link a file <code>hello.o</code>: +</p> +<div class="smallexample"> +<pre class="smallexample">ld -o <var>output</var> /lib/crt0.o hello.o -lc +</pre></div> + +<p>This tells <code>ld</code> to produce a file called <var>output</var> as the +result of linking the file <code>/lib/crt0.o</code> with <code>hello.o</code> and +the library <code>libc.a</code>, which will come from the standard search +directories. (See the discussion of the ‘<samp>-l</samp>’ option below.) +</p> +<p>Some of the command-line options to <code>ld</code> may be specified at any +point in the command line. However, options which refer to files, such +as ‘<samp>-l</samp>’ or ‘<samp>-T</samp>’, cause the file to be read at the point at +which the option appears in the command line, relative to the object +files and other file options. Repeating non-file options with a +different argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of that +option. Options which may be meaningfully specified more than once are +noted in the descriptions below. +</p> +<a name="index-object-files"></a> +<p>Non-option arguments are object files or archives which are to be linked +together. They may follow, precede, or be mixed in with command-line +options, except that an object file argument may not be placed between +an option and its argument. +</p> +<p>Usually the linker is invoked with at least one object file, but you can +specify other forms of binary input files using ‘<samp>-l</samp>’, ‘<samp>-R</samp>’, +and the script command language. If <em>no</em> binary input files at all +are specified, the linker does not produce any output, and issues the +message ‘<samp>No input files</samp>’. +</p> +<p>If the linker cannot recognize the format of an object file, it will +assume that it is a linker script. A script specified in this way +augments the main linker script used for the link (either the default +linker script or the one specified by using ‘<samp>-T</samp>’). This feature +permits the linker to link against a file which appears to be an object +or an archive, but actually merely defines some symbol values, or uses +<code>INPUT</code> or <code>GROUP</code> to load other objects. Specifying a +script in this way merely augments the main linker script, with the +extra commands placed after the main script; use the ‘<samp>-T</samp>’ option +to replace the default linker script entirely, but note the effect of +the <code>INSERT</code> command. See <a href="#Scripts">Scripts</a>. +</p> +<p>For options whose names are a single letter, +option arguments must either follow the option letter without intervening +whitespace, or be given as separate arguments immediately following the +option that requires them. +</p> +<p>For options whose names are multiple letters, either one dash or two can +precede the option name; for example, ‘<samp>-trace-symbol</samp>’ and +‘<samp>--trace-symbol</samp>’ are equivalent. Note—there is one exception to +this rule. Multiple letter options that start with a lower case ’o’ can +only be preceded by two dashes. This is to reduce confusion with the +‘<samp>-o</samp>’ option. So for example ‘<samp>-omagic</samp>’ sets the output file +name to ‘<samp>magic</samp>’ whereas ‘<samp>--omagic</samp>’ sets the NMAGIC flag on the +output. +</p> +<p>Arguments to multiple-letter options must either be separated from the +option name by an equals sign, or be given as separate arguments +immediately following the option that requires them. For example, +‘<samp>--trace-symbol foo</samp>’ and ‘<samp>--trace-symbol=foo</samp>’ are equivalent. +Unique abbreviations of the names of multiple-letter options are +accepted. +</p> +<p>Note—if the linker is being invoked indirectly, via a compiler driver +(e.g. ‘<samp>gcc</samp>’) then all the linker command-line options should be +prefixed by ‘<samp>-Wl,</samp>’ (or whatever is appropriate for the particular +compiler driver) like this: +</p> +<div class="smallexample"> +<pre class="smallexample"> gcc -Wl,--start-group foo.o bar.o -Wl,--end-group +</pre></div> + +<p>This is important, because otherwise the compiler driver program may +silently drop the linker options, resulting in a bad link. Confusion +may also arise when passing options that require values through a +driver, as the use of a space between option and argument acts as +a separator, and causes the driver to pass only the option to the linker +and the argument to the compiler. In this case, it is simplest to use +the joined forms of both single- and multiple-letter options, such as: +</p> +<div class="smallexample"> +<pre class="smallexample"> gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map +</pre></div> + +<p>Here is a table of the generic command-line switches accepted by the GNU +linker: +</p> +<dl compact="compact"> +<dt><code>@<var>file</var></code></dt> +<dd><p>Read command-line options from <var>file</var>. The options read are +inserted in place of the original @<var>file</var> option. If <var>file</var> +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +</p> +<p>Options in <var>file</var> are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The <var>file</var> may itself contain additional +@<var>file</var> options; any such options will be processed recursively. +</p> +<a name="index-_002da-keyword"></a> +</dd> +<dt><code>-a <var>keyword</var></code></dt> +<dd><p>This option is supported for HP/UX compatibility. The <var>keyword</var> +argument must be one of the strings ‘<samp>archive</samp>’, ‘<samp>shared</samp>’, or +‘<samp>default</samp>’. ‘<samp>-aarchive</samp>’ is functionally equivalent to +‘<samp>-Bstatic</samp>’, and the other two keywords are functionally equivalent +to ‘<samp>-Bdynamic</samp>’. This option may be used any number of times. +</p> +<a name="index-_002d_002daudit-AUDITLIB"></a> +</dd> +<dt><code>--audit <var>AUDITLIB</var></code></dt> +<dd><p>Adds <var>AUDITLIB</var> to the <code>DT_AUDIT</code> entry of the dynamic section. +<var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME +specified in the library. If specified multiple times <code>DT_AUDIT</code> +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</code> entry in the output file. +This option is only meaningful on ELF platforms supporting the rtld-audit +interface. +</p> +<a name="index-binary-input-format"></a> +<a name="index-_002db-format"></a> +<a name="index-_002d_002dformat_003dformat"></a> +<a name="index-input-format"></a> +<a name="index-input-format-1"></a> +</dd> +<dt><code>-b <var>input-format</var></code></dt> +<dt><code>--format=<var>input-format</var></code></dt> +<dd><p><code>ld</code> may be configured to support more than one kind of object +file. If your <code>ld</code> is configured this way, you can use the +‘<samp>-b</samp>’ option to specify the binary format for input object files +that follow this option on the command line. Even when <code>ld</code> is +configured to support alternative object formats, you don’t usually need +to specify this, as <code>ld</code> should be configured to expect as a +default input format the most usual format on each machine. +<var>input-format</var> is a text string, the name of a particular format +supported by the BFD libraries. (You can list the available binary +formats with ‘<samp>objdump -i</samp>’.) +See <a href="#BFD">BFD</a>. +</p> +<p>You may want to use this option if you are linking files with an unusual +binary format. You can also use ‘<samp>-b</samp>’ to switch formats explicitly (when +linking object files of different formats), by including +‘<samp>-b <var>input-format</var></samp>’ before each group of object files in a +particular format. +</p> +<p>The default format is taken from the environment variable +<code>GNUTARGET</code>. +See <a href="#Environment">Environment</a>. +You can also define the input format from a script, using the command +<code>TARGET</code>; +see <a href="#Format-Commands">Format Commands</a>. +</p> +<a name="index-_002dc-MRI_002dcmdfile"></a> +<a name="index-_002d_002dmri_002dscript_003dMRI_002dcmdfile"></a> +<a name="index-compatibility_002c-MRI"></a> +</dd> +<dt><code>-c <var>MRI-commandfile</var></code></dt> +<dt><code>--mri-script=<var>MRI-commandfile</var></code></dt> +<dd><p>For compatibility with linkers produced by MRI, <code>ld</code> accepts script +files written in an alternate, restricted command language, described in +<a href="#MRI">MRI Compatible Script Files</a>. +Introduce MRI script files with +the option ‘<samp>-c</samp>’; use the ‘<samp>-T</samp>’ option to run linker +scripts written in the general-purpose <code>ld</code> scripting language. +If <var>MRI-cmdfile</var> does not exist, <code>ld</code> looks for it in the directories +specified by any ‘<samp>-L</samp>’ options. +</p> +<a name="index-common-allocation"></a> +<a name="index-_002dd"></a> +<a name="index-_002ddc"></a> +<a name="index-_002ddp"></a> +</dd> +<dt><code>-d</code></dt> +<dt><code>-dc</code></dt> +<dt><code>-dp</code></dt> +<dd><p>These three options are equivalent; multiple forms are supported for +compatibility with other linkers. They assign space to common symbols +even if a relocatable output file is specified (with ‘<samp>-r</samp>’). The +script command <code>FORCE_COMMON_ALLOCATION</code> has the same effect. +See <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>. +</p> +<a name="index-_002d_002ddepaudit-AUDITLIB"></a> +<a name="index-_002dP-AUDITLIB"></a> +</dd> +<dt><code>--depaudit <var>AUDITLIB</var></code></dt> +<dt><code>-P <var>AUDITLIB</var></code></dt> +<dd><p>Adds <var>AUDITLIB</var> to the <code>DT_DEPAUDIT</code> entry of the dynamic section. +<var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME +specified in the library. If specified multiple times <code>DT_DEPAUDIT</code> +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. +</p> +<a name="index-_002d_002denable_002dlinker_002dversion"></a> +</dd> +<dt><code>--enable-linker-version</code></dt> +<dd><p>Enables the <code>LINKER_VERSION</code> linker script directive, described +in <a href="#Output-Section-Data">Output Section Data</a>. If this directive is used in a linker +script and this option has been enabled then a string containing the +linker version will be inserted at the current point. +</p> +<p>Note - this location of this option on the linker command line is +significant. It will only affect linker scripts that come after it on +the command line, or which are built into the linker. +</p> +<a name="index-_002d_002ddisable_002dlinker_002dversion"></a> +</dd> +<dt><code>--disable-linker-version</code></dt> +<dd><p>Disables the <code>LINKER_VERSION</code> linker script directive, so that it +does not insert a version string. This is the default. +</p> +<a name="index-_002d_002denable_002dnon_002dcontiguous_002dregions"></a> +</dd> +<dt><code>--enable-non-contiguous-regions</code></dt> +<dd><p>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: +</p> +<div class="smallexample"> +<pre class="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.*); } > MEM3 + } + + 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. +</pre></div> + +<p>This option is incompatible with INSERT statements because it changes +the way input sections are mapped to output sections. +</p> +<a name="index-_002d_002denable_002dnon_002dcontiguous_002dregions_002dwarnings"></a> +</dd> +<dt><code>--enable-non-contiguous-regions-warnings</code></dt> +<dd><p>This option enables warnings when +<code>--enable-non-contiguous-regions</code> 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. +</p> +<a name="index-entry-point_002c-from-command-line"></a> +<a name="index-_002de-entry"></a> +<a name="index-_002d_002dentry_003dentry"></a> +</dd> +<dt><code>-e <var>entry</var></code></dt> +<dt><code>--entry=<var>entry</var></code></dt> +<dd><p>Use <var>entry</var> as the explicit symbol for beginning execution of your +program, rather than the default entry point. If there is no symbol +named <var>entry</var>, the linker will try to parse <var>entry</var> 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</samp>’ for base 16, or a leading +‘<samp>0</samp>’ for base 8). See <a href="#Entry-Point">Entry Point</a>, for a discussion of defaults +and other ways of specifying the entry point. +</p> +<a name="index-_002d_002dexclude_002dlibs"></a> +</dd> +<dt><code>--exclude-libs <var>lib</var>,<var>lib</var>,...</code></dt> +<dd><p>Specifies a list of archive libraries from which symbols should not be automatically +exported. The library names may be delimited by commas or colons. Specifying +<code>--exclude-libs ALL</code> excludes symbols in all archive libraries from +automatic export. This option is available only for the i386 PE targeted +port of the linker and for ELF targeted ports. For i386 PE, symbols +explicitly listed in a .def file are still exported, regardless of this +option. For ELF targeted ports, symbols affected by this option will +be treated as hidden. +</p> +<a name="index-_002d_002dexclude_002dmodules_002dfor_002dimplib"></a> +</dd> +<dt><code>--exclude-modules-for-implib <var>module</var>,<var>module</var>,...</code></dt> +<dd><p>Specifies a list of object files or archive members, from which symbols +should not be automatically exported, but which should be copied wholesale +into the import library being generated during the link. The module names +may be delimited by commas or colons, and must match exactly the filenames +used by <code>ld</code> to open the files; for archive members, this is simply +the member name, but for object files the name listed must include and +match precisely any path used to specify the input file on the linker’s +command-line. This option is available only for the i386 PE targeted port +of the linker. Symbols explicitly listed in a .def file are still exported, +regardless of this option. +</p> +<a name="index-dynamic-symbol-table"></a> +<a name="index-_002dE"></a> +<a name="index-_002d_002dexport_002ddynamic"></a> +<a name="index-_002d_002dno_002dexport_002ddynamic"></a> +</dd> +<dt><code>-E</code></dt> +<dt><code>--export-dynamic</code></dt> +<dt><code>--no-export-dynamic</code></dt> +<dd><p>When creating a dynamically linked executable, using the <samp>-E</samp> +option or the <samp>--export-dynamic</samp> 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. +</p> +<p>If you do not use either of these options (or use the +<samp>--no-export-dynamic</samp> 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. +</p> +<p>If you use <code>dlopen</code> to load a dynamic object which needs to refer +back to the symbols defined by the program, rather than some other +dynamic object, then you will probably need to use this option when +linking the program itself. +</p> +<p>You can also use the dynamic list to control what symbols should +be added to the dynamic symbol table if the output format supports it. +See the description of ‘<samp>--dynamic-list</samp>’. +</p> +<p>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</samp>’ below. +</p> +<a name="index-_002d_002dexport_002ddynamic_002dsymbol_003dglob"></a> +<a name="index-export-dynamic-symbol"></a> +</dd> +<dt><code>--export-dynamic-symbol=<var>glob</var></code></dt> +<dd><p>When creating a dynamically linked executable, symbols matching +<var>glob</var> will be added to the dynamic symbol table. When creating a +shared library, references to symbols matching <var>glob</var> 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</samp>’ or +‘<samp>--dynamic-list</samp>’ are not specified. This option is only meaningful +on ELF platforms which support shared libraries. +</p> +<a name="index-_002d_002dexport_002ddynamic_002dsymbol_002dlist_003dfile"></a> +<a name="index-export-dynamic-symbol-list"></a> +</dd> +<dt><code>--export-dynamic-symbol-list=<var>file</var></code></dt> +<dd><p>Specify a ‘<samp>--export-dynamic-symbol</samp>’ for each pattern in the file. +The format of the file is the same as the version node without +scope and node name. See <a href="#VERSION">VERSION</a> for more information. +</p> +<a name="index-big_002dendian-objects"></a> +<a name="index-endianness"></a> +<a name="index-_002dEB"></a> +</dd> +<dt><code>-EB</code></dt> +<dd><p>Link big-endian objects. This affects the default output format. +</p> +<a name="index-little_002dendian-objects"></a> +<a name="index-_002dEL"></a> +</dd> +<dt><code>-EL</code></dt> +<dd><p>Link little-endian objects. This affects the default output format. +</p> +<a name="index-_002df-name"></a> +<a name="index-_002d_002dauxiliary_003dname"></a> +</dd> +<dt><code>-f <var>name</var></code></dt> +<dt><code>--auxiliary=<var>name</var></code></dt> +<dd><p>When creating an ELF shared object, set the internal DT_AUXILIARY field +to the specified name. This tells the dynamic linker that the symbol +table of the shared object should be used as an auxiliary filter on the +symbol table of the shared object <var>name</var>. +</p> +<p>If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the DT_AUXILIARY field. If +the dynamic linker resolves any symbols from the filter object, it will +first check whether there is a definition in the shared object +<var>name</var>. If there is one, it will be used instead of the definition +in the filter object. The shared object <var>name</var> need not exist. +Thus the shared object <var>name</var> may be used to provide an alternative +implementation of certain functions, perhaps for debugging or for +machine-specific performance. +</p> +<p>This option may be specified more than once. The DT_AUXILIARY entries +will be created in the order in which they appear on the command line. +</p> +<a name="index-_002dF-name"></a> +<a name="index-_002d_002dfilter_003dname"></a> +</dd> +<dt><code>-F <var>name</var></code></dt> +<dt><code>--filter=<var>name</var></code></dt> +<dd><p>When creating an ELF shared object, set the internal DT_FILTER field to +the specified name. This tells the dynamic linker that the symbol table +of the shared object which is being created should be used as a filter +on the symbol table of the shared object <var>name</var>. +</p> +<p>If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the DT_FILTER field. The +dynamic linker will resolve symbols according to the symbol table of the +filter object as usual, but it will actually link to the definitions +found in the shared object <var>name</var>. Thus the filter object can be +used to select a subset of the symbols provided by the object +<var>name</var>. +</p> +<p>Some older linkers used the <samp>-F</samp> option throughout a compilation +toolchain for specifying object-file format for both input and output +object files. +The <small>GNU</small> linker uses other mechanisms for this purpose: the +<samp>-b</samp>, <samp>--format</samp>, <samp>--oformat</samp> options, the +<code>TARGET</code> command in linker scripts, and the <code>GNUTARGET</code> +environment variable. +The <small>GNU</small> linker will ignore the <samp>-F</samp> option when not +creating an ELF shared object. +</p> +<a name="index-finalization-function"></a> +<a name="index-_002dfini_003dname"></a> +</dd> +<dt><code>-fini=<var>name</var></code></dt> +<dd><p>When creating an ELF executable or shared object, call NAME when the +executable or shared object is unloaded, by setting DT_FINI to the +address of the function. By default, the linker uses <code>_fini</code> as +the function to call. +</p> +<a name="index-_002dg"></a> +</dd> +<dt><code>-g</code></dt> +<dd><p>Ignored. Provided for compatibility with other tools. +</p> +<a name="index-_002dG-value"></a> +<a name="index-_002d_002dgpsize_003dvalue"></a> +<a name="index-object-size"></a> +</dd> +<dt><code>-G <var>value</var></code></dt> +<dt><code>--gpsize=<var>value</var></code></dt> +<dd><p>Set the maximum size of objects to be optimized using the GP register to +<var>size</var>. This is only meaningful for object file formats such as +MIPS ELF that support putting large and small objects into different +sections. This is ignored for other object file formats. +</p> +<a name="index-runtime-library-name"></a> +<a name="index-_002dh-name"></a> +<a name="index-_002dsoname_003dname"></a> +</dd> +<dt><code>-h <var>name</var></code></dt> +<dt><code>-soname=<var>name</var></code></dt> +<dd><p>When creating an ELF shared object, set the internal DT_SONAME field to +the specified name. When an executable is linked with a shared object +which has a DT_SONAME field, then when the executable is run the dynamic +linker will attempt to load the shared object specified by the DT_SONAME +field rather than using the file name given to the linker. +</p> +<a name="index-_002di"></a> +<a name="index-incremental-link"></a> +</dd> +<dt><code>-i</code></dt> +<dd><p>Perform an incremental link (same as option ‘<samp>-r</samp>’). +</p> +<a name="index-initialization-function"></a> +<a name="index-_002dinit_003dname"></a> +</dd> +<dt><code>-init=<var>name</var></code></dt> +<dd><p>When creating an ELF executable or shared object, call NAME when the +executable or shared object is loaded, by setting DT_INIT to the address +of the function. By default, the linker uses <code>_init</code> as the +function to call. +</p> +<a name="index-archive-files_002c-from-cmd-line"></a> +<a name="index-_002dl-namespec"></a> +<a name="index-_002d_002dlibrary_003dnamespec"></a> +</dd> +<dt><code>-l <var>namespec</var></code></dt> +<dt><code>--library=<var>namespec</var></code></dt> +<dd><p>Add the archive or object file specified by <var>namespec</var> to the +list of files to link. This option may be used any number of times. +If <var>namespec</var> is of the form <samp>:<var>filename</var></samp>, <code>ld</code> +will search the library path for a file called <var>filename</var>, otherwise it +will search the library path for a file called <samp>lib<var>namespec</var>.a</samp>. +</p> +<p>On systems which support shared libraries, <code>ld</code> may also search for +files other than <samp>lib<var>namespec</var>.a</samp>. Specifically, on ELF +and SunOS systems, <code>ld</code> will search a directory for a library +called <samp>lib<var>namespec</var>.so</samp> before searching for one called +<samp>lib<var>namespec</var>.a</samp>. (By convention, a <code>.so</code> extension +indicates a shared library.) Note that this behavior does not apply +to <samp>:<var>filename</var></samp>, which always specifies a file called +<var>filename</var>. +</p> +<p>The linker will search an archive only once, at the location where it is +specified on the command line. If the archive defines a symbol which +was undefined in some object which appeared before the archive on the +command line, the linker will include the appropriate file(s) from the +archive. However, an undefined symbol in an object appearing later on +the command line will not cause the linker to search the archive again. +</p> +<p>See the <samp>-(</samp> option for a way to force the linker to search +archives multiple times. +</p> +<p>You may list the same archive multiple times on the command line. +</p> +<p>This type of archive searching is standard for Unix linkers. However, +if you are using <code>ld</code> on AIX, note that it is different from the +behaviour of the AIX linker. +</p> +<a name="index-search-directory_002c-from-cmd-line"></a> +<a name="index-_002dL-dir"></a> +<a name="index-_002d_002dlibrary_002dpath_003ddir"></a> +</dd> +<dt><code>-L <var>searchdir</var></code></dt> +<dt><code>--library-path=<var>searchdir</var></code></dt> +<dd><p>Add path <var>searchdir</var> to the list of paths that <code>ld</code> will search +for archive libraries and <code>ld</code> control scripts. You may use this +option any number of times. The directories are searched in the order +in which they are specified on the command line. Directories specified +on the command line are searched before the default directories. All +<samp>-L</samp> options apply to all <samp>-l</samp> options, regardless of the +order in which the options appear. <samp>-L</samp> options do not affect +how <code>ld</code> searches for a linker script unless <samp>-T</samp> +option is specified. +</p> +<p>If <var>searchdir</var> begins with <code>=</code> or <code>$SYSROOT</code>, then this +prefix will be replaced by the <em>sysroot prefix</em>, controlled by the +‘<samp>--sysroot</samp>’ option, or specified when the linker is configured. +</p> +<p>The default set of paths searched (without being specified with +‘<samp>-L</samp>’) depends on which emulation mode <code>ld</code> is using, and in +some cases also on how it was configured. See <a href="#Environment">Environment</a>. +</p> +<p>The paths can also be specified in a link script with the +<code>SEARCH_DIR</code> command. Directories specified this way are searched +at the point in which the linker script appears in the command line. +</p> +<a name="index-emulation"></a> +<a name="index-_002dm-emulation"></a> +</dd> +<dt><code>-m <var>emulation</var></code></dt> +<dd><p>Emulate the <var>emulation</var> linker. You can list the available +emulations with the ‘<samp>--verbose</samp>’ or ‘<samp>-V</samp>’ options. +</p> +<p>If the ‘<samp>-m</samp>’ option is not used, the emulation is taken from the +<code>LDEMULATION</code> environment variable, if that is defined. +</p> +<p>Otherwise, the default emulation depends upon how the linker was +configured. +</p> +<a name="index-remapping-inputs"></a> +<a name="index-_002d_002dremap_002dinputs_003dpattern_003dfilename"></a> +<a name="index-_002d_002dremap_002dinputs_002dfile_003dfile"></a> +</dd> +<dt><code>--remap-inputs=<samp>pattern</samp>=<samp>filename</samp></code></dt> +<dt><code>--remap-inputs-file=<samp>file</samp></code></dt> +<dd><p>These options allow the names of input files to be changed before the +linker attempts to open them. The option +<samp>--remap-inputs=foo.o=bar.o</samp> will cause any attempt to load a +file called <samp>foo.o</samp> to instead try to load a file called +<samp>bar.o</samp>. Wildcard patterns are permitted in the first filename, +so <samp>--remap-inputs=foo*.o=bar.o</samp> will rename any input file that +matches <samp>foo*.o</samp> to <samp>bar.o</samp>. +</p> +<p>An alternative form of the option +<samp>--remap-inputs-file=filename</samp> allows the remappings to be read +from a file. Each line in the file can contain a single remapping. +Blank lines are ignored. Anything from a hash character (‘<samp>#</samp>’) to +the end of a line is considered to be a comment and is also ignored. +The mapping pattern can be separated from the filename by whitespace +or an equals (‘<samp>=</samp>’) character. +</p> +<p>The options can be specified multiple times. Their contents +accumulate. The remappings will be processed in the order in which +they occur on the command line, and if they come from a file, in the +order in which they occur in the file. If a match is made, no further +checking for that filename will be performed. +</p> +<p>If the replacement filename is <samp>/dev/null</samp> or just <samp>NUL</samp> +then the remapping will actually cause the input file to be ignored. +This can be a convenient way to experiment with removing input files +from a complicated build environment. +</p> +<p>Note that this option is position dependent and only affects filenames +that come after it on the command line. Thus: +</p> +<div class="smallexample"> +<pre class="smallexample"> ld foo.o --remap-inputs=foo.o=bar.o +</pre></div> + +<p>Will have no effect, whereas: +</p> +<div class="smallexample"> +<pre class="smallexample"> ld --remap-inputs=foo.o=bar.o foo.o +</pre></div> + +<p>Will rename the input file <samp>foo.o</samp> to <samp>bar.o</samp>. +</p> +<p>Note - these options also affect files referenced by <em>INPUT</em> +statements in linker scripts. But since linker scripts are processed +after the entire command line is read, the position of the remap +options on the command line is not significant. +</p> +<p>If the <samp>verbose</samp> option is enabled then any mappings that match +will be reported, although again the <samp>verbose</samp> option needs to +be enabled on the command line <em>before</em> the remaped filenames +appear. +</p> +<p>If the <samp>-Map</samp> or <samp>--print-map</samp> options are enabled then +the remapping list will be included in the map output. +</p> +<a name="index-link-map"></a> +<a name="index-_002dM"></a> +<a name="index-_002d_002dprint_002dmap"></a> +</dd> +<dt><code>-M</code></dt> +<dt><code>--print-map</code></dt> +<dd><p>Print a link map to the standard output. A link map provides +information about the link, including the following: +</p> +<ul> +<li> Where object files are mapped into memory. +</li><li> How common symbols are allocated. +</li><li> All archive members included in the link, with a mention of the symbol +which caused the archive member to be brought in. +</li><li> The values assigned to symbols. + +<p>Note - symbols whose values are computed by an expression which +involves a reference to a previous value of the same symbol may not +have correct result displayed in the link map. This is because the +linker discards intermediate results and only retains the final value +of an expression. Under such circumstances the linker will display +the final value enclosed by square brackets. Thus for example a +linker script containing: +</p> +<div class="smallexample"> +<pre class="smallexample"> foo = 1 + foo = foo * 4 + foo = foo + 8 +</pre></div> + +<p>will produce the following output in the link map if the <samp>-M</samp> +option is used: +</p> +<div class="smallexample"> +<pre class="smallexample"> 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) +</pre></div> + +<p>See <a href="#Expressions">Expressions</a> for more information about expressions in linker +scripts. +</p> +</li><li> How GNU properties are merged. + +<p>When the linker merges input .note.gnu.property sections into one output +.note.gnu.property section, some properties are removed or updated. +These actions are reported in the link map. For example: +</p> +<div class="smallexample"> +<pre class="smallexample">Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found) +</pre></div> + +<p>This indicates that property 0xc0000002 is removed from output when +merging properties in <samp>foo.o</samp>, whose property 0xc0000002 value +is 0x1, and <samp>bar.o</samp>, which doesn’t have property 0xc0000002. +</p> +<div class="smallexample"> +<pre class="smallexample">Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1) +</pre></div> + +<p>This indicates that property 0xc0010001 value is updated to 0x1 in output +when merging properties in <samp>foo.o</samp>, whose 0xc0010001 property value +is 0x1, and <samp>bar.o</samp>, whose 0xc0010001 property value is 0x1. +</p></li></ul> + +<a name="index-link-map-discarded"></a> +<a name="index-_002d_002dprint_002dmap_002ddiscarded"></a> +<a name="index-_002d_002dno_002dprint_002dmap_002ddiscarded"></a> +</dd> +<dt><code>--print-map-discarded</code></dt> +<dt><code>--no-print-map-discarded</code></dt> +<dd><p>Print (or do not print) the list of discarded and garbage collected sections +in the link map. Enabled by default. +</p> +<a name="index-_002d_002dprint_002dmap_002dlocals"></a> +<a name="index-_002d_002dno_002dprint_002dmap_002dlocals"></a> +</dd> +<dt><code>--print-map-locals</code></dt> +<dt><code>--no-print-map-locals</code></dt> +<dd><p>Print (or do not print) local symbols in the link map. Local symbols +will have the text ‘<samp>(local)</samp>’ printed before their name, and will +be listed after all of the global symbols in a given section. +Temporary local symbols (typically those that start with ‘<samp>.L</samp>’) +will not be included in the output. Disabled by default. +</p> +<a name="index-_002dn"></a> +<a name="index-read_002donly-text"></a> +<a name="index-NMAGIC"></a> +<a name="index-_002d_002dnmagic"></a> +</dd> +<dt><code>-n</code></dt> +<dt><code>--nmagic</code></dt> +<dd><p>Turn off page alignment of sections, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as <code>NMAGIC</code>. +</p> +<a name="index-_002dN"></a> +<a name="index-_002d_002domagic"></a> +<a name="index-read_002fwrite-from-cmd-line"></a> +<a name="index-OMAGIC"></a> +</dd> +<dt><code>-N</code></dt> +<dt><code>--omagic</code></dt> +<dd><p>Set the text and data sections to be readable and writable. Also, do +not page-align the data segment, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as <code>OMAGIC</code>. Note: Although a writable text section +is allowed for PE-COFF targets, it does not conform to the format +specification published by Microsoft. +</p> +<a name="index-_002d_002dno_002domagic"></a> +<a name="index-OMAGIC-1"></a> +</dd> +<dt><code>--no-omagic</code></dt> +<dd><p>This option negates most of the effects of the <samp>-N</samp> option. It +sets the text section to be read-only, and forces the data segment to +be page-aligned. Note - this option does not enable linking against +shared libraries. Use <samp>-Bdynamic</samp> for this. +</p> +<a name="index-_002do-output"></a> +<a name="index-_002d_002doutput_003doutput"></a> +<a name="index-naming-the-output-file"></a> +</dd> +<dt><code>-o <var>output</var></code></dt> +<dt><code>--output=<var>output</var></code></dt> +<dd><p>Use <var>output</var> as the name for the program produced by <code>ld</code>; if this +option is not specified, the name <samp>a.out</samp> is used by default. The +script command <code>OUTPUT</code> can also specify the output file name. +</p> +<a name="index-_002d_002ddependency_002dfile_003ddepfile"></a> +<a name="index-dependency-file"></a> +</dd> +<dt><code>--dependency-file=<var>depfile</var></code></dt> +<dd><p>Write a <em>dependency file</em> to <var>depfile</var>. This file contains a rule +suitable for <code>make</code> 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</samp>’ (see <a href="http://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html#Preprocessor-Options">Options +Controlling the Preprocessor</a> in <cite>Using the GNU Compiler +Collection</cite>). Note that there is no option like the compiler’s ‘<samp>-MM</samp>’, +to exclude “system files” (which is not a well-specified concept in the +linker, unlike “system headers” in the compiler). So the output from +‘<samp>--dependency-file</samp>’ is always specific to the exact state of the +installation where it was produced, and should not be copied into +distributed makefiles without careful editing. +</p> +<a name="index-_002dO-level"></a> +<a name="index-generating-optimized-output"></a> +</dd> +<dt><code>-O <var>level</var></code></dt> +<dd><p>If <var>level</var> is a numeric values greater than zero <code>ld</code> optimizes +the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. At the moment this +option only affects ELF shared library generation. Future releases of +the linker may make more use of this option. Also currently there is +no difference in the linker’s behaviour for different non-zero values +of this option. Again this may change with future releases. +</p> +<a name="index-_002dplugin-name"></a> +</dd> +<dt><code>-plugin <var>name</var></code></dt> +<dd><p>Involve a plugin in the linking process. The <var>name</var> parameter is +the absolute filename of the plugin. Usually this parameter is +automatically added by the complier, when using link time +optimization, but users can also add their own plugins if they so +wish. +</p> +<p>Note that the location of the compiler originated plugins is different +from the place where the <code>ar</code>, <code>nm</code> and +<code>ranlib</code> programs search for their plugins. In order for +those commands to make use of a compiler based plugin it must first be +copied into the <samp>${libdir}/bfd-plugins</samp> directory. All gcc +based linker plugins are backward compatible, so it is sufficient to +just copy in the newest one. +</p> +<a name="index-_002d_002dpush_002dstate"></a> +<a name="index-push-state-governing-input-file-handling"></a> +</dd> +<dt><code>--push-state</code></dt> +<dd><p>The <samp>--push-state</samp> allows one to preserve the current state of the +flags which govern the input file handling so that they can all be +restored with one corresponding <samp>--pop-state</samp> option. +</p> +<p>The option which are covered are: <samp>-Bdynamic</samp>, <samp>-Bstatic</samp>, +<samp>-dn</samp>, <samp>-dy</samp>, <samp>-call_shared</samp>, <samp>-non_shared</samp>, +<samp>-static</samp>, <samp>-N</samp>, <samp>-n</samp>, <samp>--whole-archive</samp>, +<samp>--no-whole-archive</samp>, <samp>-r</samp>, <samp>-Ur</samp>, +<samp>--copy-dt-needed-entries</samp>, <samp>--no-copy-dt-needed-entries</samp>, +<samp>--as-needed</samp>, <samp>--no-as-needed</samp>, and <samp>-a</samp>. +</p> +<p>One target for this option are specifications for <samp>pkg-config</samp>. When +used with the <samp>--libs</samp> option all possibly needed libraries are +listed and then possibly linked with all the time. It is better to return +something as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state +</pre></div> + +<a name="index-_002d_002dpop_002dstate"></a> +<a name="index-pop-state-governing-input-file-handling"></a> +</dd> +<dt><code>--pop-state</code></dt> +<dd><p>Undoes the effect of –push-state, restores the previous values of the +flags governing input file handling. +</p> +<a name="index-_002dq"></a> +<a name="index-_002d_002demit_002drelocs"></a> +<a name="index-retain-relocations-in-final-executable"></a> +</dd> +<dt><code>-q</code></dt> +<dt><code>--emit-relocs</code></dt> +<dd><p>Leave relocation sections and contents in fully linked executables. +Post link analysis and optimization tools may need this information in +order to perform correct modifications of executables. This results +in larger executables. +</p> +<p>This option is currently only supported on ELF platforms. +</p> +<a name="index-_002d_002dforce_002ddynamic"></a> +<a name="index-forcing-the-creation-of-dynamic-sections"></a> +</dd> +<dt><code>--force-dynamic</code></dt> +<dd><p>Force the output file to have dynamic sections. This option is specific +to VxWorks targets. +</p> +<a name="index-partial-link"></a> +<a name="index-relocatable-output"></a> +<a name="index-_002dr"></a> +<a name="index-_002d_002drelocatable"></a> +</dd> +<dt><code>-r</code></dt> +<dt><code>--relocatable</code></dt> +<dd><p>Generate relocatable output—i.e., generate an output file that can in +turn serve as input to <code>ld</code>. This is often called <em>partial +linking</em>. As a side effect, in environments that support standard Unix +magic numbers, this option also sets the output file’s magic number to +<code>OMAGIC</code>. +If this option is not specified, an absolute file is produced. When +linking C++ programs, this option <em>will not</em> resolve references to +constructors; to do that, use ‘<samp>-Ur</samp>’. +</p> +<p>When an input file does not have the same format as the output file, +partial linking is only supported if that input file does not contain any +relocations. Different output formats can have further restrictions; for +example some <code>a.out</code>-based formats do not support partial linking +with input files in other formats at all. +</p> +<p>This option does the same thing as ‘<samp>-i</samp>’. +</p> +<a name="index-_002dR-file"></a> +<a name="index-_002d_002djust_002dsymbols_003dfile"></a> +<a name="index-symbol_002donly-input"></a> +</dd> +<dt><code>-R <var>filename</var></code></dt> +<dt><code>--just-symbols=<var>filename</var></code></dt> +<dd><p>Read symbol names and their addresses from <var>filename</var>, but do not +relocate it or include it in the output. This allows your output file +to refer symbolically to absolute locations of memory defined in other +programs. You may use this option more than once. +</p> +<p>For compatibility with other ELF linkers, if the <samp>-R</samp> option is +followed by a directory name, rather than a file name, it is treated as +the <samp>-rpath</samp> option. +</p> +<a name="index-_002ds"></a> +<a name="index-_002d_002dstrip_002dall"></a> +<a name="index-strip-all-symbols"></a> +</dd> +<dt><code>-s</code></dt> +<dt><code>--strip-all</code></dt> +<dd><p>Omit all symbol information from the output file. +</p> +<a name="index-_002dS"></a> +<a name="index-_002d_002dstrip_002ddebug"></a> +<a name="index-strip-debugger-symbols"></a> +</dd> +<dt><code>-S</code></dt> +<dt><code>--strip-debug</code></dt> +<dd><p>Omit debugger symbol information (but not all symbols) from the output file. +</p> +<a name="index-_002d_002dstrip_002ddiscarded"></a> +<a name="index-_002d_002dno_002dstrip_002ddiscarded"></a> +</dd> +<dt><code>--strip-discarded</code></dt> +<dt><code>--no-strip-discarded</code></dt> +<dd><p>Omit (or do not omit) global symbols defined in discarded sections. +Enabled by default. +</p> +<a name="index-_002dt"></a> +<a name="index-_002d_002dtrace"></a> +<a name="index-input-files_002c-displaying"></a> +</dd> +<dt><code>-t</code></dt> +<dt><code>--trace</code></dt> +<dd><p>Print the names of the input files as <code>ld</code> processes them. If +‘<samp>-t</samp>’ is given twice then members within archives are also printed. +‘<samp>-t</samp>’ output is useful to generate a list of all the object files +and scripts involved in linking, for example, when packaging files for +a linker bug report. +</p> +<a name="index-_002dT-script"></a> +<a name="index-_002d_002dscript_003dscript"></a> +<a name="index-script-files"></a> +</dd> +<dt><code>-T <var>scriptfile</var></code></dt> +<dt><code>--script=<var>scriptfile</var></code></dt> +<dd><p>Use <var>scriptfile</var> as the linker script. This script replaces +<code>ld</code>’s default linker script (rather than adding to it), +unless the script contains <code>INSERT</code>, so +<var>commandfile</var> must specify everything necessary to describe the +output file. See <a href="#Scripts">Scripts</a>. If <var>scriptfile</var> does not exist in +the current directory, <code>ld</code> looks for it in the directories +specified by any preceding ‘<samp>-L</samp>’ options. Multiple ‘<samp>-T</samp>’ +options accumulate. +</p> +<a name="index-_002ddT-script"></a> +<a name="index-_002d_002ddefault_002dscript_003dscript"></a> +<a name="index-script-files-1"></a> +</dd> +<dt><code>-dT <var>scriptfile</var></code></dt> +<dt><code>--default-script=<var>scriptfile</var></code></dt> +<dd><p>Use <var>scriptfile</var> as the default linker script. See <a href="#Scripts">Scripts</a>. +</p> +<p>This option is similar to the <samp>--script</samp> option except that +processing of the script is delayed until after the rest of the +command line has been processed. This allows options placed after the +<samp>--default-script</samp> option on the command line to affect the +behaviour of the linker script, which can be important when the linker +command line cannot be directly controlled by the user. (eg because +the command line is being constructed by another tool, such as +‘<samp>gcc</samp>’). +</p> +<a name="index-_002du-symbol"></a> +<a name="index-_002d_002dundefined_003dsymbol"></a> +<a name="index-undefined-symbol"></a> +</dd> +<dt><code>-u <var>symbol</var></code></dt> +<dt><code>--undefined=<var>symbol</var></code></dt> +<dd><p>Force <var>symbol</var> to be entered in the output file as an undefined +symbol. Doing this may, for example, trigger linking of additional +modules from standard libraries. ‘<samp>-u</samp>’ may be repeated with +different option arguments to enter additional undefined symbols. This +option is equivalent to the <code>EXTERN</code> linker script command. +</p> +<p>If this option is being used to force additional modules to be pulled +into the link, and if it is an error for the symbol to remain +undefined, then the option <samp>--require-defined</samp> should be used +instead. +</p> +<a name="index-_002d_002drequire_002ddefined_003dsymbol"></a> +<a name="index-symbols_002c-require-defined"></a> +<a name="index-defined-symbol"></a> +</dd> +<dt><code>--require-defined=<var>symbol</var></code></dt> +<dd><p>Require that <var>symbol</var> is defined in the output file. This option +is the same as option <samp>--undefined</samp> except that if <var>symbol</var> +is not defined in the output file then the linker will issue an error +and exit. The same effect can be achieved in a linker script by using +<code>EXTERN</code>, <code>ASSERT</code> and <code>DEFINED</code> together. This option +can be used multiple times to require additional symbols. +</p> +<a name="index-_002dUr"></a> +<a name="index-constructors"></a> +</dd> +<dt><code>-Ur</code></dt> +<dd> +<p>For programs that do not use constructors or destructors, or for ELF +based systems this option is equivalent to <samp>-r</samp>: it generates +relocatable output—i.e., an output file that can in turn serve as +input to <code>ld</code>. For other binaries however the <samp>-Ur</samp> +option is similar to <samp>-r</samp> but it also resolves references to +constructors and destructors. +</p> +<p>For those systems where <samp>-r</samp> and <samp>-Ur</samp> behave +differently, it does not work to use <samp>-Ur</samp> on files that were +themselves linked with <samp>-Ur</samp>; once the constructor table has +been built, it cannot be added to. Use <samp>-Ur</samp> only for the last +partial link, and <samp>-r</samp> for the others. +</p> +<a name="index-_002d_002dorphan_002dhandling_003dMODE"></a> +<a name="index-orphan-sections"></a> +<a name="index-sections_002c-orphan"></a> +</dd> +<dt><code>--orphan-handling=<var>MODE</var></code></dt> +<dd><p>Control how orphan sections are handled. An orphan section is one not +specifically mentioned in a linker script. See <a href="#Orphan-Sections">Orphan Sections</a>. +</p> +<p><var>MODE</var> can have any of the following values: +</p> +<dl compact="compact"> +<dt><code>place</code></dt> +<dd><p>Orphan sections are placed into a suitable output section following +the strategy described in <a href="#Orphan-Sections">Orphan Sections</a>. The option +‘<samp>--unique</samp>’ also affects how sections are placed. +</p> +</dd> +<dt><code>discard</code></dt> +<dd><p>All orphan sections are discarded, by placing them in the +‘<samp>/DISCARD/</samp>’ section (see <a href="#Output-Section-Discarding">Output Section Discarding</a>). +</p> +</dd> +<dt><code>warn</code></dt> +<dd><p>The linker will place the orphan section as for <code>place</code> and also +issue a warning. +</p> +</dd> +<dt><code>error</code></dt> +<dd><p>The linker will exit with an error if any orphan section is found. +</p></dd> +</dl> + +<p>The default if ‘<samp>--orphan-handling</samp>’ is not given is <code>place</code>. +</p> +<a name="index-_002d_002dunique_005b_003dSECTION_005d"></a> +</dd> +<dt><code>--unique[=<var>SECTION</var>]</code></dt> +<dd><p>Creates a separate output section for every input section matching +<var>SECTION</var>, or if the optional wildcard <var>SECTION</var> argument is +missing, for every orphan input section. An orphan section is one not +specifically mentioned in a linker script. You may use this option +multiple times on the command line; It prevents the normal merging of +input sections with the same name, overriding output section assignments +in a linker script. +</p> +<a name="index-_002dv"></a> +<a name="index-_002dV"></a> +<a name="index-_002d_002dversion"></a> +<a name="index-version"></a> +</dd> +<dt><code>-v</code></dt> +<dt><code>--version</code></dt> +<dt><code>-V</code></dt> +<dd><p>Display the version number for <code>ld</code>. The <samp>-V</samp> option also +lists the supported emulations. See also the description of the +<samp>--enable-linker-version</samp> in <a href="#Options">Command-line Options</a> +which can be used to insert the linker version string into a binary. +</p> +<a name="index-_002dx"></a> +<a name="index-_002d_002ddiscard_002dall"></a> +<a name="index-deleting-local-symbols"></a> +</dd> +<dt><code>-x</code></dt> +<dt><code>--discard-all</code></dt> +<dd><p>Delete all local symbols. +</p> +<a name="index-_002dX"></a> +<a name="index-_002d_002ddiscard_002dlocals"></a> +<a name="index-local-symbols_002c-deleting"></a> +</dd> +<dt><code>-X</code></dt> +<dt><code>--discard-locals</code></dt> +<dd><p>Delete all temporary local symbols. (These symbols start with +system-specific local label prefixes, typically ‘<samp>.L</samp>’ for ELF systems +or ‘<samp>L</samp>’ for traditional a.out systems.) +</p> +<a name="index-_002dy-symbol"></a> +<a name="index-_002d_002dtrace_002dsymbol_003dsymbol"></a> +<a name="index-symbol-tracing"></a> +</dd> +<dt><code>-y <var>symbol</var></code></dt> +<dt><code>--trace-symbol=<var>symbol</var></code></dt> +<dd><p>Print the name of each linked file in which <var>symbol</var> appears. This +option may be given any number of times. On many systems it is necessary +to prepend an underscore. +</p> +<p>This option is useful when you have an undefined symbol in your link but +don’t know where the reference is coming from. +</p> +<a name="index-_002dY-path"></a> +</dd> +<dt><code>-Y <var>path</var></code></dt> +<dd><p>Add <var>path</var> to the default library search path. This option exists +for Solaris compatibility. +</p> +<a name="index-_002dz-keyword"></a> +</dd> +<dt><code>-z <var>keyword</var></code></dt> +<dd><p>The recognized keywords are: +</p><dl compact="compact"> +<dt>‘<samp>call-nop=prefix-addr</samp>’</dt> +<dt>‘<samp>call-nop=suffix-nop</samp>’</dt> +<dt>‘<samp>call-nop=prefix-<var>byte</var></samp>’</dt> +<dt>‘<samp>call-nop=suffix-<var>byte</var></samp>’</dt> +<dd><p>Specify the 1-byte <code>NOP</code> padding when transforming indirect call +to a locally defined function, foo, via its GOT slot. +<samp>call-nop=prefix-addr</samp> generates <code>0x67 call foo</code>. +<samp>call-nop=suffix-nop</samp> generates <code>call foo 0x90</code>. +<samp>call-nop=prefix-<var>byte</var></samp> generates <code><var>byte</var> call foo</code>. +<samp>call-nop=suffix-<var>byte</var></samp> generates <code>call foo <var>byte</var></code>. +Supported for i386 and x86_64. +</p> +</dd> +<dt>‘<samp>cet-report=none</samp>’</dt> +<dt>‘<samp>cet-report=warning</samp>’</dt> +<dt>‘<samp>cet-report=error</samp>’</dt> +<dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and +GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property +section. <samp>cet-report=none</samp>, which is the default, will make the +linker not report missing properties in input files. +<samp>cet-report=warning</samp> will make the linker issue a warning for +missing properties in input files. <samp>cet-report=error</samp> will make +the linker issue an error for missing properties in input files. +Note that <samp>ibt</samp> will turn off the missing +GNU_PROPERTY_X86_FEATURE_1_IBT property report and <samp>shstk</samp> will +turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report. +Supported for Linux/i386 and Linux/x86_64. +</p> +</dd> +<dt>‘<samp>combreloc</samp>’</dt> +<dt>‘<samp>nocombreloc</samp>’</dt> +<dd><p>Combine multiple dynamic relocation sections and sort to improve +dynamic symbol lookup caching. Do not do this if ‘<samp>nocombreloc</samp>’. +</p> +</dd> +<dt>‘<samp>common</samp>’</dt> +<dt>‘<samp>nocommon</samp>’</dt> +<dd><p>Generate common symbols with STT_COMMON type during a relocatable +link. Use STT_OBJECT type if ‘<samp>nocommon</samp>’. +</p> +</dd> +<dt>‘<samp>common-page-size=<var>value</var></samp>’</dt> +<dd><p>Set the page size most commonly used to <var>value</var>. Memory image +layout will be optimized to minimize memory pages if the system is +using pages of this size. +</p> +</dd> +<dt>‘<samp>defs</samp>’</dt> +<dd><p>Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +This option is the inverse of ‘<samp>-z undefs</samp>’. +</p> +</dd> +<dt>‘<samp>dynamic-undefined-weak</samp>’</dt> +<dt>‘<samp>nodynamic-undefined-weak</samp>’</dt> +<dd><p>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. Do not make them dynamic if +‘<samp>nodynamic-undefined-weak</samp>’. If neither option is given, a target +may default to either option being in force, or make some other +selection of undefined weak symbols dynamic. Not all targets support +these options. +</p> +</dd> +<dt>‘<samp>execstack</samp>’</dt> +<dd><p>Marks the object as requiring executable stack. +</p> +</dd> +<dt>‘<samp>global</samp>’</dt> +<dd><p>This option is only meaningful when building a shared object. It makes +the symbols defined by this shared object available for symbol resolution +of subsequently loaded libraries. +</p> +</dd> +<dt>‘<samp>globalaudit</samp>’</dt> +<dd><p>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</code> bit in the <code>DT_FLAGS_1</code> dynamic +tag. Global auditing requires that any auditing library defined via +the <samp>--depaudit</samp> or <samp>-P</samp> command-line options be run for +all dynamic objects loaded by the application. +</p> +</dd> +<dt>‘<samp>ibtplt</samp>’</dt> +<dd><p>Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries. +Supported for Linux/i386 and Linux/x86_64. +</p> +</dd> +<dt>‘<samp>ibt</samp>’</dt> +<dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section +to indicate compatibility with IBT. This also implies <samp>ibtplt</samp>. +Supported for Linux/i386 and Linux/x86_64. +</p> +</dd> +<dt>‘<samp>indirect-extern-access</samp>’</dt> +<dt>‘<samp>noindirect-extern-access</samp>’</dt> +<dd><p>Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in +.note.gnu.property section to indicate that object file requires +canonical function pointers and cannot be used with copy relocation. +This option also implies <samp>noextern-protected-data</samp> and +<samp>nocopyreloc</samp>. Supported for i386 and x86-64. +</p> +<p><samp>noindirect-extern-access</samp> removes +GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property +section. +</p> +</dd> +<dt>‘<samp>initfirst</samp>’</dt> +<dd><p>This option is only meaningful when building a shared object. +It marks the object so that its runtime initialization will occur +before the runtime initialization of any other objects brought into +the process at the same time. Similarly the runtime finalization of +the object will occur after the runtime finalization of any other +objects. +</p> +</dd> +<dt>‘<samp>interpose</samp>’</dt> +<dd><p>Specify that the dynamic loader should modify its symbol search order +so that symbols in this shared library interpose all other shared +libraries not so marked. +</p> +</dd> +<dt>‘<samp>unique</samp>’</dt> +<dt>‘<samp>nounique</samp>’</dt> +<dd><p>When generating a shared library or other dynamically loadable ELF +object mark it as one that should (by default) only ever be loaded once, +and only in the main namespace (when using <code>dlmopen</code>). This is +primarily used to mark fundamental libraries such as libc, libpthread et +al which do not usually function correctly unless they are the sole instances +of themselves. This behaviour can be overridden by the <code>dlmopen</code> caller +and does not apply to certain loading mechanisms (such as audit libraries). +</p> +</dd> +<dt>‘<samp>lam-u48</samp>’</dt> +<dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U48 in .note.gnu.property section +to indicate compatibility with Intel LAM_U48. Supported for Linux/x86_64. +</p> +</dd> +<dt>‘<samp>lam-u57</samp>’</dt> +<dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U57 in .note.gnu.property section +to indicate compatibility with Intel LAM_U57. Supported for Linux/x86_64. +</p> +</dd> +<dt>‘<samp>lam-u48-report=none</samp>’</dt> +<dt>‘<samp>lam-u48-report=warning</samp>’</dt> +<dt>‘<samp>lam-u48-report=error</samp>’</dt> +<dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 +property in input .note.gnu.property section. +<samp>lam-u48-report=none</samp>, which is the default, will make the +linker not report missing properties in input files. +<samp>lam-u48-report=warning</samp> will make the linker issue a warning for +missing properties in input files. <samp>lam-u48-report=error</samp> will +make the linker issue an error for missing properties in input files. +Supported for Linux/x86_64. +</p> +</dd> +<dt>‘<samp>lam-u57-report=none</samp>’</dt> +<dt>‘<samp>lam-u57-report=warning</samp>’</dt> +<dt>‘<samp>lam-u57-report=error</samp>’</dt> +<dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57 +property in input .note.gnu.property section. +<samp>lam-u57-report=none</samp>, which is the default, will make the +linker not report missing properties in input files. +<samp>lam-u57-report=warning</samp> will make the linker issue a warning for +missing properties in input files. <samp>lam-u57-report=error</samp> will +make the linker issue an error for missing properties in input files. +Supported for Linux/x86_64. +</p> +</dd> +<dt>‘<samp>lam-report=none</samp>’</dt> +<dt>‘<samp>lam-report=warning</samp>’</dt> +<dt>‘<samp>lam-report=error</samp>’</dt> +<dd><p>Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 and +GNU_PROPERTY_X86_FEATURE_1_LAM_U57 properties in input .note.gnu.property +section. <samp>lam-report=none</samp>, which is the default, will make the +linker not report missing properties in input files. +<samp>lam-report=warning</samp> will make the linker issue a warning for +missing properties in input files. <samp>lam-report=error</samp> will make +the linker issue an error for missing properties in input files. +Supported for Linux/x86_64. +</p> +</dd> +<dt>‘<samp>lazy</samp>’</dt> +<dd><p>When generating an executable or shared library, mark it to tell the +dynamic linker to defer function call resolution to the point when +the function is called (lazy binding), rather than at load time. +Lazy binding is the default. +</p> +</dd> +<dt>‘<samp>loadfltr</samp>’</dt> +<dd><p>Specify that the object’s filters be processed immediately at runtime. +</p> +</dd> +<dt>‘<samp>max-page-size=<var>value</var></samp>’</dt> +<dd><p>Set the maximum memory page size supported to <var>value</var>. +</p> +</dd> +<dt>‘<samp>muldefs</samp>’</dt> +<dd><p>Allow multiple definitions. +</p> +</dd> +<dt>‘<samp>nocopyreloc</samp>’</dt> +<dd><p>Disable linker generated .dynbss variables used in place of variables +defined in shared libraries. May result in dynamic text relocations. +</p> +</dd> +<dt>‘<samp>nodefaultlib</samp>’</dt> +<dd><p>Specify that the dynamic loader search for dependencies of this object +should ignore any default library search paths. +</p> +</dd> +<dt>‘<samp>nodelete</samp>’</dt> +<dd><p>Specify that the object shouldn’t be unloaded at runtime. +</p> +</dd> +<dt>‘<samp>nodlopen</samp>’</dt> +<dd><p>Specify that the object is not available to <code>dlopen</code>. +</p> +</dd> +<dt>‘<samp>nodump</samp>’</dt> +<dd><p>Specify that the object can not be dumped by <code>dldump</code>. +</p> +</dd> +<dt>‘<samp>noexecstack</samp>’</dt> +<dd><p>Marks the object as not requiring executable stack. +</p> +</dd> +<dt>‘<samp>noextern-protected-data</samp>’</dt> +<dd><p>Don’t treat protected data symbols as external when building a shared +library. This option overrides the linker backend default. It can be +used to work around incorrect relocations against protected data symbols +generated by compiler. Updates on protected data symbols by another +module aren’t visible to the resulting shared library. Supported for +i386 and x86-64. +</p> +</dd> +<dt>‘<samp>noreloc-overflow</samp>’</dt> +<dd><p>Disable relocation overflow check. This can be used to disable +relocation overflow check if there will be no dynamic relocation +overflow at run-time. Supported for x86_64. +</p> +</dd> +<dt>‘<samp>now</samp>’</dt> +<dd><p>When generating an executable or shared library, mark it to tell the +dynamic linker to resolve all symbols when the program is started, or +when the shared library is loaded by dlopen, instead of deferring +function call resolution to the point when the function is first +called. +</p> +</dd> +<dt>‘<samp>origin</samp>’</dt> +<dd><p>Specify that the object requires ‘<samp>$ORIGIN</samp>’ handling in paths. +</p> +</dd> +<dt>‘<samp>pack-relative-relocs</samp>’</dt> +<dt>‘<samp>nopack-relative-relocs</samp>’</dt> +<dd><p>Generate compact relative relocation in position-independent executable +and shared library. It adds <code>DT_RELR</code>, <code>DT_RELRSZ</code> and +<code>DT_RELRENT</code> entries to the dynamic section. It is ignored when +building position-dependent executable and relocatable output. +<samp>nopack-relative-relocs</samp> is the default, which disables compact +relative relocation. When linked against the GNU C Library, a +GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is +added to the output. Supported for i386 and x86-64. +</p> +</dd> +<dt>‘<samp>relro</samp>’</dt> +<dt>‘<samp>norelro</samp>’</dt> +<dd><p>Create an ELF <code>PT_GNU_RELRO</code> segment header in the object. This +specifies a memory segment that should be made read-only after +relocation, if supported. Specifying ‘<samp>common-page-size</samp>’ smaller +than the system page size will render this protection ineffective. +Don’t create an ELF <code>PT_GNU_RELRO</code> segment if ‘<samp>norelro</samp>’. +</p> +</dd> +<dt>‘<samp>report-relative-reloc</samp>’</dt> +<dd><p>Report dynamic relative relocations generated by linker. Supported for +Linux/i386 and Linux/x86_64. +</p> +</dd> +<dt>‘<samp>sectionheader</samp>’</dt> +<dt>‘<samp>nosectionheader</samp>’</dt> +<dd><p>Generate section header. Don’t generate section header if +‘<samp>nosectionheader</samp>’ is used. <samp>sectionheader</samp> is the default. +</p> +</dd> +<dt>‘<samp>separate-code</samp>’</dt> +<dt>‘<samp>noseparate-code</samp>’</dt> +<dd><p>Create separate code <code>PT_LOAD</code> segment header in the object. This +specifies a memory segment that should contain only instructions and must +be in wholly disjoint pages from any other data. Don’t create separate +code <code>PT_LOAD</code> segment if ‘<samp>noseparate-code</samp>’ is used. +</p> +</dd> +<dt>‘<samp>shstk</samp>’</dt> +<dd><p>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. +</p> +</dd> +<dt>‘<samp>stack-size=<var>value</var></samp>’</dt> +<dd><p>Specify a stack size for an ELF <code>PT_GNU_STACK</code> segment. +Specifying zero will override any default non-zero sized +<code>PT_GNU_STACK</code> segment creation. +</p> +</dd> +<dt>‘<samp>start-stop-gc</samp>’</dt> +<dt>‘<samp>nostart-stop-gc</samp>’</dt> +<dd><a name="index-start_002dstop_002dgc"></a> +<p>When ‘<samp>--gc-sections</samp>’ is in effect, a reference from a retained +section to <code>__start_SECNAME</code> or <code>__stop_SECNAME</code> causes all +input sections named <code>SECNAME</code> to also be retained, if +<code>SECNAME</code> is representable as a C identifier and either +<code>__start_SECNAME</code> or <code>__stop_SECNAME</code> is synthesized by the +linker. ‘<samp>-z start-stop-gc</samp>’ disables this effect, allowing +sections to be garbage collected as if the special synthesized symbols +were not defined. ‘<samp>-z start-stop-gc</samp>’ has no effect on a +definition of <code>__start_SECNAME</code> or <code>__stop_SECNAME</code> in an +object file or linker script. Such a definition will prevent the +linker providing a synthesized <code>__start_SECNAME</code> or +<code>__stop_SECNAME</code> respectively, and therefore the special +treatment by garbage collection for those references. +</p> +</dd> +<dt>‘<samp>start-stop-visibility=<var>value</var></samp>’</dt> +<dd><a name="index-visibility"></a> +<a name="index-ELF-symbol-visibility"></a> +<p>Specify the ELF symbol visibility for synthesized +<code>__start_SECNAME</code> and <code>__stop_SECNAME</code> symbols (see <a href="#Input-Section-Example">Input Section Example</a>). <var>value</var> must be exactly ‘<samp>default</samp>’, +‘<samp>internal</samp>’, ‘<samp>hidden</samp>’, or ‘<samp>protected</samp>’. If no ‘<samp>-z +start-stop-visibility</samp>’ option is given, ‘<samp>protected</samp>’ is used for +compatibility with historical practice. However, it’s highly +recommended to use ‘<samp>-z start-stop-visibility=hidden</samp>’ in new +programs and shared libraries so that these symbols are not exported +between shared objects, which is not usually what’s intended. +</p> +</dd> +<dt>‘<samp>text</samp>’</dt> +<dt>‘<samp>notext</samp>’</dt> +<dt>‘<samp>textoff</samp>’</dt> +<dd><p>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</samp>’ or ‘<samp>textoff</samp>’. +</p> +</dd> +<dt>‘<samp>undefs</samp>’</dt> +<dd><p>Do not report unresolved symbol references from regular object files, +either when creating an executable, or when creating a shared library. +This option is the inverse of ‘<samp>-z defs</samp>’. +</p> +</dd> +<dt>‘<samp>unique-symbol</samp>’</dt> +<dt>‘<samp>nounique-symbol</samp>’</dt> +<dd><p>Avoid duplicated local symbol names in the symbol string table. Append +".<code>number</code>" to duplicated local symbol names if ‘<samp>unique-symbol</samp>’ +is used. <samp>nounique-symbol</samp> is the default. +</p> +</dd> +<dt>‘<samp>x86-64-baseline</samp>’</dt> +<dt>‘<samp>x86-64-v2</samp>’</dt> +<dt>‘<samp>x86-64-v3</samp>’</dt> +<dt>‘<samp>x86-64-v4</samp>’</dt> +<dd><p>Specify the x86-64 ISA level needed in .note.gnu.property section. +<samp>x86-64-baseline</samp> generates <code>GNU_PROPERTY_X86_ISA_1_BASELINE</code>. +<samp>x86-64-v2</samp> generates <code>GNU_PROPERTY_X86_ISA_1_V2</code>. +<samp>x86-64-v3</samp> generates <code>GNU_PROPERTY_X86_ISA_1_V3</code>. +<samp>x86-64-v4</samp> generates <code>GNU_PROPERTY_X86_ISA_1_V4</code>. +Supported for Linux/i386 and Linux/x86_64. +</p> +</dd> +</dl> + +<p>Other keywords are ignored for Solaris compatibility. +</p> +<a name="index-_002d_0028"></a> +<a name="index-groups-of-archives"></a> +</dd> +<dt><code>-( <var>archives</var> -)</code></dt> +<dt><code>--start-group <var>archives</var> --end-group</code></dt> +<dd><p>The <var>archives</var> should be a list of archive files. They may be +either explicit file names, or ‘<samp>-l</samp>’ options. +</p> +<p>The specified archives are searched repeatedly until no new undefined +references are created. Normally, an archive is searched only once in +the order that it is specified on the command line. If a symbol in that +archive is needed to resolve an undefined symbol referred to by an +object in an archive that appears later on the command line, the linker +would not be able to resolve that reference. By grouping the archives, +they will all be searched repeatedly until all possible references are +resolved. +</p> +<p>Using this option has a significant performance cost. It is best to use +it only when there are unavoidable circular references between two or +more archives. +</p> +<a name="index-_002d_002daccept_002dunknown_002dinput_002darch"></a> +<a name="index-_002d_002dno_002daccept_002dunknown_002dinput_002darch"></a> +</dd> +<dt><code>--accept-unknown-input-arch</code></dt> +<dt><code>--no-accept-unknown-input-arch</code></dt> +<dd><p>Tells the linker to accept input files whose architecture cannot be +recognised. The assumption is that the user knows what they are doing +and deliberately wants to link in these unknown input files. This was +the default behaviour of the linker, before release 2.14. The default +behaviour from release 2.14 onwards is to reject such input files, and +so the ‘<samp>--accept-unknown-input-arch</samp>’ option has been added to +restore the old behaviour. +</p> +<a name="index-_002d_002das_002dneeded"></a> +<a name="index-_002d_002dno_002das_002dneeded"></a> +</dd> +<dt><code>--as-needed</code></dt> +<dt><code>--no-as-needed</code></dt> +<dd><p>This option affects ELF DT_NEEDED tags for dynamic libraries mentioned +on the command line after the <samp>--as-needed</samp> option. Normally +the linker will add a DT_NEEDED tag for each dynamic library mentioned +on the command line, regardless of whether the library is actually +needed or not. <samp>--as-needed</samp> causes a DT_NEEDED tag to only be +emitted for a library that <em>at that point in the link</em> satisfies a +non-weak undefined symbol reference from a regular object file or, if +the library is not found in the DT_NEEDED lists of other needed libraries, a +non-weak undefined symbol reference from another needed dynamic library. +Object files or libraries appearing on the command line <em>after</em> +the library in question do not affect whether the library is seen as +needed. This is similar to the rules for extraction of object files +from archives. <samp>--no-as-needed</samp> restores the default behaviour. +</p> +<p>Note: On Linux based systems the <samp>--as-needed</samp> option also has +an affect on the behaviour of the <samp>--rpath</samp> and +<samp>--rpath-link</samp> options. See the description of +<samp>--rpath-link</samp> for more details. +</p> +<a name="index-_002d_002dadd_002dneeded"></a> +<a name="index-_002d_002dno_002dadd_002dneeded"></a> +</dd> +<dt><code>--add-needed</code></dt> +<dt><code>--no-add-needed</code></dt> +<dd><p>These two options have been deprecated because of the similarity of +their names to the <samp>--as-needed</samp> and <samp>--no-as-needed</samp> +options. They have been replaced by <samp>--copy-dt-needed-entries</samp> +and <samp>--no-copy-dt-needed-entries</samp>. +</p> +<a name="index-_002dassert-keyword"></a> +</dd> +<dt><code>-assert <var>keyword</var></code></dt> +<dd><p>This option is ignored for SunOS compatibility. +</p> +<a name="index-_002dBdynamic"></a> +<a name="index-_002ddy"></a> +<a name="index-_002dcall_005fshared"></a> +</dd> +<dt><code>-Bdynamic</code></dt> +<dt><code>-dy</code></dt> +<dt><code>-call_shared</code></dt> +<dd><p>Link against dynamic libraries. This is only meaningful on platforms +for which shared libraries are supported. This option is normally the +default on such platforms. The different variants of this option are +for compatibility with various systems. You may use this option +multiple times on the command line: it affects library searching for +<samp>-l</samp> options which follow it. +</p> +<a name="index-_002dBgroup"></a> +</dd> +<dt><code>-Bgroup</code></dt> +<dd><p>Set the <code>DF_1_GROUP</code> flag in the <code>DT_FLAGS_1</code> entry in the dynamic +section. This causes the runtime linker to handle lookups in this +object and its dependencies to be performed only inside the group. +<samp>--unresolved-symbols=report-all</samp> is implied. This option is +only meaningful on ELF platforms which support shared libraries. +</p> +<a name="index-_002dBstatic"></a> +<a name="index-_002ddn"></a> +<a name="index-_002dnon_005fshared"></a> +<a name="index-_002dstatic"></a> +</dd> +<dt><code>-Bstatic</code></dt> +<dt><code>-dn</code></dt> +<dt><code>-non_shared</code></dt> +<dt><code>-static</code></dt> +<dd><p>Do not link against shared libraries. This is only meaningful on +platforms for which shared libraries are supported. The different +variants of this option are for compatibility with various systems. You +may use this option multiple times on the command line: it affects +library searching for <samp>-l</samp> options which follow it. This +option also implies <samp>--unresolved-symbols=report-all</samp>. This +option can be used with <samp>-shared</samp>. Doing so means that a +shared library is being created but that all of the library’s external +references must be resolved by pulling in entries from static +libraries. +</p> +<a name="index-_002dBsymbolic"></a> +</dd> +<dt><code>-Bsymbolic</code></dt> +<dd><p>When creating a shared library, bind references to global symbols to the +definition within the shared library, if any. Normally, it is possible +for a program linked against a shared library to override the definition +within the shared library. This option is only meaningful on ELF +platforms which support shared libraries. +</p> +<a name="index-_002dBsymbolic_002dfunctions"></a> +</dd> +<dt><code>-Bsymbolic-functions</code></dt> +<dd><p>When creating a shared library, bind references to global function +symbols to the definition within the shared library, if any. +This option is only meaningful on ELF platforms which support shared +libraries. +</p> +<a name="index-_002dBno_002dsymbolic"></a> +</dd> +<dt><code>-Bno-symbolic</code></dt> +<dd><p>This option can cancel previously specified ‘<samp>-Bsymbolic</samp>’ and +‘<samp>-Bsymbolic-functions</samp>’. +</p> +<a name="index-_002d_002ddynamic_002dlist_003ddynamic_002dlist_002dfile"></a> +</dd> +<dt><code>--dynamic-list=<var>dynamic-list-file</var></code></dt> +<dd><p>Specify the name of a dynamic list file to the linker. This is +typically used when creating shared libraries to specify a list of +global symbols whose references shouldn’t be bound to the definition +within the shared library, or creating dynamically linked executables +to specify a list of symbols which should be added to the symbol table +in the executable. This option is only meaningful on ELF platforms +which support shared libraries. +</p> +<p>The format of the dynamic list is the same as the version node without +scope and node name. See <a href="#VERSION">VERSION</a> for more information. +</p> +<a name="index-_002d_002ddynamic_002dlist_002ddata"></a> +</dd> +<dt><code>--dynamic-list-data</code></dt> +<dd><p>Include all global data symbols to the dynamic list. +</p> +<a name="index-_002d_002ddynamic_002dlist_002dcpp_002dnew"></a> +</dd> +<dt><code>--dynamic-list-cpp-new</code></dt> +<dd><p>Provide the builtin dynamic list for C++ operator new and delete. It +is mainly useful for building shared libstdc++. +</p> +<a name="index-_002d_002ddynamic_002dlist_002dcpp_002dtypeinfo"></a> +</dd> +<dt><code>--dynamic-list-cpp-typeinfo</code></dt> +<dd><p>Provide the builtin dynamic list for C++ runtime type identification. +</p> +<a name="index-_002d_002dcheck_002dsections"></a> +<a name="index-_002d_002dno_002dcheck_002dsections"></a> +</dd> +<dt><code>--check-sections</code></dt> +<dt><code>--no-check-sections</code></dt> +<dd><p>Asks the linker <em>not</em> to check section addresses after they have +been assigned to see if there are any overlaps. Normally the linker will +perform this check, and if it finds any overlaps it will produce +suitable error messages. The linker does know about, and does make +allowances for sections in overlays. The default behaviour can be +restored by using the command-line switch <samp>--check-sections</samp>. +Section overlap is not usually checked for relocatable links. You can +force checking in that case by using the <samp>--check-sections</samp> +option. +</p> +<a name="index-_002d_002dcopy_002ddt_002dneeded_002dentries"></a> +<a name="index-_002d_002dno_002dcopy_002ddt_002dneeded_002dentries"></a> +</dd> +<dt><code>--copy-dt-needed-entries</code></dt> +<dt><code>--no-copy-dt-needed-entries</code></dt> +<dd><p>This option affects the treatment of dynamic libraries referred to +by DT_NEEDED tags <em>inside</em> ELF dynamic libraries mentioned on the +command line. Normally the linker won’t add a DT_NEEDED tag to the +output binary for each library mentioned in a DT_NEEDED tag in an +input dynamic library. With <samp>--copy-dt-needed-entries</samp> +specified on the command line however any dynamic libraries that +follow it will have their DT_NEEDED entries added. The default +behaviour can be restored with <samp>--no-copy-dt-needed-entries</samp>. +</p> +<p>This option also has an effect on the resolution of symbols in dynamic +libraries. With <samp>--copy-dt-needed-entries</samp> dynamic libraries +mentioned on the command line will be recursively searched, following +their DT_NEEDED tags to other libraries, in order to resolve symbols +required by the output binary. With the default setting however +the searching of dynamic libraries that follow it will stop with the +dynamic library itself. No DT_NEEDED links will be traversed to resolve +symbols. +</p> +<a name="index-cross-reference-table"></a> +<a name="index-_002d_002dcref"></a> +</dd> +<dt><code>--cref</code></dt> +<dd><p>Output a cross reference table. If a linker map file is being +generated, the cross reference table is printed to the map file. +Otherwise, it is printed on the standard output. +</p> +<p>The format of the table is intentionally simple, so that it may be +easily processed by a script if necessary. The symbols are printed out, +sorted by name. For each symbol, a list of file names is given. If the +symbol is defined, the first file listed is the location of the +definition. If the symbol is defined as a common value then any files +where this happens appear next. Finally any files that reference the +symbol are listed. +</p> +<a name="index-ctf-variables"></a> +<a name="index-_002d_002dctf_002dvariables"></a> +<a name="index-_002d_002dno_002dctf_002dvariables"></a> +</dd> +<dt><code>--ctf-variables</code></dt> +<dt><code>--no-ctf-variables</code></dt> +<dd><p>The CTF debuginfo format supports a section which encodes the names and +types of variables found in the program which do not appear in any symbol +table. These variables clearly cannot be looked up by address by +conventional debuggers, so the space used for their types and names is +usually wasted: the types are usually small but the names are often not. +<samp>--ctf-variables</samp> causes the generation of such a section. +The default behaviour can be restored with <samp>--no-ctf-variables</samp>. +</p> +<a name="index-ctf-type-sharing"></a> +<a name="index-_002d_002dctf_002dshare_002dtypes"></a> +</dd> +<dt><code>--ctf-share-types=<var>method</var></code></dt> +<dd><p>Adjust the method used to share types between translation units in CTF. +</p> +<dl compact="compact"> +<dt>‘<samp>share-unconflicted</samp>’</dt> +<dd><p>Put all types that do not have ambiguous definitions into the shared dictionary, +where debuggers can easily access them, even if they only occur in one +translation unit. This is the default. +</p> +</dd> +<dt>‘<samp>share-duplicated</samp>’</dt> +<dd><p>Put only types that occur in multiple translation units into the shared +dictionary: types with only one definition go into per-translation-unit +dictionaries. Types with ambiguous definitions in multiple translation units +always go into per-translation-unit dictionaries. This tends to make the CTF +larger, but may reduce the amount of CTF in the shared dictionary. For very +large projects this may speed up opening the CTF and save memory in the CTF +consumer at runtime. +</p></dd> +</dl> + +<a name="index-common-allocation-1"></a> +<a name="index-_002d_002dno_002ddefine_002dcommon"></a> +</dd> +<dt><code>--no-define-common</code></dt> +<dd><p>This option inhibits the assignment of addresses to common symbols. +The script command <code>INHIBIT_COMMON_ALLOCATION</code> has the same effect. +See <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>. +</p> +<p>The ‘<samp>--no-define-common</samp>’ option allows decoupling +the decision to assign addresses to Common symbols from the choice +of the output file type; otherwise a non-Relocatable output type +forces assigning addresses to Common symbols. +Using ‘<samp>--no-define-common</samp>’ allows Common symbols that are referenced +from a shared library to be assigned addresses only in the main program. +This eliminates the unused duplicate space in the shared library, +and also prevents any possible confusion over resolving to the wrong +duplicate when there are many dynamic modules with specialized search +paths for runtime symbol resolution. +</p> +<a name="index-group-allocation-in-linker-script"></a> +<a name="index-section-groups"></a> +<a name="index-COMDAT"></a> +<a name="index-_002d_002dforce_002dgroup_002dallocation"></a> +</dd> +<dt><code>--force-group-allocation</code></dt> +<dd><p>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</samp>’). The script +command <code>FORCE_GROUP_ALLOCATION</code> has the same +effect. See <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>. +</p> +<a name="index-symbols_002c-from-command-line"></a> +<a name="index-_002d_002ddefsym_003dsymbol_003dexp"></a> +</dd> +<dt><code>--defsym=<var>symbol</var>=<var>expression</var></code></dt> +<dd><p>Create a global symbol in the output file, containing the absolute +address given by <var>expression</var>. You may use this option as many +times as necessary to define multiple symbols in the command line. A +limited form of arithmetic is supported for the <var>expression</var> in this +context: you may give a hexadecimal constant or the name of an existing +symbol, or use <code>+</code> and <code>-</code> to add or subtract hexadecimal +constants or symbols. If you need more elaborate expressions, consider +using the linker command language from a script (see <a href="#Assignments">Assignments</a>). +<em>Note:</em> there should be no white space between <var>symbol</var>, the +equals sign (“<tt class="key">=</tt>”), and <var>expression</var>. +</p> +<p>The linker processes ‘<samp>--defsym</samp>’ arguments and ‘<samp>-T</samp>’ arguments +in order, placing ‘<samp>--defsym</samp>’ before ‘<samp>-T</samp>’ will define the +symbol before the linker script from ‘<samp>-T</samp>’ is processed, while +placing ‘<samp>--defsym</samp>’ after ‘<samp>-T</samp>’ will define the symbol after +the linker script has been processed. This difference has +consequences for expressions within the linker script that use the +‘<samp>--defsym</samp>’ symbols, which order is correct will depend on what +you are trying to achieve. +</p> +<a name="index-demangling_002c-from-command-line"></a> +<a name="index-_002d_002ddemangle_005b_003dstyle_005d"></a> +<a name="index-_002d_002dno_002ddemangle"></a> +</dd> +<dt><code>--demangle[=<var>style</var>]</code></dt> +<dt><code>--no-demangle</code></dt> +<dd><p>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. 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</samp>’ +is set. These options may be used to override the default. +</p> +<a name="index-dynamic-linker_002c-from-command-line"></a> +<a name="index-_002dIfile"></a> +<a name="index-_002d_002ddynamic_002dlinker_003dfile"></a> +</dd> +<dt><code>-I<var>file</var></code></dt> +<dt><code>--dynamic-linker=<var>file</var></code></dt> +<dd><p>Set the name of the dynamic linker. This is only meaningful when +generating dynamically linked ELF executables. The default dynamic +linker is normally correct; don’t use this unless you know what you are +doing. +</p> +<a name="index-_002d_002dno_002ddynamic_002dlinker"></a> +</dd> +<dt><code>--no-dynamic-linker</code></dt> +<dd><p>When producing an executable file, omit the request for a dynamic +linker to be used at load-time. This is only meaningful for ELF +executables that contain dynamic relocations, and usually requires +entry point code that is capable of processing these relocations. +</p> +<a name="index-_002d_002dembedded_002drelocs"></a> +</dd> +<dt><code>--embedded-relocs</code></dt> +<dd><p>This option is similar to the <samp>--emit-relocs</samp> option except +that the relocs are stored in a target-specific section. This option +is only supported by the ‘<samp>BFIN</samp>’, ‘<samp>CR16</samp>’ and <em>M68K</em> +targets. +</p> +<a name="index-_002d_002ddisable_002dmultiple_002dabs_002ddefs"></a> +</dd> +<dt><code>--disable-multiple-abs-defs</code></dt> +<dd><p>Do not allow multiple definitions with symbols included +in filename invoked by -R or –just-symbols +</p> +<a name="index-_002d_002dfatal_002dwarnings"></a> +<a name="index-_002d_002dno_002dfatal_002dwarnings"></a> +</dd> +<dt><code>--fatal-warnings</code></dt> +<dt><code>--no-fatal-warnings</code></dt> +<dd><p>Treat all warnings as errors. The default behaviour can be restored +with the option <samp>--no-fatal-warnings</samp>. +</p> +<a name="index-_002dw"></a> +<a name="index-_002d_002dno_002dwarnings"></a> +</dd> +<dt><code>-w</code></dt> +<dt><code>--no-warnings</code></dt> +<dd><p>Do not display any warning or error messages. This overrides +<samp>--fatal-warnings</samp> if it has been enabled. This option can be +used when it is known that the output binary will not work, but there +is still a need to create it. +</p> +<a name="index-_002d_002dforce_002dexe_002dsuffix"></a> +</dd> +<dt><code>--force-exe-suffix</code></dt> +<dd><p>Make sure that an output file has a .exe suffix. +</p> +<p>If a successfully built fully linked output file does not have a +<code>.exe</code> or <code>.dll</code> suffix, this option forces the linker to copy +the output file to one of the same name with a <code>.exe</code> suffix. This +option is useful when using unmodified Unix makefiles on a Microsoft +Windows host, since some versions of Windows won’t run an image unless +it ends in a <code>.exe</code> suffix. +</p> +<a name="index-_002d_002dgc_002dsections"></a> +<a name="index-_002d_002dno_002dgc_002dsections"></a> +<a name="index-garbage-collection"></a> +</dd> +<dt><code>--gc-sections</code></dt> +<dt><code>--no-gc-sections</code></dt> +<dd><p>Enable garbage collection of unused input sections. It is ignored on +targets that do not support this option. The default behaviour (of not +performing this garbage collection) can be restored by specifying +‘<samp>--no-gc-sections</samp>’ on the command line. Note that garbage +collection for COFF and PE format targets is supported, but the +implementation is currently considered to be experimental. +</p> +<p>‘<samp>--gc-sections</samp>’ decides which input sections are used by +examining symbols and relocations. The section containing the entry +symbol and all sections containing symbols undefined on the +command-line will be kept, as will sections containing symbols +referenced by dynamic objects. Note that when building shared +libraries, the linker must assume that any visible symbol is +referenced. Once this initial set of sections has been determined, +the linker recursively marks as used any section referenced by their +relocations. See ‘<samp>--entry</samp>’, ‘<samp>--undefined</samp>’, and +‘<samp>--gc-keep-exported</samp>’. +</p> +<p>This option can be set when doing a partial link (enabled with option +‘<samp>-r</samp>’). In this case the root of symbols kept must be explicitly +specified either by one of the options ‘<samp>--entry</samp>’, +‘<samp>--undefined</samp>’, or ‘<samp>--gc-keep-exported</samp>’ or by a <code>ENTRY</code> +command in the linker script. +</p> +<p>As a GNU extension, ELF input sections marked with the +<code>SHF_GNU_RETAIN</code> flag will not be garbage collected. +</p> +<a name="index-_002d_002dprint_002dgc_002dsections"></a> +<a name="index-_002d_002dno_002dprint_002dgc_002dsections"></a> +<a name="index-garbage-collection-1"></a> +</dd> +<dt><code>--print-gc-sections</code></dt> +<dt><code>--no-print-gc-sections</code></dt> +<dd><p>List all sections removed by garbage collection. The listing is +printed on stderr. This option is only effective if garbage +collection has been enabled via the ‘<samp>--gc-sections</samp>’) option. The +default behaviour (of not listing the sections that are removed) can +be restored by specifying ‘<samp>--no-print-gc-sections</samp>’ on the command +line. +</p> +<a name="index-_002d_002dgc_002dkeep_002dexported"></a> +<a name="index-garbage-collection-2"></a> +</dd> +<dt><code>--gc-keep-exported</code></dt> +<dd><p>When ‘<samp>--gc-sections</samp>’ is enabled, this option prevents garbage +collection of unused input sections that contain global symbols having +default or protected visibility. This option is intended to be used for +executables where unreferenced sections would otherwise be garbage +collected regardless of the external visibility of contained symbols. +Note that this option has no effect when linking shared objects since +it is already the default behaviour. This option is only supported for +ELF format targets. +</p> +<a name="index-_002d_002dprint_002doutput_002dformat"></a> +<a name="index-output-format"></a> +</dd> +<dt><code>--print-output-format</code></dt> +<dd><p>Print the name of the default output format (perhaps influenced by +other command-line options). This is the string that would appear +in an <code>OUTPUT_FORMAT</code> linker script command (see <a href="#File-Commands">File Commands</a>). +</p> +<a name="index-_002d_002dprint_002dmemory_002dusage"></a> +<a name="index-memory-usage"></a> +</dd> +<dt><code>--print-memory-usage</code></dt> +<dd><p>Print used size, total size and used size of memory regions created with +the <a href="#MEMORY">MEMORY</a> command. This is useful on embedded targets to have a +quick view of amount of free memory. The format of the output has one +headline and one line per region. It is both human readable and easily +parsable by tools. Here is an example of an output: +</p> +<div class="smallexample"> +<pre class="smallexample">Memory region Used Size Region Size %age Used + ROM: 256 KB 1 MB 25.00% + RAM: 32 B 2 GB 0.00% +</pre></div> + +<a name="index-help"></a> +<a name="index-usage"></a> +<a name="index-_002d_002dhelp"></a> +</dd> +<dt><code>--help</code></dt> +<dd><p>Print a summary of the command-line options on the standard output and exit. +</p> +<a name="index-_002d_002dtarget_002dhelp"></a> +</dd> +<dt><code>--target-help</code></dt> +<dd><p>Print a summary of all target-specific options on the standard output and exit. +</p> +<a name="index-_002dMap_003dmapfile"></a> +</dd> +<dt><code>-Map=<var>mapfile</var></code></dt> +<dd><p>Print a link map to the file <var>mapfile</var>. See the description of the +<samp>-M</samp> option, above. If <var>mapfile</var> is just the character +<code>-</code> then the map will be written to stdout. +</p> +<p>Specifying a directory as <var>mapfile</var> causes the linker map to be +written as a file inside the directory. Normally name of the file +inside the directory is computed as the basename of the <var>output</var> +file with <code>.map</code> appended. If however the special character +<code>%</code> is used then this will be replaced by the full path of the +output file. Additionally if there are any characters after the +<var>%</var> symbol then <code>.map</code> will no longer be appended. +</p> +<div class="smallexample"> +<pre class="smallexample"> -o foo.exe -Map=bar [Creates ./bar] + -o ../dir/foo.exe -Map=bar [Creates ./bar] + -o foo.exe -Map=../dir [Creates ../dir/foo.exe.map] + -o ../dir2/foo.exe -Map=../dir [Creates ../dir/foo.exe.map] + -o foo.exe -Map=% [Creates ./foo.exe.map] + -o ../dir/foo.exe -Map=% [Creates ../dir/foo.exe.map] + -o foo.exe -Map=%.bar [Creates ./foo.exe.bar] + -o ../dir/foo.exe -Map=%.bar [Creates ../dir/foo.exe.bar] + -o ../dir2/foo.exe -Map=../dir/% [Creates ../dir/../dir2/foo.exe.map] + -o ../dir2/foo.exe -Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar] +</pre></div> + +<p>It is an error to specify more than one <code>%</code> character. +</p> +<p>If the map file already exists then it will be overwritten by this +operation. +</p> +<a name="index-memory-usage-1"></a> +<a name="index-_002d_002dno_002dkeep_002dmemory"></a> +</dd> +<dt><code>--no-keep-memory</code></dt> +<dd><p><code>ld</code> normally optimizes for speed over memory usage by caching the +symbol tables of input files in memory. This option tells <code>ld</code> to +instead optimize for memory usage, by rereading the symbol tables as +necessary. This may be required if <code>ld</code> runs out of memory space +while linking a large executable. +</p> +<a name="index-_002d_002dno_002dundefined"></a> +<a name="index-_002dz-defs"></a> +<a name="index-_002dz-undefs"></a> +</dd> +<dt><code>--no-undefined</code></dt> +<dt><code>-z defs</code></dt> +<dd><p>Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +The switch <samp>--[no-]allow-shlib-undefined</samp> controls the +behaviour for reporting unresolved references found in shared +libraries being linked in. +</p> +<p>The effects of this option can be reverted by using <code>-z undefs</code>. +</p> +<a name="index-_002d_002dallow_002dmultiple_002ddefinition"></a> +<a name="index-_002dz-muldefs"></a> +</dd> +<dt><code>--allow-multiple-definition</code></dt> +<dt><code>-z muldefs</code></dt> +<dd><p>Normally when a symbol is defined multiple times, the linker will +report a fatal error. These options allow multiple definitions and the +first definition will be used. +</p> +<a name="index-_002d_002dallow_002dshlib_002dundefined"></a> +<a name="index-_002d_002dno_002dallow_002dshlib_002dundefined"></a> +</dd> +<dt><code>--allow-shlib-undefined</code></dt> +<dt><code>--no-allow-shlib-undefined</code></dt> +<dd><p>Allows or disallows undefined symbols in shared libraries. +This switch is similar to <samp>--no-undefined</samp> except that it +determines the behaviour when the undefined symbols are in a +shared library rather than a regular object file. It does not affect +how undefined symbols in regular object files are handled. +</p> +<p>The default behaviour is to report errors for any undefined symbols +referenced in shared libraries if the linker is being used to create +an executable, but to allow them if the linker is being used to create +a shared library. +</p> +<p>The reasons for allowing undefined symbol references in shared +libraries specified at link time are that: +</p> +<ul> +<li> A shared library specified at link time may not be the same as the one +that is available at load time, so the symbol might actually be +resolvable at load time. +</li><li> There are some operating systems, eg BeOS and HPPA, where undefined +symbols in shared libraries are normal. + +<p>The BeOS kernel for example patches shared libraries at load time to +select whichever function is most appropriate for the current +architecture. This is used, for example, to dynamically select an +appropriate memset function. +</p></li></ul> + +<a name="index-_002d_002derror_002dhandling_002dscript_003dscriptname"></a> +</dd> +<dt><code>--error-handling-script=<var>scriptname</var></code></dt> +<dd><p>If this option is provided then the linker will invoke +<var>scriptname</var> whenever an error is encountered. Currently however +only two kinds of error are supported: missing symbols and missing +libraries. Two arguments will be passed to script: the keyword +“undefined-symbol” or ‘missing-lib” and the <var>name</var> of the +undefined symbol or missing library. The intention is that the script +will provide suggestions to the user as to where the symbol or library +might be found. After the script has finished then the normal linker +error message will be displayed. +</p> +<p>The availability of this option is controlled by a configure time +switch, so it may not be present in specific implementations. +</p> +<a name="index-_002d_002dno_002dundefined_002dversion"></a> +</dd> +<dt><code>--no-undefined-version</code></dt> +<dd><p>Normally when a symbol has an undefined version, the linker will ignore +it. This option disallows symbols with undefined version and a fatal error +will be issued instead. +</p> +<a name="index-_002d_002ddefault_002dsymver"></a> +</dd> +<dt><code>--default-symver</code></dt> +<dd><p>Create and use a default symbol version (the soname) for unversioned +exported symbols. +</p> +<a name="index-_002d_002ddefault_002dimported_002dsymver"></a> +</dd> +<dt><code>--default-imported-symver</code></dt> +<dd><p>Create and use a default symbol version (the soname) for unversioned +imported symbols. +</p> +<a name="index-_002d_002dno_002dwarn_002dmismatch"></a> +</dd> +<dt><code>--no-warn-mismatch</code></dt> +<dd><p>Normally <code>ld</code> will give an error if you try to link together input +files that are mismatched for some reason, perhaps because they have +been compiled for different processors or for different endiannesses. +This option tells <code>ld</code> that it should silently permit such possible +errors. This option should only be used with care, in cases when you +have taken some special action that ensures that the linker errors are +inappropriate. +</p> +<a name="index-_002d_002dno_002dwarn_002dsearch_002dmismatch"></a> +</dd> +<dt><code>--no-warn-search-mismatch</code></dt> +<dd><p>Normally <code>ld</code> will give a warning if it finds an incompatible +library during a library search. This option silences the warning. +</p> +<a name="index-_002d_002dno_002dwhole_002darchive"></a> +</dd> +<dt><code>--no-whole-archive</code></dt> +<dd><p>Turn off the effect of the <samp>--whole-archive</samp> option for subsequent +archive files. +</p> +<a name="index-output-file-after-errors"></a> +<a name="index-_002d_002dnoinhibit_002dexec"></a> +</dd> +<dt><code>--noinhibit-exec</code></dt> +<dd><p>Retain the executable output file whenever it is still usable. +Normally, the linker will not produce an output file if it encounters +errors during the link process; it exits without writing an output file +when it issues any error whatsoever. +</p> +<a name="index-_002dnostdlib"></a> +</dd> +<dt><code>-nostdlib</code></dt> +<dd><p>Only search library directories explicitly specified on the +command line. Library directories specified in linker scripts +(including linker scripts specified on the command line) are ignored. +</p> +<a name="index-_002d_002doformat_003doutput_002dformat"></a> +</dd> +<dt><code>--oformat=<var>output-format</var></code></dt> +<dd><p><code>ld</code> may be configured to support more than one kind of object +file. If your <code>ld</code> is configured this way, you can use the +‘<samp>--oformat</samp>’ option to specify the binary format for the output +object file. Even when <code>ld</code> is configured to support alternative +object formats, you don’t usually need to specify this, as <code>ld</code> +should be configured to produce as a default output format the most +usual format on each machine. <var>output-format</var> is a text string, the +name of a particular format supported by the BFD libraries. (You can +list the available binary formats with ‘<samp>objdump -i</samp>’.) The script +command <code>OUTPUT_FORMAT</code> can also specify the output format, but +this option overrides it. See <a href="#BFD">BFD</a>. +</p> +<a name="index-_002d_002dout_002dimplib"></a> +</dd> +<dt><code>--out-implib <var>file</var></code></dt> +<dd><p>Create an import library in <var>file</var> corresponding to the executable +the linker is generating (eg. a DLL or ELF program). This import +library (which should be called <code>*.dll.a</code> or <code>*.a</code> for DLLs) +may be used to link clients against the generated executable; this +behaviour makes it possible to skip a separate import library creation +step (eg. <code>dlltool</code> for DLLs). This option is only available for +the i386 PE and ELF targetted ports of the linker. +</p> +<a name="index-_002dpie"></a> +<a name="index-_002d_002dpic_002dexecutable"></a> +</dd> +<dt><code>-pie</code></dt> +<dt><code>--pic-executable</code></dt> +<dd><a name="index-position-independent-executables"></a> +<p>Create a position independent executable. This is currently only supported on +ELF platforms. Position independent executables are similar to shared +libraries in that they are relocated by the dynamic linker to the virtual +address the OS chooses for them (which can vary between invocations). Like +normal dynamically linked executables they can be executed and symbols +defined in the executable cannot be overridden by shared libraries. +</p> +<a name="index-_002dno_002dpie"></a> +</dd> +<dt><code>-no-pie</code></dt> +<dd><a name="index-position-dependent-executables"></a> +<p>Create a position dependent executable. This is the default. +</p> +<a name="index-_002dqmagic"></a> +</dd> +<dt><code>-qmagic</code></dt> +<dd><p>This option is ignored for Linux compatibility. +</p> +<a name="index-_002dQy"></a> +</dd> +<dt><code>-Qy</code></dt> +<dd><p>This option is ignored for SVR4 compatibility. +</p> +<a name="index-_002d_002drelax"></a> +<a name="index-synthesizing-linker"></a> +<a name="index-relaxing-addressing-modes"></a> +<a name="index-_002d_002dno_002drelax"></a> +</dd> +<dt><code>--relax</code></dt> +<dt><code>--no-relax</code></dt> +<dd><p>An option with machine dependent effects. +This option is only supported on a few targets. +See <a href="#H8_002f300"><code>ld</code> and the H8/300</a>. +See <a href="#Xtensa"><code>ld</code> and Xtensa Processors</a>. +See <a href="#M68HC11_002f68HC12"><code>ld</code> and the 68HC11 and 68HC12</a>. +See <a href="#Nios-II"><code>ld</code> and the Altera Nios II</a>. +See <a href="#PowerPC-ELF32"><code>ld</code> and PowerPC 32-bit ELF Support</a>. +</p> +<p>On some platforms the <samp>--relax</samp> option performs target specific, +global optimizations that become possible when the linker resolves +addressing in the program, such as relaxing address modes, +synthesizing new instructions, selecting shorter version of current +instructions, and combining constant values. +</p> +<p>On some platforms these link time global optimizations may make symbolic +debugging of the resulting executable impossible. +This is known to be the case for the Matsushita MN10200 and MN10300 +family of processors. +</p> +<p>On platforms where the feature is supported, the option +<samp>--no-relax</samp> will disable it. +</p> +<p>On platforms where the feature is not supported, both <samp>--relax</samp> +and <samp>--no-relax</samp> are accepted, but ignored. +</p> +<a name="index-retaining-specified-symbols"></a> +<a name="index-stripping-all-but-some-symbols"></a> +<a name="index-symbols_002c-retaining-selectively"></a> +<a name="index-_002d_002dretain_002dsymbols_002dfile_003dfilename"></a> +</dd> +<dt><code>--retain-symbols-file=<var>filename</var></code></dt> +<dd><p>Retain <em>only</em> the symbols listed in the file <var>filename</var>, +discarding all others. <var>filename</var> is simply a flat file, with one +symbol name per line. This option is especially useful in environments +(such as VxWorks) +where a large global symbol table is accumulated gradually, to conserve +run-time memory. +</p> +<p>‘<samp>--retain-symbols-file</samp>’ does <em>not</em> discard undefined symbols, +or symbols needed for relocations. +</p> +<p>You may only specify ‘<samp>--retain-symbols-file</samp>’ once in the command +line. It overrides ‘<samp>-s</samp>’ and ‘<samp>-S</samp>’. +</p> +</dd> +<dt><code>-rpath=<var>dir</var></code></dt> +<dd><a name="index-runtime-library-search-path"></a> +<a name="index-_002drpath_003ddir"></a> +<p>Add a directory to the runtime library search path. This is used when +linking an ELF executable with shared objects. All <samp>-rpath</samp> +arguments are concatenated and passed to the runtime linker, which uses +them to locate shared objects at runtime. +</p> +<p>The <samp>-rpath</samp> option is also used when locating shared objects which +are needed by shared objects explicitly included in the link; see the +description of the <samp>-rpath-link</samp> option. Searching <samp>-rpath</samp> +in this way is only supported by native linkers and cross linkers which +have been configured with the <samp>--with-sysroot</samp> option. +</p> +<p>If <samp>-rpath</samp> is not used when linking an ELF executable, the +contents of the environment variable <code>LD_RUN_PATH</code> will be used if it +is defined. +</p> +<p>The <samp>-rpath</samp> option may also be used on SunOS. By default, on +SunOS, the linker will form a runtime search path out of all the +<samp>-L</samp> options it is given. If a <samp>-rpath</samp> option is used, the +runtime search path will be formed exclusively using the <samp>-rpath</samp> +options, ignoring the <samp>-L</samp> options. This can be useful when using +gcc, which adds many <samp>-L</samp> options which may be on NFS mounted +file systems. +</p> +<p>For compatibility with other ELF linkers, if the <samp>-R</samp> option is +followed by a directory name, rather than a file name, it is treated as +the <samp>-rpath</samp> option. +</p> +<a name="index-link_002dtime-runtime-library-search-path"></a> +<a name="index-_002drpath_002dlink_003ddir"></a> +</dd> +<dt><code>-rpath-link=<var>dir</var></code></dt> +<dd><p>When using ELF or SunOS, one shared library may require another. This +happens when an <code>ld -shared</code> link includes a shared library as one +of the input files. +</p> +<p>When the linker encounters such a dependency when doing a non-shared, +non-relocatable link, it will automatically try to locate the required +shared library and include it in the link, if it is not included +explicitly. In such a case, the <samp>-rpath-link</samp> option +specifies the first set of directories to search. The +<samp>-rpath-link</samp> option may specify a sequence of directory names +either by specifying a list of names separated by colons, or by +appearing multiple times. +</p> +<p>The tokens <var>$ORIGIN</var> and <var>$LIB</var> can appear in these search +directories. They will be replaced by the full path to the directory +containing the program or shared object in the case of <var>$ORIGIN</var> +and either ‘<samp>lib</samp>’ - for 32-bit binaries - or ‘<samp>lib64</samp>’ - for +64-bit binaries - in the case of <var>$LIB</var>. +</p> +<p>The alternative form of these tokens - <var>${ORIGIN}</var> and +<var>${LIB}</var> can also be used. The token <var>$PLATFORM</var> is not +supported. +</p> +<p>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. +</p> +<p>The linker uses the following search paths to locate required shared +libraries: +</p> +<ol> +<li> Any directories specified by <samp>-rpath-link</samp> options. +</li><li> Any directories specified by <samp>-rpath</samp> options. The difference +between <samp>-rpath</samp> and <samp>-rpath-link</samp> is that directories +specified by <samp>-rpath</samp> options are included in the executable and +used at runtime, whereas the <samp>-rpath-link</samp> option is only effective +at link time. Searching <samp>-rpath</samp> in this way is only supported +by native linkers and cross linkers which have been configured with +the <samp>--with-sysroot</samp> option. +</li><li> On an ELF system, for native linkers, if the <samp>-rpath</samp> and +<samp>-rpath-link</samp> options were not used, search the contents of the +environment variable <code>LD_RUN_PATH</code>. +</li><li> On SunOS, if the <samp>-rpath</samp> option was not used, search any +directories specified using <samp>-L</samp> options. +</li><li> For a native linker, search the contents of the environment +variable <code>LD_LIBRARY_PATH</code>. +</li><li> For a native ELF linker, the directories in <code>DT_RUNPATH</code> or +<code>DT_RPATH</code> of a shared library are searched for shared +libraries needed by it. The <code>DT_RPATH</code> entries are ignored if +<code>DT_RUNPATH</code> entries exist. +</li><li> For a linker for a Linux system, if the file <samp>/etc/ld.so.conf</samp> +exists, the list of directories found in that file. Note: the path +to this file is prefixed with the <code>sysroot</code> value, if that is +defined, and then any <code>prefix</code> string if the linker was +configured with the <code>--prefix=<path></code> option. +</li><li> For a native linker on a FreeBSD system, any directories specified by +the <code>_PATH_ELF_HINTS</code> macro defined in the <samp>elf-hints.h</samp> +header file. +</li><li> Any directories specified by a <code>SEARCH_DIR</code> command in a +linker script given on the command line, including scripts specified +by <samp>-T</samp> (but not <samp>-dT</samp>). +</li><li> The default directories, normally <samp>/lib</samp> and <samp>/usr/lib</samp>. +</li><li> Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH. +</li><li> Any directories specified by a <code>SEARCH_DIR</code> command in a default +linker script. +</li></ol> + +<p>Note however on Linux based systems there is an additional caveat: If +the <samp>--as-needed</samp> option is active <em>and</em> a shared library +is located which would normally satisfy the search <em>and</em> this +library does not have DT_NEEDED tag for <samp>libc.so</samp> +<em>and</em> there is a shared library later on in the set of search +directories which also satisfies the search <em>and</em> +this second shared library does have a DT_NEEDED tag for +<samp>libc.so</samp> <em>then</em> the second library will be selected instead +of the first. +</p> +<p>If the required shared library is not found, the linker will issue a +warning and continue with the link. +</p> + +<a name="index-_002dshared"></a> +<a name="index-_002dBshareable"></a> +</dd> +<dt><code>-shared</code></dt> +<dt><code>-Bshareable</code></dt> +<dd><a name="index-shared-libraries"></a> +<p>Create a shared library. This is currently only supported on ELF, XCOFF +and SunOS platforms. On SunOS, the linker will automatically create a +shared library if the <samp>-e</samp> option is not used and there are +undefined symbols in the link. +</p> +<a name="index-_002d_002dsort_002dcommon"></a> +</dd> +<dt><code>--sort-common</code></dt> +<dt><code>--sort-common=ascending</code></dt> +<dt><code>--sort-common=descending</code></dt> +<dd><p>This option tells <code>ld</code> to sort the common symbols by alignment in +ascending or descending order when it places them in the appropriate output +sections. The symbol alignments considered are sixteen-byte or larger, +eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps +between symbols due to alignment constraints. If no sorting order is +specified, then descending order is assumed. +</p> +<a name="index-_002d_002dsort_002dsection_003dname"></a> +</dd> +<dt><code>--sort-section=name</code></dt> +<dd><p>This option will apply <code>SORT_BY_NAME</code> to all wildcard section +patterns in the linker script. +</p> +<a name="index-_002d_002dsort_002dsection_003dalignment"></a> +</dd> +<dt><code>--sort-section=alignment</code></dt> +<dd><p>This option will apply <code>SORT_BY_ALIGNMENT</code> to all wildcard section +patterns in the linker script. +</p> +<a name="index-_002d_002dspare_002ddynamic_002dtags"></a> +</dd> +<dt><code>--spare-dynamic-tags=<var>count</var></code></dt> +<dd><p>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. +</p> +<a name="index-_002d_002dsplit_002dby_002dfile"></a> +</dd> +<dt><code>--split-by-file[=<var>size</var>]</code></dt> +<dd><p>Similar to <samp>--split-by-reloc</samp> but creates a new output section for +each input file when <var>size</var> is reached. <var>size</var> defaults to a +size of 1 if not given. +</p> +<a name="index-_002d_002dsplit_002dby_002dreloc"></a> +</dd> +<dt><code>--split-by-reloc[=<var>count</var>]</code></dt> +<dd><p>Tries to creates extra sections in the output file so that no single +output section in the file contains more than <var>count</var> relocations. +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</var> relocations one output section will contain that +many relocations. <var>count</var> defaults to a value of 32768. +</p> +<a name="index-_002d_002dstats"></a> +</dd> +<dt><code>--stats</code></dt> +<dd><p>Compute and display statistics about the operation of the linker, such +as execution time and memory usage. +</p> +<a name="index-_002d_002dsysroot_003ddirectory"></a> +</dd> +<dt><code>--sysroot=<var>directory</var></code></dt> +<dd><p>Use <var>directory</var> as the location of the sysroot, overriding the +configure-time default. This option is only supported by linkers +that were configured using <samp>--with-sysroot</samp>. +</p> +<a name="index-_002d_002dtask_002dlink"></a> +</dd> +<dt><code>--task-link</code></dt> +<dd><p>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. +</p> +<a name="index-_002d_002dtraditional_002dformat"></a> +<a name="index-traditional-format"></a> +</dd> +<dt><code>--traditional-format</code></dt> +<dd><p>For some targets, the output of <code>ld</code> is different in some ways from +the output of some existing linker. This switch requests <code>ld</code> to +use the traditional format instead. +</p> +<a name="index-dbx"></a> +<p>For example, on SunOS, <code>ld</code> combines duplicate entries in the +symbol string table. This can reduce the size of an output file with +full debugging information by over 30 percent. Unfortunately, the SunOS +<code>dbx</code> program can not read the resulting program (<code>gdb</code> has no +trouble). The ‘<samp>--traditional-format</samp>’ switch tells <code>ld</code> to not +combine duplicate entries. +</p> +<a name="index-_002d_002dsection_002dstart_003dsectionname_003dorg"></a> +</dd> +<dt><code>--section-start=<var>sectionname</var>=<var>org</var></code></dt> +<dd><p>Locate a section in the output file at the absolute +address given by <var>org</var>. You may use this option as many +times as necessary to locate multiple sections in the command +line. +<var>org</var> must be a single hexadecimal integer; +for compatibility with other linkers, you may omit the leading +‘<samp>0x</samp>’ usually associated with hexadecimal values. <em>Note:</em> there +should be no white space between <var>sectionname</var>, the equals +sign (“<tt class="key">=</tt>”), and <var>org</var>. +</p> +<a name="index-_002dTbss_003dorg"></a> +<a name="index-_002dTdata_003dorg"></a> +<a name="index-_002dTtext_003dorg"></a> +<a name="index-segment-origins_002c-cmd-line"></a> +</dd> +<dt><code>-Tbss=<var>org</var></code></dt> +<dt><code>-Tdata=<var>org</var></code></dt> +<dt><code>-Ttext=<var>org</var></code></dt> +<dd><p>Same as <samp>--section-start</samp>, with <code>.bss</code>, <code>.data</code> or +<code>.text</code> as the <var>sectionname</var>. +</p> +<a name="index-_002dTtext_002dsegment_003dorg"></a> +</dd> +<dt><code>-Ttext-segment=<var>org</var></code></dt> +<dd><a name="index-text-segment-origin_002c-cmd-line"></a> +<p>When creating an ELF executable, it will set the address of the first +byte of the text segment. +</p> +<a name="index-_002dTrodata_002dsegment_003dorg"></a> +</dd> +<dt><code>-Trodata-segment=<var>org</var></code></dt> +<dd><a name="index-rodata-segment-origin_002c-cmd-line"></a> +<p>When creating an ELF executable or shared object for a target where +the read-only data is in its own segment separate from the executable +text, it will set the address of the first byte of the read-only data segment. +</p> +<a name="index-_002dTldata_002dsegment_003dorg"></a> +</dd> +<dt><code>-Tldata-segment=<var>org</var></code></dt> +<dd><a name="index-ldata-segment-origin_002c-cmd-line"></a> +<p>When creating an ELF executable or shared object for x86-64 medium memory +model, it will set the address of the first byte of the ldata segment. +</p> +<a name="index-_002d_002dunresolved_002dsymbols"></a> +</dd> +<dt><code>--unresolved-symbols=<var>method</var></code></dt> +<dd><p>Determine how to handle unresolved symbols. There are four possible +values for ‘<samp>method</samp>’: +</p> +<dl compact="compact"> +<dt>‘<samp>ignore-all</samp>’</dt> +<dd><p>Do not report any unresolved symbols. +</p> +</dd> +<dt>‘<samp>report-all</samp>’</dt> +<dd><p>Report all unresolved symbols. This is the default. +</p> +</dd> +<dt>‘<samp>ignore-in-object-files</samp>’</dt> +<dd><p>Report unresolved symbols that are contained in shared libraries, but +ignore them if they come from regular object files. +</p> +</dd> +<dt>‘<samp>ignore-in-shared-libs</samp>’</dt> +<dd><p>Report unresolved symbols that come from regular object files, but +ignore them if they come from shared libraries. This can be useful +when creating a dynamic binary and it is known that all the shared +libraries that it should be referencing are included on the linker’s +command line. +</p></dd> +</dl> + +<p>The behaviour for shared libraries on their own can also be controlled +by the <samp>--[no-]allow-shlib-undefined</samp> option. +</p> +<p>Normally the linker will generate an error message for each reported +unresolved symbol but the option <samp>--warn-unresolved-symbols</samp> +can change this to a warning. +</p> +<a name="index-_002d_002dverbose_005b_003dNUMBER_005d"></a> +<a name="index-verbose_005b_003dNUMBER_005d"></a> +</dd> +<dt><code>--dll-verbose</code></dt> +<dt><code>--verbose[=<var>NUMBER</var>]</code></dt> +<dd><p>Display the version number for <code>ld</code> and list the linker emulations +supported. Display which input files can and cannot be opened. Display +the linker script being used by the linker. If the optional <var>NUMBER</var> +argument > 1, plugin symbol status will also be displayed. +</p> +<a name="index-_002d_002dversion_002dscript_003dversion_002dscriptfile"></a> +<a name="index-version-script_002c-symbol-versions"></a> +</dd> +<dt><code>--version-script=<var>version-scriptfile</var></code></dt> +<dd><p>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 fully supported on ELF platforms which support shared libraries; +see <a href="#VERSION">VERSION</a>. 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</samp>’ in the version script will not be exported. +See <a href="#WIN32">WIN32</a>. +</p> +<a name="index-_002d_002dwarn_002dcommon"></a> +<a name="index-warnings_002c-on-combining-symbols"></a> +<a name="index-combining-symbols_002c-warnings-on"></a> +</dd> +<dt><code>--warn-common</code></dt> +<dd><p>Warn when a common symbol is combined with another common symbol or with +a symbol definition. Unix linkers allow this somewhat sloppy practice, +but linkers on some other operating systems do not. This option allows +you to find potential problems from combining global symbols. +Unfortunately, some C libraries use this practice, so you may get some +warnings about symbols in the libraries as well as in your programs. +</p> +<p>There are three kinds of global symbols, illustrated here by C examples: +</p> +<dl compact="compact"> +<dt>‘<samp>int i = 1;</samp>’</dt> +<dd><p>A definition, which goes in the initialized data section of the output +file. +</p> +</dd> +<dt>‘<samp>extern int i;</samp>’</dt> +<dd><p>An undefined reference, which does not allocate space. +There must be either a definition or a common symbol for the +variable somewhere. +</p> +</dd> +<dt>‘<samp>int i;</samp>’</dt> +<dd><p>A common symbol. If there are only (one or more) common symbols for a +variable, it goes in the uninitialized data area of the output file. +The linker merges multiple common symbols for the same variable into a +single symbol. If they are of different sizes, it picks the largest +size. The linker turns a common symbol into a declaration, if there is +a definition of the same variable. +</p></dd> +</dl> + +<p>The ‘<samp>--warn-common</samp>’ option can produce five kinds of warnings. +Each warning consists of a pair of lines: the first describes the symbol +just encountered, and the second describes the previous symbol +encountered with the same name. One or both of the two symbols will be +a common symbol. +</p> +<ol> +<li> Turning a common symbol into a reference, because there is already a +definition for the symbol. +<div class="smallexample"> +<pre class="smallexample"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>' + overridden by definition +<var>file</var>(<var>section</var>): warning: defined here +</pre></div> + +</li><li> Turning a common symbol into a reference, because a later definition for +the symbol is encountered. This is the same as the previous case, +except that the symbols are encountered in a different order. +<div class="smallexample"> +<pre class="smallexample"><var>file</var>(<var>section</var>): warning: definition of `<var>symbol</var>' + overriding common +<var>file</var>(<var>section</var>): warning: common is here +</pre></div> + +</li><li> Merging a common symbol with a previous same-sized common symbol. +<div class="smallexample"> +<pre class="smallexample"><var>file</var>(<var>section</var>): warning: multiple common + of `<var>symbol</var>' +<var>file</var>(<var>section</var>): warning: previous common is here +</pre></div> + +</li><li> Merging a common symbol with a previous larger common symbol. +<div class="smallexample"> +<pre class="smallexample"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>' + overridden by larger common +<var>file</var>(<var>section</var>): warning: larger common is here +</pre></div> + +</li><li> Merging a common symbol with a previous smaller common symbol. This is +the same as the previous case, except that the symbols are +encountered in a different order. +<div class="smallexample"> +<pre class="smallexample"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>' + overriding smaller common +<var>file</var>(<var>section</var>): warning: smaller common is here +</pre></div> +</li></ol> + +<a name="index-_002d_002dwarn_002dconstructors"></a> +</dd> +<dt><code>--warn-constructors</code></dt> +<dd><p>Warn if any global constructors are used. This is only useful for a few +object file formats. For formats like COFF or ELF, the linker can not +detect the use of global constructors. +</p> +<a name="index-_002d_002dwarn_002dexecstack"></a> +<a name="index-warnings_002c-on-executable-stack"></a> +<a name="index-executable-stack_002c-warnings-on"></a> +</dd> +<dt><code>--warn-execstack</code></dt> +<dt><code>--no-warn-execstack</code></dt> +<dd><p>On ELF platforms this option controls how the linker generates warning +messages when it creates an output file with an executable stack. By +default the linker will not warn if the <code>-z execstack</code> command +line option has been used, but this behaviour can be overridden by the +<samp>--warn-execstack</samp> option. +</p> +<p>On the other hand the linker will normally warn if the stack is made +executable because one or more of the input files need an execuable +stack and neither of the <code>-z execstack</code> or <code>-z +noexecstack</code> command line options have been specified. This warning +can be disabled via the <code>--no-warn-execstack</code> option. +</p> +<p>Note: ELF format input files specify that they need an executable +stack by having a <var>.note.GNU-stack</var> section with the executable +bit set in its section flags. They can specify that they do not need +an executable stack by having that section, but without the executable +flag bit set. If an input file does not have a <var>.note.GNU-stack</var> +section present then the default behaviour is target specific. For +some targets, then absence of such a section implies that an +executable stack <em>is</em> required. This is often a problem for hand +crafted assembler files. +</p> +<a name="index-_002d_002dwarn_002dmultiple_002dgp"></a> +</dd> +<dt><code>--warn-multiple-gp</code></dt> +<dd><p>Warn if multiple global pointer values are required in the output file. +This is only meaningful for certain processors, such as the Alpha. +Specifically, some processors put large-valued constants in a special +section. A special register (the global pointer) points into the middle +of this section, so that constants can be loaded efficiently via a +base-register relative addressing mode. Since the offset in +base-register relative mode is fixed and relatively small (e.g., 16 +bits), this limits the maximum size of the constant pool. Thus, in +large programs, it is often necessary to use multiple global pointer +values in order to be able to address all possible constants. This +option causes a warning to be issued whenever this case occurs. +</p> +<a name="index-_002d_002dwarn_002donce"></a> +<a name="index-warnings_002c-on-undefined-symbols"></a> +<a name="index-undefined-symbols_002c-warnings-on"></a> +</dd> +<dt><code>--warn-once</code></dt> +<dd><p>Only warn once for each undefined symbol, rather than once per module +which refers to it. +</p> +<a name="index-_002d_002dwarn_002drwx_002dsegments"></a> +<a name="index-warnings_002c-on-writeable-and-exectuable-segments"></a> +<a name="index-executable-segments_002c-warnings-on"></a> +</dd> +<dt><code>--warn-rwx-segments</code></dt> +<dt><code>--no-warn-rwx-segments</code></dt> +<dd><p>Warn if the linker creates a loadable, non-zero sized segment that has +all three of the read, write and execute permission flags set. Such a +segment represents a potential security vulnerability. In addition +warnings will be generated if a thread local storage segment is +created with the execute permission flag set, regardless of whether or +not it has the read and/or write flags set. +</p> +<p>These warnings are enabled by default. They can be disabled via the +<samp>--no-warn-rwx-segments</samp> option and re-enabled via the +<samp>--warn-rwx-segments</samp> option. +</p> +<a name="index-_002d_002dwarn_002dsection_002dalign"></a> +<a name="index-warnings_002c-on-section-alignment"></a> +<a name="index-section-alignment_002c-warnings-on"></a> +</dd> +<dt><code>--warn-section-align</code></dt> +<dd><p>Warn if the address of an output section is changed because of +alignment. Typically, the alignment will be set by an input section. +The address will only be changed if it not explicitly specified; that +is, if the <code>SECTIONS</code> command does not specify a start address for +the section (see <a href="#SECTIONS">SECTIONS</a>). +</p> +<a name="index-_002d_002dwarn_002dtextrel"></a> +</dd> +<dt><code>--warn-textrel</code></dt> +<dd><p>Warn if the linker adds DT_TEXTREL to a position-independent executable +or shared object. +</p> +<a name="index-_002d_002dwarn_002dalternate_002dem"></a> +</dd> +<dt><code>--warn-alternate-em</code></dt> +<dd><p>Warn if an object has alternate ELF machine code. +</p> +<a name="index-_002d_002dwarn_002dunresolved_002dsymbols"></a> +</dd> +<dt><code>--warn-unresolved-symbols</code></dt> +<dd><p>If the linker is going to report an unresolved symbol (see the option +<samp>--unresolved-symbols</samp>) it will normally generate an error. +This option makes it generate a warning instead. +</p> +<a name="index-_002d_002derror_002dunresolved_002dsymbols"></a> +</dd> +<dt><code>--error-unresolved-symbols</code></dt> +<dd><p>This restores the linker’s default behaviour of generating errors when +it is reporting unresolved symbols. +</p> +<a name="index-_002d_002dwhole_002darchive"></a> +<a name="index-including-an-entire-archive"></a> +</dd> +<dt><code>--whole-archive</code></dt> +<dd><p>For each archive mentioned on the command line after the +<samp>--whole-archive</samp> option, include every object file in the archive +in the link, rather than searching the archive for the required object +files. This is normally used to turn an archive file into a shared +library, forcing every object to be included in the resulting shared +library. This option may be used more than once. +</p> +<p>Two notes when using this option from gcc: First, gcc doesn’t know +about this option, so you have to use <samp>-Wl,-whole-archive</samp>. +Second, don’t forget to use <samp>-Wl,-no-whole-archive</samp> after your +list of archives, because gcc will add its own list of archives to +your link and you may not want this flag to affect those as well. +</p> +<a name="index-_002d_002dwrap_003dsymbol"></a> +</dd> +<dt><code>--wrap=<var>symbol</var></code></dt> +<dd><p>Use a wrapper function for <var>symbol</var>. Any undefined reference to +<var>symbol</var> will be resolved to <code>__wrap_<var>symbol</var></code>. Any +undefined reference to <code>__real_<var>symbol</var></code> will be resolved to +<var>symbol</var>. +</p> +<p>This can be used to provide a wrapper for a system function. The +wrapper function should be called <code>__wrap_<var>symbol</var></code>. If it +wishes to call the system function, it should call +<code>__real_<var>symbol</var></code>. +</p> +<p>Here is a trivial example: +</p> +<div class="smallexample"> +<pre class="smallexample">void * +__wrap_malloc (size_t c) +{ + printf ("malloc called with %zu\n", c); + return __real_malloc (c); +} +</pre></div> + +<p>If you link other code with this file using <samp>--wrap malloc</samp>, then +all calls to <code>malloc</code> will call the function <code>__wrap_malloc</code> +instead. The call to <code>__real_malloc</code> in <code>__wrap_malloc</code> will +call the real <code>malloc</code> function. +</p> +<p>You may wish to provide a <code>__real_malloc</code> function as well, so that +links without the <samp>--wrap</samp> option will succeed. If you do this, +you should not put the definition of <code>__real_malloc</code> in the same +file as <code>__wrap_malloc</code>; if you do, the assembler may resolve the +call before the linker has a chance to wrap it to <code>malloc</code>. +</p> +<p>Only undefined references are replaced by the linker. So, translation unit +internal references to <var>symbol</var> are not resolved to +<code>__wrap_<var>symbol</var></code>. In the next example, the call to <code>f</code> in +<code>g</code> is not resolved to <code>__wrap_f</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">int +f (void) +{ + return 123; +} + +int +g (void) +{ + return f(); +} +</pre></div> + +<a name="index-_002d_002deh_002dframe_002dhdr"></a> +<a name="index-_002d_002dno_002deh_002dframe_002dhdr"></a> +</dd> +<dt><code>--eh-frame-hdr</code></dt> +<dt><code>--no-eh-frame-hdr</code></dt> +<dd><p>Request (<samp>--eh-frame-hdr</samp>) or suppress +(<samp>--no-eh-frame-hdr</samp>) the creation of <code>.eh_frame_hdr</code> +section and ELF <code>PT_GNU_EH_FRAME</code> segment header. +</p> +<a name="index-_002d_002dld_002dgenerated_002dunwind_002dinfo"></a> +</dd> +<dt><code>--no-ld-generated-unwind-info</code></dt> +<dd><p>Request creation of <code>.eh_frame</code> unwind info for linker +generated code sections like PLT. This option is on by default +if linker generated unwind info is supported. This option also +controls the generation of <code>.sframe</code> stack trace info for linker +generated code sections like PLT. +</p> +<a name="index-_002d_002denable_002dnew_002ddtags"></a> +<a name="index-_002d_002ddisable_002dnew_002ddtags"></a> +</dd> +<dt><code>--enable-new-dtags</code></dt> +<dt><code>--disable-new-dtags</code></dt> +<dd><p>This linker can create the new dynamic tags in ELF. But the older ELF +systems may not understand them. If you specify +<samp>--enable-new-dtags</samp>, the new dynamic tags will be created as needed +and older dynamic tags will be omitted. +If you specify <samp>--disable-new-dtags</samp>, 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. +</p> +<a name="index-_002d_002dhash_002dsize_003dnumber"></a> +</dd> +<dt><code>--hash-size=<var>number</var></code></dt> +<dd><p>Set the default size of the linker’s hash tables to a prime number +close to <var>number</var>. Increasing this value can reduce the length of +time it takes the linker to perform its tasks, at the expense of +increasing the linker’s memory requirements. Similarly reducing this +value can reduce the memory requirements at the expense of speed. +</p> +<a name="index-_002d_002dhash_002dstyle_003dstyle"></a> +</dd> +<dt><code>--hash-style=<var>style</var></code></dt> +<dd><p>Set the type of linker’s hash table(s). <var>style</var> can be either +<code>sysv</code> for classic ELF <code>.hash</code> section, <code>gnu</code> for +new style GNU <code>.gnu.hash</code> section or <code>both</code> for both +the classic ELF <code>.hash</code> and new style GNU <code>.gnu.hash</code> +hash tables. The default depends upon how the linker was configured, +but for most Linux based systems it will be <code>both</code>. +</p> +<a name="index-_002d_002dcompress_002ddebug_002dsections_003dnone"></a> +<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzlib"></a> +<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgnu"></a> +<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgabi"></a> +<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzstd"></a> +</dd> +<dt><code>--compress-debug-sections=none</code></dt> +<dt><code>--compress-debug-sections=zlib</code></dt> +<dt><code>--compress-debug-sections=zlib-gnu</code></dt> +<dt><code>--compress-debug-sections=zlib-gabi</code></dt> +<dt><code>--compress-debug-sections=zstd</code></dt> +<dd><p>On ELF platforms, these options control how DWARF debug sections are +compressed using zlib. +</p> +<p><samp>--compress-debug-sections=none</samp> doesn’t compress DWARF debug +sections. <samp>--compress-debug-sections=zlib-gnu</samp> compresses +DWARF debug sections and renames them to begin with ‘<samp>.zdebug</samp>’ +instead of ‘<samp>.debug</samp>’. <samp>--compress-debug-sections=zlib-gabi</samp> +also compresses DWARF debug sections, but rather than renaming them it +sets the SHF_COMPRESSED flag in the sections’ headers. +</p> +<p>The <samp>--compress-debug-sections=zlib</samp> option is an alias for +<samp>--compress-debug-sections=zlib-gabi</samp>. +</p> +<p><samp>--compress-debug-sections=zstd</samp> compresses DWARF debug sections using +zstd. +</p> +<p>Note that this option overrides any compression in input debug +sections, so if a binary is linked with <samp>--compress-debug-sections=none</samp> +for example, then any compressed debug sections in input files will be +uncompressed before they are copied into the output binary. +</p> +<p>The default compression behaviour varies depending upon the target +involved and the configure options used to build the toolchain. The +default can be determined by examining the output from the linker’s +<samp>--help</samp> option. +</p> +<a name="index-_002d_002dreduce_002dmemory_002doverheads"></a> +</dd> +<dt><code>--reduce-memory-overheads</code></dt> +<dd><p>This option reduces memory requirements at ld runtime, at the expense of +linking speed. This was introduced to select the old O(n^2) algorithm +for link map file generation, rather than the new O(n) algorithm which uses +about 40% more memory for symbol storage. +</p> +<p>Another effect of the switch is to set the default hash table size to +1021, which again saves memory at the cost of lengthening the linker’s +run time. This is not done however if the <samp>--hash-size</samp> switch +has been used. +</p> +<p>The <samp>--reduce-memory-overheads</samp> switch may be also be used to +enable other tradeoffs in future versions of the linker. +</p> +<a name="index-_002d_002dmax_002dcache_002dsize_003dsize"></a> +</dd> +<dt><code>--max-cache-size=<var>size</var></code></dt> +<dd><p><code>ld</code> normally caches the relocation information and symbol tables +of input files in memory with the unlimited size. This option sets the +maximum cache size to <var>size</var>. +</p> +<a name="index-_002d_002dbuild_002did"></a> +<a name="index-_002d_002dbuild_002did_003dstyle"></a> +</dd> +<dt><code>--build-id</code></dt> +<dt><code>--build-id=<var>style</var></code></dt> +<dd><p>Request the creation of a <code>.note.gnu.build-id</code> ELF note section +or a <code>.buildid</code> COFF section. The contents of the note are +unique bits identifying this linked file. <var>style</var> can be +<code>uuid</code> to use 128 random bits, <code>sha1</code> to use a 160-bit +<small>SHA1</small> hash on the normative parts of the output contents, +<code>md5</code> to use a 128-bit <small>MD5</small> hash on the normative parts of +the output contents, or <code>0x<var>hexstring</var></code> to use a chosen bit +string specified as an even number of hexadecimal digits (<code>-</code> and +<code>:</code> characters between digit pairs are ignored). If <var>style</var> +is omitted, <code>sha1</code> is used. +</p> +<p>The <code>md5</code> and <code>sha1</code> styles produces an identifier +that is always the same in an identical output file, but will be +unique among all nonidentical output files. It is not intended +to be compared as a checksum for the file’s contents. A linked +file may be changed later by other tools, but the build ID bit +string identifying the original linked file does not change. +</p> +<p>Passing <code>none</code> for <var>style</var> disables the setting from any +<code>--build-id</code> options earlier on the command line. +</p> +<a name="index-_002d_002dpackage_002dmetadata_003dJSON"></a> +</dd> +<dt><code>--package-metadata=<var>JSON</var></code></dt> +<dd><p>Request the creation of a <code>.note.package</code> ELF note section. The +contents of the note are in JSON format, as per the package metadata +specification. For more information see: +https://systemd.io/ELF_PACKAGE_METADATA/ +If the JSON argument is missing/empty then this will disable the +creation of the metadata note, if one had been enabled by an earlier +occurrence of the –package-metdata option. +If the linker has been built with libjansson, then the JSON string +will be validated. +</p></dd> +</dl> + + +<a name="Options-Specific-to-i386-PE-Targets"></a> +<h4 class="subsection">2.1.1 Options Specific to i386 PE Targets</h4> + + +<p>The i386 PE linker supports the <samp>-shared</samp> option, which causes +the output to be a dynamically linked library (DLL) instead of a +normal executable. You should name the output <code>*.dll</code> when you +use this option. In addition, the linker fully supports the standard +<code>*.def</code> files, which may be specified on the linker command line +like an object file (in fact, it should precede archives it exports +symbols from, to ensure that they get linked in, just like a normal +object file). +</p> +<p>In addition to the options common to all targets, the i386 PE linker +support additional command-line options that are specific to the i386 +PE target. Options that take values may be separated from their +values by either a space or an equals sign. +</p> +<dl compact="compact"> +<dd> +<a name="index-_002d_002dadd_002dstdcall_002dalias"></a> +</dd> +<dt><code>--add-stdcall-alias</code></dt> +<dd><p>If given, symbols with a stdcall suffix (@<var>nn</var>) will be exported +as-is and also with the suffix stripped. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dbase_002dfile"></a> +</dd> +<dt><code>--base-file <var>file</var></code></dt> +<dd><p>Use <var>file</var> as the name of a file in which to save the base +addresses of all the relocations needed for generating DLLs with +<samp>dlltool</samp>. +[This is an i386 PE specific option] +</p> +<a name="index-_002d_002ddll"></a> +</dd> +<dt><code>--dll</code></dt> +<dd><p>Create a DLL instead of a regular executable. You may also use +<samp>-shared</samp> or specify a <code>LIBRARY</code> in a given <code>.def</code> +file. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002denable_002dlong_002dsection_002dnames"></a> +<a name="index-_002d_002ddisable_002dlong_002dsection_002dnames"></a> +</dd> +<dt><code>--enable-long-section-names</code></dt> +<dt><code>--disable-long-section-names</code></dt> +<dd><p>The PE variants of the COFF object format add an extension that permits +the use of section names longer than eight characters, the normal limit +for COFF. By default, these names are only allowed in object files, as +fully-linked executable images do not carry the COFF string table required +to support the longer names. As a GNU extension, it is possible to +allow their use in executable images as well, or to (probably pointlessly!) +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. 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, <code>ld</code> 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] +</p> +<a name="index-_002d_002denable_002dstdcall_002dfixup"></a> +<a name="index-_002d_002ddisable_002dstdcall_002dfixup"></a> +</dd> +<dt><code>--enable-stdcall-fixup</code></dt> +<dt><code>--disable-stdcall-fixup</code></dt> +<dd><p>If the link finds a symbol that it cannot resolve, it will attempt to +do “fuzzy linking” by looking for another defined symbol that differs +only in the format of the symbol name (cdecl vs stdcall) and will +resolve that symbol by linking to the match. For example, the +undefined symbol <code>_foo</code> might be linked to the function +<code>_foo@12</code>, or the undefined symbol <code>_bar@16</code> might be linked +to the function <code>_bar</code>. When the linker does this, it prints a +warning, since it normally should have failed to link, but sometimes +import libraries generated from third-party dlls may need this feature +to be usable. If you specify <samp>--enable-stdcall-fixup</samp>, this +feature is fully enabled and warnings are not printed. If you specify +<samp>--disable-stdcall-fixup</samp>, this feature is disabled and such +mismatches are considered to be errors. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dleading_002dunderscore"></a> +<a name="index-_002d_002dno_002dleading_002dunderscore"></a> +</dd> +<dt><code>--leading-underscore</code></dt> +<dt><code>--no-leading-underscore</code></dt> +<dd><p>For most targets default symbol-prefix is an underscore and is defined +in target’s description. By this option it is possible to +disable/enable the default underscore symbol-prefix. +</p> +<a name="index-DLLs_002c-creating"></a> +<a name="index-_002d_002dexport_002dall_002dsymbols"></a> +</dd> +<dt><code>--export-all-symbols</code></dt> +<dd><p>If given, all global symbols in the objects used to build a DLL will +be exported by the DLL. Note that this is the default if there +otherwise wouldn’t be any exported symbols. When symbols are +explicitly exported via DEF files or implicitly exported via function +attributes, the default is to not export anything else unless this +option is given. Note that the symbols <code>DllMain@12</code>, +<code>DllEntryPoint@0</code>, <code>DllMainCRTStartup@12</code>, and +<code>impure_ptr</code> will not be automatically +exported. Also, symbols imported from other DLLs will not be +re-exported, nor will symbols specifying the DLL’s internal layout +such as those beginning with <code>_head_</code> or ending with +<code>_iname</code>. In addition, no symbols from <code>libgcc</code>, +<code>libstd++</code>, <code>libmingw32</code>, or <code>crtX.o</code> will be exported. +Symbols whose names begin with <code>__rtti_</code> or <code>__builtin_</code> will +not be exported, to help with C++ DLLs. Finally, there is an +extensive list of cygwin-private symbols that are not exported +(obviously, this applies on when building DLLs for cygwin targets). +These cygwin-excludes are: <code>_cygwin_dll_entry@12</code>, +<code>_cygwin_crt0_common@8</code>, <code>_cygwin_noncygwin_dll_entry@12</code>, +<code>_fmode</code>, <code>_impure_ptr</code>, <code>cygwin_attach_dll</code>, +<code>cygwin_premain0</code>, <code>cygwin_premain1</code>, <code>cygwin_premain2</code>, +<code>cygwin_premain3</code>, and <code>environ</code>. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dexclude_002dsymbols"></a> +</dd> +<dt><code>--exclude-symbols <var>symbol</var>,<var>symbol</var>,...</code></dt> +<dd><p>Specifies a list of symbols which should not be automatically +exported. The symbol names may be delimited by commas or colons. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dexclude_002dall_002dsymbols"></a> +</dd> +<dt><code>--exclude-all-symbols</code></dt> +<dd><p>Specifies no symbols should be automatically exported. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dfile_002dalignment"></a> +</dd> +<dt><code>--file-alignment</code></dt> +<dd><p>Specify the file alignment. Sections in the file will always begin at +file offsets which are multiples of this number. This defaults to +512. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-heap-size"></a> +<a name="index-_002d_002dheap"></a> +</dd> +<dt><code>--heap <var>reserve</var></code></dt> +<dt><code>--heap <var>reserve</var>,<var>commit</var></code></dt> +<dd><p>Specify the number of bytes of memory to reserve (and optionally commit) +to be used as heap for this program. The default is 1MB reserved, 4K +committed. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-image-base"></a> +<a name="index-_002d_002dimage_002dbase"></a> +</dd> +<dt><code>--image-base <var>value</var></code></dt> +<dd><p>Use <var>value</var> as the base address of your program or dll. This is +the lowest memory location that will be used when your program or dll +is loaded. To reduce the need to relocate and improve performance of +your dlls, each should have a unique base address and not overlap any +other dlls. The default is 0x400000 for executables, and 0x10000000 +for dlls. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dkill_002dat"></a> +</dd> +<dt><code>--kill-at</code></dt> +<dd><p>If given, the stdcall suffixes (@<var>nn</var>) will be stripped from +symbols before they are exported. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dlarge_002daddress_002daware"></a> +</dd> +<dt><code>--large-address-aware</code></dt> +<dd><p>If given, the appropriate bit in the “Characteristics” field of the COFF +header is set to indicate that this executable supports virtual addresses +greater than 2 gigabytes. This should be used in conjunction with the /3GB +or /USERVA=<var>value</var> megabytes switch in the “[operating systems]” +section of the BOOT.INI. Otherwise, this bit has no effect. +[This option is specific to PE targeted ports of the linker] +</p> +<a name="index-_002d_002ddisable_002dlarge_002daddress_002daware"></a> +</dd> +<dt><code>--disable-large-address-aware</code></dt> +<dd><p>Reverts the effect of a previous ‘<samp>--large-address-aware</samp>’ option. +This is useful if ‘<samp>--large-address-aware</samp>’ is always set by the compiler +driver (e.g. Cygwin gcc) and the executable does not support virtual +addresses greater than 2 gigabytes. +[This option is specific to PE targeted ports of the linker] +</p> +<a name="index-_002d_002dmajor_002dimage_002dversion"></a> +</dd> +<dt><code>--major-image-version <var>value</var></code></dt> +<dd><p>Sets the major number of the “image version”. Defaults to 1. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dmajor_002dos_002dversion"></a> +</dd> +<dt><code>--major-os-version <var>value</var></code></dt> +<dd><p>Sets the major number of the “os version”. Defaults to 4. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dmajor_002dsubsystem_002dversion"></a> +</dd> +<dt><code>--major-subsystem-version <var>value</var></code></dt> +<dd><p>Sets the major number of the “subsystem version”. Defaults to 4. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dminor_002dimage_002dversion"></a> +</dd> +<dt><code>--minor-image-version <var>value</var></code></dt> +<dd><p>Sets the minor number of the “image version”. Defaults to 0. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dminor_002dos_002dversion"></a> +</dd> +<dt><code>--minor-os-version <var>value</var></code></dt> +<dd><p>Sets the minor number of the “os version”. Defaults to 0. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dminor_002dsubsystem_002dversion"></a> +</dd> +<dt><code>--minor-subsystem-version <var>value</var></code></dt> +<dd><p>Sets the minor number of the “subsystem version”. Defaults to 0. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-DEF-files_002c-creating"></a> +<a name="index-DLLs_002c-creating-1"></a> +<a name="index-_002d_002doutput_002ddef"></a> +</dd> +<dt><code>--output-def <var>file</var></code></dt> +<dd><p>The linker will create the file <var>file</var> which will contain a DEF +file corresponding to the DLL the linker is generating. This DEF file +(which should be called <code>*.def</code>) may be used to create an import +library with <code>dlltool</code> or may be used as a reference to +automatically or implicitly exported symbols. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-DLLs_002c-creating-2"></a> +<a name="index-_002d_002denable_002dauto_002dimage_002dbase"></a> +</dd> +<dt><code>--enable-auto-image-base</code></dt> +<dt><code>--enable-auto-image-base=<var>value</var></code></dt> +<dd><p>Automatically choose the image base for DLLs, optionally starting with base +<var>value</var>, unless one is specified using the <code>--image-base</code> argument. +By using a hash generated from the dllname to create unique image bases +for each DLL, in-memory collisions and relocations which can delay program +execution are avoided. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002ddisable_002dauto_002dimage_002dbase"></a> +</dd> +<dt><code>--disable-auto-image-base</code></dt> +<dd><p>Do not automatically generate a unique image base. If there is no +user-specified image base (<code>--image-base</code>) then use the platform +default. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-DLLs_002c-linking-to"></a> +<a name="index-_002d_002ddll_002dsearch_002dprefix"></a> +</dd> +<dt><code>--dll-search-prefix <var>string</var></code></dt> +<dd><p>When linking dynamically to a dll without an import library, +search for <code><string><basename>.dll</code> in preference to +<code>lib<basename>.dll</code>. This behaviour allows easy distinction +between DLLs built for the various "subplatforms": native, cygwin, +uwin, pw, etc. For instance, cygwin DLLs typically use +<code>--dll-search-prefix=cyg</code>. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002denable_002dauto_002dimport"></a> +</dd> +<dt><code>--enable-auto-import</code></dt> +<dd><p>Do sophisticated linking of <code>_symbol</code> to <code>__imp__symbol</code> for +DATA imports from DLLs, thus making it possible to bypass the dllimport +mechanism on the user side and to reference unmangled symbol names. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<p>The following remarks pertain to the original implementation of the +feature and are obsolete nowadays for Cygwin and MinGW targets. +</p> +<p>Note: Use of the ’auto-import’ extension will cause the text section +of the image file to be made writable. This does not conform to the +PE-COFF format specification published by Microsoft. +</p> +<p>Note - use of the ’auto-import’ extension will also cause read only +data which would normally be placed into the .rdata section to be +placed into the .data section instead. This is in order to work +around a problem with consts that is described here: +http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html +</p> +<p>Using ’auto-import’ generally will ’just work’ – but sometimes you may +see this message: +</p> +<p>"variable ’<var>’ can’t be auto-imported. Please read the +documentation for ld’s <code>--enable-auto-import</code> for details." +</p> +<p>This message occurs when some (sub)expression accesses an address +ultimately given by the sum of two constants (Win32 import tables only +allow one). Instances where this may occur include accesses to member +fields of struct variables imported from a DLL, as well as using a +constant index into an array variable imported from a DLL. Any +multiword variable (arrays, structs, long long, etc) may trigger +this error condition. However, regardless of the exact data type +of the offending exported variable, ld will always detect it, issue +the warning, and exit. +</p> +<p>There are several ways to address this difficulty, regardless of the +data type of the exported variable: +</p> +<p>One way is to use –enable-runtime-pseudo-reloc switch. This leaves the task +of adjusting references in your client code for runtime environment, so +this method works only when runtime environment supports this feature. +</p> +<p>A second solution is to force one of the ’constants’ to be a variable – +that is, unknown and un-optimizable at compile time. For arrays, +there are two possibilities: a) make the indexee (the array’s address) +a variable, or b) make the ’constant’ index a variable. Thus: +</p> +<div class="example"> +<pre class="example">extern type extern_array[]; +extern_array[1] --> + { volatile type *t=extern_array; t[1] } +</pre></div> + +<p>or +</p> +<div class="example"> +<pre class="example">extern type extern_array[]; +extern_array[1] --> + { volatile int t=1; extern_array[t] } +</pre></div> + +<p>For structs (and most other multiword data types) the only option +is to make the struct itself (or the long long, or the ...) variable: +</p> +<div class="example"> +<pre class="example">extern struct s extern_struct; +extern_struct.field --> + { volatile struct s *t=&extern_struct; t->field } +</pre></div> + +<p>or +</p> +<div class="example"> +<pre class="example">extern long long extern_ll; +extern_ll --> + { volatile long long * local_ll=&extern_ll; *local_ll } +</pre></div> + +<p>A third method of dealing with this difficulty is to abandon +’auto-import’ for the offending symbol and mark it with +<code>__declspec(dllimport)</code>. However, in practice that +requires using compile-time #defines to indicate whether you are +building a DLL, building client code that will link to the DLL, or +merely building/linking to a static library. In making the choice +between the various methods of resolving the ’direct address with +constant offset’ problem, you should consider typical real-world usage: +</p> +<p>Original: +</p><div class="example"> +<pre class="example">--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\n",arr[1]); +} +</pre></div> + +<p>Solution 1: +</p><div class="example"> +<pre class="example">--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + /* This workaround is for win32 and cygwin; do not "optimize" */ + volatile int *parr = arr; + printf("%d\n",parr[1]); +} +</pre></div> + +<p>Solution 2: +</p><div class="example"> +<pre class="example">--foo.h +/* Note: auto-export is assumed (no __declspec(dllexport)) */ +#if (defined(_WIN32) || defined(__CYGWIN__)) && \ + !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) +#define FOO_IMPORT __declspec(dllimport) +#else +#define FOO_IMPORT +#endif +extern FOO_IMPORT int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\n",arr[1]); +} +</pre></div> + +<p>A fourth way to avoid this problem is to re-code your +library to use a functional interface rather than a data interface +for the offending variables (e.g. set_foo() and get_foo() accessor +functions). +</p> +<a name="index-_002d_002ddisable_002dauto_002dimport"></a> +</dd> +<dt><code>--disable-auto-import</code></dt> +<dd><p>Do not attempt to do sophisticated linking of <code>_symbol</code> to +<code>__imp__symbol</code> for DATA imports from DLLs. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002denable_002druntime_002dpseudo_002dreloc"></a> +</dd> +<dt><code>--enable-runtime-pseudo-reloc</code></dt> +<dd><p>If your code contains expressions described in –enable-auto-import section, +that is, DATA imports from DLL with non-zero offset, this switch will create +a vector of ’runtime pseudo relocations’ which can be used by runtime +environment to adjust references to such data in your client code. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002ddisable_002druntime_002dpseudo_002dreloc"></a> +</dd> +<dt><code>--disable-runtime-pseudo-reloc</code></dt> +<dd><p>Do not create pseudo relocations for non-zero offset DATA imports from DLLs. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002denable_002dextra_002dpe_002ddebug"></a> +</dd> +<dt><code>--enable-extra-pe-debug</code></dt> +<dd><p>Show additional debug info related to auto-import symbol thunking. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dsection_002dalignment"></a> +</dd> +<dt><code>--section-alignment</code></dt> +<dd><p>Sets the section alignment. Sections in memory will always begin at +addresses which are a multiple of this number. Defaults to 0x1000. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-stack-size"></a> +<a name="index-_002d_002dstack"></a> +</dd> +<dt><code>--stack <var>reserve</var></code></dt> +<dt><code>--stack <var>reserve</var>,<var>commit</var></code></dt> +<dd><p>Specify the number of bytes of memory to reserve (and optionally commit) +to be used as stack for this program. The default is 2MB reserved, 4K +committed. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<a name="index-_002d_002dsubsystem"></a> +</dd> +<dt><code>--subsystem <var>which</var></code></dt> +<dt><code>--subsystem <var>which</var>:<var>major</var></code></dt> +<dt><code>--subsystem <var>which</var>:<var>major</var>.<var>minor</var></code></dt> +<dd><p>Specifies the subsystem under which your program will execute. The +legal values for <var>which</var> are <code>native</code>, <code>windows</code>, +<code>console</code>, <code>posix</code>, and <code>xbox</code>. You may optionally set +the subsystem version also. Numeric values are also accepted for +<var>which</var>. +[This option is specific to the i386 PE targeted port of the linker] +</p> +<p>The following options set flags in the <code>DllCharacteristics</code> field +of the PE file header: +[These options are specific to PE targeted ports of the linker] +</p> +<a name="index-_002d_002dhigh_002dentropy_002dva"></a> +</dd> +<dt><code>--high-entropy-va</code></dt> +<dt><code>--disable-high-entropy-va</code></dt> +<dd><p>Image is compatible with 64-bit address space layout randomization +(ASLR). This option is enabled by default for 64-bit PE images. +</p> +<p>This option also implies <samp>--dynamicbase</samp> and +<samp>--enable-reloc-section</samp>. +</p> +<a name="index-_002d_002ddynamicbase"></a> +</dd> +<dt><code>--dynamicbase</code></dt> +<dt><code>--disable-dynamicbase</code></dt> +<dd><p>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 <samp>--disable-dynamicbase</samp> option. +This option also implies <samp>--enable-reloc-section</samp>. +</p> +<a name="index-_002d_002dforceinteg"></a> +</dd> +<dt><code>--forceinteg</code></dt> +<dt><code>--disable-forceinteg</code></dt> +<dd><p>Code integrity checks are enforced. This option is disabled by +default. +</p> +<a name="index-_002d_002dnxcompat"></a> +</dd> +<dt><code>--nxcompat</code></dt> +<dt><code>--disable-nxcompat</code></dt> +<dd><p>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. +</p> +<a name="index-_002d_002dno_002disolation"></a> +</dd> +<dt><code>--no-isolation</code></dt> +<dt><code>--disable-no-isolation</code></dt> +<dd><p>Although the image understands isolation, do not isolate the image. +This option is disabled by default. +</p> +<a name="index-_002d_002dno_002dseh"></a> +</dd> +<dt><code>--no-seh</code></dt> +<dt><code>--disable-no-seh</code></dt> +<dd><p>The image does not use SEH. No SE handler may be called from +this image. This option is disabled by default. +</p> +<a name="index-_002d_002dno_002dbind"></a> +</dd> +<dt><code>--no-bind</code></dt> +<dt><code>--disable-no-bind</code></dt> +<dd><p>Do not bind this image. This option is disabled by default. +</p> +<a name="index-_002d_002dwdmdriver"></a> +</dd> +<dt><code>--wdmdriver</code></dt> +<dt><code>--disable-wdmdriver</code></dt> +<dd><p>The driver uses the MS Windows Driver Model. This option is disabled +by default. +</p> +<a name="index-_002d_002dtsaware"></a> +</dd> +<dt><code>--tsaware</code></dt> +<dt><code>--disable-tsaware</code></dt> +<dd><p>The image is Terminal Server aware. This option is disabled by +default. +</p> +<a name="index-_002d_002dinsert_002dtimestamp"></a> +</dd> +<dt><code>--insert-timestamp</code></dt> +<dt><code>--no-insert-timestamp</code></dt> +<dd><p>Insert a real timestamp into the image. This is the default behaviour +as it matches legacy code and it means that the image will work with +other, proprietary tools. The problem with this default is that it +will result in slightly different images being produced each time the +same sources are linked. The option <samp>--no-insert-timestamp</samp> +can be used to insert a zero value for the timestamp, this ensuring +that binaries produced from identical sources will compare +identically. +</p> +<a name="index-_002d_002denable_002dreloc_002dsection"></a> +</dd> +<dt><code>--enable-reloc-section</code></dt> +<dt><code>--disable-reloc-section</code></dt> +<dd><p>Create the base relocation table, which is necessary if the image +is loaded at a different image base than specified in the PE header. +This option is enabled by default. +</p></dd> +</dl> + + +<a name="Options-specific-to-C6X-uClinux-targets"></a> +<h4 class="subsection">2.1.2 Options specific to C6X uClinux targets</h4> + + +<p>The C6X uClinux target uses a binary format called DSBT to support shared +libraries. Each shared library in the system needs to have a unique index; +all executables use an index of 0. +</p> +<dl compact="compact"> +<dd> +<a name="index-_002d_002ddsbt_002dsize"></a> +</dd> +<dt><code>--dsbt-size <var>size</var></code></dt> +<dd><p>This option sets the number of entries in the DSBT of the current executable +or shared library to <var>size</var>. The default is to create a table with 64 +entries. +</p> +<a name="index-_002d_002ddsbt_002dindex"></a> +</dd> +<dt><code>--dsbt-index <var>index</var></code></dt> +<dd><p>This option sets the DSBT index of the current executable or shared library +to <var>index</var>. The default is 0, which is appropriate for generating +executables. If a shared library is generated with a DSBT index of 0, the +<code>R_C6000_DSBT_INDEX</code> relocs are copied into the output file. +</p> +<a name="index-_002d_002dno_002dmerge_002dexidx_002dentries"></a> +<p>The ‘<samp>--no-merge-exidx-entries</samp>’ switch disables the merging of adjacent +exidx entries in frame unwind info. +</p> +</dd> +</dl> + + +<a name="Options-specific-to-C_002dSKY-targets"></a> +<h4 class="subsection">2.1.3 Options specific to C-SKY targets</h4> + + +<dl compact="compact"> +<dd> +<a name="index-_002d_002dbranch_002dstub-on-C_002dSKY"></a> +</dd> +<dt><code>--branch-stub</code></dt> +<dd><p>This option enables linker branch relaxation by inserting branch stub +sections when needed to extend the range of branches. This option is +usually not required since C-SKY supports branch and call instructions that +can access the full memory range and branch relaxation is normally handled by +the compiler or assembler. +</p> +<a name="index-_002d_002dstub_002dgroup_002dsize-on-C_002dSKY"></a> +</dd> +<dt><code>--stub-group-size=<var>N</var></code></dt> +<dd><p>This option allows finer control of linker branch stub creation. +It sets the maximum size of a group of input sections that can +be handled by one stub section. A negative value of <var>N</var> locates +stub sections after their branches, while a positive value allows stub +sections to appear either before or after the branches. Values of +‘<samp>1</samp>’ or ‘<samp>-1</samp>’ indicate that the +linker should choose suitable defaults. +</p> +</dd> +</dl> + + +<a name="Options-specific-to-Motorola-68HC11-and-68HC12-targets"></a> +<h4 class="subsection">2.1.4 Options specific to Motorola 68HC11 and 68HC12 targets</h4> + + +<p>The 68HC11 and 68HC12 linkers support specific options to control the +memory bank switching mapping and trampoline code generation. +</p> +<dl compact="compact"> +<dd> +<a name="index-_002d_002dno_002dtrampoline"></a> +</dd> +<dt><code>--no-trampoline</code></dt> +<dd><p>This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a <code>jsr</code> +instruction (this happens when a pointer to a far function is taken). +</p> +<a name="index-_002d_002dbank_002dwindow"></a> +</dd> +<dt><code>--bank-window <var>name</var></code></dt> +<dd><p>This option indicates to the linker the name of the memory region in +the ‘<samp>MEMORY</samp>’ specification that describes the memory bank window. +The definition of such region is then used by the linker to compute +paging and addresses within the memory window. +</p> +</dd> +</dl> + + +<a name="Options-specific-to-Motorola-68K-target"></a> +<h4 class="subsection">2.1.5 Options specific to Motorola 68K target</h4> + + +<p>The following options are supported to control handling of GOT generation +when linking for 68K targets. +</p> +<dl compact="compact"> +<dd> +<a name="index-_002d_002dgot"></a> +</dd> +<dt><code>--got=<var>type</var></code></dt> +<dd><p>This option tells the linker which GOT generation scheme to use. +<var>type</var> should be one of ‘<samp>single</samp>’, ‘<samp>negative</samp>’, +‘<samp>multigot</samp>’ or ‘<samp>target</samp>’. For more information refer to the +Info entry for <samp>ld</samp>. +</p> +</dd> +</dl> + + +<a name="Options-specific-to-MIPS-targets"></a> +<h4 class="subsection">2.1.6 Options specific to MIPS targets</h4> + + +<p>The following options are supported to control microMIPS instruction +generation and branch relocation checks for ISA mode transitions when +linking for MIPS targets. +</p> +<dl compact="compact"> +<dd> +<a name="index-_002d_002dinsn32"></a> +</dd> +<dt><code>--insn32</code></dt> +<dd><a name="index-_002d_002dno_002dinsn32"></a> +</dd> +<dt><code>--no-insn32</code></dt> +<dd><p>These options control the choice of microMIPS instructions used in code +generated by the linker, such as that in the PLT or lazy binding stubs, +or in relaxation. If ‘<samp>--insn32</samp>’ is used, then the linker only uses +32-bit instruction encodings. By default or if ‘<samp>--no-insn32</samp>’ is +used, all instruction encodings are used, including 16-bit ones where +possible. +</p> +<a name="index-_002d_002dignore_002dbranch_002disa"></a> +</dd> +<dt><code>--ignore-branch-isa</code></dt> +<dd><a name="index-_002d_002dno_002dignore_002dbranch_002disa"></a> +</dd> +<dt><code>--no-ignore-branch-isa</code></dt> +<dd><p>These options control branch relocation checks for invalid ISA mode +transitions. If ‘<samp>--ignore-branch-isa</samp>’ is used, then the linker +accepts any branch relocations and any ISA mode transition required +is lost in relocation calculation, except for some cases of <code>BAL</code> +instructions which meet relaxation conditions and are converted to +equivalent <code>JALX</code> instructions as the associated relocation is +calculated. By default or if ‘<samp>--no-ignore-branch-isa</samp>’ is used +a check is made causing the loss of an ISA mode transition to produce +an error. +</p> +<a name="index-_002d_002dcompact_002dbranches"></a> +</dd> +<dt><code>--compact-branches</code></dt> +<dd><a name="index-_002d_002dno_002dcompact_002dbranches"></a> +</dd> +<dt><code>--no-compact-branches</code></dt> +<dd><p>These options control the generation of compact instructions by the linker +in the PLT entries for MIPS R6. +</p> +</dd> +</dl> + + + +<a name="Options-specific-to-PDP11-targets"></a> +<h4 class="subsection">2.1.7 Options specific to PDP11 targets</h4> + + +<p>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</samp>’ option, whereas for other +targets ‘<samp>--nmagic</samp>’ is the default. The ‘<samp>--imagic</samp>’ option is +defined only for the pdp11-aout target, while the others are described +here as they apply to the pdp11-aout target. +</p> +<dl compact="compact"> +<dd> +<a name="index-_002dN-1"></a> +</dd> +<dt><code>-N</code></dt> +<dd><a name="index-_002d_002domagic-1"></a> +</dd> +<dt><code>--omagic</code></dt> +<dd> +<p>Mark the output as <code>OMAGIC</code> (0407) in the <samp>a.out</samp> 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 <code>ld</code> on PDP11 Unix systems +from the beginning through 2.11BSD. +</p> +<a name="index-_002dn-1"></a> +</dd> +<dt><code>-n</code></dt> +<dd><a name="index-_002d_002dnmagic-1"></a> +</dd> +<dt><code>--nmagic</code></dt> +<dd> +<p>Mark the output as <code>NMAGIC</code> (0410) in the <samp>a.out</samp> 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 <em>pure executable</em> format. +</p> +<a name="index-_002dz"></a> +</dd> +<dt><code>-z</code></dt> +<dd><a name="index-_002d_002dimagic"></a> +</dd> +<dt><code>--imagic</code></dt> +<dd> +<p>Mark the output as <code>IMAGIC</code> (0411) in the <samp>a.out</samp> 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</samp>’ option selected +this format in 2.11BSD. This option creates a <em>separate +executable</em> format. +</p> +<a name="index-_002d_002dno_002domagic-1"></a> +</dd> +<dt><code>--no-omagic</code></dt> +<dd> +<p>Equivalent to ‘<samp>--nmagic</samp>’ for pdp11-aout. +</p> +</dd> +</dl> + + +<hr> +<a name="Environment"></a> +<div class="header"> +<p> +Previous: <a href="#Options" accesskey="p" rel="previous">Options</a>, Up: <a href="#Invocation" accesskey="u" rel="up">Invocation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Environment-Variables"></a> +<h3 class="section">2.2 Environment Variables</h3> + + +<p>You can change the behaviour of <code>ld</code> with the environment variables +<code>GNUTARGET</code>, +<code>LDEMULATION</code> and <code>COLLECT_NO_DEMANGLE</code>. +</p> +<a name="index-GNUTARGET"></a> +<a name="index-default-input-format"></a> +<p><code>GNUTARGET</code> determines the input-file object format if you don’t +use ‘<samp>-b</samp>’ (or its synonym ‘<samp>--format</samp>’). Its value should be one +of the BFD names for an input format (see <a href="#BFD">BFD</a>). If there is no +<code>GNUTARGET</code> in the environment, <code>ld</code> uses the natural format +of the target. If <code>GNUTARGET</code> is set to <code>default</code> then BFD +attempts to discover the input format by examining binary input files; +this method often succeeds, but there are potential ambiguities, since +there is no method of ensuring that the magic number used to specify +object-file formats is unique. However, the configuration procedure for +BFD on each system places the conventional format for that system first +in the search-list, so ambiguities are resolved in favor of convention. +</p> +<a name="index-LDEMULATION"></a> +<a name="index-default-emulation"></a> +<a name="index-emulation_002c-default"></a> +<p><code>LDEMULATION</code> determines the default emulation if you don’t use the +‘<samp>-m</samp>’ option. The emulation can affect various aspects of linker +behaviour, particularly the default linker script. You can list the +available emulations with the ‘<samp>--verbose</samp>’ or ‘<samp>-V</samp>’ options. If +the ‘<samp>-m</samp>’ option is not used, and the <code>LDEMULATION</code> environment +variable is not defined, the default emulation depends upon how the +linker was configured. +</p> +<a name="index-COLLECT_005fNO_005fDEMANGLE"></a> +<a name="index-demangling_002c-default"></a> +<p>Normally, the linker will default to demangling symbols. However, if +<code>COLLECT_NO_DEMANGLE</code> is set in the environment, then it will +default to not demangling symbols. This environment variable is used in +a similar fashion by the <code>gcc</code> linker wrapper program. The default +may be overridden by the ‘<samp>--demangle</samp>’ and ‘<samp>--no-demangle</samp>’ +options. +</p> + +<hr> +<a name="Scripts"></a> +<div class="header"> +<p> +Next: <a href="#Plugins" accesskey="n" rel="next">Plugins</a>, Previous: <a href="#Invocation" accesskey="p" rel="previous">Invocation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Linker-Scripts"></a> +<h2 class="chapter">3 Linker Scripts</h2> + +<a name="index-scripts"></a> +<a name="index-linker-scripts"></a> +<a name="index-command-files"></a> +<p>Every link is controlled by a <em>linker script</em>. This script is +written in the linker command language. +</p> +<p>The main purpose of the linker script is to describe how the sections in +the input files should be mapped into the output file, and to control +the memory layout of the output file. Most linker scripts do nothing +more than this. However, when necessary, the linker script can also +direct the linker to perform many other operations, using the commands +described below. +</p> +<p>The linker always uses a linker script. If you do not supply one +yourself, the linker will use a default script that is compiled into the +linker executable. You can use the ‘<samp>--verbose</samp>’ command-line option +to display the default linker script. Certain command-line options, +such as ‘<samp>-r</samp>’ or ‘<samp>-N</samp>’, will affect the default linker script. +</p> +<p>You may supply your own linker script by using the ‘<samp>-T</samp>’ command +line option. When you do this, your linker script will replace the +default linker script. +</p> +<p>You may also use linker scripts implicitly by naming them as input files +to the linker, as though they were files to be linked. See <a href="#Implicit-Linker-Scripts">Implicit Linker Scripts</a>. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Basic-Script-Concepts" accesskey="1">Basic Script Concepts</a>:</td><td> </td><td align="left" valign="top">Basic Linker Script Concepts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Script-Format" accesskey="2">Script Format</a>:</td><td> </td><td align="left" valign="top">Linker Script Format +</td></tr> +<tr><td align="left" valign="top">• <a href="#Simple-Example" accesskey="3">Simple Example</a>:</td><td> </td><td align="left" valign="top">Simple Linker Script Example +</td></tr> +<tr><td align="left" valign="top">• <a href="#Simple-Commands" accesskey="4">Simple Commands</a>:</td><td> </td><td align="left" valign="top">Simple Linker Script Commands +</td></tr> +<tr><td align="left" valign="top">• <a href="#Assignments" accesskey="5">Assignments</a>:</td><td> </td><td align="left" valign="top">Assigning Values to Symbols +</td></tr> +<tr><td align="left" valign="top">• <a href="#SECTIONS" accesskey="6">SECTIONS</a>:</td><td> </td><td align="left" valign="top">SECTIONS Command +</td></tr> +<tr><td align="left" valign="top">• <a href="#MEMORY" accesskey="7">MEMORY</a>:</td><td> </td><td align="left" valign="top">MEMORY Command +</td></tr> +<tr><td align="left" valign="top">• <a href="#PHDRS" accesskey="8">PHDRS</a>:</td><td> </td><td align="left" valign="top">PHDRS Command +</td></tr> +<tr><td align="left" valign="top">• <a href="#VERSION" accesskey="9">VERSION</a>:</td><td> </td><td align="left" valign="top">VERSION Command +</td></tr> +<tr><td align="left" valign="top">• <a href="#Expressions">Expressions</a>:</td><td> </td><td align="left" valign="top">Expressions in Linker Scripts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Implicit-Linker-Scripts">Implicit Linker Scripts</a>:</td><td> </td><td align="left" valign="top">Implicit Linker Scripts +</td></tr> +</table> + +<hr> +<a name="Basic-Script-Concepts"></a> +<div class="header"> +<p> +Next: <a href="#Script-Format" accesskey="n" rel="next">Script Format</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Basic-Linker-Script-Concepts"></a> +<h3 class="section">3.1 Basic Linker Script Concepts</h3> +<a name="index-linker-script-concepts"></a> +<p>We need to define some basic concepts and vocabulary in order to +describe the linker script language. +</p> +<p>The linker combines input files into a single output file. The output +file and each input file are in a special data format known as an +<em>object file format</em>. Each file is called an <em>object file</em>. +The output file is often called an <em>executable</em>, but for our +purposes we will also call it an object file. Each object file has, +among other things, a list of <em>sections</em>. We sometimes refer to a +section in an input file as an <em>input section</em>; similarly, a section +in the output file is an <em>output section</em>. +</p> +<p>Each section in an object file has a name and a size. Most sections +also have an associated block of data, known as the <em>section +contents</em>. A section may be marked as <em>loadable</em>, which means that +the contents should be loaded into memory when the output file is run. +A section with no contents may be <em>allocatable</em>, which means that an +area in memory should be set aside, but nothing in particular should be +loaded there (in some cases this memory must be zeroed out). A section +which is neither loadable nor allocatable typically contains some sort +of debugging information. +</p> +<p>Every loadable or allocatable output section has two addresses. The +first is the <em>VMA</em>, or virtual memory address. This is the address +the section will have when the output file is run. The second is the +<em>LMA</em>, or load memory address. This is the address at which the +section will be loaded. In most cases the two addresses will be the +same. An example of when they might be different is when a data section +is loaded into ROM, and then copied into RAM when the program starts up +(this technique is often used to initialize global variables in a ROM +based system). In this case the ROM address would be the LMA, and the +RAM address would be the VMA. +</p> +<p>You can see the sections in an object file by using the <code>objdump</code> +program with the ‘<samp>-h</samp>’ option. +</p> +<p>Every object file also has a list of <em>symbols</em>, known as the +<em>symbol table</em>. A symbol may be defined or undefined. Each symbol +has a name, and each defined symbol has an address, among other +information. If you compile a C or C++ program into an object file, you +will get a defined symbol for every defined function and global or +static variable. Every undefined function or global variable which is +referenced in the input file will become an undefined symbol. +</p> +<p>You can see the symbols in an object file by using the <code>nm</code> +program, or by using the <code>objdump</code> program with the ‘<samp>-t</samp>’ +option. +</p> +<hr> +<a name="Script-Format"></a> +<div class="header"> +<p> +Next: <a href="#Simple-Example" accesskey="n" rel="next">Simple Example</a>, Previous: <a href="#Basic-Script-Concepts" accesskey="p" rel="previous">Basic Script Concepts</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Linker-Script-Format"></a> +<h3 class="section">3.2 Linker Script Format</h3> +<a name="index-linker-script-format"></a> +<p>Linker scripts are text files. +</p> +<p>You write a linker script as a series of commands. Each command is +either a keyword, possibly followed by arguments, or an assignment to a +symbol. You may separate commands using semicolons. Whitespace is +generally ignored. +</p> +<p>Strings such as file or format names can normally be entered directly. +If the file name contains a character such as a comma which would +otherwise serve to separate file names, you may put the file name in +double quotes. There is no way to use a double quote character in a +file name. +</p> +<p>You may include comments in linker scripts just as in C, delimited by +‘<samp>/*</samp>’ and ‘<samp>*/</samp>’. As in C, comments are syntactically equivalent +to whitespace. +</p> +<hr> +<a name="Simple-Example"></a> +<div class="header"> +<p> +Next: <a href="#Simple-Commands" accesskey="n" rel="next">Simple Commands</a>, Previous: <a href="#Script-Format" accesskey="p" rel="previous">Script Format</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Simple-Linker-Script-Example"></a> +<h3 class="section">3.3 Simple Linker Script Example</h3> +<a name="index-linker-script-example"></a> +<a name="index-example-of-linker-script"></a> +<p>Many linker scripts are fairly simple. +</p> +<p>The simplest possible linker script has just one command: +‘<samp>SECTIONS</samp>’. You use the ‘<samp>SECTIONS</samp>’ command to describe the +memory layout of the output file. +</p> +<p>The ‘<samp>SECTIONS</samp>’ command is a powerful command. Here we will +describe a simple use of it. Let’s assume your program consists only of +code, initialized data, and uninitialized data. These will be in the +‘<samp>.text</samp>’, ‘<samp>.data</samp>’, and ‘<samp>.bss</samp>’ sections, respectively. +Let’s assume further that these are the only sections which appear in +your input files. +</p> +<p>For this example, let’s say that the code should be loaded at address +0x10000, and that the data should start at address 0x8000000. Here is a +linker script which will do that: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + . = 0x10000; + .text : { *(.text) } + . = 0x8000000; + .data : { *(.data) } + .bss : { *(.bss) } +} +</pre></div> + +<p>You write the ‘<samp>SECTIONS</samp>’ command as the keyword ‘<samp>SECTIONS</samp>’, +followed by a series of symbol assignments and output section +descriptions enclosed in curly braces. +</p> +<p>The first line inside the ‘<samp>SECTIONS</samp>’ command of the above example +sets the value of the special symbol ‘<samp>.</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. At the start of the +‘<samp>SECTIONS</samp>’ command, the location counter has the value ‘<samp>0</samp>’. +</p> +<p>The second line defines an output section, ‘<samp>.text</samp>’. The colon is +required syntax which may be ignored for now. Within the curly braces +after the output section name, you list the names of the input sections +which should be placed into this output section. The ‘<samp>*</samp>’ is a +wildcard which matches any file name. The expression ‘<samp>*(.text)</samp>’ +means all ‘<samp>.text</samp>’ input sections in all input files. +</p> +<p>Since the location counter is ‘<samp>0x10000</samp>’ when the output section +‘<samp>.text</samp>’ is defined, the linker will set the address of the +‘<samp>.text</samp>’ section in the output file to be ‘<samp>0x10000</samp>’. +</p> +<p>The remaining lines define the ‘<samp>.data</samp>’ and ‘<samp>.bss</samp>’ sections in +the output file. The linker will place the ‘<samp>.data</samp>’ output section +at address ‘<samp>0x8000000</samp>’. After the linker places the ‘<samp>.data</samp>’ +output section, the value of the location counter will be +‘<samp>0x8000000</samp>’ plus the size of the ‘<samp>.data</samp>’ output section. The +effect is that the linker will place the ‘<samp>.bss</samp>’ output section +immediately after the ‘<samp>.data</samp>’ output section in memory. +</p> +<p>The linker will ensure that each output section has the required +alignment, by increasing the location counter if necessary. In this +example, the specified addresses for the ‘<samp>.text</samp>’ and ‘<samp>.data</samp>’ +sections will probably satisfy any alignment constraints, but the linker +may have to create a small gap between the ‘<samp>.data</samp>’ and ‘<samp>.bss</samp>’ +sections. +</p> +<p>That’s it! That’s a simple and complete linker script. +</p> +<hr> +<a name="Simple-Commands"></a> +<div class="header"> +<p> +Next: <a href="#Assignments" accesskey="n" rel="next">Assignments</a>, Previous: <a href="#Simple-Example" accesskey="p" rel="previous">Simple Example</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Simple-Linker-Script-Commands"></a> +<h3 class="section">3.4 Simple Linker Script Commands</h3> +<a name="index-linker-script-simple-commands"></a> +<p>In this section we describe the simple linker script commands. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Entry-Point" accesskey="1">Entry Point</a>:</td><td> </td><td align="left" valign="top">Setting the entry point +</td></tr> +<tr><td align="left" valign="top">• <a href="#File-Commands" accesskey="2">File Commands</a>:</td><td> </td><td align="left" valign="top">Commands dealing with files +</td></tr> +<tr><td align="left" valign="top">• <a href="#Format-Commands" accesskey="3">Format Commands</a>:</td><td> </td><td align="left" valign="top">Commands dealing with object file formats +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr><tr><td align="left" valign="top">• <a href="#REGION_005fALIAS" accesskey="4">REGION_ALIAS</a>:</td><td> </td><td align="left" valign="top">Assign alias names to memory regions +</td></tr> +<tr><td align="left" valign="top">• <a href="#Miscellaneous-Commands" accesskey="5">Miscellaneous Commands</a>:</td><td> </td><td align="left" valign="top">Other linker script commands +</td></tr> +</table> + +<hr> +<a name="Entry-Point"></a> +<div class="header"> +<p> +Next: <a href="#File-Commands" accesskey="n" rel="next">File Commands</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Setting-the-Entry-Point"></a> +<h4 class="subsection">3.4.1 Setting the Entry Point</h4> +<a name="index-ENTRY_0028symbol_0029"></a> +<a name="index-start-of-execution"></a> +<a name="index-first-instruction"></a> +<a name="index-entry-point"></a> +<p>The first instruction to execute in a program is called the <em>entry +point</em>. You can use the <code>ENTRY</code> linker script command to set the +entry point. The argument is a symbol name: +</p><div class="smallexample"> +<pre class="smallexample">ENTRY(<var>symbol</var>) +</pre></div> + +<p>There are several ways to set the entry point. The linker will set the +entry point by trying each of the following methods in order, and +stopping when one of them succeeds: +</p><ul> +<li> the ‘<samp>-e</samp>’ <var>entry</var> command-line option; +</li><li> the <code>ENTRY(<var>symbol</var>)</code> command in a linker script; +</li><li> the value of a target-specific symbol, if it is defined; For many +targets this is <code>start</code>, but PE- and BeOS-based systems for example +check a list of possible entry symbols, matching the first one found. +</li><li> the address of the first byte of the code section, if present and an +executable is being created - the code section is usually +‘<samp>.text</samp>’, but can be something else; +</li><li> The address <code>0</code>. +</li></ul> + +<hr> +<a name="File-Commands"></a> +<div class="header"> +<p> +Next: <a href="#Format-Commands" accesskey="n" rel="next">Format Commands</a>, Previous: <a href="#Entry-Point" accesskey="p" rel="previous">Entry Point</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Commands-Dealing-with-Files"></a> +<h4 class="subsection">3.4.2 Commands Dealing with Files</h4> +<a name="index-linker-script-file-commands"></a> +<p>Several linker script commands deal with files. +</p> +<dl compact="compact"> +<dt><code>INCLUDE <var>filename</var></code></dt> +<dd><a name="index-INCLUDE-filename"></a> +<a name="index-including-a-linker-script"></a> +<p>Include the linker script <var>filename</var> at this point. The file will +be searched for in the current directory, and in any directory specified +with the <samp>-L</samp> option. You can nest calls to <code>INCLUDE</code> up to +10 levels deep. +</p> +<p>You can place <code>INCLUDE</code> directives at the top level, in <code>MEMORY</code> or +<code>SECTIONS</code> commands, or in output section descriptions. +</p> +</dd> +<dt><code>INPUT(<var>file</var>, <var>file</var>, …)</code></dt> +<dt><code>INPUT(<var>file</var> <var>file</var> …)</code></dt> +<dd><a name="index-INPUT_0028files_0029"></a> +<a name="index-input-files-in-linker-scripts"></a> +<a name="index-input-object-files-in-linker-scripts"></a> +<a name="index-linker-script-input-object-files"></a> +<p>The <code>INPUT</code> command directs the linker to include the named files +in the link, as though they were named on the command line. +</p> +<p>For example, if you always want to include <samp>subr.o</samp> any time you do +a link, but you can’t be bothered to put it on every link command line, +then you can put ‘<samp>INPUT (subr.o)</samp>’ in your linker script. +</p> +<p>In fact, if you like, you can list all of your input files in the linker +script, and then invoke the linker with nothing but a ‘<samp>-T</samp>’ option. +</p> +<p>In case a <em>sysroot prefix</em> is configured, and the filename starts +with the ‘<samp>/</samp>’ character, and the script being processed was +located inside the <em>sysroot prefix</em>, the filename will be looked +for in the <em>sysroot prefix</em>. The <em>sysroot prefix</em> can also be forced by specifying +<code>=</code> as the first character in the filename path, or prefixing the +filename path with <code>$SYSROOT</code>. See also the description of +‘<samp>-L</samp>’ in <a href="#Options">Command-line Options</a>. +</p> +<p>If a <em>sysroot prefix</em> 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. +</p> +<p>If you use ‘<samp>INPUT (-l<var>file</var>)</samp>’, <code>ld</code> will transform the +name to <code>lib<var>file</var>.a</code>, as with the command-line argument +‘<samp>-l</samp>’. +</p> +<p>When you use the <code>INPUT</code> command in an implicit linker script, the +files will be included in the link at the point at which the linker +script file is included. This can affect archive searching. +</p> +</dd> +<dt><code>GROUP(<var>file</var>, <var>file</var>, …)</code></dt> +<dt><code>GROUP(<var>file</var> <var>file</var> …)</code></dt> +<dd><a name="index-GROUP_0028files_0029"></a> +<a name="index-grouping-input-files"></a> +<p>The <code>GROUP</code> command is like <code>INPUT</code>, except that the named +files should all be archives, and they are searched repeatedly until no +new undefined references are created. See the description of ‘<samp>-(</samp>’ +in <a href="#Options">Command-line Options</a>. +</p> +</dd> +<dt><code>AS_NEEDED(<var>file</var>, <var>file</var>, …)</code></dt> +<dt><code>AS_NEEDED(<var>file</var> <var>file</var> …)</code></dt> +<dd><a name="index-AS_005fNEEDED_0028files_0029"></a> +<p>This construct can appear only inside of the <code>INPUT</code> or <code>GROUP</code> +commands, among other filenames. The files listed will be handled +as if they appear directly in the <code>INPUT</code> or <code>GROUP</code> commands, +with the exception of ELF shared libraries, that will be added only +when they are actually needed. This construct essentially enables +<samp>--as-needed</samp> option for all the files listed inside of it +and restores previous <samp>--as-needed</samp> resp. <samp>--no-as-needed</samp> +setting afterwards. +</p> +</dd> +<dt><code>OUTPUT(<var>filename</var>)</code></dt> +<dd><a name="index-OUTPUT_0028filename_0029"></a> +<a name="index-output-file-name-in-linker-script"></a> +<p>The <code>OUTPUT</code> command names the output file. Using +<code>OUTPUT(<var>filename</var>)</code> in the linker script is exactly like using +‘<samp>-o <var>filename</var></samp>’ on the command line (see <a href="#Options">Command +Line Options</a>). If both are used, the command-line option takes +precedence. +</p> +<p>You can use the <code>OUTPUT</code> command to define a default name for the +output file other than the usual default of <samp>a.out</samp>. +</p> +</dd> +<dt><code>SEARCH_DIR(<var>path</var>)</code></dt> +<dd><a name="index-SEARCH_005fDIR_0028path_0029"></a> +<a name="index-library-search-path-in-linker-script"></a> +<a name="index-archive-search-path-in-linker-script"></a> +<a name="index-search-path-in-linker-script"></a> +<p>The <code>SEARCH_DIR</code> command adds <var>path</var> to the list of paths where +<code>ld</code> looks for archive libraries. Using +<code>SEARCH_DIR(<var>path</var>)</code> is exactly like using ‘<samp>-L <var>path</var></samp>’ +on the command line (see <a href="#Options">Command-line Options</a>). If both +are used, then the linker will search both paths. Paths specified using +the command-line option are searched first. +</p> +</dd> +<dt><code>STARTUP(<var>filename</var>)</code></dt> +<dd><a name="index-STARTUP_0028filename_0029"></a> +<a name="index-first-input-file"></a> +<p>The <code>STARTUP</code> command is just like the <code>INPUT</code> command, except +that <var>filename</var> will become the first input file to be linked, as +though it were specified first on the command line. This may be useful +when using a system in which the entry point is always the start of the +first file. +</p></dd> +</dl> + +<hr> +<a name="Format-Commands"></a> +<div class="header"> +<p> +Next: <a href="#REGION_005fALIAS" accesskey="n" rel="next">REGION_ALIAS</a>, Previous: <a href="#File-Commands" accesskey="p" rel="previous">File Commands</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Commands-Dealing-with-Object-File-Formats"></a> +<h4 class="subsection">3.4.3 Commands Dealing with Object File Formats</h4> +<p>A couple of linker script commands deal with object file formats. +</p> +<dl compact="compact"> +<dt><code>OUTPUT_FORMAT(<var>bfdname</var>)</code></dt> +<dt><code>OUTPUT_FORMAT(<var>default</var>, <var>big</var>, <var>little</var>)</code></dt> +<dd><a name="index-OUTPUT_005fFORMAT_0028bfdname_0029"></a> +<a name="index-output-file-format-in-linker-script"></a> +<p>The <code>OUTPUT_FORMAT</code> command names the BFD format to use for the +output file (see <a href="#BFD">BFD</a>). Using <code>OUTPUT_FORMAT(<var>bfdname</var>)</code> is +exactly like using ‘<samp>--oformat <var>bfdname</var></samp>’ on the command line +(see <a href="#Options">Command-line Options</a>). If both are used, the command +line option takes precedence. +</p> +<p>You can use <code>OUTPUT_FORMAT</code> with three arguments to use different +formats based on the ‘<samp>-EB</samp>’ and ‘<samp>-EL</samp>’ command-line options. +This permits the linker script to set the output format based on the +desired endianness. +</p> +<p>If neither ‘<samp>-EB</samp>’ nor ‘<samp>-EL</samp>’ are used, then the output format +will be the first argument, <var>default</var>. If ‘<samp>-EB</samp>’ is used, the +output format will be the second argument, <var>big</var>. If ‘<samp>-EL</samp>’ is +used, the output format will be the third argument, <var>little</var>. +</p> +<p>For example, the default linker script for the MIPS ELF target uses this +command: +</p><div class="smallexample"> +<pre class="smallexample">OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) +</pre></div> +<p>This says that the default format for the output file is +‘<samp>elf32-bigmips</samp>’, but if the user uses the ‘<samp>-EL</samp>’ command-line +option, the output file will be created in the ‘<samp>elf32-littlemips</samp>’ +format. +</p> +</dd> +<dt><code>TARGET(<var>bfdname</var>)</code></dt> +<dd><a name="index-TARGET_0028bfdname_0029"></a> +<a name="index-input-file-format-in-linker-script"></a> +<p>The <code>TARGET</code> command names the BFD format to use when reading input +files. It affects subsequent <code>INPUT</code> and <code>GROUP</code> commands. +This command is like using ‘<samp>-b <var>bfdname</var></samp>’ on the command line +(see <a href="#Options">Command-line Options</a>). If the <code>TARGET</code> command +is used but <code>OUTPUT_FORMAT</code> is not, then the last <code>TARGET</code> +command is also used to set the format for the output file. See <a href="#BFD">BFD</a>. +</p></dd> +</dl> + +<hr> +<a name="REGION_005fALIAS"></a> +<div class="header"> +<p> +Next: <a href="#Miscellaneous-Commands" accesskey="n" rel="next">Miscellaneous Commands</a>, Previous: <a href="#Format-Commands" accesskey="p" rel="previous">Format Commands</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Assign-alias-names-to-memory-regions"></a> +<h4 class="subsection">3.4.4 Assign alias names to memory regions</h4> +<a name="index-REGION_005fALIAS_0028alias_002c-region_0029"></a> +<a name="index-region-alias"></a> +<a name="index-region-names"></a> + +<p>Alias names can be added to existing memory regions created with the +<a href="#MEMORY">MEMORY</a> command. Each name corresponds to at most one memory region. +</p> +<div class="smallexample"> +<pre class="smallexample">REGION_ALIAS(<var>alias</var>, <var>region</var>) +</pre></div> + +<p>The <code>REGION_ALIAS</code> function creates an alias name <var>alias</var> for the +memory region <var>region</var>. This allows a flexible mapping of output sections +to memory regions. An example follows. +</p> +<p>Suppose we have an application for embedded systems which come with various +memory storage devices. All have a general purpose, volatile memory <code>RAM</code> +that allows code execution or data storage. Some may have a read-only, +non-volatile memory <code>ROM</code> that allows code execution and read-only data +access. The last variant is a read-only, non-volatile memory <code>ROM2</code> with +read-only data access and no code execution capability. We have four output +sections: +</p> +<ul> +<li> <code>.text</code> program code; +</li><li> <code>.rodata</code> read-only data; +</li><li> <code>.data</code> read-write initialized data; +</li><li> <code>.bss</code> read-write zero initialized data. +</li></ul> + +<p>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>, <code>B</code> and +<code>C</code>: +</p><table> +<tr><td width="25%">Section</td><td width="25%">Variant A</td><td width="25%">Variant B</td><td width="25%">Variant C</td></tr> +<tr><td width="25%">.text</td><td width="25%">RAM</td><td width="25%">ROM</td><td width="25%">ROM</td></tr> +<tr><td width="25%">.rodata</td><td width="25%">RAM</td><td width="25%">ROM</td><td width="25%">ROM2</td></tr> +<tr><td width="25%">.data</td><td width="25%">RAM</td><td width="25%">RAM/ROM</td><td width="25%">RAM/ROM2</td></tr> +<tr><td width="25%">.bss</td><td width="25%">RAM</td><td width="25%">RAM</td><td width="25%">RAM</td></tr> +</table> +<p>The notation <code>RAM/ROM</code> or <code>RAM/ROM2</code> means that this section is +loaded into region <code>ROM</code> or <code>ROM2</code> respectively. Please note that +the load address of the <code>.data</code> section starts in all three variants at +the end of the <code>.rodata</code> section. +</p> +<p>The base linker script that deals with the output sections follows. It +includes the system dependent <code>linkcmds.memory</code> file that describes the +memory layout: +</p><div class="smallexample"> +<pre class="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 + } +</pre></div> + +<p>Now we need three different <code>linkcmds.memory</code> files to define memory +regions and alias names. The content of <code>linkcmds.memory</code> for the three +variants <code>A</code>, <code>B</code> and <code>C</code>: +</p><dl compact="compact"> +<dt><code>A</code></dt> +<dd><p>Here everything goes into the <code>RAM</code>. +</p><div class="smallexample"> +<pre class="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); +</pre></div> +</dd> +<dt><code>B</code></dt> +<dd><p>Program code and read-only data go into the <code>ROM</code>. Read-write data goes +into the <code>RAM</code>. An image of the initialized data is loaded into the +<code>ROM</code> and will be copied during system start into the <code>RAM</code>. +</p><div class="smallexample"> +<pre class="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); +</pre></div> +</dd> +<dt><code>C</code></dt> +<dd><p>Program code goes into the <code>ROM</code>. Read-only data goes into the +<code>ROM2</code>. Read-write data goes into the <code>RAM</code>. An image of the +initialized data is loaded into the <code>ROM2</code> and will be copied during +system start into the <code>RAM</code>. +</p><div class="smallexample"> +<pre class="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); +</pre></div> +</dd> +</dl> + +<p>It is possible to write a common system initialization routine to copy the +<code>.data</code> section from <code>ROM</code> or <code>ROM2</code> into the <code>RAM</code> if +necessary: +</p><div class="smallexample"> +<pre class="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); + } +} +</pre></div> + +<hr> +<a name="Miscellaneous-Commands"></a> +<div class="header"> +<p> +Previous: <a href="#REGION_005fALIAS" accesskey="p" rel="previous">REGION_ALIAS</a>, Up: <a href="#Simple-Commands" accesskey="u" rel="up">Simple Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Other-Linker-Script-Commands"></a> +<h4 class="subsection">3.4.5 Other Linker Script Commands</h4> +<p>There are a few other linker scripts commands. +</p> +<dl compact="compact"> +<dt><code>ASSERT(<var>exp</var>, <var>message</var>)</code></dt> +<dd><a name="index-ASSERT"></a> +<a name="index-assertion-in-linker-script"></a> +<p>Ensure that <var>exp</var> is non-zero. If it is zero, then exit the linker +with an error code, and print <var>message</var>. +</p> +<p>Note that assertions are checked before the final stages of linking +take place. This means that expressions involving symbols PROVIDEd +inside section definitions will fail if the user has not set values +for those symbols. The only exception to this rule is PROVIDEd +symbols that just reference dot. Thus an assertion like this: +</p> +<div class="smallexample"> +<pre class="smallexample"> .stack : + { + PROVIDE (__stack = .); + PROVIDE (__stack_size = 0x100); + ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack"); + } +</pre></div> + +<p>will fail if <code>__stack_size</code> is not defined elsewhere. Symbols +PROVIDEd outside of section definitions are evaluated earlier, so they +can be used inside ASSERTions. Thus: +</p> +<div class="smallexample"> +<pre class="smallexample"> PROVIDE (__stack_size = 0x100); + .stack : + { + PROVIDE (__stack = .); + ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack"); + } +</pre></div> + +<p>will work. +</p> +</dd> +<dt><code>EXTERN(<var>symbol</var> <var>symbol</var> …)</code></dt> +<dd><a name="index-EXTERN"></a> +<a name="index-undefined-symbol-in-linker-script"></a> +<p>Force <var>symbol</var> to be entered in the output file as an undefined +symbol. Doing this may, for example, trigger linking of additional +modules from standard libraries. You may list several <var>symbol</var>s for +each <code>EXTERN</code>, and you may use <code>EXTERN</code> multiple times. This +command has the same effect as the ‘<samp>-u</samp>’ command-line option. +</p> +</dd> +<dt><code>FORCE_COMMON_ALLOCATION</code></dt> +<dd><a name="index-FORCE_005fCOMMON_005fALLOCATION"></a> +<a name="index-common-allocation-in-linker-script"></a> +<p>This command has the same effect as the ‘<samp>-d</samp>’ command-line option: +to make <code>ld</code> assign space to common symbols even if a relocatable +output file is specified (‘<samp>-r</samp>’). +</p> +</dd> +<dt><code>INHIBIT_COMMON_ALLOCATION</code></dt> +<dd><a name="index-INHIBIT_005fCOMMON_005fALLOCATION"></a> +<a name="index-common-allocation-in-linker-script-1"></a> +<p>This command has the same effect as the ‘<samp>--no-define-common</samp>’ +command-line option: to make <code>ld</code> omit the assignment of addresses +to common symbols even for a non-relocatable output file. +</p> +</dd> +<dt><code>FORCE_GROUP_ALLOCATION</code></dt> +<dd><a name="index-FORCE_005fGROUP_005fALLOCATION"></a> +<a name="index-group-allocation-in-linker-script-1"></a> +<a name="index-section-groups-1"></a> +<a name="index-COMDAT-1"></a> +<p>This command has the same effect as the +‘<samp>--force-group-allocation</samp>’ command-line option: to make +<code>ld</code> place section group members like normal input sections, +and to delete the section groups even if a relocatable output file is +specified (‘<samp>-r</samp>’). +</p> +</dd> +<dt><code>INSERT [ AFTER | BEFORE ] <var>output_section</var></code></dt> +<dd><a name="index-INSERT"></a> +<a name="index-insert-user-script-into-default-script"></a> +<p>This command is typically used in a script specified by ‘<samp>-T</samp>’ to +augment the default <code>SECTIONS</code> with, for example, overlays. It +inserts all prior linker script statements after (or before) +<var>output_section</var>, and also causes ‘<samp>-T</samp>’ to not override the +default linker script. The exact insertion point is as for orphan +sections. See <a href="#Location-Counter">Location Counter</a>. The insertion happens after the +linker has mapped input sections to output sections. Prior to the +insertion, since ‘<samp>-T</samp>’ scripts are parsed before the default +linker script, statements in the ‘<samp>-T</samp>’ script occur before the +default linker script statements in the internal linker representation +of the script. In particular, input section assignments will be made +to ‘<samp>-T</samp>’ output sections before those in the default script. Here +is an example of how a ‘<samp>-T</samp>’ script using <code>INSERT</code> might look: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + OVERLAY : + { + .ov1 { ov1*(.text) } + .ov2 { ov2*(.text) } + } +} +INSERT AFTER .text; +</pre></div> + +<p>Note that when ‘<samp>-T</samp>’ is used twice, once to override the default +script and once to augment that script using <code>INSERT</code> the order +of parsing and section assignments apply as for the default script. +The script with <code>INSERT</code> should be specified <em>first</em> on the +command line. +</p> +</dd> +<dt><code>NOCROSSREFS(<var>section</var> <var>section</var> …)</code></dt> +<dd><a name="index-NOCROSSREFS_0028sections_0029"></a> +<a name="index-cross-references"></a> +<p>This command may be used to tell <code>ld</code> to issue an error about any +references among certain output sections. +</p> +<p>In certain types of programs, particularly on embedded systems when +using overlays, when one section is loaded into memory, another section +will not be. Any direct references between the two sections would be +errors. For example, it would be an error if code in one section called +a function defined in the other section. +</p> +<p>The <code>NOCROSSREFS</code> command takes a list of output section names. If +<code>ld</code> detects any cross references between the sections, it reports +an error and returns a non-zero exit status. Note that the +<code>NOCROSSREFS</code> command uses output section names, not input section +names. +</p> +</dd> +<dt><code>NOCROSSREFS_TO(<var>tosection</var> <var>fromsection</var> …)</code></dt> +<dd><a name="index-NOCROSSREFS_005fTO_0028tosection-fromsections_0029"></a> +<a name="index-cross-references-1"></a> +<p>This command may be used to tell <code>ld</code> to issue an error about any +references to one section from a list of other sections. +</p> +<p>The <code>NOCROSSREFS</code> command is useful when ensuring that two or more +output sections are entirely independent but there are situations where +a one-way dependency is needed. For example, in a multi-core application +there may be shared code that can be called from each core but for safety +must never call back. +</p> +<p>The <code>NOCROSSREFS_TO</code> command takes a list of output section names. +The first section can not be referenced from any of the other sections. +If <code>ld</code> detects any references to the first section from any of +the other sections, it reports an error and returns a non-zero exit +status. Note that the <code>NOCROSSREFS_TO</code> command uses output section +names, not input section names. +</p> +</dd> +<dt><code>OUTPUT_ARCH(<var>bfdarch</var>)</code></dt> +<dd><a name="index-OUTPUT_005fARCH_0028bfdarch_0029"></a> +<a name="index-machine-architecture"></a> +<a name="index-architecture"></a> +<p>Specify a particular output machine architecture. The argument is one +of the names used by the BFD library (see <a href="#BFD">BFD</a>). You can see the +architecture of an object file by using the <code>objdump</code> program with +the ‘<samp>-f</samp>’ option. +</p> +</dd> +<dt><code>LD_FEATURE(<var>string</var>)</code></dt> +<dd><a name="index-LD_005fFEATURE_0028string_0029"></a> +<p>This command may be used to modify <code>ld</code> behavior. If +<var>string</var> is <code>"SANE_EXPR"</code> then absolute symbols and numbers +in a script are simply treated as numbers everywhere. +See <a href="#Expression-Section">Expression Section</a>. +</p></dd> +</dl> + +<hr> +<a name="Assignments"></a> +<div class="header"> +<p> +Next: <a href="#SECTIONS" accesskey="n" rel="next">SECTIONS</a>, Previous: <a href="#Simple-Commands" accesskey="p" rel="previous">Simple Commands</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Assigning-Values-to-Symbols"></a> +<h3 class="section">3.5 Assigning Values to Symbols</h3> +<a name="index-assignment-in-scripts"></a> +<a name="index-symbol-definition_002c-scripts"></a> +<a name="index-variables_002c-defining"></a> +<p>You may assign a value to a symbol in a linker script. This will define +the symbol and place it into the symbol table with a global scope. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Simple-Assignments" accesskey="1">Simple Assignments</a>:</td><td> </td><td align="left" valign="top">Simple Assignments +</td></tr> +<tr><td align="left" valign="top">• <a href="#HIDDEN" accesskey="2">HIDDEN</a>:</td><td> </td><td align="left" valign="top">HIDDEN +</td></tr> +<tr><td align="left" valign="top">• <a href="#PROVIDE" accesskey="3">PROVIDE</a>:</td><td> </td><td align="left" valign="top">PROVIDE +</td></tr> +<tr><td align="left" valign="top">• <a href="#PROVIDE_005fHIDDEN" accesskey="4">PROVIDE_HIDDEN</a>:</td><td> </td><td align="left" valign="top">PROVIDE_HIDDEN +</td></tr> +<tr><td align="left" valign="top">• <a href="#Source-Code-Reference" accesskey="5">Source Code Reference</a>:</td><td> </td><td align="left" valign="top">How to use a linker script defined symbol in source code +</td></tr> +</table> + +<hr> +<a name="Simple-Assignments"></a> +<div class="header"> +<p> +Next: <a href="#HIDDEN" accesskey="n" rel="next">HIDDEN</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Simple-Assignments-1"></a> +<h4 class="subsection">3.5.1 Simple Assignments</h4> + +<p>You may assign to a symbol using any of the C assignment operators: +</p> +<dl compact="compact"> +<dt><code><var>symbol</var> = <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> += <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> -= <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> *= <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> /= <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> <<= <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> >>= <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> &= <var>expression</var> ;</code></dt> +<dt><code><var>symbol</var> |= <var>expression</var> ;</code></dt> +</dl> + +<p>The first case will define <var>symbol</var> to the value of +<var>expression</var>. In the other cases, <var>symbol</var> must already be +defined, and the value will be adjusted accordingly. +</p> +<p>The special symbol name ‘<samp>.</samp>’ indicates the location counter. You +may only use this within a <code>SECTIONS</code> command. See <a href="#Location-Counter">Location Counter</a>. +</p> +<p>The semicolon after <var>expression</var> is required. +</p> +<p>Expressions are defined below; see <a href="#Expressions">Expressions</a>. +</p> +<p>You may write symbol assignments as commands in their own right, or as +statements within a <code>SECTIONS</code> command, or as part of an output +section description in a <code>SECTIONS</code> command. +</p> +<p>The section of the symbol will be set from the section of the +expression; for more information, see <a href="#Expression-Section">Expression Section</a>. +</p> +<p>Here is an example showing the three different places that symbol +assignments may be used: +</p> +<div class="smallexample"> +<pre class="smallexample">floating_point = 0; +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + } + _bdata = (. + 3) & ~ 3; + .data : { *(.data) } +} +</pre></div> +<p>In this example, the symbol ‘<samp>floating_point</samp>’ will be defined as +zero. The symbol ‘<samp>_etext</samp>’ will be defined as the address following +the last ‘<samp>.text</samp>’ input section. The symbol ‘<samp>_bdata</samp>’ will be +defined as the address following the ‘<samp>.text</samp>’ output section aligned +upward to a 4 byte boundary. +</p> +<hr> +<a name="HIDDEN"></a> +<div class="header"> +<p> +Next: <a href="#PROVIDE" accesskey="n" rel="next">PROVIDE</a>, Previous: <a href="#Simple-Assignments" accesskey="p" rel="previous">Simple Assignments</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="HIDDEN-1"></a> +<h4 class="subsection">3.5.2 HIDDEN</h4> +<a name="index-HIDDEN"></a> +<p>For ELF targeted ports, define a symbol that will be hidden and won’t be +exported. The syntax is <code>HIDDEN(<var>symbol</var> = <var>expression</var>)</code>. +</p> +<p>Here is the example from <a href="#Simple-Assignments">Simple Assignments</a>, rewritten to use +<code>HIDDEN</code>: +</p> +<div class="smallexample"> +<pre class="smallexample">HIDDEN(floating_point = 0); +SECTIONS +{ + .text : + { + *(.text) + HIDDEN(_etext = .); + } + HIDDEN(_bdata = (. + 3) & ~ 3); + .data : { *(.data) } +} +</pre></div> +<p>In this case none of the three symbols will be visible outside this module. +</p> +<hr> +<a name="PROVIDE"></a> +<div class="header"> +<p> +Next: <a href="#PROVIDE_005fHIDDEN" accesskey="n" rel="next">PROVIDE_HIDDEN</a>, Previous: <a href="#HIDDEN" accesskey="p" rel="previous">HIDDEN</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="PROVIDE-1"></a> +<h4 class="subsection">3.5.3 PROVIDE</h4> +<a name="index-PROVIDE"></a> +<p>In some cases, it is desirable for a linker script to define a symbol +only if it is referenced and is not defined by any object included in +the link. For example, traditional linkers defined the symbol +‘<samp>etext</samp>’. However, ANSI C requires that the user be able to use +‘<samp>etext</samp>’ as a function name without encountering an error. The +<code>PROVIDE</code> keyword may be used to define a symbol, such as +‘<samp>etext</samp>’, only if it is referenced but not defined. The syntax is +<code>PROVIDE(<var>symbol</var> = <var>expression</var>)</code>. +</p> +<p>Here is an example of using <code>PROVIDE</code> to define ‘<samp>etext</samp>’: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + .text : + { + *(.text) + _etext = .; + PROVIDE(etext = .); + } +} +</pre></div> + +<p>In this example, if the program defines ‘<samp>_etext</samp>’ (with a leading +underscore), the linker will give a multiple definition diagnostic. If, +on the other hand, the program defines ‘<samp>etext</samp>’ (with no leading +underscore), the linker will silently use the definition in the program. +If the program references ‘<samp>etext</samp>’ but does not define it, the +linker will use the definition in the linker script. +</p> +<p>Note - the <code>PROVIDE</code> directive considers a common symbol to be +defined, even though such a symbol could be combined with the symbol +that the <code>PROVIDE</code> would create. This is particularly important +when considering constructor and destructor list symbols such as +‘<samp>__CTOR_LIST__</samp>’ as these are often defined as common symbols. +</p> +<hr> +<a name="PROVIDE_005fHIDDEN"></a> +<div class="header"> +<p> +Next: <a href="#Source-Code-Reference" accesskey="n" rel="next">Source Code Reference</a>, Previous: <a href="#PROVIDE" accesskey="p" rel="previous">PROVIDE</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="PROVIDE_005fHIDDEN-1"></a> +<h4 class="subsection">3.5.4 PROVIDE_HIDDEN</h4> +<a name="index-PROVIDE_005fHIDDEN"></a> +<p>Similar to <code>PROVIDE</code>. For ELF targeted ports, the symbol will be +hidden and won’t be exported. +</p> +<hr> +<a name="Source-Code-Reference"></a> +<div class="header"> +<p> +Previous: <a href="#PROVIDE_005fHIDDEN" accesskey="p" rel="previous">PROVIDE_HIDDEN</a>, Up: <a href="#Assignments" accesskey="u" rel="up">Assignments</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Source-Code-Reference-1"></a> +<h4 class="subsection">3.5.5 Source Code Reference</h4> + +<p>Accessing a linker script defined variable from source code is not +intuitive. In particular a linker script symbol is not equivalent to +a variable declaration in a high level language, it is instead a +symbol that does not have a value. +</p> +<p>Before going further, it is important to note that compilers often +transform names in the source code into different names when they are +stored in the symbol table. For example, Fortran compilers commonly +prepend or append an underscore, and C++ performs extensive ‘<samp>name +mangling</samp>’. Therefore there might be a discrepancy between the name +of a variable as it is used in source code and the name of the same +variable as it is defined in a linker script. For example in C a +linker script variable might be referred to as: +</p> +<div class="smallexample"> +<pre class="smallexample"> extern int foo; +</pre></div> + +<p>But in the linker script it might be defined as: +</p> +<div class="smallexample"> +<pre class="smallexample"> _foo = 1000; +</pre></div> + +<p>In the remaining examples however it is assumed that no name +transformation has taken place. +</p> +<p>When a symbol is declared in a high level language such as C, two +things happen. The first is that the compiler reserves enough space +in the program’s memory to hold the <em>value</em> of the symbol. The +second is that the compiler creates an entry in the program’s symbol +table which holds the symbol’s <em>address</em>. ie the symbol table +contains the address of the block of memory holding the symbol’s +value. So for example the following C declaration, at file scope: +</p> +<div class="smallexample"> +<pre class="smallexample"> int foo = 1000; +</pre></div> + +<p>creates an entry called ‘<samp>foo</samp>’ in the symbol table. This entry +holds the address of an ‘<samp>int</samp>’ sized block of memory where the +number 1000 is initially stored. +</p> +<p>When a program references a symbol the compiler generates code that +first accesses the symbol table to find the address of the symbol’s +memory block and then code to read the value from that memory block. +So: +</p> +<div class="smallexample"> +<pre class="smallexample"> foo = 1; +</pre></div> + +<p>looks up the symbol ‘<samp>foo</samp>’ in the symbol table, gets the address +associated with this symbol and then writes the value 1 into that +address. Whereas: +</p> +<div class="smallexample"> +<pre class="smallexample"> int * a = & foo; +</pre></div> + +<p>looks up the symbol ‘<samp>foo</samp>’ in the symbol table, gets its address +and then copies this address into the block of memory associated with +the variable ‘<samp>a</samp>’. +</p> +<p>Linker scripts symbol declarations, by contrast, create an entry in +the symbol table but do not assign any memory to them. Thus they are +an address without a value. So for example the linker script definition: +</p> +<div class="smallexample"> +<pre class="smallexample"> foo = 1000; +</pre></div> + +<p>creates an entry in the symbol table called ‘<samp>foo</samp>’ which holds +the address of memory location 1000, but nothing special is stored at +address 1000. This means that you cannot access the <em>value</em> of a +linker script defined symbol - it has no value - all you can do is +access the <em>address</em> of a linker script defined symbol. +</p> +<p>Hence when you are using a linker script defined symbol in source code +you should always take the address of the symbol, and never attempt to +use its value. For example suppose you want to copy the contents of a +section of memory called .ROM into a section called .FLASH and the +linker script contains these declarations: +</p> +<div class="smallexample"> +<pre class="smallexample"> start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM); + start_of_FLASH = .FLASH; +</pre></div> + +<p>Then the C source code to perform the copy would be: +</p> +<div class="smallexample"> +<pre class="smallexample"> extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); +</pre></div> + +<p>Note the use of the ‘<samp>&</samp>’ operators. These are correct. +Alternatively the symbols can be treated as the names of vectors or +arrays and then the code will again work as expected: +</p> +<div class="smallexample"> +<pre class="smallexample"> extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[]; + + memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM); +</pre></div> + +<p>Note how using this method does not require the use of ‘<samp>&</samp>’ +operators. +</p> +<hr> +<a name="SECTIONS"></a> +<div class="header"> +<p> +Next: <a href="#MEMORY" accesskey="n" rel="next">MEMORY</a>, Previous: <a href="#Assignments" accesskey="p" rel="previous">Assignments</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="SECTIONS-Command"></a> +<h3 class="section">3.6 SECTIONS Command</h3> +<a name="index-SECTIONS"></a> +<p>The <code>SECTIONS</code> command tells the linker how to map input sections +into output sections, and how to place the output sections in memory. +</p> +<p>The format of the <code>SECTIONS</code> command is: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + <var>sections-command</var> + <var>sections-command</var> + … +} +</pre></div> + +<p>Each <var>sections-command</var> may of be one of the following: +</p> +<ul> +<li> an <code>ENTRY</code> command (see <a href="#Entry-Point">Entry command</a>) +</li><li> a symbol assignment (see <a href="#Assignments">Assignments</a>) +</li><li> an output section description +</li><li> an overlay description +</li></ul> + +<p>The <code>ENTRY</code> command and symbol assignments are permitted inside the +<code>SECTIONS</code> command for convenience in using the location counter in +those commands. This can also make the linker script easier to +understand because you can use those commands at meaningful points in +the layout of the output file. +</p> +<p>Output section descriptions and overlay descriptions are described +below. +</p> +<p>If you do not use a <code>SECTIONS</code> command in your linker script, the +linker will place each input section into an identically named output +section in the order that the sections are first encountered in the +input files. If all input sections are present in the first file, for +example, the order of sections in the output file will match the order +in the first input file. The first section will be at address zero. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Output-Section-Description" accesskey="1">Output Section Description</a>:</td><td> </td><td align="left" valign="top">Output section description +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Name" accesskey="2">Output Section Name</a>:</td><td> </td><td align="left" valign="top">Output section name +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Address" accesskey="3">Output Section Address</a>:</td><td> </td><td align="left" valign="top">Output section address +</td></tr> +<tr><td align="left" valign="top">• <a href="#Input-Section" accesskey="4">Input Section</a>:</td><td> </td><td align="left" valign="top">Input section description +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Data" accesskey="5">Output Section Data</a>:</td><td> </td><td align="left" valign="top">Output section data +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Keywords" accesskey="6">Output Section Keywords</a>:</td><td> </td><td align="left" valign="top">Output section keywords +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Discarding" accesskey="7">Output Section Discarding</a>:</td><td> </td><td align="left" valign="top">Output section discarding +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Attributes" accesskey="8">Output Section Attributes</a>:</td><td> </td><td align="left" valign="top">Output section attributes +</td></tr> +<tr><td align="left" valign="top">• <a href="#Overlay-Description" accesskey="9">Overlay Description</a>:</td><td> </td><td align="left" valign="top">Overlay description +</td></tr> +</table> + +<hr> +<a name="Output-Section-Description"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Name" accesskey="n" rel="next">Output Section Name</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Description-1"></a> +<h4 class="subsection">3.6.1 Output Section Description</h4> +<p>The full description of an output section looks like this: +</p><div class="smallexample"> +<pre class="smallexample"><var>section</var> [<var>address</var>] [(<var>type</var>)] : + [AT(<var>lma</var>)] + [ALIGN(<var>section_align</var>) | ALIGN_WITH_INPUT] + [SUBALIGN(<var>subsection_align</var>)] + [<var>constraint</var>] + { + <var>output-section-command</var> + <var>output-section-command</var> + … + } [><var>region</var>] [AT><var>lma_region</var>] [:<var>phdr</var> :<var>phdr</var> …] [=<var>fillexp</var>] [,] +</pre></div> + +<p>Most output sections do not use most of the optional section attributes. +</p> +<p>The whitespace around <var>section</var> is required, so that the section +name is unambiguous. The colon and the curly braces are also required. +The comma at the end may be required if a <var>fillexp</var> is used and +the next <var>sections-command</var> looks like a continuation of the expression. +The line breaks and other white space are optional. +</p> +<p>Each <var>output-section-command</var> may be one of the following: +</p> +<ul> +<li> a symbol assignment (see <a href="#Assignments">Assignments</a>) +</li><li> an input section description (see <a href="#Input-Section">Input Section</a>) +</li><li> data values to include directly (see <a href="#Output-Section-Data">Output Section Data</a>) +</li><li> a special output section keyword (see <a href="#Output-Section-Keywords">Output Section Keywords</a>) +</li></ul> + +<hr> +<a name="Output-Section-Name"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Address" accesskey="n" rel="next">Output Section Address</a>, Previous: <a href="#Output-Section-Description" accesskey="p" rel="previous">Output Section Description</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Name-1"></a> +<h4 class="subsection">3.6.2 Output Section Name</h4> +<a name="index-name_002c-section"></a> +<a name="index-section-name"></a> +<p>The name of the output section is <var>section</var>. <var>section</var> must +meet the constraints of your output format. In formats which only +support a limited number of sections, such as <code>a.out</code>, the name +must be one of the names supported by the format (<code>a.out</code>, for +example, allows only ‘<samp>.text</samp>’, ‘<samp>.data</samp>’ or ‘<samp>.bss</samp>’). If the +output format supports any number of sections, but with numbers and not +names (as is the case for Oasys), the name should be supplied as a +quoted numeric string. A section name may consist of any sequence of +characters, but a name which contains any unusual characters such as +commas must be quoted. +</p> +<p>The output section name ‘<samp>/DISCARD/</samp>’ is special; <a href="#Output-Section-Discarding">Output Section Discarding</a>. +</p> +<hr> +<a name="Output-Section-Address"></a> +<div class="header"> +<p> +Next: <a href="#Input-Section" accesskey="n" rel="next">Input Section</a>, Previous: <a href="#Output-Section-Name" accesskey="p" rel="previous">Output Section Name</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Address-1"></a> +<h4 class="subsection">3.6.3 Output Section Address</h4> +<a name="index-address_002c-section"></a> +<a name="index-section-address"></a> +<p>The <var>address</var> is an expression for the VMA (the virtual memory +address) of the output section. This address is optional, but if it +is provided then the output address will be set exactly as specified. +</p> +<p>If the output address is not specified then one will be chosen for the +section, based on the heuristic below. This address will be adjusted +to fit the alignment requirement of the output section. The +alignment requirement is the strictest alignment of any input section +contained within the output section. +</p> +<p>The output section address heuristic is as follows: +</p> +<ul> +<li> If an output memory <var>region</var> is set for the section then it +is added to this region and its address will be the next free address +in that region. + +</li><li> If the MEMORY command has been used to create a list of memory +regions then the first region which has attributes compatible with the +section is selected to contain it. The section’s output address will +be the next free address in that region; <a href="#MEMORY">MEMORY</a>. + +</li><li> If no memory regions were specified, or none match the section then +the output address will be based on the current value of the location +counter. +</li></ul> + +<p>For example: +</p> +<div class="smallexample"> +<pre class="smallexample">.text . : { *(.text) } +</pre></div> + +<p>and +</p> +<div class="smallexample"> +<pre class="smallexample">.text : { *(.text) } +</pre></div> + +<p>are subtly different. The first will set the address of the +‘<samp>.text</samp>’ output section to the current value of the location +counter. The second will set it to the current value of the location +counter aligned to the strictest alignment of any of the ‘<samp>.text</samp>’ +input sections. +</p> +<p>The <var>address</var> may be an arbitrary expression; <a href="#Expressions">Expressions</a>. +For example, if you want to align the section on a 0x10 byte boundary, +so that the lowest four bits of the section address are zero, you could +do something like this: +</p><div class="smallexample"> +<pre class="smallexample">.text ALIGN(0x10) : { *(.text) } +</pre></div> +<p>This works because <code>ALIGN</code> returns the current location counter +aligned upward to the specified value. +</p> +<p>Specifying <var>address</var> for a section will change the value of the +location counter, provided that the section is non-empty. (Empty +sections are ignored). +</p> +<hr> +<a name="Input-Section"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Data" accesskey="n" rel="next">Output Section Data</a>, Previous: <a href="#Output-Section-Address" accesskey="p" rel="previous">Output Section Address</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Input-Section-Description"></a> +<h4 class="subsection">3.6.4 Input Section Description</h4> +<a name="index-input-sections"></a> +<a name="index-mapping-input-sections-to-output-sections"></a> +<p>The most common output section command is an input section description. +</p> +<p>The input section description is the most basic linker script operation. +You use output sections to tell the linker how to lay out your program +in memory. You use input section descriptions to tell the linker how to +map the input files into your memory layout. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Input-Section-Basics" accesskey="1">Input Section Basics</a>:</td><td> </td><td align="left" valign="top">Input section basics +</td></tr> +<tr><td align="left" valign="top">• <a href="#Input-Section-Wildcards" accesskey="2">Input Section Wildcards</a>:</td><td> </td><td align="left" valign="top">Input section wildcard patterns +</td></tr> +<tr><td align="left" valign="top">• <a href="#Input-Section-Common" accesskey="3">Input Section Common</a>:</td><td> </td><td align="left" valign="top">Input section for common symbols +</td></tr> +<tr><td align="left" valign="top">• <a href="#Input-Section-Keep" accesskey="4">Input Section Keep</a>:</td><td> </td><td align="left" valign="top">Input section and garbage collection +</td></tr> +<tr><td align="left" valign="top">• <a href="#Input-Section-Example" accesskey="5">Input Section Example</a>:</td><td> </td><td align="left" valign="top">Input section example +</td></tr> +</table> + +<hr> +<a name="Input-Section-Basics"></a> +<div class="header"> +<p> +Next: <a href="#Input-Section-Wildcards" accesskey="n" rel="next">Input Section Wildcards</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Input-Section-Basics-1"></a> +<h4 class="subsubsection">3.6.4.1 Input Section Basics</h4> +<a name="index-input-section-basics"></a> +<p>An input section description consists of a file name optionally followed +by a list of section names in parentheses. +</p> +<p>The file name and the section name may be wildcard patterns, which we +describe further below (see <a href="#Input-Section-Wildcards">Input Section Wildcards</a>). +</p> +<p>The most common input section description is to include all input +sections with a particular name in the output section. For example, to +include all input ‘<samp>.text</samp>’ sections, you would write: +</p><div class="smallexample"> +<pre class="smallexample">*(.text) +</pre></div> +<p>Here the ‘<samp>*</samp>’ is a wildcard which matches any file name. To exclude a list +<a name="index-EXCLUDE_005fFILE"></a> +of files from matching the file name wildcard, EXCLUDE_FILE may be used to +match all files except the ones specified in the EXCLUDE_FILE list. For +example: +</p><div class="smallexample"> +<pre class="smallexample">EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors) +</pre></div> +<p>will cause all .ctors sections from all files except <samp>crtend.o</samp> +and <samp>otherfile.o</samp> to be included. The EXCLUDE_FILE can also be +placed inside the section list, for example: +</p><div class="smallexample"> +<pre class="smallexample">*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors) +</pre></div> +<p>The result of this is identically to the previous example. Supporting +two syntaxes for EXCLUDE_FILE is useful if the section list contains +more than one section, as described below. +</p> +<p>There are two ways to include more than one section: +</p><div class="smallexample"> +<pre class="smallexample">*(.text .rdata) +*(.text) *(.rdata) +</pre></div> +<p>The difference between these is the order in which the ‘<samp>.text</samp>’ and +‘<samp>.rdata</samp>’ input sections will appear in the output section. In the +first example, they will be intermingled, appearing in the same order as +they are found in the linker input. In the second example, all +‘<samp>.text</samp>’ input sections will appear first, followed by all +‘<samp>.rdata</samp>’ input sections. +</p> +<p>When using EXCLUDE_FILE with more than one section, if the exclusion +is within the section list then the exclusion only applies to the +immediately following section, for example: +</p><div class="smallexample"> +<pre class="smallexample">*(EXCLUDE_FILE (*somefile.o) .text .rdata) +</pre></div> +<p>will cause all ‘<samp>.text</samp>’ sections from all files except +<samp>somefile.o</samp> to be included, while all ‘<samp>.rdata</samp>’ sections +from all files, including <samp>somefile.o</samp>, will be included. To +exclude the ‘<samp>.rdata</samp>’ sections from <samp>somefile.o</samp> the example +could be modified to: +</p><div class="smallexample"> +<pre class="smallexample">*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata) +</pre></div> +<p>Alternatively, placing the EXCLUDE_FILE outside of the section list, +before the input file selection, will cause the exclusion to apply for +all sections. Thus the previous example can be rewritten as: +</p><div class="smallexample"> +<pre class="smallexample">EXCLUDE_FILE (*somefile.o) *(.text .rdata) +</pre></div> + +<p>You can specify a file name to include sections from a particular file. +You would do this if one or more of your files contain special data that +needs to be at a particular location in memory. For example: +</p><div class="smallexample"> +<pre class="smallexample">data.o(.data) +</pre></div> + +<p>To refine the sections that are included based on the section flags +of an input section, INPUT_SECTION_FLAGS may be used. +</p> +<p>Here is a simple example for using Section header flags for ELF sections: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS { + .text : { INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) } + .text2 : { INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) } +} +</pre></div> + +<p>In this example, the output section ‘<samp>.text</samp>’ will be comprised of any +input section matching the name *(.text) whose section header flags +<code>SHF_MERGE</code> and <code>SHF_STRINGS</code> are set. The output section +‘<samp>.text2</samp>’ will be comprised of any input section matching the name *(.text) +whose section header flag <code>SHF_WRITE</code> is clear. +</p> +<p>You can also specify files within archives by writing a pattern +matching the archive, a colon, then the pattern matching the file, +with no whitespace around the colon. +</p> +<dl compact="compact"> +<dt>‘<samp>archive:file</samp>’</dt> +<dd><p>matches file within archive +</p></dd> +<dt>‘<samp>archive:</samp>’</dt> +<dd><p>matches the whole archive +</p></dd> +<dt>‘<samp>:file</samp>’</dt> +<dd><p>matches file but not one in an archive +</p></dd> +</dl> + +<p>Either one or both of ‘<samp>archive</samp>’ and ‘<samp>file</samp>’ can contain shell +wildcards. On DOS based file systems, the linker will assume that a +single letter followed by a colon is a drive specifier, so +‘<samp>c:myfile.o</samp>’ is a simple file specification, not ‘<samp>myfile.o</samp>’ +within an archive called ‘<samp>c</samp>’. ‘<samp>archive:file</samp>’ filespecs may +also be used within an <code>EXCLUDE_FILE</code> list, but may not appear in +other linker script contexts. For instance, you cannot extract a file +from an archive by using ‘<samp>archive:file</samp>’ in an <code>INPUT</code> +command. +</p> +<p>If you use a file name without a list of sections, then all sections in +the input file will be included in the output section. This is not +commonly done, but it may by useful on occasion. For example: +</p><div class="smallexample"> +<pre class="smallexample">data.o +</pre></div> + +<p>When you use a file name which is not an ‘<samp>archive:file</samp>’ specifier +and does not contain any wild card +characters, the linker will first see if you also specified the file +name on the linker command line or in an <code>INPUT</code> command. If you +did not, the linker will attempt to open the file as an input file, as +though it appeared on the command line. Note that this differs from an +<code>INPUT</code> command, because the linker will not search for the file in +the archive search path. +</p> +<hr> +<a name="Input-Section-Wildcards"></a> +<div class="header"> +<p> +Next: <a href="#Input-Section-Common" accesskey="n" rel="next">Input Section Common</a>, Previous: <a href="#Input-Section-Basics" accesskey="p" rel="previous">Input Section Basics</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Input-Section-Wildcard-Patterns"></a> +<h4 class="subsubsection">3.6.4.2 Input Section Wildcard Patterns</h4> +<a name="index-input-section-wildcards"></a> +<a name="index-wildcard-file-name-patterns"></a> +<a name="index-file-name-wildcard-patterns"></a> +<a name="index-section-name-wildcard-patterns"></a> +<p>In an input section description, either the file name or the section +name or both may be wildcard patterns. +</p> +<p>The file name of ‘<samp>*</samp>’ seen in many examples is a simple wildcard +pattern for the file name. +</p> +<p>The wildcard patterns are like those used by the Unix shell. +</p> +<dl compact="compact"> +<dt>‘<samp>*</samp>’</dt> +<dd><p>matches any number of characters +</p></dd> +<dt>‘<samp>?</samp>’</dt> +<dd><p>matches any single character +</p></dd> +<dt>‘<samp>[<var>chars</var>]</samp>’</dt> +<dd><p>matches a single instance of any of the <var>chars</var>; the ‘<samp>-</samp>’ +character may be used to specify a range of characters, as in +‘<samp>[a-z]</samp>’ to match any lower case letter +</p></dd> +<dt>‘<samp>\</samp>’</dt> +<dd><p>quotes the following character +</p></dd> +</dl> + +<p>File name wildcard patterns only match files which are explicitly +specified on the command line or in an <code>INPUT</code> command. The linker +does not search directories to expand wildcards. +</p> +<p>If a file name matches more than one wildcard pattern, or if a file name +appears explicitly and is also matched by a wildcard pattern, the linker +will use the first match in the linker script. For example, this +sequence of input section descriptions is probably in error, because the +<samp>data.o</samp> rule will not be used: +</p><div class="smallexample"> +<pre class="smallexample">.data : { *(.data) } +.data1 : { data.o(.data) } +</pre></div> + +<a name="index-SORT_005fBY_005fNAME"></a> +<p>Normally, the linker will place files and sections matched by wildcards +in the order in which they are seen during the link. You can change +this by using the <code>SORT_BY_NAME</code> keyword, which appears before a wildcard +pattern in parentheses (e.g., <code>SORT_BY_NAME(.text*)</code>). When the +<code>SORT_BY_NAME</code> keyword is used, the linker will sort the files or sections +into ascending order by name before placing them in the output file. +</p> +<a name="index-SORT_005fBY_005fALIGNMENT"></a> +<p><code>SORT_BY_ALIGNMENT</code> is similar to <code>SORT_BY_NAME</code>. +<code>SORT_BY_ALIGNMENT</code> will sort sections into descending order of +alignment before placing them in the output file. Placing larger +alignments before smaller alignments can reduce the amount of padding +needed. +</p> +<a name="index-SORT_005fBY_005fINIT_005fPRIORITY"></a> +<p><code>SORT_BY_INIT_PRIORITY</code> is also similar to <code>SORT_BY_NAME</code>. +<code>SORT_BY_INIT_PRIORITY</code> will sort sections into ascending +numerical order of the GCC init_priority attribute encoded in the +section name before placing them in the output file. In +<code>.init_array.NNNNN</code> and <code>.fini_array.NNNNN</code>, <code>NNNNN</code> is +the init_priority. In <code>.ctors.NNNNN</code> and <code>.dtors.NNNNN</code>, +<code>NNNNN</code> is 65535 minus the init_priority. +</p> +<a name="index-SORT"></a> +<p><code>SORT</code> is an alias for <code>SORT_BY_NAME</code>. +</p> +<p>When there are nested section sorting commands in linker script, there +can be at most 1 level of nesting for section sorting commands. +</p> +<ol> +<li> <code>SORT_BY_NAME</code> (<code>SORT_BY_ALIGNMENT</code> (wildcard section pattern)). +It will sort the input sections by name first, then by alignment if two +sections have the same name. +</li><li> <code>SORT_BY_ALIGNMENT</code> (<code>SORT_BY_NAME</code> (wildcard section pattern)). +It will sort the input sections by alignment first, then by name if two +sections have the same alignment. +</li><li> <code>SORT_BY_NAME</code> (<code>SORT_BY_NAME</code> (wildcard section pattern)) is +treated the same as <code>SORT_BY_NAME</code> (wildcard section pattern). +</li><li> <code>SORT_BY_ALIGNMENT</code> (<code>SORT_BY_ALIGNMENT</code> (wildcard section pattern)) +is treated the same as <code>SORT_BY_ALIGNMENT</code> (wildcard section pattern). +</li><li> All other nested section sorting commands are invalid. +</li></ol> + +<p>When both command-line section sorting option and linker script +section sorting command are used, section sorting command always +takes precedence over the command-line option. +</p> +<p>If the section sorting command in linker script isn’t nested, the +command-line option will make the section sorting command to be +treated as nested sorting command. +</p> +<ol> +<li> <code>SORT_BY_NAME</code> (wildcard section pattern ) with +<samp>--sort-sections alignment</samp> is equivalent to +<code>SORT_BY_NAME</code> (<code>SORT_BY_ALIGNMENT</code> (wildcard section pattern)). +</li><li> <code>SORT_BY_ALIGNMENT</code> (wildcard section pattern) with +<samp>--sort-section name</samp> is equivalent to +<code>SORT_BY_ALIGNMENT</code> (<code>SORT_BY_NAME</code> (wildcard section pattern)). +</li></ol> + +<p>If the section sorting command in linker script is nested, the +command-line option will be ignored. +</p> +<a name="index-SORT_005fNONE"></a> +<p><code>SORT_NONE</code> disables section sorting by ignoring the command-line +section sorting option. +</p> +<p>If you ever get confused about where input sections are going, use the +‘<samp>-M</samp>’ linker option to generate a map file. The map file shows +precisely how input sections are mapped to output sections. +</p> +<p>This example shows how wildcard patterns might be used to partition +files. This linker script directs the linker to place all ‘<samp>.text</samp>’ +sections in ‘<samp>.text</samp>’ and all ‘<samp>.bss</samp>’ sections in ‘<samp>.bss</samp>’. +The linker will place the ‘<samp>.data</samp>’ section from all files beginning +with an upper case character in ‘<samp>.DATA</samp>’; for all other files, the +linker will place the ‘<samp>.data</samp>’ section in ‘<samp>.data</samp>’. +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { + .text : { *(.text) } + .DATA : { [A-Z]*(.data) } + .data : { *(.data) } + .bss : { *(.bss) } +} +</pre></div> + +<hr> +<a name="Input-Section-Common"></a> +<div class="header"> +<p> +Next: <a href="#Input-Section-Keep" accesskey="n" rel="next">Input Section Keep</a>, Previous: <a href="#Input-Section-Wildcards" accesskey="p" rel="previous">Input Section Wildcards</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Input-Section-for-Common-Symbols"></a> +<h4 class="subsubsection">3.6.4.3 Input Section for Common Symbols</h4> +<a name="index-common-symbol-placement"></a> +<a name="index-uninitialized-data-placement"></a> +<p>A special notation is needed for common symbols, because in many object +file formats common symbols do not have a particular input section. The +linker treats common symbols as though they are in an input section +named ‘<samp>COMMON</samp>’. +</p> +<p>You may use file names with the ‘<samp>COMMON</samp>’ section just as with any +other input sections. You can use this to place common symbols from a +particular input file in one section while common symbols from other +input files are placed in another section. +</p> +<p>In most cases, common symbols in input files will be placed in the +‘<samp>.bss</samp>’ section in the output file. For example: +</p><div class="smallexample"> +<pre class="smallexample">.bss { *(.bss) *(COMMON) } +</pre></div> + +<a name="index-scommon-section"></a> +<a name="index-small-common-symbols"></a> +<p>Some object file formats have more than one type of common symbol. For +example, the MIPS ELF object file format distinguishes standard common +symbols and small common symbols. In this case, the linker will use a +different special section name for other types of common symbols. In +the case of MIPS ELF, the linker uses ‘<samp>COMMON</samp>’ for standard common +symbols and ‘<samp>.scommon</samp>’ for small common symbols. This permits you +to map the different types of common symbols into memory at different +locations. +</p> +<a name="index-_005bCOMMON_005d"></a> +<p>You will sometimes see ‘<samp>[COMMON]</samp>’ in old linker scripts. This +notation is now considered obsolete. It is equivalent to +‘<samp>*(COMMON)</samp>’. +</p> +<hr> +<a name="Input-Section-Keep"></a> +<div class="header"> +<p> +Next: <a href="#Input-Section-Example" accesskey="n" rel="next">Input Section Example</a>, Previous: <a href="#Input-Section-Common" accesskey="p" rel="previous">Input Section Common</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Input-Section-and-Garbage-Collection"></a> +<h4 class="subsubsection">3.6.4.4 Input Section and Garbage Collection</h4> +<a name="index-KEEP"></a> +<a name="index-garbage-collection-3"></a> +<p>When link-time garbage collection is in use (‘<samp>--gc-sections</samp>’), +it is often useful to mark sections that should not be eliminated. +This is accomplished by surrounding an input section’s wildcard entry +with <code>KEEP()</code>, as in <code>KEEP(*(.init))</code> or +<code>KEEP(SORT_BY_NAME(*)(.ctors))</code>. +</p> +<hr> +<a name="Input-Section-Example"></a> +<div class="header"> +<p> +Previous: <a href="#Input-Section-Keep" accesskey="p" rel="previous">Input Section Keep</a>, Up: <a href="#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Input-Section-Example-1"></a> +<h4 class="subsubsection">3.6.4.5 Input Section Example</h4> +<p>The following example is a complete linker script. It tells the linker +to read all of the sections from file <samp>all.o</samp> and place them at the +start of output section ‘<samp>outputa</samp>’ which starts at location +‘<samp>0x10000</samp>’. All of section ‘<samp>.input1</samp>’ from file <samp>foo.o</samp> +follows immediately, in the same output section. All of section +‘<samp>.input2</samp>’ from <samp>foo.o</samp> goes into output section +‘<samp>outputb</samp>’, followed by section ‘<samp>.input1</samp>’ from <samp>foo1.o</samp>. +All of the remaining ‘<samp>.input1</samp>’ and ‘<samp>.input2</samp>’ sections from any +files are written to output section ‘<samp>outputc</samp>’. +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS { + outputa 0x10000 : + { + all.o + foo.o (.input1) + } +</pre><pre class="smallexample"> outputb : + { + foo.o (.input2) + foo1.o (.input1) + } +</pre><pre class="smallexample"> outputc : + { + *(.input1) + *(.input2) + } +} +</pre></div> + +<p>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 see <a href="#PROVIDE">PROVIDE</a> 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>.</samp>’ character. +</p> +<hr> +<a name="Output-Section-Data"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Keywords" accesskey="n" rel="next">Output Section Keywords</a>, Previous: <a href="#Input-Section" accesskey="p" rel="previous">Input Section</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Data-1"></a> +<h4 class="subsection">3.6.5 Output Section Data</h4> +<a name="index-data"></a> +<a name="index-section-data"></a> +<a name="index-output-section-data"></a> +<a name="index-ASCIZ-_0060_0060string_0027_0027"></a> +<a name="index-BYTE_0028expression_0029"></a> +<a name="index-SHORT_0028expression_0029"></a> +<a name="index-LONG_0028expression_0029"></a> +<a name="index-QUAD_0028expression_0029"></a> +<a name="index-SQUAD_0028expression_0029"></a> +<p>You can include explicit bytes of data in an output section by using +<code>BYTE</code>, <code>SHORT</code>, <code>LONG</code>, <code>QUAD</code>, or <code>SQUAD</code> as +an output section command. Each keyword is followed by an expression in +parentheses providing the value to store (see <a href="#Expressions">Expressions</a>). The +value of the expression is stored at the current value of the location +counter. +</p> +<p>The <code>BYTE</code>, <code>SHORT</code>, <code>LONG</code>, and <code>QUAD</code> commands +store one, two, four, and eight bytes (respectively). After storing the +bytes, the location counter is incremented by the number of bytes +stored. +</p> +<p>For example, this will store the byte 1 followed by the four byte value +of the symbol ‘<samp>addr</samp>’: +</p><div class="smallexample"> +<pre class="smallexample">BYTE(1) +LONG(addr) +</pre></div> + +<p>When using a 64 bit host or target, <code>QUAD</code> and <code>SQUAD</code> are the +same; they both store an 8 byte, or 64 bit, value. When both host and +target are 32 bits, an expression is computed as 32 bits. In this case +<code>QUAD</code> stores a 32 bit value zero extended to 64 bits, and +<code>SQUAD</code> stores a 32 bit value sign extended to 64 bits. +</p> +<p>If the object file format of the output file has an explicit endianness, +which is the normal case, the value will be stored in that endianness. +When the object file format does not have an explicit endianness, as is +true of, for example, S-records, the value will be stored in the +endianness of the first input object file. +</p> +<p>You can include a zero-terminated string in an output section by using +<code>ASCIZ</code>. The keyword is followed by a string which is stored at +the current value of the location counter adding a zero byte at the +end. If the string includes spaces it must be enclosed in double +quotes. The string may contain ’\n’, ’\r’, ’\t’ and octal numbers. +Hex numbers are not supported. +</p> +<p>For example, this string of 16 characters will create a 17 byte area +</p><div class="smallexample"> +<pre class="smallexample"> ASCIZ "This is 16 bytes" +</pre></div> + +<p>Note—these commands only work inside a section description and not +between them, so the following will produce an error from the linker: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } </pre></div> +<p>whereas this will work: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } </pre></div> + +<a name="index-FILL_0028expression_0029"></a> +<a name="index-holes_002c-filling"></a> +<a name="index-unspecified-memory"></a> +<p>You may use the <code>FILL</code> command to set the fill pattern for the +current section. It is followed by an expression in parentheses. Any +otherwise unspecified regions of memory within the section (for example, +gaps left due to the required alignment of input sections) are filled +with the value of the expression, repeated as +necessary. A <code>FILL</code> statement covers memory locations after the +point at which it occurs in the section definition; by including more +than one <code>FILL</code> statement, you can have different fill patterns in +different parts of an output section. +</p> +<p>This example shows how to fill unspecified regions of memory with the +value ‘<samp>0x90</samp>’: +</p><div class="smallexample"> +<pre class="smallexample">FILL(0x90909090) +</pre></div> + +<p>The <code>FILL</code> command is similar to the ‘<samp>=<var>fillexp</var></samp>’ output +section attribute, but it only affects the +part of the section following the <code>FILL</code> command, rather than the +entire section. If both are used, the <code>FILL</code> command takes +precedence. See <a href="#Output-Section-Fill">Output Section Fill</a>, for details on the fill +expression. +</p> +<a name="index-LINKER_005fVERSION-1"></a> +<a name="index-LINKER_005fVERSION"></a> +<p>Inserts a string containing the version of the linker at the current +point. Note - by default this directive is disabled and will do +nothing. It only becomes active if the +<samp>--enable-linker-version</samp> command line option is used. +</p> +<p>Built-in linker scripts for ELF based targets already include this +directive in their ‘<samp>.comment</samp>’ section. +</p> +<hr> +<a name="Output-Section-Keywords"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Discarding" accesskey="n" rel="next">Output Section Discarding</a>, Previous: <a href="#Output-Section-Data" accesskey="p" rel="previous">Output Section Data</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Keywords-1"></a> +<h4 class="subsection">3.6.6 Output Section Keywords</h4> +<p>There are a couple of keywords which can appear as output section +commands. +</p> +<dl compact="compact"> +<dd><a name="index-CREATE_005fOBJECT_005fSYMBOLS"></a> +<a name="index-input-filename-symbols"></a> +<a name="index-filename-symbols"></a> +</dd> +<dt><code>CREATE_OBJECT_SYMBOLS</code></dt> +<dd><p>The command tells the linker to create a symbol for each input file. +The name of each symbol will be the name of the corresponding input +file. The section of each symbol will be the output section in which +the <code>CREATE_OBJECT_SYMBOLS</code> command appears. +</p> +<p>This is conventional for the a.out object file format. It is not +normally used for any other object file format. +</p> +<a name="index-CONSTRUCTORS"></a> +<a name="index-C_002b_002b-constructors_002c-arranging-in-link"></a> +<a name="index-constructors_002c-arranging-in-link"></a> +</dd> +<dt><code>CONSTRUCTORS</code></dt> +<dd><p>When linking using the a.out object file format, the linker uses an +unusual set construct to support C++ global constructors and +destructors. When linking object file formats which do not support +arbitrary sections, such as ECOFF and XCOFF, the linker will +automatically recognize C++ global constructors and destructors by name. +For these object file formats, the <code>CONSTRUCTORS</code> command tells the +linker to place constructor information in the output section where the +<code>CONSTRUCTORS</code> command appears. The <code>CONSTRUCTORS</code> command is +ignored for other object file formats. +</p> +<p>The symbol <code><span class="nolinebreak">__CTOR_LIST__</span></code><!-- /@w --> marks the start of the global +constructors, and the symbol <code><span class="nolinebreak">__CTOR_END__</span></code><!-- /@w --> marks the end. +Similarly, <code><span class="nolinebreak">__DTOR_LIST__</span></code><!-- /@w --> and <code><span class="nolinebreak">__DTOR_END__</span></code><!-- /@w --> mark +the start and end of the global destructors. The +first word in the list is the number of entries, followed by the address +of each constructor or destructor, followed by a zero word. The +compiler must arrange to actually run the code. For these object file +formats <small>GNU</small> C++ normally calls constructors from a subroutine +<code>__main</code>; a call to <code>__main</code> is automatically inserted into +the startup code for <code>main</code>. <small>GNU</small> C++ normally runs +destructors either by using <code>atexit</code>, or directly from the function +<code>exit</code>. +</p> +<p>For object file formats such as <code>COFF</code> or <code>ELF</code> which support +arbitrary section names, <small>GNU</small> C++ will normally arrange to put the +addresses of global constructors and destructors into the <code>.ctors</code> +and <code>.dtors</code> sections. Placing the following sequence into your +linker script will build the sort of table which the <small>GNU</small> C++ +runtime code expects to see. +</p> +<div class="smallexample"> +<pre class="smallexample"> __CTOR_LIST__ = .; + LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) + *(.ctors) + LONG(0) + __CTOR_END__ = .; + __DTOR_LIST__ = .; + LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) + *(.dtors) + LONG(0) + __DTOR_END__ = .; +</pre></div> + +<p>If you are using the <small>GNU</small> C++ support for initialization priority, +which provides some control over the order in which global constructors +are run, you must sort the constructors at link time to ensure that they +are executed in the correct order. When using the <code>CONSTRUCTORS</code> +command, use ‘<samp>SORT_BY_NAME(CONSTRUCTORS)</samp>’ instead. When using the +<code>.ctors</code> and <code>.dtors</code> sections, use ‘<samp>*(SORT_BY_NAME(.ctors))</samp>’ and +‘<samp>*(SORT_BY_NAME(.dtors))</samp>’ instead of just ‘<samp>*(.ctors)</samp>’ and +‘<samp>*(.dtors)</samp>’. +</p> +<p>Normally the compiler and linker will handle these issues automatically, +and you will not need to concern yourself with them. However, you may +need to consider this if you are using C++ and writing your own linker +scripts. +</p> +</dd> +</dl> + +<hr> +<a name="Output-Section-Discarding"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Attributes" accesskey="n" rel="next">Output Section Attributes</a>, Previous: <a href="#Output-Section-Keywords" accesskey="p" rel="previous">Output Section Keywords</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Discarding-1"></a> +<h4 class="subsection">3.6.7 Output Section Discarding</h4> +<a name="index-discarding-sections"></a> +<a name="index-sections_002c-discarding"></a> +<a name="index-removing-sections"></a> +<p>The linker will not normally create output sections with no contents. +This is for convenience when referring to input sections that may or +may not be present in any of the input files. For example: +</p><div class="smallexample"> +<pre class="smallexample">.foo : { *(.foo) } +</pre></div> +<p>will only create a ‘<samp>.foo</samp>’ section in the output file if there is a +‘<samp>.foo</samp>’ section in at least one input file, and if the input +sections are not all empty. Other link script directives that allocate +space in an output section will also create the output section. So +too will assignments to dot even if the assignment does not create +space, except for ‘<samp>. = 0</samp>’, ‘<samp>. = . + 0</samp>’, ‘<samp>. = sym</samp>’, +‘<samp>. = . + sym</samp>’ and ‘<samp>. = ALIGN (. != 0, expr, 1)</samp>’ when +‘<samp>sym</samp>’ is an absolute symbol of value 0 defined in the script. +This allows you to force output of an empty section with ‘<samp>. = .</samp>’. +</p> +<p>The linker will ignore address assignments (see <a href="#Output-Section-Address">Output Section Address</a>) +on discarded output sections, except when the linker script defines +symbols in the output section. In that case the linker will obey +the address assignments, possibly advancing dot even though the +section is discarded. +</p> +<a name="index-_002fDISCARD_002f"></a> +<p>The special output section name ‘<samp>/DISCARD/</samp>’ may be used to discard +input sections. Any input sections which are assigned to an output +section named ‘<samp>/DISCARD/</samp>’ are not included in the output file. +</p> +<p>This can be used to discard input sections marked with the ELF flag +<code>SHF_GNU_RETAIN</code>, which would otherwise have been saved from linker +garbage collection. +</p> +<p>Note, sections that match the ‘<samp>/DISCARD/</samp>’ 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. +</p> +<hr> +<a name="Output-Section-Attributes"></a> +<div class="header"> +<p> +Next: <a href="#Overlay-Description" accesskey="n" rel="next">Overlay Description</a>, Previous: <a href="#Output-Section-Discarding" accesskey="p" rel="previous">Output Section Discarding</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Attributes-1"></a> +<h4 class="subsection">3.6.8 Output Section Attributes</h4> +<a name="index-output-section-attributes"></a> +<p>We showed above that the full description of an output section looked +like this: +</p> +<div class="smallexample"> +<pre class="smallexample"><var>section</var> [<var>address</var>] [(<var>type</var>)] : + [AT(<var>lma</var>)] + [ALIGN(<var>section_align</var>) | ALIGN_WITH_INPUT] + [SUBALIGN(<var>subsection_align</var>)] + [<var>constraint</var>] + { + <var>output-section-command</var> + <var>output-section-command</var> + … + } [><var>region</var>] [AT><var>lma_region</var>] [:<var>phdr</var> :<var>phdr</var> …] [=<var>fillexp</var>] +</pre></div> + +<p>We’ve already described <var>section</var>, <var>address</var>, and +<var>output-section-command</var>. In this section we will describe the +remaining section attributes. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Output-Section-Type" accesskey="1">Output Section Type</a>:</td><td> </td><td align="left" valign="top">Output section type +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-LMA" accesskey="2">Output Section LMA</a>:</td><td> </td><td align="left" valign="top">Output section LMA +</td></tr> +<tr><td align="left" valign="top">• <a href="#Forced-Output-Alignment" accesskey="3">Forced Output Alignment</a>:</td><td> </td><td align="left" valign="top">Forced Output Alignment +</td></tr> +<tr><td align="left" valign="top">• <a href="#Forced-Input-Alignment" accesskey="4">Forced Input Alignment</a>:</td><td> </td><td align="left" valign="top">Forced Input Alignment +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Constraint" accesskey="5">Output Section Constraint</a>:</td><td> </td><td align="left" valign="top">Output section constraint +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Region" accesskey="6">Output Section Region</a>:</td><td> </td><td align="left" valign="top">Output section region +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Phdr" accesskey="7">Output Section Phdr</a>:</td><td> </td><td align="left" valign="top">Output section phdr +</td></tr> +<tr><td align="left" valign="top">• <a href="#Output-Section-Fill" accesskey="8">Output Section Fill</a>:</td><td> </td><td align="left" valign="top">Output section fill +</td></tr> +</table> + +<hr> +<a name="Output-Section-Type"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-LMA" accesskey="n" rel="next">Output Section LMA</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Type-1"></a> +<h4 class="subsubsection">3.6.8.1 Output Section Type</h4> +<p>Each output section may have a type. The type is a keyword in +parentheses. The following types are defined: +</p> +<dl compact="compact"> +<dt><code>NOLOAD</code></dt> +<dd><p>The section should be marked as not loadable, so that it will not be +loaded into memory when the program is run. +</p> +</dd> +<dt><code>READONLY</code></dt> +<dd><p>The section should be marked as read-only. +</p> +</dd> +<dt><code>DSECT</code></dt> +<dt><code>COPY</code></dt> +<dt><code>INFO</code></dt> +<dt><code>OVERLAY</code></dt> +<dd><p>These type names are supported for backward compatibility, and are +rarely used. They all have the same effect: the section should be +marked as not allocatable, so that no memory is allocated for the +section when the program is run. +</p> +</dd> +<dt><code>TYPE = <var>type</var></code></dt> +<dd><p>Set the section type to the integer <var>type</var>. When generating an ELF +output file, type names <code>SHT_PROGBITS</code>, <code>SHT_STRTAB</code>, +<code>SHT_NOTE</code>, <code>SHT_NOBITS</code>, <code>SHT_INIT_ARRAY</code>, +<code>SHT_FINI_ARRAY</code>, and <code>SHT_PREINIT_ARRAY</code> are also allowed +for <var>type</var>. It is the user’s responsibility to ensure that any +special requirements of the section type are met. +</p> +<p>Note - the TYPE only is used if some or all of the contents of the +section do not have an implicit type of their own. So for example: +</p><div class="smallexample"> +<pre class="smallexample"> .foo . TYPE = SHT_PROGBITS { *(.bar) } +</pre></div> +<p>will set the type of section ‘<samp>.foo</samp>’ to the type of the section +‘<samp>.bar</samp>’ in the input files, which may not be the SHT_PROGBITS +type. Whereas: +</p><div class="smallexample"> +<pre class="smallexample"> .foo . TYPE = SHT_PROGBITS { BYTE(1) } +</pre></div> +<p>will set the type of ‘<samp>.foo</samp>’ to SHT_PROGBBITS. If it is necessary +to override the type of incoming sections and force the output section +type then an extra piece of untyped data will be needed: +</p><div class="smallexample"> +<pre class="smallexample"> .foo . TYPE = SHT_PROGBITS { BYTE(1); *(.bar) } +</pre></div> + +</dd> +<dt><code>READONLY ( TYPE = <var>type</var> )</code></dt> +<dd><p>This form of the syntax combines the <var>READONLY</var> type with the +type specified by <var>type</var>. +</p> +</dd> +</dl> + +<a name="index-NOLOAD"></a> +<a name="index-prevent-unnecessary-loading"></a> +<a name="index-loading_002c-preventing"></a> +<p>The linker normally sets the attributes of an output section based on +the input sections which map into it. You can override this by using +the section type. For example, in the script sample below, the +‘<samp>ROM</samp>’ section is addressed at memory location ‘<samp>0</samp>’ and does not +need to be loaded when the program is run. +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { + ROM 0 (NOLOAD) : { … } + … +} +</pre></div> + +<hr> +<a name="Output-Section-LMA"></a> +<div class="header"> +<p> +Next: <a href="#Forced-Output-Alignment" accesskey="n" rel="next">Forced Output Alignment</a>, Previous: <a href="#Output-Section-Type" accesskey="p" rel="previous">Output Section Type</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-LMA-1"></a> +<h4 class="subsubsection">3.6.8.2 Output Section LMA</h4> +<a name="index-AT_003elma_005fregion"></a> +<a name="index-AT_0028lma_0029"></a> +<a name="index-load-address"></a> +<a name="index-section-load-address"></a> +<p>Every section has a virtual address (VMA) and a load address (LMA); see +<a href="#Basic-Script-Concepts">Basic Script Concepts</a>. The virtual address is specified by the +see <a href="#Output-Section-Address">Output Section Address</a> described earlier. The load address is +specified by the <code>AT</code> or <code>AT></code> keywords. Specifying a load +address is optional. +</p> +<p>The <code>AT</code> keyword takes an expression as an argument. This +specifies the exact load address of the section. The <code>AT></code> keyword +takes the name of a memory region as an argument. See <a href="#MEMORY">MEMORY</a>. The +load address of the section is set to the next free address in the +region, aligned to the section’s alignment requirements. +</p> +<p>If neither <code>AT</code> nor <code>AT></code> is specified for an allocatable +section, the linker will use the following heuristic to determine the +load address: +</p> +<ul> +<li> If the section has a specific VMA address, then this is used as +the LMA address as well. + +</li><li> If the section is not allocatable then its LMA is set to its VMA. + +</li><li> Otherwise if a memory region can be found that is compatible +with the current section, and this region contains at least one +section, then the LMA is set so the difference between the +VMA and LMA is the same as the difference between the VMA and LMA of +the last section in the located region. + +</li><li> If no memory regions have been declared then a default region +that covers the entire address space is used in the previous step. + +</li><li> If no suitable region could be found, or there was no previous +section then the LMA is set equal to the VMA. +</li></ul> + +<a name="index-ROM-initialized-data"></a> +<a name="index-initialized-data-in-ROM"></a> +<p>This feature is designed to make it easy to build a ROM image. For +example, the following linker script creates three output sections: one +called ‘<samp>.text</samp>’, which starts at <code>0x1000</code>, one called +‘<samp>.mdata</samp>’, which is loaded at the end of the ‘<samp>.text</samp>’ section +even though its VMA is <code>0x2000</code>, and one called ‘<samp>.bss</samp>’ to hold +uninitialized data at address <code>0x3000</code>. The symbol <code>_data</code> is +defined with the value <code>0x2000</code>, which shows that the location +counter holds the VMA value, not the LMA value. +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS + { + .text 0x1000 : { *(.text) _etext = . ; } + .mdata 0x2000 : + AT ( ADDR (.text) + SIZEOF (.text) ) + { _data = . ; *(.data); _edata = . ; } + .bss 0x3000 : + { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} +} +</pre></div> + +<p>The run-time initialization code for use with a program generated with +this linker script would include something like the following, to copy +the initialized data from the ROM image to its runtime address. Notice +how this code takes advantage of the symbols defined by the linker +script. +</p> +<div class="smallexample"> +<pre class="smallexample">extern char _etext, _data, _edata, _bstart, _bend; +char *src = &_etext; +char *dst = &_data; + +/* ROM has data at end of text; copy it. */ +while (dst < &_edata) + *dst++ = *src++; + +/* Zero bss. */ +for (dst = &_bstart; dst< &_bend; dst++) + *dst = 0; +</pre></div> + +<hr> +<a name="Forced-Output-Alignment"></a> +<div class="header"> +<p> +Next: <a href="#Forced-Input-Alignment" accesskey="n" rel="next">Forced Input Alignment</a>, Previous: <a href="#Output-Section-LMA" accesskey="p" rel="previous">Output Section LMA</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Forced-Output-Alignment-1"></a> +<h4 class="subsubsection">3.6.8.3 Forced Output Alignment</h4> +<a name="index-ALIGN_0028section_005falign_0029"></a> +<a name="index-forcing-output-section-alignment"></a> +<a name="index-output-section-alignment"></a> +<p>You can increase an output section’s alignment by using ALIGN. As an +alternative you can enforce that the difference between the VMA and LMA remains +intact throughout this output section with the ALIGN_WITH_INPUT attribute. +</p> +<hr> +<a name="Forced-Input-Alignment"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Constraint" accesskey="n" rel="next">Output Section Constraint</a>, Previous: <a href="#Forced-Output-Alignment" accesskey="p" rel="previous">Forced Output Alignment</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Forced-Input-Alignment-1"></a> +<h4 class="subsubsection">3.6.8.4 Forced Input Alignment</h4> +<a name="index-SUBALIGN_0028subsection_005falign_0029"></a> +<a name="index-forcing-input-section-alignment"></a> +<a name="index-input-section-alignment"></a> +<p>You can force input section alignment within an output section by using +SUBALIGN. The value specified overrides any alignment given by input +sections, whether larger or smaller. +</p> +<hr> +<a name="Output-Section-Constraint"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Region" accesskey="n" rel="next">Output Section Region</a>, Previous: <a href="#Forced-Input-Alignment" accesskey="p" rel="previous">Forced Input Alignment</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Constraint-1"></a> +<h4 class="subsubsection">3.6.8.5 Output Section Constraint</h4> +<a name="index-ONLY_005fIF_005fRO"></a> +<a name="index-ONLY_005fIF_005fRW"></a> +<a name="index-constraints-on-output-sections"></a> +<p>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</code> and +<code>ONLY_IF_RW</code> respectively. +</p> +<hr> +<a name="Output-Section-Region"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Phdr" accesskey="n" rel="next">Output Section Phdr</a>, Previous: <a href="#Output-Section-Constraint" accesskey="p" rel="previous">Output Section Constraint</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Region-1"></a> +<h4 class="subsubsection">3.6.8.6 Output Section Region</h4> +<a name="index-_003eregion"></a> +<a name="index-section_002c-assigning-to-memory-region"></a> +<a name="index-memory-regions-and-sections"></a> +<p>You can assign a section to a previously defined region of memory by +using ‘<samp>><var>region</var></samp>’. See <a href="#MEMORY">MEMORY</a>. +</p> +<p>Here is a simple example: +</p><div class="smallexample"> +<pre class="smallexample">MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } +SECTIONS { ROM : { *(.text) } >rom } +</pre></div> + +<hr> +<a name="Output-Section-Phdr"></a> +<div class="header"> +<p> +Next: <a href="#Output-Section-Fill" accesskey="n" rel="next">Output Section Fill</a>, Previous: <a href="#Output-Section-Region" accesskey="p" rel="previous">Output Section Region</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Phdr-1"></a> +<h4 class="subsubsection">3.6.8.7 Output Section Phdr</h4> +<a name="index-_003aphdr"></a> +<a name="index-section_002c-assigning-to-program-header"></a> +<a name="index-program-headers-and-sections"></a> +<p>You can assign a section to a previously defined program segment by +using ‘<samp>:<var>phdr</var></samp>’. See <a href="#PHDRS">PHDRS</a>. If a section is assigned to +one or more segments, then all subsequent allocated sections will be +assigned to those segments as well, unless they use an explicitly +<code>:<var>phdr</var></code> modifier. You can use <code>:NONE</code> to tell the +linker to not put the section in any segment at all. +</p> +<p>Here is a simple example: +</p><div class="smallexample"> +<pre class="smallexample">PHDRS { text PT_LOAD ; } +SECTIONS { .text : { *(.text) } :text } +</pre></div> + +<hr> +<a name="Output-Section-Fill"></a> +<div class="header"> +<p> +Previous: <a href="#Output-Section-Phdr" accesskey="p" rel="previous">Output Section Phdr</a>, Up: <a href="#Output-Section-Attributes" accesskey="u" rel="up">Output Section Attributes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Output-Section-Fill-1"></a> +<h4 class="subsubsection">3.6.8.8 Output Section Fill</h4> +<a name="index-_003dfillexp"></a> +<a name="index-section-fill-pattern"></a> +<a name="index-fill-pattern_002c-entire-section"></a> +<p>You can set the fill pattern for an entire section by using +‘<samp>=<var>fillexp</var></samp>’. <var>fillexp</var> is an expression +(see <a href="#Expressions">Expressions</a>). Any otherwise unspecified regions of memory +within the output section (for example, gaps left due to the required +alignment of input sections) will be filled with the value, repeated as +necessary. If the fill expression is a simple hex number, ie. a string +of hex digit starting with ‘<samp>0x</samp>’ and without a trailing ‘<samp>k</samp>’ or ‘<samp>M</samp>’, then +an arbitrarily long sequence of hex digits can be used to specify the +fill pattern; Leading zeros become part of the pattern too. For all +other cases, including extra parentheses or a unary <code>+</code>, the fill +pattern is the four least significant bytes of the value of the +expression. In all cases, the number is big-endian. +</p> +<p>You can also change the fill value with a <code>FILL</code> command in the +output section commands; (see <a href="#Output-Section-Data">Output Section Data</a>). +</p> +<p>Here is a simple example: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { .text : { *(.text) } =0x90909090 } +</pre></div> + +<hr> +<a name="Overlay-Description"></a> +<div class="header"> +<p> +Previous: <a href="#Output-Section-Attributes" accesskey="p" rel="previous">Output Section Attributes</a>, Up: <a href="#SECTIONS" accesskey="u" rel="up">SECTIONS</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Overlay-Description-1"></a> +<h4 class="subsection">3.6.9 Overlay Description</h4> +<a name="index-OVERLAY"></a> +<a name="index-overlays"></a> +<p>An overlay description provides an easy way to describe sections which +are to be loaded as part of a single memory image but are to be run at +the same memory address. At run time, some sort of overlay manager will +copy the overlaid sections in and out of the runtime memory address as +required, perhaps by simply manipulating addressing bits. This approach +can be useful, for example, when a certain region of memory is faster +than another. +</p> +<p>Overlays are described using the <code>OVERLAY</code> command. The +<code>OVERLAY</code> command is used within a <code>SECTIONS</code> command, like an +output section description. The full syntax of the <code>OVERLAY</code> +command is as follows: +</p><div class="smallexample"> +<pre class="smallexample">OVERLAY [<var>start</var>] : [NOCROSSREFS] [AT ( <var>ldaddr</var> )] + { + <var>secname1</var> + { + <var>output-section-command</var> + <var>output-section-command</var> + … + } [:<var>phdr</var>…] [=<var>fill</var>] + <var>secname2</var> + { + <var>output-section-command</var> + <var>output-section-command</var> + … + } [:<var>phdr</var>…] [=<var>fill</var>] + … + } [><var>region</var>] [:<var>phdr</var>…] [=<var>fill</var>] [,] +</pre></div> + +<p>Everything is optional except <code>OVERLAY</code> (a keyword), and each +section must have a name (<var>secname1</var> and <var>secname2</var> above). The +section definitions within the <code>OVERLAY</code> construct are identical to +those within the general <code>SECTIONS</code> construct (see <a href="#SECTIONS">SECTIONS</a>), +except that no addresses and no memory regions may be defined for +sections within an <code>OVERLAY</code>. +</p> +<p>The comma at the end may be required if a <var>fill</var> is used and +the next <var>sections-command</var> looks like a continuation of the expression. +</p> +<p>The sections are all defined with the same starting address. The load +addresses of the sections are arranged such that they are consecutive in +memory starting at the load address used for the <code>OVERLAY</code> as a +whole (as with normal section definitions, the load address is optional, +and defaults to the start address; the start address is also optional, +and defaults to the current value of the location counter). +</p> +<p>If the <code>NOCROSSREFS</code> keyword is used, and there are any +references among the sections, the linker will report an error. Since +the sections all run at the same address, it normally does not make +sense for one section to refer directly to another. +See <a href="#Miscellaneous-Commands">NOCROSSREFS</a>. +</p> +<p>For each section within the <code>OVERLAY</code>, the linker automatically +provides two symbols. The symbol <code>__load_start_<var>secname</var></code> is +defined as the starting load address of the section. The symbol +<code>__load_stop_<var>secname</var></code> is defined as the final load address of +the section. Any characters within <var>secname</var> which are not legal +within C identifiers are removed. C (or assembler) code may use these +symbols to move the overlaid sections around as necessary. +</p> +<p>At the end of the overlay, the value of the location counter is set to +the start address of the overlay plus the size of the largest section. +</p> +<p>Here is an example. Remember that this would appear inside a +<code>SECTIONS</code> construct. +</p><div class="smallexample"> +<pre class="smallexample"> OVERLAY 0x1000 : AT (0x4000) + { + .text0 { o1/*.o(.text) } + .text1 { o2/*.o(.text) } + } +</pre></div> +<p>This will define both ‘<samp>.text0</samp>’ and ‘<samp>.text1</samp>’ to start at +address 0x1000. ‘<samp>.text0</samp>’ will be loaded at address 0x4000, and +‘<samp>.text1</samp>’ will be loaded immediately after ‘<samp>.text0</samp>’. The +following symbols will be defined if referenced: <code>__load_start_text0</code>, +<code>__load_stop_text0</code>, <code>__load_start_text1</code>, +<code>__load_stop_text1</code>. +</p> +<p>C code to copy overlay <code>.text1</code> into the overlay area might look +like the following. +</p> +<div class="smallexample"> +<pre class="smallexample"> extern char __load_start_text1, __load_stop_text1; + memcpy ((char *) 0x1000, &__load_start_text1, + &__load_stop_text1 - &__load_start_text1); +</pre></div> + +<p>Note that the <code>OVERLAY</code> command is just syntactic sugar, since +everything it does can be done using the more basic commands. The above +example could have been written identically as follows. +</p> +<div class="smallexample"> +<pre class="smallexample"> .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } + PROVIDE (__load_start_text0 = LOADADDR (.text0)); + PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } + PROVIDE (__load_start_text1 = LOADADDR (.text1)); + PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); +</pre></div> + +<hr> +<a name="MEMORY"></a> +<div class="header"> +<p> +Next: <a href="#PHDRS" accesskey="n" rel="next">PHDRS</a>, Previous: <a href="#SECTIONS" accesskey="p" rel="previous">SECTIONS</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="MEMORY-Command"></a> +<h3 class="section">3.7 MEMORY Command</h3> +<a name="index-MEMORY"></a> +<a name="index-memory-regions"></a> +<a name="index-regions-of-memory"></a> +<a name="index-allocating-memory"></a> +<a name="index-discontinuous-memory"></a> +<p>The linker’s default configuration permits allocation of all available +memory. You can override this by using the <code>MEMORY</code> command. +</p> +<p>The <code>MEMORY</code> command describes the location and size of blocks of +memory in the target. You can use it to describe which memory regions +may be used by the linker, and which memory regions it must avoid. You +can then assign sections to particular memory regions. The linker will +set section addresses based on the memory regions, and will warn about +regions that become too full. The linker will not shuffle sections +around to fit into the available regions. +</p> +<p>A linker script may contain many uses of the <code>MEMORY</code> command, +however, all memory blocks defined are treated as if they were +specified inside a single <code>MEMORY</code> command. The syntax for +<code>MEMORY</code> is: +</p><div class="smallexample"> +<pre class="smallexample">MEMORY + { + <var>name</var> [(<var>attr</var>)] : ORIGIN = <var>origin</var>, LENGTH = <var>len</var> + … + } +</pre></div> + +<p>The <var>name</var> is a name used in the linker script to refer to the +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 within the <code>MEMORY</code> command. However you can +add later alias names to existing memory regions with the <a href="#REGION_005fALIAS">REGION_ALIAS</a> +command. +</p> +<a name="index-memory-region-attributes"></a> +<p>The <var>attr</var> string is an optional list of attributes that specify +whether to use a particular memory region for an input section which is +not explicitly mapped in the linker script. As described in +<a href="#SECTIONS">SECTIONS</a>, if you do not specify an output section for some input +section, the linker will create an output section with the same name as +the input section. If you define region attributes, the linker will use +them to select the memory region for the output section that it creates. +</p> +<p>The <var>attr</var> string must consist only of the following characters: +</p><dl compact="compact"> +<dt>‘<samp>R</samp>’</dt> +<dd><p>Read-only section +</p></dd> +<dt>‘<samp>W</samp>’</dt> +<dd><p>Read/write section +</p></dd> +<dt>‘<samp>X</samp>’</dt> +<dd><p>Executable section +</p></dd> +<dt>‘<samp>A</samp>’</dt> +<dd><p>Allocatable section +</p></dd> +<dt>‘<samp>I</samp>’</dt> +<dd><p>Initialized section +</p></dd> +<dt>‘<samp>L</samp>’</dt> +<dd><p>Same as ‘<samp>I</samp>’ +</p></dd> +<dt>‘<samp>!</samp>’</dt> +<dd><p>Invert the sense of any of the attributes that follow +</p></dd> +</dl> + +<p>If an unmapped section matches any of the listed attributes other than +‘<samp>!</samp>’, it will be placed in the memory region. The ‘<samp>!</samp>’ +attribute reverses the test for the characters that follow, so that an +unmapped section will be placed in the memory region only if it does +not match any of the attributes listed afterwards. Thus an attribute +string of ‘<samp>RW!X</samp>’ will match any unmapped section that has either +or both of the ‘<samp>R</samp>’ and ‘<samp>W</samp>’ attributes, but only as long as +the section does not also have the ‘<samp>X</samp>’ attribute. +</p> +<a name="index-ORIGIN-_003d"></a> +<a name="index-o-_003d"></a> +<a name="index-org-_003d"></a> +<p>The <var>origin</var> is an numerical expression for the start address of +the memory region. The expression must evaluate to a constant and it +cannot involve any symbols. The keyword <code>ORIGIN</code> may be +abbreviated to <code>org</code> or <code>o</code> (but not, for example, +<code>ORG</code>). +</p> +<a name="index-LENGTH-_003d"></a> +<a name="index-len-_003d"></a> +<a name="index-l-_003d"></a> +<p>The <var>len</var> is an expression for the size in bytes of the memory +region. As with the <var>origin</var> expression, the expression must +be numerical only and must evaluate to a constant. The keyword +<code>LENGTH</code> may be abbreviated to <code>len</code> or <code>l</code>. +</p> +<p>In the following example, we specify that there are two memory regions +available for allocation: one starting at ‘<samp>0</samp>’ for 256 kilobytes, +and the other starting at ‘<samp>0x40000000</samp>’ for four megabytes. The +linker will place into the ‘<samp>rom</samp>’ memory region every section which +is not explicitly mapped into a memory region, and is either read-only +or executable. The linker will place other sections which are not +explicitly mapped into a memory region into the ‘<samp>ram</samp>’ memory +region. +</p> +<div class="smallexample"> +<pre class="smallexample">MEMORY + { + rom (rx) : ORIGIN = 0, LENGTH = 256K + ram (!rx) : org = 0x40000000, l = 4M + } +</pre></div> + +<p>Once you define a memory region, you can direct the linker to place +specific output sections into that memory region by using the +‘<samp>><var>region</var></samp>’ output section attribute. For example, if you have +a memory region named ‘<samp>mem</samp>’, you would use ‘<samp>>mem</samp>’ in the +output section definition. See <a href="#Output-Section-Region">Output Section Region</a>. If no address +was specified for the output section, the linker will set the address to +the next available address within the memory region. If the combined +output sections directed to a memory region are too large for the +region, the linker will issue an error message. +</p> +<p>It is possible to access the origin and length of a memory in an +expression via the <code>ORIGIN(<var>memory</var>)</code> and +<code>LENGTH(<var>memory</var>)</code> functions: +</p> +<div class="smallexample"> +<pre class="smallexample"> _fstack = ORIGIN(ram) + LENGTH(ram) - 4; +</pre></div> + +<hr> +<a name="PHDRS"></a> +<div class="header"> +<p> +Next: <a href="#VERSION" accesskey="n" rel="next">VERSION</a>, Previous: <a href="#MEMORY" accesskey="p" rel="previous">MEMORY</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="PHDRS-Command"></a> +<h3 class="section">3.8 PHDRS Command</h3> +<a name="index-PHDRS"></a> +<a name="index-program-headers"></a> +<a name="index-ELF-program-headers"></a> +<a name="index-program-segments"></a> +<a name="index-segments_002c-ELF"></a> +<p>The ELF object file format uses <em>program headers</em>, also knows as +<em>segments</em>. The program headers describe how the program should be +loaded into memory. You can print them out by using the <code>objdump</code> +program with the ‘<samp>-p</samp>’ option. +</p> +<p>When you run an ELF program on a native ELF system, the system loader +reads the program headers in order to figure out how to load the +program. This will only work if the program headers are set correctly. +This manual does not describe the details of how the system loader +interprets program headers; for more information, see the ELF ABI. +</p> +<p>The linker will create reasonable program headers by default. However, +in some cases, you may need to specify the program headers more +precisely. You may use the <code>PHDRS</code> command for this purpose. When +the linker sees the <code>PHDRS</code> command in the linker script, it will +not create any program headers other than the ones specified. +</p> +<p>The linker only pays attention to the <code>PHDRS</code> command when +generating an ELF output file. In other cases, the linker will simply +ignore <code>PHDRS</code>. +</p> +<p>This is the syntax of the <code>PHDRS</code> command. The words <code>PHDRS</code>, +<code>FILEHDR</code>, <code>AT</code>, and <code>FLAGS</code> are keywords. +</p> +<div class="smallexample"> +<pre class="smallexample">PHDRS +{ + <var>name</var> <var>type</var> [ FILEHDR ] [ PHDRS ] [ AT ( <var>address</var> ) ] + [ FLAGS ( <var>flags</var> ) ] ; +} +</pre></div> + +<p>The <var>name</var> is used only for reference in the <code>SECTIONS</code> command +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. The headers are processed in order and it +is usual for them to map to sections in ascending load address order. +</p> +<p>Certain program header types describe segments of memory which the +system loader will load from the file. In the linker script, you +specify the contents of these segments by placing allocatable output +sections in the segments. You use the ‘<samp>:<var>phdr</var></samp>’ output section +attribute to place a section in a particular segment. See <a href="#Output-Section-Phdr">Output Section Phdr</a>. +</p> +<p>It is normal to put certain sections in more than one segment. This +merely implies that one segment of memory contains another. You may +repeat ‘<samp>:<var>phdr</var></samp>’, using it once for each segment which should +contain the section. +</p> +<p>If you place a section in one or more segments using ‘<samp>:<var>phdr</var></samp>’, +then the linker will place all subsequent allocatable sections which do +not specify ‘<samp>:<var>phdr</var></samp>’ in the same segments. This is for +convenience, since generally a whole set of contiguous sections will be +placed in a single segment. You can use <code>:NONE</code> to override the +default segment and tell the linker to not put the section in any +segment at all. +</p> +<a name="index-FILEHDR"></a> +<a name="index-PHDRS-1"></a> +<p>You may use the <code>FILEHDR</code> and <code>PHDRS</code> keywords after +the program header type to further describe the contents of the segment. +The <code>FILEHDR</code> keyword means that the segment should include the ELF +file header. The <code>PHDRS</code> keyword means that the segment should +include the ELF program headers themselves. If applied to a loadable +segment (<code>PT_LOAD</code>), all prior loadable segments must have one of +these keywords. +</p> +<p>The <var>type</var> may be one of the following. The numbers indicate the +value of the keyword. +</p> +<dl compact="compact"> +<dt><code>PT_NULL</code> (0)</dt> +<dd><p>Indicates an unused program header. +</p> +</dd> +<dt><code>PT_LOAD</code> (1)</dt> +<dd><p>Indicates that this program header describes a segment to be loaded from +the file. +</p> +</dd> +<dt><code>PT_DYNAMIC</code> (2)</dt> +<dd><p>Indicates a segment where dynamic linking information can be found. +</p> +</dd> +<dt><code>PT_INTERP</code> (3)</dt> +<dd><p>Indicates a segment where the name of the program interpreter may be +found. +</p> +</dd> +<dt><code>PT_NOTE</code> (4)</dt> +<dd><p>Indicates a segment holding note information. +</p> +</dd> +<dt><code>PT_SHLIB</code> (5)</dt> +<dd><p>A reserved program header type, defined but not specified by the ELF +ABI. +</p> +</dd> +<dt><code>PT_PHDR</code> (6)</dt> +<dd><p>Indicates a segment where the program headers may be found. +</p> +</dd> +<dt><code>PT_TLS</code> (7)</dt> +<dd><p>Indicates a segment containing thread local storage. +</p> +</dd> +<dt><var>expression</var></dt> +<dd><p>An expression giving the numeric type of the program header. This may +be used for types not defined above. +</p></dd> +</dl> + +<p>You can specify that a segment should be loaded at a particular address +in memory by using an <code>AT</code> expression. This is identical to the +<code>AT</code> command used as an output section attribute (see <a href="#Output-Section-LMA">Output Section LMA</a>). The <code>AT</code> command for a program header overrides the +output section attribute. +</p> +<p>The linker will normally set the segment flags based on the sections +which comprise the segment. You may use the <code>FLAGS</code> keyword to +explicitly specify the segment flags. The value of <var>flags</var> must be +an integer. It is used to set the <code>p_flags</code> field of the program +header. +</p> +<p>Here is an example of <code>PHDRS</code>. This shows a typical set of program +headers used on a native ELF system. +</p> +<div class="example"> +<pre class="example">PHDRS +{ + headers PT_PHDR PHDRS ; + interp PT_INTERP ; + text PT_LOAD FILEHDR PHDRS ; + data PT_LOAD ; + dynamic PT_DYNAMIC ; +} + +SECTIONS +{ + . = SIZEOF_HEADERS; + .interp : { *(.interp) } :text :interp + .text : { *(.text) } :text + .rodata : { *(.rodata) } /* defaults to :text */ + … + . = . + 0x1000; /* move to a new page in memory */ + .data : { *(.data) } :data + .dynamic : { *(.dynamic) } :data :dynamic + … +} +</pre></div> + +<hr> +<a name="VERSION"></a> +<div class="header"> +<p> +Next: <a href="#Expressions" accesskey="n" rel="next">Expressions</a>, Previous: <a href="#PHDRS" accesskey="p" rel="previous">PHDRS</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="VERSION-Command"></a> +<h3 class="section">3.9 VERSION Command</h3> +<a name="index-VERSION-_007bscript-text_007d"></a> +<a name="index-symbol-versions"></a> +<a name="index-version-script"></a> +<a name="index-versions-of-symbols"></a> +<p>The linker supports symbol versions when using ELF. Symbol versions are +only useful when using shared libraries. The dynamic linker can use +symbol versions to select a specific version of a function when it runs +a program that may have been linked against an earlier version of the +shared library. +</p> +<p>You can include a version script directly in the main linker script, or +you can supply the version script as an implicit linker script. You can +also use the ‘<samp>--version-script</samp>’ linker option. +</p> +<p>The syntax of the <code>VERSION</code> command is simply +</p><div class="smallexample"> +<pre class="smallexample">VERSION { version-script-commands } +</pre></div> + +<p>The format of the version script commands is identical to that used by +Sun’s linker in Solaris 2.5. The version script defines a tree of +version nodes. You specify the node names and interdependencies in the +version script. You can specify which symbols are bound to which +version nodes, and you can reduce a specified set of symbols to local +scope so that they are not globally visible outside of the shared +library. +</p> +<p>The easiest way to demonstrate the version script language is with a few +examples. +</p> +<div class="smallexample"> +<pre class="smallexample">VERS_1.1 { + global: + foo1; + local: + old*; + original*; + new*; +}; + +VERS_1.2 { + foo2; +} VERS_1.1; + +VERS_2.0 { + bar1; bar2; + extern "C++" { + ns::*; + "f(int, double)"; + }; +} VERS_1.2; +</pre></div> + +<p>This example version script defines three version nodes. The first +version node defined is ‘<samp>VERS_1.1</samp>’; it has no other dependencies. +The script binds the symbol ‘<samp>foo1</samp>’ to ‘<samp>VERS_1.1</samp>’. It reduces +a number of symbols to local scope so that they are not visible outside +of the shared library; this is done using wildcard patterns, so that any +symbol whose name begins with ‘<samp>old</samp>’, ‘<samp>original</samp>’, or ‘<samp>new</samp>’ +is matched. The wildcard patterns available are the same as those used +in the shell when matching filenames (also known as “globbing”). +However, if you specify the symbol name inside double quotes, then the +name is treated as literal, rather than as a glob pattern. +</p> +<p>Next, the version script defines node ‘<samp>VERS_1.2</samp>’. This node +depends upon ‘<samp>VERS_1.1</samp>’. The script binds the symbol ‘<samp>foo2</samp>’ +to the version node ‘<samp>VERS_1.2</samp>’. +</p> +<p>Finally, the version script defines node ‘<samp>VERS_2.0</samp>’. This node +depends upon ‘<samp>VERS_1.2</samp>’. The scripts binds the symbols ‘<samp>bar1</samp>’ +and ‘<samp>bar2</samp>’ are bound to the version node ‘<samp>VERS_2.0</samp>’. +</p> +<p>When the linker finds a symbol defined in a library which is not +specifically bound to a version node, it will effectively bind it to an +unspecified base version of the library. You can bind all otherwise +unspecified symbols to a given version node by using ‘<samp>global: *;</samp>’ +somewhere in the version script. Note that it’s slightly crazy to use +wildcards in a global spec except on the last version node. Global +wildcards elsewhere run the risk of accidentally adding symbols to the +set exported for an old version. That’s wrong since older versions +ought to have a fixed set of symbols. +</p> +<p>The names of the version nodes have no specific meaning other than what +they might suggest to the person reading them. The ‘<samp>2.0</samp>’ version +could just as well have appeared in between ‘<samp>1.1</samp>’ and ‘<samp>1.2</samp>’. +However, this would be a confusing way to write a version script. +</p> +<p>Node name can be omitted, provided it is the only version node +in the version script. Such version script doesn’t assign any versions to +symbols, only selects which symbols will be globally visible out and which +won’t. +</p> +<div class="smallexample"> +<pre class="smallexample">{ global: foo; bar; local: *; }; +</pre></div> + +<p>When you link an application against a shared library that has versioned +symbols, the application itself knows which version of each symbol it +requires, and it also knows which version nodes it needs from each +shared library it is linked against. Thus at runtime, the dynamic +loader can make a quick check to make sure that the libraries you have +linked against do in fact supply all of the version nodes that the +application will need to resolve all of the dynamic symbols. In this +way it is possible for the dynamic linker to know with certainty that +all external symbols that it needs will be resolvable without having to +search for each symbol reference. +</p> +<p>The symbol versioning is in effect a much more sophisticated way of +doing minor version checking that SunOS does. The fundamental problem +that is being addressed here is that typically references to external +functions are bound on an as-needed basis, and are not all bound when +the application starts up. If a shared library is out of date, a +required interface may be missing; when the application tries to use +that interface, it may suddenly and unexpectedly fail. With symbol +versioning, the user will get a warning when they start their program if +the libraries being used with the application are too old. +</p> +<p>There are several GNU extensions to Sun’s versioning approach. The +first of these is the ability to bind a symbol to a version node in the +source file where the symbol is defined instead of in the versioning +script. This was done mainly to reduce the burden on the library +maintainer. You can do this by putting something like: +</p><div class="smallexample"> +<pre class="smallexample">__asm__(".symver original_foo,foo@VERS_1.1"); +</pre></div> +<p>in the C source file. This renames the function ‘<samp>original_foo</samp>’ to +be an alias for ‘<samp>foo</samp>’ bound to the version node ‘<samp>VERS_1.1</samp>’. +The ‘<samp>local:</samp>’ directive can be used to prevent the symbol +‘<samp>original_foo</samp>’ from being exported. A ‘<samp>.symver</samp>’ directive +takes precedence over a version script. +</p> +<p>The second GNU extension is to allow multiple versions of the same +function to appear in a given shared library. In this way you can make +an incompatible change to an interface without increasing the major +version number of the shared library, while still allowing applications +linked against the old interface to continue to function. +</p> +<p>To do this, you must use multiple ‘<samp>.symver</samp>’ directives in the +source file. Here is an example: +</p> +<div class="smallexample"> +<pre class="smallexample">__asm__(".symver original_foo,foo@"); +__asm__(".symver old_foo,foo@VERS_1.1"); +__asm__(".symver old_foo1,foo@VERS_1.2"); +__asm__(".symver new_foo,foo@@VERS_2.0"); +</pre></div> + +<p>In this example, ‘<samp>foo@</samp>’ represents the symbol ‘<samp>foo</samp>’ bound to the +unspecified base version of the symbol. The source file that contains this +example would define 4 C functions: ‘<samp>original_foo</samp>’, ‘<samp>old_foo</samp>’, +‘<samp>old_foo1</samp>’, and ‘<samp>new_foo</samp>’. +</p> +<p>When you have multiple definitions of a given symbol, there needs to be +some way to specify a default version to which external references to +this symbol will be bound. You can do this with the +‘<samp>foo@@VERS_2.0</samp>’ type of ‘<samp>.symver</samp>’ directive. You can only +declare one version of a symbol as the default in this manner; otherwise +you would effectively have multiple definitions of the same symbol. +</p> +<p>If you wish to bind a reference to a specific version of the symbol +within the shared library, you can use the aliases of convenience +(i.e., ‘<samp>old_foo</samp>’), or you can use the ‘<samp>.symver</samp>’ directive to +specifically bind to an external version of the function in question. +</p> +<p>You can also specify the language in the version script: +</p> +<div class="smallexample"> +<pre class="smallexample">VERSION extern "lang" { version-script-commands } +</pre></div> + +<p>The supported ‘<samp>lang</samp>’s are ‘<samp>C</samp>’, ‘<samp>C++</samp>’, and ‘<samp>Java</samp>’. +The linker will iterate over the list of symbols at the link time and +demangle them according to ‘<samp>lang</samp>’ before matching them to the +patterns specified in ‘<samp>version-script-commands</samp>’. The default +‘<samp>lang</samp>’ is ‘<samp>C</samp>’. +</p> +<p>Demangled names may contains spaces and other special characters. As +described above, you can use a glob pattern to match demangled names, +or you can use a double-quoted string to match the string exactly. In +the latter case, be aware that minor differences (such as differing +whitespace) between the version script and the demangler output will +cause a mismatch. As the exact string generated by the demangler +might change in the future, even if the mangled name does not, you +should check that all of your version directives are behaving as you +expect when you upgrade. +</p> +<hr> +<a name="Expressions"></a> +<div class="header"> +<p> +Next: <a href="#Implicit-Linker-Scripts" accesskey="n" rel="next">Implicit Linker Scripts</a>, Previous: <a href="#VERSION" accesskey="p" rel="previous">VERSION</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Expressions-in-Linker-Scripts"></a> +<h3 class="section">3.10 Expressions in Linker Scripts</h3> +<a name="index-expressions"></a> +<a name="index-arithmetic"></a> +<p>The syntax for expressions in the linker script language is identical to +that of C expressions, except that whitespace is required in some +places to resolve syntactic ambiguities. All expressions are +evaluated as integers. All expressions are evaluated in the same +size, which is 32 bits if both the host and target are 32 bits, and is +otherwise 64 bits. +</p> +<p>You can use and set symbol values in expressions. +</p> +<p>The linker defines several special purpose builtin functions for use in +expressions. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Constants" accesskey="1">Constants</a>:</td><td> </td><td align="left" valign="top">Constants +</td></tr> +<tr><td align="left" valign="top">• <a href="#Symbolic-Constants" accesskey="2">Symbolic Constants</a>:</td><td> </td><td align="left" valign="top">Symbolic constants +</td></tr> +<tr><td align="left" valign="top">• <a href="#Symbols" accesskey="3">Symbols</a>:</td><td> </td><td align="left" valign="top">Symbol Names +</td></tr> +<tr><td align="left" valign="top">• <a href="#Orphan-Sections" accesskey="4">Orphan Sections</a>:</td><td> </td><td align="left" valign="top">Orphan Sections +</td></tr> +<tr><td align="left" valign="top">• <a href="#Location-Counter" accesskey="5">Location Counter</a>:</td><td> </td><td align="left" valign="top">The Location Counter +</td></tr> +<tr><td align="left" valign="top">• <a href="#Operators" accesskey="6">Operators</a>:</td><td> </td><td align="left" valign="top">Operators +</td></tr> +<tr><td align="left" valign="top">• <a href="#Evaluation" accesskey="7">Evaluation</a>:</td><td> </td><td align="left" valign="top">Evaluation +</td></tr> +<tr><td align="left" valign="top">• <a href="#Expression-Section" accesskey="8">Expression Section</a>:</td><td> </td><td align="left" valign="top">The Section of an Expression +</td></tr> +<tr><td align="left" valign="top">• <a href="#Builtin-Functions" accesskey="9">Builtin Functions</a>:</td><td> </td><td align="left" valign="top">Builtin Functions +</td></tr> +</table> + +<hr> +<a name="Constants"></a> +<div class="header"> +<p> +Next: <a href="#Symbolic-Constants" accesskey="n" rel="next">Symbolic Constants</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Constants-1"></a> +<h4 class="subsection">3.10.1 Constants</h4> +<a name="index-integer-notation"></a> +<a name="index-constants-in-linker-scripts"></a> +<p>All constants are integers. +</p> +<p>As in C, the linker considers an integer beginning with ‘<samp>0</samp>’ to be +octal, and an integer beginning with ‘<samp>0x</samp>’ or ‘<samp>0X</samp>’ to be +hexadecimal. Alternatively the linker accepts suffixes of ‘<samp>h</samp>’ or +‘<samp>H</samp>’ for hexadecimal, ‘<samp>o</samp>’ or ‘<samp>O</samp>’ for octal, ‘<samp>b</samp>’ or +‘<samp>B</samp>’ for binary and ‘<samp>d</samp>’ or ‘<samp>D</samp>’ for decimal. Any integer +value without a prefix or a suffix is considered to be decimal. +</p> +<a name="index-scaled-integers"></a> +<a name="index-K-and-M-integer-suffixes"></a> +<a name="index-M-and-K-integer-suffixes"></a> +<a name="index-suffixes-for-integers"></a> +<a name="index-integer-suffixes"></a> +<p>In addition, you can use the suffixes <code>K</code> and <code>M</code> to scale a +constant by +<code>1024</code> or <code>1024*1024</code> +respectively. For example, the following +all refer to the same quantity: +</p> +<div class="smallexample"> +<pre class="smallexample">_fourk_1 = 4K; +_fourk_2 = 4096; +_fourk_3 = 0x1000; +_fourk_4 = 10000o; +</pre></div> + +<p>Note - the <code>K</code> and <code>M</code> suffixes cannot be used in +conjunction with the base suffixes mentioned above. +</p> +<hr> +<a name="Symbolic-Constants"></a> +<div class="header"> +<p> +Next: <a href="#Symbols" accesskey="n" rel="next">Symbols</a>, Previous: <a href="#Constants" accesskey="p" rel="previous">Constants</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Symbolic-Constants-1"></a> +<h4 class="subsection">3.10.2 Symbolic Constants</h4> +<a name="index-symbolic-constants"></a> +<a name="index-CONSTANT"></a> +<p>It is possible to refer to target-specific constants via the use of +the <code>CONSTANT(<var>name</var>)</code> operator, where <var>name</var> is one of: +</p> +<dl compact="compact"> +<dt><code>MAXPAGESIZE</code></dt> +<dd><a name="index-MAXPAGESIZE"></a> +<p>The target’s maximum page size. +</p> +</dd> +<dt><code>COMMONPAGESIZE</code></dt> +<dd><a name="index-COMMONPAGESIZE"></a> +<p>The target’s default page size. +</p></dd> +</dl> + +<p>So for example: +</p> +<div class="smallexample"> +<pre class="smallexample"> .text ALIGN (CONSTANT (MAXPAGESIZE)) : { *(.text) } +</pre></div> + +<p>will create a text section aligned to the largest page boundary +supported by the target. +</p> +<hr> +<a name="Symbols"></a> +<div class="header"> +<p> +Next: <a href="#Orphan-Sections" accesskey="n" rel="next">Orphan Sections</a>, Previous: <a href="#Symbolic-Constants" accesskey="p" rel="previous">Symbolic Constants</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Symbol-Names"></a> +<h4 class="subsection">3.10.3 Symbol Names</h4> +<a name="index-symbol-names"></a> +<a name="index-names"></a> +<a name="index-quoted-symbol-names"></a> +<a name="index-_0022"></a> +<p>Unless quoted, symbol names start with a letter, underscore, or period +and may include letters, digits, underscores, periods, and hyphens. +Unquoted symbol names must not conflict with any keywords. You can +specify a symbol which contains odd characters or has the same name as a +keyword by surrounding the symbol name in double quotes: +</p><div class="smallexample"> +<pre class="smallexample">"SECTION" = 9; +"with a space" = "also with a space" + 10; +</pre></div> + +<p>Since symbols can contain many non-alphabetic characters, it is safest +to delimit symbols with spaces. For example, ‘<samp>A-B</samp>’ is one symbol, +whereas ‘<samp>A - B</samp>’ is an expression involving subtraction. +</p> +<hr> +<a name="Orphan-Sections"></a> +<div class="header"> +<p> +Next: <a href="#Location-Counter" accesskey="n" rel="next">Location Counter</a>, Previous: <a href="#Symbols" accesskey="p" rel="previous">Symbols</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Orphan-Sections-1"></a> +<h4 class="subsection">3.10.4 Orphan Sections</h4> +<a name="index-orphan"></a> +<p>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 by either finding, or creating a suitable output section +in which to place the orphaned input section. +</p> +<p>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. +</p> +<p>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. +</p> +<p>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. +</p> +<p>The command-line options ‘<samp>--orphan-handling</samp>’ and ‘<samp>--unique</samp>’ +(see <a href="#Options">Command-line Options</a>) can be used to control which +output sections an orphan is placed in. +</p> +<hr> +<a name="Location-Counter"></a> +<div class="header"> +<p> +Next: <a href="#Operators" accesskey="n" rel="next">Operators</a>, Previous: <a href="#Orphan-Sections" accesskey="p" rel="previous">Orphan Sections</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="The-Location-Counter"></a> +<h4 class="subsection">3.10.5 The Location Counter</h4> +<a name="index-_002e"></a> +<a name="index-dot"></a> +<a name="index-location-counter"></a> +<a name="index-current-output-location"></a> +<p>The special linker variable <em>dot</em> ‘<samp>.</samp>’ always contains the +current output location counter. Since the <code>.</code> always refers to a +location in an output section, it may only appear in an expression +within a <code>SECTIONS</code> command. The <code>.</code> symbol may appear +anywhere that an ordinary symbol is allowed in an expression. +</p> +<a name="index-holes"></a> +<p>Assigning a value to <code>.</code> will cause the location counter to be +moved. This may be used to create holes in the output section. The +location counter may not be moved backwards inside an output section, +and may not be moved backwards outside of an output section if so +doing creates areas with overlapping LMAs. +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + output : + { + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + } = 0x12345678; +} +</pre></div> +<p>In the previous example, the ‘<samp>.text</samp>’ section from <samp>file1</samp> is +located at the beginning of the output section ‘<samp>output</samp>’. It is +followed by a 1000 byte gap. Then the ‘<samp>.text</samp>’ section from +<samp>file2</samp> appears, also with a 1000 byte gap following before the +‘<samp>.text</samp>’ section from <samp>file3</samp>. The notation ‘<samp>= 0x12345678</samp>’ +specifies what data to write in the gaps (see <a href="#Output-Section-Fill">Output Section Fill</a>). +</p> +<a name="index-dot-inside-sections"></a> +<p>Note: <code>.</code> actually refers to the byte offset from the start of the +current containing object. Normally this is the <code>SECTIONS</code> +statement, whose start address is 0, hence <code>.</code> can be used as an +absolute address. If <code>.</code> is used inside a section description +however, it refers to the byte offset from the start of that section, +not an absolute address. Thus in a script like this: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + . = 0x100 + .text: { + *(.text) + . = 0x200 + } + . = 0x500 + .data: { + *(.data) + . += 0x600 + } +} +</pre></div> + +<p>The ‘<samp>.text</samp>’ section will be assigned a starting address of 0x100 +and a size of exactly 0x200 bytes, even if there is not enough data in +the ‘<samp>.text</samp>’ input sections to fill this area. (If there is too +much data, an error will be produced because this would be an attempt to +move <code>.</code> backwards). The ‘<samp>.data</samp>’ section will start at 0x500 +and it will have an extra 0x600 bytes worth of space after the end of +the values from the ‘<samp>.data</samp>’ input sections and before the end of +the ‘<samp>.data</samp>’ output section itself. +</p> +<a name="index-dot-outside-sections"></a> +<p>Setting symbols to the value of the location counter outside of an +output section statement can result in unexpected values if the linker +needs to place orphan sections. For example, given the following: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +</pre></div> + +<p>If the linker needs to place some input section, e.g. <code>.rodata</code>, +not mentioned in the script, it might choose to place that section +between <code>.text</code> and <code>.data</code>. You might think the linker +should place <code>.rodata</code> on the blank line in the above script, but +blank lines are of no particular significance to the linker. As well, +the linker doesn’t associate the above symbol names with their +sections. Instead, it assumes that all assignments or other +statements belong to the previous output section, except for the +special case of an assignment to <code>.</code>. I.e., the linker will +place the orphan <code>.rodata</code> section as if the script was written +as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .rodata: { *(.rodata) } + .data: { *(.data) } + end_of_data = . ; +} +</pre></div> + +<p>This may or may not be the script author’s intention for the value of +<code>start_of_data</code>. One way to influence the orphan section +placement is to assign the location counter to itself, as the linker +assumes that an assignment to <code>.</code> is setting the start address of +a following output section and thus should be grouped with that +section. So you could write: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +</pre></div> + +<p>Now, the orphan <code>.rodata</code> section will be placed between +<code>end_of_text</code> and <code>start_of_data</code>. +</p> +<hr> +<a name="Operators"></a> +<div class="header"> +<p> +Next: <a href="#Evaluation" accesskey="n" rel="next">Evaluation</a>, Previous: <a href="#Location-Counter" accesskey="p" rel="previous">Location Counter</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Operators-1"></a> +<h4 class="subsection">3.10.6 Operators</h4> +<a name="index-operators-for-arithmetic"></a> +<a name="index-arithmetic-operators"></a> +<a name="index-precedence-in-expressions"></a> +<p>The linker recognizes the standard C set of arithmetic operators, with +the standard bindings and precedence levels: +</p><div class="smallexample"> +<pre class="smallexample">precedence associativity Operators Notes +(highest) +1 left ! - ~ (1) +2 left * / % +3 left + - +4 left >> << +5 left == != > < <= >= +6 left & +7 left | +8 left && +9 left || +10 right ? : +11 right &= += -= *= /= (2) +(lowest) +</pre></div> +<p>Notes: +(1) Prefix operators +(2) See <a href="#Assignments">Assignments</a>. +</p> +<hr> +<a name="Evaluation"></a> +<div class="header"> +<p> +Next: <a href="#Expression-Section" accesskey="n" rel="next">Expression Section</a>, Previous: <a href="#Operators" accesskey="p" rel="previous">Operators</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Evaluation-1"></a> +<h4 class="subsection">3.10.7 Evaluation</h4> +<a name="index-lazy-evaluation"></a> +<a name="index-expression-evaluation-order"></a> +<p>The linker evaluates expressions lazily. It only computes the value of +an expression when absolutely necessary. +</p> +<p>The linker needs some information, such as the value of the start +address of the first section, and the origins and lengths of memory +regions, in order to do any linking at all. These values are computed +as soon as possible when the linker reads in the linker script. +</p> +<p>However, other values (such as symbol values) are not known or needed +until after storage allocation. Such values are evaluated later, when +other information (such as the sizes of output sections) is available +for use in the symbol assignment expression. +</p> +<p>The sizes of sections cannot be known until after allocation, so +assignments dependent upon these are not performed until after +allocation. +</p> +<p>Some expressions, such as those depending upon the location counter +‘<samp>.</samp>’, must be evaluated during section allocation. +</p> +<p>If the result of an expression is required, but the value is not +available, then an error results. For example, a script like the +following +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS + { + .text 9+this_isnt_constant : + { *(.text) } + } +</pre></div> +<p>will cause the error message ‘<samp>non constant expression for initial +address</samp>’. +</p> +<hr> +<a name="Expression-Section"></a> +<div class="header"> +<p> +Next: <a href="#Builtin-Functions" accesskey="n" rel="next">Builtin Functions</a>, Previous: <a href="#Evaluation" accesskey="p" rel="previous">Evaluation</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="The-Section-of-an-Expression"></a> +<h4 class="subsection">3.10.8 The Section of an Expression</h4> +<a name="index-expression-sections"></a> +<a name="index-absolute-expressions"></a> +<a name="index-relative-expressions"></a> +<a name="index-absolute-and-relocatable-symbols"></a> +<a name="index-relocatable-and-absolute-symbols"></a> +<a name="index-symbols_002c-relocatable-and-absolute"></a> +<p>Addresses and symbols may be section relative, or absolute. A section +relative symbol is relocatable. If you request relocatable output +using the ‘<samp>-r</samp>’ option, a further link operation may change the +value of a section relative symbol. On the other hand, an absolute +symbol will retain the same value throughout any further link +operations. +</p> +<p>Some terms in linker expressions are addresses. This is true of +section relative symbols and for builtin functions that return an +address, such as <code>ADDR</code>, <code>LOADADDR</code>, <code>ORIGIN</code> and +<code>SEGMENT_START</code>. Other terms are simply numbers, or are builtin +functions that return a non-address value, such as <code>LENGTH</code>. +One complication is that unless you set <code>LD_FEATURE ("SANE_EXPR")</code> +(see <a href="#Miscellaneous-Commands">Miscellaneous Commands</a>), numbers and absolute symbols are treated +differently depending on their location, for compatibility with older +versions of <code>ld</code>. Expressions appearing outside an output +section definition treat all numbers as absolute addresses. +Expressions appearing inside an output section definition treat +absolute symbols as numbers. If <code>LD_FEATURE ("SANE_EXPR")</code> is +given, then absolute symbols and numbers are simply treated as numbers +everywhere. +</p> +<p>In the following simple example, +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS + { + . = 0x100; + __executable_start = 0x100; + .data : + { + . = 0x10; + __data_start = 0x10; + *(.data) + } + … + } +</pre></div> + +<p>both <code>.</code> and <code>__executable_start</code> are set to the absolute +address 0x100 in the first two assignments, then both <code>.</code> and +<code>__data_start</code> are set to 0x10 relative to the <code>.data</code> +section in the second two assignments. +</p> +<p>For expressions involving numbers, relative addresses and absolute +addresses, ld follows these rules to evaluate terms: +</p> +<ul> +<li> Unary operations on an absolute address or number, and binary +operations on two absolute addresses or two numbers, or between one +absolute address and a number, apply the operator to the value(s). +</li><li> Unary operations on a relative address, and binary operations on two +relative addresses in the same section or between one relative address +and a number, apply the operator to the offset part of the address(es). +</li><li> Other binary operations, that is, between two relative addresses not +in the same section, or between a relative address and an absolute +address, first convert any non-absolute term to an absolute address +before applying the operator. +</li></ul> + +<p>The result section of each sub-expression is as follows: +</p> +<ul> +<li> An operation involving only numbers results in a number. +</li><li> The result of comparisons, ‘<samp>&&</samp>’ and ‘<samp>||</samp>’ is also a number. +</li><li> The result of other binary arithmetic and logical operations on two +relative addresses in the same section or two absolute addresses +(after above conversions) is also a number when +<code>LD_FEATURE ("SANE_EXPR")</code> or inside an output section definition +but an absolute address otherwise. +</li><li> The result of other operations on relative addresses or one +relative address and a number, is a relative address in the same +section as the relative operand(s). +</li><li> The result of other operations on absolute addresses (after above +conversions) is an absolute address. +</li></ul> + +<p>You can use the builtin function <code>ABSOLUTE</code> to force an expression +to be absolute when it would otherwise be relative. For example, to +create an absolute symbol set to the address of the end of the output +section ‘<samp>.data</samp>’: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS + { + .data : { *(.data) _edata = ABSOLUTE(.); } + } +</pre></div> +<p>If ‘<samp>ABSOLUTE</samp>’ were not used, ‘<samp>_edata</samp>’ would be relative to the +‘<samp>.data</samp>’ section. +</p> +<p>Using <code>LOADADDR</code> also forces an expression absolute, since this +particular builtin function returns an absolute address. +</p> +<hr> +<a name="Builtin-Functions"></a> +<div class="header"> +<p> +Previous: <a href="#Expression-Section" accesskey="p" rel="previous">Expression Section</a>, Up: <a href="#Expressions" accesskey="u" rel="up">Expressions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Builtin-Functions-1"></a> +<h4 class="subsection">3.10.9 Builtin Functions</h4> +<a name="index-functions-in-expressions"></a> +<p>The linker script language includes a number of builtin functions for +use in linker script expressions. +</p> +<dl compact="compact"> +<dt><code>ABSOLUTE(<var>exp</var>)</code></dt> +<dd><a name="index-ABSOLUTE_0028exp_0029"></a> +<a name="index-expression_002c-absolute"></a> +<p>Return the absolute (non-relocatable, as opposed to non-negative) value +of the expression <var>exp</var>. Primarily useful to assign an absolute +value to a symbol within a section definition, where symbol values are +normally section relative. See <a href="#Expression-Section">Expression Section</a>. +</p> +</dd> +<dt><code>ADDR(<var>section</var>)</code></dt> +<dd><a name="index-ADDR_0028section_0029"></a> +<a name="index-section-address-in-expression"></a> +<p>Return the address (VMA) of the named <var>section</var>. Your +script must previously have defined the location of that section. In +the following example, <code>start_of_output_1</code>, <code>symbol_1</code> and +<code>symbol_2</code> are assigned equivalent values, except that +<code>symbol_1</code> will be relative to the <code>.output1</code> section while +the other two will be absolute: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { … + .output1 : + { + start_of_output_1 = ABSOLUTE(.); + … + } + .output : + { + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + } +… } +</pre></div> + +</dd> +<dt><code>ALIGN(<var>align</var>)</code></dt> +<dt><code>ALIGN(<var>exp</var>,<var>align</var>)</code></dt> +<dd><a name="index-ALIGN_0028align_0029"></a> +<a name="index-ALIGN_0028exp_002calign_0029"></a> +<a name="index-round-up-location-counter"></a> +<a name="index-align-location-counter"></a> +<a name="index-round-up-expression"></a> +<a name="index-align-expression"></a> +<p>Return the location counter (<code>.</code>) or arbitrary expression aligned +to the next <var>align</var> boundary. The single operand <code>ALIGN</code> +doesn’t change the value of the location counter—it just does +arithmetic on it. The two operand <code>ALIGN</code> allows an arbitrary +expression to be aligned upwards (<code>ALIGN(<var>align</var>)</code> is +equivalent to <code>ALIGN(ABSOLUTE(.), <var>align</var>)</code>). +</p> +<p>Here is an example which aligns the output <code>.data</code> section to the +next <code>0x2000</code> byte boundary after the preceding section and sets a +variable within the section to the next <code>0x8000</code> boundary after the +input sections: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS { … + .data ALIGN(0x2000): { + *(.data) + variable = ALIGN(0x8000); + } +… } +</pre></div> +<p>The first use of <code>ALIGN</code> in this example specifies the location of +a section because it is used as the optional <var>address</var> attribute of +a section definition (see <a href="#Output-Section-Address">Output Section Address</a>). The second use +of <code>ALIGN</code> is used to defines the value of a symbol. +</p> +<p>The builtin function <code>NEXT</code> is closely related to <code>ALIGN</code>. +</p> +</dd> +<dt><code>ALIGNOF(<var>section</var>)</code></dt> +<dd><a name="index-ALIGNOF_0028section_0029"></a> +<a name="index-section-alignment"></a> +<p>Return the alignment in bytes of the named <var>section</var>, if that section has +been allocated. If the section has not been allocated when this is +evaluated, the linker will report an error. In the following example, +the alignment of the <code>.output</code> section is stored as the first +value in that section. +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS{ … + .output { + LONG (ALIGNOF (.output)) + … + } +… } +</pre></div> + +</dd> +<dt><code>BLOCK(<var>exp</var>)</code></dt> +<dd><a name="index-BLOCK_0028exp_0029"></a> +<p>This is a synonym for <code>ALIGN</code>, for compatibility with older linker +scripts. It is most often seen when setting the address of an output +section. +</p> +</dd> +<dt><code>DATA_SEGMENT_ALIGN(<var>maxpagesize</var>, <var>commonpagesize</var>)</code></dt> +<dd><a name="index-DATA_005fSEGMENT_005fALIGN_0028maxpagesize_002c-commonpagesize_0029"></a> +<p>This is equivalent to either +</p><div class="smallexample"> +<pre class="smallexample">(ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - 1))) +</pre></div> +<p>or +</p><div class="smallexample"> +<pre class="smallexample">(ALIGN(<var>maxpagesize</var>) + + ((. + <var>commonpagesize</var> - 1) & (<var>maxpagesize</var> - <var>commonpagesize</var>))) +</pre></div> +<p>depending on whether the latter uses fewer <var>commonpagesize</var> sized pages +for the data segment (area between the result of this expression and +<code>DATA_SEGMENT_END</code>) than the former or not. +If the latter form is used, it means <var>commonpagesize</var> bytes of runtime +memory will be saved at the expense of up to <var>commonpagesize</var> wasted +bytes in the on-disk file. +</p> +<p>This expression can only be used directly in <code>SECTIONS</code> commands, not in +any output section descriptions and only once in the linker script. +<var>commonpagesize</var> should be less or equal to <var>maxpagesize</var> and should +be the system page size the object wants to be optimized for while still +running on system page sizes up to <var>maxpagesize</var>. Note however +that ‘<samp>-z relro</samp>’ protection will not be effective if the system +page size is larger than <var>commonpagesize</var>. +</p> +<p>Example: +</p><div class="smallexample"> +<pre class="smallexample"> . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); +</pre></div> + +</dd> +<dt><code>DATA_SEGMENT_END(<var>exp</var>)</code></dt> +<dd><a name="index-DATA_005fSEGMENT_005fEND_0028exp_0029"></a> +<p>This defines the end of data segment for <code>DATA_SEGMENT_ALIGN</code> +evaluation purposes. +</p> +<div class="smallexample"> +<pre class="smallexample"> . = DATA_SEGMENT_END(.); +</pre></div> + +</dd> +<dt><code>DATA_SEGMENT_RELRO_END(<var>offset</var>, <var>exp</var>)</code></dt> +<dd><a name="index-DATA_005fSEGMENT_005fRELRO_005fEND_0028offset_002c-exp_0029"></a> +<p>This defines the end of the <code>PT_GNU_RELRO</code> segment when +‘<samp>-z relro</samp>’ option is used. +When ‘<samp>-z relro</samp>’ option is not present, <code>DATA_SEGMENT_RELRO_END</code> +does nothing, otherwise <code>DATA_SEGMENT_ALIGN</code> is padded so that +<var>exp</var> + <var>offset</var> is aligned to the <var>commonpagesize</var> +argument given to <code>DATA_SEGMENT_ALIGN</code>. If present in the linker +script, it must be placed between <code>DATA_SEGMENT_ALIGN</code> and +<code>DATA_SEGMENT_END</code>. Evaluates to the second argument plus any +padding needed at the end of the <code>PT_GNU_RELRO</code> segment due to +section alignment. +</p> +<div class="smallexample"> +<pre class="smallexample"> . = DATA_SEGMENT_RELRO_END(24, .); +</pre></div> + +</dd> +<dt><code>DEFINED(<var>symbol</var>)</code></dt> +<dd><a name="index-DEFINED_0028symbol_0029"></a> +<a name="index-symbol-defaults"></a> +<p>Return 1 if <var>symbol</var> is in the linker global symbol table and is +defined before the statement using DEFINED in the script, otherwise +return 0. You can use this function to provide +default values for symbols. For example, the following script fragment +shows how to set a global symbol ‘<samp>begin</samp>’ to the first location in +the ‘<samp>.text</samp>’ section—but if a symbol called ‘<samp>begin</samp>’ already +existed, its value is preserved: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS { … + .text : { + begin = DEFINED(begin) ? begin : . ; + … + } + … +} +</pre></div> + +</dd> +<dt><code>LENGTH(<var>memory</var>)</code></dt> +<dd><a name="index-LENGTH_0028memory_0029"></a> +<p>Return the length of the memory region named <var>memory</var>. +</p> +</dd> +<dt><code>LOADADDR(<var>section</var>)</code></dt> +<dd><a name="index-LOADADDR_0028section_0029"></a> +<a name="index-section-load-address-in-expression"></a> +<p>Return the absolute LMA of the named <var>section</var>. (see <a href="#Output-Section-LMA">Output Section LMA</a>). +</p> +</dd> +<dt><code>LOG2CEIL(<var>exp</var>)</code></dt> +<dd><a name="index-LOG2CEIL_0028exp_0029"></a> +<p>Return the binary logarithm of <var>exp</var> rounded towards infinity. +<code>LOG2CEIL(0)</code> returns 0. +</p> +<a name="index-MAX"></a> +</dd> +<dt><code>MAX(<var>exp1</var>, <var>exp2</var>)</code></dt> +<dd><p>Returns the maximum of <var>exp1</var> and <var>exp2</var>. +</p> +<a name="index-MIN"></a> +</dd> +<dt><code>MIN(<var>exp1</var>, <var>exp2</var>)</code></dt> +<dd><p>Returns the minimum of <var>exp1</var> and <var>exp2</var>. +</p> +</dd> +<dt><code>NEXT(<var>exp</var>)</code></dt> +<dd><a name="index-NEXT_0028exp_0029"></a> +<a name="index-unallocated-address_002c-next"></a> +<p>Return the next unallocated address that is a multiple of <var>exp</var>. +This function is closely related to <code>ALIGN(<var>exp</var>)</code>; unless you +use the <code>MEMORY</code> command to define discontinuous memory for the +output file, the two functions are equivalent. +</p> +</dd> +<dt><code>ORIGIN(<var>memory</var>)</code></dt> +<dd><a name="index-ORIGIN_0028memory_0029"></a> +<p>Return the origin of the memory region named <var>memory</var>. +</p> +</dd> +<dt><code>SEGMENT_START(<var>segment</var>, <var>default</var>)</code></dt> +<dd><a name="index-SEGMENT_005fSTART_0028segment_002c-default_0029"></a> +<p>Return the base address of the named <var>segment</var>. If an explicit +value has already been given for this segment (with a command-line +‘<samp>-T</samp>’ option) then that value will be returned otherwise the value +will be <var>default</var>. At present, the ‘<samp>-T</samp>’ command-line option +can only be used to set the base address for the “text”, “data”, and +“bss” sections, but you can use <code>SEGMENT_START</code> with any segment +name. +</p> +</dd> +<dt><code>SIZEOF(<var>section</var>)</code></dt> +<dd><a name="index-SIZEOF_0028section_0029"></a> +<a name="index-section-size"></a> +<p>Return the size in bytes of the named <var>section</var>, if that section has +been allocated. If the section has not been allocated when this is +evaluated, the linker will report an error. In the following example, +<code>symbol_1</code> and <code>symbol_2</code> are assigned identical values: +</p><div class="smallexample"> +<pre class="smallexample">SECTIONS{ … + .output { + .start = . ; + … + .end = . ; + } + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); +… } +</pre></div> + +</dd> +<dt><code>SIZEOF_HEADERS</code></dt> +<dd><a name="index-SIZEOF_005fHEADERS"></a> +<a name="index-header-size"></a> +<p>Return the size in bytes of the output file’s headers. This is +information which appears at the start of the output file. You can use +this number when setting the start address of the first section, if you +choose, to facilitate paging. +</p> +<a name="index-not-enough-room-for-program-headers"></a> +<a name="index-program-headers_002c-not-enough-room"></a> +<p>When producing an ELF output file, if the linker script uses the +<code>SIZEOF_HEADERS</code> builtin function, the linker must compute the +number of program headers before it has determined all the section +addresses and sizes. If the linker later discovers that it needs +additional program headers, it will report an error ‘<samp>not enough +room for program headers</samp>’. To avoid this error, you must avoid using +the <code>SIZEOF_HEADERS</code> function, or you must rework your linker +script to avoid forcing the linker to use additional program headers, or +you must define the program headers yourself using the <code>PHDRS</code> +command (see <a href="#PHDRS">PHDRS</a>). +</p></dd> +</dl> + +<hr> +<a name="Implicit-Linker-Scripts"></a> +<div class="header"> +<p> +Previous: <a href="#Expressions" accesskey="p" rel="previous">Expressions</a>, Up: <a href="#Scripts" accesskey="u" rel="up">Scripts</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Implicit-Linker-Scripts-1"></a> +<h3 class="section">3.11 Implicit Linker Scripts</h3> +<a name="index-implicit-linker-scripts"></a> +<p>If you specify a linker input file which the linker can not recognize as +an object file or an archive file, it will try to read the file as a +linker script. If the file can not be parsed as a linker script, the +linker will report an error. +</p> +<p>An implicit linker script will not replace the default linker script. +</p> +<p>Typically an implicit linker script would contain only symbol +assignments, or the <code>INPUT</code>, <code>GROUP</code>, or <code>VERSION</code> +commands. +</p> +<p>Any input files read because of an implicit linker script will be read +at the position in the command line where the implicit linker script was +read. This can affect archive searching. +</p> +<hr> +<a name="Plugins"></a> +<div class="header"> +<p> +Next: <a href="#Machine-Dependent" accesskey="n" rel="next">Machine Dependent</a>, Previous: <a href="#Scripts" accesskey="p" rel="previous">Scripts</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Linker-Plugins"></a> +<h2 class="chapter">4 Linker Plugins</h2> + +<a name="index-plugins"></a> +<a name="index-linker-plugins"></a> +<p>The linker can use dynamically loaded plugins to modify its behavior. +For example, the link-time optimization feature that some compilers +support is implemented with a linker plugin. +</p> +<p>Currently there is only one plugin shipped by default, but more may +be added here later. +</p> +<p>Plugins are enabled via the use of the <samp>-plugin <var>name</var></samp> +command line option. See <a href="#Options">Options</a>. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#libdep-Plugin" accesskey="1">libdep Plugin</a>:</td><td> </td><td align="left" valign="top">Static Library Dependencies Plugin +</td></tr> +</table> + +<hr> +<a name="libdep-Plugin"></a> +<div class="header"> +<p> +Up: <a href="#Plugins" accesskey="u" rel="up">Plugins</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Static-Library-Dependencies-Plugin"></a> +<h3 class="section">4.1 Static Library Dependencies Plugin</h3> +<a name="index-static-library-dependencies"></a> +<p>Originally, static libraries were contained in an archive file consisting +just of a collection of relocatable object files. Later they evolved to +optionally include a symbol table, to assist in finding the needed objects +within a library. There their evolution ended, and dynamic libraries +rose to ascendance. +</p> +<p>One useful feature of dynamic libraries was that, more than just collecting +multiple objects into a single file, they also included a list of their +dependencies, such that one could specify just the name of a single dynamic +library at link time, and all of its dependencies would be implicitly +referenced as well. But static libraries lacked this feature, so if a +link invocation was switched from using dynamic libraries to static +libraries, the link command would usually fail unless it was rewritten to +explicitly list the dependencies of the static library. +</p> +<p>The GNU <code>ar</code> utility now supports a <samp>--record-libdeps</samp> option +to embed dependency lists into static libraries as well, and the <samp>libdep</samp> +plugin may be used to read this dependency information at link time. The +dependency information is stored as a single string, carrying <samp>-l</samp> +and <samp>-L</samp> arguments as they would normally appear in a linker +command line. As such, the information can be written with any text +utility and stored into any archive, even if GNU <code>ar</code> is not +being used to create the archive. The information is stored in an +archive member named ‘<samp>__.LIBDEP</samp>’. +</p> +<p>For example, given a library <samp>libssl.a</samp> that depends on another +library <samp>libcrypto.a</samp> which may be found in <samp>/usr/local/lib</samp>, +the ‘<samp>__.LIBDEP</samp>’ member of <samp>libssl.a</samp> would contain +</p> +<div class="smallexample"> +<pre class="smallexample">-L/usr/local/lib -lcrypto +</pre></div> + +<hr> +<a name="Machine-Dependent"></a> +<div class="header"> +<p> +Next: <a href="#BFD" accesskey="n" rel="next">BFD</a>, Previous: <a href="#Plugins" accesskey="p" rel="previous">Plugins</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Machine-Dependent-Features"></a> +<h2 class="chapter">5 Machine Dependent Features</h2> + +<a name="index-machine-dependencies"></a> +<p><code>ld</code> has additional features on some platforms; the following +sections describe them. Machines where <code>ld</code> has no additional +functionality are not listed. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#H8_002f300" accesskey="1">H8/300</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and the H8/300 +</td></tr> +<tr><td align="left" valign="top">• <a href="#M68HC11_002f68HC12" accesskey="2">M68HC11/68HC12</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and the Motorola 68HC11 and 68HC12 families +</td></tr> +<tr><td align="left" valign="top">• <a href="#ARM" accesskey="3">ARM</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and the ARM family +</td></tr> +<tr><td align="left" valign="top">• <a href="#HPPA-ELF32" accesskey="4">HPPA ELF32</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and HPPA 32-bit ELF +</td></tr> +<tr><td align="left" valign="top">• <a href="#M68K" accesskey="5">M68K</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and the Motorola 68K family +</td></tr> +<tr><td align="left" valign="top">• <a href="#MIPS" accesskey="6">MIPS</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and the MIPS family +</td></tr> +<tr><td align="left" valign="top">• <a href="#MMIX" accesskey="7">MMIX</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and MMIX +</td></tr> +<tr><td align="left" valign="top">• <a href="#MSP430" accesskey="8">MSP430</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and MSP430 +</td></tr> +<tr><td align="left" valign="top">• <a href="#NDS32" accesskey="9">NDS32</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and NDS32 +</td></tr> +<tr><td align="left" valign="top">• <a href="#Nios-II">Nios II</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and the Altera Nios II +</td></tr> +<tr><td align="left" valign="top">• <a href="#PowerPC-ELF32">PowerPC ELF32</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and PowerPC 32-bit ELF Support +</td></tr> +<tr><td align="left" valign="top">• <a href="#PowerPC64-ELF64">PowerPC64 ELF64</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and PowerPC64 64-bit ELF Support +</td></tr> +<tr><td align="left" valign="top">• <a href="#S_002f390-ELF">S/390 ELF</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and S/390 ELF Support +</td></tr> +<tr><td align="left" valign="top">• <a href="#SPU-ELF">SPU ELF</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and SPU ELF Support +</td></tr> +<tr><td align="left" valign="top">• <a href="#TI-COFF">TI COFF</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and TI COFF +</td></tr> +<tr><td align="left" valign="top">• <a href="#WIN32">WIN32</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and WIN32 (cygwin/mingw) +</td></tr> +<tr><td align="left" valign="top">• <a href="#Xtensa">Xtensa</a>:</td><td> </td><td align="left" valign="top"><code>ld</code> and Xtensa Processors +</td></tr> +</table> + + +<hr> +<a name="H8_002f300"></a> +<div class="header"> +<p> +Next: <a href="#M68HC11_002f68HC12" accesskey="n" rel="next">M68HC11/68HC12</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-the-H8_002f300"></a> +<h3 class="section">5.1 <code>ld</code> and the H8/300</h3> + +<a name="index-H8_002f300-support"></a> +<p>For the H8/300, <code>ld</code> can perform these global optimizations when +you specify the ‘<samp>--relax</samp>’ command-line option. +</p> +<dl compact="compact"> +<dd><a name="index-relaxing-on-H8_002f300"></a> +</dd> +<dt><em>relaxing address modes</em></dt> +<dd><p><code>ld</code> finds all <code>jsr</code> and <code>jmp</code> instructions whose +targets are within eight bits, and turns them into eight-bit +program-counter relative <code>bsr</code> and <code>bra</code> instructions, +respectively. +</p> +<a name="index-synthesizing-on-H8_002f300"></a> +</dd> +<dt><em>synthesizing instructions</em></dt> +<dd><p><code>ld</code> finds all <code>mov.b</code> instructions which use the +sixteen-bit absolute address form, but refer to the top +page of memory, and changes them to use the eight-bit address form. +(That is: the linker turns ‘<samp>mov.b <code>@</code><var>aa</var>:16</samp>’ into +‘<samp>mov.b <code>@</code><var>aa</var>:8</samp>’ whenever the address <var>aa</var> is in the +top page of memory). +</p> +<p><code>ld</code> finds all <code>mov</code> instructions which use the register +indirect with 32-bit displacement addressing mode, but use a small +displacement inside 16-bit displacement range, and changes them to use +the 16-bit displacement form. (That is: the linker turns ‘<samp>mov.b +<code>@</code><var>d</var>:32,ERx</samp>’ into ‘<samp>mov.b <code>@</code><var>d</var>:16,ERx</samp>’ +whenever the displacement <var>d</var> is in the 16 bit signed integer +range. Only implemented in ELF-format ld). +</p> +</dd> +<dt><em>bit manipulation instructions</em></dt> +<dd><p><code>ld</code> finds all bit manipulation instructions like <code>band, bclr, +biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor</code> +which use 32 bit and 16 bit absolute address form, but refer to the top +page of memory, and changes them to use the 8 bit address form. +(That is: the linker turns ‘<samp>bset #xx:3,<code>@</code><var>aa</var>:32</samp>’ into +‘<samp>bset #xx:3,<code>@</code><var>aa</var>:8</samp>’ whenever the address <var>aa</var> is in +the top page of memory). +</p> +</dd> +<dt><em>system control instructions</em></dt> +<dd><p><code>ld</code> finds all <code>ldc.w, stc.w</code> instructions which use the +32 bit absolute address form, but refer to the top page of memory, and +changes them to use 16 bit address form. +(That is: the linker turns ‘<samp>ldc.w <code>@</code><var>aa</var>:32,ccr</samp>’ into +‘<samp>ldc.w <code>@</code><var>aa</var>:16,ccr</samp>’ whenever the address <var>aa</var> is in +the top page of memory). +</p></dd> +</dl> + + + + + +<hr> +<a name="M68HC11_002f68HC12"></a> +<div class="header"> +<p> +Next: <a href="#ARM" accesskey="n" rel="next">ARM</a>, Previous: <a href="#H8_002f300" accesskey="p" rel="previous">H8/300</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-the-Motorola-68HC11-and-68HC12-families"></a> +<h3 class="section">5.2 <code>ld</code> and the Motorola 68HC11 and 68HC12 families</h3> + +<a name="index-M68HC11-and-68HC12-support"></a> + +<a name="Linker-Relaxation"></a> +<h4 class="subsection">5.2.1 Linker Relaxation</h4> + +<p>For the Motorola 68HC11, <code>ld</code> can perform these global +optimizations when you specify the ‘<samp>--relax</samp>’ command-line option. +</p> +<dl compact="compact"> +<dd><a name="index-relaxing-on-M68HC11"></a> +</dd> +<dt><em>relaxing address modes</em></dt> +<dd><p><code>ld</code> finds all <code>jsr</code> and <code>jmp</code> instructions whose +targets are within eight bits, and turns them into eight-bit +program-counter relative <code>bsr</code> and <code>bra</code> instructions, +respectively. +</p> +<p><code>ld</code> also looks at all 16-bit extended addressing modes and +transforms them in a direct addressing mode when the address is in +page 0 (between 0 and 0x0ff). +</p> +</dd> +<dt><em>relaxing gcc instruction group</em></dt> +<dd><p>When <code>gcc</code> is called with <samp>-mrelax</samp>, it can emit group +of instructions that the linker can optimize to use a 68HC11 direct +addressing mode. These instructions consists of <code>bclr</code> or +<code>bset</code> instructions. +</p> +</dd> +</dl> + +<a name="Trampoline-Generation"></a> +<h4 class="subsection">5.2.2 Trampoline Generation</h4> + +<a name="index-trampoline-generation-on-M68HC11"></a> +<a name="index-trampoline-generation-on-M68HC12"></a> +<p>For 68HC11 and 68HC12, <code>ld</code> can generate trampoline code to +call a far function using a normal <code>jsr</code> instruction. The linker +will also change the relocation to some far function to use the +trampoline address instead of the function address. This is typically the +case when a pointer to a function is taken. The pointer will in fact +point to the function trampoline. +</p> + +<hr> +<a name="ARM"></a> +<div class="header"> +<p> +Next: <a href="#HPPA-ELF32" accesskey="n" rel="next">HPPA ELF32</a>, Previous: <a href="#M68HC11_002f68HC12" accesskey="p" rel="previous">M68HC11/68HC12</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-the-ARM-family"></a> +<h3 class="section">5.3 <code>ld</code> and the ARM family</h3> + +<a name="index-ARM-interworking-support"></a> +<a name="index-_002d_002dsupport_002dold_002dcode"></a> +<p>For the ARM, <code>ld</code> will generate code stubs to allow functions calls +between ARM and Thumb code. These stubs only work with code that has +been compiled and assembled with the ‘<samp>-mthumb-interwork</samp>’ command +line option. If it is necessary to link with old ARM object files or +libraries, which have not been compiled with the -mthumb-interwork +option then the ‘<samp>--support-old-code</samp>’ command-line switch should be +given to the linker. This will make it generate larger stub functions +which will work with non-interworking aware ARM code. Note, however, +the linker does not support generating stubs for function calls to +non-interworking aware Thumb code. +</p> +<a name="index-thumb-entry-point"></a> +<a name="index-entry-point_002c-thumb"></a> +<a name="index-_002d_002dthumb_002dentry_003dentry"></a> +<p>The ‘<samp>--thumb-entry</samp>’ switch is a duplicate of the generic +‘<samp>--entry</samp>’ switch, in that it sets the program’s starting address. +But it also sets the bottom bit of the address, so that it can be +branched to using a BX instruction, and the program will start +executing in Thumb mode straight away. +</p> +<a name="index-PE-import-table-prefixing"></a> +<a name="index-_002d_002duse_002dnul_002dprefixed_002dimport_002dtables"></a> +<p>The ‘<samp>--use-nul-prefixed-import-tables</samp>’ switch is specifying, that +the import tables idata4 and idata5 have to be generated with a zero +element prefix for import libraries. This is the old style to generate +import tables. By default this option is turned off. +</p> +<a name="index-BE8"></a> +<a name="index-_002d_002dbe8"></a> +<p>The ‘<samp>--be8</samp>’ switch instructs <code>ld</code> to generate BE8 format +executables. This option is only valid when linking big-endian +objects - ie ones which have been assembled with the <samp>-EB</samp> +option. The resulting image will contain big-endian data and +little-endian code. +</p> +<a name="index-TARGET1"></a> +<a name="index-_002d_002dtarget1_002drel"></a> +<a name="index-_002d_002dtarget1_002dabs"></a> +<p>The ‘<samp>R_ARM_TARGET1</samp>’ relocation is typically used for entries in the +‘<samp>.init_array</samp>’ section. It is interpreted as either ‘<samp>R_ARM_REL32</samp>’ +or ‘<samp>R_ARM_ABS32</samp>’, depending on the target. The ‘<samp>--target1-rel</samp>’ +and ‘<samp>--target1-abs</samp>’ switches override the default. +</p> +<a name="index-TARGET2"></a> +<a name="index-_002d_002dtarget2_003dtype"></a> +<p>The ‘<samp>--target2=type</samp>’ switch overrides the default definition of the +‘<samp>R_ARM_TARGET2</samp>’ relocation. Valid values for ‘<samp>type</samp>’, their +meanings, and target defaults are as follows: +</p><dl compact="compact"> +<dt>‘<samp>rel</samp>’</dt> +<dd><p>‘<samp>R_ARM_REL32</samp>’ (arm*-*-elf, arm*-*-eabi) +</p></dd> +<dt>‘<samp>abs</samp>’</dt> +<dd><p>‘<samp>R_ARM_ABS32</samp>’ +</p></dd> +<dt>‘<samp>got-rel</samp>’</dt> +<dd><p>‘<samp>R_ARM_GOT_PREL</samp>’ (arm*-*-linux, arm*-*-*bsd) +</p></dd> +</dl> + +<a name="index-FIX_005fV4BX"></a> +<a name="index-_002d_002dfix_002dv4bx"></a> +<p>The ‘<samp>R_ARM_V4BX</samp>’ relocation (defined by the ARM AAELF +specification) enables objects compiled for the ARMv4 architecture to be +interworking-safe when linked with other objects compiled for ARMv4t, but +also allows pure ARMv4 binaries to be built from the same ARMv4 objects. +</p> +<p>In the latter case, the switch <samp>--fix-v4bx</samp> must be passed to the +linker, which causes v4t <code>BX rM</code> instructions to be rewritten as +<code>MOV PC,rM</code>, since v4 processors do not have a <code>BX</code> instruction. +</p> +<p>In the former case, the switch should not be used, and ‘<samp>R_ARM_V4BX</samp>’ +relocations are ignored. +</p> +<a name="index-FIX_005fV4BX_005fINTERWORKING"></a> +<a name="index-_002d_002dfix_002dv4bx_002dinterworking"></a> +<p>Replace <code>BX rM</code> instructions identified by ‘<samp>R_ARM_V4BX</samp>’ +relocations with a branch to the following veneer: +</p> +<div class="smallexample"> +<pre class="smallexample">TST rM, #1 +MOVEQ PC, rM +BX Rn +</pre></div> + +<p>This allows generation of libraries/applications that work on ARMv4 cores +and are still interworking safe. Note that the above veneer clobbers the +condition flags, so may cause incorrect program behavior in rare cases. +</p> +<a name="index-USE_005fBLX"></a> +<a name="index-_002d_002duse_002dblx"></a> +<p>The ‘<samp>--use-blx</samp>’ switch enables the linker to use ARM/Thumb +BLX instructions (available on ARMv5t and above) in various +situations. Currently it is used to perform calls via the PLT from Thumb +code using BLX rather than using BX and a mode-switching stub before +each PLT entry. This should lead to such calls executing slightly faster. +</p> +<a name="index-VFP11_005fDENORM_005fFIX"></a> +<a name="index-_002d_002dvfp11_002ddenorm_002dfix"></a> +<p>The ‘<samp>--vfp11-denorm-fix</samp>’ switch enables a link-time workaround for a +bug in certain VFP11 coprocessor hardware, which sometimes allows +instructions with denorm operands (which must be handled by support code) +to have those operands overwritten by subsequent instructions before +the support code can read the intended values. +</p> +<p>The bug may be avoided in scalar mode if you allow at least one +intervening instruction between a VFP11 instruction which uses a register +and another instruction which writes to the same register, or at least two +intervening instructions if vector mode is in use. The bug only affects +full-compliance floating-point mode: you do not need this workaround if +you are using "runfast" mode. Please contact ARM for further details. +</p> +<p>If you know you are using buggy VFP11 hardware, you can +enable this workaround by specifying the linker option +‘<samp>--vfp-denorm-fix=scalar</samp>’ if you are using the VFP11 scalar +mode only, or ‘<samp>--vfp-denorm-fix=vector</samp>’ if you are using +vector mode (the latter also works for scalar code). The default is +‘<samp>--vfp-denorm-fix=none</samp>’. +</p> +<p>If the workaround is enabled, instructions are scanned for +potentially-troublesome sequences, and a veneer is created for each +such sequence which may trigger the erratum. The veneer consists of the +first instruction of the sequence and a branch back to the subsequent +instruction. The original instruction is then replaced with a branch to +the veneer. The extra cycles required to call and return from the veneer +are sufficient to avoid the erratum in both the scalar and vector cases. +</p> +<a name="index-ARM1176-erratum-workaround"></a> +<a name="index-_002d_002dfix_002darm1176"></a> +<a name="index-_002d_002dno_002dfix_002darm1176"></a> +<p>The ‘<samp>--fix-arm1176</samp>’ switch enables a link-time workaround for an erratum +in certain ARM1176 processors. The workaround is enabled by default if you +are targeting ARM v6 (excluding ARM v6T2) or earlier. It can be disabled +unconditionally by specifying ‘<samp>--no-fix-arm1176</samp>’. +</p> +<p>Further information is available in the “ARM1176JZ-S and ARM1176JZF-S +Programmer Advice Notice” available on the ARM documentation website at: +http://infocenter.arm.com/. +</p> +<a name="index-STM32L4xx-erratum-workaround"></a> +<a name="index-_002d_002dfix_002dstm32l4xx_002d629360"></a> + +<p>The ‘<samp>--fix-stm32l4xx-629360</samp>’ switch enables a link-time +workaround for a bug in the bus matrix / memory controller for some of +the STM32 Cortex-M4 based products (STM32L4xx). When accessing +off-chip memory via the affected bus for bus reads of 9 words or more, +the bus can generate corrupt data and/or abort. These are only +core-initiated accesses (not DMA), and might affect any access: +integer loads such as LDM, POP and floating-point loads such as VLDM, +VPOP. Stores are not affected. +</p> +<p>The bug can be avoided by splitting memory accesses into the +necessary chunks to keep bus reads below 8 words. +</p> +<p>The workaround is not enabled by default, this is equivalent to use +‘<samp>--fix-stm32l4xx-629360=none</samp>’. If you know you are using buggy +STM32L4xx hardware, you can enable the workaround by specifying the +linker option ‘<samp>--fix-stm32l4xx-629360</samp>’, or the equivalent +‘<samp>--fix-stm32l4xx-629360=default</samp>’. +</p> +<p>If the workaround is enabled, instructions are scanned for +potentially-troublesome sequences, and a veneer is created for each +such sequence which may trigger the erratum. The veneer consists in a +replacement sequence emulating the behaviour of the original one and a +branch back to the subsequent instruction. The original instruction is +then replaced with a branch to the veneer. +</p> +<p>The workaround does not always preserve the memory access order for +the LDMDB instruction, when the instruction loads the PC. +</p> +<p>The workaround is not able to handle problematic instructions when +they are in the middle of an IT block, since a branch is not allowed +there. In that case, the linker reports a warning and no replacement +occurs. +</p> +<p>The workaround is not able to replace problematic instructions with a +PC-relative branch instruction if the ‘<samp>.text</samp>’ section is too +large. In that case, when the branch that replaces the original code +cannot be encoded, the linker reports a warning and no replacement +occurs. +</p> +<a name="index-NO_005fENUM_005fSIZE_005fWARNING"></a> +<a name="index-_002d_002dno_002denum_002dsize_002dwarning"></a> +<p>The <samp>--no-enum-size-warning</samp> switch prevents the linker from +warning when linking object files that specify incompatible EABI +enumeration size attributes. For example, with this switch enabled, +linking of an object file using 32-bit enumeration values with another +using enumeration values fitted into the smallest possible space will +not be diagnosed. +</p> +<a name="index-NO_005fWCHAR_005fSIZE_005fWARNING"></a> +<a name="index-_002d_002dno_002dwchar_002dsize_002dwarning"></a> +<p>The <samp>--no-wchar-size-warning</samp> switch prevents the linker from +warning when linking object files that specify incompatible EABI +<code>wchar_t</code> size attributes. For example, with this switch enabled, +linking of an object file using 32-bit <code>wchar_t</code> values with another +using 16-bit <code>wchar_t</code> values will not be diagnosed. +</p> +<a name="index-PIC_005fVENEER"></a> +<a name="index-_002d_002dpic_002dveneer"></a> +<p>The ‘<samp>--pic-veneer</samp>’ switch makes the linker use PIC sequences for +ARM/Thumb interworking veneers, even if the rest of the binary +is not PIC. This avoids problems on uClinux targets where +‘<samp>--emit-relocs</samp>’ is used to generate relocatable binaries. +</p> +<a name="index-STUB_005fGROUP_005fSIZE"></a> +<a name="index-_002d_002dstub_002dgroup_002dsize_003dN"></a> +<p>The linker will automatically generate and insert small sequences of +code into a linked ARM ELF executable whenever an attempt is made to +perform a function call to a symbol that is too far away. The +placement of these sequences of instructions - called stubs - is +controlled by the command-line option <samp>--stub-group-size=N</samp>. +The placement is important because a poor choice can create a need for +duplicate stubs, increasing the code size. The linker will try to +group stubs together in order to reduce interruptions to the flow of +code, but it needs guidance as to how big these groups should be and +where they should be placed. +</p> +<p>The value of ‘<samp>N</samp>’, the parameter to the +<samp>--stub-group-size=</samp> option controls where the stub groups are +placed. If it is negative then all stubs are placed after the first +branch that needs them. If it is positive then the stubs can be +placed either before or after the branches that need them. If the +value of ‘<samp>N</samp>’ is 1 (either +1 or -1) then the linker will choose +exactly where to place groups of stubs, using its built in heuristics. +A value of ‘<samp>N</samp>’ greater than 1 (or smaller than -1) tells the +linker that a single group of stubs can service at most ‘<samp>N</samp>’ bytes +from the input sections. +</p> +<p>The default, if <samp>--stub-group-size=</samp> is not specified, is +‘<samp>N = +1</samp>’. +</p> +<p>Farcalls stubs insertion is fully supported for the ARM-EABI target +only, because it relies on object files properties not present +otherwise. +</p> +<a name="index-Cortex_002dA8-erratum-workaround"></a> +<a name="index-_002d_002dfix_002dcortex_002da8"></a> +<a name="index-_002d_002dno_002dfix_002dcortex_002da8"></a> +<p>The ‘<samp>--fix-cortex-a8</samp>’ 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</samp>’, or disabled unconditionally by specifying ‘<samp>--no-fix-cortex-a8</samp>’. +</p> +<p>The erratum only affects Thumb-2 code. Please contact ARM for further details. +</p> +<a name="index-Cortex_002dA53-erratum-835769-workaround"></a> +<a name="index-_002d_002dfix_002dcortex_002da53_002d835769"></a> +<a name="index-_002d_002dno_002dfix_002dcortex_002da53_002d835769"></a> +<p>The ‘<samp>--fix-cortex-a53-835769</samp>’ switch enables a link-time workaround for erratum 835769 present on certain early revisions of Cortex-A53 processors. The workaround is disabled by default. It can be enabled by specifying ‘<samp>--fix-cortex-a53-835769</samp>’, or disabled unconditionally by specifying ‘<samp>--no-fix-cortex-a53-835769</samp>’. +</p> +<p>Please contact ARM for further details. +</p> +<a name="index-_002d_002dmerge_002dexidx_002dentries"></a> +<a name="index-_002d_002dno_002dmerge_002dexidx_002dentries-1"></a> +<a name="index-Merging-exidx-entries"></a> +<p>The ‘<samp>--no-merge-exidx-entries</samp>’ switch disables the merging of adjacent exidx entries in debuginfo. +</p> +<a name="index-_002d_002dlong_002dplt"></a> +<a name="index-32_002dbit-PLT-entries"></a> +<p>The ‘<samp>--long-plt</samp>’ option enables the use of 16 byte PLT entries +which support up to 4Gb of code. The default is to use 12 byte PLT +entries which only support 512Mb of code. +</p> +<a name="index-_002d_002dno_002dapply_002ddynamic_002drelocs"></a> +<a name="index-AArch64-rela-addend"></a> +<p>The ‘<samp>--no-apply-dynamic-relocs</samp>’ option makes AArch64 linker do not apply +link-time values for dynamic relocations. +</p> +<a name="index-Placement-of-SG-veneers"></a> +<p>All SG veneers are placed in the special output section <code>.gnu.sgstubs</code>. +Its start address must be set, either with the command-line option +‘<samp>--section-start</samp>’ or in a linker script, to indicate where to place these +veneers in memory. +</p> +<a name="index-_002d_002dcmse_002dimplib"></a> +<a name="index-Secure-gateway-import-library"></a> +<p>The ‘<samp>--cmse-implib</samp>’ option requests that the import libraries +specified by the ‘<samp>--out-implib</samp>’ and ‘<samp>--in-implib</samp>’ options are +secure gateway import libraries, suitable for linking a non-secure +executable against secure code as per ARMv8-M Security Extensions. +</p> +<a name="index-_002d_002din_002dimplib_003dfile"></a> +<a name="index-Input-import-library"></a> +<p>The ‘<samp>--in-implib=file</samp>’ specifies an input import library whose symbols +must keep the same address in the executable being produced. A warning is +given if no ‘<samp>--out-implib</samp>’ is given but new symbols have been introduced +in the executable that should be listed in its import library. Otherwise, if +‘<samp>--out-implib</samp>’ is specified, the symbols are added to the output import +library. A warning is also given if some symbols present in the input import +library have disappeared from the executable. This option is only effective +for Secure Gateway import libraries, ie. when ‘<samp>--cmse-implib</samp>’ is +specified. +</p> + + +<hr> +<a name="HPPA-ELF32"></a> +<div class="header"> +<p> +Next: <a href="#M68K" accesskey="n" rel="next">M68K</a>, Previous: <a href="#ARM" accesskey="p" rel="previous">ARM</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-HPPA-32_002dbit-ELF-Support"></a> +<h3 class="section">5.4 <code>ld</code> and HPPA 32-bit ELF Support</h3> +<a name="index-HPPA-multiple-sub_002dspace-stubs"></a> +<a name="index-_002d_002dmulti_002dsubspace"></a> +<p>When generating a shared library, <code>ld</code> will by default generate +import stubs suitable for use with a single sub-space application. +The ‘<samp>--multi-subspace</samp>’ switch causes <code>ld</code> to generate export +stubs, and different (larger) import stubs suitable for use with +multiple sub-spaces. +</p> +<a name="index-HPPA-stub-grouping"></a> +<a name="index-_002d_002dstub_002dgroup_002dsize_003dN-1"></a> +<p>Long branch stubs and import/export stubs are placed by <code>ld</code> in +stub sections located between groups of input sections. +‘<samp>--stub-group-size</samp>’ 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</samp>’ chooses this scheme, ensuring that +branches to stubs always use a negative offset. Two special values of +‘<samp>N</samp>’ are recognized, ‘<samp>1</samp>’ and ‘<samp>-1</samp>’. These both instruct +<code>ld</code> 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</samp>’ respectively. +</p> +<p>Note that ‘<samp>--stub-group-size</samp>’ 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. +</p> + + +<hr> +<a name="M68K"></a> +<div class="header"> +<p> +Next: <a href="#MIPS" accesskey="n" rel="next">MIPS</a>, Previous: <a href="#HPPA-ELF32" accesskey="p" rel="previous">HPPA ELF32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-the-Motorola-68K-family"></a> +<h3 class="section">5.5 <code>ld</code> and the Motorola 68K family</h3> + +<a name="index-Motorola-68K-GOT-generation"></a> +<a name="index-_002d_002dgot_003dtype"></a> +<p>The ‘<samp>--got=<var>type</var></samp>’ option lets you choose the GOT generation scheme. +The choices are ‘<samp>single</samp>’, ‘<samp>negative</samp>’, ‘<samp>multigot</samp>’ and +‘<samp>target</samp>’. When ‘<samp>target</samp>’ is selected the linker chooses +the default GOT generation scheme for the current target. +‘<samp>single</samp>’ tells the linker to generate a single GOT with +entries only at non-negative offsets. +‘<samp>negative</samp>’ instructs the linker to generate a single GOT with +entries at both negative and positive offsets. Not all environments +support such GOTs. +‘<samp>multigot</samp>’ allows the linker to generate several GOTs in the +output file. All GOT references from a single input object +file access the same GOT, but references from different input object +files might access different GOTs. Not all environments support such GOTs. +</p> + + +<hr> +<a name="MIPS"></a> +<div class="header"> +<p> +Next: <a href="#MMIX" accesskey="n" rel="next">MMIX</a>, Previous: <a href="#M68K" accesskey="p" rel="previous">M68K</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-the-MIPS-family"></a> +<h3 class="section">5.6 <code>ld</code> and the MIPS family</h3> + +<a name="index-MIPS-microMIPS-instruction-choice-selection"></a> +<a name="index-_002d_002dinsn32-1"></a> +<a name="index-_002d_002dno_002dinsn32-1"></a> +<p>The ‘<samp>--insn32</samp>’ and ‘<samp>--no-insn32</samp>’ options control the choice of +microMIPS instructions used in code generated by the linker, such as that +in the PLT or lazy binding stubs, or in relaxation. If ‘<samp>--insn32</samp>’ is +used, then the linker only uses 32-bit instruction encodings. By default +or if ‘<samp>--no-insn32</samp>’ is used, all instruction encodings are used, +including 16-bit ones where possible. +</p> +<a name="index-MIPS-branch-relocation-check-control"></a> +<a name="index-_002d_002dignore_002dbranch_002disa-1"></a> +<a name="index-_002d_002dno_002dignore_002dbranch_002disa-1"></a> +<p>The ‘<samp>--ignore-branch-isa</samp>’ and ‘<samp>--no-ignore-branch-isa</samp>’ options +control branch relocation checks for invalid ISA mode transitions. If +‘<samp>--ignore-branch-isa</samp>’ is used, then the linker accepts any branch +relocations and any ISA mode transition required is lost in relocation +calculation, except for some cases of <code>BAL</code> instructions which meet +relaxation conditions and are converted to equivalent <code>JALX</code> +instructions as the associated relocation is calculated. By default +or if ‘<samp>--no-ignore-branch-isa</samp>’ is used a check is made causing +the loss of an ISA mode transition to produce an error. +</p> + + +<hr> +<a name="MMIX"></a> +<div class="header"> +<p> +Next: <a href="#MSP430" accesskey="n" rel="next">MSP430</a>, Previous: <a href="#MIPS" accesskey="p" rel="previous">MIPS</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-MMIX"></a> +<h3 class="section">5.7 <code>ld</code> and MMIX</h3> +<p>For MMIX, there is a choice of generating <code>ELF</code> object files or +<code>mmo</code> object files when linking. The simulator <code>mmix</code> +understands the <code>mmo</code> format. The binutils <code>objcopy</code> utility +can translate between the two formats. +</p> +<p>There is one special section, the ‘<samp>.MMIX.reg_contents</samp>’ section. +Contents in this section is assumed to correspond to that of global +registers, and symbols referring to it are translated to special symbols, +equal to registers. In a final link, the start address of the +‘<samp>.MMIX.reg_contents</samp>’ section corresponds to the first allocated +global register multiplied by 8. Register <code>$255</code> is not included in +this section; it is always set to the program entry, which is at the +symbol <code>Main</code> for <code>mmo</code> files. +</p> +<p>Global symbols with the prefix <code>__.MMIX.start.</code>, for example +<code>__.MMIX.start..text</code> and <code>__.MMIX.start..data</code> are special. +The default linker script uses these to set the default start address +of a section. +</p> +<p>Initial and trailing multiples of zero-valued 32-bit words in a section, +are left out from an mmo file. +</p> + + +<hr> +<a name="MSP430"></a> +<div class="header"> +<p> +Next: <a href="#NDS32" accesskey="n" rel="next">NDS32</a>, Previous: <a href="#MMIX" accesskey="p" rel="previous">MMIX</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-MSP430"></a> +<h3 class="section">5.8 <code>ld</code> and MSP430</h3> +<p>For the MSP430 it is possible to select the MPU architecture. The flag ‘<samp>-m [mpu type]</samp>’ +will select an appropriate linker script for selected MPU type. (To get a list of known MPUs +just pass ‘<samp>-m help</samp>’ option to the linker). +</p> +<a name="index-MSP430-extra-sections"></a> +<p>The linker will recognize some extra sections which are MSP430 specific: +</p> +<dl compact="compact"> +<dt><code>‘<samp>.vectors</samp>’</code></dt> +<dd><p>Defines a portion of ROM where interrupt vectors located. +</p> +</dd> +<dt><code>‘<samp>.bootloader</samp>’</code></dt> +<dd><p>Defines the bootloader portion of the ROM (if applicable). Any code +in this section will be uploaded to the MPU. +</p> +</dd> +<dt><code>‘<samp>.infomem</samp>’</code></dt> +<dd><p>Defines an information memory section (if applicable). Any code in +this section will be uploaded to the MPU. +</p> +</dd> +<dt><code>‘<samp>.infomemnobits</samp>’</code></dt> +<dd><p>This is the same as the ‘<samp>.infomem</samp>’ section except that any code +in this section will not be uploaded to the MPU. +</p> +</dd> +<dt><code>‘<samp>.noinit</samp>’</code></dt> +<dd><p>Denotes a portion of RAM located above ‘<samp>.bss</samp>’ section. +</p> +<p>The last two sections are used by gcc. +</p></dd> +</dl> + +<dl compact="compact"> +<dd><a name="index-MSP430-Options"></a> +<a name="index-_002d_002dcode_002dregion"></a> +</dd> +<dt><samp>--code-region=[either,lower,upper,none]</samp></dt> +<dd><p>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. +</p> +<a name="index-_002d_002ddata_002dregion"></a> +</dd> +<dt><samp>--data-region=[either,lower,upper,none]</samp></dt> +<dd><p>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. +</p> +<a name="index-_002d_002ddisable_002dsec_002dtransformation"></a> +</dd> +<dt><samp>--disable-sec-transformation</samp></dt> +<dd><p>Prevent the transformation of sections as specified by the <code>--code-region</code> +and <code>--data-region</code> 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. +</p></dd> +</dl> + + + +<hr> +<a name="NDS32"></a> +<div class="header"> +<p> +Next: <a href="#Nios-II" accesskey="n" rel="next">Nios II</a>, Previous: <a href="#MSP430" accesskey="p" rel="previous">MSP430</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-NDS32"></a> +<h3 class="section">5.9 <code>ld</code> and NDS32</h3> +<a name="index-relaxing-on-NDS32"></a> +<p>For NDS32, there are some options to select relaxation behavior. The linker +relaxes objects according to these options. +</p> +<dl compact="compact"> +<dt><code>‘<samp>--m[no-]fp-as-gp</samp>’</code></dt> +<dd><p>Disable/enable fp-as-gp relaxation. +</p> +</dd> +<dt><code>‘<samp>--mexport-symbols=FILE</samp>’</code></dt> +<dd><p>Exporting symbols and their address into FILE as linker script. +</p> +</dd> +<dt><code>‘<samp>--m[no-]ex9</samp>’</code></dt> +<dd><p>Disable/enable link-time EX9 relaxation. +</p> +</dd> +<dt><code>‘<samp>--mexport-ex9=FILE</samp>’</code></dt> +<dd><p>Export the EX9 table after linking. +</p> +</dd> +<dt><code>‘<samp>--mimport-ex9=FILE</samp>’</code></dt> +<dd><p>Import the Ex9 table for EX9 relaxation. +</p> +</dd> +<dt><code>‘<samp>--mupdate-ex9</samp>’</code></dt> +<dd><p>Update the existing EX9 table. +</p> +</dd> +<dt><code>‘<samp>--mex9-limit=NUM</samp>’</code></dt> +<dd><p>Maximum number of entries in the ex9 table. +</p> +</dd> +<dt><code>‘<samp>--mex9-loop-aware</samp>’</code></dt> +<dd><p>Avoid generating the EX9 instruction inside the loop. +</p> +</dd> +<dt><code>‘<samp>--m[no-]ifc</samp>’</code></dt> +<dd><p>Disable/enable the link-time IFC optimization. +</p> +</dd> +<dt><code>‘<samp>--mifc-loop-aware</samp>’</code></dt> +<dd><p>Avoid generating the IFC instruction inside the loop. +</p></dd> +</dl> + + + +<hr> +<a name="Nios-II"></a> +<div class="header"> +<p> +Next: <a href="#PowerPC-ELF32" accesskey="n" rel="next">PowerPC ELF32</a>, Previous: <a href="#NDS32" accesskey="p" rel="previous">NDS32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-the-Altera-Nios-II"></a> +<h3 class="section">5.10 <code>ld</code> and the Altera Nios II</h3> +<a name="index-Nios-II-call-relaxation"></a> +<a name="index-_002d_002drelax-on-Nios-II"></a> + +<p>Call and immediate jump instructions on Nios II processors are limited to +transferring control to addresses in the same 256MB memory segment, +which may result in <code>ld</code> giving +‘<samp>relocation truncated to fit</samp>’ errors with very large programs. +The command-line option <samp>--relax</samp> enables the generation of +trampolines that can access the entire 32-bit address space for calls +outside the normal <code>call</code> and <code>jmpi</code> address range. These +trampolines are inserted at section boundaries, so may not themselves +be reachable if an input section and its associated call trampolines are +larger than 256MB. +</p> +<p>The <samp>--relax</samp> option is enabled by default unless <samp>-r</samp> +is also specified. You can disable trampoline generation by using the +<samp>--no-relax</samp> linker option. You can also disable this optimization +locally by using the ‘<samp>set .noat</samp>’ directive in assembly-language +source files, as the linker-inserted trampolines use the <code>at</code> +register as a temporary. +</p> +<p>Note that the linker <samp>--relax</samp> option is independent of assembler +relaxation options, and that using the GNU assembler’s <samp>-relax-all</samp> +option interferes with the linker’s more selective call instruction relaxation. +</p> + + +<hr> +<a name="PowerPC-ELF32"></a> +<div class="header"> +<p> +Next: <a href="#PowerPC64-ELF64" accesskey="n" rel="next">PowerPC64 ELF64</a>, Previous: <a href="#Nios-II" accesskey="p" rel="previous">Nios II</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-PowerPC-32_002dbit-ELF-Support"></a> +<h3 class="section">5.11 <code>ld</code> and PowerPC 32-bit ELF Support</h3> +<a name="index-PowerPC-long-branches"></a> +<a name="index-_002d_002drelax-on-PowerPC"></a> +<p>Branches on PowerPC processors are limited to a signed 26-bit +displacement, which may result in <code>ld</code> giving +‘<samp>relocation truncated to fit</samp>’ errors with very large programs. +‘<samp>--relax</samp>’ 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. You may combine ‘<samp>-r</samp>’ and +‘<samp>--relax</samp>’ 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. +</p> +<a name="index-PowerPC-ELF32-options"></a> +<dl compact="compact"> +<dd><a name="index-PowerPC-PLT"></a> +<a name="index-_002d_002dbss_002dplt"></a> +</dd> +<dt><samp>--bss-plt</samp></dt> +<dd><p>Current PowerPC GCC accepts a ‘<samp>-msecure-plt</samp>’ option that +generates code capable of using a newer PLT and GOT layout that has +the security advantage of no executable section ever needing to be +writable and no writable section ever being executable. PowerPC +<code>ld</code> will generate this layout, including stubs to access the +PLT, if all input files (including startup and static libraries) were +compiled with ‘<samp>-msecure-plt</samp>’. ‘<samp>--bss-plt</samp>’ forces the old +BSS PLT (and GOT layout) which can give slightly better performance. +</p> +<a name="index-_002d_002dsecure_002dplt"></a> +</dd> +<dt><samp>--secure-plt</samp></dt> +<dd><p><code>ld</code> will use the new PLT and GOT layout if it is linking new +‘<samp>-fpic</samp>’ or ‘<samp>-fPIC</samp>’ code, but does not do so automatically +when linking non-PIC code. This option requests the new PLT and GOT +layout. A warning will be given if some object file requires the old +style BSS PLT. +</p> +<a name="index-PowerPC-GOT"></a> +<a name="index-_002d_002dsdata_002dgot"></a> +</dd> +<dt><samp>--sdata-got</samp></dt> +<dd><p>The new secure PLT and GOT are placed differently relative to other +sections compared to older BSS PLT and GOT placement. The location of +<code>.plt</code> must change because the new secure PLT is an initialized +section while the old PLT is uninitialized. The reason for the +<code>.got</code> change is more subtle: The new placement allows +<code>.got</code> to be read-only in applications linked with +‘<samp>-z relro -z now</samp>’. However, this placement means that +<code>.sdata</code> cannot always be used in shared libraries, because the +PowerPC ABI accesses <code>.sdata</code> in shared libraries from the GOT +pointer. ‘<samp>--sdata-got</samp>’ forces the old GOT placement. PowerPC +GCC doesn’t use <code>.sdata</code> in shared libraries, so this option is +really only useful for other compilers that may do so. +</p> +<a name="index-PowerPC-stub-symbols"></a> +<a name="index-_002d_002demit_002dstub_002dsyms"></a> +</dd> +<dt><samp>--emit-stub-syms</samp></dt> +<dd><p>This option causes <code>ld</code> to label linker stubs with a local +symbol that encodes the stub type and destination. +</p> +<a name="index-PowerPC-TLS-optimization"></a> +<a name="index-_002d_002dno_002dtls_002doptimize"></a> +</dd> +<dt><samp>--no-tls-optimize</samp></dt> +<dd><p>PowerPC <code>ld</code> normally performs some optimization of code +sequences used to access Thread-Local Storage. Use this option to +disable the optimization. +</p></dd> +</dl> + + + +<hr> +<a name="PowerPC64-ELF64"></a> +<div class="header"> +<p> +Next: <a href="#S_002f390-ELF" accesskey="n" rel="next">S/390 ELF</a>, Previous: <a href="#PowerPC-ELF32" accesskey="p" rel="previous">PowerPC ELF32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-PowerPC64-64_002dbit-ELF-Support"></a> +<h3 class="section">5.12 <code>ld</code> and PowerPC64 64-bit ELF Support</h3> + +<a name="index-PowerPC64-ELF64-options"></a> +<dl compact="compact"> +<dd><a name="index-PowerPC64-stub-grouping"></a> +<a name="index-_002d_002dstub_002dgroup_002dsize"></a> +</dd> +<dt><samp>--stub-group-size</samp></dt> +<dd><p>Long branch stubs, PLT call stubs and TOC adjusting stubs are placed +by <code>ld</code> in stub sections located between groups of input sections. +‘<samp>--stub-group-size</samp>’ 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</samp>’ chooses this scheme, ensuring that +branches to stubs always use a negative offset. Two special values of +‘<samp>N</samp>’ are recognized, ‘<samp>1</samp>’ and ‘<samp>-1</samp>’. These both instruct +<code>ld</code> 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</samp>’ respectively. +</p> +<p>Note that ‘<samp>--stub-group-size</samp>’ 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. +</p> +<a name="index-PowerPC64-stub-symbols"></a> +<a name="index-_002d_002demit_002dstub_002dsyms-1"></a> +</dd> +<dt><samp>--emit-stub-syms</samp></dt> +<dd><p>This option causes <code>ld</code> to label linker stubs with a local +symbol that encodes the stub type and destination. +</p> +<a name="index-PowerPC64-dot-symbols"></a> +<a name="index-_002d_002ddotsyms"></a> +<a name="index-_002d_002dno_002ddotsyms"></a> +</dd> +<dt><samp>--dotsyms</samp></dt> +<dt><samp>--no-dotsyms</samp></dt> +<dd><p>These two options control how <code>ld</code> interprets version patterns +in a version script. Older PowerPC64 compilers emitted both a +function descriptor symbol with the same name as the function, and a +code entry symbol with the name prefixed by a dot (‘<samp>.</samp>’). To +properly version a function ‘<samp>foo</samp>’, the version script thus needs +to control both ‘<samp>foo</samp>’ and ‘<samp>.foo</samp>’. The option +‘<samp>--dotsyms</samp>’, on by default, automatically adds the required +dot-prefixed patterns. Use ‘<samp>--no-dotsyms</samp>’ to disable this +feature. +</p> +<a name="index-PowerPC64-register-save_002frestore-functions"></a> +<a name="index-_002d_002dsave_002drestore_002dfuncs"></a> +<a name="index-_002d_002dno_002dsave_002drestore_002dfuncs"></a> +</dd> +<dt><samp>--save-restore-funcs</samp></dt> +<dt><samp>--no-save-restore-funcs</samp></dt> +<dd><p>These two options control whether PowerPC64 <code>ld</code> automatically +provides out-of-line register save and restore functions used by +‘<samp>-Os</samp>’ code. The default is to provide any such referenced +function for a normal final link, and to not do so for a relocatable +link. +</p> +<a name="index-PowerPC64-TLS-optimization"></a> +<a name="index-_002d_002dno_002dtls_002doptimize-1"></a> +</dd> +<dt><samp>--no-tls-optimize</samp></dt> +<dd><p>PowerPC64 <code>ld</code> normally performs some optimization of code +sequences used to access Thread-Local Storage. Use this option to +disable the optimization. +</p> +<a name="index-PowerPC64-_005f_005ftls_005fget_005faddr-optimization"></a> +<a name="index-_002d_002dtls_002dget_002daddr_002doptimize"></a> +<a name="index-_002d_002dno_002dtls_002dget_002daddr_002doptimize"></a> +<a name="index-_002d_002dtls_002dget_002daddr_002dregsave"></a> +<a name="index-_002d_002dno_002dtls_002dget_002daddr_002dregsave"></a> +</dd> +<dt><samp>--tls-get-addr-optimize</samp></dt> +<dt><samp>--no-tls-get-addr-optimize</samp></dt> +<dd><p>These options control how PowerPC64 <code>ld</code> 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</code> for a given symbol to be resolved by the special +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 <samp>--tls-get-addr-optimize</samp> 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. +<samp>--tls-get-addr-regsave</samp> 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. +<samp>--no-tls-get-addr-regsave</samp> disables generation of the +register saves. +</p> +<a name="index-PowerPC64-OPD-optimization"></a> +<a name="index-_002d_002dno_002dopd_002doptimize"></a> +</dd> +<dt><samp>--no-opd-optimize</samp></dt> +<dd><p>PowerPC64 <code>ld</code> normally removes <code>.opd</code> section entries +corresponding to deleted link-once functions, or functions removed by +the action of ‘<samp>--gc-sections</samp>’ or linker script <code>/DISCARD/</code>. +Use this option to disable <code>.opd</code> optimization. +</p> +<a name="index-PowerPC64-OPD-spacing"></a> +<a name="index-_002d_002dnon_002doverlapping_002dopd"></a> +</dd> +<dt><samp>--non-overlapping-opd</samp></dt> +<dd><p>Some PowerPC64 compilers have an option to generate compressed +<code>.opd</code> entries spaced 16 bytes apart, overlapping the third word, +the static chain pointer (unused in C) with the first word of the next +entry. This option expands such entries to the full 24 bytes. +</p> +<a name="index-PowerPC64-TOC-optimization"></a> +<a name="index-_002d_002dno_002dtoc_002doptimize"></a> +</dd> +<dt><samp>--no-toc-optimize</samp></dt> +<dd><p>PowerPC64 <code>ld</code> normally removes unused <code>.toc</code> section +entries. Such entries are detected by examining relocations that +reference the TOC in code sections. A reloc in a deleted code section +marks a TOC word as unneeded, while a reloc in a kept code section +marks a TOC word as needed. Since the TOC may reference itself, TOC +relocs are also examined. TOC words marked as both needed and +unneeded will of course be kept. TOC words without any referencing +reloc are assumed to be part of a multi-word entry, and are kept or +discarded as per the nearest marked preceding word. This works +reliably for compiler generated code, but may be incorrect if assembly +code is used to insert TOC entries. Use this option to disable the +optimization. +</p> +<a name="index-PowerPC64-inline-PLT-call-optimization"></a> +<a name="index-_002d_002dno_002dinline_002doptimize"></a> +</dd> +<dt><samp>--no-inline-optimize</samp></dt> +<dd><p>PowerPC64 <code>ld</code> normally replaces inline PLT call sequences +marked with <code>R_PPC64_PLTSEQ</code>, <code>R_PPC64_PLTCALL</code>, +<code>R_PPC64_PLT16_HA</code> and <code>R_PPC64_PLT16_LO_DS</code> relocations by +a number of <code>nop</code>s and a direct call when the function is defined +locally and can’t be overridden by some other definition. This option +disables that optimization. +</p> +<a name="index-PowerPC64-multi_002dTOC"></a> +<a name="index-_002d_002dno_002dmulti_002dtoc"></a> +</dd> +<dt><samp>--no-multi-toc</samp></dt> +<dd><p>If given any toc option besides <code>-mcmodel=medium</code> or +<code>-mcmodel=large</code>, PowerPC64 GCC generates code for a TOC model +where TOC +entries are accessed with a 16-bit offset from r2. This limits the +total TOC size to 64K. PowerPC64 <code>ld</code> extends this limit by +grouping code sections such that each group uses less than 64K for its +TOC entries, then inserts r2 adjusting stubs between inter-group +calls. <code>ld</code> does not split apart input sections, so cannot +help if a single input file has a <code>.toc</code> section that exceeds +64K, most likely from linking multiple files with <code>ld -r</code>. +Use this option to turn off this feature. +</p> +<a name="index-PowerPC64-TOC-sorting"></a> +<a name="index-_002d_002dno_002dtoc_002dsort"></a> +</dd> +<dt><samp>--no-toc-sort</samp></dt> +<dd><p>By default, <code>ld</code> sorts TOC sections so that those whose file +happens to have a section called <code>.init</code> or <code>.fini</code> are +placed first, followed by TOC sections referenced by code generated +with PowerPC64 gcc’s <code>-mcmodel=small</code>, and lastly TOC sections +referenced only by code generated with PowerPC64 gcc’s +<code>-mcmodel=medium</code> or <code>-mcmodel=large</code> options. Doing this +results in better TOC grouping for multi-TOC. Use this option to turn +off this feature. +</p> +<a name="index-PowerPC64-PLT-stub-alignment"></a> +<a name="index-_002d_002dplt_002dalign"></a> +<a name="index-_002d_002dno_002dplt_002dalign"></a> +</dd> +<dt><samp>--plt-align</samp></dt> +<dt><samp>--no-plt-align</samp></dt> +<dd><p>Use these options to control whether individual PLT call stubs are +aligned to a 32-byte boundary, or to the specified power of two +boundary when using <code>--plt-align=</code>. A negative value may be +specified to pad PLT call stubs so that they do not cross the +specified power of two boundary (or the minimum number of boundaries +if a PLT stub is so large that it must cross a boundary). By default +PLT call stubs are aligned to 32-byte boundaries. +</p> +<a name="index-PowerPC64-PLT-call-stub-static-chain"></a> +<a name="index-_002d_002dplt_002dstatic_002dchain"></a> +<a name="index-_002d_002dno_002dplt_002dstatic_002dchain"></a> +</dd> +<dt><samp>--plt-static-chain</samp></dt> +<dt><samp>--no-plt-static-chain</samp></dt> +<dd><p>Use these options to control whether PLT call stubs load the static +chain pointer (r11). <code>ld</code> defaults to not loading the static +chain since there is never any need to do so on a PLT call. +</p> +<a name="index-PowerPC64-PLT-call-stub-thread-safety"></a> +<a name="index-_002d_002dplt_002dthread_002dsafe"></a> +<a name="index-_002d_002dno_002dplt_002dthread_002dsafe"></a> +</dd> +<dt><samp>--plt-thread-safe</samp></dt> +<dt><samp>--no-plt-thread-safe</samp></dt> +<dd><p>With power7’s weakly ordered memory model, it is possible when using +lazy binding for ld.so to update a plt entry in one thread and have +another thread see the individual plt entry words update in the wrong +order, despite ld.so carefully writing in the correct order and using +memory write barriers. To avoid this we need some sort of read +barrier in the call stub, or use LD_BIND_NOW=1. By default, <code>ld</code> +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. +</p> +<a name="index-PowerPC64-ELFv2-PLT-localentry-optimization"></a> +<a name="index-_002d_002dplt_002dlocalentry"></a> +<a name="index-_002d_002dno_002dplt_002dlocalentry"></a> +</dd> +<dt><samp>--plt-localentry</samp></dt> +<dt><samp>--no-localentry</samp></dt> +<dd><p>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. <samp>--no-plt-localentry</samp> is the default. +</p> +<a name="index-PowerPC64-Power10-stubs"></a> +<a name="index-_002d_002dpower10_002dstubs"></a> +<a name="index-_002d_002dno_002dpower10_002dstubs"></a> +</dd> +<dt><samp>--power10-stubs</samp></dt> +<dt><samp>--no-power10-stubs</samp></dt> +<dd><p>When PowerPC64 <code>ld</code> links input object files containing +relocations used on power10 prefixed instructions it normally creates +linkage stubs (PLT call and long branch) using power10 instructions +for <code>@notoc</code> PLT calls where <code>r2</code> is not known. The +power10 notoc stubs are smaller and faster, so are preferred for +power10. <samp>--power10-stubs</samp> and <samp>--no-power10-stubs</samp> +allow you to override the linker’s selection of stub instructions. +<samp>--power10-stubs=auto</samp> allows the user to select the default +auto mode. +</p></dd> +</dl> + + + +<hr> +<a name="S_002f390-ELF"></a> +<div class="header"> +<p> +Next: <a href="#SPU-ELF" accesskey="n" rel="next">SPU ELF</a>, Previous: <a href="#PowerPC64-ELF64" accesskey="p" rel="previous">PowerPC64 ELF64</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-S_002f390-ELF-Support"></a> +<h3 class="section">5.13 <code>ld</code> and S/390 ELF Support</h3> + +<a name="index-S_002f390-ELF-options"></a> +<dl compact="compact"> +<dd> +<a name="index-S_002f390"></a> +<a name="index-_002d_002ds390_002dpgste"></a> +</dd> +<dt><samp>--s390-pgste</samp></dt> +<dd><p>This option marks the result file with a <code>PT_S390_PGSTE</code> +segment. The Linux kernel is supposed to allocate 4k page tables for +binaries marked that way. +</p></dd> +</dl> + + + +<hr> +<a name="SPU-ELF"></a> +<div class="header"> +<p> +Next: <a href="#TI-COFF" accesskey="n" rel="next">TI COFF</a>, Previous: <a href="#S_002f390-ELF" accesskey="p" rel="previous">S/390 ELF</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-SPU-ELF-Support"></a> +<h3 class="section">5.14 <code>ld</code> and SPU ELF Support</h3> + +<a name="index-SPU-ELF-options"></a> +<dl compact="compact"> +<dd> +<a name="index-SPU-plugins"></a> +<a name="index-_002d_002dplugin"></a> +</dd> +<dt><samp>--plugin</samp></dt> +<dd><p>This option marks an executable as a PIC plugin module. +</p> +<a name="index-SPU-overlays"></a> +<a name="index-_002d_002dno_002doverlays"></a> +</dd> +<dt><samp>--no-overlays</samp></dt> +<dd><p>Normally, <code>ld</code> recognizes calls to functions within overlay +regions, and redirects such calls to an overlay manager via a stub. +<code>ld</code> also provides a built-in overlay manager. This option +turns off all this special overlay handling. +</p> +<a name="index-SPU-overlay-stub-symbols"></a> +<a name="index-_002d_002demit_002dstub_002dsyms-2"></a> +</dd> +<dt><samp>--emit-stub-syms</samp></dt> +<dd><p>This option causes <code>ld</code> to label overlay stubs with a local +symbol that encodes the stub type and destination. +</p> +<a name="index-SPU-extra-overlay-stubs"></a> +<a name="index-_002d_002dextra_002doverlay_002dstubs"></a> +</dd> +<dt><samp>--extra-overlay-stubs</samp></dt> +<dd><p>This option causes <code>ld</code> to add overlay call stubs on all +function calls out of overlay regions. Normally stubs are not added +on calls to non-overlay regions. +</p> +<a name="index-SPU-local-store-size"></a> +<a name="index-_002d_002dlocal_002dstore_003dlo_003ahi"></a> +</dd> +<dt><samp>--local-store=lo:hi</samp></dt> +<dd><p><code>ld</code> usually checks that a final executable for SPU fits in +the address range 0 to 256k. This option may be used to change the +range. Disable the check entirely with <samp>--local-store=0:0</samp>. +</p> +<a name="index-SPU"></a> +<a name="index-_002d_002dstack_002danalysis"></a> +</dd> +<dt><samp>--stack-analysis</samp></dt> +<dd><p>SPU local store space is limited. Over-allocation of stack space +unnecessarily limits space available for code and data, while +under-allocation results in runtime failures. If given this option, +<code>ld</code> will provide an estimate of maximum stack usage. +<code>ld</code> does this by examining symbols in code sections to +determine the extents of functions, and looking at function prologues +for stack adjusting instructions. A call-graph is created by looking +for relocations on branch instructions. The graph is then searched +for the maximum stack usage path. Note that this analysis does not +find calls made via function pointers, and does not handle recursion +and other cycles in the call graph. Stack usage may be +under-estimated if your code makes such calls. Also, stack usage for +dynamic allocation, e.g. alloca, will not be detected. If a link map +is requested, detailed information about each function’s stack usage +and calls will be given. +</p> +<a name="index-SPU-1"></a> +<a name="index-_002d_002demit_002dstack_002dsyms"></a> +</dd> +<dt><samp>--emit-stack-syms</samp></dt> +<dd><p>This option, if given along with <samp>--stack-analysis</samp> will result +in <code>ld</code> emitting stack sizing symbols for each function. +These take the form <code>__stack_<function_name></code> for global +functions, and <code>__stack_<number>_<function_name></code> for static +functions. <code><number></code> is the section id in hex. The value of +such symbols is the stack requirement for the corresponding function. +The symbol size will be zero, type <code>STT_NOTYPE</code>, binding +<code>STB_LOCAL</code>, and section <code>SHN_ABS</code>. +</p></dd> +</dl> + + + +<hr> +<a name="TI-COFF"></a> +<div class="header"> +<p> +Next: <a href="#WIN32" accesskey="n" rel="next">WIN32</a>, Previous: <a href="#SPU-ELF" accesskey="p" rel="previous">SPU ELF</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld_0027s-Support-for-Various-TI-COFF-Versions"></a> +<h3 class="section">5.15 <code>ld</code>’s Support for Various TI COFF Versions</h3> +<a name="index-TI-COFF-versions"></a> +<a name="index-_002d_002dformat_003dversion"></a> +<p>The ‘<samp>--format</samp>’ 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</code> will read any version or byte order, but the output +header format depends on the default specified by the specific target. +</p> + + +<hr> +<a name="WIN32"></a> +<div class="header"> +<p> +Next: <a href="#Xtensa" accesskey="n" rel="next">Xtensa</a>, Previous: <a href="#TI-COFF" accesskey="p" rel="previous">TI COFF</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-WIN32-_0028cygwin_002fmingw_0029"></a> +<h3 class="section">5.16 <code>ld</code> and WIN32 (cygwin/mingw)</h3> + +<p>This section describes some of the win32 specific <code>ld</code> issues. +See <a href="#Options">Command-line Options</a> for detailed description of the +command-line options mentioned here. +</p> +<dl compact="compact"> +<dd><a name="index-import-libraries"></a> +</dd> +<dt><em>import libraries</em></dt> +<dd><p>The standard Windows linker creates and uses so-called import +libraries, which contains information for linking to dll’s. They are +regular static archives and are handled as any other static +archive. The cygwin and mingw ports of <code>ld</code> have specific +support for creating such libraries provided with the +‘<samp>--out-implib</samp>’ command-line option. +</p> +</dd> +<dt><em>Resource only DLLs</em></dt> +<dd><p>It is possible to create a DLL that only contains resources, ie just a +‘<samp>.rsrc</samp>’ section, but in order to do so a custom linker script +must be used. This is because the built-in default linker scripts +will always create ‘<samp>.text</samp>’ and ‘<samp>.idata</samp>’ sections, even if +there is no input to go into them. +</p> +<p>The script should look like this, although the <code>OUTPUT_FORMAT</code> +should be changed to match the desired format. +</p> +<div class="example"> +<pre class="example">OUTPUT_FORMAT(pei-i386) +SECTIONS +{ + . = SIZEOF_HEADERS; + . = ALIGN(__section_alignment__); + .rsrc __image_base__ + __section_alignment__ : ALIGN(4) + { + KEEP (*(.rsrc)) + KEEP (*(.rsrc$*)) + } + /DISCARD/ : { *(*) } +} +</pre></div> + +<p>With this script saved to a file called, eg <samp>rsrc.ld</samp>, a command +line like this can be used to create the resource only DLL +<samp>rsrc.dll</samp> from an input file called <samp>rsrc.o</samp>: +</p> +<div class="smallexample"> +<pre class="smallexample">ld -dll --subsystem windows -e 0 -s rsrc.o -o rsrc.dll -T rsrc.ld +</pre></div> + +</dd> +<dt><em>exporting DLL symbols</em></dt> +<dd><a name="index-exporting-DLL-symbols"></a> +<p>The cygwin/mingw <code>ld</code> has several ways to export symbols for dll’s. +</p> +<dl compact="compact"> +<dt><em>using auto-export functionality</em></dt> +<dd><a name="index-using-auto_002dexport-functionality"></a> +<p>By default <code>ld</code> exports symbols with the auto-export functionality, +which is controlled by the following command-line options: +</p> +<ul> +<li> –export-all-symbols [This is the default] +</li><li> –exclude-symbols +</li><li> –exclude-libs +</li><li> –exclude-modules-for-implib +</li><li> –version-script +</li></ul> + +<p>When auto-export is in operation, <code>ld</code> 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</samp>’ option can be used in order to see the +final list of exported symbols with all exclusions taken into effect. +</p> +<p>If ‘<samp>--export-all-symbols</samp>’ is not given explicitly on the +command line, then the default auto-export behavior will be <em>disabled</em> +if either of the following are true: +</p> +<ul> +<li> A DEF file is used. +</li><li> Any symbol in any object file was marked with the __declspec(dllexport) attribute. +</li></ul> + +</dd> +<dt><em>using a DEF file</em></dt> +<dd><a name="index-using-a-DEF-file"></a> +<p>Another way of exporting symbols is using a DEF file. A DEF file is +an ASCII file containing definitions of symbols which should be +exported when a dll is created. Usually it is named ‘<samp><dll +name>.def</samp>’ and is added as any other object file to the linker’s +command line. The file’s name must end in ‘<samp>.def</samp>’ or ‘<samp>.DEF</samp>’. +</p> +<div class="example"> +<pre class="example">gcc -o <output> <objectfiles> <dll name>.def +</pre></div> + +<p>Using a DEF file turns off the normal auto-export behavior, unless the +‘<samp>--export-all-symbols</samp>’ option is also used. +</p> +<p>Here is an example of a DEF file for a shared library called ‘<samp>xyz.dll</samp>’: +</p> +<div class="example"> +<pre class="example">LIBRARY "xyz.dll" BASE=0x20000000 + +EXPORTS +foo +bar +_bar = bar +another_foo = abc.dll.afoo +var1 DATA +doo = foo == foo2 +eoo DATA == var1 +</pre></div> + +<p>This example defines a DLL with a non-default base address and seven +symbols in the export table. The third exported symbol <code>_bar</code> is an +alias for the second. The fourth symbol, <code>another_foo</code> is resolved +by "forwarding" to another module and treating it as an alias for +<code>afoo</code> exported from the DLL ‘<samp>abc.dll</samp>’. The final symbol +<code>var1</code> is declared to be a data object. The ‘<samp>doo</samp>’ symbol in +export library is an alias of ‘<samp>foo</samp>’, which gets the string name +in export table ‘<samp>foo2</samp>’. The ‘<samp>eoo</samp>’ symbol is an data export +symbol, which gets in export table the name ‘<samp>var1</samp>’. +</p> +<p>The optional <code>LIBRARY <name></code> command indicates the <em>internal</em> +name of the output DLL. If ‘<samp><name></samp>’ does not include a suffix, +the default library suffix, ‘<samp>.DLL</samp>’ is appended. +</p> +<p>When the .DEF file is used to build an application, rather than a +library, the <code>NAME <name></code> command should be used instead of +<code>LIBRARY</code>. If ‘<samp><name></samp>’ does not include a suffix, the default +executable suffix, ‘<samp>.EXE</samp>’ is appended. +</p> +<p>With either <code>LIBRARY <name></code> or <code>NAME <name></code> the optional +specification <code>BASE = <number></code> may be used to specify a +non-default base address for the image. +</p> +<p>If neither <code>LIBRARY <name></code> nor <code>NAME <name></code> is specified, +or they specify an empty string, the internal name is the same as the +filename specified on the command line. +</p> +<p>The complete specification of an export symbol is: +</p> +<div class="example"> +<pre class="example">EXPORTS + ( ( ( <name1> [ = <name2> ] ) + | ( <name1> = <module-name> . <external-name>)) + [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) * +</pre></div> + +<p>Declares ‘<samp><name1></samp>’ as an exported symbol from the DLL, or declares +‘<samp><name1></samp>’ as an exported alias for ‘<samp><name2></samp>’; or declares +‘<samp><name1></samp>’ as a "forward" alias for the symbol +‘<samp><external-name></samp>’ in the DLL ‘<samp><module-name></samp>’. +Optionally, the symbol may be exported by the specified ordinal +‘<samp><integer></samp>’ alias. The optional ‘<samp><name3></samp>’ is the to be used +string in import/export table for the symbol. +</p> +<p>The optional keywords that follow the declaration indicate: +</p> +<p><code>NONAME</code>: Do not put the symbol name in the DLL’s export table. It +will still be exported by its ordinal alias (either the value specified +by the .def specification or, otherwise, the value assigned by the +linker). The symbol name, however, does remain visible in the import +library (if any), unless <code>PRIVATE</code> is also specified. +</p> +<p><code>DATA</code>: The symbol is a variable or object, rather than a function. +The import lib will export only an indirect reference to <code>foo</code> as +the symbol <code>_imp__foo</code> (ie, <code>foo</code> must be resolved as +<code>*_imp__foo</code>). +</p> +<p><code>CONSTANT</code>: Like <code>DATA</code>, but put the undecorated <code>foo</code> as +well as <code>_imp__foo</code> into the import library. Both refer to the +read-only import address table’s pointer to the variable, not to the +variable itself. This can be dangerous. If the user code fails to add +the <code>dllimport</code> attribute and also fails to explicitly add the +extra indirection that the use of the attribute enforces, the +application will behave unexpectedly. +</p> +<p><code>PRIVATE</code>: 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</code> +API at runtime or by using the GNU ld extension of linking directly to +the DLL without an import library. +</p> +<p>See ld/deffilep.y in the binutils sources for the full specification of +other DEF file statements +</p> +<a name="index-creating-a-DEF-file"></a> +<p>While linking a shared dll, <code>ld</code> is able to create a DEF file +with the ‘<samp>--output-def <file></samp>’ command-line option. +</p> +</dd> +<dt><em>Using decorations</em></dt> +<dd><a name="index-Using-decorations"></a> +<p>Another way of marking symbols for export is to modify the source code +itself, so that when building the DLL each symbol to be exported is +declared as: +</p> +<div class="example"> +<pre class="example">__declspec(dllexport) int a_variable +__declspec(dllexport) void a_function(int with_args) +</pre></div> + +<p>All such symbols will be exported from the DLL. If, however, +any of the object files in the DLL contain symbols decorated in +this way, then the normal auto-export behavior is disabled, unless +the ‘<samp>--export-all-symbols</samp>’ option is also used. +</p> +<p>Note that object files that wish to access these symbols must <em>not</em> +decorate them with dllexport. Instead, they should use dllimport, +instead: +</p> +<div class="example"> +<pre class="example">__declspec(dllimport) int a_variable +__declspec(dllimport) void a_function(int with_args) +</pre></div> + +<p>This complicates the structure of library header files, because +when included by the library itself the header must declare the +variables and functions as dllexport, but when included by client +code the header must declare them as dllimport. There are a number +of idioms that are typically used to do this; often client code can +omit the __declspec() declaration completely. See +‘<samp>--enable-auto-import</samp>’ and ‘<samp>automatic data imports</samp>’ for more +information. +</p></dd> +</dl> + +<a name="index-automatic-data-imports"></a> +</dd> +<dt><em>automatic data imports</em></dt> +<dd><p>The standard Windows dll format supports data imports from dlls only +by adding special decorations (dllimport/dllexport), which let the +compiler produce specific assembler instructions to deal with this +issue. This increases the effort necessary to port existing Un*x +code to these platforms, especially for large +c++ libraries and applications. The auto-import feature, which was +initially provided by Paul Sokolovsky, allows one to omit the +decorations to achieve a behavior that conforms to that on POSIX/Un*x +platforms. This feature is enabled with the ‘<samp>--enable-auto-import</samp>’ +command-line option, although it is enabled by default on cygwin/mingw. +The ‘<samp>--enable-auto-import</samp>’ option itself now serves mainly to +suppress any warnings that are ordinarily emitted when linked objects +trigger the feature’s use. +</p> +<p>auto-import of variables does not always work flawlessly without +additional assistance. Sometimes, you will see this message +</p> +<p>"variable ’<var>’ can’t be auto-imported. Please read the +documentation for ld’s <code>--enable-auto-import</code> for details." +</p> +<p>The ‘<samp>--enable-auto-import</samp>’ documentation explains why this error +occurs, and several methods that can be used to overcome this difficulty. +One of these methods is the <em>runtime pseudo-relocs</em> feature, described +below. +</p> +<a name="index-runtime-pseudo_002drelocation"></a> +<p>For complex variables imported from DLLs (such as structs or classes), +object files typically contain a base address for the variable and an +offset (<em>addend</em>) within the variable–to specify a particular +field or public member, for instance. Unfortunately, the runtime loader used +in win32 environments is incapable of fixing these references at runtime +without the additional information supplied by dllimport/dllexport decorations. +The standard auto-import feature described above is unable to resolve these +references. +</p> +<p>The ‘<samp>--enable-runtime-pseudo-relocs</samp>’ switch allows these references to +be resolved without error, while leaving the task of adjusting the references +themselves (with their non-zero addends) to specialized code provided by the +runtime environment. Recent versions of the cygwin and mingw environments and +compilers provide this runtime support; older versions do not. However, the +support is only necessary on the developer’s platform; the compiled result will +run without error on an older system. +</p> +<p>‘<samp>--enable-runtime-pseudo-relocs</samp>’ is not the default; it must be explicitly +enabled as needed. +</p> +<a name="index-direct-linking-to-a-dll"></a> +</dd> +<dt><em>direct linking to a dll</em></dt> +<dd><p>The cygwin/mingw ports of <code>ld</code> support the direct linking, +including data symbols, to a dll without the usage of any import +libraries. This is much faster and uses much less memory than does the +traditional import library method, especially when linking large +libraries or applications. When <code>ld</code> creates an import lib, each +function or variable exported from the dll is stored in its own bfd, even +though a single bfd could contain many exports. The overhead involved in +storing, loading, and processing so many bfd’s is quite large, and explains the +tremendous time, memory, and storage needed to link against particularly +large or complex libraries when using import libs. +</p> +<p>Linking directly to a dll uses no extra command-line switches other than +‘<samp>-L</samp>’ and ‘<samp>-l</samp>’, because <code>ld</code> already searches for a number +of names to match each library. All that is needed from the developer’s +perspective is an understanding of this search, in order to force ld to +select the dll instead of an import library. +</p> + +<p>For instance, when ld is called with the argument ‘<samp>-lxxx</samp>’ it will attempt +to find, in the first directory of its search path, +</p> +<div class="example"> +<pre class="example">libxxx.dll.a +xxx.dll.a +libxxx.a +xxx.lib +libxxx.lib +cygxxx.dll (*) +libxxx.dll +xxx.dll +</pre></div> + +<p>before moving on to the next directory in the search path. +</p> +<p>(*) Actually, this is not ‘<samp>cygxxx.dll</samp>’ but in fact is ‘<samp><prefix>xxx.dll</samp>’, +where ‘<samp><prefix></samp>’ is set by the <code>ld</code> option +‘<samp>--dll-search-prefix=<prefix></samp>’. In the case of cygwin, the standard gcc spec +file includes ‘<samp>--dll-search-prefix=cyg</samp>’, so in effect we actually search for +‘<samp>cygxxx.dll</samp>’. +</p> +<p>Other win32-based unix environments, such as mingw or pw32, may use other +‘<samp><prefix></samp>’es, although at present only cygwin makes use of this feature. It +was originally intended to help avoid name conflicts among dll’s built for the +various win32/un*x environments, so that (for example) two versions of a zlib dll +could coexist on the same machine. +</p> +<p>The generic cygwin/mingw path layout uses a ‘<samp>bin</samp>’ directory for +applications and dll’s and a ‘<samp>lib</samp>’ directory for the import +libraries (using cygwin nomenclature): +</p> +<div class="example"> +<pre class="example">bin/ + cygxxx.dll +lib/ + libxxx.dll.a (in case of dll's) + libxxx.a (in case of static archive) +</pre></div> + +<p>Linking directly to a dll without using the import library can be +done two ways: +</p> +<p>1. Use the dll directly by adding the ‘<samp>bin</samp>’ path to the link line +</p><div class="example"> +<pre class="example">gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx +</pre></div> + +<p>However, as the dll’s often have version numbers appended to their names +(‘<samp>cygncurses-5.dll</samp>’) this will often fail, unless one specifies +‘<samp>-L../bin -lncurses-5</samp>’ to include the version. Import libs are generally +not versioned, and do not have this difficulty. +</p> +<p>2. Create a symbolic link from the dll to a file in the ‘<samp>lib</samp>’ +directory according to the above mentioned search pattern. This +should be used to avoid unwanted changes in the tools needed for +making the app/dll. +</p> +<div class="example"> +<pre class="example">ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] +</pre></div> + +<p>Then you can link without any make environment changes. +</p> +<div class="example"> +<pre class="example">gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx +</pre></div> + +<p>This technique also avoids the version number problems, because the following is +perfectly legal +</p> +<div class="example"> +<pre class="example">bin/ + cygxxx-5.dll +lib/ + libxxx.dll.a -> ../bin/cygxxx-5.dll +</pre></div> + +<p>Linking directly to a dll without using an import lib will work +even when auto-import features are exercised, and even when +‘<samp>--enable-runtime-pseudo-relocs</samp>’ is used. +</p> +<p>Given the improvements in speed and memory usage, one might justifiably +wonder why import libraries are used at all. There are three reasons: +</p> +<p>1. Until recently, the link-directly-to-dll functionality did <em>not</em> +work with auto-imported data. +</p> +<p>2. Sometimes it is necessary to include pure static objects within the +import library (which otherwise contains only bfd’s for indirection +symbols that point to the exports of a dll). Again, the import lib +for the cygwin kernel makes use of this ability, and it is not +possible to do this without an import lib. +</p> +<p>3. Symbol aliases can only be resolved using an import lib. This is +critical when linking against OS-supplied dll’s (eg, the win32 API) +in which symbols are usually exported as undecorated aliases of their +stdcall-decorated assembly names. +</p> +<p>So, import libs are not going away. But the ability to replace +true import libs with a simple symbolic link to (or a copy of) +a dll, in many cases, is a useful addition to the suite of tools +binutils makes available to the win32 developer. Given the +massive improvements in memory requirements during linking, storage +requirements, and linking speed, we expect that many developers +will soon begin to use this feature whenever possible. +</p> +</dd> +<dt><em>symbol aliasing</em></dt> +<dd><dl compact="compact"> +<dt><em>adding additional names</em></dt> +<dd><p>Sometimes, it is useful to export symbols with additional names. +A symbol ‘<samp>foo</samp>’ will be exported as ‘<samp>foo</samp>’, but it can also be +exported as ‘<samp>_foo</samp>’ by using special directives in the DEF file +when creating the dll. This will affect also the optional created +import library. Consider the following DEF file: +</p> +<div class="example"> +<pre class="example">LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +foo +_foo = foo +</pre></div> + +<p>The line ‘<samp>_foo = foo</samp>’ maps the symbol ‘<samp>foo</samp>’ to ‘<samp>_foo</samp>’. +</p> +<p>Another method for creating a symbol alias is to create it in the +source code using the "weak" attribute: +</p> +<div class="example"> +<pre class="example">void foo () { /* Do something. */; } +void _foo () __attribute__ ((weak, alias ("foo"))); +</pre></div> + +<p>See the gcc manual for more information about attributes and weak +symbols. +</p> +</dd> +<dt><em>renaming symbols</em></dt> +<dd><p>Sometimes it is useful to rename exports. For instance, the cygwin +kernel does this regularly. A symbol ‘<samp>_foo</samp>’ can be exported as +‘<samp>foo</samp>’ but not as ‘<samp>_foo</samp>’ by using special directives in the +DEF file. (This will also affect the import library, if it is +created). In the following example: +</p> +<div class="example"> +<pre class="example">LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +_foo = foo +</pre></div> + +<p>The line ‘<samp>_foo = foo</samp>’ maps the exported symbol ‘<samp>foo</samp>’ to +‘<samp>_foo</samp>’. +</p></dd> +</dl> + +<p>Note: using a DEF file disables the default auto-export behavior, +unless the ‘<samp>--export-all-symbols</samp>’ command-line option is used. +If, however, you are trying to rename symbols, then you should list +<em>all</em> desired exports in the DEF file, including the symbols +that are not being renamed, and do <em>not</em> use the +‘<samp>--export-all-symbols</samp>’ option. If you list only the +renamed symbols in the DEF file, and use ‘<samp>--export-all-symbols</samp>’ +to handle the other symbols, then the both the new names <em>and</em> +the original names for the renamed symbols will be exported. +In effect, you’d be aliasing those symbols, not renaming them, +which is probably not what you wanted. +</p> +<a name="index-weak-externals"></a> +</dd> +<dt><em>weak externals</em></dt> +<dd><p>The Windows object format, PE, specifies a form of weak symbols called +weak externals. When a weak symbol is linked and the symbol is not +defined, the weak symbol becomes an alias for some other symbol. There +are three variants of weak externals: +</p><ul> +<li> Definition is searched for in objects and libraries, historically +called lazy externals. +</li><li> Definition is searched for only in other objects, not in libraries. +This form is not presently implemented. +</li><li> No search; the symbol is an alias. This form is not presently +implemented. +</li></ul> +<p>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. +</p> +<a name="index-aligned-common-symbols"></a> +</dd> +<dt><em>aligned common symbols</em></dt> +<dd><p>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</samp>’ section, which are recognized +by <code>ld</code> 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. +</p> +</dd> +</dl> + + + +<hr> +<a name="Xtensa"></a> +<div class="header"> +<p> +Previous: <a href="#WIN32" accesskey="p" rel="previous">WIN32</a>, Up: <a href="#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="ld-and-Xtensa-Processors"></a> +<h3 class="section">5.17 <code>ld</code> and Xtensa Processors</h3> + +<a name="index-Xtensa-processors"></a> +<p>The default <code>ld</code> behavior for Xtensa processors is to interpret +<code>SECTIONS</code> commands so that lists of explicitly named sections in a +specification with a wildcard file will be interleaved when necessary to +keep literal pools within the range of PC-relative load offsets. For +example, with the command: +</p> +<div class="smallexample"> +<pre class="smallexample">SECTIONS +{ + .text : { + *(.literal .text) + } +} +</pre></div> + +<p><code>ld</code> may interleave some of the <code>.literal</code> +and <code>.text</code> sections from different object files to ensure that the +literal pools are within the range of PC-relative load offsets. A valid +interleaving might place the <code>.literal</code> sections from an initial +group of files followed by the <code>.text</code> sections of that group of +files. Then, the <code>.literal</code> sections from the rest of the files +and the <code>.text</code> sections from the rest of the files would follow. +</p> +<a name="index-_002d_002drelax-on-Xtensa"></a> +<a name="index-relaxing-on-Xtensa"></a> +<p>Relaxation is enabled by default for the Xtensa version of <code>ld</code> and +provides two important link-time optimizations. The first optimization +is to combine identical literal values to reduce code size. A redundant +literal will be removed and all the <code>L32R</code> instructions that use it +will be changed to reference an identical literal, as long as the +location of the replacement literal is within the offset range of all +the <code>L32R</code> instructions. The second optimization is to remove +unnecessary overhead from assembler-generated “longcall” sequences of +<code>L32R</code>/<code>CALLX<var>n</var></code> when the target functions are within +range of direct <code>CALL<var>n</var></code> instructions. +</p> +<p>For each of these cases where an indirect call sequence can be optimized +to a direct call, the linker will change the <code>CALLX<var>n</var></code> +instruction to a <code>CALL<var>n</var></code> instruction, remove the <code>L32R</code> +instruction, and remove the literal referenced by the <code>L32R</code> +instruction if it is not used for anything else. Removing the +<code>L32R</code> instruction always reduces code size but can potentially +hurt performance by changing the alignment of subsequent branch targets. +By default, the linker will always preserve alignments, either by +switching some instructions between 24-bit encodings and the equivalent +density instructions or by inserting a no-op in place of the <code>L32R</code> +instruction that was removed. If code size is more important than +performance, the <samp>--size-opt</samp> option can be used to prevent the +linker from widening density instructions or inserting no-ops, except in +a few cases where no-ops are required for correctness. +</p> +<p>The following Xtensa-specific command-line options can be used to +control the linker: +</p> +<a name="index-Xtensa-options"></a> +<dl compact="compact"> +<dt><samp>--size-opt</samp></dt> +<dd><p>When optimizing indirect calls to direct calls, optimize for code size +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. +</p> +</dd> +<dt><samp>--abi-windowed</samp></dt> +<dt><samp>--abi-call0</samp></dt> +<dd><p>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</code> 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. +</p></dd> +</dl> + + +<hr> +<a name="BFD"></a> +<div class="header"> +<p> +Next: <a href="#Reporting-Bugs" accesskey="n" rel="next">Reporting Bugs</a>, Previous: <a href="#Machine-Dependent" accesskey="p" rel="previous">Machine Dependent</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="BFD-1"></a> +<h2 class="chapter">6 BFD</h2> + +<a name="index-back-end"></a> +<a name="index-object-file-management"></a> +<a name="index-object-formats-available"></a> +<a name="index-objdump-_002di"></a> +<p>The linker accesses object and archive files using the BFD libraries. +These libraries allow the linker to use the same routines to operate on +object files whatever the object file format. A different object file +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</code> +(see <a href="http://sourceware.org/binutils/docs/binutils/objdump.html#objdump">objdump</a> in <cite>The GNU Binary Utilities</cite>) to +list all the formats available for your configuration. +</p> +<a name="index-BFD-requirements"></a> +<a name="index-requirements-for-BFD"></a> +<p>As with most implementations, BFD is a compromise between +several conflicting requirements. The major factor influencing +BFD design was efficiency: any time used converting between +formats is time which would not have been spent had BFD not +been involved. This is partly offset by abstraction payback; since +BFD simplifies applications and back ends, more time and care +may be spent optimizing algorithms for a greater speed. +</p> +<p>One minor artifact of the BFD solution which you should bear in +mind is the potential for information loss. There are two places where +useful information can be lost using the BFD mechanism: during +conversion and during output. See <a href="#BFD-information-loss">BFD information loss</a>. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#BFD-outline" accesskey="1">BFD outline</a>:</td><td> </td><td align="left" valign="top">How it works: an outline of BFD +</td></tr> +</table> + +<hr> +<a name="BFD-outline"></a> +<div class="header"> +<p> +Up: <a href="#BFD" accesskey="u" rel="up">BFD</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="How-It-Works_003a-An-Outline-of-BFD"></a> +<h3 class="section">6.1 How It Works: An Outline of BFD</h3> +<a name="index-opening-object-files"></a> + +<p>When an object file is opened, BFD subroutines automatically determine +the format of the input object file. They then build a descriptor in +memory with pointers to routines that will be used to access elements of +the object file’s data structures. +</p> +<p>As different information from the object files is required, +BFD reads from different sections of the file and processes them. +For example, a very common operation for the linker is processing symbol +tables. Each BFD back end provides a routine for converting +between the object file’s representation of symbols and an internal +canonical format. When the linker asks for the symbol table of an object +file, it calls through a memory pointer to the routine from the +relevant BFD back end which reads and converts the table into a canonical +form. The linker then operates upon the canonical form. When the link is +finished and the linker writes the output file’s symbol table, +another BFD back end routine is called to take the newly +created symbol table and convert it into the chosen output format. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#BFD-information-loss" accesskey="1">BFD information loss</a>:</td><td> </td><td align="left" valign="top">Information Loss +</td></tr> +<tr><td align="left" valign="top">• <a href="#Canonical-format" accesskey="2">Canonical format</a>:</td><td> </td><td align="left" valign="top">The BFD canonical object-file format +</td></tr> +</table> + +<hr> +<a name="BFD-information-loss"></a> +<div class="header"> +<p> +Next: <a href="#Canonical-format" accesskey="n" rel="next">Canonical format</a>, Up: <a href="#BFD-outline" accesskey="u" rel="up">BFD outline</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Information-Loss"></a> +<h4 class="subsection">6.1.1 Information Loss</h4> + +<p><em>Information can be lost during output.</em> The output formats +supported by BFD do not provide identical facilities, and +information which can be described in one form has nowhere to go in +another format. One example of this is alignment information in +<code>b.out</code>. There is nowhere in an <code>a.out</code> format file to store +alignment information on the contained data, so when a file is linked +from <code>b.out</code> and an <code>a.out</code> image is produced, alignment +information will not propagate to the output file. (The linker will +still use the alignment information internally, so the link is performed +correctly). +</p> +<p>Another example is COFF section names. COFF files may contain an +unlimited number of sections, each one with a textual section name. If +the target of the link is a format which does not have many sections (e.g., +<code>a.out</code>) or has sections without names (e.g., the Oasys format), the +link cannot be done simply. You can circumvent this problem by +describing the desired input-to-output section mapping with the linker command +language. +</p> +<p><em>Information can be lost during canonicalization.</em> The BFD +internal canonical form of the external formats is not exhaustive; there +are structures in input formats for which there is no direct +representation internally. This means that the BFD back ends +cannot maintain all possible data richness through the transformation +between external to internal and back to external formats. +</p> +<p>This limitation is only a problem when an application reads one +format and writes another. Each BFD back end is responsible for +maintaining as much data as possible, and the internal BFD +canonical form has structures which are opaque to the BFD core, +and exported only to the back ends. When a file is read in one format, +the canonical form is generated for BFD and the application. At the +same time, the back end saves away any information which may otherwise +be lost. If the data is then written back in the same format, the back +end routine will be able to use the canonical form provided by the +BFD core as well as the information it prepared earlier. Since +there is a great deal of commonality between back ends, +there is no information lost when +linking or copying big endian COFF to little endian COFF, or <code>a.out</code> to +<code>b.out</code>. When a mixture of formats is linked, the information is +only lost from the files whose format differs from the destination. +</p> +<hr> +<a name="Canonical-format"></a> +<div class="header"> +<p> +Previous: <a href="#BFD-information-loss" accesskey="p" rel="previous">BFD information loss</a>, Up: <a href="#BFD-outline" accesskey="u" rel="up">BFD outline</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="The-BFD-canonical-object_002dfile-format"></a> +<h4 class="subsection">6.1.2 The BFD canonical object-file format</h4> + +<p>The greatest potential for loss of information occurs when there is the least +overlap between the information provided by the source format, that +stored by the canonical format, and that needed by the +destination format. A brief description of the canonical form may help +you understand which kinds of data you can count on preserving across +conversions. +<a name="index-BFD-canonical-format"></a> +<a name="index-internal-object_002dfile-format"></a> +</p> +<dl compact="compact"> +<dt><em>files</em></dt> +<dd><p>Information stored on a per-file basis includes target machine +architecture, particular implementation format type, a demand pageable +bit, and a write protected bit. Information like Unix magic numbers is +not stored here—only the magic numbers’ meaning, so a <code>ZMAGIC</code> +file would have both the demand pageable bit and the write protected +text bit set. The byte order of the target is stored on a per-file +basis, so that big- and little-endian object files may be used with one +another. +</p> +</dd> +<dt><em>sections</em></dt> +<dd><p>Each section in the input file contains the name of the section, the +section’s original address in the object file, size and alignment +information, various flags, and pointers into other BFD data +structures. +</p> +</dd> +<dt><em>symbols</em></dt> +<dd><p>Each symbol contains a pointer to the information for the object file +which originally defined it, its name, its value, and various flag +bits. When a BFD back end reads in a symbol table, it relocates all +symbols to make them relative to the base of the section where they were +defined. Doing this ensures that each symbol points to its containing +section. Each symbol also has a varying amount of hidden private data +for the BFD back end. Since the symbol points to the original file, the +private data format for that symbol is accessible. <code>ld</code> can +operate on a collection of symbols of wildly different formats without +problems. +</p> +<p>Normal global and simple local symbols are maintained on output, so an +output file (no matter its format) will retain symbols pointing to +functions and to global, static, and common variables. Some symbol +information is not worth retaining; in <code>a.out</code>, type information is +stored in the symbol table as long symbol names. This information would +be useless to most COFF debuggers; the linker has command-line switches +to allow users to throw it away. +</p> +<p>There is one word of type information within the symbol, so if the +format supports symbol type information within symbols (for example, COFF, +Oasys) and the type is simple enough to fit within one word +(nearly everything but aggregates), the information will be preserved. +</p> +</dd> +<dt><em>relocation level</em></dt> +<dd><p>Each canonical BFD relocation record contains a pointer to the symbol to +relocate to, the offset of the data to relocate, the section the data +is in, and a pointer to a relocation type descriptor. Relocation is +performed by passing messages through the relocation type +descriptor and the symbol pointer. Therefore, relocations can be performed +on output data using a relocation method that is only available in one of the +input formats. For instance, Oasys provides a byte relocation format. +A relocation record requesting this relocation type would point +indirectly to a routine to perform this, so the relocation may be +performed on a byte being written to a 68k COFF file, even though 68k COFF +has no such relocation type. +</p> +</dd> +<dt><em>line numbers</em></dt> +<dd><p>Object formats can contain, for debugging purposes, some form of mapping +between symbols, source line numbers, and addresses in the output file. +These addresses have to be relocated along with the symbol information. +Each symbol with an associated list of line number records points to the +first record of the list. The head of a line number list consists of a +pointer to the symbol, which allows finding out the address of the +function whose line number is being described. The rest of the list is +made up of pairs: offsets into the section and line numbers. Any format +which can simply derive this information can pass it successfully +between formats. +</p></dd> +</dl> + +<hr> +<a name="Reporting-Bugs"></a> +<div class="header"> +<p> +Next: <a href="#MRI" accesskey="n" rel="next">MRI</a>, Previous: <a href="#BFD" accesskey="p" rel="previous">BFD</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Reporting-Bugs-1"></a> +<h2 class="chapter">7 Reporting Bugs</h2> +<a name="index-bugs-in-ld"></a> +<a name="index-reporting-bugs-in-ld"></a> + +<p>Your bug reports play an essential role in making <code>ld</code> reliable. +</p> +<p>Reporting a bug may help you by bringing a solution to your problem, or +it may not. But in any case the principal function of a bug report is +to help the entire community by making the next version of <code>ld</code> +work better. Bug reports are your contribution to the maintenance of +<code>ld</code>. +</p> +<p>In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Bug-Criteria" accesskey="1">Bug Criteria</a>:</td><td> </td><td align="left" valign="top">Have you found a bug? +</td></tr> +<tr><td align="left" valign="top">• <a href="#Bug-Reporting" accesskey="2">Bug Reporting</a>:</td><td> </td><td align="left" valign="top">How to report bugs +</td></tr> +</table> + +<hr> +<a name="Bug-Criteria"></a> +<div class="header"> +<p> +Next: <a href="#Bug-Reporting" accesskey="n" rel="next">Bug Reporting</a>, Up: <a href="#Reporting-Bugs" accesskey="u" rel="up">Reporting Bugs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="Have-You-Found-a-Bug_003f"></a> +<h3 class="section">7.1 Have You Found a Bug?</h3> +<a name="index-bug-criteria"></a> + +<p>If you are not sure whether you have found a bug, here are some guidelines: +</p> +<ul> +<li> <a name="index-fatal-signal"></a> +<a name="index-linker-crash"></a> +<a name="index-crash-of-linker"></a> +If the linker gets a fatal signal, for any input whatever, that is a +<code>ld</code> bug. Reliable linkers never crash. + +</li><li> <a name="index-error-on-valid-input"></a> +If <code>ld</code> produces an error message for valid input, that is a bug. + +</li><li> <a name="index-invalid-input"></a> +If <code>ld</code> does not produce an error message for invalid input, that +may be a bug. In the general case, the linker can not verify that +object files are correct. + +</li><li> If you are an experienced user of linkers, your suggestions for +improvement of <code>ld</code> are welcome in any case. +</li></ul> + +<hr> +<a name="Bug-Reporting"></a> +<div class="header"> +<p> +Previous: <a href="#Bug-Criteria" accesskey="p" rel="previous">Bug Criteria</a>, Up: <a href="#Reporting-Bugs" accesskey="u" rel="up">Reporting Bugs</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="How-to-Report-Bugs"></a> +<h3 class="section">7.2 How to Report Bugs</h3> +<a name="index-bug-reports"></a> +<a name="index-ld-bugs_002c-reporting"></a> + +<p>A number of companies and individuals offer support for <small>GNU</small> +products. If you obtained <code>ld</code> from a support organization, we +recommend you contact that organization first. +</p> +<p>You can find contact information for many support companies and +individuals in the file <samp>etc/SERVICE</samp> in the <small>GNU</small> Emacs +distribution. +</p> +<p>Otherwise, send bug reports for <code>ld</code> to +<a href="https://bugs.linaro.org/">https://bugs.linaro.org/</a>. +</p> +<p>The fundamental principle of reporting bugs usefully is this: +<strong>report all the facts</strong>. If you are not sure whether to state a +fact or leave it out, state it! +</p> +<p>Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of a symbol you use in an example does not +matter. Well, probably it does not, but one cannot be sure. Perhaps +the bug is a stray memory reference which happens to fetch from the +location where that name is stored in memory; perhaps, if the name +were different, the contents of that location would fool the linker +into doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. +</p> +<p>Keep in mind that the purpose of a bug report is to enable us to fix +the bug if it is new to us. Therefore, always write your bug reports +on the assumption that the bug has not been reported previously. +</p> +<p>Sometimes people give a few sketchy facts and ask, “Does this ring a +bell?” This cannot help us fix a bug, so it is basically useless. We +respond by asking for enough details to enable us to investigate. +You might as well expedite matters by sending them to begin with. +</p> +<p>To enable us to fix the bug, you should include all these things: +</p> +<ul> +<li> The version of <code>ld</code>. <code>ld</code> announces it if you start it with +the ‘<samp>--version</samp>’ argument. + +<p>Without this, we will not know whether there is any point in looking for +the bug in the current version of <code>ld</code>. +</p> +</li><li> Any patches you may have applied to the <code>ld</code> source, including any +patches made to the <code>BFD</code> library. + +</li><li> The type of machine you are using, and the operating system name and +version number. + +</li><li> What compiler (and its version) was used to compile <code>ld</code>—e.g. +“<code>gcc-2.7</code>”. + +</li><li> The command arguments you gave the linker to link your example and +observe the bug. To guarantee you will not omit something important, +list them all. A copy of the Makefile (or the output from make) is +sufficient. + +<p>If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. +</p> +</li><li> A complete input file, or set of input files, that will reproduce the +bug. It is generally most helpful to send the actual object files +provided that they are reasonably small. Say no more than 10K. For +bigger files you can either make them available by FTP or HTTP or else +state that you are willing to send the object file(s) to whomever +requests them. (Note - your email will be going to a mailing list, so +we do not want to clog it up with large attachments). But small +attachments are best. + +<p>If the source files were assembled using <code>gas</code> or compiled using +<code>gcc</code>, then it may be OK to send the source files rather than the +object files. In this case, be sure to say exactly what version of +<code>gas</code> or <code>gcc</code> was used to produce the object files. Also say +how <code>gas</code> or <code>gcc</code> were configured. +</p> +</li><li> A description of what behavior you observe that you believe is +incorrect. For example, “It gets a fatal signal.” + +<p>Of course, if the bug is that <code>ld</code> gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might +not notice unless it is glaringly wrong. You might as well not give us +a chance to make a mistake. +</p> +<p>Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of <code>ld</code> is out of sync, or you have encountered a bug in the +C library on your system. (This has happened!) Your copy might crash +and ours would not. If you told us to expect a crash, then when ours +fails to crash, we would know that the bug was not happening for us. If +you had not told us to expect a crash, then we would not be able to draw +any conclusion from our observations. +</p> +</li><li> If you wish to suggest changes to the <code>ld</code> source, send us context +diffs, as generated by <code>diff</code> with the ‘<samp>-u</samp>’, ‘<samp>-c</samp>’, or +‘<samp>-p</samp>’ option. Always send diffs from the old file to the new file. +If you even discuss something in the <code>ld</code> source, refer to it by +context, not by line number. + +<p>The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. +</p></li></ul> + +<p>Here are some things that are not necessary: +</p> +<ul> +<li> A description of the envelope of the bug. + +<p>Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. +</p> +<p>This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. +</p> +<p>Of course, if you can find a simpler example to report <em>instead</em> +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. +</p> +<p>However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. +</p> +</li><li> A patch for the bug. + +<p>A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. +</p> +<p>Sometimes with a program as complicated as <code>ld</code> it is very hard to +construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be +able to construct one, so we will not be able to verify that the bug is +fixed. +</p> +<p>And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. +</p> +</li><li> A guess about what the bug is or what it depends on. + +<p>Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +</p></li></ul> + +<hr> +<a name="MRI"></a> +<div class="header"> +<p> +Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Reporting-Bugs" accesskey="p" rel="previous">Reporting Bugs</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="MRI-Compatible-Script-Files"></a> +<h2 class="appendix">Appendix A MRI Compatible Script Files</h2> +<a name="index-MRI-compatibility"></a> +<p>To aid users making the transition to <small>GNU</small> <code>ld</code> from the MRI +linker, <code>ld</code> can use MRI compatible linker scripts as an +alternative to the more general-purpose linker scripting language +described in <a href="#Scripts">Scripts</a>. MRI compatible linker scripts have a much +simpler command set than the scripting language otherwise used with +<code>ld</code>. <small>GNU</small> <code>ld</code> supports the most commonly used MRI +linker commands; these commands are described here. +</p> +<p>In general, MRI scripts aren’t of much use with the <code>a.out</code> object +file format, since it only has three sections and MRI scripts lack some +features to make use of them. +</p> +<p>You can specify a file containing an MRI-compatible script using the +‘<samp>-c</samp>’ command-line option. +</p> +<p>Each command in an MRI-compatible script occupies its own line; each +command line starts with the keyword that identifies the command (though +blank lines are also allowed for punctuation). If a line of an +MRI-compatible script begins with an unrecognized keyword, <code>ld</code> +issues a warning message, but continues processing the script. +</p> +<p>Lines beginning with ‘<samp>*</samp>’ are comments. +</p> +<p>You can write these commands using all upper-case letters, or all +lower case; for example, ‘<samp>chip</samp>’ is the same as ‘<samp>CHIP</samp>’. +The following list shows only the upper-case form of each command. +</p> +<dl compact="compact"> +<dd><a name="index-ABSOLUTE-_0028MRI_0029"></a> +</dd> +<dt><code>ABSOLUTE <var>secname</var></code></dt> +<dt><code>ABSOLUTE <var>secname</var>, <var>secname</var>, … <var>secname</var></code></dt> +<dd><p>Normally, <code>ld</code> includes in the output file all sections from all +the input files. However, in an MRI-compatible script, you can use the +<code>ABSOLUTE</code> command to restrict the sections that will be present in +your output program. If the <code>ABSOLUTE</code> command is used at all in a +script, then only the sections named explicitly in <code>ABSOLUTE</code> +commands will appear in the linker output. You can still use other +input sections (whatever you select on the command line, or using +<code>LOAD</code>) to resolve addresses in the output file. +</p> +<a name="index-ALIAS-_0028MRI_0029"></a> +</dd> +<dt><code>ALIAS <var>out-secname</var>, <var>in-secname</var></code></dt> +<dd><p>Use this command to place the data from input section <var>in-secname</var> +in a section called <var>out-secname</var> in the linker output file. +</p> +<p><var>in-secname</var> may be an integer. +</p> +<a name="index-ALIGN-_0028MRI_0029"></a> +</dd> +<dt><code>ALIGN <var>secname</var> = <var>expression</var></code></dt> +<dd><p>Align the section called <var>secname</var> to <var>expression</var>. The +<var>expression</var> should be a power of two. +</p> +<a name="index-BASE-_0028MRI_0029"></a> +</dd> +<dt><code>BASE <var>expression</var></code></dt> +<dd><p>Use the value of <var>expression</var> as the lowest address (other than +absolute addresses) in the output file. +</p> +<a name="index-CHIP-_0028MRI_0029"></a> +</dd> +<dt><code>CHIP <var>expression</var></code></dt> +<dt><code>CHIP <var>expression</var>, <var>expression</var></code></dt> +<dd><p>This command does nothing; it is accepted only for compatibility. +</p> +<a name="index-END-_0028MRI_0029"></a> +</dd> +<dt><code>END</code></dt> +<dd><p>This command does nothing whatever; it’s only accepted for compatibility. +</p> +<a name="index-FORMAT-_0028MRI_0029"></a> +</dd> +<dt><code>FORMAT <var>output-format</var></code></dt> +<dd><p>Similar to the <code>OUTPUT_FORMAT</code> command in the more general linker +language, but restricted to S-records, if <var>output-format</var> is ‘<samp>S</samp>’ +</p> +<a name="index-LIST-_0028MRI_0029"></a> +</dd> +<dt><code>LIST <var>anything</var>…</code></dt> +<dd><p>Print (to the standard output file) a link map, as produced by the +<code>ld</code> command-line option ‘<samp>-M</samp>’. +</p> +<p>The keyword <code>LIST</code> may be followed by anything on the +same line, with no change in its effect. +</p> +<a name="index-LOAD-_0028MRI_0029"></a> +</dd> +<dt><code>LOAD <var>filename</var></code></dt> +<dt><code>LOAD <var>filename</var>, <var>filename</var>, … <var>filename</var></code></dt> +<dd><p>Include one or more object file <var>filename</var> in the link; this has the +same effect as specifying <var>filename</var> directly on the <code>ld</code> +command line. +</p> +<a name="index-NAME-_0028MRI_0029"></a> +</dd> +<dt><code>NAME <var>output-name</var></code></dt> +<dd><p><var>output-name</var> is the name for the program produced by <code>ld</code>; the +MRI-compatible command <code>NAME</code> is equivalent to the command-line +option ‘<samp>-o</samp>’ or the general script language command <code>OUTPUT</code>. +</p> +<a name="index-ORDER-_0028MRI_0029"></a> +</dd> +<dt><code>ORDER <var>secname</var>, <var>secname</var>, … <var>secname</var></code></dt> +<dt><code>ORDER <var>secname</var> <var>secname</var> <var>secname</var></code></dt> +<dd><p>Normally, <code>ld</code> orders the sections in its output file in the +order in which they first appear in the input files. In an MRI-compatible +script, you can override this ordering with the <code>ORDER</code> command. The +sections you list with <code>ORDER</code> will appear first in your output +file, in the order specified. +</p> +<a name="index-PUBLIC-_0028MRI_0029"></a> +</dd> +<dt><code>PUBLIC <var>name</var>=<var>expression</var></code></dt> +<dt><code>PUBLIC <var>name</var>,<var>expression</var></code></dt> +<dt><code>PUBLIC <var>name</var> <var>expression</var></code></dt> +<dd><p>Supply a value (<var>expression</var>) for external symbol +<var>name</var> used in the linker input files. +</p> +<a name="index-SECT-_0028MRI_0029"></a> +</dd> +<dt><code>SECT <var>secname</var>, <var>expression</var></code></dt> +<dt><code>SECT <var>secname</var>=<var>expression</var></code></dt> +<dt><code>SECT <var>secname</var> <var>expression</var></code></dt> +<dd><p>You can use any of these three forms of the <code>SECT</code> command to +specify the start address (<var>expression</var>) for section <var>secname</var>. +If you have more than one <code>SECT</code> statement for the same +<var>secname</var>, only the <em>first</em> sets the start address. +</p></dd> +</dl> + +<hr> +<a name="GNU-Free-Documentation-License"></a> +<div class="header"> +<p> +Next: <a href="#LD-Index" accesskey="n" rel="next">LD Index</a>, Previous: <a href="#MRI" accesskey="p" rel="previous">MRI</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="GNU-Free-Documentation-License-1"></a> +<h2 class="appendix">Appendix B GNU Free Documentation License</h2> +<div align="center">Version 1.3, 3 November 2008 +</div> + +<div class="display"> +<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<a href="http://fsf.org/">http://fsf.org/</a> + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</pre></div> + +<ol> +<li> PREAMBLE + +<p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <em>free</em> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +</p> +<p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. +</p> +<p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +</p> +</li><li> APPLICABILITY AND DEFINITIONS + +<p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +</p> +<p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +</p> +<p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +</p> +<p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +</p> +<p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +</p> +<p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. +</p> +<p>Examples of suitable formats for Transparent copies include plain +<small>ASCII</small> without markup, Texinfo input format, LaTeX input +format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available +<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> designed for human modification. Examples +of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and +<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, <acronym>SGML</acronym> or +<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are +not generally available, and the machine-generated <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> produced by some word processors for +output purposes only. +</p> +<p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work’s title, +preceding the beginning of the body of the text. +</p> +<p>The “publisher” means any person or entity that distributes copies +of the Document to the public. +</p> +<p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. +</p> +<p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +</p> +</li><li> VERBATIM COPYING + +<p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +</p> +<p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +</p> +</li><li> COPYING IN QUANTITY + +<p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +</p> +<p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +</p> +<p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +</p> +<p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +</p> +</li><li> MODIFICATIONS + +<p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +</p> +<ol> +<li> Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +</li><li> List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +</li><li> State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +</li><li> Preserve all the copyright notices of the Document. + +</li><li> Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +</li><li> Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +</li><li> Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +</li><li> Include an unaltered copy of this License. + +</li><li> Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +</li><li> Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +</li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +</li><li> Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +</li><li> Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +</li><li> Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +</li><li> Preserve any Warranty Disclaimers. +</li></ol> + +<p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +</p> +<p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +</p> +<p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +</p> +<p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +</p> +</li><li> COMBINING DOCUMENTS + +<p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +</p> +<p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +</p> +<p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” +</p> +</li><li> COLLECTIONS OF DOCUMENTS + +<p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +</p> +<p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +</p> +</li><li> AGGREGATION WITH INDEPENDENT WORKS + +<p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation’s users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +</p> +<p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document’s Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +</p> +</li><li> TRANSLATION + +<p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +</p> +<p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +</p> +</li><li> TERMINATION + +<p>You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +</p> +<p>However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +</p> +<p>Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +</p> +<p>Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +</p> +</li><li> FUTURE REVISIONS OF THIS LICENSE + +<p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. +</p> +<p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy’s public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +</p> +</li><li> RELICENSING + +<p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. +</p> +<p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +</p> +<p>“Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +</p> +<p>An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +</p> +<p>The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. +</p> +</li></ol> + +<a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a> +<h3 class="heading">ADDENDUM: How to use this License for your documents</h3> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +</p> +<div class="smallexample"> +<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre></div> + +<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: +</p> +<div class="smallexample"> +<pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre></div> + +<p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +</p> +<p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +</p> + +<hr> +<a name="LD-Index"></a> +<div class="header"> +<p> +Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="previous">GNU Free Documentation License</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#LD-Index" title="Index" rel="index">Index</a>]</p> +</div> +<a name="LD-Index-1"></a> +<h2 class="unnumbered">LD Index</h2> + +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#LD-Index_cp_symbol-1"><b>"</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-2"><b>-</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-3"><b>.</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-4"><b>/</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-5"><b>3</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-6"><b>:</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-7"><b>=</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-8"><b>></b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-9"><b>[</b></a> + +<br> +<a class="summary-letter" href="#LD-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-Q"><b>Q</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-V"><b>V</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-W"><b>W</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-X"><b>X</b></a> + +</td></tr></table> +<table class="index-cp" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-1">"</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0022"><code>"</code></a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-2">-</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_0028"><code>-(</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002daccept_002dunknown_002dinput_002darch"><code>--accept-unknown-input-arch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dadd_002dneeded"><code>--add-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dadd_002dstdcall_002dalias"><code>--add-stdcall-alias</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dallow_002dmultiple_002ddefinition"><code>--allow-multiple-definition</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dallow_002dshlib_002dundefined"><code>--allow-shlib-undefined</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002das_002dneeded"><code>--as-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002daudit-AUDITLIB"><code>--audit <var>AUDITLIB</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dauxiliary_003dname"><code>--auxiliary=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbank_002dwindow"><code>--bank-window</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbase_002dfile"><code>--base-file</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbe8"><code>--be8</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbranch_002dstub-on-C_002dSKY"><code>--branch-stub on C-SKY</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbss_002dplt"><code>--bss-plt</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbuild_002did"><code>--build-id</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dbuild_002did_003dstyle"><code>--build-id=<var>style</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcheck_002dsections"><code>--check-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcmse_002dimplib"><code>--cmse-implib</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcode_002dregion"><code>--code-region</code></a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcompact_002dbranches"><code>--compact-branches</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dnone"><code>--compress-debug-sections=none</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzlib"><code>--compress-debug-sections=zlib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgabi"><code>--compress-debug-sections=zlib-gabi</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgnu"><code>--compress-debug-sections=zlib-gnu</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcompress_002ddebug_002dsections_003dzstd"><code>--compress-debug-sections=zstd</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcopy_002ddt_002dneeded_002dentries"><code>--copy-dt-needed-entries</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dcref"><code>--cref</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dctf_002dshare_002dtypes"><code>--ctf-share-types</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dctf_002dvariables"><code>--ctf-variables</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddata_002dregion"><code>--data-region</code></a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddefault_002dimported_002dsymver"><code>--default-imported-symver</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddefault_002dscript_003dscript"><code>--default-script=<var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddefault_002dsymver"><code>--default-symver</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddefsym_003dsymbol_003dexp"><code>--defsym=<var>symbol</var>=<var>exp</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddemangle_005b_003dstyle_005d"><code>--demangle[=<var>style</var>]</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddepaudit-AUDITLIB"><code>--depaudit <var>AUDITLIB</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddependency_002dfile_003ddepfile"><code>--dependency-file=<var>depfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dauto_002dimage_002dbase"><code>--disable-auto-image-base</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dauto_002dimport"><code>--disable-auto-import</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dlarge_002daddress_002daware"><code>--disable-large-address-aware</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dlinker_002dversion"><code>--disable-linker-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dlong_002dsection_002dnames"><code>--disable-long-section-names</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dmultiple_002dabs_002ddefs"><code>--disable-multiple-abs-defs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dnew_002ddtags"><code>--disable-new-dtags</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002druntime_002dpseudo_002dreloc"><code>--disable-runtime-pseudo-reloc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dsec_002dtransformation"><code>--disable-sec-transformation</code></a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddisable_002dstdcall_002dfixup"><code>--disable-stdcall-fixup</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddiscard_002dall"><code>--discard-all</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddiscard_002dlocals"><code>--discard-locals</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddll"><code>--dll</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddll_002dsearch_002dprefix"><code>--dll-search-prefix</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddotsyms"><code>--dotsyms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddsbt_002dindex"><code>--dsbt-index</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddsbt_002dsize"><code>--dsbt-size</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlinker_003dfile"><code>--dynamic-linker=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_002dcpp_002dnew"><code>--dynamic-list-cpp-new</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_002dcpp_002dtypeinfo"><code>--dynamic-list-cpp-typeinfo</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_002ddata"><code>--dynamic-list-data</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddynamic_002dlist_003ddynamic_002dlist_002dfile"><code>--dynamic-list=<var>dynamic-list-file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ddynamicbase"><code>--dynamicbase</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002deh_002dframe_002dhdr"><code>--eh-frame-hdr</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dembedded_002drelocs"><code>--embedded-relocs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002demit_002drelocs"><code>--emit-relocs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstack_002dsyms"><code>--emit-stack-syms</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstub_002dsyms"><code>--emit-stub-syms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstub_002dsyms-1"><code>--emit-stub-syms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002demit_002dstub_002dsyms-2"><code>--emit-stub-syms</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dauto_002dimage_002dbase"><code>--enable-auto-image-base</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dauto_002dimport"><code>--enable-auto-import</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dextra_002dpe_002ddebug"><code>--enable-extra-pe-debug</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dlinker_002dversion"><code>--enable-linker-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dlong_002dsection_002dnames"><code>--enable-long-section-names</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dnew_002ddtags"><code>--enable-new-dtags</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dnon_002dcontiguous_002dregions"><code>--enable-non-contiguous-regions</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dnon_002dcontiguous_002dregions_002dwarnings"><code>--enable-non-contiguous-regions-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dreloc_002dsection"><code>--enable-reloc-section</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002druntime_002dpseudo_002dreloc"><code>--enable-runtime-pseudo-reloc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002denable_002dstdcall_002dfixup"><code>--enable-stdcall-fixup</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dentry_003dentry"><code>--entry=<var>entry</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002derror_002dhandling_002dscript_003dscriptname"><code>--error-handling-script=<var>scriptname</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002derror_002dunresolved_002dsymbols"><code>--error-unresolved-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dall_002dsymbols"><code>--exclude-all-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dlibs"><code>--exclude-libs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dmodules_002dfor_002dimplib"><code>--exclude-modules-for-implib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexclude_002dsymbols"><code>--exclude-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002dall_002dsymbols"><code>--export-all-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002ddynamic"><code>--export-dynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002ddynamic_002dsymbol_002dlist_003dfile"><code>--export-dynamic-symbol-list=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dexport_002ddynamic_002dsymbol_003dglob"><code>--export-dynamic-symbol=<var>glob</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dextra_002doverlay_002dstubs"><code>--extra-overlay-stubs</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfatal_002dwarnings"><code>--fatal-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfile_002dalignment"><code>--file-alignment</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfilter_003dname"><code>--filter=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002darm1176"><code>--fix-arm1176</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dcortex_002da53_002d835769"><code>--fix-cortex-a53-835769</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dcortex_002da8"><code>--fix-cortex-a8</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dstm32l4xx_002d629360"><code>--fix-stm32l4xx-629360</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dv4bx"><code>--fix-v4bx</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dfix_002dv4bx_002dinterworking"><code>--fix-v4bx-interworking</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dforce_002ddynamic"><code>--force-dynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dforce_002dexe_002dsuffix"><code>--force-exe-suffix</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dforce_002dgroup_002dallocation"><code>--force-group-allocation</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dforceinteg"><code>--forceinteg</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dformat_003dformat"><code>--format=<var>format</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dformat_003dversion"><code>--format=<var>version</var></code></a>:</td><td> </td><td valign="top"><a href="#TI-COFF">TI COFF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dgc_002dkeep_002dexported"><code>--gc-keep-exported</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dgc_002dsections"><code>--gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dgot"><code>--got</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dgot_003dtype"><code>--got=<var>type</var></code></a>:</td><td> </td><td valign="top"><a href="#M68K">M68K</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dgpsize_003dvalue"><code>--gpsize=<var>value</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dhash_002dsize_003dnumber"><code>--hash-size=<var>number</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dhash_002dstyle_003dstyle"><code>--hash-style=<var>style</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dheap"><code>--heap</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dhelp"><code>--help</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dhigh_002dentropy_002dva"><code>--high-entropy-va</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dignore_002dbranch_002disa"><code>--ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dignore_002dbranch_002disa-1"><code>--ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dimage_002dbase"><code>--image-base</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dimagic"><code>--imagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002din_002dimplib_003dfile"><code>--in-implib=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dinsert_002dtimestamp"><code>--insert-timestamp</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dinsn32"><code>--insn32</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dinsn32-1"><code>--insn32</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002djust_002dsymbols_003dfile"><code>--just-symbols=<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dkill_002dat"><code>--kill-at</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dlarge_002daddress_002daware"><code>--large-address-aware</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dld_002dgenerated_002dunwind_002dinfo"><code>--ld-generated-unwind-info</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dleading_002dunderscore"><code>--leading-underscore</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dlibrary_002dpath_003ddir"><code>--library-path=<var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dlibrary_003dnamespec"><code>--library=<var>namespec</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dlocal_002dstore_003dlo_003ahi"><code>--local-store=lo:hi</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dlong_002dplt"><code>--long-plt</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmajor_002dimage_002dversion"><code>--major-image-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmajor_002dos_002dversion"><code>--major-os-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmajor_002dsubsystem_002dversion"><code>--major-subsystem-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmax_002dcache_002dsize_003dsize"><code>--max-cache-size=<var>size</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmerge_002dexidx_002dentries"><code>--merge-exidx-entries</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dminor_002dimage_002dversion"><code>--minor-image-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dminor_002dos_002dversion"><code>--minor-os-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dminor_002dsubsystem_002dversion"><code>--minor-subsystem-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmri_002dscript_003dMRI_002dcmdfile"><code>--mri-script=<var>MRI-cmdfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dmulti_002dsubspace"><code>--multi-subspace</code></a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dnmagic"><code>--nmagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dnmagic-1"><code>--nmagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002daccept_002dunknown_002dinput_002darch"><code>--no-accept-unknown-input-arch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dadd_002dneeded"><code>--no-add-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dallow_002dshlib_002dundefined"><code>--no-allow-shlib-undefined</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dapply_002ddynamic_002drelocs"><code>--no-apply-dynamic-relocs</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002das_002dneeded"><code>--no-as-needed</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dbind"><code>--no-bind</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dcheck_002dsections"><code>--no-check-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dcompact_002dbranches"><code>--no-compact-branches</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dcopy_002ddt_002dneeded_002dentries"><code>--no-copy-dt-needed-entries</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dctf_002dvariables"><code>--no-ctf-variables</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddefine_002dcommon"><code>--no-define-common</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddemangle"><code>--no-demangle</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddotsyms"><code>--no-dotsyms</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002ddynamic_002dlinker"><code>--no-dynamic-linker</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002deh_002dframe_002dhdr"><code>--no-eh-frame-hdr</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002denum_002dsize_002dwarning"><code>--no-enum-size-warning</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dexport_002ddynamic"><code>--no-export-dynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfatal_002dwarnings"><code>--no-fatal-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfix_002darm1176"><code>--no-fix-arm1176</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfix_002dcortex_002da53_002d835769"><code>--no-fix-cortex-a53-835769</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dfix_002dcortex_002da8"><code>--no-fix-cortex-a8</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dgc_002dsections"><code>--no-gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dignore_002dbranch_002disa"><code>--no-ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dignore_002dbranch_002disa-1"><code>--no-ignore-branch-isa</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dinline_002doptimize"><code>--no-inline-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dinsn32"><code>--no-insn32</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dinsn32-1"><code>--no-insn32</code></a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002disolation"><code>--no-isolation</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dkeep_002dmemory"><code>--no-keep-memory</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dleading_002dunderscore"><code>--no-leading-underscore</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dmerge_002dexidx_002dentries"><code>--no-merge-exidx-entries</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dmerge_002dexidx_002dentries-1"><code>--no-merge-exidx-entries</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dmulti_002dtoc"><code>--no-multi-toc</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002domagic"><code>--no-omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002domagic-1"><code>--no-omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dopd_002doptimize"><code>--no-opd-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002doverlays"><code>--no-overlays</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dalign"><code>--no-plt-align</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dlocalentry"><code>--no-plt-localentry</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dstatic_002dchain"><code>--no-plt-static-chain</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dplt_002dthread_002dsafe"><code>--no-plt-thread-safe</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dpower10_002dstubs"><code>--no-power10-stubs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dprint_002dgc_002dsections"><code>--no-print-gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dprint_002dmap_002ddiscarded"><code>--no-print-map-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dprint_002dmap_002dlocals"><code>--no-print-map-locals</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dsave_002drestore_002dfuncs"><code>--no-save-restore-funcs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dseh"><code>--no-seh</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dstrip_002ddiscarded"><code>--no-strip-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002dget_002daddr_002doptimize"><code>--no-tls-get-addr-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002dget_002daddr_002dregsave"><code>--no-tls-get-addr-regsave</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002doptimize"><code>--no-tls-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtls_002doptimize-1"><code>--no-tls-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtoc_002doptimize"><code>--no-toc-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtoc_002dsort"><code>--no-toc-sort</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dtrampoline"><code>--no-trampoline</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dundefined"><code>--no-undefined</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dundefined_002dversion"><code>--no-undefined-version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwarn_002dmismatch"><code>--no-warn-mismatch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwarn_002dsearch_002dmismatch"><code>--no-warn-search-mismatch</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwarnings"><code>--no-warnings</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwchar_002dsize_002dwarning"><code>--no-wchar-size-warning</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002dwhole_002darchive"><code>--no-whole-archive</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dnoinhibit_002dexec"><code>--noinhibit-exec</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dnon_002doverlapping_002dopd"><code>--non-overlapping-opd</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dnxcompat"><code>--nxcompat</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002doformat_003doutput_002dformat"><code>--oformat=<var>output-format</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002domagic"><code>--omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002domagic-1"><code>--omagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dorphan_002dhandling_003dMODE"><code>--orphan-handling=<var>MODE</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dout_002dimplib"><code>--out-implib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002doutput_002ddef"><code>--output-def</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002doutput_003doutput"><code>--output=<var>output</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dpackage_002dmetadata_003dJSON"><code>--package-metadata=<var>JSON</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dpic_002dexecutable"><code>--pic-executable</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dpic_002dveneer"><code>--pic-veneer</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dalign"><code>--plt-align</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dlocalentry"><code>--plt-localentry</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dstatic_002dchain"><code>--plt-static-chain</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dplt_002dthread_002dsafe"><code>--plt-thread-safe</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dplugin"><code>--plugin</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dpop_002dstate"><code>--pop-state</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dpower10_002dstubs"><code>--power10-stubs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dgc_002dsections"><code>--print-gc-sections</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmap"><code>--print-map</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmap_002ddiscarded"><code>--print-map-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmap_002dlocals"><code>--print-map-locals</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002dmemory_002dusage"><code>--print-memory-usage</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dprint_002doutput_002dformat"><code>--print-output-format</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dpush_002dstate"><code>--push-state</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dreduce_002dmemory_002doverheads"><code>--reduce-memory-overheads</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002drelax"><code>--relax</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002drelax-on-Nios-II"><code>--relax on Nios II</code></a>:</td><td> </td><td valign="top"><a href="#Nios-II">Nios II</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002drelax-on-PowerPC"><code>--relax on PowerPC</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002drelax-on-Xtensa"><samp>--relax</samp> on Xtensa</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002drelocatable"><code>--relocatable</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dremap_002dinputs_002dfile_003dfile"><code>--remap-inputs-file=<samp>file</samp></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dremap_002dinputs_003dpattern_003dfilename"><code>--remap-inputs=<samp>pattern</samp>=<samp>filename</samp></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002drequire_002ddefined_003dsymbol"><code>--require-defined=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dretain_002dsymbols_002dfile_003dfilename"><code>--retain-symbols-file=<var>filename</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002ds390_002dpgste"><code>--s390-pgste</code></a>:</td><td> </td><td valign="top"><a href="#S_002f390-ELF">S/390 ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsave_002drestore_002dfuncs"><code>--save-restore-funcs</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dscript_003dscript"><code>--script=<var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsdata_002dgot"><code>--sdata-got</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsection_002dalignment"><code>--section-alignment</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsection_002dstart_003dsectionname_003dorg"><code>--section-start=<var>sectionname</var>=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsecure_002dplt"><code>--secure-plt</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsort_002dcommon"><code>--sort-common</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsort_002dsection_003dalignment"><code>--sort-section=alignment</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsort_002dsection_003dname"><code>--sort-section=name</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dspare_002ddynamic_002dtags"><code>--spare-dynamic-tags</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsplit_002dby_002dfile"><code>--split-by-file</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsplit_002dby_002dreloc"><code>--split-by-reloc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstack"><code>--stack</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstack_002danalysis"><code>--stack-analysis</code></a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstats"><code>--stats</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstrip_002dall"><code>--strip-all</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstrip_002ddebug"><code>--strip-debug</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstrip_002ddiscarded"><code>--strip-discarded</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize"><code>--stub-group-size</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize-on-C_002dSKY"><code>--stub-group-size on C-SKY</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize_003dN"><code>--stub-group-size=<var>N</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dstub_002dgroup_002dsize_003dN-1"><code>--stub-group-size=<var>N</var></code></a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsubsystem"><code>--subsystem</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsupport_002dold_002dcode"><code>--support-old-code</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dsysroot_003ddirectory"><code>--sysroot=<var>directory</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtarget_002dhelp"><code>--target-help</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtarget1_002dabs"><code>--target1-abs</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtarget1_002drel"><code>--target1-rel</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtarget2_003dtype"><code>--target2=<var>type</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtask_002dlink"><code>--task-link</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dthumb_002dentry_003dentry"><code>--thumb-entry=<var>entry</var></code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtls_002dget_002daddr_002doptimize"><code>--tls-get-addr-optimize</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtls_002dget_002daddr_002dregsave"><code>--tls-get-addr-regsave</code></a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtrace"><code>--trace</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtrace_002dsymbol_003dsymbol"><code>--trace-symbol=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtraditional_002dformat"><code>--traditional-format</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dtsaware"><code>--tsaware</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dundefined_003dsymbol"><code>--undefined=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dunique_005b_003dSECTION_005d"><code>--unique[=<var>SECTION</var>]</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dunresolved_002dsymbols"><code>--unresolved-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002duse_002dblx"><code>--use-blx</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002duse_002dnul_002dprefixed_002dimport_002dtables"><code>--use-nul-prefixed-import-tables</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dverbose_005b_003dNUMBER_005d"><code>--verbose[=<var>NUMBER</var>]</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dversion"><code>--version</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dversion_002dscript_003dversion_002dscriptfile"><code>--version-script=<var>version-scriptfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dvfp11_002ddenorm_002dfix"><code>--vfp11-denorm-fix</code></a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dalternate_002dem"><code>--warn-alternate-em</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dcommon"><code>--warn-common</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dconstructors"><code>--warn-constructors</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dexecstack"><code>--warn-execstack</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dmultiple_002dgp"><code>--warn-multiple-gp</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002donce"><code>--warn-once</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002drwx_002dsegments"><code>--warn-rwx-segments</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dsection_002dalign"><code>--warn-section-align</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dtextrel"><code>--warn-textrel</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwarn_002dunresolved_002dsymbols"><code>--warn-unresolved-symbols</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwdmdriver"><code>--wdmdriver</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwhole_002darchive"><code>--whole-archive</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dwrap_003dsymbol"><code>--wrap=<var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002da-keyword"><code>-a <var>keyword</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dassert-keyword"><code>-assert <var>keyword</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002db-format"><code>-b <var>format</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBdynamic"><code>-Bdynamic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBgroup"><code>-Bgroup</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBno_002dsymbolic"><code>-Bno-symbolic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBshareable"><code>-Bshareable</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBstatic"><code>-Bstatic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBsymbolic"><code>-Bsymbolic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dBsymbolic_002dfunctions"><code>-Bsymbolic-functions</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dc-MRI_002dcmdfile"><code>-c <var>MRI-cmdfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dcall_005fshared"><code>-call_shared</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dd"><code>-d</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002ddc"><code>-dc</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002ddn"><code>-dn</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002ddp"><code>-dp</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002ddT-script"><code>-dT <var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002ddy"><code>-dy</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dE"><code>-E</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002de-entry"><code>-e <var>entry</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dEB"><code>-EB</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dEL"><code>-EL</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002df-name"><code>-f <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dF-name"><code>-F <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dfini_003dname"><code>-fini=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dg"><code>-g</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dG-value"><code>-G <var>value</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dh-name"><code>-h <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002di"><code>-i</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dIfile"><code>-I<var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dinit_003dname"><code>-init=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dL-dir"><code>-L <var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dl-namespec"><code>-l <var>namespec</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dM"><code>-M</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dm-emulation"><code>-m <var>emulation</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dMap_003dmapfile"><code>-Map=<var>mapfile</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dn"><code>-n</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dN"><code>-N</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dN-1"><code>-N</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dn-1"><code>-n</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dno_002dpie"><code>-no-pie</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d_002dno_002drelax">–no-relax</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dnon_005fshared"><code>-non_shared</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dnostdlib"><code>-nostdlib</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dO-level"><code>-O <var>level</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002do-output"><code>-o <var>output</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dP-AUDITLIB"><code>-P <var>AUDITLIB</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dpie"><code>-pie</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dplugin-name"><code>-plugin <var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dq"><code>-q</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dqmagic"><code>-qmagic</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dQy"><code>-Qy</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dr"><code>-r</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dR-file"><code>-R <var>file</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002drpath_002dlink_003ddir"><code>-rpath-link=<var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002drpath_003ddir"><code>-rpath=<var>dir</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002ds"><code>-s</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dS"><code>-S</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dshared"><code>-shared</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dsoname_003dname"><code>-soname=<var>name</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dstatic"><code>-static</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dt"><code>-t</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dT-script"><code>-T <var>script</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dTbss_003dorg"><code>-Tbss=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dTdata_003dorg"><code>-Tdata=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dTldata_002dsegment_003dorg"><code>-Tldata-segment=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dTrodata_002dsegment_003dorg"><code>-Trodata-segment=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dTtext_002dsegment_003dorg"><code>-Ttext-segment=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dTtext_003dorg"><code>-Ttext=<var>org</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002du-symbol"><code>-u <var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dUr"><code>-Ur</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dv"><code>-v</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dV"><code>-V</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dw"><code>-w</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dx"><code>-x</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dX"><code>-X</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dY-path"><code>-Y <var>path</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dy-symbol"><code>-y <var>symbol</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dz"><code>-z</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dz-defs"><code>-z defs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dz-keyword"><code>-z <var>keyword</var></code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dz-muldefs"><code>-z muldefs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002dz-undefs"><code>-z undefs</code></a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-3">.</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002e"><code>.</code></a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-4">/</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002fDISCARD_002f">/DISCARD/</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-5">3</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-32_002dbit-PLT-entries">32-bit PLT entries</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-6">:</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_003aphdr"><code>:<var>phdr</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Phdr">Output Section Phdr</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-7">=</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_003dfillexp"><code>=<var>fillexp</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Fill">Output Section Fill</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-8">></a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_003eregion"><code>><var>region</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Region">Output Section Region</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_symbol-9">[</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_005bCOMMON_005d">[COMMON]</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-A">A</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-AArch64-rela-addend">AArch64 rela addend</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ABSOLUTE-_0028MRI_0029"><code>ABSOLUTE</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-absolute-and-relocatable-symbols">absolute and relocatable symbols</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-absolute-expressions">absolute expressions</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ABSOLUTE_0028exp_0029"><code>ABSOLUTE(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ADDR_0028section_0029"><code>ADDR(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-address_002c-section">address, section</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Address">Output Section Address</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ALIAS-_0028MRI_0029"><code>ALIAS</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ALIGN-_0028MRI_0029"><code>ALIGN</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-align-expression">align expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-align-location-counter">align location counter</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ALIGN_0028align_0029"><code>ALIGN(<var>align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ALIGN_0028exp_002calign_0029"><code>ALIGN(<var>exp</var>,<var>align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ALIGN_0028section_005falign_0029"><code>ALIGN(<var>section_align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Forced-Output-Alignment">Forced Output Alignment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-aligned-common-symbols">aligned common symbols</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ALIGNOF_0028section_0029"><code>ALIGNOF(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-allocating-memory">allocating memory</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-architecture">architecture</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-archive-files_002c-from-cmd-line">archive files, from cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-archive-search-path-in-linker-script">archive search path in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-arithmetic">arithmetic</a>:</td><td> </td><td valign="top"><a href="#Expressions">Expressions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-arithmetic-operators">arithmetic operators</a>:</td><td> </td><td valign="top"><a href="#Operators">Operators</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ARM-interworking-support">ARM interworking support</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ARM1176-erratum-workaround">ARM1176 erratum workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ASCIZ-_0060_0060string_0027_0027"><code>ASCIZ ``<var>string</var>''</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ASSERT"><code>ASSERT</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-assertion-in-linker-script">assertion in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-assignment-in-scripts">assignment in scripts</a>:</td><td> </td><td valign="top"><a href="#Assignments">Assignments</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-AS_005fNEEDED_0028files_0029"><code>AS_NEEDED(<var>files</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-AT_0028lma_0029"><code>AT(<var>lma</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-AT_003elma_005fregion"><code>AT><var>lma_region</var></code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-automatic-data-imports">automatic data imports</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-B">B</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-back-end">back end</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASE-_0028MRI_0029"><code>BASE</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BE8">BE8</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BFD-canonical-format">BFD canonical format</a>:</td><td> </td><td valign="top"><a href="#Canonical-format">Canonical format</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BFD-requirements">BFD requirements</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-big_002dendian-objects">big-endian objects</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-binary-input-format">binary input format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BLOCK_0028exp_0029"><code>BLOCK(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bug-criteria">bug criteria</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bug-reports">bug reports</a>:</td><td> </td><td valign="top"><a href="#Bug-Reporting">Bug Reporting</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bugs-in-ld">bugs in <code>ld</code></a>:</td><td> </td><td valign="top"><a href="#Reporting-Bugs">Reporting Bugs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BYTE_0028expression_0029"><code>BYTE(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-C">C</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-C_002b_002b-constructors_002c-arranging-in-link">C++ constructors, arranging in link</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-CHIP-_0028MRI_0029"><code>CHIP</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COLLECT_005fNO_005fDEMANGLE"><code>COLLECT_NO_DEMANGLE</code></a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-combining-symbols_002c-warnings-on">combining symbols, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMDAT">COMDAT</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMDAT-1">COMDAT</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-files">command files</a>:</td><td> </td><td valign="top"><a href="#Scripts">Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-line">command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-common-allocation">common allocation</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-common-allocation-1">common allocation</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-common-allocation-in-linker-script">common allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-common-allocation-in-linker-script-1">common allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-common-symbol-placement">common symbol placement</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMMONPAGESIZE"><code>COMMONPAGESIZE</code></a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-compatibility_002c-MRI">compatibility, MRI</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-CONSTANT"><code>CONSTANT</code></a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-constants-in-linker-scripts">constants in linker scripts</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-constraints-on-output-sections">constraints on output sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Constraint">Output Section Constraint</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-constructors">constructors</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-CONSTRUCTORS"><code>CONSTRUCTORS</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-constructors_002c-arranging-in-link">constructors, arranging in link</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Cortex_002dA53-erratum-835769-workaround">Cortex-A53 erratum 835769 workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Cortex_002dA8-erratum-workaround">Cortex-A8 erratum workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-crash-of-linker">crash of linker</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-CREATE_005fOBJECT_005fSYMBOLS"><code>CREATE_OBJECT_SYMBOLS</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-creating-a-DEF-file">creating a DEF file</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-cross-reference-table">cross reference table</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-cross-references">cross references</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-cross-references-1">cross references</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ctf-type-sharing">ctf type sharing</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ctf-variables">ctf variables</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-current-output-location">current output location</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-D">D</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-data">data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DATA_005fSEGMENT_005fALIGN_0028maxpagesize_002c-commonpagesize_0029"><code>DATA_SEGMENT_ALIGN(<var>maxpagesize</var>, <var>commonpagesize</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DATA_005fSEGMENT_005fEND_0028exp_0029"><code>DATA_SEGMENT_END(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DATA_005fSEGMENT_005fRELRO_005fEND_0028offset_002c-exp_0029"><code>DATA_SEGMENT_RELRO_END(<var>offset</var>, <var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dbx">dbx</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DEF-files_002c-creating">DEF files, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-default-emulation">default emulation</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-default-input-format">default input format</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-defined-symbol">defined symbol</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DEFINED_0028symbol_0029"><code>DEFINED(<var>symbol</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-deleting-local-symbols">deleting local symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-demangling_002c-default">demangling, default</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-demangling_002c-from-command-line">demangling, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dependency-file">dependency file</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-direct-linking-to-a-dll">direct linking to a dll</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-discarding-sections">discarding sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-discontinuous-memory">discontinuous memory</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DLLs_002c-creating">DLLs, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DLLs_002c-creating-1">DLLs, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DLLs_002c-creating-2">DLLs, creating</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-DLLs_002c-linking-to">DLLs, linking to</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dot">dot</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dot-inside-sections">dot inside sections</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dot-outside-sections">dot outside sections</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dynamic-linker_002c-from-command-line">dynamic linker, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dynamic-symbol-table">dynamic symbol table</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-E">E</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-ELF-program-headers">ELF program headers</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ELF-symbol-visibility">ELF symbol visibility</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-emulation">emulation</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-emulation_002c-default">emulation, default</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-END-_0028MRI_0029"><code>END</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-endianness">endianness</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-entry-point">entry point</a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-entry-point_002c-from-command-line">entry point, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-entry-point_002c-thumb">entry point, thumb</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ENTRY_0028symbol_0029"><code>ENTRY(<var>symbol</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-error-on-valid-input">error on valid input</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-example-of-linker-script">example of linker script</a>:</td><td> </td><td valign="top"><a href="#Simple-Example">Simple Example</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EXCLUDE_005fFILE">EXCLUDE_FILE</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Basics">Input Section Basics</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-executable-segments_002c-warnings-on">executable segments, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-executable-stack_002c-warnings-on">executable stack, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-export-dynamic-symbol">export dynamic symbol</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-export-dynamic-symbol-list">export dynamic symbol list</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-exporting-DLL-symbols">exporting DLL symbols</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expression-evaluation-order">expression evaluation order</a>:</td><td> </td><td valign="top"><a href="#Evaluation">Evaluation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expression-sections">expression sections</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expression_002c-absolute">expression, absolute</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expressions">expressions</a>:</td><td> </td><td valign="top"><a href="#Expressions">Expressions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EXTERN"><code>EXTERN</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-F">F</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-fatal-signal">fatal signal</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-file-name-wildcard-patterns">file name wildcard patterns</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FILEHDR"><code>FILEHDR</code></a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-filename-symbols">filename symbols</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-fill-pattern_002c-entire-section">fill pattern, entire section</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Fill">Output Section Fill</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FILL_0028expression_0029"><code>FILL(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-finalization-function">finalization function</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-first-input-file">first input file</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-first-instruction">first instruction</a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FIX_005fV4BX">FIX_V4BX</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FIX_005fV4BX_005fINTERWORKING">FIX_V4BX_INTERWORKING</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FORCE_005fCOMMON_005fALLOCATION"><code>FORCE_COMMON_ALLOCATION</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FORCE_005fGROUP_005fALLOCATION"><code>FORCE_GROUP_ALLOCATION</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forcing-input-section-alignment">forcing input section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Input-Alignment">Forced Input Alignment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forcing-output-section-alignment">forcing output section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Output-Alignment">Forced Output Alignment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forcing-the-creation-of-dynamic-sections">forcing the creation of dynamic sections</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FORMAT-_0028MRI_0029"><code>FORMAT</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-functions-in-expressions">functions in expressions</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-G">G</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-garbage-collection">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-garbage-collection-1">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-garbage-collection-2">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-garbage-collection-3">garbage collection</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Keep">Input Section Keep</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-generating-optimized-output">generating optimized output</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-GNU-linker"><small>GNU</small> linker</a>:</td><td> </td><td valign="top"><a href="#Overview">Overview</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-GNUTARGET"><code>GNUTARGET</code></a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-group-allocation-in-linker-script">group allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-group-allocation-in-linker-script-1">group allocation in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-GROUP_0028files_0029"><code>GROUP(<var>files</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-grouping-input-files">grouping input files</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-groups-of-archives">groups of archives</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-H">H</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-H8_002f300-support">H8/300 support</a>:</td><td> </td><td valign="top"><a href="#H8_002f300">H8/300</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-header-size">header size</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-heap-size">heap size</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-help">help</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HIDDEN">HIDDEN</a>:</td><td> </td><td valign="top"><a href="#HIDDEN">HIDDEN</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-holes">holes</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-holes_002c-filling">holes, filling</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HPPA-multiple-sub_002dspace-stubs">HPPA multiple sub-space stubs</a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HPPA-stub-grouping">HPPA stub grouping</a>:</td><td> </td><td valign="top"><a href="#HPPA-ELF32">HPPA ELF32</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-I">I</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-image-base">image base</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-implicit-linker-scripts">implicit linker scripts</a>:</td><td> </td><td valign="top"><a href="#Implicit-Linker-Scripts">Implicit Linker Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-import-libraries">import libraries</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-INCLUDE-filename"><code>INCLUDE <var>filename</var></code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-including-a-linker-script">including a linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-including-an-entire-archive">including an entire archive</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-incremental-link">incremental link</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-INHIBIT_005fCOMMON_005fALLOCATION"><code>INHIBIT_COMMON_ALLOCATION</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-initialization-function">initialization function</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-initialized-data-in-ROM">initialized data in ROM</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-file-format-in-linker-script">input file format in linker script</a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-filename-symbols">input filename symbols</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Keywords">Output Section Keywords</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-files-in-linker-scripts">input files in linker scripts</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-files_002c-displaying">input files, displaying</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-format">input format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-format-1">input format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Input-import-library">Input import library</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-object-files-in-linker-scripts">input object files in linker scripts</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-section-alignment">input section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Input-Alignment">Forced Input Alignment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-section-basics">input section basics</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Basics">Input Section Basics</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-section-wildcards">input section wildcards</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input-sections">input sections</a>:</td><td> </td><td valign="top"><a href="#Input-Section">Input Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-INPUT_0028files_0029"><code>INPUT(<var>files</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-INSERT"><code>INSERT</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-insert-user-script-into-default-script">insert user script into default script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-integer-notation">integer notation</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-integer-suffixes">integer suffixes</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-internal-object_002dfile-format">internal object-file format</a>:</td><td> </td><td valign="top"><a href="#Canonical-format">Canonical format</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-invalid-input">invalid input</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-K">K</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-K-and-M-integer-suffixes">K and M integer suffixes</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-KEEP">KEEP</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Keep">Input Section Keep</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-L">L</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-l-_003d"><code>l =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-lazy-evaluation">lazy evaluation</a>:</td><td> </td><td valign="top"><a href="#Evaluation">Evaluation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ld-bugs_002c-reporting"><code>ld</code> bugs, reporting</a>:</td><td> </td><td valign="top"><a href="#Bug-Reporting">Bug Reporting</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ldata-segment-origin_002c-cmd-line">ldata segment origin, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LDEMULATION"><code>LDEMULATION</code></a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LD_005fFEATURE_0028string_0029"><code>LD_FEATURE(<var>string</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-len-_003d"><code>len =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LENGTH-_003d"><code>LENGTH =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LENGTH_0028memory_0029"><code>LENGTH(<var>memory</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-library-search-path-in-linker-script">library search path in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-link-map">link map</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-link-map-discarded">link map discarded</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-link_002dtime-runtime-library-search-path">link-time runtime library search path</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-crash">linker crash</a>:</td><td> </td><td valign="top"><a href="#Bug-Criteria">Bug Criteria</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-plugins">linker plugins</a>:</td><td> </td><td valign="top"><a href="#Plugins">Plugins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-script-concepts">linker script concepts</a>:</td><td> </td><td valign="top"><a href="#Basic-Script-Concepts">Basic Script Concepts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-script-example">linker script example</a>:</td><td> </td><td valign="top"><a href="#Simple-Example">Simple Example</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-script-file-commands">linker script file commands</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-script-format">linker script format</a>:</td><td> </td><td valign="top"><a href="#Script-Format">Script Format</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-script-input-object-files">linker script input object files</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-script-simple-commands">linker script simple commands</a>:</td><td> </td><td valign="top"><a href="#Simple-Commands">Simple Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-linker-scripts">linker scripts</a>:</td><td> </td><td valign="top"><a href="#Scripts">Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LINKER_005fVERSION">LINKER_VERSION</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LINKER_005fVERSION-1"><code>LINKER_VERSION</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LIST-_0028MRI_0029"><code>LIST</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-little_002dendian-objects">little-endian objects</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LOAD-_0028MRI_0029"><code>LOAD</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-load-address">load address</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LOADADDR_0028section_0029"><code>LOADADDR(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-loading_002c-preventing">loading, preventing</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Type">Output Section Type</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-local-symbols_002c-deleting">local symbols, deleting</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-location-counter">location counter</a>:</td><td> </td><td valign="top"><a href="#Location-Counter">Location Counter</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LOG2CEIL_0028exp_0029"><code>LOG2CEIL(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LONG_0028expression_0029"><code>LONG(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-M">M</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-M-and-K-integer-suffixes">M and K integer suffixes</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-M68HC11-and-68HC12-support">M68HC11 and 68HC12 support</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-machine-architecture">machine architecture</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-machine-dependencies">machine dependencies</a>:</td><td> </td><td valign="top"><a href="#Machine-Dependent">Machine Dependent</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-mapping-input-sections-to-output-sections">mapping input sections to output sections</a>:</td><td> </td><td valign="top"><a href="#Input-Section">Input Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MAX"><code>MAX</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MAXPAGESIZE"><code>MAXPAGESIZE</code></a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MEMORY"><code>MEMORY</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-memory-region-attributes">memory region attributes</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-memory-regions">memory regions</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-memory-regions-and-sections">memory regions and sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Region">Output Section Region</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-memory-usage">memory usage</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-memory-usage-1">memory usage</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Merging-exidx-entries">Merging exidx entries</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MIN"><code>MIN</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MIPS-branch-relocation-check-control">MIPS branch relocation check control</a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MIPS-microMIPS-instruction-choice-selection">MIPS microMIPS instruction choice selection</a>:</td><td> </td><td valign="top"><a href="#MIPS">MIPS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Motorola-68K-GOT-generation">Motorola 68K GOT generation</a>:</td><td> </td><td valign="top"><a href="#M68K">M68K</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MRI-compatibility">MRI compatibility</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MSP430-extra-sections">MSP430 extra sections</a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MSP430-Options">MSP430 Options</a>:</td><td> </td><td valign="top"><a href="#MSP430">MSP430</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-N">N</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-NAME-_0028MRI_0029"><code>NAME</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-name_002c-section">name, section</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Name">Output Section Name</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-names">names</a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-naming-the-output-file">naming the output file</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NEXT_0028exp_0029"><code>NEXT(<var>exp</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Nios-II-call-relaxation">Nios II call relaxation</a>:</td><td> </td><td valign="top"><a href="#Nios-II">Nios II</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NMAGIC">NMAGIC</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NOCROSSREFS_0028sections_0029"><code>NOCROSSREFS(<var>sections</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NOCROSSREFS_005fTO_0028tosection-fromsections_0029"><code>NOCROSSREFS_TO(<var>tosection</var> <var>fromsections</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NOLOAD"><code>NOLOAD</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Type">Output Section Type</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-not-enough-room-for-program-headers">not enough room for program headers</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NO_005fENUM_005fSIZE_005fWARNING">NO_ENUM_SIZE_WARNING</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-NO_005fWCHAR_005fSIZE_005fWARNING">NO_WCHAR_SIZE_WARNING</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-O">O</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-o-_003d"><code>o =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-objdump-_002di"><code>objdump -i</code></a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-object-file-management">object file management</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-object-files">object files</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-object-formats-available">object formats available</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-object-size">object size</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OMAGIC">OMAGIC</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OMAGIC-1">OMAGIC</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ONLY_005fIF_005fRO"><code>ONLY_IF_RO</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Constraint">Output Section Constraint</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ONLY_005fIF_005fRW"><code>ONLY_IF_RW</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Constraint">Output Section Constraint</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-opening-object-files">opening object files</a>:</td><td> </td><td valign="top"><a href="#BFD-outline">BFD outline</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-operators-for-arithmetic">operators for arithmetic</a>:</td><td> </td><td valign="top"><a href="#Operators">Operators</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-options">options</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ORDER-_0028MRI_0029"><code>ORDER</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-org-_003d"><code>org =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ORIGIN-_003d"><code>ORIGIN =</code></a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ORIGIN_0028memory_0029"><code>ORIGIN(<var>memory</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-orphan">orphan</a>:</td><td> </td><td valign="top"><a href="#Orphan-Sections">Orphan Sections</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-orphan-sections">orphan sections</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-file-after-errors">output file after errors</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-file-format-in-linker-script">output file format in linker script</a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-file-name-in-linker-script">output file name in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-format">output format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-section-alignment">output section alignment</a>:</td><td> </td><td valign="top"><a href="#Forced-Output-Alignment">Forced Output Alignment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-section-attributes">output section attributes</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Attributes">Output Section Attributes</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output-section-data">output section data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OUTPUT_0028filename_0029"><code>OUTPUT(<var>filename</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OUTPUT_005fARCH_0028bfdarch_0029"><code>OUTPUT_ARCH(<var>bfdarch</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OUTPUT_005fFORMAT_0028bfdname_0029"><code>OUTPUT_FORMAT(<var>bfdname</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OVERLAY"><code>OVERLAY</code></a>:</td><td> </td><td valign="top"><a href="#Overlay-Description">Overlay Description</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-overlays">overlays</a>:</td><td> </td><td valign="top"><a href="#Overlay-Description">Overlay Description</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-P">P</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-partial-link">partial link</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PE-import-table-prefixing">PE import table prefixing</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PHDRS"><code>PHDRS</code></a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PHDRS-1"><code>PHDRS</code></a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PIC_005fVENEER">PIC_VENEER</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Placement-of-SG-veneers">Placement of SG veneers</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-plugins">plugins</a>:</td><td> </td><td valign="top"><a href="#Plugins">Plugins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-pop-state-governing-input-file-handling">pop state governing input file handling</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-position-dependent-executables">position dependent executables</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-position-independent-executables">position independent executables</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC-ELF32-options">PowerPC ELF32 options</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC-GOT">PowerPC GOT</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC-long-branches">PowerPC long branches</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC-PLT">PowerPC PLT</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC-stub-symbols">PowerPC stub symbols</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC-TLS-optimization">PowerPC TLS optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC-ELF32">PowerPC ELF32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-dot-symbols">PowerPC64 dot symbols</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-ELF64-options">PowerPC64 ELF64 options</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-ELFv2-PLT-localentry-optimization">PowerPC64 ELFv2 PLT localentry optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-inline-PLT-call-optimization">PowerPC64 inline PLT call optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-multi_002dTOC">PowerPC64 multi-TOC</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-OPD-optimization">PowerPC64 OPD optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-OPD-spacing">PowerPC64 OPD spacing</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-PLT-call-stub-static-chain">PowerPC64 PLT call stub static chain</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-PLT-call-stub-thread-safety">PowerPC64 PLT call stub thread safety</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-PLT-stub-alignment">PowerPC64 PLT stub alignment</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-Power10-stubs">PowerPC64 Power10 stubs</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-register-save_002frestore-functions">PowerPC64 register save/restore functions</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-stub-grouping">PowerPC64 stub grouping</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-stub-symbols">PowerPC64 stub symbols</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-TLS-optimization">PowerPC64 TLS optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-TOC-optimization">PowerPC64 TOC optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-TOC-sorting">PowerPC64 TOC sorting</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PowerPC64-_005f_005ftls_005fget_005faddr-optimization">PowerPC64 __tls_get_addr optimization</a>:</td><td> </td><td valign="top"><a href="#PowerPC64-ELF64">PowerPC64 ELF64</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-precedence-in-expressions">precedence in expressions</a>:</td><td> </td><td valign="top"><a href="#Operators">Operators</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-prevent-unnecessary-loading">prevent unnecessary loading</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Type">Output Section Type</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-program-headers">program headers</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-program-headers-and-sections">program headers and sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Phdr">Output Section Phdr</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-program-headers_002c-not-enough-room">program headers, not enough room</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-program-segments">program segments</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PROVIDE">PROVIDE</a>:</td><td> </td><td valign="top"><a href="#PROVIDE">PROVIDE</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PROVIDE_005fHIDDEN">PROVIDE_HIDDEN</a>:</td><td> </td><td valign="top"><a href="#PROVIDE_005fHIDDEN">PROVIDE_HIDDEN</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PUBLIC-_0028MRI_0029"><code>PUBLIC</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-push-state-governing-input-file-handling">push state governing input file handling</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-Q">Q</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-QUAD_0028expression_0029"><code>QUAD(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-quoted-symbol-names">quoted symbol names</a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-R">R</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-read_002donly-text">read-only text</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-read_002fwrite-from-cmd-line">read/write from cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-region-alias">region alias</a>:</td><td> </td><td valign="top"><a href="#REGION_005fALIAS">REGION_ALIAS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-region-names">region names</a>:</td><td> </td><td valign="top"><a href="#REGION_005fALIAS">REGION_ALIAS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-regions-of-memory">regions of memory</a>:</td><td> </td><td valign="top"><a href="#MEMORY">MEMORY</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-REGION_005fALIAS_0028alias_002c-region_0029"><code>REGION_ALIAS(<var>alias</var>, <var>region</var>)</code></a>:</td><td> </td><td valign="top"><a href="#REGION_005fALIAS">REGION_ALIAS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relative-expressions">relative expressions</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relaxing-addressing-modes">relaxing addressing modes</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relaxing-on-H8_002f300">relaxing on H8/300</a>:</td><td> </td><td valign="top"><a href="#H8_002f300">H8/300</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relaxing-on-M68HC11">relaxing on M68HC11</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relaxing-on-NDS32"><code>relaxing on NDS32</code></a>:</td><td> </td><td valign="top"><a href="#NDS32">NDS32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relaxing-on-Xtensa">relaxing on Xtensa</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relocatable-and-absolute-symbols">relocatable and absolute symbols</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-relocatable-output">relocatable output</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-remapping-inputs">remapping inputs</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-removing-sections">removing sections</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-reporting-bugs-in-ld">reporting bugs in <code>ld</code></a>:</td><td> </td><td valign="top"><a href="#Reporting-Bugs">Reporting Bugs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-requirements-for-BFD">requirements for BFD</a>:</td><td> </td><td valign="top"><a href="#BFD">BFD</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-retain-relocations-in-final-executable">retain relocations in final executable</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-retaining-specified-symbols">retaining specified symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-rodata-segment-origin_002c-cmd-line">rodata segment origin, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ROM-initialized-data">ROM initialized data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-round-up-expression">round up expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-round-up-location-counter">round up location counter</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-runtime-library-name">runtime library name</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-runtime-library-search-path">runtime library search path</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-runtime-pseudo_002drelocation">runtime pseudo-relocation</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-S">S</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-S_002f390">S/390</a>:</td><td> </td><td valign="top"><a href="#S_002f390-ELF">S/390 ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-S_002f390-ELF-options">S/390 ELF options</a>:</td><td> </td><td valign="top"><a href="#S_002f390-ELF">S/390 ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-scaled-integers">scaled integers</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-scommon-section">scommon section</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-script-files">script files</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-script-files-1">script files</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-scripts">scripts</a>:</td><td> </td><td valign="top"><a href="#Scripts">Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-search-directory_002c-from-cmd-line">search directory, from cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-search-path-in-linker-script">search path in linker script</a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SEARCH_005fDIR_0028path_0029"><code>SEARCH_DIR(<var>path</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SECT-_0028MRI_0029"><code>SECT</code> (MRI)</a>:</td><td> </td><td valign="top"><a href="#MRI">MRI</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-address">section address</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Address">Output Section Address</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-address-in-expression">section address in expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-alignment">section alignment</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-alignment_002c-warnings-on">section alignment, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-data">section data</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-fill-pattern">section fill pattern</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Fill">Output Section Fill</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-groups">section groups</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-groups-1">section groups</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-load-address">section load address</a>:</td><td> </td><td valign="top"><a href="#Output-Section-LMA">Output Section LMA</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-load-address-in-expression">section load address in expression</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-name">section name</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Name">Output Section Name</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-name-wildcard-patterns">section name wildcard patterns</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section-size">section size</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section_002c-assigning-to-memory-region">section, assigning to memory region</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Region">Output Section Region</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-section_002c-assigning-to-program-header">section, assigning to program header</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Phdr">Output Section Phdr</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SECTIONS"><code>SECTIONS</code></a>:</td><td> </td><td valign="top"><a href="#SECTIONS">SECTIONS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-sections_002c-discarding">sections, discarding</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Discarding">Output Section Discarding</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-sections_002c-orphan">sections, orphan</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Secure-gateway-import-library">Secure gateway import library</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-segment-origins_002c-cmd-line">segment origins, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-segments_002c-ELF">segments, ELF</a>:</td><td> </td><td valign="top"><a href="#PHDRS">PHDRS</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SEGMENT_005fSTART_0028segment_002c-default_0029"><code>SEGMENT_START(<var>segment</var>, <var>default</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shared-libraries">shared libraries</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SHORT_0028expression_0029"><code>SHORT(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SIZEOF_0028section_0029"><code>SIZEOF(<var>section</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SIZEOF_005fHEADERS"><code>SIZEOF_HEADERS</code></a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-small-common-symbols">small common symbols</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SORT">SORT</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SORT_005fBY_005fALIGNMENT">SORT_BY_ALIGNMENT</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SORT_005fBY_005fINIT_005fPRIORITY">SORT_BY_INIT_PRIORITY</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SORT_005fBY_005fNAME">SORT_BY_NAME</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SORT_005fNONE">SORT_NONE</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU">SPU</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-1">SPU</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-ELF-options">SPU ELF options</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-extra-overlay-stubs">SPU extra overlay stubs</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-local-store-size">SPU local store size</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-overlay-stub-symbols">SPU overlay stub symbols</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-overlays">SPU overlays</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SPU-plugins">SPU plugins</a>:</td><td> </td><td valign="top"><a href="#SPU-ELF">SPU ELF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SQUAD_0028expression_0029"><code>SQUAD(<var>expression</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-stack-size">stack size</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-standard-Unix-system">standard Unix system</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-start-of-execution">start of execution</a>:</td><td> </td><td valign="top"><a href="#Entry-Point">Entry Point</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-start_002dstop_002dgc">start-stop-gc</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-STARTUP_0028filename_0029"><code>STARTUP(<var>filename</var>)</code></a>:</td><td> </td><td valign="top"><a href="#File-Commands">File Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-static-library-dependencies">static library dependencies</a>:</td><td> </td><td valign="top"><a href="#libdep-Plugin">libdep Plugin</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-STM32L4xx-erratum-workaround">STM32L4xx erratum workaround</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-strip-all-symbols">strip all symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-strip-debugger-symbols">strip debugger symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-stripping-all-but-some-symbols">stripping all but some symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-STUB_005fGROUP_005fSIZE">STUB_GROUP_SIZE</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SUBALIGN_0028subsection_005falign_0029"><code>SUBALIGN(<var>subsection_align</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Forced-Input-Alignment">Forced Input Alignment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-suffixes-for-integers">suffixes for integers</a>:</td><td> </td><td valign="top"><a href="#Constants">Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbol-defaults">symbol defaults</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbol-definition_002c-scripts">symbol definition, scripts</a>:</td><td> </td><td valign="top"><a href="#Assignments">Assignments</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbol-names">symbol names</a>:</td><td> </td><td valign="top"><a href="#Symbols">Symbols</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbol-tracing">symbol tracing</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbol-versions">symbol versions</a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbol_002donly-input">symbol-only input</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbolic-constants">symbolic constants</a>:</td><td> </td><td valign="top"><a href="#Symbolic-Constants">Symbolic Constants</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbols_002c-from-command-line">symbols, from command line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbols_002c-relocatable-and-absolute">symbols, relocatable and absolute</a>:</td><td> </td><td valign="top"><a href="#Expression-Section">Expression Section</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbols_002c-require-defined">symbols, require defined</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-symbols_002c-retaining-selectively">symbols, retaining selectively</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-synthesizing-linker">synthesizing linker</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-synthesizing-on-H8_002f300">synthesizing on H8/300</a>:</td><td> </td><td valign="top"><a href="#H8_002f300">H8/300</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-T">T</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-TARGET_0028bfdname_0029"><code>TARGET(<var>bfdname</var>)</code></a>:</td><td> </td><td valign="top"><a href="#Format-Commands">Format Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TARGET1">TARGET1</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TARGET2">TARGET2</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-text-segment-origin_002c-cmd-line">text segment origin, cmd line</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-thumb-entry-point">thumb entry point</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TI-COFF-versions">TI COFF versions</a>:</td><td> </td><td valign="top"><a href="#TI-COFF">TI COFF</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-traditional-format">traditional format</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-trampoline-generation-on-M68HC11">trampoline generation on M68HC11</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-trampoline-generation-on-M68HC12">trampoline generation on M68HC12</a>:</td><td> </td><td valign="top"><a href="#M68HC11_002f68HC12">M68HC11/68HC12</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-U">U</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-unallocated-address_002c-next">unallocated address, next</a>:</td><td> </td><td valign="top"><a href="#Builtin-Functions">Builtin Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-undefined-symbol">undefined symbol</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-undefined-symbol-in-linker-script">undefined symbol in linker script</a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-undefined-symbols_002c-warnings-on">undefined symbols, warnings on</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-uninitialized-data-placement">uninitialized data placement</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Common">Input Section Common</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-unspecified-memory">unspecified memory</a>:</td><td> </td><td valign="top"><a href="#Output-Section-Data">Output Section Data</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-usage">usage</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-USE_005fBLX">USE_BLX</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-using-a-DEF-file">using a DEF file</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-using-auto_002dexport-functionality">using auto-export functionality</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Using-decorations">Using decorations</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-V">V</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-variables_002c-defining">variables, defining</a>:</td><td> </td><td valign="top"><a href="#Assignments">Assignments</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-verbose_005b_003dNUMBER_005d">verbose[=<var>NUMBER</var>]</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-version">version</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-version-script">version script</a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-version-script_002c-symbol-versions">version script, symbol versions</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-VERSION-_007bscript-text_007d"><code>VERSION {script text}</code></a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-versions-of-symbols">versions of symbols</a>:</td><td> </td><td valign="top"><a href="#VERSION">VERSION</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-VFP11_005fDENORM_005fFIX">VFP11_DENORM_FIX</a>:</td><td> </td><td valign="top"><a href="#ARM">ARM</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-visibility">visibility</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-W">W</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-warnings_002c-on-combining-symbols">warnings, on combining symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-warnings_002c-on-executable-stack">warnings, on executable stack</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-warnings_002c-on-section-alignment">warnings, on section alignment</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-warnings_002c-on-undefined-symbols">warnings, on undefined symbols</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-warnings_002c-on-writeable-and-exectuable-segments">warnings, on writeable and exectuable segments</a>:</td><td> </td><td valign="top"><a href="#Options">Options</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-weak-externals">weak externals</a>:</td><td> </td><td valign="top"><a href="#WIN32">WIN32</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-what-is-this_003f">what is this?</a>:</td><td> </td><td valign="top"><a href="#Overview">Overview</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-wildcard-file-name-patterns">wildcard file name patterns</a>:</td><td> </td><td valign="top"><a href="#Input-Section-Wildcards">Input Section Wildcards</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="LD-Index_cp_letter-X">X</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-Xtensa-options">Xtensa options</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Xtensa-processors">Xtensa processors</a>:</td><td> </td><td valign="top"><a href="#Xtensa">Xtensa</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#LD-Index_cp_symbol-1"><b>"</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-2"><b>-</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-3"><b>.</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-4"><b>/</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-5"><b>3</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-6"><b>:</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-7"><b>=</b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-8"><b>></b></a> + +<a class="summary-letter" href="#LD-Index_cp_symbol-9"><b>[</b></a> + +<br> +<a class="summary-letter" href="#LD-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-Q"><b>Q</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-V"><b>V</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-W"><b>W</b></a> + +<a class="summary-letter" href="#LD-Index_cp_letter-X"><b>X</b></a> + +</td></tr></table> + + +<hr> + + + +</body> +</html> |