extend.texi (aligned): Expand attribute description.

gcc/ChangeLog:

	* doc/extend.texi (aligned): Expand attribute description.
	(Alignment): Rename section.  Discuss function arguments.

From-SVN: r265498

gcc/ChangeLog

+2018-10-25  Martin Sebor  <msebor@redhat.com>
+
+	* doc/extend.texi (aligned): Expand attribute description.
+	(Alignment): Rename section.  Discuss function arguments.
+
 2018-10-25  Jan Hubicka  <jh@suse.cz>
 
 	* ipa-devirt.c (main_odr_variant): Remove.

gcc/doc/extend.texi

@@ -66,7 +66,7 @@ extensions, accepted by GCC in C90 mode and in C++.
 * C++ Comments::        C++ comments are recognized.
 * Dollar Signs::        Dollar sign is allowed in identifiers.
 * Character Escapes::   @samp{\e} stands for the character @key{ESC}.
-* Alignment::           Inquiring about the alignment of a type or variable.
+* Alignment::           Determining the alignment of a function, type or variable.
 * Inline::              Defining inline functions (as fast as macros).
 * Volatiles::           What constitutes an access to a volatile object.
 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
@@ -2380,10 +2380,14 @@ is not defined in the same translation unit.
 This attribute requires assembler and object file support,
 and may not be available on all targets.
 
-@item aligned (@var{alignment})
+@item aligned
+@itemx aligned (@var{alignment})
 @cindex @code{aligned} function attribute
-This attribute specifies a minimum alignment for the function,
-measured in bytes.
+The @code{aligned} attribute specifies a minimum alignment for
+the function, measured in bytes.  When specified, @var{alignment} must
+be an integer constant power of 2.  Specifying no @var{alignment} argument
+implies the maximum alignment for the target, which is often, but by no
+means always, 8 or 16 bytes.
 
 You cannot use this attribute to decrease the alignment of a function,
 only to increase it.  However, when you explicitly specify a function
@@ -6016,9 +6020,15 @@ The following attributes are supported on most targets.
 
 @table @code
 @cindex @code{aligned} variable attribute
-@item aligned (@var{alignment})
-This attribute specifies a minimum alignment for the variable or
-structure field, measured in bytes.  For example, the declaration:
+@item aligned
+@itemx aligned (@var{alignment})
+The @code{aligned} attribute specifies a minimum alignment for the variable
+or structure field, measured in bytes.  When specified, @var{alignment} must
+be an integer constant power of 2.  Specifying no @var{alignment} argument
+implies the maximum alignment for the target, which is often, but by no
+means always, 8 or 16 bytes.
+
+For example, the declaration:
 
 @smallexample
 int x __attribute__ ((aligned (16))) = 0;
@@ -6945,9 +6955,13 @@ The following type attributes are supported on most targets.
 
 @table @code
 @cindex @code{aligned} type attribute
-@item aligned (@var{alignment})
-This attribute specifies a minimum alignment (in bytes) for variables
-of the specified type.  For example, the declarations:
+@item aligned
+@itemx aligned (@var{alignment})
+The @code{aligned} attribute specifies a minimum alignment (in bytes) for
+variables of the specified type.  When specified, @var{alignment} must be
+a power of 2.  Specifying no @var{alignment} argument implies the maximum
+alignment for the target, which is often, but by no means always, 8 or 16
+bytes.  For example, the declarations:
 
 @smallexample
 struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
@@ -7944,29 +7958,29 @@ You can use the sequence @samp{\e} in a string or character constant to
 stand for the ASCII character @key{ESC}.
 
 @node Alignment
-@section Inquiring on Alignment of Types or Variables
+@section Determining the Alignment of Functions, Types or Variables
 @cindex alignment
 @cindex type alignment
 @cindex variable alignment
 
-The keyword @code{__alignof__} allows you to inquire about how an object
-is aligned, or the minimum alignment usually required by a type.  Its
-syntax is just like @code{sizeof}.
+The keyword @code{__alignof__} determines the alignment requirement of
+a function, object, or a type, or the minimum alignment usually required
+by a type.  Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
 
 For example, if the target machine requires a @code{double} value to be
 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
 This is true on many RISC machines.  On more traditional machine
 designs, @code{__alignof__ (double)} is 4 or even 2.
 
-Some machines never actually require alignment; they allow reference to any
+Some machines never actually require alignment; they allow references to any
 data type even at an odd address.  For these machines, @code{__alignof__}
 reports the smallest alignment that GCC gives the data type, usually as
 mandated by the target ABI.
 
 If the operand of @code{__alignof__} is an lvalue rather than a type,
 its value is the required alignment for its type, taking into account
-any minimum alignment specified with GCC's @code{__attribute__}
-extension (@pxref{Variable Attributes}).  For example, after this
+any minimum alignment specified by attribute @code{aligned}
+(@pxref{Common Variable Attributes}).  For example, after this
 declaration:
 
 @smallexample
@@ -7976,9 +7990,12 @@ struct foo @{ int x; char y; @} foo1;
 @noindent
 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
+It is an error to ask for the alignment of an incomplete type other
+than @code{void}.
 
-It is an error to ask for the alignment of an incomplete type.
-
+If the operand of the @code{__alignof__} expression is a function,
+the expression evaluates to the alignment of the function which may
+be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
 
 @node Inline
 @section An Inline Function is As Fast As a Macro