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