diff options
Diffstat (limited to 'share/doc/gcc/Attribute-Syntax.html')
| -rw-r--r-- | share/doc/gcc/Attribute-Syntax.html | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/share/doc/gcc/Attribute-Syntax.html b/share/doc/gcc/Attribute-Syntax.html new file mode 100644 index 0000000..09f1fe3 --- /dev/null +++ b/share/doc/gcc/Attribute-Syntax.html @@ -0,0 +1,335 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Using the GNU Compiler Collection (GCC): Attribute Syntax</title> + +<meta name="description" content="Using the GNU Compiler Collection (GCC): Attribute Syntax"> +<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Attribute Syntax"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Indices.html#Indices" rel="index" title="Indices"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="C-Extensions.html#C-Extensions" rel="up" title="C Extensions"> +<link href="Function-Prototypes.html#Function-Prototypes" rel="next" title="Function Prototypes"> +<link href="Statement-Attributes.html#Statement-Attributes" rel="previous" title="Statement Attributes"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Attribute-Syntax"></a> +<div class="header"> +<p> +Next: <a href="Function-Prototypes.html#Function-Prototypes" accesskey="n" rel="next">Function Prototypes</a>, Previous: <a href="Statement-Attributes.html#Statement-Attributes" accesskey="p" rel="previous">Statement Attributes</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Attribute-Syntax-1"></a> +<h3 class="section">6.39 Attribute Syntax</h3> +<a name="index-attribute-syntax"></a> + +<p>This section describes the syntax with which <code>__attribute__</code> 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 +limitations in the grammar for attributes, some forms described here +may not be successfully parsed in all cases. +</p> +<p>There are some problems with the semantics of attributes in C++. For +example, there are no manglings for attributes, although they may affect +code generation, so problems may arise when attributed types are used in +conjunction with templates or overloading. Similarly, <code>typeid</code> +does not distinguish between types with different attributes. Support +for attributes in C++ may be restricted in future to attributes on +declarations only, but not on nested declarators. +</p> +<p>See <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>, for details of the semantics of attributes +applying to functions. See <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>, for details of the +semantics of attributes applying to variables. See <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>, +for details of the semantics of attributes applying to structure, union +and enumerated types. +See <a href="Label-Attributes.html#Label-Attributes">Label Attributes</a>, for details of the semantics of attributes +applying to labels. +See <a href="Enumerator-Attributes.html#Enumerator-Attributes">Enumerator Attributes</a>, for details of the semantics of attributes +applying to enumerators. +See <a href="Statement-Attributes.html#Statement-Attributes">Statement Attributes</a>, for details of the semantics of attributes +applying to statements. +</p> +<p>An <em>attribute specifier</em> is of the form +<code>__attribute__ ((<var>attribute-list</var>))</code>. An <em>attribute list</em> +is a possibly empty comma-separated sequence of <em>attributes</em>, where +each attribute is one of the following: +</p> +<ul> +<li> Empty. Empty attributes are ignored. + +</li><li> An attribute name +(which may be an identifier such as <code>unused</code>, or a reserved +word such as <code>const</code>). + +</li><li> An attribute name followed by a parenthesized list of +parameters for the attribute. +These parameters take one of the following forms: + +<ul> +<li> An identifier. For example, <code>mode</code> attributes use this form. + +</li><li> An identifier followed by a comma and a non-empty comma-separated list +of expressions. For example, <code>format</code> attributes use this form. + +</li><li> A possibly empty comma-separated list of expressions. For example, +<code>format_arg</code> attributes use this form with the list being a single +integer constant expression, and <code>alias</code> attributes use this form +with the list being a single string constant. +</li></ul> +</li></ul> + +<p>An <em>attribute specifier list</em> is a sequence of one or more attribute +specifiers, not separated by any other tokens. +</p> +<p>You may optionally specify attribute names with ‘<samp>__</samp>’ +preceding and following the name. +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 the attribute name <code>__noreturn__</code> instead of <code>noreturn</code>. +</p> + +<a name="Label-Attributes-2"></a> +<h4 class="subsubheading">Label Attributes</h4> + +<p>In GNU C, an attribute specifier list may appear after the colon following a +label, other than a <code>case</code> or <code>default</code> label. GNU C++ only permits +attributes on labels if the attribute specifier is immediately +followed by a semicolon (i.e., the label applies to an empty +statement). If the semicolon is missing, C++ label attributes are +ambiguous, as it is permissible for a declaration, which could begin +with an attribute list, to be labelled in C++. Declarations cannot be +labelled in C90 or C99, so the ambiguity does not arise there. +</p> +<a name="Enumerator-Attributes-2"></a> +<h4 class="subsubheading">Enumerator Attributes</h4> + +<p>In GNU C, an attribute specifier list may appear as part of an enumerator. +The attribute goes after the enumeration constant, before <code>=</code>, if +present. The optional attribute in the enumerator appertains to the +enumeration constant. It is not possible to place the attribute after +the constant expression, if present. +</p> +<a name="Statement-Attributes-2"></a> +<h4 class="subsubheading">Statement Attributes</h4> +<p>In GNU C, an attribute specifier list may appear as part of a null +statement. The attribute goes before the semicolon. +</p> +<a name="Type-Attributes-1"></a> +<h4 class="subsubheading">Type Attributes</h4> + +<p>An attribute specifier list may appear as part of a <code>struct</code>, +<code>union</code> or <code>enum</code> specifier. It may go either immediately +after the <code>struct</code>, <code>union</code> or <code>enum</code> keyword, or after +the closing brace. The former syntax is preferred. +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. +</p> + +<a name="All-other-attributes"></a> +<h4 class="subsubheading">All other attributes</h4> + +<p>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), or to a particular declarator +within a declaration. Where an +attribute specifier is applied to a parameter declared as a function or +an array, it should apply to the function or array rather than the +pointer to which the parameter is implicitly converted, but this is not +yet correctly implemented. +</p> +<p>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</code>.) 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 obsolescent usage where a type of +<code>int</code> 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. +</p> +<p>At present, the first parameter in a function prototype must have some +type specifier that is not an attribute specifier; this resolves an +ambiguity in the interpretation of <code>void f(int +(__attribute__((foo)) x))</code>, but is subject to change. At present, if +the parentheses of a function declarator contain only attributes then +those attributes are ignored, rather than yielding an error or warning +or implying a single parameter of type int, but this is subject to +change. +</p> +<p>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. Such attribute specifiers apply +only to the identifier before whose declarator they appear. For +example, in +</p> +<div class="smallexample"> +<pre class="smallexample">__attribute__((noreturn)) void d0 (void), + __attribute__((format(printf, 1, 2))) d1 (const char *, ...), + d2 (void); +</pre></div> + +<p>the <code>noreturn</code> attribute applies to all the functions +declared; the <code>format</code> attribute only applies to <code>d1</code>. +</p> +<p>An attribute specifier list may appear immediately before the comma, +<code>=</code> or semicolon terminating the declaration of an identifier other +than a function definition. Such attribute specifiers apply +to the declared object or function. Where an +assembler name for an object or function is specified (see <a href="Asm-Labels.html#Asm-Labels">Asm Labels</a>), the attribute must follow the <code>asm</code> +specification. +</p> +<p>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). +</p> +<p>Attribute specifiers may be mixed with type qualifiers appearing inside +the <code>[]</code> of a parameter array declarator, in the C99 construct by +which such qualifiers are applied to the pointer to which the array is +implicitly converted. Such attribute specifiers apply to the pointer, +not to the array, but at present this is not implemented and they are +ignored. +</p> +<p>An attribute specifier list may appear at the start of a nested +declarator. At present, there are some limitations in this usage: the +attributes correctly apply to the declarator, but for most individual +attributes the semantics this implies are not implemented. +When attribute specifiers follow the <code>*</code> of a pointer +declarator, they may be mixed with any type qualifiers present. +The following describes the formal semantics of this syntax. It makes the +most sense if you are familiar with the formal specification of +declarators in the ISO C standard. +</p> +<p>Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration <code>T +D1</code>, where <code>T</code> contains declaration specifiers that specify a type +<var>Type</var> (such as <code>int</code>) and <code>D1</code> is a declarator that +contains an identifier <var>ident</var>. The type specified for <var>ident</var> +for derived declarators whose type does not include an attribute +specifier is as in the ISO C standard. +</p> +<p>If <code>D1</code> has the form <code>( <var>attribute-specifier-list</var> D )</code>, +and the declaration <code>T D</code> specifies the type +“<var>derived-declarator-type-list</var> <var>Type</var>” for <var>ident</var>, then +<code>T D1</code> specifies the type “<var>derived-declarator-type-list</var> +<var>attribute-specifier-list</var> <var>Type</var>” for <var>ident</var>. +</p> +<p>If <code>D1</code> has the form <code>* +<var>type-qualifier-and-attribute-specifier-list</var> D</code>, and the +declaration <code>T D</code> specifies the type +“<var>derived-declarator-type-list</var> <var>Type</var>” for <var>ident</var>, then +<code>T D1</code> specifies the type “<var>derived-declarator-type-list</var> +<var>type-qualifier-and-attribute-specifier-list</var> pointer to <var>Type</var>” for +<var>ident</var>. +</p> +<p>For example, +</p> +<div class="smallexample"> +<pre class="smallexample">void (__attribute__((noreturn)) ****f) (void); +</pre></div> + +<p>specifies the type “pointer to pointer to pointer to pointer to +non-returning function returning <code>void</code>”. As another example, +</p> +<div class="smallexample"> +<pre class="smallexample">char *__attribute__((aligned(8))) *f; +</pre></div> + +<p>specifies the type “pointer to 8-byte-aligned pointer to <code>char</code>”. +Note again that this does not work with most attributes; for example, +the usage of ‘<samp>aligned</samp>’ and ‘<samp>noreturn</samp>’ attributes given above +is not yet supported. +</p> +<p>For compatibility with existing code written for compiler versions that +did not implement attributes on nested declarators, some laxity is +allowed in the placing of attributes. If an attribute that only applies +to types is applied to a declaration, it is treated as applying to +the type of that declaration. If an attribute that only applies to +declarations is applied to the type of a declaration, it is treated +as applying to that declaration; and, for compatibility with code +placing the attributes immediately before the identifier declared, such +an attribute applied to a function return type is treated as +applying to the function type, and such an attribute applied to an array +element type is treated as applying to the array type. If an +attribute that only applies to function types is applied to a +pointer-to-function type, it is treated as applying to the pointer +target type; if such an attribute is applied to a function return type +that is not a pointer-to-function type, it is treated as applying +to the function type. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Function-Prototypes.html#Function-Prototypes" accesskey="n" rel="next">Function Prototypes</a>, Previous: <a href="Statement-Attributes.html#Statement-Attributes" accesskey="p" rel="previous">Statement Attributes</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |