327 lines
16 KiB
HTML
327 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Copyright (C) 1988-2016 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.2, 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="Option-Index.html#Option-Index" rel="index" title="Option Index">
|
|
<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="Enumerator-Attributes.html#Enumerator-Attributes" rel="prev" title="Enumerator 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" 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="Enumerator-Attributes.html#Enumerator-Attributes" accesskey="p" rel="prev">Enumerator 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="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<a name="Attribute-Syntax-1"></a>
|
|
<h3 class="section">6.36 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
|
|
infelicities 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.
|
|
</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="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="Enumerator-Attributes.html#Enumerator-Attributes" accesskey="p" rel="prev">Enumerator 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="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|