[PATCH] gas/doc: clarify local label vs local symbol terminology

[Jan Beulich]

On 10.02.2026 05:37, Fangrui Song wrote:
> On Mon, Feb 9, 2026 at 12:07 AM Jan Beulich <jbeulich@suse.com> wrote:
>> On 08.02.2026 22:40, maskray@sourceware.org wrote:
>>> In ELF, "local symbols" refer to symbols of STB_LOCAL binding. The
>>> doc is inconsistent: while it uses "local symbol" in places like .local,
>>> "local symbols" are also used for .L-prefixed symbols (as determined by
>>> bfd_is_local_label).
>>>
>>> Rename "Local Symbol Names" to "Local Label Names" for .L-prefixed
>>> symbols,
>>
>> While I can certainly see where you're coming from, I fear "local label"
>> also has its downside: These "identifiers" can be used for more than just
>> "labels", and hence naming them "symbols" (of whatever sort) is imo more
>> appropriate.
>>
>> As .local is ELF-only anyway, how about adjusting the wording there, e.g.
>> to prefer STB_LOCAL where "local" is presently used?
> 
> Apart from the gas doc, I believe prevailing use of "local symbol"
> refers to the ELF STB_LOCAL binding, e.g.
> https://gabi.xinuos.com/elf/05-symtab.html
> "STB_LOCAL - Local symbols are not visible outside the object file
> containing their definition."
> 
> I don't get the downside of "local label" -  do you mean that .Lfoo in
> `call .Lfoo` should not be called "local label" because it is not of
> the `xxx:` form?

No, the use as an insn operand is still a label. But the use in e.g.
.equ is (imo) not.

>>> and rename "Local Labels" to "Numeric Local Labels" for
>>> N:/Nb/Nf numeric labels.
>>
>> Not sure "numeric" is helpful here, as this increases the disconnect from
>> naming within the assembler (where it's "FB labels").
>>
>>>  This makes the documentation consistent with
>>> BFD terminology and avoids confusion with ELF STB_LOCAL "local symbols".
>>
>> How does BFD terminology come into play here? Iirc "local symbols" is a
>> gas-internal concept; struct local_symbol doesn't reference any BFD
>> symbol.
> 
> OK, I am unfamiliar with gas internals. Just noticed that `colon` uses
> `local_symbol_make` under `bfd_is_local_label`.
> 
> The "local symbol" term appears across multiple object file formats
> (even if "external"/"non-external" are more formal). For example,
> 
> A COFF doc in 1987
> http://bitsavers.informatik.uni-stuttgart.de/pdf/motorola/sysv/MU43814PR_D2_System_V_68_Release_3_Programmers_Reference_Manual_Vol_2_198804/11_COFF.pdf
> describes F_LSYMS as "local symbols stripped from the file". ISTM It
> uses for "local symbols" for non-external symbols instead of those
> with a special prefix.
> 
> Mac OS X utilities also use "local symbol" for non-external symbols
> https://www.unix.com/man_page/osx/1/strip/
> 
> I think it would be nice for the public gas doc to use "local symbol"
> to refer to non-external symbols rather than L/.L symbols.

In which case we need a suitable alternative name. "Internal symbol"?

Jan