Patch to document __attribute__ syntax

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

This patch attempts to document the syntax of attribute usage for C,
and what attributes in different places mean, while I have some grasp
of the C parser.  (I haven't attempted to make sense of how they work
in the C++ parser, or whether the same or different problems apply
there.)  This partly addresses Debian bug#12253
(http://bugs.debian.org/12253), but

(a) documents the problems with attribute syntax (see projects page),
and what I think the syntax ought to be and mean, as much as the
currently working syntax and its limitations (though it does attempt
to describe those); and

(b) doesn't add the `obvious' syntax described in that bug report for
attributes on function definitions, though it does document that
syntax for future use.

It passes "make info" and "make dvi".  OK to commit?

2001-01-23  Joseph S. Myers  <jsm28@cam.ac.uk>

	* extend.texi (Attribute Syntax): New section.

--- extend.texi.orig	Sat Jan 13 17:31:39 2001
+++ extend.texi	Tue Jan 23 01:20:32 2001
@@ -56,6 +56,7 @@
 * Case Ranges::		`case 1 ... 9' and such.
 * Function Attributes:: Declaring that functions have no side effects,
                          or that they can never return.
+* Attribute Syntax::    Formal syntax for attributes.
 * Function Prototypes:: Prototype declarations and old-style definitions.
 * C++ Comments::        C++ comments are recognized.
 * Dollar Signs::        Dollar sign is allowed in identifiers.
@@ -105,6 +106,7 @@
 * Case Ranges::		`case 1 ... 9' and such.
 * Function Attributes:: Declaring that functions have no side effects,
                          or that they can never return.
+* Attribute Syntax::    Formal syntax for attributes.
 * Function Prototypes:: Prototype declarations and old-style definitions.
 * C++ Comments::        C++ comments are recognized.
 * Dollar Signs::        Dollar sign is allowed in identifiers.
@@ -1505,6 +1507,9 @@
 being concerned about a possible macro of the same name.  For example,
 you may use @code{__noreturn__} instead of @code{noreturn}.

+@xref{Attribute Syntax}, for details of the exact syntax for using
+attributes.
+
 @table @code
 @cindex @code{noreturn} function attribute
 @item noreturn
@@ -1979,6 +1984,181 @@
 part of the grammar.  @xref{Other Directives,,Miscellaneous
 Preprocessing Directives, cpp, The C Preprocessor}.

+@node Attribute Syntax
+@section Attribute Syntax
+@cindex attribute syntax
+
+This section describes the syntax with which @code{__attribute__} may be
+used, and the constructs to which attribute specifiers bind, for the C
+language.  Some details may vary for C++ and Objective C.  Because of
+infelicities in the grammar for attributes, some forms described here
+may not be successfully parsed in all cases.
+
+@xref{Function Attributes}, for details of the semantics of attributes
+applying to functions.  @xref{Variable Attributes}, for details of the
+semantics of attributes applying to variables.  @xref{Type Attributes},
+for details of the semantics of attributes applying to structure, union
+and enumerated types.
+
+An @dfn{attribute specifier} is of the form
+@code{__attribute__ ((@var{attribute-list}))}.  An @dfn{attribute list}
+is a possibly empty comma-separated sequence of @dfn{attributes}, where
+each attribute is one of the following:
+
+@itemize @bullet
+@item
+Empty.  Empty attributes are ignored.
+
+@item
+A word (which may be an identifier such as @code{unused}, or a reserved
+word such as @code{const}).
+
+@item
+A word, followed by, in parentheses, parameters for the attribute.
+These parameters take one of the following forms:
+
+@itemize @bullet
+@item
+An identifier.  For example, @code{mode} attributes use this form.
+
+@item
+An identifier followed by a comma and a non-empty comma-separated list
+of expressions.  For example, @code{format} attributes use this form.
+
+@item
+A possibly empty comma-separated list of expressions.  For example,
+@code{format_arg} attributes use this form with the list being a single
+integer constant expression, and @code{alias} attributes use this form
+with the list being a single string constant.
+@end itemize
+@end itemize
+
+An @dfn{attribute specifier list} is a sequence of one or more attribute
+specifiers, not separated by any other tokens.
+
+An attribute specifier list may appear after the colon following a
+label, other than a @code{case} or @code{default} label.  The only
+attribute it makes sense to use after a label is @code{unused}.  This
+feature is intended for code generated by programs which contains labels
+that may be unused but which is compiled with @option{-Wall}.  It would
+not normally be appropriate to use in it human-written code, though it
+could be useful in cases where the code that jumps to the label is
+contained within an @code{#ifdef} conditional.
+
+An attribute specifier list may appear as part of a @code{struct},
+@code{union} or @code{enum} specifier.  It may go either immediately
+after the @code{struct}, @code{union} or @code{enum} keyword, or after
+the closing brace.  It is ignored if the content of the structure, union
+or enumerated type is not defined in the specifier in which the
+attribute specifier list is used---that is, in usages such as
+@code{struct __attribute__((foo)) bar} with no following opening brace.
+Where attribute specifiers follow the closing brace, they are considered
+to relate to the structure, union or enumerated type defined, not to any
+enclosing declaration the type specifier appears in, and the type
+defined is not complete until after the attribute specifiers.
+@c Otherwise, there would be the following problems: a shift/reduce
+@c conflict between attributes binding the the struct/union/enum and
+@c binding to the list of specifiers/qualifiers; and "aligned"
+@c attributes could use sizeof for the structure, but the size could be
+@c changed later by "packed" attributes.
+
+Otherwise, an attribute specifier appears as part of a declaration,
+counting declarations of unnamed parameters and type names, and relates
+to that declaration (which may be nested in another declaration, for
+example in the case of a parameter declaration).  In future, attribute
+specifiers in some places may however apply to a particular declarator
+within a declaration instead; these cases are noted below.
+
+Any list of specifiers and qualifiers at the start of a declaration may
+contain attribute specifiers, whether or not such a list may in that
+context contain storage class specifiers.  (Some attributes, however,
+are essentially in the nature of storage class specifiers, and only make
+sense where storage class specifiers may be used; for example,
+@code{section}.)  There is one necessary limitation to this syntax: the
+first old-style parameter declaration in a function definition cannot
+begin with an attribute specifier, because such an attribute applies to
+the function instead by syntax described below (which, however, is not
+yet implemented in this case).  In some other cases, attribute
+specifiers are permitted by this grammar but not yet supported by the
+compiler.  All attribute specifiers in this place relate to the
+declaration as a whole.  In the obsolencent usage where a type of
+@code{int} is implied by the absence of type specifiers, such a list of
+specifiers and qualifiers may be an attribute specifier list with no
+other specifiers or qualifiers.
+
+An attribute specifier list may appear immediately before a declarator
+(other than the first) in a comma-separated list of declarators in a
+declaration of more than one identifier using a single list of
+specifiers and qualifiers.  At present, such attribute specifiers apply
+not only to the identifier before whose declarator they appear, but to
+all subsequent identifiers declared in that declaration, but in future
+they may apply only to that single identifier.  For example, in
+@code{__attribute__((noreturn)) void d0 (void),
+__attribute__((format(printf, 1, 2))) d1 (const char *, ...), d2
+(void)}, the @code{noreturn} attribute applies to all the functions
+declared; the @code{format} attribute should only apply to @code{d1},
+but at present applies to @code{d2} as well (and so causes an error).
+
+An attribute specifier list may appear immediately before the comma,
+@code{=} or semicolon terminating the declaration of an identifier other
+than a function definition.  At present, such attribute specifiers apply
+to the declared object or function, but in future they may attach to the
+outermost adjacent declarator.  In simple cases there is no difference,
+but, for example, in @code{void (****f)(void)
+__attribute__((noreturn));}, at present the @code{noreturn} attribute
+applies to @code{f}, which causes a warning since @code{f} is not a
+function, but in future it may apply to the function @code{****f}.  The
+precise semantics of what attributes in such cases will apply to are not
+yet specified.  Where an assembler name for an object or function is
+specified (@pxref{Asm Labels}), at present the attribute must follow the
+@code{asm} specification; in future, attributes before the @code{asm}
+specification may apply to the adjacent declarator, and those after it
+to the declared object or function.
+
+An attribute specifier list may, in future, be permitted to appear after
+the declarator in a function definition (before any old-style parameter
+declarations or the function body).
+
+An attribute specifier list may appear at the start of a nested
+declarator.  At present, there are some limitations in this usage: the
+attributes apply to the identifer declared, and to all subsequent
+identifiers declared in that declaration (if it includes a
+comma-separated list of declarators), rather than to a specific
+declarator.  When attribute specifiers follow the @code{*} of a pointer
+declarator, they must presently follow any type qualifiers present, and
+cannot be mixed with them.  The following describes intended future
+semantics which make this syntax more useful only.  It will make the
+most sense if you are familiar with the formal specification of
+declarators in the ISO C standard.
+
+Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
+D1}, where @code{T} contains declaration specifiers that specify a type
+@var{Type} (such as @code{int}) and @code{D1} is a declarator that
+contains an identifier @var{ident}.  The type specified for @var{ident}
+for derived declarators whose type does not include an attribute
+specifier is as in the ISO C standard.
+
+If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
+and the declaration @code{T D} specifies the type
+``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
+@code{T D1} specifies the type ``@var{derived-declarator-type-list}
+@var{attribute-specifier-list} @var{Type}'' for @var{ident}.
+
+If @code{D1} has the form @code{*
+@var{type-qualifier-and-attribute-specifier-list} D}, and the
+declaration @code{T D} specifies the type
+``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
+@code{T D1} specifies the type ``@var{derived-declarator-type-list}
+@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for
+@var{ident}.
+
+For example, @code{void (__attribute__((noreturn)) ****f)();} specifies
+the type ``pointer to pointer to pointer to pointer to non-returning
+function returning @code{void}''.  As another example, @code{char
+*__attribute__((aligned(8))) *f;} specifies the type ``pointer to
+8-byte-aligned pointer to @code{char}''.  Note again that this describes
+intended future semantics, not current implementation.
+
 @node Function Prototypes
 @section Prototypes and Old-Style Function Definitions
 @cindex function prototype declarations
@@ -2129,6 +2309,9 @@
 being concerned about a possible macro of the same name.  For example,
 you may use @code{__aligned__} instead of @code{aligned}.

+@xref{Attribute Syntax}, for details of the exact syntax for using
+attributes.
+
 @table @code
 @cindex @code{aligned} attribute
 @item aligned (@var{alignment})
@@ -2368,6 +2551,9 @@

 You may also specify attributes between the enum, struct or union
 tag and the name of the type rather than after the closing brace.
+
+@xref{Attribute Syntax}, for details of the exact syntax for using
+attributes.

 @table @code
 @cindex @code{aligned} attribute

-- 
Joseph S. Myers
jsm28@cam.ac.uk