-..\r
- -------------------------------------------------------------------\r
- NOTE: This file is automatically generated by running clang-tblgen\r
- -gen-attr-docs. Do not edit this file by hand!!\r
- -------------------------------------------------------------------\r
-\r
-===================\r
-Attributes in Clang\r
-===================\r
-.. contents::\r
- :local:\r
-\r
-Introduction\r
-============\r
-\r
-This page lists the attributes currently supported by Clang.\r
-\r
-Function Attributes\r
-===================\r
-\r
-\r
-interrupt\r
----------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on\r
-ARM targets. This attribute may be attached to a function definition and\r
-instructs the backend to generate appropriate function entry/exit code so that\r
-it can be used directly as an interrupt service routine.\r
-\r
-The parameter passed to the interrupt attribute is optional, but if\r
-provided it must be a string literal with one of the following values: "IRQ",\r
-"FIQ", "SWI", "ABORT", "UNDEF".\r
-\r
-The semantics are as follows:\r
-\r
-- If the function is AAPCS, Clang instructs the backend to realign the stack to\r
- 8 bytes on entry. This is a general requirement of the AAPCS at public\r
- interfaces, but may not hold when an exception is taken. Doing this allows\r
- other AAPCS functions to be called.\r
-- If the CPU is M-class this is all that needs to be done since the architecture\r
- itself is designed in such a way that functions obeying the normal AAPCS ABI\r
- constraints are valid exception handlers.\r
-- If the CPU is not M-class, the prologue and epilogue are modified to save all\r
- non-banked registers that are used, so that upon return the user-mode state\r
- will not be corrupted. Note that to avoid unnecessary overhead, only\r
- general-purpose (integer) registers are saved in this way. If VFP operations\r
- are needed, that state must be saved manually.\r
-\r
- Specifically, interrupt kinds other than "FIQ" will save all core registers\r
- except "lr" and "sp". "FIQ" interrupts will save r0-r7.\r
-- If the CPU is not M-class, the return instruction is changed to one of the\r
- canonical sequences permitted by the architecture for exception return. Where\r
- possible the function itself will make the necessary "lr" adjustments so that\r
- the "preferred return address" is selected.\r
-\r
- Unfortunately the compiler is unable to make this guarantee for an "UNDEF"\r
- handler, where the offset from "lr" to the preferred return address depends on\r
- the execution state of the code which generated the exception. In this case\r
- a sequence equivalent to "movs pc, lr" will be used.\r
-\r
-\r
-acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)\r
------------------------------------------------------------------------------------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-Marks a function as acquiring a capability.\r
-\r
-\r
-assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)\r
--------------------------------------------------------------------------------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-Marks a function that dynamically tests whether a capability is held, and halts\r
-the program if it is not held.\r
-\r
-\r
-availability\r
-------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-The ``availability`` attribute can be placed on declarations to describe the\r
-lifecycle of that declaration relative to operating system versions. Consider\r
-the function declaration for a hypothetical function ``f``:\r
-\r
-.. code-block:: c++\r
-\r
- void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));\r
-\r
-The availability attribute states that ``f`` was introduced in Mac OS X 10.4,\r
-deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information\r
-is used by Clang to determine when it is safe to use ``f``: for example, if\r
-Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``\r
-succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call\r
-succeeds but Clang emits a warning specifying that the function is deprecated.\r
-Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call\r
-fails because ``f()`` is no longer available.\r
-\r
-The availability attribute is a comma-separated list starting with the\r
-platform name and then including clauses specifying important milestones in the\r
-declaration's lifetime (in any order) along with additional information. Those\r
-clauses can be:\r
-\r
-introduced=\ *version*\r
- The first version in which this declaration was introduced.\r
-\r
-deprecated=\ *version*\r
- The first version in which this declaration was deprecated, meaning that\r
- users should migrate away from this API.\r
-\r
-obsoleted=\ *version*\r
- The first version in which this declaration was obsoleted, meaning that it\r
- was removed completely and can no longer be used.\r
-\r
-unavailable\r
- This declaration is never available on this platform.\r
-\r
-message=\ *string-literal*\r
- Additional message text that Clang will provide when emitting a warning or\r
- error about use of a deprecated or obsoleted declaration. Useful to direct\r
- users to replacement APIs.\r
-\r
-Multiple availability attributes can be placed on a declaration, which may\r
-correspond to different platforms. Only the availability attribute with the\r
-platform corresponding to the target platform will be used; any others will be\r
-ignored. If no availability attribute specifies availability for the current\r
-target platform, the availability attributes are ignored. Supported platforms\r
-are:\r
-\r
-``ios``\r
- Apple's iOS operating system. The minimum deployment target is specified by\r
- the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``\r
- command-line arguments.\r
-\r
-``macosx``\r
- Apple's Mac OS X operating system. The minimum deployment target is\r
- specified by the ``-mmacosx-version-min=*version*`` command-line argument.\r
-\r
-A declaration can be used even when deploying back to a platform version prior\r
-to when the declaration was introduced. When this happens, the declaration is\r
-`weakly linked\r
-<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,\r
-as if the ``weak_import`` attribute were added to the declaration. A\r
-weakly-linked declaration may or may not be present a run-time, and a program\r
-can determine whether the declaration is present by checking whether the\r
-address of that declaration is non-NULL.\r
-\r
-If there are multiple declarations of the same entity, the availability\r
-attributes must either match on a per-platform basis or later\r
-declarations must not have availability attributes for that\r
-platform. For example:\r
-\r
-.. code-block:: c\r
-\r
- void g(void) __attribute__((availability(macosx,introduced=10.4)));\r
- void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches\r
- void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform\r
- void g(void); // okay, inherits both macosx and ios availability from above.\r
- void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch\r
-\r
-When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:\r
-\r
-.. code-block:: objc\r
-\r
- @interface A\r
- - (id)method __attribute__((availability(macosx,introduced=10.4)));\r
- - (id)method2 __attribute__((availability(macosx,introduced=10.4)));\r
- @end\r
-\r
- @interface B : A\r
- - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later\r
- - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4\r
- @end\r
-\r
-\r
-_Noreturn\r
----------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "","","","X"\r
-\r
-A function declared as ``_Noreturn`` shall not return to its caller. The\r
-compiler will generate a diagnostic for a function declared as ``_Noreturn``\r
-that appears to be capable of returning to its caller.\r
-\r
-\r
-noreturn\r
---------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "","X","",""\r
-\r
-A function declared as ``[[noreturn]]`` shall not return to its caller. The\r
-compiler will generate a diagnostic for a function declared as ``[[noreturn]]``\r
-that appears to be capable of returning to its caller.\r
-\r
-\r
-carries_dependency\r
-------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-The ``carries_dependency`` attribute specifies dependency propagation into and\r
-out of functions.\r
-\r
-When specified on a function or Objective-C method, the ``carries_depedency``\r
-attribute means that the return value carries a dependency out of the function, \r
-so that the implementation need not constrain ordering upon return from that\r
-function. Implementations of the function and its caller may choose to preserve\r
-dependencies instead of emitting memory ordering instructions such as fences.\r
-\r
-Note, this attribute does not change the meaning of the program, but may result\r
-in generatation of more efficient code.\r
-\r
-\r
-enable_if\r
----------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-The ``enable_if`` attribute can be placed on function declarations to control\r
-which overload is selected based on the values of the function's arguments.\r
-When combined with the ``overloadable`` attribute, this feature is also\r
-available in C.\r
-\r
-.. code-block:: c++\r
-\r
- int isdigit(int c);\r
- int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));\r
- \r
- void foo(char c) {\r
- isdigit(c);\r
- isdigit(10);\r
- isdigit(-10); // results in a compile-time error.\r
- }\r
-\r
-The enable_if attribute takes two arguments, the first is an expression written\r
-in terms of the function parameters, the second is a string explaining why this\r
-overload candidate could not be selected to be displayed in diagnostics. The\r
-expression is part of the function signature for the purposes of determining\r
-whether it is a redeclaration (following the rules used when determining\r
-whether a C++ template specialization is ODR-equivalent), but is not part of\r
-the type.\r
-\r
-The enable_if expression is evaluated as if it were the body of a\r
-bool-returning constexpr function declared with the arguments of the function\r
-it is being applied to, then called with the parameters at the callsite. If the\r
-result is false or could not be determined through constant expression\r
-evaluation, then this overload will not be chosen and the provided string may\r
-be used in a diagnostic if the compile fails as a result.\r
-\r
-Because the enable_if expression is an unevaluated context, there are no global\r
-state changes, nor the ability to pass information from the enable_if\r
-expression to the function body. For example, suppose we want calls to\r
-strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of\r
-strbuf) only if the size of strbuf can be determined:\r
-\r
-.. code-block:: c++\r
-\r
- __attribute__((always_inline))\r
- static inline size_t strnlen(const char *s, size_t maxlen)\r
- __attribute__((overloadable))\r
- __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),\r
- "chosen when the buffer size is known but 'maxlen' is not")))\r
- {\r
- return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));\r
- }\r
-\r
-Multiple enable_if attributes may be applied to a single declaration. In this\r
-case, the enable_if expressions are evaluated from left to right in the\r
-following manner. First, the candidates whose enable_if expressions evaluate to\r
-false or cannot be evaluated are discarded. If the remaining candidates do not\r
-share ODR-equivalent enable_if expressions, the overload resolution is\r
-ambiguous. Otherwise, enable_if overload resolution continues with the next\r
-enable_if attribute on the candidates that have not been discarded and have\r
-remaining enable_if attributes. In this way, we pick the most specific\r
-overload out of a number of viable overloads using enable_if.\r
-\r
-.. code-block:: c++\r
-\r
- void f() __attribute__((enable_if(true, ""))); // #1\r
- void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2\r
- \r
- void g(int i, int j) __attribute__((enable_if(i, ""))); // #1\r
- void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2\r
-\r
-In this example, a call to f() is always resolved to #2, as the first enable_if\r
-expression is ODR-equivalent for both declarations, but #1 does not have another\r
-enable_if expression to continue evaluating, so the next round of evaluation has\r
-only a single candidate. In a call to g(1, 1), the call is ambiguous even though\r
-#2 has more enable_if attributes, because the first enable_if expressions are\r
-not ODR-equivalent.\r
-\r
-Query for this feature with ``__has_attribute(enable_if)``.\r
-\r
-\r
-format (gnu::format)\r
---------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-Clang supports the ``format`` attribute, which indicates that the function\r
-accepts a ``printf`` or ``scanf``-like format string and corresponding\r
-arguments or a ``va_list`` that contains these arguments.\r
-\r
-Please see `GCC documentation about format attribute\r
-<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details\r
-about attribute syntax.\r
-\r
-Clang implements two kinds of checks with this attribute.\r
-\r
-#. Clang checks that the function with the ``format`` attribute is called with\r
- a format string that uses format specifiers that are allowed, and that\r
- arguments match the format string. This is the ``-Wformat`` warning, it is\r
- on by default.\r
-\r
-#. Clang checks that the format string argument is a literal string. This is\r
- the ``-Wformat-nonliteral`` warning, it is off by default.\r
-\r
- Clang implements this mostly the same way as GCC, but there is a difference\r
- for functions that accept a ``va_list`` argument (for example, ``vprintf``).\r
- GCC does not emit ``-Wformat-nonliteral`` warning for calls to such\r
- fuctions. Clang does not warn if the format string comes from a function\r
- parameter, where the function is annotated with a compatible attribute,\r
- otherwise it warns. For example:\r
-\r
- .. code-block:: c\r
-\r
- __attribute__((__format__ (__scanf__, 1, 3)))\r
- void foo(const char* s, char *buf, ...) {\r
- va_list ap;\r
- va_start(ap, buf);\r
-\r
- vprintf(s, ap); // warning: format string is not a string literal\r
- }\r
-\r
- In this case we warn because ``s`` contains a format string for a\r
- ``scanf``-like function, but it is passed to a ``printf``-like function.\r
-\r
- If the attribute is removed, clang still warns, because the format string is\r
- not a string literal.\r
-\r
- Another example:\r
-\r
- .. code-block:: c\r
-\r
- __attribute__((__format__ (__printf__, 1, 3)))\r
- void foo(const char* s, char *buf, ...) {\r
- va_list ap;\r
- va_start(ap, buf);\r
-\r
- vprintf(s, ap); // warning\r
- }\r
-\r
- In this case Clang does not warn because the format string ``s`` and\r
- the corresponding arguments are annotated. If the arguments are\r
- incorrect, the caller of ``foo`` will receive a warning.\r
-\r
-\r
-noduplicate (clang::noduplicate)\r
---------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-The ``noduplicate`` attribute can be placed on function declarations to control\r
-whether function calls to this function can be duplicated or not as a result of\r
-optimizations. This is required for the implementation of functions with\r
-certain special requirements, like the OpenCL "barrier" function, that might\r
-need to be run concurrently by all the threads that are executing in lockstep\r
-on the hardware. For example this attribute applied on the function\r
-"nodupfunc" in the code below avoids that:\r
-\r
-.. code-block:: c\r
-\r
- void nodupfunc() __attribute__((noduplicate));\r
- // Setting it as a C++11 attribute is also valid\r
- // void nodupfunc() [[clang::noduplicate]];\r
- void foo();\r
- void bar();\r
-\r
- nodupfunc();\r
- if (a > n) {\r
- foo();\r
- } else {\r
- bar();\r
- }\r
-\r
-gets possibly modified by some optimizations into code similar to this:\r
-\r
-.. code-block:: c\r
-\r
- if (a > n) {\r
- nodupfunc();\r
- foo();\r
- } else {\r
- nodupfunc();\r
- bar();\r
- }\r
-\r
-where the call to "nodupfunc" is duplicated and sunk into the two branches\r
-of the condition.\r
-\r
-\r
-no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)\r
------------------------------------------------------------------------------------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-.. _langext-address_sanitizer:\r
-\r
-Use ``__attribute__((no_sanitize_address))`` on a function declaration to\r
-specify that address safety instrumentation (e.g. AddressSanitizer) should\r
-not be applied to that function.\r
-\r
-\r
-no_sanitize_memory\r
-------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-.. _langext-memory_sanitizer:\r
-\r
-Use ``__attribute__((no_sanitize_memory))`` on a function declaration to\r
-specify that checks for uninitialized memory should not be inserted \r
-(e.g. by MemorySanitizer). The function may still be instrumented by the tool\r
-to avoid false positives in other places.\r
-\r
-\r
-no_sanitize_thread\r
-------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-.. _langext-thread_sanitizer:\r
-\r
-Use ``__attribute__((no_sanitize_thread))`` on a function declaration to\r
-specify that checks for data races on plain (non-atomic) memory accesses should\r
-not be inserted by ThreadSanitizer. The function is still instrumented by the\r
-tool to avoid false positives and provide meaningful stack traces.\r
-\r
-\r
-objc_method_family\r
-------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Many methods in Objective-C have conventional meanings determined by their\r
-selectors. It is sometimes useful to be able to mark a method as having a\r
-particular conventional meaning despite not having the right selector, or as\r
-not having the conventional meaning that its selector would suggest. For these\r
-use cases, we provide an attribute to specifically describe the "method family"\r
-that a method belongs to.\r
-\r
-**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of\r
-``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This\r
-attribute can only be placed at the end of a method declaration:\r
-\r
-.. code-block:: objc\r
-\r
- - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));\r
-\r
-Users who do not wish to change the conventional meaning of a method, and who\r
-merely want to document its non-standard retain and release semantics, should\r
-use the retaining behavior attributes (``ns_returns_retained``,\r
-``ns_returns_not_retained``, etc).\r
-\r
-Query for this feature with ``__has_attribute(objc_method_family)``.\r
-\r
-\r
-objc_requires_super\r
--------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Some Objective-C classes allow a subclass to override a particular method in a\r
-parent class but expect that the overriding method also calls the overridden\r
-method in the parent class. For these cases, we provide an attribute to\r
-designate that a method requires a "call to ``super``" in the overriding\r
-method in the subclass.\r
-\r
-**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only\r
-be placed at the end of a method declaration:\r
-\r
-.. code-block:: objc\r
-\r
- - (void)foo __attribute__((objc_requires_super));\r
-\r
-This attribute can only be applied the method declarations within a class, and\r
-not a protocol. Currently this attribute does not enforce any placement of\r
-where the call occurs in the overriding method (such as in the case of\r
-``-dealloc`` where the call must appear at the end). It checks only that it\r
-exists.\r
-\r
-Note that on both OS X and iOS that the Foundation framework provides a\r
-convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this\r
-attribute:\r
-\r
-.. code-block:: objc\r
-\r
- - (void)foo NS_REQUIRES_SUPER;\r
-\r
-This macro is conditionally defined depending on the compiler's support for\r
-this attribute. If the compiler does not support the attribute the macro\r
-expands to nothing.\r
-\r
-Operationally, when a method has this annotation the compiler will warn if the\r
-implementation of an override in a subclass does not call super. For example:\r
-\r
-.. code-block:: objc\r
-\r
- warning: method possibly missing a [super AnnotMeth] call\r
- - (void) AnnotMeth{};\r
- ^\r
-\r
-\r
-overloadable\r
-------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Clang provides support for C++ function overloading in C. Function overloading\r
-in C is introduced using the ``overloadable`` attribute. For example, one\r
-might provide several overloaded versions of a ``tgsin`` function that invokes\r
-the appropriate standard function computing the sine of a value with ``float``,\r
-``double``, or ``long double`` precision:\r
-\r
-.. code-block:: c\r
-\r
- #include <math.h>\r
- float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }\r
- double __attribute__((overloadable)) tgsin(double x) { return sin(x); }\r
- long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }\r
-\r
-Given these declarations, one can call ``tgsin`` with a ``float`` value to\r
-receive a ``float`` result, with a ``double`` to receive a ``double`` result,\r
-etc. Function overloading in C follows the rules of C++ function overloading\r
-to pick the best overload given the call arguments, with a few C-specific\r
-semantics:\r
-\r
-* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a\r
- floating-point promotion (per C99) rather than as a floating-point conversion\r
- (as in C++).\r
-\r
-* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is\r
- considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are\r
- compatible types.\r
-\r
-* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``\r
- and ``U`` are compatible types. This conversion is given "conversion" rank.\r
-\r
-The declaration of ``overloadable`` functions is restricted to function\r
-declarations and definitions. Most importantly, if any function with a given\r
-name is given the ``overloadable`` attribute, then all function declarations\r
-and definitions with that name (and in that scope) must have the\r
-``overloadable`` attribute. This rule even applies to redeclarations of\r
-functions whose original declaration had the ``overloadable`` attribute, e.g.,\r
-\r
-.. code-block:: c\r
-\r
- int f(int) __attribute__((overloadable));\r
- float f(float); // error: declaration of "f" must have the "overloadable" attribute\r
-\r
- int g(int) __attribute__((overloadable));\r
- int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute\r
-\r
-Functions marked ``overloadable`` must have prototypes. Therefore, the\r
-following code is ill-formed:\r
-\r
-.. code-block:: c\r
-\r
- int h() __attribute__((overloadable)); // error: h does not have a prototype\r
-\r
-However, ``overloadable`` functions are allowed to use a ellipsis even if there\r
-are no named parameters (as is permitted in C++). This feature is particularly\r
-useful when combined with the ``unavailable`` attribute:\r
-\r
-.. code-block:: c++\r
-\r
- void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error\r
-\r
-Functions declared with the ``overloadable`` attribute have their names mangled\r
-according to the same rules as C++ function names. For example, the three\r
-``tgsin`` functions in our motivating example get the mangled names\r
-``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two\r
-caveats to this use of name mangling:\r
-\r
-* Future versions of Clang may change the name mangling of functions overloaded\r
- in C, so you should not depend on an specific mangling. To be completely\r
- safe, we strongly urge the use of ``static inline`` with ``overloadable``\r
- functions.\r
-\r
-* The ``overloadable`` attribute has almost no meaning when used in C++,\r
- because names will already be mangled and functions are already overloadable.\r
- However, when an ``overloadable`` function occurs within an ``extern "C"``\r
- linkage specification, it's name *will* be mangled in the same way as it\r
- would in C.\r
-\r
-Query for this feature with ``__has_extension(attribute_overloadable)``.\r
-\r
-\r
-release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)\r
------------------------------------------------------------------------------------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-Marks a function as releasing a capability.\r
-\r
-\r
-try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)\r
----------------------------------------------------------------------------------------------------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-Marks a function that attempts to acquire a capability. This function may fail to\r
-actually acquire the capability; they accept a Boolean value determining\r
-whether acquiring the capability means success (true), or failing to acquire\r
-the capability means success (false).\r
-\r
-\r
-Variable Attributes\r
-===================\r
-\r
-\r
-tls_model (gnu::tls_model)\r
---------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","X","",""\r
-\r
-The ``tls_model`` attribute allows you to specify which thread-local storage\r
-model to use. It accepts the following strings:\r
-\r
-* global-dynamic\r
-* local-dynamic\r
-* initial-exec\r
-* local-exec\r
-\r
-TLS models are mutually exclusive.\r
-\r
-\r
-Type Attributes\r
-===============\r
-\r
-\r
-__single_inhertiance, __multiple_inheritance, __virtual_inheritance\r
--------------------------------------------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "","","","X"\r
-\r
-This collection of keywords is enabled under ``-fms-extensions`` and controls\r
-the pointer-to-member representation used on ``*-*-win32`` targets.\r
-\r
-The ``*-*-win32`` targets utilize a pointer-to-member representation which\r
-varies in size and alignment depending on the definition of the underlying\r
-class.\r
-\r
-However, this is problematic when a forward declaration is only available and\r
-no definition has been made yet. In such cases, Clang is forced to utilize the\r
-most general representation that is available to it.\r
-\r
-These keywords make it possible to use a pointer-to-member representation other\r
-than the most general one regardless of whether or not the definition will ever\r
-be present in the current translation unit.\r
-\r
-This family of keywords belong between the ``class-key`` and ``class-name``:\r
-\r
-.. code-block:: c++\r
-\r
- struct __single_inheritance S;\r
- int S::*i;\r
- struct S {};\r
-\r
-This keyword can be applied to class templates but only has an effect when used\r
-on full specializations:\r
-\r
-.. code-block:: c++\r
-\r
- template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template\r
- template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization\r
- template <> struct __single_inheritance A<int, float>;\r
-\r
-Note that choosing an inheritance model less general than strictly necessary is\r
-an error:\r
-\r
-.. code-block:: c++\r
-\r
- struct __multiple_inheritance S; // error: inheritance model does not match definition\r
- int S::*i;\r
- struct S {};\r
-\r
-\r
-Statement Attributes\r
-====================\r
-\r
-\r
-fallthrough (clang::fallthrough)\r
---------------------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "","X","",""\r
-\r
-The ``clang::fallthrough`` attribute is used along with the\r
-``-Wimplicit-fallthrough`` argument to annotate intentional fall-through\r
-between switch labels. It can only be applied to a null statement placed at a\r
-point of execution between any statement and the next switch label. It is\r
-common to mark these places with a specific comment, but this attribute is\r
-meant to replace comments with a more strict annotation, which can be checked\r
-by the compiler. This attribute doesn't change semantics of the code and can\r
-be used wherever an intended fall-through occurs. It is designed to mimic\r
-control-flow statements like ``break;``, so it can be placed in most places\r
-where ``break;`` can, but only if there are no statements on the execution path\r
-between it and the next switch label.\r
-\r
-Here is an example:\r
-\r
-.. code-block:: c++\r
-\r
- // compile with -Wimplicit-fallthrough\r
- switch (n) {\r
- case 22:\r
- case 33: // no warning: no statements between case labels\r
- f();\r
- case 44: // warning: unannotated fall-through\r
- g();\r
- [[clang::fallthrough]];\r
- case 55: // no warning\r
- if (x) {\r
- h();\r
- break;\r
- }\r
- else {\r
- i();\r
- [[clang::fallthrough]];\r
- }\r
- case 66: // no warning\r
- p();\r
- [[clang::fallthrough]]; // warning: fallthrough annotation does not\r
- // directly precede case label\r
- q();\r
- case 77: // warning: unannotated fall-through\r
- r();\r
- }\r
-\r
-\r
-Consumed Annotation Checking\r
-============================\r
-Clang supports additional attributes for checking basic resource management\r
-properties, specifically for unique objects that have a single owning reference.\r
-The following attributes are currently supported, although **the implementation\r
-for these annotations is currently in development and are subject to change.**\r
-\r
-callable_when\r
--------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Use ``__attribute__((callable_when(...)))`` to indicate what states a method\r
-may be called in. Valid states are unconsumed, consumed, or unknown. Each\r
-argument to this attribute must be a quoted string. E.g.:\r
-\r
-``__attribute__((callable_when("unconsumed", "unknown")))``\r
-\r
-\r
-consumable\r
-----------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Each ``class`` that uses any of the typestate annotations must first be marked\r
-using the ``consumable`` attribute. Failure to do so will result in a warning.\r
-\r
-This attribute accepts a single parameter that must be one of the following:\r
-``unknown``, ``consumed``, or ``unconsumed``.\r
-\r
-\r
-param_typestate\r
----------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-This attribute specifies expectations about function parameters. Calls to an\r
-function with annotated parameters will issue a warning if the corresponding\r
-argument isn't in the expected state. The attribute is also used to set the\r
-initial state of the parameter when analyzing the function's body.\r
-\r
-\r
-return_typestate\r
-----------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-The ``return_typestate`` attribute can be applied to functions or parameters.\r
-When applied to a function the attribute specifies the state of the returned\r
-value. The function's body is checked to ensure that it always returns a value\r
-in the specified state. On the caller side, values returned by the annotated\r
-function are initialized to the given state.\r
-\r
-When applied to a function parameter it modifies the state of an argument after\r
-a call to the function returns. The function's body is checked to ensure that\r
-the parameter is in the expected state before returning.\r
-\r
-\r
-set_typestate\r
--------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Annotate methods that transition an object into a new state with\r
-``__attribute__((set_typestate(new_state)))``. The new new state must be\r
-unconsumed, consumed, or unknown.\r
-\r
-\r
-test_typestate\r
---------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method\r
-returns true if the object is in the specified state..\r
-\r
-\r
-Type Safety Checking\r
-====================\r
-Clang supports additional attributes to enable checking type safety properties\r
-that can't be enforced by the C type system. Use cases include:\r
-\r
-* MPI library implementations, where these attributes enable checking that\r
- the buffer type matches the passed ``MPI_Datatype``;\r
-* for HDF5 library there is a similar use case to MPI;\r
-* checking types of variadic functions' arguments for functions like\r
- ``fcntl()`` and ``ioctl()``.\r
-\r
-You can detect support for these attributes with ``__has_attribute()``. For\r
-example:\r
-\r
-.. code-block:: c++\r
-\r
- #if defined(__has_attribute)\r
- # if __has_attribute(argument_with_type_tag) && \\r
- __has_attribute(pointer_with_type_tag) && \\r
- __has_attribute(type_tag_for_datatype)\r
- # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))\r
- /* ... other macros ... */\r
- # endif\r
- #endif\r
-\r
- #if !defined(ATTR_MPI_PWT)\r
- # define ATTR_MPI_PWT(buffer_idx, type_idx)\r
- #endif\r
-\r
- int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)\r
- ATTR_MPI_PWT(1,3);\r
-\r
-argument_with_type_tag\r
-----------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,\r
-type_tag_idx)))`` on a function declaration to specify that the function\r
-accepts a type tag that determines the type of some other argument.\r
-``arg_kind`` is an identifier that should be used when annotating all\r
-applicable type tags.\r
-\r
-This attribute is primarily useful for checking arguments of variadic functions\r
-(``pointer_with_type_tag`` can be used in most non-variadic cases).\r
-\r
-For example:\r
-\r
-.. code-block:: c++\r
-\r
- int fcntl(int fd, int cmd, ...)\r
- __attribute__(( argument_with_type_tag(fcntl,3,2) ));\r
-\r
-\r
-pointer_with_type_tag\r
----------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``\r
-on a function declaration to specify that the function accepts a type tag that\r
-determines the pointee type of some other pointer argument.\r
-\r
-For example:\r
-\r
-.. code-block:: c++\r
-\r
- int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)\r
- __attribute__(( pointer_with_type_tag(mpi,1,3) ));\r
-\r
-\r
-type_tag_for_datatype\r
----------------------\r
-.. csv-table:: Supported Syntaxes\r
- :header: "GNU", "C++11", "__declspec", "Keyword"\r
-\r
- "X","","",""\r
-\r
-Clang supports annotating type tags of two forms.\r
-\r
-* **Type tag that is an expression containing a reference to some declared\r
- identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a\r
- declaration with that identifier:\r
-\r
- .. code-block:: c++\r
-\r
- extern struct mpi_datatype mpi_datatype_int\r
- __attribute__(( type_tag_for_datatype(mpi,int) ));\r
- #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)\r
-\r
-* **Type tag that is an integral literal.** Introduce a ``static const``\r
- variable with a corresponding initializer value and attach\r
- ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,\r
- for example:\r
-\r
- .. code-block:: c++\r
-\r
- #define MPI_INT ((MPI_Datatype) 42)\r
- static const MPI_Datatype mpi_datatype_int\r
- __attribute__(( type_tag_for_datatype(mpi,int) )) = 42\r
-\r
-The attribute also accepts an optional third argument that determines how the\r
-expression is compared to the type tag. There are two supported flags:\r
-\r
-* ``layout_compatible`` will cause types to be compared according to\r
- layout-compatibility rules (C++11 [class.mem] p 17, 18). This is\r
- implemented to support annotating types like ``MPI_DOUBLE_INT``.\r
-\r
- For example:\r
-\r
- .. code-block:: c++\r
-\r
- /* In mpi.h */\r
- struct internal_mpi_double_int { double d; int i; };\r
- extern struct mpi_datatype mpi_datatype_double_int\r
- __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));\r
-\r
- #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)\r
-\r
- /* In user code */\r
- struct my_pair { double a; int b; };\r
- struct my_pair *buffer;\r
- MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning\r
-\r
- struct my_int_pair { int a; int b; }\r
- struct my_int_pair *buffer2;\r
- MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element\r
- // type 'struct my_int_pair'\r
- // doesn't match specified MPI_Datatype\r
-\r
-* ``must_be_null`` specifies that the expression should be a null pointer\r
- constant, for example:\r
-\r
- .. code-block:: c++\r
-\r
- /* In mpi.h */\r
- extern struct mpi_datatype mpi_datatype_null\r
- __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));\r
-\r
- #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)\r
-\r
- /* In user code */\r
- MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL\r
- // was specified but buffer\r
- // is not a null pointer\r
-\r
-\r
+..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-attr-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+===================
+Attributes in Clang
+===================
+.. contents::
+ :local:
+
+Introduction
+============
+
+This page lists the attributes currently supported by Clang.
+
+Function Attributes
+===================
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.
+
+The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: "IRQ",
+"FIQ", "SWI", "ABORT", "UNDEF".
+
+The semantics are as follows:
+
+- If the function is AAPCS, Clang instructs the backend to realign the stack to
+ 8 bytes on entry. This is a general requirement of the AAPCS at public
+ interfaces, but may not hold when an exception is taken. Doing this allows
+ other AAPCS functions to be called.
+- If the CPU is M-class this is all that needs to be done since the architecture
+ itself is designed in such a way that functions obeying the normal AAPCS ABI
+ constraints are valid exception handlers.
+- If the CPU is not M-class, the prologue and epilogue are modified to save all
+ non-banked registers that are used, so that upon return the user-mode state
+ will not be corrupted. Note that to avoid unnecessary overhead, only
+ general-purpose (integer) registers are saved in this way. If VFP operations
+ are needed, that state must be saved manually.
+
+ Specifically, interrupt kinds other than "FIQ" will save all core registers
+ except "lr" and "sp". "FIQ" interrupts will save r0-r7.
+- If the CPU is not M-class, the return instruction is changed to one of the
+ canonical sequences permitted by the architecture for exception return. Where
+ possible the function itself will make the necessary "lr" adjustments so that
+ the "preferred return address" is selected.
+
+ Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
+ handler, where the offset from "lr" to the preferred return address depends on
+ the execution state of the code which generated the exception. In this case
+ a sequence equivalent to "movs pc, lr" will be used.
+
+
+acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function as acquiring a capability.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+availability
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+The ``availability`` attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions. Consider
+the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
+succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because ``f()`` is no longer available.
+
+The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration's lifetime (in any order) along with additional information. Those
+clauses can be:
+
+introduced=\ *version*
+ The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+ The first version in which this declaration was deprecated, meaning that
+ users should migrate away from this API.
+
+obsoleted=\ *version*
+ The first version in which this declaration was obsoleted, meaning that it
+ was removed completely and can no longer be used.
+
+unavailable
+ This declaration is never available on this platform.
+
+message=\ *string-literal*
+ Additional message text that Clang will provide when emitting a warning or
+ error about use of a deprecated or obsoleted declaration. Useful to direct
+ users to replacement APIs.
+
+Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored. If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored. Supported platforms
+are:
+
+``ios``
+ Apple's iOS operating system. The minimum deployment target is specified by
+ the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
+ command-line arguments.
+
+``macosx``
+ Apple's Mac OS X operating system. The minimum deployment target is
+ specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+
+A declaration can be used even when deploying back to a platform version prior
+to when the declaration was introduced. When this happens, the declaration is
+`weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` attribute were added to the declaration. A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.
+
+If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:
+
+.. code-block:: c
+
+ void g(void) __attribute__((availability(macosx,introduced=10.4)));
+ void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches
+ void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+ void g(void); // okay, inherits both macosx and ios availability from above.
+ void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+.. code-block:: objc
+
+ @interface A
+ - (id)method __attribute__((availability(macosx,introduced=10.4)));
+ - (id)method2 __attribute__((availability(macosx,introduced=10.4)));
+ @end
+
+ @interface B : A
+ - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later
+ - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4
+ @end
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","","","X"
+
+A function declared as ``_Noreturn`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``_Noreturn``
+that appears to be capable of returning to its caller.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","X","",""
+
+A function declared as ``[[noreturn]]`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
+that appears to be capable of returning to its caller.
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+The ``carries_dependency`` attribute specifies dependency propagation into and
+out of functions.
+
+When specified on a function or Objective-C method, the ``carries_depedency``
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.
+
+Note, this attribute does not change the meaning of the program, but may result
+in generatation of more efficient code.
+
+
+enable_if
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+The ``enable_if`` attribute can be placed on function declarations to control
+which overload is selected based on the values of the function's arguments.
+When combined with the ``overloadable`` attribute, this feature is also
+available in C.
+
+.. code-block:: c++
+
+ int isdigit(int c);
+ int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));
+
+ void foo(char c) {
+ isdigit(c);
+ isdigit(10);
+ isdigit(-10); // results in a compile-time error.
+ }
+
+The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.
+
+The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the callsite. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.
+
+Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:
+
+.. code-block:: c++
+
+ __attribute__((always_inline))
+ static inline size_t strnlen(const char *s, size_t maxlen)
+ __attribute__((overloadable))
+ __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
+ "chosen when the buffer size is known but 'maxlen' is not")))
+ {
+ return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
+ }
+
+Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.
+
+.. code-block:: c++
+
+ void f() __attribute__((enable_if(true, ""))); // #1
+ void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
+
+ void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
+ void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
+
+In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.
+
+Query for this feature with ``__has_attribute(enable_if)``.
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the ``-Wformat`` warning, it is
+ on by default.
+
+#. Clang checks that the format string argument is a literal string. This is
+ the ``-Wformat-nonliteral`` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+ GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
+ fuctions. Clang does not warn if the format string comes from a function
+ parameter, where the function is annotated with a compatible attribute,
+ otherwise it warns. For example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+
+ In this case we warn because ``s`` contains a format string for a
+ ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+
+ In this case Clang does not warn because the format string ``s`` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of ``foo`` will receive a warning.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+The ``noduplicate`` attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL "barrier" function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+"nodupfunc" in the code below avoids that:
+
+.. code-block:: c
+
+ void nodupfunc() __attribute__((noduplicate));
+ // Setting it as a C++11 attribute is also valid
+ // void nodupfunc() [[clang::noduplicate]];
+ void foo();
+ void bar();
+
+ nodupfunc();
+ if (a > n) {
+ foo();
+ } else {
+ bar();
+ }
+
+gets possibly modified by some optimizations into code similar to this:
+
+.. code-block:: c
+
+ if (a > n) {
+ nodupfunc();
+ foo();
+ } else {
+ nodupfunc();
+ bar();
+ }
+
+where the call to "nodupfunc" is duplicated and sunk into the two branches
+of the condition.
+
+
+no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.
+
+
+no_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+.. _langext-memory_sanitizer:
+
+Use ``__attribute__((no_sanitize_memory))`` on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.
+
+
+no_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+.. _langext-thread_sanitizer:
+
+Use ``__attribute__((no_sanitize_thread))`` on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.
+
+
+objc_method_family
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the "method family"
+that a method belongs to.
+
+**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
+``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
+attribute can only be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
+
+Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (``ns_returns_retained``,
+``ns_returns_not_retained``, etc).
+
+Query for this feature with ``__has_attribute(objc_method_family)``.
+
+
+objc_requires_super
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a "call to ``super``" in the overriding
+method in the subclass.
+
+**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only
+be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (void)foo __attribute__((objc_requires_super));
+
+This attribute can only be applied the method declarations within a class, and
+not a protocol. Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+``-dealloc`` where the call must appear at the end). It checks only that it
+exists.
+
+Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
+attribute:
+
+.. code-block:: objc
+
+ - (void)foo NS_REQUIRES_SUPER;
+
+This macro is conditionally defined depending on the compiler's support for
+this attribute. If the compiler does not support the attribute the macro
+expands to nothing.
+
+Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super. For example:
+
+.. code-block:: objc
+
+ warning: method possibly missing a [super AnnotMeth] call
+ - (void) AnnotMeth{};
+ ^
+
+
+overloadable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the ``overloadable`` attribute. For example, one
+might provide several overloaded versions of a ``tgsin`` function that invokes
+the appropriate standard function computing the sine of a value with ``float``,
+``double``, or ``long double`` precision:
+
+.. code-block:: c
+
+ #include <math.h>
+ float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+ double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+ long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+Given these declarations, one can call ``tgsin`` with a ``float`` value to
+receive a ``float`` result, with a ``double`` to receive a ``double`` result,
+etc. Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:
+
+* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
+ floating-point promotion (per C99) rather than as a floating-point conversion
+ (as in C++).
+
+* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
+ considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
+ compatible types.
+
+* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
+ and ``U`` are compatible types. This conversion is given "conversion" rank.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions. Most importantly, if any function with a given
+name is given the ``overloadable`` attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+``overloadable`` attribute. This rule even applies to redeclarations of
+functions whose original declaration had the ``overloadable`` attribute, e.g.,
+
+.. code-block:: c
+
+ int f(int) __attribute__((overloadable));
+ float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+ int g(int) __attribute__((overloadable));
+ int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes. Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+ int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++). This feature is particularly
+useful when combined with the ``unavailable`` attribute:
+
+.. code-block:: c++
+
+ void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
+caveats to this use of name mangling:
+
+* Future versions of Clang may change the name mangling of functions overloaded
+ in C, so you should not depend on an specific mangling. To be completely
+ safe, we strongly urge the use of ``static inline`` with ``overloadable``
+ functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+ because names will already be mangled and functions are already overloadable.
+ However, when an ``overloadable`` function occurs within an ``extern "C"``
+ linkage specification, it's name *will* be mangled in the same way as it
+ would in C.
+
+Query for this feature with ``__has_extension(attribute_overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function as releasing a capability.
+
+
+try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)
+---------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).
+
+
+Variable Attributes
+===================
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+The ``tls_model`` attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:
+
+* global-dynamic
+* local-dynamic
+* initial-exec
+* local-exec
+
+TLS models are mutually exclusive.
+
+
+Type Attributes
+===============
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","","","X"
+
+This collection of keywords is enabled under ``-fms-extensions`` and controls
+the pointer-to-member representation used on ``*-*-win32`` targets.
+
+The ``*-*-win32`` targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.
+
+However, this is problematic when a forward declaration is only available and
+no definition has been made yet. In such cases, Clang is forced to utilize the
+most general representation that is available to it.
+
+These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.
+
+This family of keywords belong between the ``class-key`` and ``class-name``:
+
+.. code-block:: c++
+
+ struct __single_inheritance S;
+ int S::*i;
+ struct S {};
+
+This keyword can be applied to class templates but only has an effect when used
+on full specializations:
+
+.. code-block:: c++
+
+ template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
+ template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
+ template <> struct __single_inheritance A<int, float>;
+
+Note that choosing an inheritance model less general than strictly necessary is
+an error:
+
+.. code-block:: c++
+
+ struct __multiple_inheritance S; // error: inheritance model does not match definition
+ int S::*i;
+ struct S {};
+
+
+Statement Attributes
+====================
+
+
+fallthrough (clang::fallthrough)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","X","",""
+
+The ``clang::fallthrough`` attribute is used along with the
+``-Wimplicit-fallthrough`` argument to annotate intentional fall-through
+between switch labels. It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label. It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler. This attribute doesn't change semantics of the code and can
+be used wherever an intended fall-through occurs. It is designed to mimic
+control-flow statements like ``break;``, so it can be placed in most places
+where ``break;`` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+Here is an example:
+
+.. code-block:: c++
+
+ // compile with -Wimplicit-fallthrough
+ switch (n) {
+ case 22:
+ case 33: // no warning: no statements between case labels
+ f();
+ case 44: // warning: unannotated fall-through
+ g();
+ [[clang::fallthrough]];
+ case 55: // no warning
+ if (x) {
+ h();
+ break;
+ }
+ else {
+ i();
+ [[clang::fallthrough]];
+ }
+ case 66: // no warning
+ p();
+ [[clang::fallthrough]]; // warning: fallthrough annotation does not
+ // directly precede case label
+ q();
+ case 77: // warning: unannotated fall-through
+ r();
+ }
+
+
+Consumed Annotation Checking
+============================
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((callable_when(...)))`` to indicate what states a method
+may be called in. Valid states are unconsumed, consumed, or unknown. Each
+argument to this attribute must be a quoted string. E.g.:
+
+``__attribute__((callable_when("unconsumed", "unknown")))``
+
+
+consumable
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Each ``class`` that uses any of the typestate annotations must first be marked
+using the ``consumable`` attribute. Failure to do so will result in a warning.
+
+This attribute accepts a single parameter that must be one of the following:
+``unknown``, ``consumed``, or ``unconsumed``.
+
+
+param_typestate
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+This attribute specifies expectations about function parameters. Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn't in the expected state. The attribute is also used to set the
+initial state of the parameter when analyzing the function's body.
+
+
+return_typestate
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+The ``return_typestate`` attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value. The function's body is checked to ensure that it always returns a value
+in the specified state. On the caller side, values returned by the annotated
+function are initialized to the given state.
+
+When applied to a function parameter it modifies the state of an argument after
+a call to the function returns. The function's body is checked to ensure that
+the parameter is in the expected state before returning.
+
+
+set_typestate
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Annotate methods that transition an object into a new state with
+``__attribute__((set_typestate(new_state)))``. The new new state must be
+unconsumed, consumed, or unknown.
+
+
+test_typestate
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
+returns true if the object is in the specified state..
+
+
+Type Safety Checking
+====================
+Clang supports additional attributes to enable checking type safety properties
+that can't be enforced by the C type system. Use cases include:
+
+* MPI library implementations, where these attributes enable checking that
+ the buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar use case to MPI;
+* checking types of variadic functions' arguments for functions like
+ ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``. For
+example:
+
+.. code-block:: c++
+
+ #if defined(__has_attribute)
+ # if __has_attribute(argument_with_type_tag) && \
+ __has_attribute(pointer_with_type_tag) && \
+ __has_attribute(type_tag_for_datatype)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+ /* ... other macros ... */
+ # endif
+ #endif
+
+ #if !defined(ATTR_MPI_PWT)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx)
+ #endif
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ ATTR_MPI_PWT(1,3);
+
+argument_with_type_tag
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))`` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+``arg_kind`` is an identifier that should be used when annotating all
+applicable type tags.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+For example:
+
+.. code-block:: c++
+
+ int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+For example:
+
+.. code-block:: c++
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Clang supports annotating type tags of two forms.
+
+* **Type tag that is an expression containing a reference to some declared
+ identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
+ declaration with that identifier:
+
+ .. code-block:: c++
+
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+
+* **Type tag that is an integral literal.** Introduce a ``static const``
+ variable with a corresponding initializer value and attach
+ ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
+ for example:
+
+ .. code-block:: c++
+
+ #define MPI_INT ((MPI_Datatype) 42)
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
+
+The attribute also accepts an optional third argument that determines how the
+expression is compared to the type tag. There are two supported flags:
+
+* ``layout_compatible`` will cause types to be compared according to
+ layout-compatibility rules (C++11 [class.mem] p 17, 18). This is
+ implemented to support annotating types like ``MPI_DOUBLE_INT``.
+
+ For example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ struct internal_mpi_double_int { double d; int i; };
+ extern struct mpi_datatype mpi_datatype_double_int
+ __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));
+
+ #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element
+ // type 'struct my_int_pair'
+ // doesn't match specified MPI_Datatype
+
+* ``must_be_null`` specifies that the expression should be a null pointer
+ constant, for example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ extern struct mpi_datatype mpi_datatype_null
+ __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+ #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+
+ /* In user code */
+ MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
+ // was specified but buffer
+ // is not a null pointer
+
+
projects / clang / commitdiff