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