Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame^] | 1 | .. |
| 2 | ------------------------------------------------------------------- |
| 3 | NOTE: This file is automatically generated by running clang-tblgen |
| 4 | -gen-attr-docs. Do not edit this file by hand!! |
| 5 | ------------------------------------------------------------------- |
| 6 | |
| 7 | =================== |
| 8 | Attributes in Clang |
| 9 | =================== |
| 10 | .. contents:: |
| 11 | :local: |
| 12 | |
| 13 | Introduction |
| 14 | ============ |
| 15 | |
| 16 | This page lists the attributes currently supported by Clang. |
| 17 | |
| 18 | Function Attributes |
| 19 | =================== |
| 20 | |
| 21 | |
| 22 | interrupt |
| 23 | --------- |
| 24 | .. csv-table:: Supported Syntaxes |
| 25 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 26 | |
| 27 | "X","","","" |
| 28 | |
| 29 | Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on |
| 30 | ARM targets. This attribute may be attached to a function definition and |
| 31 | instructs the backend to generate appropriate function entry/exit code so that |
| 32 | it can be used directly as an interrupt service routine. |
| 33 | |
| 34 | The parameter passed to the interrupt attribute is optional, but if |
| 35 | provided it must be a string literal with one of the following values: "IRQ", |
| 36 | "FIQ", "SWI", "ABORT", "UNDEF". |
| 37 | |
| 38 | The semantics are as follows: |
| 39 | |
| 40 | - If the function is AAPCS, Clang instructs the backend to realign the stack to |
| 41 | 8 bytes on entry. This is a general requirement of the AAPCS at public |
| 42 | interfaces, but may not hold when an exception is taken. Doing this allows |
| 43 | other AAPCS functions to be called. |
| 44 | - If the CPU is M-class this is all that needs to be done since the architecture |
| 45 | itself is designed in such a way that functions obeying the normal AAPCS ABI |
| 46 | constraints are valid exception handlers. |
| 47 | - If the CPU is not M-class, the prologue and epilogue are modified to save all |
| 48 | non-banked registers that are used, so that upon return the user-mode state |
| 49 | will not be corrupted. Note that to avoid unnecessary overhead, only |
| 50 | general-purpose (integer) registers are saved in this way. If VFP operations |
| 51 | are needed, that state must be saved manually. |
| 52 | |
| 53 | Specifically, interrupt kinds other than "FIQ" will save all core registers |
| 54 | except "lr" and "sp". "FIQ" interrupts will save r0-r7. |
| 55 | - If the CPU is not M-class, the return instruction is changed to one of the |
| 56 | canonical sequences permitted by the architecture for exception return. Where |
| 57 | possible the function itself will make the necessary "lr" adjustments so that |
| 58 | the "preferred return address" is selected. |
| 59 | |
| 60 | Unfortunately the compiler is unable to make this guarantee for an "UNDEF" |
| 61 | handler, where the offset from "lr" to the preferred return address depends on |
| 62 | the execution state of the code which generated the exception. In this case |
| 63 | a sequence equivalent to "movs pc, lr" will be used. |
| 64 | |
| 65 | |
| 66 | acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability) |
| 67 | ----------------------------------------------------------------------------------------------------------- |
| 68 | .. csv-table:: Supported Syntaxes |
| 69 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 70 | |
| 71 | "X","X","","" |
| 72 | |
| 73 | Marks a function as acquiring a capability. |
| 74 | |
| 75 | |
| 76 | assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability) |
| 77 | ------------------------------------------------------------------------------------------------------- |
| 78 | .. csv-table:: Supported Syntaxes |
| 79 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 80 | |
| 81 | "X","X","","" |
| 82 | |
| 83 | Marks a function that dynamically tests whether a capability is held, and halts |
| 84 | the program if it is not held. |
| 85 | |
| 86 | |
| 87 | availability |
| 88 | ------------ |
| 89 | .. csv-table:: Supported Syntaxes |
| 90 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 91 | |
| 92 | "X","","","" |
| 93 | |
| 94 | The ``availability`` attribute can be placed on declarations to describe the |
| 95 | lifecycle of that declaration relative to operating system versions. Consider |
| 96 | the function declaration for a hypothetical function ``f``: |
| 97 | |
| 98 | .. code-block:: c++ |
| 99 | |
| 100 | void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); |
| 101 | |
| 102 | The availability attribute states that ``f`` was introduced in Mac OS X 10.4, |
| 103 | deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information |
| 104 | is used by Clang to determine when it is safe to use ``f``: for example, if |
| 105 | Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` |
| 106 | succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call |
| 107 | succeeds but Clang emits a warning specifying that the function is deprecated. |
| 108 | Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call |
| 109 | fails because ``f()`` is no longer available. |
| 110 | |
| 111 | The availability attribute is a comma-separated list starting with the |
| 112 | platform name and then including clauses specifying important milestones in the |
| 113 | declaration's lifetime (in any order) along with additional information. Those |
| 114 | clauses can be: |
| 115 | |
| 116 | introduced=\ *version* |
| 117 | The first version in which this declaration was introduced. |
| 118 | |
| 119 | deprecated=\ *version* |
| 120 | The first version in which this declaration was deprecated, meaning that |
| 121 | users should migrate away from this API. |
| 122 | |
| 123 | obsoleted=\ *version* |
| 124 | The first version in which this declaration was obsoleted, meaning that it |
| 125 | was removed completely and can no longer be used. |
| 126 | |
| 127 | unavailable |
| 128 | This declaration is never available on this platform. |
| 129 | |
| 130 | message=\ *string-literal* |
| 131 | Additional message text that Clang will provide when emitting a warning or |
| 132 | error about use of a deprecated or obsoleted declaration. Useful to direct |
| 133 | users to replacement APIs. |
| 134 | |
| 135 | Multiple availability attributes can be placed on a declaration, which may |
| 136 | correspond to different platforms. Only the availability attribute with the |
| 137 | platform corresponding to the target platform will be used; any others will be |
| 138 | ignored. If no availability attribute specifies availability for the current |
| 139 | target platform, the availability attributes are ignored. Supported platforms |
| 140 | are: |
| 141 | |
| 142 | ``ios`` |
| 143 | Apple's iOS operating system. The minimum deployment target is specified by |
| 144 | the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` |
| 145 | command-line arguments. |
| 146 | |
| 147 | ``macosx`` |
| 148 | Apple's Mac OS X operating system. The minimum deployment target is |
| 149 | specified by the ``-mmacosx-version-min=*version*`` command-line argument. |
| 150 | |
| 151 | A declaration can be used even when deploying back to a platform version prior |
| 152 | to when the declaration was introduced. When this happens, the declaration is |
| 153 | `weakly linked |
| 154 | <https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_, |
| 155 | as if the ``weak_import`` attribute were added to the declaration. A |
| 156 | weakly-linked declaration may or may not be present a run-time, and a program |
| 157 | can determine whether the declaration is present by checking whether the |
| 158 | address of that declaration is non-NULL. |
| 159 | |
| 160 | If there are multiple declarations of the same entity, the availability |
| 161 | attributes must either match on a per-platform basis or later |
| 162 | declarations must not have availability attributes for that |
| 163 | platform. For example: |
| 164 | |
| 165 | .. code-block:: c |
| 166 | |
| 167 | void g(void) __attribute__((availability(macosx,introduced=10.4))); |
| 168 | void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches |
| 169 | void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform |
| 170 | void g(void); // okay, inherits both macosx and ios availability from above. |
| 171 | void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch |
| 172 | |
| 173 | When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: |
| 174 | |
| 175 | .. code-block:: objc |
| 176 | |
| 177 | @interface A |
| 178 | - (id)method __attribute__((availability(macosx,introduced=10.4))); |
| 179 | - (id)method2 __attribute__((availability(macosx,introduced=10.4))); |
| 180 | @end |
| 181 | |
| 182 | @interface B : A |
| 183 | - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later |
| 184 | - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4 |
| 185 | @end |
| 186 | |
| 187 | |
| 188 | _Noreturn |
| 189 | --------- |
| 190 | .. csv-table:: Supported Syntaxes |
| 191 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 192 | |
| 193 | "","","","X" |
| 194 | |
| 195 | A function declared as ``_Noreturn`` shall not return to its caller. The |
| 196 | compiler will generate a diagnostic for a function declared as ``_Noreturn`` |
| 197 | that appears to be capable of returning to its caller. |
| 198 | |
| 199 | |
| 200 | noreturn |
| 201 | -------- |
| 202 | .. csv-table:: Supported Syntaxes |
| 203 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 204 | |
| 205 | "","X","","" |
| 206 | |
| 207 | A function declared as ``[[noreturn]]`` shall not return to its caller. The |
| 208 | compiler will generate a diagnostic for a function declared as ``[[noreturn]]`` |
| 209 | that appears to be capable of returning to its caller. |
| 210 | |
| 211 | |
| 212 | carries_dependency |
| 213 | ------------------ |
| 214 | .. csv-table:: Supported Syntaxes |
| 215 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 216 | |
| 217 | "X","X","","" |
| 218 | |
| 219 | The ``carries_dependency`` attribute specifies dependency propagation into and |
| 220 | out of functions. |
| 221 | |
| 222 | When specified on a function or Objective-C method, the ``carries_depedency`` |
| 223 | attribute means that the return value carries a dependency out of the function, |
| 224 | so that the implementation need not constrain ordering upon return from that |
| 225 | function. Implementations of the function and its caller may choose to preserve |
| 226 | dependencies instead of emitting memory ordering instructions such as fences. |
| 227 | |
| 228 | Note, this attribute does not change the meaning of the program, but may result |
| 229 | in generatation of more efficient code. |
| 230 | |
| 231 | |
| 232 | enable_if |
| 233 | --------- |
| 234 | .. csv-table:: Supported Syntaxes |
| 235 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 236 | |
| 237 | "X","","","" |
| 238 | |
| 239 | The ``enable_if`` attribute can be placed on function declarations to control |
| 240 | which overload is selected based on the values of the function's arguments. |
| 241 | When combined with the ``overloadable`` attribute, this feature is also |
| 242 | available in C. |
| 243 | |
| 244 | .. code-block:: c++ |
| 245 | |
| 246 | int isdigit(int c); |
| 247 | 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"))); |
| 248 | |
| 249 | void foo(char c) { |
| 250 | isdigit(c); |
| 251 | isdigit(10); |
| 252 | isdigit(-10); // results in a compile-time error. |
| 253 | } |
| 254 | |
| 255 | The enable_if attribute takes two arguments, the first is an expression written |
| 256 | in terms of the function parameters, the second is a string explaining why this |
| 257 | overload candidate could not be selected to be displayed in diagnostics. The |
| 258 | expression is part of the function signature for the purposes of determining |
| 259 | whether it is a redeclaration (following the rules used when determining |
| 260 | whether a C++ template specialization is ODR-equivalent), but is not part of |
| 261 | the type. |
| 262 | |
| 263 | The enable_if expression is evaluated as if it were the body of a |
| 264 | bool-returning constexpr function declared with the arguments of the function |
| 265 | it is being applied to, then called with the parameters at the callsite. If the |
| 266 | result is false or could not be determined through constant expression |
| 267 | evaluation, then this overload will not be chosen and the provided string may |
| 268 | be used in a diagnostic if the compile fails as a result. |
| 269 | |
| 270 | Because the enable_if expression is an unevaluated context, there are no global |
| 271 | state changes, nor the ability to pass information from the enable_if |
| 272 | expression to the function body. For example, suppose we want calls to |
| 273 | strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of |
| 274 | strbuf) only if the size of strbuf can be determined: |
| 275 | |
| 276 | .. code-block:: c++ |
| 277 | |
| 278 | __attribute__((always_inline)) |
| 279 | static inline size_t strnlen(const char *s, size_t maxlen) |
| 280 | __attribute__((overloadable)) |
| 281 | __attribute__((enable_if(__builtin_object_size(s, 0) != -1))), |
| 282 | "chosen when the buffer size is known but 'maxlen' is not"))) |
| 283 | { |
| 284 | return strnlen_chk(s, maxlen, __builtin_object_size(s, 0)); |
| 285 | } |
| 286 | |
| 287 | Multiple enable_if attributes may be applied to a single declaration. In this |
| 288 | case, the enable_if expressions are evaluated from left to right in the |
| 289 | following manner. First, the candidates whose enable_if expressions evaluate to |
| 290 | false or cannot be evaluated are discarded. If the remaining candidates do not |
| 291 | share ODR-equivalent enable_if expressions, the overload resolution is |
| 292 | ambiguous. Otherwise, enable_if overload resolution continues with the next |
| 293 | enable_if attribute on the candidates that have not been discarded and have |
| 294 | remaining enable_if attributes. In this way, we pick the most specific |
| 295 | overload out of a number of viable overloads using enable_if. |
| 296 | |
| 297 | .. code-block:: c++ |
| 298 | |
| 299 | void f() __attribute__((enable_if(true, ""))); // #1 |
| 300 | void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2 |
| 301 | |
| 302 | void g(int i, int j) __attribute__((enable_if(i, ""))); // #1 |
| 303 | void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2 |
| 304 | |
| 305 | In this example, a call to f() is always resolved to #2, as the first enable_if |
| 306 | expression is ODR-equivalent for both declarations, but #1 does not have another |
| 307 | enable_if expression to continue evaluating, so the next round of evaluation has |
| 308 | only a single candidate. In a call to g(1, 1), the call is ambiguous even though |
| 309 | #2 has more enable_if attributes, because the first enable_if expressions are |
| 310 | not ODR-equivalent. |
| 311 | |
| 312 | Query for this feature with ``__has_attribute(enable_if)``. |
| 313 | |
| 314 | |
| 315 | format (gnu::format) |
| 316 | -------------------- |
| 317 | .. csv-table:: Supported Syntaxes |
| 318 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 319 | |
| 320 | "X","X","","" |
| 321 | |
| 322 | Clang supports the ``format`` attribute, which indicates that the function |
| 323 | accepts a ``printf`` or ``scanf``-like format string and corresponding |
| 324 | arguments or a ``va_list`` that contains these arguments. |
| 325 | |
| 326 | Please see `GCC documentation about format attribute |
| 327 | <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details |
| 328 | about attribute syntax. |
| 329 | |
| 330 | Clang implements two kinds of checks with this attribute. |
| 331 | |
| 332 | #. Clang checks that the function with the ``format`` attribute is called with |
| 333 | a format string that uses format specifiers that are allowed, and that |
| 334 | arguments match the format string. This is the ``-Wformat`` warning, it is |
| 335 | on by default. |
| 336 | |
| 337 | #. Clang checks that the format string argument is a literal string. This is |
| 338 | the ``-Wformat-nonliteral`` warning, it is off by default. |
| 339 | |
| 340 | Clang implements this mostly the same way as GCC, but there is a difference |
| 341 | for functions that accept a ``va_list`` argument (for example, ``vprintf``). |
| 342 | GCC does not emit ``-Wformat-nonliteral`` warning for calls to such |
| 343 | fuctions. Clang does not warn if the format string comes from a function |
| 344 | parameter, where the function is annotated with a compatible attribute, |
| 345 | otherwise it warns. For example: |
| 346 | |
| 347 | .. code-block:: c |
| 348 | |
| 349 | __attribute__((__format__ (__scanf__, 1, 3))) |
| 350 | void foo(const char* s, char *buf, ...) { |
| 351 | va_list ap; |
| 352 | va_start(ap, buf); |
| 353 | |
| 354 | vprintf(s, ap); // warning: format string is not a string literal |
| 355 | } |
| 356 | |
| 357 | In this case we warn because ``s`` contains a format string for a |
| 358 | ``scanf``-like function, but it is passed to a ``printf``-like function. |
| 359 | |
| 360 | If the attribute is removed, clang still warns, because the format string is |
| 361 | not a string literal. |
| 362 | |
| 363 | Another example: |
| 364 | |
| 365 | .. code-block:: c |
| 366 | |
| 367 | __attribute__((__format__ (__printf__, 1, 3))) |
| 368 | void foo(const char* s, char *buf, ...) { |
| 369 | va_list ap; |
| 370 | va_start(ap, buf); |
| 371 | |
| 372 | vprintf(s, ap); // warning |
| 373 | } |
| 374 | |
| 375 | In this case Clang does not warn because the format string ``s`` and |
| 376 | the corresponding arguments are annotated. If the arguments are |
| 377 | incorrect, the caller of ``foo`` will receive a warning. |
| 378 | |
| 379 | |
| 380 | noduplicate (clang::noduplicate) |
| 381 | -------------------------------- |
| 382 | .. csv-table:: Supported Syntaxes |
| 383 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 384 | |
| 385 | "X","X","","" |
| 386 | |
| 387 | The ``noduplicate`` attribute can be placed on function declarations to control |
| 388 | whether function calls to this function can be duplicated or not as a result of |
| 389 | optimizations. This is required for the implementation of functions with |
| 390 | certain special requirements, like the OpenCL "barrier" function, that might |
| 391 | need to be run concurrently by all the threads that are executing in lockstep |
| 392 | on the hardware. For example this attribute applied on the function |
| 393 | "nodupfunc" in the code below avoids that: |
| 394 | |
| 395 | .. code-block:: c |
| 396 | |
| 397 | void nodupfunc() __attribute__((noduplicate)); |
| 398 | // Setting it as a C++11 attribute is also valid |
| 399 | // void nodupfunc() [[clang::noduplicate]]; |
| 400 | void foo(); |
| 401 | void bar(); |
| 402 | |
| 403 | nodupfunc(); |
| 404 | if (a > n) { |
| 405 | foo(); |
| 406 | } else { |
| 407 | bar(); |
| 408 | } |
| 409 | |
| 410 | gets possibly modified by some optimizations into code similar to this: |
| 411 | |
| 412 | .. code-block:: c |
| 413 | |
| 414 | if (a > n) { |
| 415 | nodupfunc(); |
| 416 | foo(); |
| 417 | } else { |
| 418 | nodupfunc(); |
| 419 | bar(); |
| 420 | } |
| 421 | |
| 422 | where the call to "nodupfunc" is duplicated and sunk into the two branches |
| 423 | of the condition. |
| 424 | |
| 425 | |
| 426 | no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address) |
| 427 | ----------------------------------------------------------------------------------------------------------- |
| 428 | .. csv-table:: Supported Syntaxes |
| 429 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 430 | |
| 431 | "X","X","","" |
| 432 | |
| 433 | .. _langext-address_sanitizer: |
| 434 | |
| 435 | Use ``__attribute__((no_sanitize_address))`` on a function declaration to |
| 436 | specify that address safety instrumentation (e.g. AddressSanitizer) should |
| 437 | not be applied to that function. |
| 438 | |
| 439 | |
| 440 | no_sanitize_memory |
| 441 | ------------------ |
| 442 | .. csv-table:: Supported Syntaxes |
| 443 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 444 | |
| 445 | "X","","","" |
| 446 | |
| 447 | .. _langext-memory_sanitizer: |
| 448 | |
| 449 | Use ``__attribute__((no_sanitize_memory))`` on a function declaration to |
| 450 | specify that checks for uninitialized memory should not be inserted |
| 451 | (e.g. by MemorySanitizer). The function may still be instrumented by the tool |
| 452 | to avoid false positives in other places. |
| 453 | |
| 454 | |
| 455 | no_sanitize_thread |
| 456 | ------------------ |
| 457 | .. csv-table:: Supported Syntaxes |
| 458 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 459 | |
| 460 | "X","","","" |
| 461 | |
| 462 | .. _langext-thread_sanitizer: |
| 463 | |
| 464 | Use ``__attribute__((no_sanitize_thread))`` on a function declaration to |
| 465 | specify that checks for data races on plain (non-atomic) memory accesses should |
| 466 | not be inserted by ThreadSanitizer. The function is still instrumented by the |
| 467 | tool to avoid false positives and provide meaningful stack traces. |
| 468 | |
| 469 | |
| 470 | objc_method_family |
| 471 | ------------------ |
| 472 | .. csv-table:: Supported Syntaxes |
| 473 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 474 | |
| 475 | "X","","","" |
| 476 | |
| 477 | Many methods in Objective-C have conventional meanings determined by their |
| 478 | selectors. It is sometimes useful to be able to mark a method as having a |
| 479 | particular conventional meaning despite not having the right selector, or as |
| 480 | not having the conventional meaning that its selector would suggest. For these |
| 481 | use cases, we provide an attribute to specifically describe the "method family" |
| 482 | that a method belongs to. |
| 483 | |
| 484 | **Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of |
| 485 | ``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This |
| 486 | attribute can only be placed at the end of a method declaration: |
| 487 | |
| 488 | .. code-block:: objc |
| 489 | |
| 490 | - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); |
| 491 | |
| 492 | Users who do not wish to change the conventional meaning of a method, and who |
| 493 | merely want to document its non-standard retain and release semantics, should |
| 494 | use the retaining behavior attributes (``ns_returns_retained``, |
| 495 | ``ns_returns_not_retained``, etc). |
| 496 | |
| 497 | Query for this feature with ``__has_attribute(objc_method_family)``. |
| 498 | |
| 499 | |
| 500 | objc_requires_super |
| 501 | ------------------- |
| 502 | .. csv-table:: Supported Syntaxes |
| 503 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 504 | |
| 505 | "X","","","" |
| 506 | |
| 507 | Some Objective-C classes allow a subclass to override a particular method in a |
| 508 | parent class but expect that the overriding method also calls the overridden |
| 509 | method in the parent class. For these cases, we provide an attribute to |
| 510 | designate that a method requires a "call to ``super``" in the overriding |
| 511 | method in the subclass. |
| 512 | |
| 513 | **Usage**: ``__attribute__((objc_requires_super))``. This attribute can only |
| 514 | be placed at the end of a method declaration: |
| 515 | |
| 516 | .. code-block:: objc |
| 517 | |
| 518 | - (void)foo __attribute__((objc_requires_super)); |
| 519 | |
| 520 | This attribute can only be applied the method declarations within a class, and |
| 521 | not a protocol. Currently this attribute does not enforce any placement of |
| 522 | where the call occurs in the overriding method (such as in the case of |
| 523 | ``-dealloc`` where the call must appear at the end). It checks only that it |
| 524 | exists. |
| 525 | |
| 526 | Note that on both OS X and iOS that the Foundation framework provides a |
| 527 | convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this |
| 528 | attribute: |
| 529 | |
| 530 | .. code-block:: objc |
| 531 | |
| 532 | - (void)foo NS_REQUIRES_SUPER; |
| 533 | |
| 534 | This macro is conditionally defined depending on the compiler's support for |
| 535 | this attribute. If the compiler does not support the attribute the macro |
| 536 | expands to nothing. |
| 537 | |
| 538 | Operationally, when a method has this annotation the compiler will warn if the |
| 539 | implementation of an override in a subclass does not call super. For example: |
| 540 | |
| 541 | .. code-block:: objc |
| 542 | |
| 543 | warning: method possibly missing a [super AnnotMeth] call |
| 544 | - (void) AnnotMeth{}; |
| 545 | ^ |
| 546 | |
| 547 | |
| 548 | overloadable |
| 549 | ------------ |
| 550 | .. csv-table:: Supported Syntaxes |
| 551 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 552 | |
| 553 | "X","","","" |
| 554 | |
| 555 | Clang provides support for C++ function overloading in C. Function overloading |
| 556 | in C is introduced using the ``overloadable`` attribute. For example, one |
| 557 | might provide several overloaded versions of a ``tgsin`` function that invokes |
| 558 | the appropriate standard function computing the sine of a value with ``float``, |
| 559 | ``double``, or ``long double`` precision: |
| 560 | |
| 561 | .. code-block:: c |
| 562 | |
| 563 | #include <math.h> |
| 564 | float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } |
| 565 | double __attribute__((overloadable)) tgsin(double x) { return sin(x); } |
| 566 | long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } |
| 567 | |
| 568 | Given these declarations, one can call ``tgsin`` with a ``float`` value to |
| 569 | receive a ``float`` result, with a ``double`` to receive a ``double`` result, |
| 570 | etc. Function overloading in C follows the rules of C++ function overloading |
| 571 | to pick the best overload given the call arguments, with a few C-specific |
| 572 | semantics: |
| 573 | |
| 574 | * Conversion from ``float`` or ``double`` to ``long double`` is ranked as a |
| 575 | floating-point promotion (per C99) rather than as a floating-point conversion |
| 576 | (as in C++). |
| 577 | |
| 578 | * A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is |
| 579 | considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are |
| 580 | compatible types. |
| 581 | |
| 582 | * A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` |
| 583 | and ``U`` are compatible types. This conversion is given "conversion" rank. |
| 584 | |
| 585 | The declaration of ``overloadable`` functions is restricted to function |
| 586 | declarations and definitions. Most importantly, if any function with a given |
| 587 | name is given the ``overloadable`` attribute, then all function declarations |
| 588 | and definitions with that name (and in that scope) must have the |
| 589 | ``overloadable`` attribute. This rule even applies to redeclarations of |
| 590 | functions whose original declaration had the ``overloadable`` attribute, e.g., |
| 591 | |
| 592 | .. code-block:: c |
| 593 | |
| 594 | int f(int) __attribute__((overloadable)); |
| 595 | float f(float); // error: declaration of "f" must have the "overloadable" attribute |
| 596 | |
| 597 | int g(int) __attribute__((overloadable)); |
| 598 | int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute |
| 599 | |
| 600 | Functions marked ``overloadable`` must have prototypes. Therefore, the |
| 601 | following code is ill-formed: |
| 602 | |
| 603 | .. code-block:: c |
| 604 | |
| 605 | int h() __attribute__((overloadable)); // error: h does not have a prototype |
| 606 | |
| 607 | However, ``overloadable`` functions are allowed to use a ellipsis even if there |
| 608 | are no named parameters (as is permitted in C++). This feature is particularly |
| 609 | useful when combined with the ``unavailable`` attribute: |
| 610 | |
| 611 | .. code-block:: c++ |
| 612 | |
| 613 | void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error |
| 614 | |
| 615 | Functions declared with the ``overloadable`` attribute have their names mangled |
| 616 | according to the same rules as C++ function names. For example, the three |
| 617 | ``tgsin`` functions in our motivating example get the mangled names |
| 618 | ``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two |
| 619 | caveats to this use of name mangling: |
| 620 | |
| 621 | * Future versions of Clang may change the name mangling of functions overloaded |
| 622 | in C, so you should not depend on an specific mangling. To be completely |
| 623 | safe, we strongly urge the use of ``static inline`` with ``overloadable`` |
| 624 | functions. |
| 625 | |
| 626 | * The ``overloadable`` attribute has almost no meaning when used in C++, |
| 627 | because names will already be mangled and functions are already overloadable. |
| 628 | However, when an ``overloadable`` function occurs within an ``extern "C"`` |
| 629 | linkage specification, it's name *will* be mangled in the same way as it |
| 630 | would in C. |
| 631 | |
| 632 | Query for this feature with ``__has_extension(attribute_overloadable)``. |
| 633 | |
| 634 | |
| 635 | release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability) |
| 636 | ----------------------------------------------------------------------------------------------------------- |
| 637 | .. csv-table:: Supported Syntaxes |
| 638 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 639 | |
| 640 | "X","X","","" |
| 641 | |
| 642 | Marks a function as releasing a capability. |
| 643 | |
| 644 | |
| 645 | try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability) |
| 646 | --------------------------------------------------------------------------------------------------------------------------- |
| 647 | .. csv-table:: Supported Syntaxes |
| 648 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 649 | |
| 650 | "X","X","","" |
| 651 | |
| 652 | Marks a function that attempts to acquire a capability. This function may fail to |
| 653 | actually acquire the capability; they accept a Boolean value determining |
| 654 | whether acquiring the capability means success (true), or failing to acquire |
| 655 | the capability means success (false). |
| 656 | |
| 657 | |
| 658 | Variable Attributes |
| 659 | =================== |
| 660 | |
| 661 | |
| 662 | tls_model (gnu::tls_model) |
| 663 | -------------------------- |
| 664 | .. csv-table:: Supported Syntaxes |
| 665 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 666 | |
| 667 | "X","X","","" |
| 668 | |
| 669 | The ``tls_model`` attribute allows you to specify which thread-local storage |
| 670 | model to use. It accepts the following strings: |
| 671 | |
| 672 | * global-dynamic |
| 673 | * local-dynamic |
| 674 | * initial-exec |
| 675 | * local-exec |
| 676 | |
| 677 | TLS models are mutually exclusive. |
| 678 | |
| 679 | |
| 680 | Type Attributes |
| 681 | =============== |
| 682 | |
| 683 | |
| 684 | __single_inhertiance, __multiple_inheritance, __virtual_inheritance |
| 685 | ------------------------------------------------------------------- |
| 686 | .. csv-table:: Supported Syntaxes |
| 687 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 688 | |
| 689 | "","","","X" |
| 690 | |
| 691 | This collection of keywords is enabled under ``-fms-extensions`` and controls |
| 692 | the pointer-to-member representation used on ``*-*-win32`` targets. |
| 693 | |
| 694 | The ``*-*-win32`` targets utilize a pointer-to-member representation which |
| 695 | varies in size and alignment depending on the definition of the underlying |
| 696 | class. |
| 697 | |
| 698 | However, this is problematic when a forward declaration is only available and |
| 699 | no definition has been made yet. In such cases, Clang is forced to utilize the |
| 700 | most general representation that is available to it. |
| 701 | |
| 702 | These keywords make it possible to use a pointer-to-member representation other |
| 703 | than the most general one regardless of whether or not the definition will ever |
| 704 | be present in the current translation unit. |
| 705 | |
| 706 | This family of keywords belong between the ``class-key`` and ``class-name``: |
| 707 | |
| 708 | .. code-block:: c++ |
| 709 | |
| 710 | struct __single_inheritance S; |
| 711 | int S::*i; |
| 712 | struct S {}; |
| 713 | |
| 714 | This keyword can be applied to class templates but only has an effect when used |
| 715 | on full specializations: |
| 716 | |
| 717 | .. code-block:: c++ |
| 718 | |
| 719 | template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template |
| 720 | template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization |
| 721 | template <> struct __single_inheritance A<int, float>; |
| 722 | |
| 723 | Note that choosing an inheritance model less general than strictly necessary is |
| 724 | an error: |
| 725 | |
| 726 | .. code-block:: c++ |
| 727 | |
| 728 | struct __multiple_inheritance S; // error: inheritance model does not match definition |
| 729 | int S::*i; |
| 730 | struct S {}; |
| 731 | |
| 732 | |
| 733 | Statement Attributes |
| 734 | ==================== |
| 735 | |
| 736 | |
| 737 | fallthrough (clang::fallthrough) |
| 738 | -------------------------------- |
| 739 | .. csv-table:: Supported Syntaxes |
| 740 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 741 | |
| 742 | "","X","","" |
| 743 | |
| 744 | The ``clang::fallthrough`` attribute is used along with the |
| 745 | ``-Wimplicit-fallthrough`` argument to annotate intentional fall-through |
| 746 | between switch labels. It can only be applied to a null statement placed at a |
| 747 | point of execution between any statement and the next switch label. It is |
| 748 | common to mark these places with a specific comment, but this attribute is |
| 749 | meant to replace comments with a more strict annotation, which can be checked |
| 750 | by the compiler. This attribute doesn't change semantics of the code and can |
| 751 | be used wherever an intended fall-through occurs. It is designed to mimic |
| 752 | control-flow statements like ``break;``, so it can be placed in most places |
| 753 | where ``break;`` can, but only if there are no statements on the execution path |
| 754 | between it and the next switch label. |
| 755 | |
| 756 | Here is an example: |
| 757 | |
| 758 | .. code-block:: c++ |
| 759 | |
| 760 | // compile with -Wimplicit-fallthrough |
| 761 | switch (n) { |
| 762 | case 22: |
| 763 | case 33: // no warning: no statements between case labels |
| 764 | f(); |
| 765 | case 44: // warning: unannotated fall-through |
| 766 | g(); |
| 767 | [[clang::fallthrough]]; |
| 768 | case 55: // no warning |
| 769 | if (x) { |
| 770 | h(); |
| 771 | break; |
| 772 | } |
| 773 | else { |
| 774 | i(); |
| 775 | [[clang::fallthrough]]; |
| 776 | } |
| 777 | case 66: // no warning |
| 778 | p(); |
| 779 | [[clang::fallthrough]]; // warning: fallthrough annotation does not |
| 780 | // directly precede case label |
| 781 | q(); |
| 782 | case 77: // warning: unannotated fall-through |
| 783 | r(); |
| 784 | } |
| 785 | |
| 786 | |
| 787 | Consumed Annotation Checking |
| 788 | ============================ |
| 789 | Clang supports additional attributes for checking basic resource management |
| 790 | properties, specifically for unique objects that have a single owning reference. |
| 791 | The following attributes are currently supported, although **the implementation |
| 792 | for these annotations is currently in development and are subject to change.** |
| 793 | |
| 794 | callable_when |
| 795 | ------------- |
| 796 | .. csv-table:: Supported Syntaxes |
| 797 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 798 | |
| 799 | "X","","","" |
| 800 | |
| 801 | Use ``__attribute__((callable_when(...)))`` to indicate what states a method |
| 802 | may be called in. Valid states are unconsumed, consumed, or unknown. Each |
| 803 | argument to this attribute must be a quoted string. E.g.: |
| 804 | |
| 805 | ``__attribute__((callable_when("unconsumed", "unknown")))`` |
| 806 | |
| 807 | |
| 808 | consumable |
| 809 | ---------- |
| 810 | .. csv-table:: Supported Syntaxes |
| 811 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 812 | |
| 813 | "X","","","" |
| 814 | |
| 815 | Each ``class`` that uses any of the typestate annotations must first be marked |
| 816 | using the ``consumable`` attribute. Failure to do so will result in a warning. |
| 817 | |
| 818 | This attribute accepts a single parameter that must be one of the following: |
| 819 | ``unknown``, ``consumed``, or ``unconsumed``. |
| 820 | |
| 821 | |
| 822 | param_typestate |
| 823 | --------------- |
| 824 | .. csv-table:: Supported Syntaxes |
| 825 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 826 | |
| 827 | "X","","","" |
| 828 | |
| 829 | This attribute specifies expectations about function parameters. Calls to an |
| 830 | function with annotated parameters will issue a warning if the corresponding |
| 831 | argument isn't in the expected state. The attribute is also used to set the |
| 832 | initial state of the parameter when analyzing the function's body. |
| 833 | |
| 834 | |
| 835 | return_typestate |
| 836 | ---------------- |
| 837 | .. csv-table:: Supported Syntaxes |
| 838 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 839 | |
| 840 | "X","","","" |
| 841 | |
| 842 | The ``return_typestate`` attribute can be applied to functions or parameters. |
| 843 | When applied to a function the attribute specifies the state of the returned |
| 844 | value. The function's body is checked to ensure that it always returns a value |
| 845 | in the specified state. On the caller side, values returned by the annotated |
| 846 | function are initialized to the given state. |
| 847 | |
| 848 | When applied to a function parameter it modifies the state of an argument after |
| 849 | a call to the function returns. The function's body is checked to ensure that |
| 850 | the parameter is in the expected state before returning. |
| 851 | |
| 852 | |
| 853 | set_typestate |
| 854 | ------------- |
| 855 | .. csv-table:: Supported Syntaxes |
| 856 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 857 | |
| 858 | "X","","","" |
| 859 | |
| 860 | Annotate methods that transition an object into a new state with |
| 861 | ``__attribute__((set_typestate(new_state)))``. The new new state must be |
| 862 | unconsumed, consumed, or unknown. |
| 863 | |
| 864 | |
| 865 | test_typestate |
| 866 | -------------- |
| 867 | .. csv-table:: Supported Syntaxes |
| 868 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 869 | |
| 870 | "X","","","" |
| 871 | |
| 872 | Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method |
| 873 | returns true if the object is in the specified state.. |
| 874 | |
| 875 | |
| 876 | Type Safety Checking |
| 877 | ==================== |
| 878 | Clang supports additional attributes to enable checking type safety properties |
| 879 | that can't be enforced by the C type system. Use cases include: |
| 880 | |
| 881 | * MPI library implementations, where these attributes enable checking that |
| 882 | the buffer type matches the passed ``MPI_Datatype``; |
| 883 | * for HDF5 library there is a similar use case to MPI; |
| 884 | * checking types of variadic functions' arguments for functions like |
| 885 | ``fcntl()`` and ``ioctl()``. |
| 886 | |
| 887 | You can detect support for these attributes with ``__has_attribute()``. For |
| 888 | example: |
| 889 | |
| 890 | .. code-block:: c++ |
| 891 | |
| 892 | #if defined(__has_attribute) |
| 893 | # if __has_attribute(argument_with_type_tag) && \ |
| 894 | __has_attribute(pointer_with_type_tag) && \ |
| 895 | __has_attribute(type_tag_for_datatype) |
| 896 | # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) |
| 897 | /* ... other macros ... */ |
| 898 | # endif |
| 899 | #endif |
| 900 | |
| 901 | #if !defined(ATTR_MPI_PWT) |
| 902 | # define ATTR_MPI_PWT(buffer_idx, type_idx) |
| 903 | #endif |
| 904 | |
| 905 | int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) |
| 906 | ATTR_MPI_PWT(1,3); |
| 907 | |
| 908 | argument_with_type_tag |
| 909 | ---------------------- |
| 910 | .. csv-table:: Supported Syntaxes |
| 911 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 912 | |
| 913 | "X","","","" |
| 914 | |
| 915 | Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, |
| 916 | type_tag_idx)))`` on a function declaration to specify that the function |
| 917 | accepts a type tag that determines the type of some other argument. |
| 918 | ``arg_kind`` is an identifier that should be used when annotating all |
| 919 | applicable type tags. |
| 920 | |
| 921 | This attribute is primarily useful for checking arguments of variadic functions |
| 922 | (``pointer_with_type_tag`` can be used in most non-variadic cases). |
| 923 | |
| 924 | For example: |
| 925 | |
| 926 | .. code-block:: c++ |
| 927 | |
| 928 | int fcntl(int fd, int cmd, ...) |
| 929 | __attribute__(( argument_with_type_tag(fcntl,3,2) )); |
| 930 | |
| 931 | |
| 932 | pointer_with_type_tag |
| 933 | --------------------- |
| 934 | .. csv-table:: Supported Syntaxes |
| 935 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 936 | |
| 937 | "X","","","" |
| 938 | |
| 939 | Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` |
| 940 | on a function declaration to specify that the function accepts a type tag that |
| 941 | determines the pointee type of some other pointer argument. |
| 942 | |
| 943 | For example: |
| 944 | |
| 945 | .. code-block:: c++ |
| 946 | |
| 947 | int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) |
| 948 | __attribute__(( pointer_with_type_tag(mpi,1,3) )); |
| 949 | |
| 950 | |
| 951 | type_tag_for_datatype |
| 952 | --------------------- |
| 953 | .. csv-table:: Supported Syntaxes |
| 954 | :header: "GNU", "C++11", "__declspec", "Keyword" |
| 955 | |
| 956 | "X","","","" |
| 957 | |
| 958 | Clang supports annotating type tags of two forms. |
| 959 | |
| 960 | * **Type tag that is an expression containing a reference to some declared |
| 961 | identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a |
| 962 | declaration with that identifier: |
| 963 | |
| 964 | .. code-block:: c++ |
| 965 | |
| 966 | extern struct mpi_datatype mpi_datatype_int |
| 967 | __attribute__(( type_tag_for_datatype(mpi,int) )); |
| 968 | #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) |
| 969 | |
| 970 | * **Type tag that is an integral literal.** Introduce a ``static const`` |
| 971 | variable with a corresponding initializer value and attach |
| 972 | ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, |
| 973 | for example: |
| 974 | |
| 975 | .. code-block:: c++ |
| 976 | |
| 977 | #define MPI_INT ((MPI_Datatype) 42) |
| 978 | static const MPI_Datatype mpi_datatype_int |
| 979 | __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 |
| 980 | |
| 981 | The attribute also accepts an optional third argument that determines how the |
| 982 | expression is compared to the type tag. There are two supported flags: |
| 983 | |
| 984 | * ``layout_compatible`` will cause types to be compared according to |
| 985 | layout-compatibility rules (C++11 [class.mem] p 17, 18). This is |
| 986 | implemented to support annotating types like ``MPI_DOUBLE_INT``. |
| 987 | |
| 988 | For example: |
| 989 | |
| 990 | .. code-block:: c++ |
| 991 | |
| 992 | /* In mpi.h */ |
| 993 | struct internal_mpi_double_int { double d; int i; }; |
| 994 | extern struct mpi_datatype mpi_datatype_double_int |
| 995 | __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); |
| 996 | |
| 997 | #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) |
| 998 | |
| 999 | /* In user code */ |
| 1000 | struct my_pair { double a; int b; }; |
| 1001 | struct my_pair *buffer; |
| 1002 | MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning |
| 1003 | |
| 1004 | struct my_int_pair { int a; int b; } |
| 1005 | struct my_int_pair *buffer2; |
| 1006 | MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element |
| 1007 | // type 'struct my_int_pair' |
| 1008 | // doesn't match specified MPI_Datatype |
| 1009 | |
| 1010 | * ``must_be_null`` specifies that the expression should be a null pointer |
| 1011 | constant, for example: |
| 1012 | |
| 1013 | .. code-block:: c++ |
| 1014 | |
| 1015 | /* In mpi.h */ |
| 1016 | extern struct mpi_datatype mpi_datatype_null |
| 1017 | __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); |
| 1018 | |
| 1019 | #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) |
| 1020 | |
| 1021 | /* In user code */ |
| 1022 | MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL |
| 1023 | // was specified but buffer |
| 1024 | // is not a null pointer |
| 1025 | |
| 1026 | |