On 2/13/20 3:55 PM, Sandra Loosemore wrote:
On 2/5/20 1:13 PM, Martin Sebor wrote:
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index ec99c38a607..3634ce1c423 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2557,8 +2557,11 @@ __attribute__ ((access (write_only, 1, 2),
access (read_write, 3))) int fgets (c
@item alias ("@var{target}")
@cindex @code{alias} function attribute
-The @code{alias} attribute causes the declaration to be emitted as an
-alias for another symbol, which must be specified. For instance,
+The @code{alias} attribute causes the declaration to be emitted as an
alias
+for another symbol, which must have been previously declared with the
same
+type, and for variables same size and alignment. Declaring an alias
with
+a different type than the target is undefined and may be diagnosed. For
+instance, an alias for another symbol, which must be specified. For
instance,
@smallexample
void __f () @{ /* @r{Do something.} */; @}
This is kind of garbled. Do you have an extraneous sentence beginning
"For instance" in there? It doesn't flow from the text you added before
that.
That does look garbled. I've fixed that in the revised patch.
@@ -3919,31 +3922,41 @@ results in warning on line 5.
@item weak
@cindex @code{weak} function attribute
-The @code{weak} attribute causes the declaration to be emitted as a weak
-symbol rather than a global. This is primarily useful in defining
-library functions that can be overridden in user code, though it can
-also be used with non-function declarations. Weak symbols are supported
-for ELF targets, and also for a.out targets when using the GNU assembler
-and linker.
+The @code{weak} attribute causes a declaration of an external symbol
+to be emitted as a weak symbol rather than a global. This is primarily
+useful in defining library functions that can be overridden in user
code,
+though it can also be used with non-function declarations. The
overriding
+symbol must have the same type, and for variables size, and alignment as
+the weak symbol. Weak symbols are supported for ELF targets, and
also for
+a.out targets when using the GNU assembler and linker.
The "for variables" clause is awkward and has a comma in the wrong
place. I'd split this into a separate sentence, like
The overriding symbol must have the same type as the weak symbol. If it
is a variable it must also have the same size and alignment.
Agreed, that looks better.
@item weakref
@itemx weakref ("@var{target}")
@cindex @code{weakref} function attribute
The @code{weakref} attribute marks a declaration as a weak reference.
Without arguments, it should be accompanied by an @code{alias} attribute
-naming the target symbol. Optionally, the @var{target} may be given as
-an argument to @code{weakref} itself. In either case, @code{weakref}
-implicitly marks the declaration as @code{weak}. Without a
-@var{target}, given as an argument to @code{weakref} or to @code{alias},
-@code{weakref} is equivalent to @code{weak}.
+naming the target symbol. Alernatively, @var{target} may be given as
s/Alernatively/Alternatively/
+an argument to @code{weakref} itself, naming the target definition of
+the alias. The the @var{target} must have the same type, and for
s/The the/The/
+variables also the same size and alignment as the declaration. In
either
Same comments above re splitting this into two sentences to avoid
awkward wording.
I've spit it up into multiple sentences as you suggested. Attached
is the updated revision that I plan to commit unless you (or anyone
else) have further suggestions.
Thanks for the review!
Martin
The rest of this patch looks OK.
-Sandra
gcc/ChangeLog:
* doc/extend.texi (attribute alias): Mention type requirement
(attribute weak): Same.
(attribute weakref): Correct invalid example.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 5739063b330..b7f462a76b0 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -2557,8 +2557,11 @@ __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (c
@item alias ("@var{target}")
@cindex @code{alias} function attribute
-The @code{alias} attribute causes the declaration to be emitted as an
-alias for another symbol, which must be specified. For instance,
+The @code{alias} attribute causes the declaration to be emitted as an alias
+for another symbol, which must have been previously declared with the same
+type, and for variables, also the same size and alignment. Declaring an alias
+with a different type than the target is undefined and may be diagnosed. As
+an example, the following declarations:
@smallexample
void __f () @{ /* @r{Do something.} */; @}
@@ -2566,9 +2569,9 @@ void f () __attribute__ ((weak, alias ("__f")));
@end smallexample
@noindent
-defines @samp{f} to be a weak alias for @samp{__f}. In C++, the
-mangled name for the target must be used. It is an error if @samp{__f}
-is not defined in the same translation unit.
+define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
+for the target must be used. It is an error if @samp{__f} is not defined in
+the same translation unit.
This attribute requires assembler and object file support,
and may not be available on all targets.
@@ -3919,31 +3922,43 @@ results in warning on line 5.
@item weak
@cindex @code{weak} function attribute
-The @code{weak} attribute causes the declaration to be emitted as a weak
-symbol rather than a global. This is primarily useful in defining
-library functions that can be overridden in user code, though it can
-also be used with non-function declarations. Weak symbols are supported
-for ELF targets, and also for a.out targets when using the GNU assembler
-and linker.
+The @code{weak} attribute causes a declaration of an external symbol
+to be emitted as a weak symbol rather than a global. This is primarily
+useful in defining library functions that can be overridden in user code,
+though it can also be used with non-function declarations. The overriding
+symbol must have the same type as the weak symbol. In addition, if it
+designates a variable it must also have the same size and alignment as
+the weak symbol. Weak symbols are supported for ELF targets, and also
+for a.out targets when using the GNU assembler and linker.
@item weakref
@itemx weakref ("@var{target}")
@cindex @code{weakref} function attribute
The @code{weakref} attribute marks a declaration as a weak reference.
Without arguments, it should be accompanied by an @code{alias} attribute
-naming the target symbol. Optionally, the @var{target} may be given as
-an argument to @code{weakref} itself. In either case, @code{weakref}
-implicitly marks the declaration as @code{weak}. Without a
-@var{target}, given as an argument to @code{weakref} or to @code{alias},
-@code{weakref} is equivalent to @code{weak}.
+naming the target symbol. Alternatively, @var{target} may be given as
+an argument to @code{weakref} itself, naming the target definition of
+the alias. The @var{target} must have the same type as the declaration.
+In addition, if it designates a variable it must also have the same size
+and alignment as the declaration. In either form of the declaration
+@code{weakref} implicitly marks the declared symbol as @code{weak}. Without
+a @var{target} given as an argument to @code{weakref} or to @code{alias},
+@code{weakref} is equivalent to @code{weak} (in that case the declaration
+may be @code{extern}).
@smallexample
-static int x() __attribute__ ((weakref ("y")));
+/* Given the declaration: */
+extern int y (void);
+
+/* the following... */
+static int x (void) __attribute__ ((weakref ("y")));
+
/* is equivalent to... */
-static int x() __attribute__ ((weak, weakref, alias ("y")));
-/* and to... */
-static int x() __attribute__ ((weakref));
-static int x() __attribute__ ((alias ("y")));
+static int x (void) __attribute__ ((weakref, alias ("y")));
+
+/* or, alternatively, to... */
+static int x (void) __attribute__ ((weakref));
+static int x (void) __attribute__ ((alias ("y")));
@end smallexample
A weak reference is an alias that does not by itself require a
@@ -3956,10 +3971,10 @@ symbol, not necessarily in the same translation unit.
The effect is equivalent to moving all references to the alias to a
separate translation unit, renaming the alias to the aliased symbol,
declaring it as weak, compiling the two separate translation units and
-performing a link with relocatable output (ie: @code{ld -r}) on them.
+performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
-At present, a declaration to which @code{weakref} is attached can
-only be @code{static}.
+A declaration to which @code{weakref} is attached and that is associated
+with a named @code{target} must be @code{static}.
@end table
