It was pointed out recently in another forum that GCC doesn't
document attribute alias for variables. It was also noted in
the same discussion that the semantics of accessing aliases
and their targets can have "surprising" effects because GCC
(as do other compilers) assumes that distinct declarations
with external linkage denote distinct entities.
The attached patch adds text to the manual describing attribute
alias for variables and pointing out the caveat of accessing
the same object using both the alias and the target.
Martin
PS Unlike for function aliases where type mismatches have been
diagnosed by -Wattribute-alias since 8.1, GCC doesn't complain
when the the type of an alias target variable doesn't match that
of its aliases. Except for top-level qualifiers where it might
make sense to allow the target to be less qualified than
the alias (similarly as with const pointers to non-const objects
or with C++ const references), I assume it's just an oversight.
I will try to look into diagnosing these mismatches as well.
gcc/ChangeLog:
* doc/extend.texi (Common Variable Attributes): Document alias
attribute.
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 273914)
+++ gcc/doc/extend.texi (working copy)
@@ -6719,6 +6719,32 @@ attributes.
The following attributes are supported on most targets.
@table @code
+
+@item alias ("@var{target}")
+@cindex @code{alias} variable attribute
+The @code{alias} variable attribute causes the declaration to be emitted
+as an alias for another symbol known as an @dfn{alias target}. Except
+for top-level qualifiers the alias target must have the same type as
+the alias. For instance, the following
+
+@smallexample
+int var_target;
+extern int __attribute__ ((alias ("var_target"))) var_alias;
+@end smallexample
+
+defines @code{var_alias} to be an alias for the @code{var_target} variable.
+
+It is an error if the alias target is not defined in the same translation
+unit as the alias.
+
+Note that in the absence of the attribute GCC assumes that distinct
+declarations with external linkage denote distinct objects. Using both
+the alias and the alias target to access the same object is undefined
+in a translation unit without a declaration of the alias with the attribute.
+
+This attribute requires assembler and object file support, and may not be
+available on all targets.
+
@cindex @code{aligned} variable attribute
@item aligned
@itemx aligned (@var{alignment})
