[doc] document variable attribute alias

Message ID a050c6a3-e1ce-1ee4-7c1d-20513518dd42@gmail.com
State New
Headers show
Series
  • [doc] document variable attribute alias
Related show

Commit Message

Martin Sebor July 31, 2019, 11:05 p.m.
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.

Comments

Sandra Loosemore Aug. 5, 2019, 3:45 a.m. | #1
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
Martin Sebor Aug. 5, 2019, 10:43 p.m. | #2
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
Sandra Loosemore Aug. 5, 2019, 11:30 p.m. | #3
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

Patch

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