| <html lang="en"> |
| <head> |
| <title>Section - Using as</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Using as"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Pseudo-Ops.html#Pseudo-Ops" title="Pseudo Ops"> |
| <link rel="prev" href="Scl.html#Scl" title="Scl"> |
| <link rel="next" href="Set.html#Set" title="Set"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU Assembler "as". |
| |
| Copyright (C) 1991-2019 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''. |
| |
| --> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Section"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Set.html#Set">Set</a>, |
| Previous: <a rel="previous" accesskey="p" href="Scl.html#Scl">Scl</a>, |
| Up: <a rel="up" accesskey="u" href="Pseudo-Ops.html#Pseudo-Ops">Pseudo Ops</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">7.82 <code>.section </code><var>name</var></h3> |
| |
| <p><a name="index-named-section-459"></a>Use the <code>.section</code> directive to assemble the following code into a section |
| named <var>name</var>. |
| |
| <p>This directive is only supported for targets that actually support arbitrarily |
| named sections; on <code>a.out</code> targets, for example, it is not accepted, even |
| with a standard <code>a.out</code> section name. |
| |
| <!-- only print the extra heading if both COFF and ELF are set --> |
| <h4 class="subheading">COFF Version</h4> |
| |
| <p><a name="index-g_t_0040code_007bsection_007d-directive-_0028COFF-version_0029-460"></a>For COFF targets, the <code>.section</code> directive is used in one of the following |
| ways: |
| |
| <pre class="smallexample"> .section <var>name</var>[, "<var>flags</var>"] |
| .section <var>name</var>[, <var>subsection</var>] |
| </pre> |
| <p>If the optional argument is quoted, it is taken as flags to use for the |
| section. Each flag is a single character. The following flags are recognized: |
| |
| <dl> |
| <dt><code>b</code><dd>bss section (uninitialized data) |
| <br><dt><code>n</code><dd>section is not loaded |
| <br><dt><code>w</code><dd>writable section |
| <br><dt><code>d</code><dd>data section |
| <br><dt><code>e</code><dd>exclude section from linking |
| <br><dt><code>r</code><dd>read-only section |
| <br><dt><code>x</code><dd>executable section |
| <br><dt><code>s</code><dd>shared section (meaningful for PE targets) |
| <br><dt><code>a</code><dd>ignored. (For compatibility with the ELF version) |
| <br><dt><code>y</code><dd>section is not readable (meaningful for PE targets) |
| <br><dt><code>0-9</code><dd>single-digit power-of-two section alignment (GNU extension) |
| </dl> |
| |
| <p>If no flags are specified, the default flags depend upon the section name. If |
| the section name is not recognized, the default will be for the section to be |
| loaded and writable. Note the <code>n</code> and <code>w</code> flags remove attributes |
| from the section, rather than adding them, so if they are used on their own it |
| will be as if no flags had been specified at all. |
| |
| <p>If the optional argument to the <code>.section</code> directive is not quoted, it is |
| taken as a subsection number (see <a href="Sub_002dSections.html#Sub_002dSections">Sub-Sections</a>). |
| |
| <!-- only print the extra heading if both COFF and ELF are set --> |
| <h4 class="subheading">ELF Version</h4> |
| |
| <p><a name="index-Section-Stack-461"></a>This is one of the ELF section stack manipulation directives. The others are |
| <code>.subsection</code> (see <a href="SubSection.html#SubSection">SubSection</a>), <code>.pushsection</code> |
| (see <a href="PushSection.html#PushSection">PushSection</a>), <code>.popsection</code> (see <a href="PopSection.html#PopSection">PopSection</a>), and |
| <code>.previous</code> (see <a href="Previous.html#Previous">Previous</a>). |
| |
| <p><a name="index-g_t_0040code_007bsection_007d-directive-_0028ELF-version_0029-462"></a>For ELF targets, the <code>.section</code> directive is used like this: |
| |
| <pre class="smallexample"> .section <var>name</var> [, "<var>flags</var>"[, @<var>type</var>[,<var>flag_specific_arguments</var>]]] |
| </pre> |
| <p><a name="Section-Name-Substitutions"></a><a name="index-g_t_002d_002dsectname_002dsubst-463"></a><a name="index-section-name-substitution-464"></a>If the ‘<samp><span class="samp">--sectname-subst</span></samp>’ command-line option is provided, the <var>name</var> |
| argument may contain a substitution sequence. Only <code>%S</code> is supported |
| at the moment, and substitutes the current section name. For example: |
| |
| <pre class="smallexample"> .macro exception_code |
| .section %S.exception |
| [exception code here] |
| .previous |
| .endm |
| |
| .text |
| [code] |
| exception_code |
| [...] |
| |
| .section .init |
| [init code] |
| exception_code |
| [...] |
| </pre> |
| <p>The two <code>exception_code</code> invocations above would create the |
| <code>.text.exception</code> and <code>.init.exception</code> sections respectively. |
| This is useful e.g. to discriminate between ancillary sections that are |
| tied to setup code to be discarded after use from ancillary sections that |
| need to stay resident without having to define multiple <code>exception_code</code> |
| macros just for that purpose. |
| |
| <p>The optional <var>flags</var> argument is a quoted string which may contain any |
| combination of the following characters: |
| |
| <dl> |
| <dt><code>a</code><dd>section is allocatable |
| <br><dt><code>d</code><dd>section is a GNU_MBIND section |
| <br><dt><code>e</code><dd>section is excluded from executable and shared library. |
| <br><dt><code>w</code><dd>section is writable |
| <br><dt><code>x</code><dd>section is executable |
| <br><dt><code>M</code><dd>section is mergeable |
| <br><dt><code>S</code><dd>section contains zero terminated strings |
| <br><dt><code>G</code><dd>section is a member of a section group |
| <br><dt><code>T</code><dd>section is used for thread-local-storage |
| <br><dt><code>?</code><dd>section is a member of the previously-current section's group, if any |
| <br><dt><code><number></code><dd>a numeric value indicating the bits to be set in the ELF section header's flags |
| field. Note - if one or more of the alphabetic characters described above is |
| also included in the flags field, their bit values will be ORed into the |
| resulting value. |
| <br><dt><code><target specific></code><dd>some targets extend this list with their own flag characters |
| </dl> |
| |
| <p>Note - once a section's flags have been set they cannot be changed. There are |
| a few exceptions to this rule however. Processor and application specific |
| flags can be added to an already defined section. The <code>.interp</code>, |
| <code>.strtab</code> and <code>.symtab</code> sections can have the allocate flag |
| (<code>a</code>) set after they are initially defined, and the <code>.note-GNU-stack</code> |
| section may have the executable (<code>x</code>) flag added. |
| |
| <p>The optional <var>type</var> argument may contain one of the following constants: |
| |
| <dl> |
| <dt><code>@progbits</code><dd>section contains data |
| <br><dt><code>@nobits</code><dd>section does not contain data (i.e., section only occupies space) |
| <br><dt><code>@note</code><dd>section contains data which is used by things other than the program |
| <br><dt><code>@init_array</code><dd>section contains an array of pointers to init functions |
| <br><dt><code>@fini_array</code><dd>section contains an array of pointers to finish functions |
| <br><dt><code>@preinit_array</code><dd>section contains an array of pointers to pre-init functions |
| <br><dt><code>@<number></code><dd>a numeric value to be set as the ELF section header's type field. |
| <br><dt><code>@<target specific></code><dd>some targets extend this list with their own types |
| </dl> |
| |
| <p>Many targets only support the first three section types. The type may be |
| enclosed in double quotes if necessary. |
| |
| <p>Note on targets where the <code>@</code> character is the start of a comment (eg |
| ARM) then another character is used instead. For example the ARM port uses the |
| <code>%</code> character. |
| |
| <p>Note - some sections, eg <code>.text</code> and <code>.data</code> are considered to be |
| special and have fixed types. Any attempt to declare them with a different |
| type will generate an error from the assembler. |
| |
| <p>If <var>flags</var> contains the <code>M</code> symbol then the <var>type</var> argument must |
| be specified as well as an extra argument—<var>entsize</var>—like this: |
| |
| <pre class="smallexample"> .section <var>name</var> , "<var>flags</var>"M, @<var>type</var>, <var>entsize</var> |
| </pre> |
| <p>Sections with the <code>M</code> flag but not <code>S</code> flag must contain fixed size |
| constants, each <var>entsize</var> octets long. Sections with both <code>M</code> and |
| <code>S</code> must contain zero terminated strings where each character is |
| <var>entsize</var> bytes long. The linker may remove duplicates within sections with |
| the same name, same entity size and same flags. <var>entsize</var> must be an |
| absolute expression. For sections with both <code>M</code> and <code>S</code>, a string |
| which is a suffix of a larger string is considered a duplicate. Thus |
| <code>"def"</code> will be merged with <code>"abcdef"</code>; A reference to the first |
| <code>"def"</code> will be changed to a reference to <code>"abcdef"+3</code>. |
| |
| <p>If <var>flags</var> contains the <code>G</code> symbol then the <var>type</var> argument must |
| be present along with an additional field like this: |
| |
| <pre class="smallexample"> .section <var>name</var> , "<var>flags</var>"G, @<var>type</var>, <var>GroupName</var>[, <var>linkage</var>] |
| </pre> |
| <p>The <var>GroupName</var> field specifies the name of the section group to which this |
| particular section belongs. The optional linkage field can contain: |
| |
| <dl> |
| <dt><code>comdat</code><dd>indicates that only one copy of this section should be retained |
| <br><dt><code>.gnu.linkonce</code><dd>an alias for comdat |
| </dl> |
| |
| <p>Note: if both the <var>M</var> and <var>G</var> flags are present then the fields for |
| the Merge flag should come first, like this: |
| |
| <pre class="smallexample"> .section <var>name</var> , "<var>flags</var>"MG, @<var>type</var>, <var>entsize</var>, <var>GroupName</var>[, <var>linkage</var>] |
| </pre> |
| <p>If <var>flags</var> contains the <code>?</code> symbol then it may not also contain the |
| <code>G</code> symbol and the <var>GroupName</var> or <var>linkage</var> fields should not be |
| present. Instead, <code>?</code> says to consider the section that's current before |
| this directive. If that section used <code>G</code>, then the new section will use |
| <code>G</code> with those same <var>GroupName</var> and <var>linkage</var> fields implicitly. |
| If not, then the <code>?</code> symbol has no effect. |
| |
| <p>If no flags are specified, the default flags depend upon the section name. If |
| the section name is not recognized, the default will be for the section to have |
| none of the above flags: it will not be allocated in memory, nor writable, nor |
| executable. The section will contain data. |
| |
| <p>For ELF targets, the assembler supports another type of <code>.section</code> |
| directive for compatibility with the Solaris assembler: |
| |
| <pre class="smallexample"> .section "<var>name</var>"[, <var>flags</var>...] |
| </pre> |
| <p>Note that the section name is quoted. There may be a sequence of comma |
| separated flags: |
| |
| <dl> |
| <dt><code>#alloc</code><dd>section is allocatable |
| <br><dt><code>#write</code><dd>section is writable |
| <br><dt><code>#execinstr</code><dd>section is executable |
| <br><dt><code>#exclude</code><dd>section is excluded from executable and shared library. |
| <br><dt><code>#tls</code><dd>section is used for thread local storage |
| </dl> |
| |
| <p>This directive replaces the current section and subsection. See the |
| contents of the gas testsuite directory <code>gas/testsuite/gas/elf</code> for |
| some examples of how this directive and the other section stack directives |
| work. |
| |
| </body></html> |
| |