1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- This file documents the GNU linker LD 4(GNU Toolchain for the A-profile Architecture 10.3-2021.07 (arm-10.29)) 5version 2.36.1. 6 7Copyright (C) 1991-2021 Free Software Foundation, Inc. 8 9Permission is granted to copy, distribute and/or modify this document 10under the terms of the GNU Free Documentation License, Version 1.3 11or any later version published by the Free Software Foundation; 12with no Invariant Sections, with no Front-Cover Texts, and with no 13Back-Cover Texts. A copy of the license is included in the 14section entitled "GNU Free Documentation License". --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>LD: Input Section Basics</title> 18 19<meta name="description" content="LD: Input Section Basics"> 20<meta name="keywords" content="LD: Input Section Basics"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="LD-Index.html#LD-Index" rel="index" title="LD Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Input-Section.html#Input-Section" rel="up" title="Input Section"> 29<link href="Input-Section-Wildcards.html#Input-Section-Wildcards" rel="next" title="Input Section Wildcards"> 30<link href="Input-Section.html#Input-Section" rel="previous" title="Input Section"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Input-Section-Basics"></a> 65<div class="header"> 66<p> 67Next: <a href="Input-Section-Wildcards.html#Input-Section-Wildcards" accesskey="n" rel="next">Input Section Wildcards</a>, Up: <a href="Input-Section.html#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Input-Section-Basics-1"></a> 71<h4 class="subsubsection">3.6.4.1 Input Section Basics</h4> 72<a name="index-input-section-basics"></a> 73<p>An input section description consists of a file name optionally followed 74by a list of section names in parentheses. 75</p> 76<p>The file name and the section name may be wildcard patterns, which we 77describe further below (see <a href="Input-Section-Wildcards.html#Input-Section-Wildcards">Input Section Wildcards</a>). 78</p> 79<p>The most common input section description is to include all input 80sections with a particular name in the output section. For example, to 81include all input ‘<samp>.text</samp>’ sections, you would write: 82</p><div class="smallexample"> 83<pre class="smallexample">*(.text) 84</pre></div> 85<p>Here the ‘<samp>*</samp>’ is a wildcard which matches any file name. To exclude a list 86<a name="index-EXCLUDE_005fFILE"></a> 87of files from matching the file name wildcard, EXCLUDE_FILE may be used to 88match all files except the ones specified in the EXCLUDE_FILE list. For 89example: 90</p><div class="smallexample"> 91<pre class="smallexample">EXCLUDE_FILE (*crtend.o *otherfile.o) *(.ctors) 92</pre></div> 93<p>will cause all .ctors sections from all files except <samp>crtend.o</samp> 94and <samp>otherfile.o</samp> to be included. The EXCLUDE_FILE can also be 95placed inside the section list, for example: 96</p><div class="smallexample"> 97<pre class="smallexample">*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors) 98</pre></div> 99<p>The result of this is identically to the previous example. Supporting 100two syntaxes for EXCLUDE_FILE is useful if the section list contains 101more than one section, as described below. 102</p> 103<p>There are two ways to include more than one section: 104</p><div class="smallexample"> 105<pre class="smallexample">*(.text .rdata) 106*(.text) *(.rdata) 107</pre></div> 108<p>The difference between these is the order in which the ‘<samp>.text</samp>’ and 109‘<samp>.rdata</samp>’ input sections will appear in the output section. In the 110first example, they will be intermingled, appearing in the same order as 111they are found in the linker input. In the second example, all 112‘<samp>.text</samp>’ input sections will appear first, followed by all 113‘<samp>.rdata</samp>’ input sections. 114</p> 115<p>When using EXCLUDE_FILE with more than one section, if the exclusion 116is within the section list then the exclusion only applies to the 117immediately following section, for example: 118</p><div class="smallexample"> 119<pre class="smallexample">*(EXCLUDE_FILE (*somefile.o) .text .rdata) 120</pre></div> 121<p>will cause all ‘<samp>.text</samp>’ sections from all files except 122<samp>somefile.o</samp> to be included, while all ‘<samp>.rdata</samp>’ sections 123from all files, including <samp>somefile.o</samp>, will be included. To 124exclude the ‘<samp>.rdata</samp>’ sections from <samp>somefile.o</samp> the example 125could be modified to: 126</p><div class="smallexample"> 127<pre class="smallexample">*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata) 128</pre></div> 129<p>Alternatively, placing the EXCLUDE_FILE outside of the section list, 130before the input file selection, will cause the exclusion to apply for 131all sections. Thus the previous example can be rewritten as: 132</p><div class="smallexample"> 133<pre class="smallexample">EXCLUDE_FILE (*somefile.o) *(.text .rdata) 134</pre></div> 135 136<p>You can specify a file name to include sections from a particular file. 137You would do this if one or more of your files contain special data that 138needs to be at a particular location in memory. For example: 139</p><div class="smallexample"> 140<pre class="smallexample">data.o(.data) 141</pre></div> 142 143<p>To refine the sections that are included based on the section flags 144of an input section, INPUT_SECTION_FLAGS may be used. 145</p> 146<p>Here is a simple example for using Section header flags for ELF sections: 147</p> 148<div class="smallexample"> 149<pre class="smallexample">SECTIONS { 150 .text : { INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) } 151 .text2 : { INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) } 152} 153</pre></div> 154 155<p>In this example, the output section ‘<samp>.text</samp>’ will be comprised of any 156input section matching the name *(.text) whose section header flags 157<code>SHF_MERGE</code> and <code>SHF_STRINGS</code> are set. The output section 158‘<samp>.text2</samp>’ will be comprised of any input section matching the name *(.text) 159whose section header flag <code>SHF_WRITE</code> is clear. 160</p> 161<p>You can also specify files within archives by writing a pattern 162matching the archive, a colon, then the pattern matching the file, 163with no whitespace around the colon. 164</p> 165<dl compact="compact"> 166<dt>‘<samp>archive:file</samp>’</dt> 167<dd><p>matches file within archive 168</p></dd> 169<dt>‘<samp>archive:</samp>’</dt> 170<dd><p>matches the whole archive 171</p></dd> 172<dt>‘<samp>:file</samp>’</dt> 173<dd><p>matches file but not one in an archive 174</p></dd> 175</dl> 176 177<p>Either one or both of ‘<samp>archive</samp>’ and ‘<samp>file</samp>’ can contain shell 178wildcards. On DOS based file systems, the linker will assume that a 179single letter followed by a colon is a drive specifier, so 180‘<samp>c:myfile.o</samp>’ is a simple file specification, not ‘<samp>myfile.o</samp>’ 181within an archive called ‘<samp>c</samp>’. ‘<samp>archive:file</samp>’ filespecs may 182also be used within an <code>EXCLUDE_FILE</code> list, but may not appear in 183other linker script contexts. For instance, you cannot extract a file 184from an archive by using ‘<samp>archive:file</samp>’ in an <code>INPUT</code> 185command. 186</p> 187<p>If you use a file name without a list of sections, then all sections in 188the input file will be included in the output section. This is not 189commonly done, but it may by useful on occasion. For example: 190</p><div class="smallexample"> 191<pre class="smallexample">data.o 192</pre></div> 193 194<p>When you use a file name which is not an ‘<samp>archive:file</samp>’ specifier 195and does not contain any wild card 196characters, the linker will first see if you also specified the file 197name on the linker command line or in an <code>INPUT</code> command. If you 198did not, the linker will attempt to open the file as an input file, as 199though it appeared on the command line. Note that this differs from an 200<code>INPUT</code> command, because the linker will not search for the file in 201the archive search path. 202</p> 203<hr> 204<div class="header"> 205<p> 206Next: <a href="Input-Section-Wildcards.html#Input-Section-Wildcards" accesskey="n" rel="next">Input Section Wildcards</a>, Up: <a href="Input-Section.html#Input-Section" accesskey="u" rel="up">Input Section</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p> 207</div> 208 209 210 211</body> 212</html> 213