as: Symbol Names
5.3 Symbol Names
================
Symbol names begin with a letter or with one of '._'. On most machines,
you can also use '$' in symbol names; exceptions are noted in
Machine Dependencies. That character may be followed by any string of
digits, letters, dollar signs (unless otherwise noted for a particular
target machine), and underscores.
Case of letters is significant: 'foo' is a different symbol name than
'Foo'.
Symbol names do not start with a digit. An exception to this rule is
made for Local Labels. See below.
Multibyte characters are supported. To generate a symbol name
containing multibyte characters enclose it within double quotes and use
escape codes. cf Strings. Generating a multibyte symbol name
from a label is not currently supported.
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.
Local Symbol Names
------------------
A local symbol is any symbol beginning with certain local label
prefixes. By default, the local label prefix is '.L' for ELF systems or
'L' for traditional a.out systems, but each target may have its own set
of local label prefixes. On the HPPA local symbols begin with 'L$'.
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 '-L' option (Include Local Symbols
L.) to retain the local symbols in the object files.
Local Labels
------------
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 'N:' (where N represents
any non-negative integer). To refer to the most recent previous
definition of that label write 'Nb', using the same number as when you
defined the label. To refer to the next definition of a local label,
write 'Nf'. The 'b' stands for "backwards" and the 'f' stands for
"forwards".
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 'N'), 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 ('0:'...'9:') are implemented in a slightly more efficient manner
than the others.
Here is an example:
1: branch 1f
2: branch 1b
1: branch 2f
2: branch 1b
Which is the equivalent of:
label_1: branch label_3
label_2: branch label_1
label_3: branch label_4
label_4: branch label_3
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:
'_local label prefix_'
All local symbols begin with the system-specific local label
prefix. Normally both 'as' and 'ld' 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 '-L' option then 'as'
retains these symbols in the object file. If you also instruct
'ld' to retain these symbols, you may use them in debugging.
'NUMBER'
This is the number that was used in the local label definition. So
if the label is written '55:' then the number is '55'.
'C-B'
This unusual character is included so you do not accidentally
invent a symbol of the same name. The character has ASCII value of
'\002' (control-B).
'_ordinal number_'
This is a serial number to keep the labels distinct. The first
definition of '0:' gets the number '1'. The 15th definition of
'0:' gets the number '15', and so on. Likewise the first
definition of '1:' gets the number '1' and its 15th definition gets
'15' as well.
So for example, the first '1:' may be named '.L1C-B1', and the 44th
'3:' may be named '.L3C-B44'.
Dollar Local Labels
-------------------
On some targets 'as' 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.
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., '55$:'.
They can also be distinguished from ordinary local labels by their
transformed names which use ASCII character '\001' (control-A) as the
magic character to distinguish them from ordinary labels. For example,
the fifth definition of '6$' may be named '.L6'C-A'5'.