]>
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 | .. _c++-attributes: | |
7 | ||
8 | C++-Specific Variable, Function, and Type Attributes | |
9 | **************************************************** | |
10 | ||
11 | Some attributes only make sense for C++ programs. | |
12 | ||
13 | .. index:: abi_tag function attribute, abi_tag variable attribute, abi_tag type attribute | |
14 | ||
15 | .. gcc-attr:: abi_tag ("tag", ...) | |
16 | ||
17 | The ``abi_tag`` attribute can be applied to a function, variable, or class | |
18 | declaration. It modifies the mangled name of the entity to | |
19 | incorporate the tag name, in order to distinguish the function or | |
20 | class from an earlier version with a different ABI; perhaps the class | |
21 | has changed size, or the function has a different return type that is | |
22 | not encoded in the mangled name. | |
23 | ||
24 | The attribute can also be applied to an inline namespace, but does not | |
25 | affect the mangled name of the namespace; in this case it is only used | |
26 | for :option:`-Wabi-tag` warnings and automatic tagging of functions and | |
27 | variables. Tagging inline namespaces is generally preferable to | |
28 | tagging individual declarations, but the latter is sometimes | |
29 | necessary, such as when only certain members of a class need to be | |
30 | tagged. | |
31 | ||
32 | The argument can be a list of strings of arbitrary length. The | |
33 | strings are sorted on output, so the order of the list is | |
34 | unimportant. | |
35 | ||
36 | A redeclaration of an entity must not add new ABI tags, | |
37 | since doing so would change the mangled name. | |
38 | ||
39 | The ABI tags apply to a name, so all instantiations and | |
40 | specializations of a template have the same tags. The attribute will | |
41 | be ignored if applied to an explicit specialization or instantiation. | |
42 | ||
43 | The :option:`-Wabi-tag` flag enables a warning about a class which does | |
44 | not have all the ABI tags used by its subobjects and virtual functions; for users with code | |
45 | that needs to coexist with an earlier ABI, using this option can help | |
46 | to find all affected types that need to be tagged. | |
47 | ||
48 | When a type involving an ABI tag is used as the type of a variable or | |
49 | return type of a function where that tag is not already present in the | |
50 | signature of the function, the tag is automatically applied to the | |
51 | variable or function. :option:`-Wabi-tag` also warns about this | |
52 | situation; this warning can be avoided by explicitly tagging the | |
53 | variable or function or moving it into a tagged inline namespace. | |
54 | ||
55 | .. index:: init_priority variable attribute | |
56 | ||
57 | .. gcc-attr:: init_priority (priority) | |
58 | ||
59 | In Standard C++, objects defined at namespace scope are guaranteed to be | |
60 | initialized in an order in strict accordance with that of their definitions | |
61 | *in a given translation unit*. No guarantee is made for initializations | |
62 | across translation units. However, GNU C++ allows users to control the | |
63 | order of initialization of objects defined at namespace scope with the | |
64 | ``init_priority`` attribute by specifying a relative :samp:`{priority}`, | |
65 | a constant integral expression currently bounded between 101 and 65535 | |
66 | inclusive. Lower numbers indicate a higher priority. | |
67 | ||
68 | In the following example, ``A`` would normally be created before | |
69 | ``B``, but the ``init_priority`` attribute reverses that order: | |
70 | ||
71 | .. code-block:: c++ | |
72 | ||
73 | Some_Class A __attribute__ ((init_priority (2000))); | |
74 | Some_Class B __attribute__ ((init_priority (543))); | |
75 | ||
76 | Note that the particular values of :samp:`{priority}` do not matter; only their | |
77 | relative ordering. | |
78 | ||
79 | .. index:: warn_unused type attribute | |
80 | ||
81 | .. gcc-attr:: warn_unused | |
82 | ||
83 | For C++ types with non-trivial constructors and/or destructors it is | |
84 | impossible for the compiler to determine whether a variable of this | |
85 | type is truly unused if it is not referenced. This type attribute | |
86 | informs the compiler that variables of this type should be warned | |
87 | about if they appear to be unused, just like variables of fundamental | |
88 | types. | |
89 | ||
90 | This attribute is appropriate for types which just represent a value, | |
91 | such as ``std::string`` ; it is not appropriate for types which | |
92 | control a resource, such as ``std::lock_guard``. | |
93 | ||
94 | This attribute is also accepted in C, but it is unnecessary because C | |
95 | does not have constructors or destructors. |