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 10 def 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 =================== 18 Attributes in Clang 19 =================== 20 .. contents:: 21 :local: 22 23 Introduction 24 ============ 25 26 This page lists the attributes currently supported by Clang. 27 }]; 28 } 29 30 def SectionDocs : Documentation { 31 let Category = DocCatVariable; 32 let Content = [{ 33 The ``section`` attribute allows you to specify a specific section a 34 global variable or function should be in after translation. 35 }]; 36 let Heading = "section (gnu::section, __declspec(allocate))"; 37 } 38 39 def InitSegDocs : Documentation { 40 let Category = DocCatVariable; 41 let Content = [{ 42 The attribute applied by ``pragma init_seg()`` controls the section into 43 which global initialization function pointers are emitted. It is only 44 available with ``-fms-extensions``. Typically, this function pointer is 45 emitted into ``.CRT$XCU`` on Windows. The user can change the order of 46 initialization by using a different section name with the same 47 ``.CRT$XC`` prefix and a suffix that sorts lexicographically before or 48 after the standard ``.CRT$XCU`` sections. See the init_seg_ 49 documentation on MSDN for more information. 50 51 .. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx 52 }]; 53 } 54 55 def TLSModelDocs : Documentation { 56 let Category = DocCatVariable; 57 let Content = [{ 58 The ``tls_model`` attribute allows you to specify which thread-local storage 59 model to use. It accepts the following strings: 60 61 * global-dynamic 62 * local-dynamic 63 * initial-exec 64 * local-exec 65 66 TLS models are mutually exclusive. 67 }]; 68 } 69 70 def ThreadDocs : Documentation { 71 let Category = DocCatVariable; 72 let Content = [{ 73 The ``__declspec(thread)`` attribute declares a variable with thread local 74 storage. It is available under the ``-fms-extensions`` flag for MSVC 75 compatibility. See the documentation for `__declspec(thread)`_ on MSDN. 76 77 .. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx 78 79 In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the 80 GNU ``__thread`` keyword. The variable must not have a destructor and must have 81 a constant initializer, if any. The attribute only applies to variables 82 declared with static storage duration, such as globals, class static data 83 members, and static locals. 84 }]; 85 } 86 87 def CarriesDependencyDocs : Documentation { 88 let Category = DocCatFunction; 89 let Content = [{ 90 The ``carries_dependency`` attribute specifies dependency propagation into and 91 out of functions. 92 93 When specified on a function or Objective-C method, the ``carries_dependency`` 94 attribute means that the return value carries a dependency out of the function, 95 so that the implementation need not constrain ordering upon return from that 96 function. Implementations of the function and its caller may choose to preserve 97 dependencies instead of emitting memory ordering instructions such as fences. 98 99 Note, this attribute does not change the meaning of the program, but may result 100 in generation of more efficient code. 101 }]; 102 } 103 104 def C11NoReturnDocs : Documentation { 105 let Category = DocCatFunction; 106 let Content = [{ 107 A function declared as ``_Noreturn`` shall not return to its caller. The 108 compiler will generate a diagnostic for a function declared as ``_Noreturn`` 109 that appears to be capable of returning to its caller. 110 }]; 111 } 112 113 def CXX11NoReturnDocs : Documentation { 114 let Category = DocCatFunction; 115 let Content = [{ 116 A function declared as ``[[noreturn]]`` shall not return to its caller. The 117 compiler will generate a diagnostic for a function declared as ``[[noreturn]]`` 118 that appears to be capable of returning to its caller. 119 }]; 120 } 121 122 def AssertCapabilityDocs : Documentation { 123 let Category = DocCatFunction; 124 let Heading = "assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)"; 125 let Content = [{ 126 Marks a function that dynamically tests whether a capability is held, and halts 127 the program if it is not held. 128 }]; 129 } 130 131 def AcquireCapabilityDocs : Documentation { 132 let Category = DocCatFunction; 133 let Heading = "acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)"; 134 let Content = [{ 135 Marks a function as acquiring a capability. 136 }]; 137 } 138 139 def TryAcquireCapabilityDocs : Documentation { 140 let Category = DocCatFunction; 141 let Heading = "try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)"; 142 let Content = [{ 143 Marks a function that attempts to acquire a capability. This function may fail to 144 actually acquire the capability; they accept a Boolean value determining 145 whether acquiring the capability means success (true), or failing to acquire 146 the capability means success (false). 147 }]; 148 } 149 150 def ReleaseCapabilityDocs : Documentation { 151 let Category = DocCatFunction; 152 let Heading = "release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)"; 153 let Content = [{ 154 Marks a function as releasing a capability. 155 }]; 156 } 157 158 def AssumeAlignedDocs : Documentation { 159 let Category = DocCatFunction; 160 let Content = [{ 161 Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function 162 declaration to specify that the return value of the function (which must be a 163 pointer type) has the specified offset, in bytes, from an address with the 164 specified alignment. The offset is taken to be zero if omitted. 165 166 .. code-block:: c++ 167 168 // The returned pointer value has 32-byte alignment. 169 void *a() __attribute__((assume_aligned (32))); 170 171 // The returned pointer value is 4 bytes greater than an address having 172 // 32-byte alignment. 173 void *b() __attribute__((assume_aligned (32, 4))); 174 175 Note that this attribute provides information to the compiler regarding a 176 condition that the code already ensures is true. It does not cause the compiler 177 to enforce the provided alignment assumption. 178 }]; 179 } 180 181 def EnableIfDocs : Documentation { 182 let Category = DocCatFunction; 183 let Content = [{ 184 .. Note:: Some features of this attribute are experimental. The meaning of 185 multiple enable_if attributes on a single declaration is subject to change in 186 a future version of clang. Also, the ABI is not standardized and the name 187 mangling may change in future versions. To avoid that, use asm labels. 188 189 The ``enable_if`` attribute can be placed on function declarations to control 190 which overload is selected based on the values of the function's arguments. 191 When combined with the ``overloadable`` attribute, this feature is also 192 available in C. 193 194 .. code-block:: c++ 195 196 int isdigit(int c); 197 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"))); 198 199 void foo(char c) { 200 isdigit(c); 201 isdigit(10); 202 isdigit(-10); // results in a compile-time error. 203 } 204 205 The enable_if attribute takes two arguments, the first is an expression written 206 in terms of the function parameters, the second is a string explaining why this 207 overload candidate could not be selected to be displayed in diagnostics. The 208 expression is part of the function signature for the purposes of determining 209 whether it is a redeclaration (following the rules used when determining 210 whether a C++ template specialization is ODR-equivalent), but is not part of 211 the type. 212 213 The enable_if expression is evaluated as if it were the body of a 214 bool-returning constexpr function declared with the arguments of the function 215 it is being applied to, then called with the parameters at the call site. If the 216 result is false or could not be determined through constant expression 217 evaluation, then this overload will not be chosen and the provided string may 218 be used in a diagnostic if the compile fails as a result. 219 220 Because the enable_if expression is an unevaluated context, there are no global 221 state changes, nor the ability to pass information from the enable_if 222 expression to the function body. For example, suppose we want calls to 223 strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of 224 strbuf) only if the size of strbuf can be determined: 225 226 .. code-block:: c++ 227 228 __attribute__((always_inline)) 229 static inline size_t strnlen(const char *s, size_t maxlen) 230 __attribute__((overloadable)) 231 __attribute__((enable_if(__builtin_object_size(s, 0) != -1))), 232 "chosen when the buffer size is known but 'maxlen' is not"))) 233 { 234 return strnlen_chk(s, maxlen, __builtin_object_size(s, 0)); 235 } 236 237 Multiple enable_if attributes may be applied to a single declaration. In this 238 case, the enable_if expressions are evaluated from left to right in the 239 following manner. First, the candidates whose enable_if expressions evaluate to 240 false or cannot be evaluated are discarded. If the remaining candidates do not 241 share ODR-equivalent enable_if expressions, the overload resolution is 242 ambiguous. Otherwise, enable_if overload resolution continues with the next 243 enable_if attribute on the candidates that have not been discarded and have 244 remaining enable_if attributes. In this way, we pick the most specific 245 overload out of a number of viable overloads using enable_if. 246 247 .. code-block:: c++ 248 249 void f() __attribute__((enable_if(true, ""))); // #1 250 void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2 251 252 void g(int i, int j) __attribute__((enable_if(i, ""))); // #1 253 void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2 254 255 In this example, a call to f() is always resolved to #2, as the first enable_if 256 expression is ODR-equivalent for both declarations, but #1 does not have another 257 enable_if expression to continue evaluating, so the next round of evaluation has 258 only a single candidate. In a call to g(1, 1), the call is ambiguous even though 259 #2 has more enable_if attributes, because the first enable_if expressions are 260 not ODR-equivalent. 261 262 Query for this feature with ``__has_attribute(enable_if)``. 263 264 Note that functions with one or more ``enable_if`` attributes may not have 265 their address taken, unless all of the conditions specified by said 266 ``enable_if`` are constants that evaluate to ``true``. For example: 267 268 .. code-block:: c 269 270 const int TrueConstant = 1; 271 const int FalseConstant = 0; 272 int f(int a) __attribute__((enable_if(a > 0, ""))); 273 int g(int a) __attribute__((enable_if(a == 0 || a != 0, ""))); 274 int h(int a) __attribute__((enable_if(1, ""))); 275 int i(int a) __attribute__((enable_if(TrueConstant, ""))); 276 int j(int a) __attribute__((enable_if(FalseConstant, ""))); 277 278 void fn() { 279 int (*ptr)(int); 280 ptr = &f; // error: 'a > 0' is not always true 281 ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant 282 ptr = &h; // OK: 1 is a truthy constant 283 ptr = &i; // OK: 'TrueConstant' is a truthy constant 284 ptr = &j; // error: 'FalseConstant' is a constant, but not truthy 285 } 286 287 Because ``enable_if`` evaluation happens during overload resolution, 288 ``enable_if`` may give unintuitive results when used with templates, depending 289 on when overloads are resolved. In the example below, clang will emit a 290 diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``: 291 292 .. code-block:: c++ 293 294 double foo(int i) __attribute__((enable_if(i > 0, ""))); 295 void *foo(int i) __attribute__((enable_if(i <= 0, ""))); 296 template <int I> 297 auto bar() { return foo(I); } 298 299 template <typename T> 300 auto baz() { return foo(T::number); } 301 302 struct WithNumber { constexpr static int number = 1; }; 303 void callThem() { 304 bar<sizeof(WithNumber)>(); 305 baz<WithNumber>(); 306 } 307 308 This is because, in ``bar``, ``foo`` is resolved prior to template 309 instantiation, so the value for ``I`` isn't known (thus, both ``enable_if`` 310 conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during 311 template instantiation, so the value for ``T::number`` is known. 312 }]; 313 } 314 315 def PassObjectSizeDocs : Documentation { 316 let Category = DocCatVariable; // Technically it's a parameter doc, but eh. 317 let Content = [{ 318 .. Note:: The mangling of functions with parameters that are annotated with 319 ``pass_object_size`` is subject to change. You can get around this by 320 using ``__asm__("foo")`` to explicitly name your functions, thus preserving 321 your ABI; also, non-overloadable C functions with ``pass_object_size`` are 322 not mangled. 323 324 The ``pass_object_size(Type)`` attribute can be placed on function parameters to 325 instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite 326 of said function, and implicitly pass the result of this call in as an invisible 327 argument of type ``size_t`` directly after the parameter annotated with 328 ``pass_object_size``. Clang will also replace any calls to 329 ``__builtin_object_size(param, Type)`` in the function by said implicit 330 parameter. 331 332 Example usage: 333 334 .. code-block:: c 335 336 int bzero1(char *const p __attribute__((pass_object_size(0)))) 337 __attribute__((noinline)) { 338 int i = 0; 339 for (/**/; i < (int)__builtin_object_size(p, 0); ++i) { 340 p[i] = 0; 341 } 342 return i; 343 } 344 345 int main() { 346 char chars[100]; 347 int n = bzero1(&chars[0]); 348 assert(n == sizeof(chars)); 349 return 0; 350 } 351 352 If successfully evaluating ``__builtin_object_size(param, Type)`` at the 353 callsite is not possible, then the "failed" value is passed in. So, using the 354 definition of ``bzero1`` from above, the following code would exit cleanly: 355 356 .. code-block:: c 357 358 int main2(int argc, char *argv[]) { 359 int n = bzero1(argv); 360 assert(n == -1); 361 return 0; 362 } 363 364 ``pass_object_size`` plays a part in overload resolution. If two overload 365 candidates are otherwise equally good, then the overload with one or more 366 parameters with ``pass_object_size`` is preferred. This implies that the choice 367 between two identical overloads both with ``pass_object_size`` on one or more 368 parameters will always be ambiguous; for this reason, having two such overloads 369 is illegal. For example: 370 371 .. code-block:: c++ 372 373 #define PS(N) __attribute__((pass_object_size(N))) 374 // OK 375 void Foo(char *a, char *b); // Overload A 376 // OK -- overload A has no parameters with pass_object_size. 377 void Foo(char *a PS(0), char *b PS(0)); // Overload B 378 // Error -- Same signature (sans pass_object_size) as overload B, and both 379 // overloads have one or more parameters with the pass_object_size attribute. 380 void Foo(void *a PS(0), void *b); 381 382 // OK 383 void Bar(void *a PS(0)); // Overload C 384 // OK 385 void Bar(char *c PS(1)); // Overload D 386 387 void main() { 388 char known[10], *unknown; 389 Foo(unknown, unknown); // Calls overload B 390 Foo(known, unknown); // Calls overload B 391 Foo(unknown, known); // Calls overload B 392 Foo(known, known); // Calls overload B 393 394 Bar(known); // Calls overload D 395 Bar(unknown); // Calls overload D 396 } 397 398 Currently, ``pass_object_size`` is a bit restricted in terms of its usage: 399 400 * Only one use of ``pass_object_size`` is allowed per parameter. 401 402 * It is an error to take the address of a function with ``pass_object_size`` on 403 any of its parameters. If you wish to do this, you can create an overload 404 without ``pass_object_size`` on any parameters. 405 406 * It is an error to apply the ``pass_object_size`` attribute to parameters that 407 are not pointers. Additionally, any parameter that ``pass_object_size`` is 408 applied to must be marked ``const`` at its function's definition. 409 }]; 410 } 411 412 def OverloadableDocs : Documentation { 413 let Category = DocCatFunction; 414 let Content = [{ 415 Clang provides support for C++ function overloading in C. Function overloading 416 in C is introduced using the ``overloadable`` attribute. For example, one 417 might provide several overloaded versions of a ``tgsin`` function that invokes 418 the appropriate standard function computing the sine of a value with ``float``, 419 ``double``, or ``long double`` precision: 420 421 .. code-block:: c 422 423 #include <math.h> 424 float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } 425 double __attribute__((overloadable)) tgsin(double x) { return sin(x); } 426 long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } 427 428 Given these declarations, one can call ``tgsin`` with a ``float`` value to 429 receive a ``float`` result, with a ``double`` to receive a ``double`` result, 430 etc. Function overloading in C follows the rules of C++ function overloading 431 to pick the best overload given the call arguments, with a few C-specific 432 semantics: 433 434 * Conversion from ``float`` or ``double`` to ``long double`` is ranked as a 435 floating-point promotion (per C99) rather than as a floating-point conversion 436 (as in C++). 437 438 * A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is 439 considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are 440 compatible types. 441 442 * A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` 443 and ``U`` are compatible types. This conversion is given "conversion" rank. 444 445 The declaration of ``overloadable`` functions is restricted to function 446 declarations and definitions. Most importantly, if any function with a given 447 name is given the ``overloadable`` attribute, then all function declarations 448 and definitions with that name (and in that scope) must have the 449 ``overloadable`` attribute. This rule even applies to redeclarations of 450 functions whose original declaration had the ``overloadable`` attribute, e.g., 451 452 .. code-block:: c 453 454 int f(int) __attribute__((overloadable)); 455 float f(float); // error: declaration of "f" must have the "overloadable" attribute 456 457 int g(int) __attribute__((overloadable)); 458 int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute 459 460 Functions marked ``overloadable`` must have prototypes. Therefore, the 461 following code is ill-formed: 462 463 .. code-block:: c 464 465 int h() __attribute__((overloadable)); // error: h does not have a prototype 466 467 However, ``overloadable`` functions are allowed to use a ellipsis even if there 468 are no named parameters (as is permitted in C++). This feature is particularly 469 useful when combined with the ``unavailable`` attribute: 470 471 .. code-block:: c++ 472 473 void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error 474 475 Functions declared with the ``overloadable`` attribute have their names mangled 476 according to the same rules as C++ function names. For example, the three 477 ``tgsin`` functions in our motivating example get the mangled names 478 ``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two 479 caveats to this use of name mangling: 480 481 * Future versions of Clang may change the name mangling of functions overloaded 482 in C, so you should not depend on an specific mangling. To be completely 483 safe, we strongly urge the use of ``static inline`` with ``overloadable`` 484 functions. 485 486 * The ``overloadable`` attribute has almost no meaning when used in C++, 487 because names will already be mangled and functions are already overloadable. 488 However, when an ``overloadable`` function occurs within an ``extern "C"`` 489 linkage specification, it's name *will* be mangled in the same way as it 490 would in C. 491 492 Query for this feature with ``__has_extension(attribute_overloadable)``. 493 }]; 494 } 495 496 def ObjCMethodFamilyDocs : Documentation { 497 let Category = DocCatFunction; 498 let Content = [{ 499 Many methods in Objective-C have conventional meanings determined by their 500 selectors. It is sometimes useful to be able to mark a method as having a 501 particular conventional meaning despite not having the right selector, or as 502 not having the conventional meaning that its selector would suggest. For these 503 use cases, we provide an attribute to specifically describe the "method family" 504 that a method belongs to. 505 506 **Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of 507 ``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This 508 attribute can only be placed at the end of a method declaration: 509 510 .. code-block:: objc 511 512 - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); 513 514 Users who do not wish to change the conventional meaning of a method, and who 515 merely want to document its non-standard retain and release semantics, should 516 use the retaining behavior attributes (``ns_returns_retained``, 517 ``ns_returns_not_retained``, etc). 518 519 Query for this feature with ``__has_attribute(objc_method_family)``. 520 }]; 521 } 522 523 def NoDebugDocs : Documentation { 524 let Category = DocCatVariable; 525 let Content = [{ 526 The ``nodebug`` attribute allows you to suppress debugging information for a 527 function or method, or for a variable that is not a parameter or a non-static 528 data member. 529 }]; 530 } 531 532 def NoDuplicateDocs : Documentation { 533 let Category = DocCatFunction; 534 let Content = [{ 535 The ``noduplicate`` attribute can be placed on function declarations to control 536 whether function calls to this function can be duplicated or not as a result of 537 optimizations. This is required for the implementation of functions with 538 certain special requirements, like the OpenCL "barrier" function, that might 539 need to be run concurrently by all the threads that are executing in lockstep 540 on the hardware. For example this attribute applied on the function 541 "nodupfunc" in the code below avoids that: 542 543 .. code-block:: c 544 545 void nodupfunc() __attribute__((noduplicate)); 546 // Setting it as a C++11 attribute is also valid 547 // void nodupfunc() [[clang::noduplicate]]; 548 void foo(); 549 void bar(); 550 551 nodupfunc(); 552 if (a > n) { 553 foo(); 554 } else { 555 bar(); 556 } 557 558 gets possibly modified by some optimizations into code similar to this: 559 560 .. code-block:: c 561 562 if (a > n) { 563 nodupfunc(); 564 foo(); 565 } else { 566 nodupfunc(); 567 bar(); 568 } 569 570 where the call to "nodupfunc" is duplicated and sunk into the two branches 571 of the condition. 572 }]; 573 } 574 575 def NoSplitStackDocs : Documentation { 576 let Category = DocCatFunction; 577 let Content = [{ 578 The ``no_split_stack`` attribute disables the emission of the split stack 579 preamble for a particular function. It has no effect if ``-fsplit-stack`` 580 is not specified. 581 }]; 582 } 583 584 def ObjCRequiresSuperDocs : Documentation { 585 let Category = DocCatFunction; 586 let Content = [{ 587 Some Objective-C classes allow a subclass to override a particular method in a 588 parent class but expect that the overriding method also calls the overridden 589 method in the parent class. For these cases, we provide an attribute to 590 designate that a method requires a "call to ``super``" in the overriding 591 method in the subclass. 592 593 **Usage**: ``__attribute__((objc_requires_super))``. This attribute can only 594 be placed at the end of a method declaration: 595 596 .. code-block:: objc 597 598 - (void)foo __attribute__((objc_requires_super)); 599 600 This attribute can only be applied the method declarations within a class, and 601 not a protocol. Currently this attribute does not enforce any placement of 602 where the call occurs in the overriding method (such as in the case of 603 ``-dealloc`` where the call must appear at the end). It checks only that it 604 exists. 605 606 Note that on both OS X and iOS that the Foundation framework provides a 607 convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this 608 attribute: 609 610 .. code-block:: objc 611 612 - (void)foo NS_REQUIRES_SUPER; 613 614 This macro is conditionally defined depending on the compiler's support for 615 this attribute. If the compiler does not support the attribute the macro 616 expands to nothing. 617 618 Operationally, when a method has this annotation the compiler will warn if the 619 implementation of an override in a subclass does not call super. For example: 620 621 .. code-block:: objc 622 623 warning: method possibly missing a [super AnnotMeth] call 624 - (void) AnnotMeth{}; 625 ^ 626 }]; 627 } 628 629 def ObjCRuntimeNameDocs : Documentation { 630 let Category = DocCatFunction; 631 let Content = [{ 632 By default, the Objective-C interface or protocol identifier is used 633 in the metadata name for that object. The `objc_runtime_name` 634 attribute allows annotated interfaces or protocols to use the 635 specified string argument in the object's metadata name instead of the 636 default name. 637 638 **Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute 639 can only be placed before an @protocol or @interface declaration: 640 641 .. code-block:: objc 642 643 __attribute__((objc_runtime_name("MyLocalName"))) 644 @interface Message 645 @end 646 647 }]; 648 } 649 650 def ObjCRuntimeVisibleDocs : Documentation { 651 let Category = DocCatFunction; 652 let Content = [{ 653 This attribute specifies that the Objective-C class to which it applies is visible to the Objective-C runtime but not to the linker. Classes annotated with this attribute cannot be subclassed and cannot have categories defined for them. 654 }]; 655 } 656 657 def ObjCBoxableDocs : Documentation { 658 let Category = DocCatFunction; 659 let Content = [{ 660 Structs and unions marked with the ``objc_boxable`` attribute can be used 661 with the Objective-C boxed expression syntax, ``@(...)``. 662 663 **Usage**: ``__attribute__((objc_boxable))``. This attribute 664 can only be placed on a declaration of a trivially-copyable struct or union: 665 666 .. code-block:: objc 667 668 struct __attribute__((objc_boxable)) some_struct { 669 int i; 670 }; 671 union __attribute__((objc_boxable)) some_union { 672 int i; 673 float f; 674 }; 675 typedef struct __attribute__((objc_boxable)) _some_struct some_struct; 676 677 // ... 678 679 some_struct ss; 680 NSValue *boxed = @(ss); 681 682 }]; 683 } 684 685 def AvailabilityDocs : Documentation { 686 let Category = DocCatFunction; 687 let Content = [{ 688 The ``availability`` attribute can be placed on declarations to describe the 689 lifecycle of that declaration relative to operating system versions. Consider 690 the function declaration for a hypothetical function ``f``: 691 692 .. code-block:: c++ 693 694 void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7))); 695 696 The availability attribute states that ``f`` was introduced in Mac OS X 10.4, 697 deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information 698 is used by Clang to determine when it is safe to use ``f``: for example, if 699 Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` 700 succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call 701 succeeds but Clang emits a warning specifying that the function is deprecated. 702 Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call 703 fails because ``f()`` is no longer available. 704 705 The availability attribute is a comma-separated list starting with the 706 platform name and then including clauses specifying important milestones in the 707 declaration's lifetime (in any order) along with additional information. Those 708 clauses can be: 709 710 introduced=\ *version* 711 The first version in which this declaration was introduced. 712 713 deprecated=\ *version* 714 The first version in which this declaration was deprecated, meaning that 715 users should migrate away from this API. 716 717 obsoleted=\ *version* 718 The first version in which this declaration was obsoleted, meaning that it 719 was removed completely and can no longer be used. 720 721 unavailable 722 This declaration is never available on this platform. 723 724 message=\ *string-literal* 725 Additional message text that Clang will provide when emitting a warning or 726 error about use of a deprecated or obsoleted declaration. Useful to direct 727 users to replacement APIs. 728 729 replacement=\ *string-literal* 730 Additional message text that Clang will use to provide Fix-It when emitting 731 a warning about use of a deprecated declaration. The Fix-It will replace 732 the deprecated declaration with the new declaration specified. 733 734 Multiple availability attributes can be placed on a declaration, which may 735 correspond to different platforms. Only the availability attribute with the 736 platform corresponding to the target platform will be used; any others will be 737 ignored. If no availability attribute specifies availability for the current 738 target platform, the availability attributes are ignored. Supported platforms 739 are: 740 741 ``ios`` 742 Apple's iOS operating system. The minimum deployment target is specified by 743 the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` 744 command-line arguments. 745 746 ``macos`` 747 Apple's Mac OS X operating system. The minimum deployment target is 748 specified by the ``-mmacosx-version-min=*version*`` command-line argument. 749 ``macosx`` is supported for backward-compatibility reasons, but it is 750 deprecated. 751 752 ``tvos`` 753 Apple's tvOS operating system. The minimum deployment target is specified by 754 the ``-mtvos-version-min=*version*`` command-line argument. 755 756 ``watchos`` 757 Apple's watchOS operating system. The minimum deployment target is specified by 758 the ``-mwatchos-version-min=*version*`` command-line argument. 759 760 A declaration can typically be used even when deploying back to a platform 761 version prior to when the declaration was introduced. When this happens, the 762 declaration is `weakly linked 763 <https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_, 764 as if the ``weak_import`` attribute were added to the declaration. A 765 weakly-linked declaration may or may not be present a run-time, and a program 766 can determine whether the declaration is present by checking whether the 767 address of that declaration is non-NULL. 768 769 The flag ``strict`` disallows using API when deploying back to a 770 platform version prior to when the declaration was introduced. An 771 attempt to use such API before its introduction causes a hard error. 772 Weakly-linking is almost always a better API choice, since it allows 773 users to query availability at runtime. 774 775 If there are multiple declarations of the same entity, the availability 776 attributes must either match on a per-platform basis or later 777 declarations must not have availability attributes for that 778 platform. For example: 779 780 .. code-block:: c 781 782 void g(void) __attribute__((availability(macos,introduced=10.4))); 783 void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches 784 void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform 785 void g(void); // okay, inherits both macos and ios availability from above. 786 void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch 787 788 When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: 789 790 .. code-block:: objc 791 792 @interface A 793 - (id)method __attribute__((availability(macos,introduced=10.4))); 794 - (id)method2 __attribute__((availability(macos,introduced=10.4))); 795 @end 796 797 @interface B : A 798 - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later 799 - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4 800 @end 801 }]; 802 } 803 804 def WarnMaybeUnusedDocs : Documentation { 805 let Category = DocCatVariable; 806 let Heading = "maybe_unused, unused, gnu::unused"; 807 let Content = [{ 808 When passing the ``-Wunused`` flag to Clang, entities that are unused by the 809 program may be diagnosed. The ``[[maybe_unused]]`` (or 810 ``__attribute__((unused))``) attribute can be used to silence such diagnostics 811 when the entity cannot be removed. For instance, a local variable may exist 812 solely for use in an ``assert()`` statement, which makes the local variable 813 unused when ``NDEBUG`` is defined. 814 815 The attribute may be applied to the declaration of a class, a typedef, a 816 variable, a function or method, a function parameter, an enumeration, an 817 enumerator, a non-static data member, or a label. 818 819 .. code-block: c++ 820 #include <cassert> 821 822 [[maybe_unused]] void f([[maybe_unused]] bool thing1, 823 [[maybe_unused]] bool thing2) { 824 [[maybe_unused]] bool b = thing1 && thing2; 825 assert(b); 826 } 827 }]; 828 } 829 830 def WarnUnusedResultsDocs : Documentation { 831 let Category = DocCatFunction; 832 let Heading = "nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result"; 833 let Content = [{ 834 Clang supports the ability to diagnose when the results of a function call 835 expression are discarded under suspicious circumstances. A diagnostic is 836 generated when a function or its return type is marked with ``[[nodiscard]]`` 837 (or ``__attribute__((warn_unused_result))``) and the function call appears as a 838 potentially-evaluated discarded-value expression that is not explicitly cast to 839 `void`. 840 841 .. code-block: c++ 842 struct [[nodiscard]] error_info { /*...*/ }; 843 error_info enable_missile_safety_mode(); 844 845 void launch_missiles(); 846 void test_missiles() { 847 enable_missile_safety_mode(); // diagnoses 848 launch_missiles(); 849 } 850 error_info &foo(); 851 void f() { foo(); } // Does not diagnose, error_info is a reference. 852 }]; 853 } 854 855 def FallthroughDocs : Documentation { 856 let Category = DocCatStmt; 857 let Heading = "fallthrough, clang::fallthrough"; 858 let Content = [{ 859 The ``fallthrough`` (or ``clang::fallthrough``) attribute is used 860 to annotate intentional fall-through 861 between switch labels. It can only be applied to a null statement placed at a 862 point of execution between any statement and the next switch label. It is 863 common to mark these places with a specific comment, but this attribute is 864 meant to replace comments with a more strict annotation, which can be checked 865 by the compiler. This attribute doesn't change semantics of the code and can 866 be used wherever an intended fall-through occurs. It is designed to mimic 867 control-flow statements like ``break;``, so it can be placed in most places 868 where ``break;`` can, but only if there are no statements on the execution path 869 between it and the next switch label. 870 871 By default, Clang does not warn on unannotated fallthrough from one ``switch`` 872 case to another. Diagnostics on fallthrough without a corresponding annotation 873 can be enabled with the ``-Wimplicit-fallthrough`` argument. 874 875 Here is an example: 876 877 .. code-block:: c++ 878 879 // compile with -Wimplicit-fallthrough 880 switch (n) { 881 case 22: 882 case 33: // no warning: no statements between case labels 883 f(); 884 case 44: // warning: unannotated fall-through 885 g(); 886 [[clang::fallthrough]]; 887 case 55: // no warning 888 if (x) { 889 h(); 890 break; 891 } 892 else { 893 i(); 894 [[clang::fallthrough]]; 895 } 896 case 66: // no warning 897 p(); 898 [[clang::fallthrough]]; // warning: fallthrough annotation does not 899 // directly precede case label 900 q(); 901 case 77: // warning: unannotated fall-through 902 r(); 903 } 904 }]; 905 } 906 907 def ARMInterruptDocs : Documentation { 908 let Category = DocCatFunction; 909 let Content = [{ 910 Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on 911 ARM targets. This attribute may be attached to a function definition and 912 instructs the backend to generate appropriate function entry/exit code so that 913 it can be used directly as an interrupt service routine. 914 915 The parameter passed to the interrupt attribute is optional, but if 916 provided it must be a string literal with one of the following values: "IRQ", 917 "FIQ", "SWI", "ABORT", "UNDEF". 918 919 The semantics are as follows: 920 921 - If the function is AAPCS, Clang instructs the backend to realign the stack to 922 8 bytes on entry. This is a general requirement of the AAPCS at public 923 interfaces, but may not hold when an exception is taken. Doing this allows 924 other AAPCS functions to be called. 925 - If the CPU is M-class this is all that needs to be done since the architecture 926 itself is designed in such a way that functions obeying the normal AAPCS ABI 927 constraints are valid exception handlers. 928 - If the CPU is not M-class, the prologue and epilogue are modified to save all 929 non-banked registers that are used, so that upon return the user-mode state 930 will not be corrupted. Note that to avoid unnecessary overhead, only 931 general-purpose (integer) registers are saved in this way. If VFP operations 932 are needed, that state must be saved manually. 933 934 Specifically, interrupt kinds other than "FIQ" will save all core registers 935 except "lr" and "sp". "FIQ" interrupts will save r0-r7. 936 - If the CPU is not M-class, the return instruction is changed to one of the 937 canonical sequences permitted by the architecture for exception return. Where 938 possible the function itself will make the necessary "lr" adjustments so that 939 the "preferred return address" is selected. 940 941 Unfortunately the compiler is unable to make this guarantee for an "UNDEF" 942 handler, where the offset from "lr" to the preferred return address depends on 943 the execution state of the code which generated the exception. In this case 944 a sequence equivalent to "movs pc, lr" will be used. 945 }]; 946 } 947 948 def MipsInterruptDocs : Documentation { 949 let Category = DocCatFunction; 950 let Content = [{ 951 Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on 952 MIPS targets. This attribute may be attached to a function definition and instructs 953 the backend to generate appropriate function entry/exit code so that it can be used 954 directly as an interrupt service routine. 955 956 By default, the compiler will produce a function prologue and epilogue suitable for 957 an interrupt service routine that handles an External Interrupt Controller (eic) 958 generated interrupt. This behaviour can be explicitly requested with the "eic" 959 argument. 960 961 Otherwise, for use with vectored interrupt mode, the argument passed should be 962 of the form "vector=LEVEL" where LEVEL is one of the following values: 963 "sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will 964 then set the interrupt mask to the corresponding level which will mask all 965 interrupts up to and including the argument. 966 967 The semantics are as follows: 968 969 - The prologue is modified so that the Exception Program Counter (EPC) and 970 Status coprocessor registers are saved to the stack. The interrupt mask is 971 set so that the function can only be interrupted by a higher priority 972 interrupt. The epilogue will restore the previous values of EPC and Status. 973 974 - The prologue and epilogue are modified to save and restore all non-kernel 975 registers as necessary. 976 977 - The FPU is disabled in the prologue, as the floating pointer registers are not 978 spilled to the stack. 979 980 - The function return sequence is changed to use an exception return instruction. 981 982 - The parameter sets the interrupt mask for the function corresponding to the 983 interrupt level specified. If no mask is specified the interrupt mask 984 defaults to "eic". 985 }]; 986 } 987 988 def TargetDocs : Documentation { 989 let Category = DocCatFunction; 990 let Content = [{ 991 Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute. 992 This attribute may be attached to a function definition and instructs 993 the backend to use different code generation options than were passed on the 994 command line. 995 996 The current set of options correspond to the existing "subtarget features" for 997 the target with or without a "-mno-" in front corresponding to the absence 998 of the feature, as well as ``arch="CPU"`` which will change the default "CPU" 999 for the function. 1000 1001 Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2", 1002 "avx", "xop" and largely correspond to the machine specific options handled by 1003 the front end. 1004 }]; 1005 } 1006 1007 def DocCatAMDGPURegisterAttributes : 1008 DocumentationCategory<"AMD GPU Register Attributes"> { 1009 let Content = [{ 1010 Clang supports attributes for controlling register usage on AMD GPU 1011 targets. These attributes may be attached to a kernel function 1012 definition and is an optimization hint to the backend for the maximum 1013 number of registers to use. This is useful in cases where register 1014 limited occupancy is known to be an important factor for the 1015 performance for the kernel. 1016 1017 The semantics are as follows: 1018 1019 - The backend will attempt to limit the number of used registers to 1020 the specified value, but the exact number used is not 1021 guaranteed. The number used may be rounded up to satisfy the 1022 allocation requirements or ABI constraints of the subtarget. For 1023 example, on Southern Islands VGPRs may only be allocated in 1024 increments of 4, so requesting a limit of 39 VGPRs will really 1025 attempt to use up to 40. Requesting more registers than the 1026 subtarget supports will truncate to the maximum allowed. The backend 1027 may also use fewer registers than requested whenever possible. 1028 1029 - 0 implies the default no limit on register usage. 1030 1031 - Ignored on older VLIW subtargets which did not have separate scalar 1032 and vector registers, R600 through Northern Islands. 1033 1034 }]; 1035 } 1036 1037 1038 def AMDGPUNumVGPRDocs : Documentation { 1039 let Category = DocCatAMDGPURegisterAttributes; 1040 let Content = [{ 1041 Clang supports the 1042 ``__attribute__((amdgpu_num_vgpr(<num_registers>)))`` attribute on AMD 1043 Southern Islands GPUs and later for controlling the number of vector 1044 registers. A typical value would be between 4 and 256 in increments 1045 of 4. 1046 }]; 1047 } 1048 1049 def AMDGPUNumSGPRDocs : Documentation { 1050 let Category = DocCatAMDGPURegisterAttributes; 1051 let Content = [{ 1052 1053 Clang supports the 1054 ``__attribute__((amdgpu_num_sgpr(<num_registers>)))`` attribute on AMD 1055 Southern Islands GPUs and later for controlling the number of scalar 1056 registers. A typical value would be between 8 and 104 in increments of 1057 8. 1058 1059 Due to common instruction constraints, an additional 2-4 SGPRs are 1060 typically required for internal use depending on features used. This 1061 value is a hint for the total number of SGPRs to use, and not the 1062 number of user SGPRs, so no special consideration needs to be given 1063 for these. 1064 }]; 1065 } 1066 1067 def DocCatCallingConvs : DocumentationCategory<"Calling Conventions"> { 1068 let Content = [{ 1069 Clang supports several different calling conventions, depending on the target 1070 platform and architecture. The calling convention used for a function determines 1071 how parameters are passed, how results are returned to the caller, and other 1072 low-level details of calling a function. 1073 }]; 1074 } 1075 1076 def PcsDocs : Documentation { 1077 let Category = DocCatCallingConvs; 1078 let Content = [{ 1079 On ARM targets, this attribute can be used to select calling conventions 1080 similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and 1081 "aapcs-vfp". 1082 }]; 1083 } 1084 1085 def RegparmDocs : Documentation { 1086 let Category = DocCatCallingConvs; 1087 let Content = [{ 1088 On 32-bit x86 targets, the regparm attribute causes the compiler to pass 1089 the first three integer parameters in EAX, EDX, and ECX instead of on the 1090 stack. This attribute has no effect on variadic functions, and all parameters 1091 are passed via the stack as normal. 1092 }]; 1093 } 1094 1095 def SysVABIDocs : Documentation { 1096 let Category = DocCatCallingConvs; 1097 let Content = [{ 1098 On Windows x86_64 targets, this attribute changes the calling convention of a 1099 function to match the default convention used on Sys V targets such as Linux, 1100 Mac, and BSD. This attribute has no effect on other targets. 1101 }]; 1102 } 1103 1104 def MSABIDocs : Documentation { 1105 let Category = DocCatCallingConvs; 1106 let Content = [{ 1107 On non-Windows x86_64 targets, this attribute changes the calling convention of 1108 a function to match the default convention used on Windows x86_64. This 1109 attribute has no effect on Windows targets or non-x86_64 targets. 1110 }]; 1111 } 1112 1113 def StdCallDocs : Documentation { 1114 let Category = DocCatCallingConvs; 1115 let Content = [{ 1116 On 32-bit x86 targets, this attribute changes the calling convention of a 1117 function to clear parameters off of the stack on return. This convention does 1118 not support variadic calls or unprototyped functions in C, and has no effect on 1119 x86_64 targets. This calling convention is used widely by the Windows API and 1120 COM applications. See the documentation for `__stdcall`_ on MSDN. 1121 1122 .. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx 1123 }]; 1124 } 1125 1126 def FastCallDocs : Documentation { 1127 let Category = DocCatCallingConvs; 1128 let Content = [{ 1129 On 32-bit x86 targets, this attribute changes the calling convention of a 1130 function to use ECX and EDX as register parameters and clear parameters off of 1131 the stack on return. This convention does not support variadic calls or 1132 unprototyped functions in C, and has no effect on x86_64 targets. This calling 1133 convention is supported primarily for compatibility with existing code. Users 1134 seeking register parameters should use the ``regparm`` attribute, which does 1135 not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN. 1136 1137 .. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx 1138 }]; 1139 } 1140 1141 def ThisCallDocs : Documentation { 1142 let Category = DocCatCallingConvs; 1143 let Content = [{ 1144 On 32-bit x86 targets, this attribute changes the calling convention of a 1145 function to use ECX for the first parameter (typically the implicit ``this`` 1146 parameter of C++ methods) and clear parameters off of the stack on return. This 1147 convention does not support variadic calls or unprototyped functions in C, and 1148 has no effect on x86_64 targets. See the documentation for `__thiscall`_ on 1149 MSDN. 1150 1151 .. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx 1152 }]; 1153 } 1154 1155 def VectorCallDocs : Documentation { 1156 let Category = DocCatCallingConvs; 1157 let Content = [{ 1158 On 32-bit x86 *and* x86_64 targets, this attribute changes the calling 1159 convention of a function to pass vector parameters in SSE registers. 1160 1161 On 32-bit x86 targets, this calling convention is similar to ``__fastcall``. 1162 The first two integer parameters are passed in ECX and EDX. Subsequent integer 1163 parameters are passed in memory, and callee clears the stack. On x86_64 1164 targets, the callee does *not* clear the stack, and integer parameters are 1165 passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling 1166 convention. 1167 1168 On both 32-bit x86 and x86_64 targets, vector and floating point arguments are 1169 passed in XMM0-XMM5. Homogenous vector aggregates of up to four elements are 1170 passed in sequential SSE registers if enough are available. If AVX is enabled, 1171 256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that 1172 cannot be passed in registers for any reason is passed by reference, which 1173 allows the caller to align the parameter memory. 1174 1175 See the documentation for `__vectorcall`_ on MSDN for more details. 1176 1177 .. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx 1178 }]; 1179 } 1180 1181 def DocCatConsumed : DocumentationCategory<"Consumed Annotation Checking"> { 1182 let Content = [{ 1183 Clang supports additional attributes for checking basic resource management 1184 properties, specifically for unique objects that have a single owning reference. 1185 The following attributes are currently supported, although **the implementation 1186 for these annotations is currently in development and are subject to change.** 1187 }]; 1188 } 1189 1190 def SetTypestateDocs : Documentation { 1191 let Category = DocCatConsumed; 1192 let Content = [{ 1193 Annotate methods that transition an object into a new state with 1194 ``__attribute__((set_typestate(new_state)))``. The new state must be 1195 unconsumed, consumed, or unknown. 1196 }]; 1197 } 1198 1199 def CallableWhenDocs : Documentation { 1200 let Category = DocCatConsumed; 1201 let Content = [{ 1202 Use ``__attribute__((callable_when(...)))`` to indicate what states a method 1203 may be called in. Valid states are unconsumed, consumed, or unknown. Each 1204 argument to this attribute must be a quoted string. E.g.: 1205 1206 ``__attribute__((callable_when("unconsumed", "unknown")))`` 1207 }]; 1208 } 1209 1210 def TestTypestateDocs : Documentation { 1211 let Category = DocCatConsumed; 1212 let Content = [{ 1213 Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method 1214 returns true if the object is in the specified state.. 1215 }]; 1216 } 1217 1218 def ParamTypestateDocs : Documentation { 1219 let Category = DocCatConsumed; 1220 let Content = [{ 1221 This attribute specifies expectations about function parameters. Calls to an 1222 function with annotated parameters will issue a warning if the corresponding 1223 argument isn't in the expected state. The attribute is also used to set the 1224 initial state of the parameter when analyzing the function's body. 1225 }]; 1226 } 1227 1228 def ReturnTypestateDocs : Documentation { 1229 let Category = DocCatConsumed; 1230 let Content = [{ 1231 The ``return_typestate`` attribute can be applied to functions or parameters. 1232 When applied to a function the attribute specifies the state of the returned 1233 value. The function's body is checked to ensure that it always returns a value 1234 in the specified state. On the caller side, values returned by the annotated 1235 function are initialized to the given state. 1236 1237 When applied to a function parameter it modifies the state of an argument after 1238 a call to the function returns. The function's body is checked to ensure that 1239 the parameter is in the expected state before returning. 1240 }]; 1241 } 1242 1243 def ConsumableDocs : Documentation { 1244 let Category = DocCatConsumed; 1245 let Content = [{ 1246 Each ``class`` that uses any of the typestate annotations must first be marked 1247 using the ``consumable`` attribute. Failure to do so will result in a warning. 1248 1249 This attribute accepts a single parameter that must be one of the following: 1250 ``unknown``, ``consumed``, or ``unconsumed``. 1251 }]; 1252 } 1253 1254 def NoSanitizeDocs : Documentation { 1255 let Category = DocCatFunction; 1256 let Content = [{ 1257 Use the ``no_sanitize`` attribute on a function declaration to specify 1258 that a particular instrumentation or set of instrumentations should not be 1259 applied to that function. The attribute takes a list of string literals, 1260 which have the same meaning as values accepted by the ``-fno-sanitize=`` 1261 flag. For example, ``__attribute__((no_sanitize("address", "thread")))`` 1262 specifies that AddressSanitizer and ThreadSanitizer should not be applied 1263 to the function. 1264 1265 See :ref:`Controlling Code Generation <controlling-code-generation>` for a 1266 full list of supported sanitizer flags. 1267 }]; 1268 } 1269 1270 def NoSanitizeAddressDocs : Documentation { 1271 let Category = DocCatFunction; 1272 // This function has multiple distinct spellings, and so it requires a custom 1273 // heading to be specified. The most common spelling is sufficient. 1274 let Heading = "no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)"; 1275 let Content = [{ 1276 .. _langext-address_sanitizer: 1277 1278 Use ``__attribute__((no_sanitize_address))`` on a function declaration to 1279 specify that address safety instrumentation (e.g. AddressSanitizer) should 1280 not be applied to that function. 1281 }]; 1282 } 1283 1284 def NoSanitizeThreadDocs : Documentation { 1285 let Category = DocCatFunction; 1286 let Heading = "no_sanitize_thread"; 1287 let Content = [{ 1288 .. _langext-thread_sanitizer: 1289 1290 Use ``__attribute__((no_sanitize_thread))`` on a function declaration to 1291 specify that checks for data races on plain (non-atomic) memory accesses should 1292 not be inserted by ThreadSanitizer. The function is still instrumented by the 1293 tool to avoid false positives and provide meaningful stack traces. 1294 }]; 1295 } 1296 1297 def NoSanitizeMemoryDocs : Documentation { 1298 let Category = DocCatFunction; 1299 let Heading = "no_sanitize_memory"; 1300 let Content = [{ 1301 .. _langext-memory_sanitizer: 1302 1303 Use ``__attribute__((no_sanitize_memory))`` on a function declaration to 1304 specify that checks for uninitialized memory should not be inserted 1305 (e.g. by MemorySanitizer). The function may still be instrumented by the tool 1306 to avoid false positives in other places. 1307 }]; 1308 } 1309 1310 def DocCatTypeSafety : DocumentationCategory<"Type Safety Checking"> { 1311 let Content = [{ 1312 Clang supports additional attributes to enable checking type safety properties 1313 that can't be enforced by the C type system. Use cases include: 1314 1315 * MPI library implementations, where these attributes enable checking that 1316 the buffer type matches the passed ``MPI_Datatype``; 1317 * for HDF5 library there is a similar use case to MPI; 1318 * checking types of variadic functions' arguments for functions like 1319 ``fcntl()`` and ``ioctl()``. 1320 1321 You can detect support for these attributes with ``__has_attribute()``. For 1322 example: 1323 1324 .. code-block:: c++ 1325 1326 #if defined(__has_attribute) 1327 # if __has_attribute(argument_with_type_tag) && \ 1328 __has_attribute(pointer_with_type_tag) && \ 1329 __has_attribute(type_tag_for_datatype) 1330 # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) 1331 /* ... other macros ... */ 1332 # endif 1333 #endif 1334 1335 #if !defined(ATTR_MPI_PWT) 1336 # define ATTR_MPI_PWT(buffer_idx, type_idx) 1337 #endif 1338 1339 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 1340 ATTR_MPI_PWT(1,3); 1341 }]; 1342 } 1343 1344 def ArgumentWithTypeTagDocs : Documentation { 1345 let Category = DocCatTypeSafety; 1346 let Heading = "argument_with_type_tag"; 1347 let Content = [{ 1348 Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, 1349 type_tag_idx)))`` on a function declaration to specify that the function 1350 accepts a type tag that determines the type of some other argument. 1351 ``arg_kind`` is an identifier that should be used when annotating all 1352 applicable type tags. 1353 1354 This attribute is primarily useful for checking arguments of variadic functions 1355 (``pointer_with_type_tag`` can be used in most non-variadic cases). 1356 1357 For example: 1358 1359 .. code-block:: c++ 1360 1361 int fcntl(int fd, int cmd, ...) 1362 __attribute__(( argument_with_type_tag(fcntl,3,2) )); 1363 }]; 1364 } 1365 1366 def PointerWithTypeTagDocs : Documentation { 1367 let Category = DocCatTypeSafety; 1368 let Heading = "pointer_with_type_tag"; 1369 let Content = [{ 1370 Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` 1371 on a function declaration to specify that the function accepts a type tag that 1372 determines the pointee type of some other pointer argument. 1373 1374 For example: 1375 1376 .. code-block:: c++ 1377 1378 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 1379 __attribute__(( pointer_with_type_tag(mpi,1,3) )); 1380 }]; 1381 } 1382 1383 def TypeTagForDatatypeDocs : Documentation { 1384 let Category = DocCatTypeSafety; 1385 let Content = [{ 1386 Clang supports annotating type tags of two forms. 1387 1388 * **Type tag that is an expression containing a reference to some declared 1389 identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a 1390 declaration with that identifier: 1391 1392 .. code-block:: c++ 1393 1394 extern struct mpi_datatype mpi_datatype_int 1395 __attribute__(( type_tag_for_datatype(mpi,int) )); 1396 #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) 1397 1398 * **Type tag that is an integral literal.** Introduce a ``static const`` 1399 variable with a corresponding initializer value and attach 1400 ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, 1401 for example: 1402 1403 .. code-block:: c++ 1404 1405 #define MPI_INT ((MPI_Datatype) 42) 1406 static const MPI_Datatype mpi_datatype_int 1407 __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 1408 1409 The attribute also accepts an optional third argument that determines how the 1410 expression is compared to the type tag. There are two supported flags: 1411 1412 * ``layout_compatible`` will cause types to be compared according to 1413 layout-compatibility rules (C++11 [class.mem] p 17, 18). This is 1414 implemented to support annotating types like ``MPI_DOUBLE_INT``. 1415 1416 For example: 1417 1418 .. code-block:: c++ 1419 1420 /* In mpi.h */ 1421 struct internal_mpi_double_int { double d; int i; }; 1422 extern struct mpi_datatype mpi_datatype_double_int 1423 __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); 1424 1425 #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) 1426 1427 /* In user code */ 1428 struct my_pair { double a; int b; }; 1429 struct my_pair *buffer; 1430 MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning 1431 1432 struct my_int_pair { int a; int b; } 1433 struct my_int_pair *buffer2; 1434 MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element 1435 // type 'struct my_int_pair' 1436 // doesn't match specified MPI_Datatype 1437 1438 * ``must_be_null`` specifies that the expression should be a null pointer 1439 constant, for example: 1440 1441 .. code-block:: c++ 1442 1443 /* In mpi.h */ 1444 extern struct mpi_datatype mpi_datatype_null 1445 __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); 1446 1447 #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) 1448 1449 /* In user code */ 1450 MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL 1451 // was specified but buffer 1452 // is not a null pointer 1453 }]; 1454 } 1455 1456 def FlattenDocs : Documentation { 1457 let Category = DocCatFunction; 1458 let Content = [{ 1459 The ``flatten`` attribute causes calls within the attributed function to 1460 be inlined unless it is impossible to do so, for example if the body of the 1461 callee is unavailable or if the callee has the ``noinline`` attribute. 1462 }]; 1463 } 1464 1465 def FormatDocs : Documentation { 1466 let Category = DocCatFunction; 1467 let Content = [{ 1468 1469 Clang supports the ``format`` attribute, which indicates that the function 1470 accepts a ``printf`` or ``scanf``-like format string and corresponding 1471 arguments or a ``va_list`` that contains these arguments. 1472 1473 Please see `GCC documentation about format attribute 1474 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details 1475 about attribute syntax. 1476 1477 Clang implements two kinds of checks with this attribute. 1478 1479 #. Clang checks that the function with the ``format`` attribute is called with 1480 a format string that uses format specifiers that are allowed, and that 1481 arguments match the format string. This is the ``-Wformat`` warning, it is 1482 on by default. 1483 1484 #. Clang checks that the format string argument is a literal string. This is 1485 the ``-Wformat-nonliteral`` warning, it is off by default. 1486 1487 Clang implements this mostly the same way as GCC, but there is a difference 1488 for functions that accept a ``va_list`` argument (for example, ``vprintf``). 1489 GCC does not emit ``-Wformat-nonliteral`` warning for calls to such 1490 functions. Clang does not warn if the format string comes from a function 1491 parameter, where the function is annotated with a compatible attribute, 1492 otherwise it warns. For example: 1493 1494 .. code-block:: c 1495 1496 __attribute__((__format__ (__scanf__, 1, 3))) 1497 void foo(const char* s, char *buf, ...) { 1498 va_list ap; 1499 va_start(ap, buf); 1500 1501 vprintf(s, ap); // warning: format string is not a string literal 1502 } 1503 1504 In this case we warn because ``s`` contains a format string for a 1505 ``scanf``-like function, but it is passed to a ``printf``-like function. 1506 1507 If the attribute is removed, clang still warns, because the format string is 1508 not a string literal. 1509 1510 Another example: 1511 1512 .. code-block:: c 1513 1514 __attribute__((__format__ (__printf__, 1, 3))) 1515 void foo(const char* s, char *buf, ...) { 1516 va_list ap; 1517 va_start(ap, buf); 1518 1519 vprintf(s, ap); // warning 1520 } 1521 1522 In this case Clang does not warn because the format string ``s`` and 1523 the corresponding arguments are annotated. If the arguments are 1524 incorrect, the caller of ``foo`` will receive a warning. 1525 }]; 1526 } 1527 1528 def AlignValueDocs : Documentation { 1529 let Category = DocCatType; 1530 let Content = [{ 1531 The align_value attribute can be added to the typedef of a pointer type or the 1532 declaration of a variable of pointer or reference type. It specifies that the 1533 pointer will point to, or the reference will bind to, only objects with at 1534 least the provided alignment. This alignment value must be some positive power 1535 of 2. 1536 1537 .. code-block:: c 1538 1539 typedef double * aligned_double_ptr __attribute__((align_value(64))); 1540 void foo(double & x __attribute__((align_value(128)), 1541 aligned_double_ptr y) { ... } 1542 1543 If the pointer value does not have the specified alignment at runtime, the 1544 behavior of the program is undefined. 1545 }]; 1546 } 1547 1548 def FlagEnumDocs : Documentation { 1549 let Category = DocCatType; 1550 let Content = [{ 1551 This attribute can be added to an enumerator to signal to the compiler that it 1552 is intended to be used as a flag type. This will cause the compiler to assume 1553 that the range of the type includes all of the values that you can get by 1554 manipulating bits of the enumerator when issuing warnings. 1555 }]; 1556 } 1557 1558 def EmptyBasesDocs : Documentation { 1559 let Category = DocCatType; 1560 let Content = [{ 1561 The empty_bases attribute permits the compiler to utilize the 1562 empty-base-optimization more frequently. 1563 This attribute only applies to struct, class, and union types. 1564 It is only supported when using the Microsoft C++ ABI. 1565 }]; 1566 } 1567 1568 def LayoutVersionDocs : Documentation { 1569 let Category = DocCatType; 1570 let Content = [{ 1571 The layout_version attribute requests that the compiler utilize the class 1572 layout rules of a particular compiler version. 1573 This attribute only applies to struct, class, and union types. 1574 It is only supported when using the Microsoft C++ ABI. 1575 }]; 1576 } 1577 1578 def MSInheritanceDocs : Documentation { 1579 let Category = DocCatType; 1580 let Heading = "__single_inhertiance, __multiple_inheritance, __virtual_inheritance"; 1581 let Content = [{ 1582 This collection of keywords is enabled under ``-fms-extensions`` and controls 1583 the pointer-to-member representation used on ``*-*-win32`` targets. 1584 1585 The ``*-*-win32`` targets utilize a pointer-to-member representation which 1586 varies in size and alignment depending on the definition of the underlying 1587 class. 1588 1589 However, this is problematic when a forward declaration is only available and 1590 no definition has been made yet. In such cases, Clang is forced to utilize the 1591 most general representation that is available to it. 1592 1593 These keywords make it possible to use a pointer-to-member representation other 1594 than the most general one regardless of whether or not the definition will ever 1595 be present in the current translation unit. 1596 1597 This family of keywords belong between the ``class-key`` and ``class-name``: 1598 1599 .. code-block:: c++ 1600 1601 struct __single_inheritance S; 1602 int S::*i; 1603 struct S {}; 1604 1605 This keyword can be applied to class templates but only has an effect when used 1606 on full specializations: 1607 1608 .. code-block:: c++ 1609 1610 template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template 1611 template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization 1612 template <> struct __single_inheritance A<int, float>; 1613 1614 Note that choosing an inheritance model less general than strictly necessary is 1615 an error: 1616 1617 .. code-block:: c++ 1618 1619 struct __multiple_inheritance S; // error: inheritance model does not match definition 1620 int S::*i; 1621 struct S {}; 1622 }]; 1623 } 1624 1625 def MSNoVTableDocs : Documentation { 1626 let Category = DocCatType; 1627 let Content = [{ 1628 This attribute can be added to a class declaration or definition to signal to 1629 the compiler that constructors and destructors will not reference the virtual 1630 function table. It is only supported when using the Microsoft C++ ABI. 1631 }]; 1632 } 1633 1634 def OptnoneDocs : Documentation { 1635 let Category = DocCatFunction; 1636 let Content = [{ 1637 The ``optnone`` attribute suppresses essentially all optimizations 1638 on a function or method, regardless of the optimization level applied to 1639 the compilation unit as a whole. This is particularly useful when you 1640 need to debug a particular function, but it is infeasible to build the 1641 entire application without optimization. Avoiding optimization on the 1642 specified function can improve the quality of the debugging information 1643 for that function. 1644 1645 This attribute is incompatible with the ``always_inline`` and ``minsize`` 1646 attributes. 1647 }]; 1648 } 1649 1650 def LoopHintDocs : Documentation { 1651 let Category = DocCatStmt; 1652 let Heading = "#pragma clang loop"; 1653 let Content = [{ 1654 The ``#pragma clang loop`` directive allows loop optimization hints to be 1655 specified for the subsequent loop. The directive allows vectorization, 1656 interleaving, and unrolling to be enabled or disabled. Vector width as well 1657 as interleave and unrolling count can be manually specified. See 1658 `language extensions 1659 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ 1660 for details. 1661 }]; 1662 } 1663 1664 def UnrollHintDocs : Documentation { 1665 let Category = DocCatStmt; 1666 let Heading = "#pragma unroll, #pragma nounroll"; 1667 let Content = [{ 1668 Loop unrolling optimization hints can be specified with ``#pragma unroll`` and 1669 ``#pragma nounroll``. The pragma is placed immediately before a for, while, 1670 do-while, or c++11 range-based for loop. 1671 1672 Specifying ``#pragma unroll`` without a parameter directs the loop unroller to 1673 attempt to fully unroll the loop if the trip count is known at compile time and 1674 attempt to partially unroll the loop if the trip count is not known at compile 1675 time: 1676 1677 .. code-block:: c++ 1678 1679 #pragma unroll 1680 for (...) { 1681 ... 1682 } 1683 1684 Specifying the optional parameter, ``#pragma unroll _value_``, directs the 1685 unroller to unroll the loop ``_value_`` times. The parameter may optionally be 1686 enclosed in parentheses: 1687 1688 .. code-block:: c++ 1689 1690 #pragma unroll 16 1691 for (...) { 1692 ... 1693 } 1694 1695 #pragma unroll(16) 1696 for (...) { 1697 ... 1698 } 1699 1700 Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled: 1701 1702 .. code-block:: c++ 1703 1704 #pragma nounroll 1705 for (...) { 1706 ... 1707 } 1708 1709 ``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to 1710 ``#pragma clang loop unroll(full)`` and 1711 ``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll`` 1712 is equivalent to ``#pragma clang loop unroll(disable)``. See 1713 `language extensions 1714 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ 1715 for further details including limitations of the unroll hints. 1716 }]; 1717 } 1718 1719 def OpenCLUnrollHintDocs : Documentation { 1720 let Category = DocCatStmt; 1721 let Heading = "__attribute__((opencl_unroll_hint))"; 1722 let Content = [{ 1723 The opencl_unroll_hint attribute qualifier can be used to specify that a loop 1724 (for, while and do loops) can be unrolled. This attribute qualifier can be 1725 used to specify full unrolling or partial unrolling by a specified amount. 1726 This is a compiler hint and the compiler may ignore this directive. See 1727 `OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_ 1728 s6.11.5 for details. 1729 }]; 1730 } 1731 1732 def OpenCLAccessDocs : Documentation { 1733 let Category = DocCatStmt; 1734 let Heading = "__read_only, __write_only, __read_write (read_only, write_only, read_write)"; 1735 let Content = [{ 1736 The access qualifiers must be used with image object arguments or pipe arguments 1737 to declare if they are being read or written by a kernel or function. 1738 1739 The read_only/__read_only, write_only/__write_only and read_write/__read_write 1740 names are reserved for use as access qualifiers and shall not be used otherwise. 1741 1742 .. code-block:: c 1743 1744 kernel void 1745 foo (read_only image2d_t imageA, 1746 write_only image2d_t imageB) { 1747 ... 1748 } 1749 1750 In the above example imageA is a read-only 2D image object, and imageB is a 1751 write-only 2D image object. 1752 1753 The read_write (or __read_write) qualifier can not be used with pipe. 1754 1755 More details can be found in the OpenCL C language Spec v2.0, Section 6.6. 1756 }]; 1757 } 1758 1759 def DocOpenCLAddressSpaces : DocumentationCategory<"OpenCL Address Spaces"> { 1760 let Content = [{ 1761 The address space qualifier may be used to specify the region of memory that is 1762 used to allocate the object. OpenCL supports the following address spaces: 1763 __generic(generic), __global(global), __local(local), __private(private), 1764 __constant(constant). 1765 1766 .. code-block:: c 1767 1768 __constant int c = ...; 1769 1770 __generic int* foo(global int* g) { 1771 __local int* l; 1772 private int p; 1773 ... 1774 return l; 1775 } 1776 1777 More details can be found in the OpenCL C language Spec v2.0, Section 6.5. 1778 }]; 1779 } 1780 1781 def OpenCLAddressSpaceGenericDocs : Documentation { 1782 let Category = DocOpenCLAddressSpaces; 1783 let Content = [{ 1784 The generic address space attribute is only available with OpenCL v2.0 and later. 1785 It can be used with pointer types. Variables in global and local scope and 1786 function parameters in non-kernel functions can have the generic address space 1787 type attribute. It is intended to be a placeholder for any other address space 1788 except for '__constant' in OpenCL code which can be used with multiple address 1789 spaces. 1790 }]; 1791 } 1792 1793 def OpenCLAddressSpaceConstantDocs : Documentation { 1794 let Category = DocOpenCLAddressSpaces; 1795 let Content = [{ 1796 The constant address space attribute signals that an object is located in 1797 a constant (non-modifiable) memory region. It is available to all work items. 1798 Any type can be annotated with the constant address space attribute. Objects 1799 with the constant address space qualifier can be declared in any scope and must 1800 have an initializer. 1801 }]; 1802 } 1803 1804 def OpenCLAddressSpaceGlobalDocs : Documentation { 1805 let Category = DocOpenCLAddressSpaces; 1806 let Content = [{ 1807 The global address space attribute specifies that an object is allocated in 1808 global memory, which is accessible by all work items. The content stored in this 1809 memory area persists between kernel executions. Pointer types to the global 1810 address space are allowed as function parameters or local variables. Starting 1811 with OpenCL v2.0, the global address space can be used with global (program 1812 scope) variables and static local variable as well. 1813 }]; 1814 } 1815 1816 def OpenCLAddressSpaceLocalDocs : Documentation { 1817 let Category = DocOpenCLAddressSpaces; 1818 let Content = [{ 1819 The local address space specifies that an object is allocated in the local (work 1820 group) memory area, which is accessible to all work items in the same work 1821 group. The content stored in this memory region is not accessible after 1822 the kernel execution ends. In a kernel function scope, any variable can be in 1823 the local address space. In other scopes, only pointer types to the local address 1824 space are allowed. Local address space variables cannot have an initializer. 1825 }]; 1826 } 1827 1828 def OpenCLAddressSpacePrivateDocs : Documentation { 1829 let Category = DocOpenCLAddressSpaces; 1830 let Content = [{ 1831 The private address space specifies that an object is allocated in the private 1832 (work item) memory. Other work items cannot access the same memory area and its 1833 content is destroyed after work item execution ends. Local variables can be 1834 declared in the private address space. Function arguments are always in the 1835 private address space. Kernel function arguments of a pointer or an array type 1836 cannot point to the private address space. 1837 }]; 1838 } 1839 1840 def OpenCLNoSVMDocs : Documentation { 1841 let Category = DocCatVariable; 1842 let Content = [{ 1843 OpenCL 2.0 supports the optional ``__attribute__((nosvm))`` qualifier for 1844 pointer variable. It informs the compiler that the pointer does not refer 1845 to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details. 1846 1847 Since it is not widely used and has been removed from OpenCL 2.1, it is ignored 1848 by Clang. 1849 }]; 1850 } 1851 def NullabilityDocs : DocumentationCategory<"Nullability Attributes"> { 1852 let Content = [{ 1853 Whether a particular pointer may be "null" is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the ``nonnull`` and ``returns_nonnull`` attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (``_Nullable``) or cannot be null (``_Nonnull``). 1854 1855 The nullability (type) qualifiers express whether a value of a given pointer type can be null (the ``_Nullable`` qualifier), doesn't have a defined meaning for null (the ``_Nonnull`` qualifier), or for which the purpose of null is unclear (the ``_Null_unspecified`` qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the ``nonnull`` and ``returns_nonnull`` attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example: 1856 1857 .. code-block:: c 1858 1859 // No meaningful result when 'ptr' is null (here, it happens to be undefined behavior). 1860 int fetch(int * _Nonnull ptr) { return *ptr; } 1861 1862 // 'ptr' may be null. 1863 int fetch_or_zero(int * _Nullable ptr) { 1864 return ptr ? *ptr : 0; 1865 } 1866 1867 // A nullable pointer to non-null pointers to const characters. 1868 const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n); 1869 1870 In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example: 1871 1872 .. code-block:: objective-c 1873 1874 @interface NSView : NSResponder 1875 - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView; 1876 @property (assign, nullable) NSView *superview; 1877 @property (readonly, nonnull) NSArray *subviews; 1878 @end 1879 }]; 1880 } 1881 1882 def TypeNonNullDocs : Documentation { 1883 let Category = NullabilityDocs; 1884 let Content = [{ 1885 The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful value for a value of the ``_Nonnull`` pointer type. For example, given a declaration such as: 1886 1887 .. code-block:: c 1888 1889 int fetch(int * _Nonnull ptr); 1890 1891 a caller of ``fetch`` should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to ``fetch``. Note that, unlike the declaration attribute ``nonnull``, the presence of ``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch`` is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null. 1892 }]; 1893 } 1894 1895 def TypeNullableDocs : Documentation { 1896 let Category = NullabilityDocs; 1897 let Content = [{ 1898 The ``_Nullable`` nullability qualifier indicates that a value of the ``_Nullable`` pointer type can be null. For example, given: 1899 1900 .. code-block:: c 1901 1902 int fetch_or_zero(int * _Nullable ptr); 1903 1904 a caller of ``fetch_or_zero`` can provide null. 1905 }]; 1906 } 1907 1908 def TypeNullUnspecifiedDocs : Documentation { 1909 let Category = NullabilityDocs; 1910 let Content = [{ 1911 The ``_Null_unspecified`` nullability qualifier indicates that neither the ``_Nonnull`` nor ``_Nullable`` qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API. 1912 }]; 1913 } 1914 1915 def NonNullDocs : Documentation { 1916 let Category = NullabilityDocs; 1917 let Content = [{ 1918 The ``nonnull`` attribute indicates that some function parameters must not be null, and can be used in several different ways. It's original usage (`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example: 1919 1920 .. code-block:: c 1921 1922 extern void * my_memcpy (void *dest, const void *src, size_t len) 1923 __attribute__((nonnull (1, 2))); 1924 1925 Here, the ``nonnull`` attribute indicates that parameters 1 and 2 1926 cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null: 1927 1928 .. code-block:: c 1929 1930 extern void * my_memcpy (void *dest, const void *src, size_t len) 1931 __attribute__((nonnull)); 1932 1933 Clang also allows the ``nonnull`` attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example: 1934 1935 .. code-block:: c 1936 1937 extern void * my_memcpy (void *dest __attribute__((nonnull)), 1938 const void *src __attribute__((nonnull)), size_t len); 1939 1940 Note that the ``nonnull`` attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable. 1941 }]; 1942 } 1943 1944 def ReturnsNonNullDocs : Documentation { 1945 let Category = NullabilityDocs; 1946 let Content = [{ 1947 The ``returns_nonnull`` attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system ``malloc`` might be defined to terminate a process when memory is not available rather than returning a null pointer: 1948 1949 .. code-block:: c 1950 1951 extern void * malloc (size_t size) __attribute__((returns_nonnull)); 1952 1953 The ``returns_nonnull`` attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable 1954 }]; 1955 } 1956 1957 def NoAliasDocs : Documentation { 1958 let Category = DocCatFunction; 1959 let Content = [{ 1960 The ``noalias`` attribute indicates that the only memory accesses inside 1961 function are loads and stores from objects pointed to by its pointer-typed 1962 arguments, with arbitrary offsets. 1963 }]; 1964 } 1965 1966 def OMPDeclareSimdDocs : Documentation { 1967 let Category = DocCatFunction; 1968 let Heading = "#pragma omp declare simd"; 1969 let Content = [{ 1970 The `declare simd` construct can be applied to a function to enable the creation 1971 of one or more versions that can process multiple arguments using SIMD 1972 instructions from a single invocation in a SIMD loop. The `declare simd` 1973 directive is a declarative directive. There may be multiple `declare simd` 1974 directives for a function. The use of a `declare simd` construct on a function 1975 enables the creation of SIMD versions of the associated function that can be 1976 used to process multiple arguments from a single invocation from a SIMD loop 1977 concurrently. 1978 The syntax of the `declare simd` construct is as follows: 1979 1980 .. code-block:: c 1981 1982 #pragma omp declare simd [clause[[,] clause] ...] new-line 1983 [#pragma omp declare simd [clause[[,] clause] ...] new-line] 1984 [...] 1985 function definition or declaration 1986 1987 where clause is one of the following: 1988 1989 .. code-block:: c 1990 1991 simdlen(length) 1992 linear(argument-list[:constant-linear-step]) 1993 aligned(argument-list[:alignment]) 1994 uniform(argument-list) 1995 inbranch 1996 notinbranch 1997 1998 }]; 1999 } 2000 2001 def OMPDeclareTargetDocs : Documentation { 2002 let Category = DocCatFunction; 2003 let Heading = "#pragma omp declare target"; 2004 let Content = [{ 2005 The `declare target` directive specifies that variables and functions are mapped 2006 to a device for OpenMP offload mechanism. 2007 2008 The syntax of the declare target directive is as follows: 2009 2010 .. code-block:: c 2011 2012 #pragma omp declare target new-line 2013 declarations-definition-seq 2014 #pragma omp end declare target new-line 2015 }]; 2016 } 2017 2018 def NotTailCalledDocs : Documentation { 2019 let Category = DocCatFunction; 2020 let Content = [{ 2021 The ``not_tail_called`` attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as ``always_inline`` cannot be marked as ``not_tail_called``. 2022 2023 For example, it prevents tail-call optimization in the following case: 2024 2025 .. code-block:: c 2026 2027 int __attribute__((not_tail_called)) foo1(int); 2028 2029 int foo2(int a) { 2030 return foo1(a); // No tail-call optimization on direct calls. 2031 } 2032 2033 However, it doesn't prevent tail-call optimization in this case: 2034 2035 .. code-block:: c 2036 2037 int __attribute__((not_tail_called)) foo1(int); 2038 2039 int foo2(int a) { 2040 int (*fn)(int) = &foo1; 2041 2042 // not_tail_called has no effect on an indirect call even if the call can be 2043 // resolved at compile time. 2044 return (*fn)(a); 2045 } 2046 2047 Marking virtual functions as ``not_tail_called`` is an error: 2048 2049 .. code-block:: c++ 2050 2051 class Base { 2052 public: 2053 // not_tail_called on a virtual function is an error. 2054 [[clang::not_tail_called]] virtual int foo1(); 2055 2056 virtual int foo2(); 2057 2058 // Non-virtual functions can be marked ``not_tail_called``. 2059 [[clang::not_tail_called]] int foo3(); 2060 }; 2061 2062 class Derived1 : public Base { 2063 public: 2064 int foo1() override; 2065 2066 // not_tail_called on a virtual function is an error. 2067 [[clang::not_tail_called]] int foo2() override; 2068 }; 2069 }]; 2070 } 2071 2072 def InternalLinkageDocs : Documentation { 2073 let Category = DocCatFunction; 2074 let Content = [{ 2075 The ``internal_linkage`` attribute changes the linkage type of the declaration to internal. 2076 This is similar to C-style ``static``, but can be used on classes and class methods. When applied to a class definition, 2077 this attribute affects all methods and static data members of that class. 2078 This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables. 2079 }]; 2080 } 2081 2082 def DisableTailCallsDocs : Documentation { 2083 let Category = DocCatFunction; 2084 let Content = [{ 2085 The ``disable_tail_calls`` attribute instructs the backend to not perform tail call optimization inside the marked function. 2086 2087 For example: 2088 2089 .. code-block:: c 2090 2091 int callee(int); 2092 2093 int foo(int a) __attribute__((disable_tail_calls)) { 2094 return callee(a); // This call is not tail-call optimized. 2095 } 2096 2097 Marking virtual functions as ``disable_tail_calls`` is legal. 2098 2099 .. code-block:: c++ 2100 2101 int callee(int); 2102 2103 class Base { 2104 public: 2105 [[clang::disable_tail_calls]] virtual int foo1() { 2106 return callee(); // This call is not tail-call optimized. 2107 } 2108 }; 2109 2110 class Derived1 : public Base { 2111 public: 2112 int foo1() override { 2113 return callee(); // This call is tail-call optimized. 2114 } 2115 }; 2116 2117 }]; 2118 } 2119 2120 def AnyX86InterruptDocs : Documentation { 2121 let Category = DocCatFunction; 2122 let Content = [{ 2123 Clang supports the GNU style ``__attribute__((interrupt))`` attribute on 2124 x86/x86-64 targets.The compiler generates function entry and exit sequences 2125 suitable for use in an interrupt handler when this attribute is present. 2126 The 'IRET' instruction, instead of the 'RET' instruction, is used to return 2127 from interrupt or exception handlers. All registers, except for the EFLAGS 2128 register which is restored by the 'IRET' instruction, are preserved by the 2129 compiler. 2130 2131 Any interruptible-without-stack-switch code must be compiled with 2132 -mno-red-zone since interrupt handlers can and will, because of the 2133 hardware design, touch the red zone. 2134 2135 1. interrupt handler must be declared with a mandatory pointer argument: 2136 2137 .. code-block:: c 2138 2139 struct interrupt_frame 2140 { 2141 uword_t ip; 2142 uword_t cs; 2143 uword_t flags; 2144 uword_t sp; 2145 uword_t ss; 2146 }; 2147 2148 __attribute__ ((interrupt)) 2149 void f (struct interrupt_frame *frame) { 2150 ... 2151 } 2152 2153 2. exception handler: 2154 2155 The exception handler is very similar to the interrupt handler with 2156 a different mandatory function signature: 2157 2158 .. code-block:: c 2159 2160 __attribute__ ((interrupt)) 2161 void f (struct interrupt_frame *frame, uword_t error_code) { 2162 ... 2163 } 2164 2165 and compiler pops 'ERROR_CODE' off stack before the 'IRET' instruction. 2166 2167 The exception handler should only be used for exceptions which push an 2168 error code and all other exceptions must use the interrupt handler. 2169 The system will crash if the wrong handler is used. 2170 }]; 2171 } 2172 2173 def SwiftCallDocs : Documentation { 2174 let Category = DocCatVariable; 2175 let Content = [{ 2176 The ``swiftcall`` attribute indicates that a function should be called 2177 using the Swift calling convention for a function or function pointer. 2178 2179 The lowering for the Swift calling convention, as described by the Swift 2180 ABI documentation, occurs in multiple phases. The first, "high-level" 2181 phase breaks down the formal parameters and results into innately direct 2182 and indirect components, adds implicit paraameters for the generic 2183 signature, and assigns the context and error ABI treatments to parameters 2184 where applicable. The second phase breaks down the direct parameters 2185 and results from the first phase and assigns them to registers or the 2186 stack. The ``swiftcall`` convention only handles this second phase of 2187 lowering; the C function type must accurately reflect the results 2188 of the first phase, as follows: 2189 2190 - Results classified as indirect by high-level lowering should be 2191 represented as parameters with the ``swift_indirect_result`` attribute. 2192 2193 - Results classified as direct by high-level lowering should be represented 2194 as follows: 2195 2196 - First, remove any empty direct results. 2197 2198 - If there are no direct results, the C result type should be ``void``. 2199 2200 - If there is one direct result, the C result type should be a type with 2201 the exact layout of that result type. 2202 2203 - If there are a multiple direct results, the C result type should be 2204 a struct type with the exact layout of a tuple of those results. 2205 2206 - Parameters classified as indirect by high-level lowering should be 2207 represented as parameters of pointer type. 2208 2209 - Parameters classified as direct by high-level lowering should be 2210 omitted if they are empty types; otherwise, they should be represented 2211 as a parameter type with a layout exactly matching the layout of the 2212 Swift parameter type. 2213 2214 - The context parameter, if present, should be represented as a trailing 2215 parameter with the ``swift_context`` attribute. 2216 2217 - The error result parameter, if present, should be represented as a 2218 trailing parameter (always following a context parameter) with the 2219 ``swift_error_result`` attribute. 2220 2221 ``swiftcall`` does not support variadic arguments or unprototyped functions. 2222 2223 The parameter ABI treatment attributes are aspects of the function type. 2224 A function type which which applies an ABI treatment attribute to a 2225 parameter is a different type from an otherwise-identical function type 2226 that does not. A single parameter may not have multiple ABI treatment 2227 attributes. 2228 2229 Support for this feature is target-dependent, although it should be 2230 supported on every target that Swift supports. Query for this support 2231 with ``__has_attribute(swiftcall)``. This implies support for the 2232 ``swift_context``, ``swift_error_result``, and ``swift_indirect_result`` 2233 attributes. 2234 }]; 2235 } 2236 2237 def SwiftContextDocs : Documentation { 2238 let Category = DocCatVariable; 2239 let Content = [{ 2240 The ``swift_context`` attribute marks a parameter of a ``swiftcall`` 2241 function as having the special context-parameter ABI treatment. 2242 2243 This treatment generally passes the context value in a special register 2244 which is normally callee-preserved. 2245 2246 A ``swift_context`` parameter must either be the last parameter or must be 2247 followed by a ``swift_error_result`` parameter (which itself must always be 2248 the last parameter). 2249 2250 A context parameter must have pointer or reference type. 2251 }]; 2252 } 2253 2254 def SwiftErrorResultDocs : Documentation { 2255 let Category = DocCatVariable; 2256 let Content = [{ 2257 The ``swift_error_result`` attribute marks a parameter of a ``swiftcall`` 2258 function as having the special error-result ABI treatment. 2259 2260 This treatment generally passes the underlying error value in and out of 2261 the function through a special register which is normally callee-preserved. 2262 This is modeled in C by pretending that the register is addressable memory: 2263 2264 - The caller appears to pass the address of a variable of pointer type. 2265 The current value of this variable is copied into the register before 2266 the call; if the call returns normally, the value is copied back into the 2267 variable. 2268 2269 - The callee appears to receive the address of a variable. This address 2270 is actually a hidden location in its own stack, initialized with the 2271 value of the register upon entry. When the function returns normally, 2272 the value in that hidden location is written back to the register. 2273 2274 A ``swift_error_result`` parameter must be the last parameter, and it must be 2275 preceded by a ``swift_context`` parameter. 2276 2277 A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some 2278 type T. Note that no qualifiers are permitted on the intermediate level. 2279 2280 It is undefined behavior if the caller does not pass a pointer or 2281 reference to a valid object. 2282 2283 The standard convention is that the error value itself (that is, the 2284 value stored in the apparent argument) will be null upon function entry, 2285 but this is not enforced by the ABI. 2286 }]; 2287 } 2288 2289 def SwiftIndirectResultDocs : Documentation { 2290 let Category = DocCatVariable; 2291 let Content = [{ 2292 The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall`` 2293 function as having the special indirect-result ABI treatmenet. 2294 2295 This treatment gives the parameter the target's normal indirect-result 2296 ABI treatment, which may involve passing it differently from an ordinary 2297 parameter. However, only the first indirect result will receive this 2298 treatment. Furthermore, low-level lowering may decide that a direct result 2299 must be returned indirectly; if so, this will take priority over the 2300 ``swift_indirect_result`` parameters. 2301 2302 A ``swift_indirect_result`` parameter must either be the first parameter or 2303 follow another ``swift_indirect_result`` parameter. 2304 2305 A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for 2306 some object type ``T``. If ``T`` is a complete type at the point of 2307 definition of a function, it is undefined behavior if the argument 2308 value does not point to storage of adequate size and alignment for a 2309 value of type ``T``. 2310 2311 Making indirect results explicit in the signature allows C functions to 2312 directly construct objects into them without relying on language 2313 optimizations like C++'s named return value optimization (NRVO). 2314 }]; 2315 } 2316 2317 def AbiTagsDocs : Documentation { 2318 let Category = DocCatFunction; 2319 let Content = [{ 2320 The ``abi_tag`` attribute can be applied to a function, variable, class or 2321 inline namespace declaration to modify the mangled name of the entity. It gives 2322 the ability to distinguish between different versions of the same entity but 2323 with different ABI versions supported. For example, a newer version of a class 2324 could have a different set of data members and thus have a different size. Using 2325 the ``abi_tag`` attribute, it is possible to have different mangled names for 2326 a global variable of the class type. Therefor, the old code could keep using 2327 the old manged name and the new code will use the new mangled name with tags. 2328 }]; 2329 } 2330 2331 def PreserveMostDocs : Documentation { 2332 let Category = DocCatCallingConvs; 2333 let Content = [{ 2334 On X86-64 and AArch64 targets, this attribute changes the calling convention of 2335 a function. The ``preserve_most`` calling convention attempts to make the code 2336 in the caller as unintrusive as possible. This convention behaves identically 2337 to the ``C`` calling convention on how arguments and return values are passed, 2338 but it uses a different set of caller/callee-saved registers. This alleviates 2339 the burden of saving and recovering a large register set before and after the 2340 call in the caller. If the arguments are passed in callee-saved registers, 2341 then they will be preserved by the callee across the call. This doesn't 2342 apply for values returned in callee-saved registers. 2343 2344 - On X86-64 the callee preserves all general purpose registers, except for 2345 R11. R11 can be used as a scratch register. Floating-point registers 2346 (XMMs/YMMs) are not preserved and need to be saved by the caller. 2347 2348 The idea behind this convention is to support calls to runtime functions 2349 that have a hot path and a cold path. The hot path is usually a small piece 2350 of code that doesn't use many registers. The cold path might need to call out to 2351 another function and therefore only needs to preserve the caller-saved 2352 registers, which haven't already been saved by the caller. The 2353 `preserve_most` calling convention is very similar to the ``cold`` calling 2354 convention in terms of caller/callee-saved registers, but they are used for 2355 different types of function calls. ``coldcc`` is for function calls that are 2356 rarely executed, whereas `preserve_most` function calls are intended to be 2357 on the hot path and definitely executed a lot. Furthermore ``preserve_most`` 2358 doesn't prevent the inliner from inlining the function call. 2359 2360 This calling convention will be used by a future version of the Objective-C 2361 runtime and should therefore still be considered experimental at this time. 2362 Although this convention was created to optimize certain runtime calls to 2363 the Objective-C runtime, it is not limited to this runtime and might be used 2364 by other runtimes in the future too. The current implementation only 2365 supports X86-64 and AArch64, but the intention is to support more architectures 2366 in the future. 2367 }]; 2368 } 2369 2370 def PreserveAllDocs : Documentation { 2371 let Category = DocCatCallingConvs; 2372 let Content = [{ 2373 On X86-64 and AArch64 targets, this attribute changes the calling convention of 2374 a function. The ``preserve_all`` calling convention attempts to make the code 2375 in the caller even less intrusive than the ``preserve_most`` calling convention. 2376 This calling convention also behaves identical to the ``C`` calling convention 2377 on how arguments and return values are passed, but it uses a different set of 2378 caller/callee-saved registers. This removes the burden of saving and 2379 recovering a large register set before and after the call in the caller. If 2380 the arguments are passed in callee-saved registers, then they will be 2381 preserved by the callee across the call. This doesn't apply for values 2382 returned in callee-saved registers. 2383 2384 - On X86-64 the callee preserves all general purpose registers, except for 2385 R11. R11 can be used as a scratch register. Furthermore it also preserves 2386 all floating-point registers (XMMs/YMMs). 2387 2388 The idea behind this convention is to support calls to runtime functions 2389 that don't need to call out to any other functions. 2390 2391 This calling convention, like the ``preserve_most`` calling convention, will be 2392 used by a future version of the Objective-C runtime and should be considered 2393 experimental at this time. 2394 }]; 2395 } 2396 2397 def DeprecatedDocs : Documentation { 2398 let Category = DocCatFunction; 2399 let Content = [{ 2400 The ``deprecated`` attribute can be applied to a function, a variable, or a 2401 type. This is useful when identifying functions, variables, or types that are 2402 expected to be removed in a future version of a program. 2403 2404 Consider the function declaration for a hypothetical function ``f``: 2405 2406 .. code-block:: c++ 2407 2408 void f(void) __attribute__((deprecated("message", "replacement"))); 2409 2410 When spelled as `__attribute__((deprecated))`, the deprecated attribute can have 2411 two optional string arguments. The first one is the message to display when 2412 emitting the warning; the second one enables the compiler to provide a Fix-It 2413 to replace the deprecated name with a new name. Otherwise, when spelled as 2414 `[[gnu::deprecated]] or [[deprecated]]`, the attribute can have one optional 2415 string argument which is the message to display when emitting the warning. 2416 }]; 2417 } 2418 2419 def IFuncDocs : Documentation { 2420 let Category = DocCatFunction; 2421 let Content = [{ 2422 ``__attribute__((ifunc("resolver")))`` is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function. 2423 2424 The symbol name of the resolver function is given in quotes. A function with this name (after mangling) must be defined in the current translation unit; it may be ``static``. The resolver function should take no arguments and return a pointer. 2425 2426 The ``ifunc`` attribute may only be used on a function declaration. A function declaration with an ``ifunc`` attribute is considered to be a definition of the declared entity. The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline. 2427 2428 Not all targets support this attribute. ELF targets support this attribute when using binutils v2.20.1 or higher and glibc v2.11.1 or higher. Non-ELF targets currently do not support this attribute. 2429 }]; 2430 } 2431 2432 def LTOVisibilityDocs : Documentation { 2433 let Category = DocCatType; 2434 let Content = [{ 2435 See :doc:`LTOVisibility`. 2436 }]; 2437 } 2438 2439 def RenderScriptKernelAttributeDocs : Documentation { 2440 let Category = DocCatFunction; 2441 let Content = [{ 2442 ``__attribute__((kernel))`` is used to mark a ``kernel`` function in 2443 RenderScript. 2444 2445 In RenderScript, ``kernel`` functions are used to express data-parallel 2446 computations. The RenderScript runtime efficiently parallelizes ``kernel`` 2447 functions to run on computational resources such as multi-core CPUs and GPUs. 2448 See the RenderScript_ documentation for more information. 2449 2450 .. _RenderScript: https://developer.android.com/guide/topics/renderscript/compute.html 2451 }]; 2452 } 2453 2454 def XRayDocs : Documentation { 2455 let Category = DocCatFunction; 2456 let Heading = "xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument)"; 2457 let Content = [{ 2458 ``__attribute__((xray_always_instrument))`` or ``[[clang::xray_always_instrument]]`` is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching. 2459 2460 Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points. 2461 2462 If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise. 2463 }]; 2464 } 2465