]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. index:: function attributes, declaring attributes of functions, volatile applied to function, const applied to function | |
7 | ||
8 | .. _function-attributes: | |
9 | ||
10 | Declaring Attributes of Functions | |
11 | ********************************* | |
12 | ||
13 | In GNU C and C++, you can use function attributes to specify certain | |
14 | function properties that may help the compiler optimize calls or | |
15 | check code more carefully for correctness. For example, you | |
16 | can use attributes to specify that a function never returns | |
17 | (:fn-attr:`noreturn`), returns a value depending only on the values of | |
18 | its arguments (``const``), or has ``printf`` -style arguments | |
19 | (``format``). | |
20 | ||
21 | You can also use attributes to control memory placement, code | |
22 | generation options or call/return conventions within the function | |
23 | being annotated. Many of these attributes are target-specific. For | |
24 | example, many targets support attributes for defining interrupt | |
25 | handler functions, which typically must follow special register usage | |
26 | and return conventions. Such attributes are described in the subsection | |
27 | for each target. However, a considerable number of attributes are | |
28 | supported by most, if not all targets. Those are described in | |
29 | the :ref:`common-function-attributes` section. | |
30 | ||
31 | Function attributes are introduced by the ``__attribute__`` keyword | |
32 | in the declaration of a function, followed by an attribute specification | |
33 | enclosed in double parentheses. You can specify multiple attributes in | |
34 | a declaration by separating them by commas within the double parentheses | |
35 | or by immediately following one attribute specification with another. | |
36 | See :ref:`attribute-syntax`, for the exact rules on attribute syntax and | |
37 | placement. Compatible attribute specifications on distinct declarations | |
38 | of the same function are merged. An attribute specification that is not | |
39 | compatible with attributes already applied to a declaration of the same | |
40 | function is ignored with a warning. | |
41 | ||
42 | Some function attributes take one or more arguments that refer to | |
43 | the function's parameters by their positions within the function parameter | |
44 | list. Such attribute arguments are referred to as :dfn:`positional arguments`. | |
45 | Unless specified otherwise, positional arguments that specify properties | |
46 | of parameters with pointer types can also specify the same properties of | |
47 | the implicit C++ ``this`` argument in non-static member functions, and | |
48 | of parameters of reference to a pointer type. For ordinary functions, | |
49 | position one refers to the first parameter on the list. In C++ non-static | |
50 | member functions, position one refers to the implicit ``this`` pointer. | |
51 | The same restrictions and effects apply to function attributes used with | |
52 | ordinary functions or C++ member functions. | |
53 | ||
54 | GCC also supports attributes on | |
55 | variable declarations (see :ref:`variable-attributes`), | |
56 | labels (see :ref:`label-attributes`), | |
57 | enumerators (see :ref:`enumerator-attributes`), | |
58 | statements (see :ref:`statement-attributes`), | |
59 | types (see :ref:`type-attributes`), | |
60 | and on field declarations (for :fn-attr:`tainted_args`). | |
61 | ||
62 | There is some overlap between the purposes of attributes and pragmas | |
63 | (see :ref:`pragmas`). It has been | |
64 | found convenient to use ``__attribute__`` to achieve a natural | |
65 | attachment of attributes to their corresponding declarations, whereas | |
66 | ``#pragma`` is of use for compatibility with other compilers | |
67 | or constructs that do not naturally form part of the grammar. | |
68 | ||
69 | In addition to the attributes documented here, | |
70 | GCC plugins may provide their own attributes. | |
71 | ||
72 | .. toctree:: | |
73 | :maxdepth: 1 | |
74 | ||
75 | declaring-attributes-of-functions/common-function-attributes | |
76 | declaring-attributes-of-functions/aarch64-function-attributes | |
77 | declaring-attributes-of-functions/amd-gcn-function-attributes | |
78 | declaring-attributes-of-functions/arc-function-attributes | |
79 | declaring-attributes-of-functions/arm-function-attributes | |
80 | declaring-attributes-of-functions/avr-function-attributes | |
81 | declaring-attributes-of-functions/blackfin-function-attributes | |
82 | declaring-attributes-of-functions/bpf-function-attributes | |
83 | declaring-attributes-of-functions/c-sky-function-attributes | |
84 | declaring-attributes-of-functions/epiphany-function-attributes | |
85 | declaring-attributes-of-functions/h8-300-function-attributes | |
86 | declaring-attributes-of-functions/ia-64-function-attributes | |
87 | declaring-attributes-of-functions/m32c-function-attributes | |
88 | declaring-attributes-of-functions/m32r-d-function-attributes | |
89 | declaring-attributes-of-functions/m68k-function-attributes | |
90 | declaring-attributes-of-functions/mcore-function-attributes | |
91 | declaring-attributes-of-functions/mep-function-attributes | |
92 | declaring-attributes-of-functions/microblaze-function-attributes | |
93 | declaring-attributes-of-functions/microsoft-windows-function-attributes | |
94 | declaring-attributes-of-functions/mips-function-attributes | |
95 | declaring-attributes-of-functions/msp430-function-attributes | |
96 | declaring-attributes-of-functions/nds32-function-attributes | |
97 | declaring-attributes-of-functions/nios-ii-function-attributes | |
98 | declaring-attributes-of-functions/nvidia-ptx-function-attributes | |
99 | declaring-attributes-of-functions/powerpc-function-attributes | |
100 | declaring-attributes-of-functions/risc-v-function-attributes | |
101 | declaring-attributes-of-functions/rl78-function-attributes | |
102 | declaring-attributes-of-functions/rx-function-attributes | |
103 | declaring-attributes-of-functions/s-390-function-attributes | |
104 | declaring-attributes-of-functions/sh-function-attributes | |
105 | declaring-attributes-of-functions/symbian-os-function-attributes | |
106 | declaring-attributes-of-functions/v850-function-attributes | |
107 | declaring-attributes-of-functions/visium-function-attributes | |
108 | declaring-attributes-of-functions/x86-function-attributes | |
109 | declaring-attributes-of-functions/xstormy16-function-attributes |