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 Assembler "as". 4 5Copyright (C) 1991-2021 Free Software Foundation, Inc. 6 7Permission is granted to copy, distribute and/or modify this document 8under the terms of the GNU Free Documentation License, Version 1.3 9or any later version published by the Free Software Foundation; 10with no Invariant Sections, with no Front-Cover Texts, and with no 11Back-Cover Texts. A copy of the license is included in the 12section entitled "GNU Free Documentation License". 13 --> 14<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 15<head> 16<title>Using as: Section</title> 17 18<meta name="description" content="Using as: Section"> 19<meta name="keywords" content="Using as: Section"> 20<meta name="resource-type" content="document"> 21<meta name="distribution" content="global"> 22<meta name="Generator" content="makeinfo"> 23<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 24<link href="index.html#Top" rel="start" title="Top"> 25<link href="AS-Index.html#AS-Index" rel="index" title="AS Index"> 26<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 27<link href="Pseudo-Ops.html#Pseudo-Ops" rel="up" title="Pseudo Ops"> 28<link href="Set.html#Set" rel="next" title="Set"> 29<link href="Scl.html#Scl" rel="previous" title="Scl"> 30<style type="text/css"> 31<!-- 32a.summary-letter {text-decoration: none} 33blockquote.smallquotation {font-size: smaller} 34div.display {margin-left: 3.2em} 35div.example {margin-left: 3.2em} 36div.indentedblock {margin-left: 3.2em} 37div.lisp {margin-left: 3.2em} 38div.smalldisplay {margin-left: 3.2em} 39div.smallexample {margin-left: 3.2em} 40div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 41div.smalllisp {margin-left: 3.2em} 42kbd {font-style:oblique} 43pre.display {font-family: inherit} 44pre.format {font-family: inherit} 45pre.menu-comment {font-family: serif} 46pre.menu-preformatted {font-family: serif} 47pre.smalldisplay {font-family: inherit; font-size: smaller} 48pre.smallexample {font-size: smaller} 49pre.smallformat {font-family: inherit; font-size: smaller} 50pre.smalllisp {font-size: smaller} 51span.nocodebreak {white-space:nowrap} 52span.nolinebreak {white-space:nowrap} 53span.roman {font-family:serif; font-weight:normal} 54span.sansserif {font-family:sans-serif; font-weight:normal} 55ul.no-bullet {list-style: none} 56--> 57</style> 58 59 60</head> 61 62<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 63<a name="Section"></a> 64<div class="header"> 65<p> 66Next: <a href="Set.html#Set" accesskey="n" rel="next">Set</a>, Previous: <a href="Scl.html#Scl" accesskey="p" rel="previous">Scl</a>, Up: <a href="Pseudo-Ops.html#Pseudo-Ops" accesskey="u" rel="up">Pseudo Ops</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p> 67</div> 68<hr> 69<a name="g_t_002esection-name"></a> 70<h3 class="section">7.84 <code>.section <var>name</var></code></h3> 71 72<a name="index-named-section"></a> 73<p>Use the <code>.section</code> directive to assemble the following code into a section 74named <var>name</var>. 75</p> 76<p>This directive is only supported for targets that actually support arbitrarily 77named sections; on <code>a.out</code> targets, for example, it is not accepted, even 78with a standard <code>a.out</code> section name. 79</p> 80<a name="COFF-Version"></a> 81<h4 class="subheading">COFF Version</h4> 82 83<a name="index-section-directive-_0028COFF-version_0029"></a> 84<p>For COFF targets, the <code>.section</code> directive is used in one of the following 85ways: 86</p> 87<div class="smallexample"> 88<pre class="smallexample">.section <var>name</var>[, "<var>flags</var>"] 89.section <var>name</var>[, <var>subsection</var>] 90</pre></div> 91 92<p>If the optional argument is quoted, it is taken as flags to use for the 93section. Each flag is a single character. The following flags are recognized: 94</p> 95<dl compact="compact"> 96<dt><code>b</code></dt> 97<dd><p>bss section (uninitialized data) 98</p></dd> 99<dt><code>n</code></dt> 100<dd><p>section is not loaded 101</p></dd> 102<dt><code>w</code></dt> 103<dd><p>writable section 104</p></dd> 105<dt><code>d</code></dt> 106<dd><p>data section 107</p></dd> 108<dt><code>e</code></dt> 109<dd><p>exclude section from linking 110</p></dd> 111<dt><code>r</code></dt> 112<dd><p>read-only section 113</p></dd> 114<dt><code>x</code></dt> 115<dd><p>executable section 116</p></dd> 117<dt><code>s</code></dt> 118<dd><p>shared section (meaningful for PE targets) 119</p></dd> 120<dt><code>a</code></dt> 121<dd><p>ignored. (For compatibility with the ELF version) 122</p></dd> 123<dt><code>y</code></dt> 124<dd><p>section is not readable (meaningful for PE targets) 125</p></dd> 126<dt><code>0-9</code></dt> 127<dd><p>single-digit power-of-two section alignment (GNU extension) 128</p></dd> 129</dl> 130 131<p>If no flags are specified, the default flags depend upon the section name. If 132the section name is not recognized, the default will be for the section to be 133loaded and writable. Note the <code>n</code> and <code>w</code> flags remove attributes 134from the section, rather than adding them, so if they are used on their own it 135will be as if no flags had been specified at all. 136</p> 137<p>If the optional argument to the <code>.section</code> directive is not quoted, it is 138taken as a subsection number (see <a href="Sub_002dSections.html#Sub_002dSections">Sub-Sections</a>). 139</p> 140<a name="ELF-Version"></a> 141<h4 class="subheading">ELF Version</h4> 142 143<a name="index-Section-Stack-3"></a> 144<p>This is one of the ELF section stack manipulation directives. The others are 145<code>.subsection</code> (see <a href="SubSection.html#SubSection">SubSection</a>), <code>.pushsection</code> 146(see <a href="PushSection.html#PushSection">PushSection</a>), <code>.popsection</code> (see <a href="PopSection.html#PopSection">PopSection</a>), and 147<code>.previous</code> (see <a href="Previous.html#Previous">Previous</a>). 148</p> 149<a name="index-section-directive-_0028ELF-version_0029"></a> 150<p>For ELF targets, the <code>.section</code> directive is used like this: 151</p> 152<div class="smallexample"> 153<pre class="smallexample">.section <var>name</var> [, "<var>flags</var>"[, @<var>type</var>[,<var>flag_specific_arguments</var>]]] 154</pre></div> 155 156<a name="Section-Name-Substitutions"></a><a name="index-_002d_002dsectname_002dsubst"></a> 157<a name="index-section-name-substitution"></a> 158<p>If the ‘<samp>--sectname-subst</samp>’ command-line option is provided, the <var>name</var> 159argument may contain a substitution sequence. Only <code>%S</code> is supported 160at the moment, and substitutes the current section name. For example: 161</p> 162<div class="smallexample"> 163<pre class="smallexample">.macro exception_code 164.section %S.exception 165[exception code here] 166.previous 167.endm 168 169.text 170[code] 171exception_code 172[...] 173 174.section .init 175[init code] 176exception_code 177[...] 178</pre></div> 179 180<p>The two <code>exception_code</code> invocations above would create the 181<code>.text.exception</code> and <code>.init.exception</code> sections respectively. 182This is useful e.g. to discriminate between ancillary sections that are 183tied to setup code to be discarded after use from ancillary sections that 184need to stay resident without having to define multiple <code>exception_code</code> 185macros just for that purpose. 186</p> 187<p>The optional <var>flags</var> argument is a quoted string which may contain any 188combination of the following characters: 189</p> 190<dl compact="compact"> 191<dt><code>a</code></dt> 192<dd><p>section is allocatable 193</p></dd> 194<dt><code>d</code></dt> 195<dd><p>section is a GNU_MBIND section 196</p></dd> 197<dt><code>e</code></dt> 198<dd><p>section is excluded from executable and shared library. 199</p></dd> 200<dt><code>o</code></dt> 201<dd><p>section references a symbol defined in another section (the linked-to 202section) in the same file. 203</p></dd> 204<dt><code>w</code></dt> 205<dd><p>section is writable 206</p></dd> 207<dt><code>x</code></dt> 208<dd><p>section is executable 209</p></dd> 210<dt><code>M</code></dt> 211<dd><p>section is mergeable 212</p></dd> 213<dt><code>S</code></dt> 214<dd><p>section contains zero terminated strings 215</p></dd> 216<dt><code>G</code></dt> 217<dd><p>section is a member of a section group 218</p></dd> 219<dt><code>T</code></dt> 220<dd><p>section is used for thread-local-storage 221</p></dd> 222<dt><code>?</code></dt> 223<dd><p>section is a member of the previously-current section’s group, if any 224</p></dd> 225<dt><code>R</code></dt> 226<dd><p>retained section (apply SHF_GNU_RETAIN to prevent linker garbage 227collection, GNU ELF extension) 228</p></dd> 229<dt><code><code><number></code></code></dt> 230<dd><p>a numeric value indicating the bits to be set in the ELF section header’s flags 231field. Note - if one or more of the alphabetic characters described above is 232also included in the flags field, their bit values will be ORed into the 233resulting value. 234</p></dd> 235<dt><code><code><target specific></code></code></dt> 236<dd><p>some targets extend this list with their own flag characters 237</p></dd> 238</dl> 239 240<p>Note - once a section’s flags have been set they cannot be changed. There are 241a few exceptions to this rule however. Processor and application specific 242flags can be added to an already defined section. The <code>.interp</code>, 243<code>.strtab</code> and <code>.symtab</code> sections can have the allocate flag 244(<code>a</code>) set after they are initially defined, and the <code>.note-GNU-stack</code> 245section may have the executable (<code>x</code>) flag added. Also note that the 246<code>.attach_to_group</code> directive can be used to add a section to a group even 247if the section was not originally declared to be part of that group. 248</p> 249<p>The optional <var>type</var> argument may contain one of the following constants: 250</p> 251<dl compact="compact"> 252<dt><code>@progbits</code></dt> 253<dd><p>section contains data 254</p></dd> 255<dt><code>@nobits</code></dt> 256<dd><p>section does not contain data (i.e., section only occupies space) 257</p></dd> 258<dt><code>@note</code></dt> 259<dd><p>section contains data which is used by things other than the program 260</p></dd> 261<dt><code>@init_array</code></dt> 262<dd><p>section contains an array of pointers to init functions 263</p></dd> 264<dt><code>@fini_array</code></dt> 265<dd><p>section contains an array of pointers to finish functions 266</p></dd> 267<dt><code>@preinit_array</code></dt> 268<dd><p>section contains an array of pointers to pre-init functions 269</p></dd> 270<dt><code>@<code><number></code></code></dt> 271<dd><p>a numeric value to be set as the ELF section header’s type field. 272</p></dd> 273<dt><code>@<code><target specific></code></code></dt> 274<dd><p>some targets extend this list with their own types 275</p></dd> 276</dl> 277 278<p>Many targets only support the first three section types. The type may be 279enclosed in double quotes if necessary. 280</p> 281<p>Note on targets where the <code>@</code> character is the start of a comment (eg 282ARM) then another character is used instead. For example the ARM port uses the 283<code>%</code> character. 284</p> 285<p>Note - some sections, eg <code>.text</code> and <code>.data</code> are considered to be 286special and have fixed types. Any attempt to declare them with a different 287type will generate an error from the assembler. 288</p> 289<p>If <var>flags</var> contains the <code>M</code> symbol then the <var>type</var> argument must 290be specified as well as an extra argument—<var>entsize</var>—like this: 291</p> 292<div class="smallexample"> 293<pre class="smallexample">.section <var>name</var> , "<var>flags</var>"M, @<var>type</var>, <var>entsize</var> 294</pre></div> 295 296<p>Sections with the <code>M</code> flag but not <code>S</code> flag must contain fixed size 297constants, each <var>entsize</var> octets long. Sections with both <code>M</code> and 298<code>S</code> must contain zero terminated strings where each character is 299<var>entsize</var> bytes long. The linker may remove duplicates within sections with 300the same name, same entity size and same flags. <var>entsize</var> must be an 301absolute expression. For sections with both <code>M</code> and <code>S</code>, a string 302which is a suffix of a larger string is considered a duplicate. Thus 303<code>"def"</code> will be merged with <code>"abcdef"</code>; A reference to the first 304<code>"def"</code> will be changed to a reference to <code>"abcdef"+3</code>. 305</p> 306<p>If <var>flags</var> contains the <code>o</code> flag, then the <var>type</var> argument 307must be present along with an additional field like this: 308</p> 309<div class="smallexample"> 310<pre class="smallexample">.section <var>name</var>,"<var>flags</var>"o,@<var>type</var>,<var>SymbolName</var>|<var>SectionIndex</var> 311</pre></div> 312 313<p>The <var>SymbolName</var> field specifies the symbol name which the section 314references. Alternatively a numeric <var>SectionIndex</var> can be provided. This 315is not generally a good idea as section indicies are rarely known at assembly 316time, but the facility is provided for testing purposes. An index of zero is 317allowed. It indicates that the linked-to section has already been discarded. 318</p> 319<p>Note: If both the <var>M</var> and <var>o</var> flags are present, then the fields 320for the Merge flag should come first, like this: 321</p> 322<div class="smallexample"> 323<pre class="smallexample">.section <var>name</var>,"<var>flags</var>"Mo,@<var>type</var>,<var>entsize</var>,<var>SymbolName</var> 324</pre></div> 325 326<p>If <var>flags</var> contains the <code>G</code> symbol then the <var>type</var> argument must 327be present along with an additional field like this: 328</p> 329<div class="smallexample"> 330<pre class="smallexample">.section <var>name</var> , "<var>flags</var>"G, @<var>type</var>, <var>GroupName</var>[, <var>linkage</var>] 331</pre></div> 332 333<p>The <var>GroupName</var> field specifies the name of the section group to which this 334particular section belongs. The optional linkage field can contain: 335</p> 336<dl compact="compact"> 337<dt><code>comdat</code></dt> 338<dd><p>indicates that only one copy of this section should be retained 339</p></dd> 340<dt><code>.gnu.linkonce</code></dt> 341<dd><p>an alias for comdat 342</p></dd> 343</dl> 344 345<p>Note: if both the <var>M</var> and <var>G</var> flags are present then the fields for 346the Merge flag should come first, like this: 347</p> 348<div class="smallexample"> 349<pre class="smallexample">.section <var>name</var> , "<var>flags</var>"MG, @<var>type</var>, <var>entsize</var>, <var>GroupName</var>[, <var>linkage</var>] 350</pre></div> 351 352<p>If both <code>o</code> flag and <code>G</code> flag are present, then the 353<var>SymbolName</var> field for <code>o</code> comes first, like this: 354</p> 355<div class="smallexample"> 356<pre class="smallexample">.section <var>name</var>,"<var>flags</var>"oG,@<var>type</var>,<var>SymbolName</var>,<var>GroupName</var>[,<var>linkage</var>] 357</pre></div> 358 359<p>If <var>flags</var> contains the <code>?</code> symbol then it may not also contain the 360<code>G</code> symbol and the <var>GroupName</var> or <var>linkage</var> fields should not be 361present. Instead, <code>?</code> says to consider the section that’s current before 362this directive. If that section used <code>G</code>, then the new section will use 363<code>G</code> with those same <var>GroupName</var> and <var>linkage</var> fields implicitly. 364If not, then the <code>?</code> symbol has no effect. 365</p> 366<p>The optional <var>unique,<code><number></code></var> argument must come last. It 367assigns <var><code><number></code></var> as a unique section ID to distinguish 368different sections with the same section name like these: 369</p> 370<div class="smallexample"> 371<pre class="smallexample">.section <var>name</var>,"<var>flags</var>",@<var>type</var>,<var>unique,<code><number></code></var> 372.section <var>name</var>,"<var>flags</var>"G,@<var>type</var>,<var>GroupName</var>,[<var>linkage</var>],<var>unique,<code><number></code></var> 373.section <var>name</var>,"<var>flags</var>"MG,@<var>type</var>,<var>entsize</var>,<var>GroupName</var>[,<var>linkage</var>],<var>unique,<code><number></code></var> 374</pre></div> 375 376<p>The valid values of <var><code><number></code></var> are between 0 and 4294967295. 377</p> 378<p>If no flags are specified, the default flags depend upon the section name. If 379the section name is not recognized, the default will be for the section to have 380none of the above flags: it will not be allocated in memory, nor writable, nor 381executable. The section will contain data. 382</p> 383<p>For ELF targets, the assembler supports another type of <code>.section</code> 384directive for compatibility with the Solaris assembler: 385</p> 386<div class="smallexample"> 387<pre class="smallexample">.section "<var>name</var>"[, <var>flags</var>...] 388</pre></div> 389 390<p>Note that the section name is quoted. There may be a sequence of comma 391separated flags: 392</p> 393<dl compact="compact"> 394<dt><code>#alloc</code></dt> 395<dd><p>section is allocatable 396</p></dd> 397<dt><code>#write</code></dt> 398<dd><p>section is writable 399</p></dd> 400<dt><code>#execinstr</code></dt> 401<dd><p>section is executable 402</p></dd> 403<dt><code>#exclude</code></dt> 404<dd><p>section is excluded from executable and shared library. 405</p></dd> 406<dt><code>#tls</code></dt> 407<dd><p>section is used for thread local storage 408</p></dd> 409</dl> 410 411<p>This directive replaces the current section and subsection. See the 412contents of the gas testsuite directory <code>gas/testsuite/gas/elf</code> for 413some examples of how this directive and the other section stack directives 414work. 415</p> 416<hr> 417<div class="header"> 418<p> 419Next: <a href="Set.html#Set" accesskey="n" rel="next">Set</a>, Previous: <a href="Scl.html#Scl" accesskey="p" rel="previous">Scl</a>, Up: <a href="Pseudo-Ops.html#Pseudo-Ops" accesskey="u" rel="up">Pseudo Ops</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p> 420</div> 421 422 423 424</body> 425</html> 426