[doc PATCH] document variable attribute alias

[doc PATCH] document variable attribute alias

[Martin Sebor]

[-- Attachment #1: Type: text/plain, Size: 1041 bytes --]

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.

[-- Attachment #2: gcc-alias-var-attr.diff --]
[-- Type: text/x-patch, Size: 1489 bytes --]

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})

Re: [doc PATCH] document variable attribute alias

[Sandra Loosemore]

On 7/31/19 5:05 PM, Martin Sebor wrote:
> 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

One minor nit:

> +@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.


Please use @noindent on the continuation of the sentence after the @end 
smallexample.

OK with that fixed.

-Sandra

Re: [doc PATCH] document variable attribute alias

[Martin Sebor]

On 8/4/19 9:45 PM, Sandra Loosemore wrote:
> On 7/31/19 5:05 PM, Martin Sebor wrote:
>> 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
> 
> One minor nit:
> 
>> +@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.
> 
> 
> Please use @noindent on the continuation of the sentence after the @end 
> smallexample.
> 
> OK with that fixed.

Done in r274127.

Since people tend to refer to the manual for older versions
of the compiler I'd like to make this change on supported
release branches as well.  If you see any problem with it
please let me know, otherwise I'll go ahead later this week.

Thanks
Martin

Re: [doc PATCH] document variable attribute alias

[Sandra Loosemore]

On 8/5/19 4:43 PM, Martin Sebor wrote:
> On 8/4/19 9:45 PM, Sandra Loosemore wrote:
>> [snip]
>>
>> OK with that fixed.
> 
> Done in r274127.
> 
> Since people tend to refer to the manual for older versions
> of the compiler I'd like to make this change on supported
> release branches as well.  If you see any problem with it
> please let me know, otherwise I'll go ahead later this week.

OK with me.  My understanding is that backporting documentation fixes is 
always allowed unless the branch is frozen.

-Sandra