From: Joseph Myers Date: Sat, 27 Jan 2001 21:29:53 +0000 (+0000) Subject: * extend.texi (Attribute Syntax): New section. X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=2c5e91d224fa8c9434d4deda5f78e52ad4183965;p=platform%2Fupstream%2Fgcc.git * extend.texi (Attribute Syntax): New section. From-SVN: r39305 --- diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 739d967..ff12a3b 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,7 @@ +2001-01-27 Joseph S. Myers + + * extend.texi (Attribute Syntax): New section. + 2001-01-27 Michael Sokolov * fixproto: Correctly install synthesised unistd.h and stdlib.h when diff --git a/gcc/extend.texi b/gcc/extend.texi index 51a8ff0..0c42d95 100644 --- a/gcc/extend.texi +++ b/gcc/extend.texi @@ -56,6 +56,7 @@ C++ Language}, for extensions that apply @emph{only} to C++. * 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 @@ C++ Language}, for extensions that apply @emph{only} to C++. * 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 @@ each keyword. This allows you to use them in header files without 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 @@ attachment of attributes to their corresponding declarations, whereas 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 @@ each keyword. This allows you to use them in header files without 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}) @@ -2369,6 +2552,9 @@ brace of a definition. 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 @item aligned (@var{alignment})