<html lang="en">
<head>
<title>Symbol Names - 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="Symbols.html#Symbols" title="Symbols">
<link rel="prev" href="Setting-Symbols.html#Setting-Symbols" title="Setting Symbols">
<link rel="next" href="Dot.html#Dot" title="Dot">
<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="Symbol-Names"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Dot.html#Dot">Dot</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Setting-Symbols.html#Setting-Symbols">Setting Symbols</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Symbols.html#Symbols">Symbols</a>
<hr>
</div>

<h3 class="section">5.3 Symbol Names</h3>

<p><a name="index-symbol-names-215"></a><a name="index-names_002c-symbol-216"></a>Symbol names begin with a letter or with one of &lsquo;<samp><span class="samp">._</span></samp>&rsquo;.  On most
machines, you can also use <code>$</code> in symbol names; exceptions are
noted in <a href="Machine-Dependencies.html#Machine-Dependencies">Machine Dependencies</a>.  That character may be followed by any
string of digits, letters, dollar signs (unless otherwise noted for a
particular target machine), and underscores.

   <p>Case of letters is significant: <code>foo</code> is a different symbol name
than <code>Foo</code>.

   <p>Symbol names do not start with a digit.  An exception to this rule is made for
Local Labels.  See below.

   <p>Multibyte characters are supported.  To generate a symbol name containing
multibyte characters enclose it within double quotes and use escape codes. cf
See <a href="Strings.html#Strings">Strings</a>.  Generating a multibyte symbol name from a label is not
currently supported.

   <p>Each symbol has exactly one name.  Each name in an assembly language program
refers to exactly one symbol.  You may use that symbol name any number of times
in a program.

<h4 class="subheading">Local Symbol Names</h4>

<p><a name="index-local-symbol-names-217"></a><a name="index-symbol-names_002c-local-218"></a>A local symbol is any symbol beginning with certain local label prefixes. 
By default, the local label prefix is &lsquo;<samp><span class="samp">.L</span></samp>&rsquo; for ELF systems or
&lsquo;<samp><span class="samp">L</span></samp>&rsquo; for traditional a.out systems, but each target may have its own
set of local label prefixes. 
On the HPPA local symbols begin with &lsquo;<samp><span class="samp">L$</span></samp>&rsquo;.

   <p>Local symbols are defined and used within the assembler, but they are
normally not saved in object files.  Thus, they are not visible when debugging. 
You may use the &lsquo;<samp><span class="samp">-L</span></samp>&rsquo; option (see <a href="L.html#L">Include Local Symbols</a>)
to retain the local symbols in the object files.

<h4 class="subheading">Local Labels</h4>

<p><a name="index-local-labels-219"></a><a name="index-temporary-symbol-names-220"></a><a name="index-symbol-names_002c-temporary-221"></a>Local labels are different from local symbols.  Local labels help compilers and
programmers use names temporarily.  They create symbols which are guaranteed to
be unique over the entire scope of the input source code and which can be
referred to by a simple notation.  To define a local label, write a label of
the form &lsquo;<samp><b>N</b><span class="samp">:</span></samp>&rsquo; (where <b>N</b> represents any non-negative integer). 
To refer to the most recent previous definition of that label write
&lsquo;<samp><b>N</b><span class="samp">b</span></samp>&rsquo;, using the same number as when you defined the label.  To refer
to the next definition of a local label, write &lsquo;<samp><b>N</b><span class="samp">f</span></samp>&rsquo;.  The &lsquo;<samp><span class="samp">b</span></samp>&rsquo;
stands for &ldquo;backwards&rdquo; and the &lsquo;<samp><span class="samp">f</span></samp>&rsquo; stands for &ldquo;forwards&rdquo;.

   <p>There is no restriction on how you can use these labels, and you can reuse them
