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

[Fangrui Song]

Resend to ensure the message goes to binutils@sourceware.org.
Apologies to Jan for the duplicate message (I used @sourceware.org as
a sender which is blocked by sourceware.org
(https://sourceware.org/bugzilla/show_bug.cgi?id=33906))

On Tue, Feb 10, 2026 at 12:10 AM Jan Beulich <jbeulich@suse.com> wrote:
>
> 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

I think "internal symbol" works. It avoids the STB_LOCAL ambiguity and
moves beyond labels (`.equ .Lxxx, 3` doesn't involve a "label").
GCC uses ASM_GENERATE_INTERNAL_LABEL as the macro to produce
.L-prefixed symbols.

While there is still potential confusion with ELF STV_INTERNAL linkage
(only used by SGI for their link-time interprocedural optimization per
https://groups.google.com/g/generic-abi/c/AahK3BVmYWQ/m/oylW2Jkvpy0J ;
identical to STV_HIDDEN for most implementations I think), I think
that is acceptable.

Another alternative is "temporary symbol", used by the LLVM integrated
assembler.