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: Symbol Names</title> 17 18<meta name="description" content="Using as: Symbol Names"> 19<meta name="keywords" content="Using as: Symbol Names"> 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="Symbols.html#Symbols" rel="up" title="Symbols"> 28<link href="Dot.html#Dot" rel="next" title="Dot"> 29<link href="Setting-Symbols.html#Setting-Symbols" rel="previous" title="Setting Symbols"> 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="Symbol-Names"></a> 64<div class="header"> 65<p> 66Next: <a href="Dot.html#Dot" accesskey="n" rel="next">Dot</a>, Previous: <a href="Setting-Symbols.html#Setting-Symbols" accesskey="p" rel="previous">Setting Symbols</a>, Up: <a href="Symbols.html#Symbols" accesskey="u" rel="up">Symbols</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="Symbol-Names-1"></a> 70<h3 class="section">5.3 Symbol Names</h3> 71 72<a name="index-symbol-names"></a> 73<a name="index-names_002c-symbol"></a> 74<p>Symbol names begin with a letter or with one of ‘<samp>._</samp>’. On most 75machines, you can also use <code>$</code> in symbol names; exceptions are 76noted in <a href="Machine-Dependencies.html#Machine-Dependencies">Machine Dependencies</a>. That character may be followed by any 77string of digits, letters, dollar signs (unless otherwise noted for a 78particular target machine), and underscores. 79</p> 80<p>Case of letters is significant: <code>foo</code> is a different symbol name 81than <code>Foo</code>. 82</p> 83<p>Symbol names do not start with a digit. An exception to this rule is made for 84Local Labels. See below. 85</p> 86<p>Multibyte characters are supported. To generate a symbol name containing 87multibyte characters enclose it within double quotes and use escape codes. cf 88See <a href="Strings.html#Strings">Strings</a>. Generating a multibyte symbol name from a label is not 89currently supported. 90</p> 91<p>Each symbol has exactly one name. Each name in an assembly language program 92refers to exactly one symbol. You may use that symbol name any number of times 93in a program. 94</p> 95<a name="Local-Symbol-Names"></a> 96<h4 class="subheading">Local Symbol Names</h4> 97 98<a name="index-local-symbol-names"></a> 99<a name="index-symbol-names_002c-local"></a> 100<p>A local symbol is any symbol beginning with certain local label prefixes. 101By default, the local label prefix is ‘<samp>.L</samp>’ for ELF systems or 102‘<samp>L</samp>’ for traditional a.out systems, but each target may have its own 103set of local label prefixes. 104On the HPPA local symbols begin with ‘<samp>L$</samp>’. 105</p> 106<p>Local symbols are defined and used within the assembler, but they are 107normally not saved in object files. Thus, they are not visible when debugging. 108You may use the ‘<samp>-L</samp>’ option (see <a href="L.html#L">Include Local Symbols</a>) 109to retain the local symbols in the object files. 110</p> 111<a name="Local-Labels-1"></a> 112<h4 class="subheading">Local Labels</h4> 113 114<a name="index-local-labels"></a> 115<a name="index-temporary-symbol-names"></a> 116<a name="index-symbol-names_002c-temporary"></a> 117<p>Local labels are different from local symbols. Local labels help compilers and 118programmers use names temporarily. They create symbols which are guaranteed to 119be unique over the entire scope of the input source code and which can be 120referred to by a simple notation. To define a local label, write a label of 121the form ‘<samp><b>N</b>:</samp>’ (where <b>N</b> represents any non-negative integer). 122To refer to the most recent previous definition of that label write 123‘<samp><b>N</b>b</samp>’, using the same number as when you defined the label. To refer 124to the next definition of a local label, write ‘<samp><b>N</b>f</samp>’. The ‘<samp>b</samp>’ 125stands for “backwards” and the ‘<samp>f</samp>’ stands for “forwards”. 126</p> 127<p>There is no restriction on how you can use these labels, and you can reuse them 128too. So that it is possible to repeatedly define the same local label (using 129the same number ‘<samp><b>N</b></samp>’), although you can only refer to the most recently 130defined local label of that number (for a backwards reference) or the next 131definition of a specific local label for a forward reference. It is also worth 132noting that the first 10 local labels (‘<samp><b>0:</b></samp>’…‘<samp><b>9:</b></samp>’) are 133implemented in a slightly more efficient manner than the others. 134</p> 135<p>Here is an example: 136</p> 137<div class="smallexample"> 138<pre class="smallexample">1: branch 1f 1392: branch 1b 1401: branch 2f 1412: branch 1b 142</pre></div> 143 144<p>Which is the equivalent of: 145</p> 146<div class="smallexample"> 147<pre class="smallexample">label_1: branch label_3 148label_2: branch label_1 149label_3: branch label_4 150label_4: branch label_3 151</pre></div> 152 153<p>Local label names are only a notational device. They are immediately 154transformed into more conventional symbol names before the assembler uses them. 155The symbol names are stored in the symbol table, appear in error messages, and 156are optionally emitted to the object file. The names are constructed using 157these parts: 158</p> 159<dl compact="compact"> 160<dt><code><em>local label prefix</em></code></dt> 161<dd><p>All local symbols begin with the system-specific local label prefix. 162Normally both <code>as</code> and <code>ld</code> forget symbols 163that start with the local label prefix. These labels are 164used for symbols you are never intended to see. If you use the 165‘<samp>-L</samp>’ option then <code>as</code> retains these symbols in the 166object file. If you also instruct <code>ld</code> to retain these symbols, 167you may use them in debugging. 168</p> 169</dd> 170<dt><code><var>number</var></code></dt> 171<dd><p>This is the number that was used in the local label definition. So if the 172label is written ‘<samp>55:</samp>’ then the number is ‘<samp>55</samp>’. 173</p> 174</dd> 175<dt><code><kbd>C-B</kbd></code></dt> 176<dd><p>This unusual character is included so you do not accidentally invent a symbol 177of the same name. The character has ASCII value of ‘<samp>\002</samp>’ (control-B). 178</p> 179</dd> 180<dt><code><em>ordinal number</em></code></dt> 181<dd><p>This is a serial number to keep the labels distinct. The first definition of 182‘<samp>0:</samp>’ gets the number ‘<samp>1</samp>’. The 15th definition of ‘<samp>0:</samp>’ gets the 183number ‘<samp>15</samp>’, and so on. Likewise the first definition of ‘<samp>1:</samp>’ gets 184the number ‘<samp>1</samp>’ and its 15th definition gets ‘<samp>15</samp>’ as well. 185</p></dd> 186</dl> 187 188<p>So for example, the first <code>1:</code> may be named <code>.L1<kbd>C-B</kbd>1</code>, and 189the 44th <code>3:</code> may be named <code>.L3<kbd>C-B</kbd>44</code>. 190</p> 191<a name="Dollar-Local-Labels"></a> 192<h4 class="subheading">Dollar Local Labels</h4> 193<a name="index-dollar-local-symbols"></a> 194 195<p>On some targets <code>as</code> also supports an even more local form of 196local labels called dollar labels. These labels go out of scope (i.e., they 197become undefined) as soon as a non-local label is defined. Thus they remain 198valid for only a small region of the input source code. Normal local labels, 199by contrast, remain in scope for the entire file, or until they are redefined 200by another occurrence of the same local label. 201</p> 202<p>Dollar labels are defined in exactly the same way as ordinary local labels, 203except that they have a dollar sign suffix to their numeric value, e.g., 204‘<samp><b>55$:</b></samp>’. 205</p> 206<p>They can also be distinguished from ordinary local labels by their transformed 207names which use ASCII character ‘<samp>\001</samp>’ (control-A) as the magic character 208to distinguish them from ordinary labels. For example, the fifth definition of 209‘<samp>6$</samp>’ may be named ‘<samp>.L6<kbd>C-A</kbd>5</samp>’. 210</p> 211<hr> 212<div class="header"> 213<p> 214Next: <a href="Dot.html#Dot" accesskey="n" rel="next">Dot</a>, Previous: <a href="Setting-Symbols.html#Setting-Symbols" accesskey="p" rel="previous">Setting Symbols</a>, Up: <a href="Symbols.html#Symbols" accesskey="u" rel="up">Symbols</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> 215</div> 216 217 218 219</body> 220</html> 221