too.  So that it is possible to repeatedly define the same local label (using
the same number &lsquo;<samp><b>N</b></samp>&rsquo;), although you can only refer to the most recently
defined local label of that number (for a backwards reference) or the next
definition of a specific local label for a forward reference.  It is also worth
noting that the first 10 local labels (&lsquo;<samp><b>0:</b></samp>&rsquo;<small class="dots">...</small>&lsquo;<samp><b>9:</b></samp>&rsquo;) are
implemented in a slightly more efficient manner than the others.

   <p>Here is an example:

<pre class="smallexample">     1:        branch 1f
     2:        branch 1b
     1:        branch 2f
     2:        branch 1b
</pre>
   <p>Which is the equivalent of:

<pre class="smallexample">     label_1:  branch label_3
     label_2:  branch label_1
     label_3:  branch label_4
     label_4:  branch label_3
</pre>
   <p>Local label names are only a notational device.  They are immediately
transformed into more conventional symbol names before the assembler uses them. 
The symbol names are stored in the symbol table, appear in error messages, and
are optionally emitted to the object file.  The names are constructed using
these parts:

     <dl>
<dt><em>local label prefix</em><dd>All local symbols begin with the system-specific local label prefix. 
Normally both <samp><span class="command">as</span></samp> and <code>ld</code> forget symbols
that start with the local label prefix.  These labels are
used for symbols you are never intended to see.  If you use the
&lsquo;<samp><span class="samp">-L</span></samp>&rsquo; option then <samp><span class="command">as</span></samp> retains these symbols in the
object file. If you also instruct <code>ld</code> to retain these symbols,
you may use them in debugging.

     <br><dt><var>number</var><dd>This is the number that was used in the local label definition.  So if the
label is written &lsquo;<samp><span class="samp">55:</span></samp>&rsquo; then the number is &lsquo;<samp><span class="samp">55</span></samp>&rsquo;.

     <br><dt><kbd>C-B</kbd><dd>This unusual character is included so you do not accidentally invent a symbol
of the same name.  The character has ASCII value of &lsquo;<samp><span class="samp">\002</span></samp>&rsquo; (control-B).

     <br><dt><em>ordinal number</em><dd>This is a serial number to keep the labels distinct.  The first definition of
&lsquo;<samp><span class="samp">0:</span></samp>&rsquo; gets the number &lsquo;<samp><span class="samp">1</span></samp>&rsquo;.  The 15th definition of &lsquo;<samp><span class="samp">0:</span></samp>&rsquo; gets the
number &lsquo;<samp><span class="samp">15</span></samp>&rsquo;, and so on.  Likewise the first definition of &lsquo;<samp><span class="samp">1:</span></samp>&rsquo; gets
the number &lsquo;<samp><span class="samp">1</span></samp>&rsquo; and its 15th definition gets &lsquo;<samp><span class="samp">15</span></samp>&rsquo; as well. 
</dl>

   <p>So for example, the first <code>1:</code> may be named <code>.L1</code><kbd>C-B</kbd><code>1</code>, and
the 44th <code>3:</code> may be named <code>.L3</code><kbd>C-B</kbd><code>44</code>.

<h4 class="subheading">Dollar Local Labels</h4>

<p><a name="index-dollar-local-symbols-222"></a>
On some targets <code>as</code> also supports an even more local form of
local labels called dollar labels.  These labels go out of scope (i.e., they
become undefined) as soon as a non-local label is defined.  Thus they remain
valid for only a small region of the input source code.  Normal local labels,
by contrast, remain in scope for the entire file, or until they are redefined
by another occurrence of the same local label.

   <p>Dollar labels are defined in exactly the same way as ordinary local labels,
except that they have a dollar sign suffix to their numeric value, e.g.,
&lsquo;<samp><b>55$:</b></samp>&rsquo;.

   <p>They can also be distinguished from ordinary local labels by their transformed
names which use ASCII character &lsquo;<samp><span class="samp">\001</span></samp>&rsquo; (control-A) as the magic character
to distinguish them from ordinary labels.  For example, the fifth definition of
&lsquo;<samp><span class="samp">6$</span></samp>&rsquo; may be named &lsquo;<samp><span class="samp">.L6</span><kbd>C-A</kbd><span class="samp">5</span></samp>&rsquo;.

   </body></html>