Using as: Symbols

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. Symbols

Symbols are a central concept: the programmer uses symbols to name things, the linker uses symbols to link, and the debugger uses symbols to debug.

> Warning: `as` does not place symbols in the object file in the same order they were declared. This may break some debuggers.

> 5.1 Labels |  |
> 5.2 Giving Symbols Other Values |  |
> 5.3 Symbol Names |  |
> 5.4 The Special Dot Symbol |  |
> 5.5 Symbol Attributes |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.1 Labels

A label is written as a symbol immediately followed by a colon ``:'`. The symbol then represents the current value of the active location counter, and is, for example, a suitable instruction operand. You are warned if you use the same symbol to represent two different locations: the first definition overrides any other definitions.

On the HPPA, the usual form for a label need not be immediately followed by a colon, but instead must start in column zero. Only one label may be defined on a single line. To work around this, the HPPA version of `as` also provides a special directive `.label` for defining labels more flexibly.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.2 Giving Symbols Other Values

A symbol can be given an arbitrary value by writing a symbol, followed by an equals sign ``='`, followed by an expression (see section 6. Expressions). This is equivalent to using the `.set` directive. See section `.set`. In the same way, using a double equals sign ``='```='` here represents an equivalent of the `.eqv` directive. See section `.eqv`.

Blackfin does not support symbol assignment with ``='`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 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 9. Machine Dependent Features. 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`.

Multibyte characters are supported. To generate a symbol name containing multibyte characters enclose it within double quotes and use escape codes. cf See section 3.6.1.1 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 (see section Include Local Symbols: ``-L'`) to retain the local symbols in the object files.

### Local Labels

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 positive 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 `.L1`C-B`1`, and the 44th `3:` may be named `.L3`C-B`44`.

### Dollar Local Labels

`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'`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.4 The Special Dot Symbol

The special symbol ``.'` refers to the current address that `as` is assembling into. Thus, the expression ``melvin: .long .'` defines `melvin` to contain its own address. Assigning a value to `.` is treated the same as a `.org` directive. Thus, the expression ``.=.+4'` is the same as saying ``.space 4'`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.5 Symbol Attributes

Every symbol has, as well as its name, the attributes "Value" and "Type". Depending on output format, symbols can also have auxiliary attributes.

If you use a symbol without defining it, `as` assumes zero for all these attributes, and probably won't warn you. This makes the symbol an externally defined symbol, which is generally what you would want.

> 5.5.1 Value |  |
> 5.5.2 Type |  |
> 5.5.3 Symbol Attributes: `a.out` |  |
> 5.5.4 Symbol Attributes for COFF |  |
> 5.5.5 Symbol Attributes for SOM |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.1 Value

The value of a symbol is (usually) 32 bits. For a symbol which labels a location in the text, data, bss or absolute sections the value is the number of addresses from the start of that section to the label. Naturally for text, data and bss sections the value of a symbol changes as `ld` changes section base addresses during linking. Absolute symbols' values do not change during linking: that is why they are called absolute.

The value of an undefined symbol is treated in a special way. If it is 0 then the symbol is not defined in this assembler source file, and `ld` tries to determine its value from other files linked into the same program. You make this kind of symbol simply by mentioning a symbol name without defining it. A non-zero value represents a `.comm` common declaration. The value is how much common storage to reserve, in bytes (addresses). The symbol refers to the first address of the allocated storage.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.2 Type

The type attribute of a symbol contains relocation (section) information, any flag settings indicating that a symbol is external, and (optionally), other information for linkers and debuggers. The exact format depends on the object-code output format in use.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.3 Symbol Attributes: `a.out`

> 5.5.3.1 Descriptor |  |
> 5.5.3.2 Other |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 5.5.3.1 Descriptor

This is an arbitrary 16-bit value. You may establish a symbol's descriptor value by using a `.desc` statement (see section `.desc`). A descriptor value means nothing to `as`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 5.5.3.2 Other

This is an arbitrary 8-bit value. It means nothing to `as`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.4 Symbol Attributes for COFF

The COFF format supports a multitude of auxiliary symbol attributes; like the primary symbol attributes, they are set between `.def` and `.endef` directives.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 5.5.4.1 Primary Attributes

The symbol name is set with `.def`; the value and type, respectively, with `.val` and `.type`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 5.5.4.2 Auxiliary Attributes

The `as` directives `.dim`, `.line`, `.scl`, `.size`, `.tag`, and `.weak` can generate auxiliary symbol table information for COFF.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.5.5 Symbol Attributes for SOM

The SOM format for the HPPA supports a multitude of symbol attributes set with the `.EXPORT` and `.IMPORT` directives.

The attributes are described in HP9000 Series 800 Assembly Language Reference Manual (HP 92432-90001) under the `IMPORT` and `EXPORT` assembler directive documentation.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 10 2014 using texi2html