1.. 2 ------------------------------------------------------------------- 3 NOTE: This file is automatically generated by running clang-tblgen 4 -gen-attr-docs. Do not edit this file by hand!! 5 ------------------------------------------------------------------- 6 7=================== 8Attributes in Clang 9=================== 10.. contents:: 11 :local: 12 13.. |br| raw:: html 14 15 <br/> 16 17Introduction 18============ 19 20This page lists the attributes currently supported by Clang. 21 22Function Attributes 23=================== 24 25 26#pragma omp declare simd 27------------------------ 28.. csv-table:: Supported Syntaxes 29 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 30 31 "","","","","","``omp declare simd``","" 32 33The `declare simd` construct can be applied to a function to enable the creation 34of one or more versions that can process multiple arguments using SIMD 35instructions from a single invocation in a SIMD loop. The `declare simd` 36directive is a declarative directive. There may be multiple `declare simd` 37directives for a function. The use of a `declare simd` construct on a function 38enables the creation of SIMD versions of the associated function that can be 39used to process multiple arguments from a single invocation from a SIMD loop 40concurrently. 41The syntax of the `declare simd` construct is as follows: 42 43 .. code-block:: none 44 45 #pragma omp declare simd [clause[[,] clause] ...] new-line 46 [#pragma omp declare simd [clause[[,] clause] ...] new-line] 47 [...] 48 function definition or declaration 49 50where clause is one of the following: 51 52 .. code-block:: none 53 54 simdlen(length) 55 linear(argument-list[:constant-linear-step]) 56 aligned(argument-list[:alignment]) 57 uniform(argument-list) 58 inbranch 59 notinbranch 60 61 62#pragma omp declare target 63-------------------------- 64.. csv-table:: Supported Syntaxes 65 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 66 67 "","","","","","``omp declare target``","" 68 69The `declare target` directive specifies that variables and functions are mapped 70to a device for OpenMP offload mechanism. 71 72The syntax of the declare target directive is as follows: 73 74 .. code-block:: c 75 76 #pragma omp declare target new-line 77 declarations-definition-seq 78 #pragma omp end declare target new-line 79 80 81_Noreturn 82--------- 83.. csv-table:: Supported Syntaxes 84 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 85 86 "","","","","``_Noreturn``","","" 87 88A function declared as ``_Noreturn`` shall not return to its caller. The 89compiler will generate a diagnostic for a function declared as ``_Noreturn`` 90that appears to be capable of returning to its caller. 91 92 93abi_tag 94------- 95.. csv-table:: Supported Syntaxes 96 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 97 98 "``abi_tag``","``gnu::abi_tag``","","","","","Yes" 99 100The ``abi_tag`` attribute can be applied to a function, variable, class or 101inline namespace declaration to modify the mangled name of the entity. It gives 102the ability to distinguish between different versions of the same entity but 103with different ABI versions supported. For example, a newer version of a class 104could have a different set of data members and thus have a different size. Using 105the ``abi_tag`` attribute, it is possible to have different mangled names for 106a global variable of the class type. Therefore, the old code could keep using 107the old manged name and the new code will use the new mangled name with tags. 108 109 110acquire_capability, acquire_shared_capability 111--------------------------------------------- 112.. csv-table:: Supported Syntaxes 113 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 114 115 "``acquire_capability`` |br| ``acquire_shared_capability`` |br| ``exclusive_lock_function`` |br| ``shared_lock_function``","``clang::acquire_capability`` |br| ``clang::acquire_shared_capability``","","","","","" 116 117Marks a function as acquiring a capability. 118 119 120alloc_align 121----------- 122.. csv-table:: Supported Syntaxes 123 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 124 125 "``alloc_align``","``gnu::alloc_align``","","","","","" 126 127Use ``__attribute__((alloc_align(<alignment>))`` on a function 128declaration to specify that the return value of the function (which must be a 129pointer type) is at least as aligned as the value of the indicated parameter. The 130parameter is given by its index in the list of formal parameters; the first 131parameter has index 1 unless the function is a C++ non-static member function, 132in which case the first parameter has index 2 to account for the implicit ``this`` 133parameter. 134 135.. code-block:: c++ 136 137 // The returned pointer has the alignment specified by the first parameter. 138 void *a(size_t align) __attribute__((alloc_align(1))); 139 140 // The returned pointer has the alignment specified by the second parameter. 141 void *b(void *v, size_t align) __attribute__((alloc_align(2))); 142 143 // The returned pointer has the alignment specified by the second visible 144 // parameter, however it must be adjusted for the implicit 'this' parameter. 145 void *Foo::b(void *v, size_t align) __attribute__((alloc_align(3))); 146 147Note that this attribute merely informs the compiler that a function always 148returns a sufficiently aligned pointer. It does not cause the compiler to 149emit code to enforce that alignment. The behavior is undefined if the returned 150poitner is not sufficiently aligned. 151 152 153alloc_size 154---------- 155.. csv-table:: Supported Syntaxes 156 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 157 158 "``alloc_size``","``gnu::alloc_size``","","","","","Yes" 159 160The ``alloc_size`` attribute can be placed on functions that return pointers in 161order to hint to the compiler how many bytes of memory will be available at the 162returned pointer. ``alloc_size`` takes one or two arguments. 163 164- ``alloc_size(N)`` implies that argument number N equals the number of 165 available bytes at the returned pointer. 166- ``alloc_size(N, M)`` implies that the product of argument number N and 167 argument number M equals the number of available bytes at the returned 168 pointer. 169 170Argument numbers are 1-based. 171 172An example of how to use ``alloc_size`` 173 174.. code-block:: c 175 176 void *my_malloc(int a) __attribute__((alloc_size(1))); 177 void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2))); 178 179 int main() { 180 void *const p = my_malloc(100); 181 assert(__builtin_object_size(p, 0) == 100); 182 void *const a = my_calloc(20, 5); 183 assert(__builtin_object_size(a, 0) == 100); 184 } 185 186.. Note:: This attribute works differently in clang than it does in GCC. 187 Specifically, clang will only trace ``const`` pointers (as above); we give up 188 on pointers that are not marked as ``const``. In the vast majority of cases, 189 this is unimportant, because LLVM has support for the ``alloc_size`` 190 attribute. However, this may cause mildly unintuitive behavior when used with 191 other attributes, such as ``enable_if``. 192 193 194artificial 195---------- 196.. csv-table:: Supported Syntaxes 197 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 198 199 "``artificial``","``gnu::artificial``","","","","","" 200 201The ``artificial`` attribute can be applied to an inline function. If such a 202function is inlined, the attribute indicates that debuggers should associate 203the resulting instructions with the call site, rather than with the 204corresponding line within the inlined callee. 205 206 207assert_capability, assert_shared_capability 208------------------------------------------- 209.. csv-table:: Supported Syntaxes 210 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 211 212 "``assert_capability`` |br| ``assert_shared_capability``","``clang::assert_capability`` |br| ``clang::assert_shared_capability``","","","","","" 213 214Marks a function that dynamically tests whether a capability is held, and halts 215the program if it is not held. 216 217 218assume_aligned 219-------------- 220.. csv-table:: Supported Syntaxes 221 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 222 223 "``assume_aligned``","``gnu::assume_aligned``","","","","","Yes" 224 225Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function 226declaration to specify that the return value of the function (which must be a 227pointer type) has the specified offset, in bytes, from an address with the 228specified alignment. The offset is taken to be zero if omitted. 229 230.. code-block:: c++ 231 232 // The returned pointer value has 32-byte alignment. 233 void *a() __attribute__((assume_aligned (32))); 234 235 // The returned pointer value is 4 bytes greater than an address having 236 // 32-byte alignment. 237 void *b() __attribute__((assume_aligned (32, 4))); 238 239Note that this attribute provides information to the compiler regarding a 240condition that the code already ensures is true. It does not cause the compiler 241to enforce the provided alignment assumption. 242 243 244availability 245------------ 246.. csv-table:: Supported Syntaxes 247 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 248 249 "``availability``","``clang::availability``","``clang::availability``","","","","Yes" 250 251The ``availability`` attribute can be placed on declarations to describe the 252lifecycle of that declaration relative to operating system versions. Consider 253the function declaration for a hypothetical function ``f``: 254 255.. code-block:: c++ 256 257 void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7))); 258 259The availability attribute states that ``f`` was introduced in macOS 10.4, 260deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information 261is used by Clang to determine when it is safe to use ``f``: for example, if 262Clang is instructed to compile code for macOS 10.5, a call to ``f()`` 263succeeds. If Clang is instructed to compile code for macOS 10.6, the call 264succeeds but Clang emits a warning specifying that the function is deprecated. 265Finally, if Clang is instructed to compile code for macOS 10.7, the call 266fails because ``f()`` is no longer available. 267 268The availability attribute is a comma-separated list starting with the 269platform name and then including clauses specifying important milestones in the 270declaration's lifetime (in any order) along with additional information. Those 271clauses can be: 272 273introduced=\ *version* 274 The first version in which this declaration was introduced. 275 276deprecated=\ *version* 277 The first version in which this declaration was deprecated, meaning that 278 users should migrate away from this API. 279 280obsoleted=\ *version* 281 The first version in which this declaration was obsoleted, meaning that it 282 was removed completely and can no longer be used. 283 284unavailable 285 This declaration is never available on this platform. 286 287message=\ *string-literal* 288 Additional message text that Clang will provide when emitting a warning or 289 error about use of a deprecated or obsoleted declaration. Useful to direct 290 users to replacement APIs. 291 292replacement=\ *string-literal* 293 Additional message text that Clang will use to provide Fix-It when emitting 294 a warning about use of a deprecated declaration. The Fix-It will replace 295 the deprecated declaration with the new declaration specified. 296 297Multiple availability attributes can be placed on a declaration, which may 298correspond to different platforms. Only the availability attribute with the 299platform corresponding to the target platform will be used; any others will be 300ignored. If no availability attribute specifies availability for the current 301target platform, the availability attributes are ignored. Supported platforms 302are: 303 304``ios`` 305 Apple's iOS operating system. The minimum deployment target is specified by 306 the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` 307 command-line arguments. 308 309``macos`` 310 Apple's macOS operating system. The minimum deployment target is 311 specified by the ``-mmacosx-version-min=*version*`` command-line argument. 312 ``macosx`` is supported for backward-compatibility reasons, but it is 313 deprecated. 314 315``tvos`` 316 Apple's tvOS operating system. The minimum deployment target is specified by 317 the ``-mtvos-version-min=*version*`` command-line argument. 318 319``watchos`` 320 Apple's watchOS operating system. The minimum deployment target is specified by 321 the ``-mwatchos-version-min=*version*`` command-line argument. 322 323A declaration can typically be used even when deploying back to a platform 324version prior to when the declaration was introduced. When this happens, the 325declaration is `weakly linked 326<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_, 327as if the ``weak_import`` attribute were added to the declaration. A 328weakly-linked declaration may or may not be present a run-time, and a program 329can determine whether the declaration is present by checking whether the 330address of that declaration is non-NULL. 331 332The flag ``strict`` disallows using API when deploying back to a 333platform version prior to when the declaration was introduced. An 334attempt to use such API before its introduction causes a hard error. 335Weakly-linking is almost always a better API choice, since it allows 336users to query availability at runtime. 337 338If there are multiple declarations of the same entity, the availability 339attributes must either match on a per-platform basis or later 340declarations must not have availability attributes for that 341platform. For example: 342 343.. code-block:: c 344 345 void g(void) __attribute__((availability(macos,introduced=10.4))); 346 void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches 347 void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform 348 void g(void); // okay, inherits both macos and ios availability from above. 349 void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch 350 351When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: 352 353.. code-block:: objc 354 355 @interface A 356 - (id)method __attribute__((availability(macos,introduced=10.4))); 357 - (id)method2 __attribute__((availability(macos,introduced=10.4))); 358 @end 359 360 @interface B : A 361 - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later 362 - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4 363 @end 364 365Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from 366``<os/availability.h>`` can simplify the spelling: 367 368.. code-block:: objc 369 370 @interface A 371 - (id)method API_AVAILABLE(macos(10.11))); 372 - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0)); 373 @end 374 375Also see the documentation for `@available 376<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_ 377 378 379carries_dependency 380------------------ 381.. csv-table:: Supported Syntaxes 382 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 383 384 "``carries_dependency``","``carries_dependency``","","","","","Yes" 385 386The ``carries_dependency`` attribute specifies dependency propagation into and 387out of functions. 388 389When specified on a function or Objective-C method, the ``carries_dependency`` 390attribute means that the return value carries a dependency out of the function, 391so that the implementation need not constrain ordering upon return from that 392function. Implementations of the function and its caller may choose to preserve 393dependencies instead of emitting memory ordering instructions such as fences. 394 395Note, this attribute does not change the meaning of the program, but may result 396in generation of more efficient code. 397 398 399cf_consumed 400----------- 401.. csv-table:: Supported Syntaxes 402 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 403 404 "``cf_consumed``","``clang::cf_consumed``","``clang::cf_consumed``","","","","Yes" 405 406The behavior of a function with respect to reference counting for Foundation 407(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 408convention (e.g. functions starting with "get" are assumed to return at 409``+0``). 410 411It can be overriden using a family of the following attributes. In 412Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 413a function communicates that the object is returned at ``+1``, and the caller 414is responsible for freeing it. 415Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 416specifies that the object is returned at ``+0`` and the ownership remains with 417the callee. 418The annotation ``__attribute__((ns_consumes_self))`` specifies that 419the Objective-C method call consumes the reference to ``self``, e.g. by 420attaching it to a supplied parameter. 421Additionally, parameters can have an annotation 422``__attribute__((ns_consumed))``, which specifies that passing an owned object 423as that parameter effectively transfers the ownership, and the caller is no 424longer responsible for it. 425These attributes affect code generation when interacting with ARC code, and 426they are used by the Clang Static Analyzer. 427 428In C programs using CoreFoundation, a similar set of attributes: 429``__attribute__((cf_returns_not_retained))``, 430``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 431have the same respective semantics when applied to CoreFoundation objects. 432These attributes affect code generation when interacting with ARC code, and 433they are used by the Clang Static Analyzer. 434 435Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 436the same attribute family is present: 437``__attribute__((os_returns_not_retained))``, 438``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 439with the same respective semantics. 440Similar to ``__attribute__((ns_consumes_self))``, 441``__attribute__((os_consumes_this))`` specifies that the method call consumes 442the reference to "this" (e.g., when attaching it to a different object supplied 443as a parameter). 444Out parameters (parameters the function is meant to write into, 445either via pointers-to-pointers or references-to-pointers) 446may be annotated with ``__attribute__((os_returns_retained))`` 447or ``__attribute__((os_returns_not_retained))`` which specifies that the object 448written into the out parameter should (or respectively should not) be released 449after use. 450Since often out parameters may or may not be written depending on the exit 451code of the function, 452annotations ``__attribute__((os_returns_retained_on_zero))`` 453and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 454an out parameter at ``+1`` is written if and only if the function returns a zero 455(respectively non-zero) error code. 456Observe that return-code-dependent out parameter annotations are only 457available for retained out parameters, as non-retained object do not have to be 458released by the callee. 459These attributes are only used by the Clang Static Analyzer. 460 461The family of attributes ``X_returns_X_retained`` can be added to functions, 462C++ methods, and Objective-C methods and properties. 463Attributes ``X_consumed`` can be added to parameters of methods, functions, 464and Objective-C methods. 465 466 467cf_returns_not_retained 468----------------------- 469.. csv-table:: Supported Syntaxes 470 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 471 472 "``cf_returns_not_retained``","``clang::cf_returns_not_retained``","``clang::cf_returns_not_retained``","","","","" 473 474The behavior of a function with respect to reference counting for Foundation 475(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 476convention (e.g. functions starting with "get" are assumed to return at 477``+0``). 478 479It can be overriden using a family of the following attributes. In 480Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 481a function communicates that the object is returned at ``+1``, and the caller 482is responsible for freeing it. 483Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 484specifies that the object is returned at ``+0`` and the ownership remains with 485the callee. 486The annotation ``__attribute__((ns_consumes_self))`` specifies that 487the Objective-C method call consumes the reference to ``self``, e.g. by 488attaching it to a supplied parameter. 489Additionally, parameters can have an annotation 490``__attribute__((ns_consumed))``, which specifies that passing an owned object 491as that parameter effectively transfers the ownership, and the caller is no 492longer responsible for it. 493These attributes affect code generation when interacting with ARC code, and 494they are used by the Clang Static Analyzer. 495 496In C programs using CoreFoundation, a similar set of attributes: 497``__attribute__((cf_returns_not_retained))``, 498``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 499have the same respective semantics when applied to CoreFoundation objects. 500These attributes affect code generation when interacting with ARC code, and 501they are used by the Clang Static Analyzer. 502 503Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 504the same attribute family is present: 505``__attribute__((os_returns_not_retained))``, 506``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 507with the same respective semantics. 508Similar to ``__attribute__((ns_consumes_self))``, 509``__attribute__((os_consumes_this))`` specifies that the method call consumes 510the reference to "this" (e.g., when attaching it to a different object supplied 511as a parameter). 512Out parameters (parameters the function is meant to write into, 513either via pointers-to-pointers or references-to-pointers) 514may be annotated with ``__attribute__((os_returns_retained))`` 515or ``__attribute__((os_returns_not_retained))`` which specifies that the object 516written into the out parameter should (or respectively should not) be released 517after use. 518Since often out parameters may or may not be written depending on the exit 519code of the function, 520annotations ``__attribute__((os_returns_retained_on_zero))`` 521and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 522an out parameter at ``+1`` is written if and only if the function returns a zero 523(respectively non-zero) error code. 524Observe that return-code-dependent out parameter annotations are only 525available for retained out parameters, as non-retained object do not have to be 526released by the callee. 527These attributes are only used by the Clang Static Analyzer. 528 529The family of attributes ``X_returns_X_retained`` can be added to functions, 530C++ methods, and Objective-C methods and properties. 531Attributes ``X_consumed`` can be added to parameters of methods, functions, 532and Objective-C methods. 533 534 535cf_returns_retained 536------------------- 537.. csv-table:: Supported Syntaxes 538 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 539 540 "``cf_returns_retained``","``clang::cf_returns_retained``","``clang::cf_returns_retained``","","","","" 541 542The behavior of a function with respect to reference counting for Foundation 543(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 544convention (e.g. functions starting with "get" are assumed to return at 545``+0``). 546 547It can be overriden using a family of the following attributes. In 548Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 549a function communicates that the object is returned at ``+1``, and the caller 550is responsible for freeing it. 551Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 552specifies that the object is returned at ``+0`` and the ownership remains with 553the callee. 554The annotation ``__attribute__((ns_consumes_self))`` specifies that 555the Objective-C method call consumes the reference to ``self``, e.g. by 556attaching it to a supplied parameter. 557Additionally, parameters can have an annotation 558``__attribute__((ns_consumed))``, which specifies that passing an owned object 559as that parameter effectively transfers the ownership, and the caller is no 560longer responsible for it. 561These attributes affect code generation when interacting with ARC code, and 562they are used by the Clang Static Analyzer. 563 564In C programs using CoreFoundation, a similar set of attributes: 565``__attribute__((cf_returns_not_retained))``, 566``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 567have the same respective semantics when applied to CoreFoundation objects. 568These attributes affect code generation when interacting with ARC code, and 569they are used by the Clang Static Analyzer. 570 571Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 572the same attribute family is present: 573``__attribute__((os_returns_not_retained))``, 574``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 575with the same respective semantics. 576Similar to ``__attribute__((ns_consumes_self))``, 577``__attribute__((os_consumes_this))`` specifies that the method call consumes 578the reference to "this" (e.g., when attaching it to a different object supplied 579as a parameter). 580Out parameters (parameters the function is meant to write into, 581either via pointers-to-pointers or references-to-pointers) 582may be annotated with ``__attribute__((os_returns_retained))`` 583or ``__attribute__((os_returns_not_retained))`` which specifies that the object 584written into the out parameter should (or respectively should not) be released 585after use. 586Since often out parameters may or may not be written depending on the exit 587code of the function, 588annotations ``__attribute__((os_returns_retained_on_zero))`` 589and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 590an out parameter at ``+1`` is written if and only if the function returns a zero 591(respectively non-zero) error code. 592Observe that return-code-dependent out parameter annotations are only 593available for retained out parameters, as non-retained object do not have to be 594released by the callee. 595These attributes are only used by the Clang Static Analyzer. 596 597The family of attributes ``X_returns_X_retained`` can be added to functions, 598C++ methods, and Objective-C methods and properties. 599Attributes ``X_consumed`` can be added to parameters of methods, functions, 600and Objective-C methods. 601 602 603code_seg 604-------- 605.. csv-table:: Supported Syntaxes 606 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 607 608 "","","","``code_seg``","","","" 609 610The ``__declspec(code_seg)`` attribute enables the placement of code into separate 611named segments that can be paged or locked in memory individually. This attribute 612is used to control the placement of instantiated templates and compiler-generated 613code. See the documentation for `__declspec(code_seg)`_ on MSDN. 614 615.. _`__declspec(code_seg)`: http://msdn.microsoft.com/en-us/library/dn636922.aspx 616 617 618convergent 619---------- 620.. csv-table:: Supported Syntaxes 621 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 622 623 "``convergent``","``clang::convergent``","``clang::convergent``","","","","Yes" 624 625The ``convergent`` attribute can be placed on a function declaration. It is 626translated into the LLVM ``convergent`` attribute, which indicates that the call 627instructions of a function with this attribute cannot be made control-dependent 628on any additional values. 629 630In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA, 631the call instructions of a function with this attribute must be executed by 632all work items or threads in a work group or sub group. 633 634This attribute is different from ``noduplicate`` because it allows duplicating 635function calls if it can be proved that the duplicated function calls are 636not made control-dependent on any additional values, e.g., unrolling a loop 637executed by all work items. 638 639Sample usage: 640.. code-block:: c 641 642 void convfunc(void) __attribute__((convergent)); 643 // Setting it as a C++11 attribute is also valid in a C++ program. 644 // void convfunc(void) [[clang::convergent]]; 645 646 647cpu_dispatch 648------------ 649.. csv-table:: Supported Syntaxes 650 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 651 652 "``cpu_dispatch``","``clang::cpu_dispatch``","``clang::cpu_dispatch``","``cpu_dispatch``","","","Yes" 653 654The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and 655resolve multiversioned functions. This form of multiversioning provides a 656mechanism for declaring versions across translation units and manually 657specifying the resolved function list. A specified CPU defines a set of minimum 658features that are required for the function to be called. The result of this is 659that future processors execute the most restrictive version of the function the 660new processor can execute. 661 662Function versions are defined with ``cpu_specific``, which takes one or more CPU 663names as a parameter. For example: 664 665.. code-block:: c 666 667 // Declares and defines the ivybridge version of single_cpu. 668 __attribute__((cpu_specific(ivybridge))) 669 void single_cpu(void){} 670 671 // Declares and defines the atom version of single_cpu. 672 __attribute__((cpu_specific(atom))) 673 void single_cpu(void){} 674 675 // Declares and defines both the ivybridge and atom version of multi_cpu. 676 __attribute__((cpu_specific(ivybridge, atom))) 677 void multi_cpu(void){} 678 679A dispatching (or resolving) function can be declared anywhere in a project's 680source code with ``cpu_dispatch``. This attribute takes one or more CPU names 681as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch`` 682are not expected to be defined, only declared. If such a marked function has a 683definition, any side effects of the function are ignored; trivial function 684bodies are permissible for ICC compatibility. 685 686.. code-block:: c 687 688 // Creates a resolver for single_cpu above. 689 __attribute__((cpu_dispatch(ivybridge, atom))) 690 void single_cpu(void){} 691 692 // Creates a resolver for multi_cpu, but adds a 3rd version defined in another 693 // translation unit. 694 __attribute__((cpu_dispatch(ivybridge, atom, sandybridge))) 695 void multi_cpu(void){} 696 697Note that it is possible to have a resolving function that dispatches based on 698more or fewer options than are present in the program. Specifying fewer will 699result in the omitted options not being considered during resolution. Specifying 700a version for resolution that isn't defined in the program will result in a 701linking failure. 702 703It is also possible to specify a CPU name of ``generic`` which will be resolved 704if the executing processor doesn't satisfy the features required in the CPU 705name. The behavior of a program executing on a processor that doesn't satisfy 706any option of a multiversioned function is undefined. 707 708 709cpu_specific 710------------ 711.. csv-table:: Supported Syntaxes 712 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 713 714 "``cpu_specific``","``clang::cpu_specific``","``clang::cpu_specific``","``cpu_specific``","","","Yes" 715 716The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and 717resolve multiversioned functions. This form of multiversioning provides a 718mechanism for declaring versions across translation units and manually 719specifying the resolved function list. A specified CPU defines a set of minimum 720features that are required for the function to be called. The result of this is 721that future processors execute the most restrictive version of the function the 722new processor can execute. 723 724Function versions are defined with ``cpu_specific``, which takes one or more CPU 725names as a parameter. For example: 726 727.. code-block:: c 728 729 // Declares and defines the ivybridge version of single_cpu. 730 __attribute__((cpu_specific(ivybridge))) 731 void single_cpu(void){} 732 733 // Declares and defines the atom version of single_cpu. 734 __attribute__((cpu_specific(atom))) 735 void single_cpu(void){} 736 737 // Declares and defines both the ivybridge and atom version of multi_cpu. 738 __attribute__((cpu_specific(ivybridge, atom))) 739 void multi_cpu(void){} 740 741A dispatching (or resolving) function can be declared anywhere in a project's 742source code with ``cpu_dispatch``. This attribute takes one or more CPU names 743as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch`` 744are not expected to be defined, only declared. If such a marked function has a 745definition, any side effects of the function are ignored; trivial function 746bodies are permissible for ICC compatibility. 747 748.. code-block:: c 749 750 // Creates a resolver for single_cpu above. 751 __attribute__((cpu_dispatch(ivybridge, atom))) 752 void single_cpu(void){} 753 754 // Creates a resolver for multi_cpu, but adds a 3rd version defined in another 755 // translation unit. 756 __attribute__((cpu_dispatch(ivybridge, atom, sandybridge))) 757 void multi_cpu(void){} 758 759Note that it is possible to have a resolving function that dispatches based on 760more or fewer options than are present in the program. Specifying fewer will 761result in the omitted options not being considered during resolution. Specifying 762a version for resolution that isn't defined in the program will result in a 763linking failure. 764 765It is also possible to specify a CPU name of ``generic`` which will be resolved 766if the executing processor doesn't satisfy the features required in the CPU 767name. The behavior of a program executing on a processor that doesn't satisfy 768any option of a multiversioned function is undefined. 769 770 771deprecated 772---------- 773.. csv-table:: Supported Syntaxes 774 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 775 776 "``deprecated``","``gnu::deprecated`` |br| ``deprecated``","``deprecated``","``deprecated``","","","" 777 778The ``deprecated`` attribute can be applied to a function, a variable, or a 779type. This is useful when identifying functions, variables, or types that are 780expected to be removed in a future version of a program. 781 782Consider the function declaration for a hypothetical function ``f``: 783 784.. code-block:: c++ 785 786 void f(void) __attribute__((deprecated("message", "replacement"))); 787 788When spelled as `__attribute__((deprecated))`, the deprecated attribute can have 789two optional string arguments. The first one is the message to display when 790emitting the warning; the second one enables the compiler to provide a Fix-It 791to replace the deprecated name with a new name. Otherwise, when spelled as 792`[[gnu::deprecated]] or [[deprecated]]`, the attribute can have one optional 793string argument which is the message to display when emitting the warning. 794 795 796diagnose_if 797----------- 798.. csv-table:: Supported Syntaxes 799 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 800 801 "``diagnose_if``","","","","","","" 802 803The ``diagnose_if`` attribute can be placed on function declarations to emit 804warnings or errors at compile-time if calls to the attributed function meet 805certain user-defined criteria. For example: 806 807.. code-block:: c 808 809 int abs(int a) 810 __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning"))); 811 int must_abs(int a) 812 __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error"))); 813 814 int val = abs(1); // warning: Redundant abs call 815 int val2 = must_abs(1); // error: Redundant abs call 816 int val3 = abs(val); 817 int val4 = must_abs(val); // Because run-time checks are not emitted for 818 // diagnose_if attributes, this executes without 819 // issue. 820 821 822``diagnose_if`` is closely related to ``enable_if``, with a few key differences: 823 824* Overload resolution is not aware of ``diagnose_if`` attributes: they're 825 considered only after we select the best candidate from a given candidate set. 826* Function declarations that differ only in their ``diagnose_if`` attributes are 827 considered to be redeclarations of the same function (not overloads). 828* If the condition provided to ``diagnose_if`` cannot be evaluated, no 829 diagnostic will be emitted. 830 831Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``. 832 833As a result of bullet number two, ``diagnose_if`` attributes will stack on the 834same function. For example: 835 836.. code-block:: c 837 838 int foo() __attribute__((diagnose_if(1, "diag1", "warning"))); 839 int foo() __attribute__((diagnose_if(1, "diag2", "warning"))); 840 841 int bar = foo(); // warning: diag1 842 // warning: diag2 843 int (*fooptr)(void) = foo; // warning: diag1 844 // warning: diag2 845 846 constexpr int supportsAPILevel(int N) { return N < 5; } 847 int baz(int a) 848 __attribute__((diagnose_if(!supportsAPILevel(10), 849 "Upgrade to API level 10 to use baz", "error"))); 850 int baz(int a) 851 __attribute__((diagnose_if(!a, "0 is not recommended.", "warning"))); 852 853 int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz 854 int v = baz(0); // error: Upgrade to API level 10 to use baz 855 856Query for this feature with ``__has_attribute(diagnose_if)``. 857 858 859disable_tail_calls 860------------------ 861.. csv-table:: Supported Syntaxes 862 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 863 864 "``disable_tail_calls``","``clang::disable_tail_calls``","``clang::disable_tail_calls``","","","","Yes" 865 866The ``disable_tail_calls`` attribute instructs the backend to not perform tail call optimization inside the marked function. 867 868For example: 869 870 .. code-block:: c 871 872 int callee(int); 873 874 int foo(int a) __attribute__((disable_tail_calls)) { 875 return callee(a); // This call is not tail-call optimized. 876 } 877 878Marking virtual functions as ``disable_tail_calls`` is legal. 879 880 .. code-block:: c++ 881 882 int callee(int); 883 884 class Base { 885 public: 886 [[clang::disable_tail_calls]] virtual int foo1() { 887 return callee(); // This call is not tail-call optimized. 888 } 889 }; 890 891 class Derived1 : public Base { 892 public: 893 int foo1() override { 894 return callee(); // This call is tail-call optimized. 895 } 896 }; 897 898 899enable_if 900--------- 901.. csv-table:: Supported Syntaxes 902 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 903 904 "``enable_if``","","","","","","Yes" 905 906.. Note:: Some features of this attribute are experimental. The meaning of 907 multiple enable_if attributes on a single declaration is subject to change in 908 a future version of clang. Also, the ABI is not standardized and the name 909 mangling may change in future versions. To avoid that, use asm labels. 910 911The ``enable_if`` attribute can be placed on function declarations to control 912which overload is selected based on the values of the function's arguments. 913When combined with the ``overloadable`` attribute, this feature is also 914available in C. 915 916.. code-block:: c++ 917 918 int isdigit(int c); 919 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"))); 920 921 void foo(char c) { 922 isdigit(c); 923 isdigit(10); 924 isdigit(-10); // results in a compile-time error. 925 } 926 927The enable_if attribute takes two arguments, the first is an expression written 928in terms of the function parameters, the second is a string explaining why this 929overload candidate could not be selected to be displayed in diagnostics. The 930expression is part of the function signature for the purposes of determining 931whether it is a redeclaration (following the rules used when determining 932whether a C++ template specialization is ODR-equivalent), but is not part of 933the type. 934 935The enable_if expression is evaluated as if it were the body of a 936bool-returning constexpr function declared with the arguments of the function 937it is being applied to, then called with the parameters at the call site. If the 938result is false or could not be determined through constant expression 939evaluation, then this overload will not be chosen and the provided string may 940be used in a diagnostic if the compile fails as a result. 941 942Because the enable_if expression is an unevaluated context, there are no global 943state changes, nor the ability to pass information from the enable_if 944expression to the function body. For example, suppose we want calls to 945strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of 946strbuf) only if the size of strbuf can be determined: 947 948.. code-block:: c++ 949 950 __attribute__((always_inline)) 951 static inline size_t strnlen(const char *s, size_t maxlen) 952 __attribute__((overloadable)) 953 __attribute__((enable_if(__builtin_object_size(s, 0) != -1))), 954 "chosen when the buffer size is known but 'maxlen' is not"))) 955 { 956 return strnlen_chk(s, maxlen, __builtin_object_size(s, 0)); 957 } 958 959Multiple enable_if attributes may be applied to a single declaration. In this 960case, the enable_if expressions are evaluated from left to right in the 961following manner. First, the candidates whose enable_if expressions evaluate to 962false or cannot be evaluated are discarded. If the remaining candidates do not 963share ODR-equivalent enable_if expressions, the overload resolution is 964ambiguous. Otherwise, enable_if overload resolution continues with the next 965enable_if attribute on the candidates that have not been discarded and have 966remaining enable_if attributes. In this way, we pick the most specific 967overload out of a number of viable overloads using enable_if. 968 969.. code-block:: c++ 970 971 void f() __attribute__((enable_if(true, ""))); // #1 972 void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2 973 974 void g(int i, int j) __attribute__((enable_if(i, ""))); // #1 975 void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2 976 977In this example, a call to f() is always resolved to #2, as the first enable_if 978expression is ODR-equivalent for both declarations, but #1 does not have another 979enable_if expression to continue evaluating, so the next round of evaluation has 980only a single candidate. In a call to g(1, 1), the call is ambiguous even though 981#2 has more enable_if attributes, because the first enable_if expressions are 982not ODR-equivalent. 983 984Query for this feature with ``__has_attribute(enable_if)``. 985 986Note that functions with one or more ``enable_if`` attributes may not have 987their address taken, unless all of the conditions specified by said 988``enable_if`` are constants that evaluate to ``true``. For example: 989 990.. code-block:: c 991 992 const int TrueConstant = 1; 993 const int FalseConstant = 0; 994 int f(int a) __attribute__((enable_if(a > 0, ""))); 995 int g(int a) __attribute__((enable_if(a == 0 || a != 0, ""))); 996 int h(int a) __attribute__((enable_if(1, ""))); 997 int i(int a) __attribute__((enable_if(TrueConstant, ""))); 998 int j(int a) __attribute__((enable_if(FalseConstant, ""))); 999 1000 void fn() { 1001 int (*ptr)(int); 1002 ptr = &f; // error: 'a > 0' is not always true 1003 ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant 1004 ptr = &h; // OK: 1 is a truthy constant 1005 ptr = &i; // OK: 'TrueConstant' is a truthy constant 1006 ptr = &j; // error: 'FalseConstant' is a constant, but not truthy 1007 } 1008 1009Because ``enable_if`` evaluation happens during overload resolution, 1010``enable_if`` may give unintuitive results when used with templates, depending 1011on when overloads are resolved. In the example below, clang will emit a 1012diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``: 1013 1014.. code-block:: c++ 1015 1016 double foo(int i) __attribute__((enable_if(i > 0, ""))); 1017 void *foo(int i) __attribute__((enable_if(i <= 0, ""))); 1018 template <int I> 1019 auto bar() { return foo(I); } 1020 1021 template <typename T> 1022 auto baz() { return foo(T::number); } 1023 1024 struct WithNumber { constexpr static int number = 1; }; 1025 void callThem() { 1026 bar<sizeof(WithNumber)>(); 1027 baz<WithNumber>(); 1028 } 1029 1030This is because, in ``bar``, ``foo`` is resolved prior to template 1031instantiation, so the value for ``I`` isn't known (thus, both ``enable_if`` 1032conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during 1033template instantiation, so the value for ``T::number`` is known. 1034 1035 1036exclude_from_explicit_instantiation 1037----------------------------------- 1038.. csv-table:: Supported Syntaxes 1039 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1040 1041 "``exclude_from_explicit_instantiation``","``clang::exclude_from_explicit_instantiation``","``clang::exclude_from_explicit_instantiation``","","","","Yes" 1042 1043The ``exclude_from_explicit_instantiation`` attribute opts-out a member of a 1044class template from being part of explicit template instantiations of that 1045class template. This means that an explicit instantiation will not instantiate 1046members of the class template marked with the attribute, but also that code 1047where an extern template declaration of the enclosing class template is visible 1048will not take for granted that an external instantiation of the class template 1049would provide those members (which would otherwise be a link error, since the 1050explicit instantiation won't provide those members). For example, let's say we 1051don't want the ``data()`` method to be part of libc++'s ABI. To make sure it 1052is not exported from the dylib, we give it hidden visibility: 1053 1054 .. code-block:: c++ 1055 1056 // in <string> 1057 template <class CharT> 1058 class basic_string { 1059 public: 1060 __attribute__((__visibility__("hidden"))) 1061 const value_type* data() const noexcept { ... } 1062 }; 1063 1064 template class basic_string<char>; 1065 1066Since an explicit template instantiation declaration for ``basic_string<char>`` 1067is provided, the compiler is free to assume that ``basic_string<char>::data()`` 1068will be provided by another translation unit, and it is free to produce an 1069external call to this function. However, since ``data()`` has hidden visibility 1070and the explicit template instantiation is provided in a shared library (as 1071opposed to simply another translation unit), ``basic_string<char>::data()`` 1072won't be found and a link error will ensue. This happens because the compiler 1073assumes that ``basic_string<char>::data()`` is part of the explicit template 1074instantiation declaration, when it really isn't. To tell the compiler that 1075``data()`` is not part of the explicit template instantiation declaration, the 1076``exclude_from_explicit_instantiation`` attribute can be used: 1077 1078 .. code-block:: c++ 1079 1080 // in <string> 1081 template <class CharT> 1082 class basic_string { 1083 public: 1084 __attribute__((__visibility__("hidden"))) 1085 __attribute__((exclude_from_explicit_instantiation)) 1086 const value_type* data() const noexcept { ... } 1087 }; 1088 1089 template class basic_string<char>; 1090 1091Now, the compiler won't assume that ``basic_string<char>::data()`` is provided 1092externally despite there being an explicit template instantiation declaration: 1093the compiler will implicitly instantiate ``basic_string<char>::data()`` in the 1094TUs where it is used. 1095 1096This attribute can be used on static and non-static member functions of class 1097templates, static data members of class templates and member classes of class 1098templates. 1099 1100 1101external_source_symbol 1102---------------------- 1103.. csv-table:: Supported Syntaxes 1104 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1105 1106 "``external_source_symbol``","``clang::external_source_symbol``","``clang::external_source_symbol``","","","","Yes" 1107 1108The ``external_source_symbol`` attribute specifies that a declaration originates 1109from an external source and describes the nature of that source. 1110 1111The fact that Clang is capable of recognizing declarations that were defined 1112externally can be used to provide better tooling support for mixed-language 1113projects or projects that rely on auto-generated code. For instance, an IDE that 1114uses Clang and that supports mixed-language projects can use this attribute to 1115provide a correct 'jump-to-definition' feature. For a concrete example, 1116consider a protocol that's defined in a Swift file: 1117 1118.. code-block:: swift 1119 1120 @objc public protocol SwiftProtocol { 1121 func method() 1122 } 1123 1124This protocol can be used from Objective-C code by including a header file that 1125was generated by the Swift compiler. The declarations in that header can use 1126the ``external_source_symbol`` attribute to make Clang aware of the fact 1127that ``SwiftProtocol`` actually originates from a Swift module: 1128 1129.. code-block:: objc 1130 1131 __attribute__((external_source_symbol(language="Swift",defined_in="module"))) 1132 @protocol SwiftProtocol 1133 @required 1134 - (void) method; 1135 @end 1136 1137Consequently, when 'jump-to-definition' is performed at a location that 1138references ``SwiftProtocol``, the IDE can jump to the original definition in 1139the Swift source file rather than jumping to the Objective-C declaration in the 1140auto-generated header file. 1141 1142The ``external_source_symbol`` attribute is a comma-separated list that includes 1143clauses that describe the origin and the nature of the particular declaration. 1144Those clauses can be: 1145 1146language=\ *string-literal* 1147 The name of the source language in which this declaration was defined. 1148 1149defined_in=\ *string-literal* 1150 The name of the source container in which the declaration was defined. The 1151 exact definition of source container is language-specific, e.g. Swift's 1152 source containers are modules, so ``defined_in`` should specify the Swift 1153 module name. 1154 1155generated_declaration 1156 This declaration was automatically generated by some tool. 1157 1158The clauses can be specified in any order. The clauses that are listed above are 1159all optional, but the attribute has to have at least one clause. 1160 1161 1162flatten 1163------- 1164.. csv-table:: Supported Syntaxes 1165 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1166 1167 "``flatten``","``gnu::flatten``","","","","","Yes" 1168 1169The ``flatten`` attribute causes calls within the attributed function to 1170be inlined unless it is impossible to do so, for example if the body of the 1171callee is unavailable or if the callee has the ``noinline`` attribute. 1172 1173 1174force_align_arg_pointer 1175----------------------- 1176.. csv-table:: Supported Syntaxes 1177 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1178 1179 "``force_align_arg_pointer``","``gnu::force_align_arg_pointer``","","","","","" 1180 1181Use this attribute to force stack alignment. 1182 1183Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions 1184(like 'movaps') that work with the stack require operands to be 16-byte aligned. 1185This attribute realigns the stack in the function prologue to make sure the 1186stack can be used with SSE instructions. 1187 1188Note that the x86_64 ABI forces 16-byte stack alignment at the call site. 1189Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in 1190rare cases where the caller does not align the stack properly (e.g. flow 1191jumps from i386 arch code). 1192 1193 .. code-block:: c 1194 1195 __attribute__ ((force_align_arg_pointer)) 1196 void f () { 1197 ... 1198 } 1199 1200 1201format 1202------ 1203.. csv-table:: Supported Syntaxes 1204 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1205 1206 "``format``","``gnu::format``","","","","","" 1207 1208Clang supports the ``format`` attribute, which indicates that the function 1209accepts a ``printf`` or ``scanf``-like format string and corresponding 1210arguments or a ``va_list`` that contains these arguments. 1211 1212Please see `GCC documentation about format attribute 1213<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details 1214about attribute syntax. 1215 1216Clang implements two kinds of checks with this attribute. 1217 1218#. Clang checks that the function with the ``format`` attribute is called with 1219 a format string that uses format specifiers that are allowed, and that 1220 arguments match the format string. This is the ``-Wformat`` warning, it is 1221 on by default. 1222 1223#. Clang checks that the format string argument is a literal string. This is 1224 the ``-Wformat-nonliteral`` warning, it is off by default. 1225 1226 Clang implements this mostly the same way as GCC, but there is a difference 1227 for functions that accept a ``va_list`` argument (for example, ``vprintf``). 1228 GCC does not emit ``-Wformat-nonliteral`` warning for calls to such 1229 functions. Clang does not warn if the format string comes from a function 1230 parameter, where the function is annotated with a compatible attribute, 1231 otherwise it warns. For example: 1232 1233 .. code-block:: c 1234 1235 __attribute__((__format__ (__scanf__, 1, 3))) 1236 void foo(const char* s, char *buf, ...) { 1237 va_list ap; 1238 va_start(ap, buf); 1239 1240 vprintf(s, ap); // warning: format string is not a string literal 1241 } 1242 1243 In this case we warn because ``s`` contains a format string for a 1244 ``scanf``-like function, but it is passed to a ``printf``-like function. 1245 1246 If the attribute is removed, clang still warns, because the format string is 1247 not a string literal. 1248 1249 Another example: 1250 1251 .. code-block:: c 1252 1253 __attribute__((__format__ (__printf__, 1, 3))) 1254 void foo(const char* s, char *buf, ...) { 1255 va_list ap; 1256 va_start(ap, buf); 1257 1258 vprintf(s, ap); // warning 1259 } 1260 1261 In this case Clang does not warn because the format string ``s`` and 1262 the corresponding arguments are annotated. If the arguments are 1263 incorrect, the caller of ``foo`` will receive a warning. 1264 1265 1266gnu_inline 1267---------- 1268.. csv-table:: Supported Syntaxes 1269 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1270 1271 "``gnu_inline``","``gnu::gnu_inline``","","","","","Yes" 1272 1273The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline 1274semantics, meaning: 1275 1276* If any declaration that is declared ``inline`` is not declared ``extern``, 1277 then the ``inline`` keyword is just a hint. In particular, an out-of-line 1278 definition is still emitted for a function with external linkage, even if all 1279 call sites are inlined, unlike in C99 and C++ inline semantics. 1280 1281* If all declarations that are declared ``inline`` are also declared 1282 ``extern``, then the function body is present only for inlining and no 1283 out-of-line version is emitted. 1284 1285Some important consequences: ``static inline`` emits an out-of-line 1286version if needed, a plain ``inline`` definition emits an out-of-line version 1287always, and an ``extern inline`` definition (in a header) followed by a 1288(non-``extern``) ``inline`` declaration in a source file emits an out-of-line 1289version of the function in that source file but provides the function body for 1290inlining to all includers of the header. 1291 1292Either ``__GNUC_GNU_INLINE__`` (GNU inline semantics) or 1293``__GNUC_STDC_INLINE__`` (C99 semantics) will be defined (they are mutually 1294exclusive). If ``__GNUC_STDC_INLINE__`` is defined, then the ``gnu_inline`` 1295function attribute can be used to get GNU inline semantics on a per function 1296basis. If ``__GNUC_GNU_INLINE__`` is defined, then the translation unit is 1297already being compiled with GNU inline semantics as the implied default. It is 1298unspecified which macro is defined in a C++ compilation. 1299 1300GNU inline semantics are the default behavior with ``-std=gnu89``, 1301``-std=c89``, ``-std=c94``, or ``-fgnu89-inline``. 1302 1303 1304ifunc 1305----- 1306.. csv-table:: Supported Syntaxes 1307 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1308 1309 "``ifunc``","``gnu::ifunc``","","","","","Yes" 1310 1311``__attribute__((ifunc("resolver")))`` is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function. 1312 1313The 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 return a pointer. 1314 1315The ``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. 1316 1317Not all targets support this attribute. ELF target support depends on both the linker and runtime linker, and is available in at least lld 4.0 and later, binutils 2.20.1 and later, glibc v2.11.1 and later, and FreeBSD 9.1 and later. Non-ELF targets currently do not support this attribute. 1318 1319 1320import_module 1321------------- 1322.. csv-table:: Supported Syntaxes 1323 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1324 1325 "``import_module``","``clang::import_module``","``clang::import_module``","","","","Yes" 1326 1327Clang supports the ``__attribute__((import_module(<module_name>)))`` 1328attribute for the WebAssembly target. This attribute may be attached to a 1329function declaration, where it modifies how the symbol is to be imported 1330within the WebAssembly linking environment. 1331 1332WebAssembly imports use a two-level namespace scheme, consisting of a module 1333name, which typically identifies a module from which to import, and a field 1334name, which typically identifies a field from that module to import. By 1335default, module names for C/C++ symbols are assigned automatically by the 1336linker. This attribute can be used to override the default behavior, and 1337reuqest a specific module name be used instead. 1338 1339 1340import_name 1341----------- 1342.. csv-table:: Supported Syntaxes 1343 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1344 1345 "``import_name``","``clang::import_name``","``clang::import_name``","","","","Yes" 1346 1347Clang supports the ``__attribute__((import_name(<name>)))`` 1348attribute for the WebAssembly target. This attribute may be attached to a 1349function declaration, where it modifies how the symbol is to be imported 1350within the WebAssembly linking environment. 1351 1352WebAssembly imports use a two-level namespace scheme, consisting of a module 1353name, which typically identifies a module from which to import, and a field 1354name, which typically identifies a field from that module to import. By 1355default, field names for C/C++ symbols are the same as their C/C++ symbol 1356names. This attribute can be used to override the default behavior, and 1357reuqest a specific field name be used instead. 1358 1359 1360internal_linkage 1361---------------- 1362.. csv-table:: Supported Syntaxes 1363 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1364 1365 "``internal_linkage``","``clang::internal_linkage``","``clang::internal_linkage``","","","","Yes" 1366 1367The ``internal_linkage`` attribute changes the linkage type of the declaration to internal. 1368This is similar to C-style ``static``, but can be used on classes and class methods. When applied to a class definition, 1369this attribute affects all methods and static data members of that class. 1370This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables. 1371 1372 1373interrupt (ARM) 1374--------------- 1375.. csv-table:: Supported Syntaxes 1376 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1377 1378 "``interrupt``","``gnu::interrupt``","","","","","" 1379 1380Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on 1381ARM targets. This attribute may be attached to a function definition and 1382instructs the backend to generate appropriate function entry/exit code so that 1383it can be used directly as an interrupt service routine. 1384 1385The parameter passed to the interrupt attribute is optional, but if 1386provided it must be a string literal with one of the following values: "IRQ", 1387"FIQ", "SWI", "ABORT", "UNDEF". 1388 1389The semantics are as follows: 1390 1391- If the function is AAPCS, Clang instructs the backend to realign the stack to 1392 8 bytes on entry. This is a general requirement of the AAPCS at public 1393 interfaces, but may not hold when an exception is taken. Doing this allows 1394 other AAPCS functions to be called. 1395- If the CPU is M-class this is all that needs to be done since the architecture 1396 itself is designed in such a way that functions obeying the normal AAPCS ABI 1397 constraints are valid exception handlers. 1398- If the CPU is not M-class, the prologue and epilogue are modified to save all 1399 non-banked registers that are used, so that upon return the user-mode state 1400 will not be corrupted. Note that to avoid unnecessary overhead, only 1401 general-purpose (integer) registers are saved in this way. If VFP operations 1402 are needed, that state must be saved manually. 1403 1404 Specifically, interrupt kinds other than "FIQ" will save all core registers 1405 except "lr" and "sp". "FIQ" interrupts will save r0-r7. 1406- If the CPU is not M-class, the return instruction is changed to one of the 1407 canonical sequences permitted by the architecture for exception return. Where 1408 possible the function itself will make the necessary "lr" adjustments so that 1409 the "preferred return address" is selected. 1410 1411 Unfortunately the compiler is unable to make this guarantee for an "UNDEF" 1412 handler, where the offset from "lr" to the preferred return address depends on 1413 the execution state of the code which generated the exception. In this case 1414 a sequence equivalent to "movs pc, lr" will be used. 1415 1416 1417interrupt (AVR) 1418--------------- 1419.. csv-table:: Supported Syntaxes 1420 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1421 1422 "``interrupt``","``gnu::interrupt``","","","","","Yes" 1423 1424Clang supports the GNU style ``__attribute__((interrupt))`` attribute on 1425AVR targets. This attribute may be attached to a function definition and instructs 1426the backend to generate appropriate function entry/exit code so that it can be used 1427directly as an interrupt service routine. 1428 1429On the AVR, the hardware globally disables interrupts when an interrupt is executed. 1430The first instruction of an interrupt handler declared with this attribute is a SEI 1431instruction to re-enable interrupts. See also the signal attribute that 1432does not insert a SEI instruction. 1433 1434 1435interrupt (MIPS) 1436---------------- 1437.. csv-table:: Supported Syntaxes 1438 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1439 1440 "``interrupt``","``gnu::interrupt``","","","","","Yes" 1441 1442Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on 1443MIPS targets. This attribute may be attached to a function definition and instructs 1444the backend to generate appropriate function entry/exit code so that it can be used 1445directly as an interrupt service routine. 1446 1447By default, the compiler will produce a function prologue and epilogue suitable for 1448an interrupt service routine that handles an External Interrupt Controller (eic) 1449generated interrupt. This behaviour can be explicitly requested with the "eic" 1450argument. 1451 1452Otherwise, for use with vectored interrupt mode, the argument passed should be 1453of the form "vector=LEVEL" where LEVEL is one of the following values: 1454"sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will 1455then set the interrupt mask to the corresponding level which will mask all 1456interrupts up to and including the argument. 1457 1458The semantics are as follows: 1459 1460- The prologue is modified so that the Exception Program Counter (EPC) and 1461 Status coprocessor registers are saved to the stack. The interrupt mask is 1462 set so that the function can only be interrupted by a higher priority 1463 interrupt. The epilogue will restore the previous values of EPC and Status. 1464 1465- The prologue and epilogue are modified to save and restore all non-kernel 1466 registers as necessary. 1467 1468- The FPU is disabled in the prologue, as the floating pointer registers are not 1469 spilled to the stack. 1470 1471- The function return sequence is changed to use an exception return instruction. 1472 1473- The parameter sets the interrupt mask for the function corresponding to the 1474 interrupt level specified. If no mask is specified the interrupt mask 1475 defaults to "eic". 1476 1477 1478interrupt (RISCV) 1479----------------- 1480.. csv-table:: Supported Syntaxes 1481 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1482 1483 "``interrupt``","``gnu::interrupt``","","","","","Yes" 1484 1485Clang supports the GNU style ``__attribute__((interrupt))`` attribute on RISCV 1486targets. This attribute may be attached to a function definition and instructs 1487the backend to generate appropriate function entry/exit code so that it can be 1488used directly as an interrupt service routine. 1489 1490Permissible values for this parameter are ``user``, ``supervisor``, 1491and ``machine``. If there is no parameter, then it defaults to machine. 1492 1493Repeated interrupt attribute on the same declaration will cause a warning 1494to be emitted. In case of repeated declarations, the last one prevails. 1495 1496Refer to: 1497https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html 1498https://riscv.org/specifications/privileged-isa/ 1499The RISC-V Instruction Set Manual Volume II: Privileged Architecture 1500Version 1.10. 1501 1502 1503kernel 1504------ 1505.. csv-table:: Supported Syntaxes 1506 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1507 1508 "``kernel``","","","","","","Yes" 1509 1510``__attribute__((kernel))`` is used to mark a ``kernel`` function in 1511RenderScript. 1512 1513In RenderScript, ``kernel`` functions are used to express data-parallel 1514computations. The RenderScript runtime efficiently parallelizes ``kernel`` 1515functions to run on computational resources such as multi-core CPUs and GPUs. 1516See the RenderScript_ documentation for more information. 1517 1518.. _RenderScript: https://developer.android.com/guide/topics/renderscript/compute.html 1519 1520 1521lifetimebound 1522------------- 1523.. csv-table:: Supported Syntaxes 1524 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1525 1526 "``lifetimebound``","``clang::lifetimebound``","","","","","" 1527 1528The ``lifetimebound`` attribute indicates that a resource owned by 1529a function parameter or implicit object parameter 1530is retained by the return value of the annotated function 1531(or, for a parameter of a constructor, in the value of the constructed object). 1532It is only supported in C++. 1533 1534This attribute provides an experimental implementation of the facility 1535described in the C++ committee paper [http://wg21.link/p0936r0](P0936R0), 1536and is subject to change as the design of the corresponding functionality 1537changes. 1538 1539 1540long_call, far 1541-------------- 1542.. csv-table:: Supported Syntaxes 1543 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1544 1545 "``long_call`` |br| ``far``","``gnu::long_call`` |br| ``gnu::far``","","","","","Yes" 1546 1547Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``, 1548and ``__attribute__((near))`` attributes on MIPS targets. These attributes may 1549only be added to function declarations and change the code generated 1550by the compiler when directly calling the function. The ``near`` attribute 1551allows calls to the function to be made using the ``jal`` instruction, which 1552requires the function to be located in the same naturally aligned 256MB 1553segment as the caller. The ``long_call`` and ``far`` attributes are synonyms 1554and require the use of a different call sequence that works regardless 1555of the distance between the functions. 1556 1557These attributes have no effect for position-independent code. 1558 1559These attributes take priority over command line switches such 1560as ``-mlong-calls`` and ``-mno-long-calls``. 1561 1562 1563micromips 1564--------- 1565.. csv-table:: Supported Syntaxes 1566 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1567 1568 "``micromips``","``gnu::micromips``","","","","","Yes" 1569 1570Clang supports the GNU style ``__attribute__((micromips))`` and 1571``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes 1572may be attached to a function definition and instructs the backend to generate 1573or not to generate microMIPS code for that function. 1574 1575These attributes override the `-mmicromips` and `-mno-micromips` options 1576on the command line. 1577 1578 1579min_vector_width 1580---------------- 1581.. csv-table:: Supported Syntaxes 1582 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1583 1584 "``min_vector_width``","``clang::min_vector_width``","``clang::min_vector_width``","","","","Yes" 1585 1586Clang supports the ``__attribute__((min_vector_width(width)))`` attribute. This 1587attribute may be attached to a function and informs the backend that this 1588function desires vectors of at least this width to be generated. Target-specific 1589maximum vector widths still apply. This means even if you ask for something 1590larger than the target supports, you will only get what the target supports. 1591This attribute is meant to be a hint to control target heuristics that may 1592generate narrower vectors than what the target hardware supports. 1593 1594This is currently used by the X86 target to allow some CPUs that support 512-bit 1595vectors to be limited to using 256-bit vectors to avoid frequency penalties. 1596This is currently enabled with the ``-prefer-vector-width=256`` command line 1597option. The ``min_vector_width`` attribute can be used to prevent the backend 1598from trying to split vector operations to match the ``prefer-vector-width``. All 1599X86 vector intrinsics from x86intrin.h already set this attribute. Additionally, 1600use of any of the X86-specific vector builtins will implicitly set this 1601attribute on the calling function. The intent is that explicitly writing vector 1602code using the X86 intrinsics will prevent ``prefer-vector-width`` from 1603affecting the code. 1604 1605 1606no_caller_saved_registers 1607------------------------- 1608.. csv-table:: Supported Syntaxes 1609 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1610 1611 "``no_caller_saved_registers``","``gnu::no_caller_saved_registers``","","","","","" 1612 1613Use this attribute to indicate that the specified function has no 1614caller-saved registers. That is, all registers are callee-saved except for 1615registers used for passing parameters to the function or returning parameters 1616from the function. 1617The compiler saves and restores any modified registers that were not used for 1618passing or returning arguments to the function. 1619 1620The user can call functions specified with the 'no_caller_saved_registers' 1621attribute from an interrupt handler without saving and restoring all 1622call-clobbered registers. 1623 1624Note that 'no_caller_saved_registers' attribute is not a calling convention. 1625In fact, it only overrides the decision of which registers should be saved by 1626the caller, but not how the parameters are passed from the caller to the callee. 1627 1628For example: 1629 1630 .. code-block:: c 1631 1632 __attribute__ ((no_caller_saved_registers, fastcall)) 1633 void f (int arg1, int arg2) { 1634 ... 1635 } 1636 1637 In this case parameters 'arg1' and 'arg2' will be passed in registers. 1638 In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as 1639 register parameters. However, it will not assume any scratch registers and 1640 should save and restore any modified registers except for ECX and EDX. 1641 1642 1643no_sanitize 1644----------- 1645.. csv-table:: Supported Syntaxes 1646 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1647 1648 "``no_sanitize``","``clang::no_sanitize``","``clang::no_sanitize``","","","","Yes" 1649 1650Use the ``no_sanitize`` attribute on a function or a global variable 1651declaration to specify that a particular instrumentation or set of 1652instrumentations should not be applied. The attribute takes a list of 1653string literals, which have the same meaning as values accepted by the 1654``-fno-sanitize=`` flag. For example, 1655``__attribute__((no_sanitize("address", "thread")))`` specifies that 1656AddressSanitizer and ThreadSanitizer should not be applied to the 1657function or variable. 1658 1659See :ref:`Controlling Code Generation <controlling-code-generation>` for a 1660full list of supported sanitizer flags. 1661 1662 1663no_sanitize_address, no_address_safety_analysis 1664----------------------------------------------- 1665.. csv-table:: Supported Syntaxes 1666 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1667 1668 "``no_address_safety_analysis`` |br| ``no_sanitize_address`` |br| ``no_sanitize_thread`` |br| ``no_sanitize_memory``","``gnu::no_address_safety_analysis`` |br| ``gnu::no_sanitize_address`` |br| ``gnu::no_sanitize_thread`` |br| ``clang::no_sanitize_memory``","``clang::no_sanitize_memory``","","","","Yes" 1669 1670.. _langext-address_sanitizer: 1671 1672Use ``__attribute__((no_sanitize_address))`` on a function or a global 1673variable declaration to specify that address safety instrumentation 1674(e.g. AddressSanitizer) should not be applied. 1675 1676 1677no_sanitize_memory 1678------------------ 1679.. csv-table:: Supported Syntaxes 1680 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1681 1682 "``no_address_safety_analysis`` |br| ``no_sanitize_address`` |br| ``no_sanitize_thread`` |br| ``no_sanitize_memory``","``gnu::no_address_safety_analysis`` |br| ``gnu::no_sanitize_address`` |br| ``gnu::no_sanitize_thread`` |br| ``clang::no_sanitize_memory``","``clang::no_sanitize_memory``","","","","Yes" 1683 1684.. _langext-memory_sanitizer: 1685 1686Use ``__attribute__((no_sanitize_memory))`` on a function declaration to 1687specify that checks for uninitialized memory should not be inserted 1688(e.g. by MemorySanitizer). The function may still be instrumented by the tool 1689to avoid false positives in other places. 1690 1691 1692no_sanitize_thread 1693------------------ 1694.. csv-table:: Supported Syntaxes 1695 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1696 1697 "``no_address_safety_analysis`` |br| ``no_sanitize_address`` |br| ``no_sanitize_thread`` |br| ``no_sanitize_memory``","``gnu::no_address_safety_analysis`` |br| ``gnu::no_sanitize_address`` |br| ``gnu::no_sanitize_thread`` |br| ``clang::no_sanitize_memory``","``clang::no_sanitize_memory``","","","","Yes" 1698 1699.. _langext-thread_sanitizer: 1700 1701Use ``__attribute__((no_sanitize_thread))`` on a function declaration to 1702specify that checks for data races on plain (non-atomic) memory accesses should 1703not be inserted by ThreadSanitizer. The function is still instrumented by the 1704tool to avoid false positives and provide meaningful stack traces. 1705 1706 1707no_split_stack 1708-------------- 1709.. csv-table:: Supported Syntaxes 1710 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1711 1712 "``no_split_stack``","``gnu::no_split_stack``","","","","","Yes" 1713 1714The ``no_split_stack`` attribute disables the emission of the split stack 1715preamble for a particular function. It has no effect if ``-fsplit-stack`` 1716is not specified. 1717 1718 1719no_stack_protector 1720------------------ 1721.. csv-table:: Supported Syntaxes 1722 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1723 1724 "``no_stack_protector``","``clang::no_stack_protector``","``clang::no_stack_protector``","","","","Yes" 1725 1726Clang supports the ``__attribute__((no_stack_protector))`` attribute which disables 1727the stack protector on the specified function. This attribute is useful for 1728selectively disabling the stack protector on some functions when building with 1729``-fstack-protector`` compiler option. 1730 1731For example, it disables the stack protector for the function ``foo`` but function 1732``bar`` will still be built with the stack protector with the ``-fstack-protector`` 1733option. 1734 1735.. code-block:: c 1736 1737 int __attribute__((no_stack_protector)) 1738 foo (int x); // stack protection will be disabled for foo. 1739 1740 int bar(int y); // bar can be built with the stack protector. 1741 1742 1743noalias 1744------- 1745.. csv-table:: Supported Syntaxes 1746 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1747 1748 "","","","``noalias``","","","" 1749 1750The ``noalias`` attribute indicates that the only memory accesses inside 1751function are loads and stores from objects pointed to by its pointer-typed 1752arguments, with arbitrary offsets. 1753 1754 1755nocf_check 1756---------- 1757.. csv-table:: Supported Syntaxes 1758 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1759 1760 "``nocf_check``","``gnu::nocf_check``","","","","","Yes" 1761 1762Jump Oriented Programming attacks rely on tampering with addresses used by 1763indirect call / jmp, e.g. redirect control-flow to non-programmer 1764intended bytes in the binary. 1765X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow 1766Enforcement Technology (CET). IBT instruments ENDBR instructions used to 1767specify valid targets of indirect call / jmp. 1768The ``nocf_check`` attribute has two roles: 17691. Appertains to a function - do not add ENDBR instruction at the beginning of 1770the function. 17712. Appertains to a function pointer - do not track the target function of this 1772pointer (by adding nocf_check prefix to the indirect-call instruction). 1773 1774 1775nodiscard, warn_unused_result 1776----------------------------- 1777.. csv-table:: Supported Syntaxes 1778 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1779 1780 "``warn_unused_result``","``nodiscard`` |br| ``clang::warn_unused_result`` |br| ``gnu::warn_unused_result``","``nodiscard``","","","","Yes" 1781 1782Clang supports the ability to diagnose when the results of a function call 1783expression are discarded under suspicious circumstances. A diagnostic is 1784generated when a function or its return type is marked with ``[[nodiscard]]`` 1785(or ``__attribute__((warn_unused_result))``) and the function call appears as a 1786potentially-evaluated discarded-value expression that is not explicitly cast to 1787`void`. 1788 1789.. code-block: c++ 1790 struct [[nodiscard]] error_info { /*...*/ }; 1791 error_info enable_missile_safety_mode(); 1792 1793 void launch_missiles(); 1794 void test_missiles() { 1795 enable_missile_safety_mode(); // diagnoses 1796 launch_missiles(); 1797 } 1798 error_info &foo(); 1799 void f() { foo(); } // Does not diagnose, error_info is a reference. 1800 1801 1802noduplicate 1803----------- 1804.. csv-table:: Supported Syntaxes 1805 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1806 1807 "``noduplicate``","``clang::noduplicate``","``clang::noduplicate``","","","","Yes" 1808 1809The ``noduplicate`` attribute can be placed on function declarations to control 1810whether function calls to this function can be duplicated or not as a result of 1811optimizations. This is required for the implementation of functions with 1812certain special requirements, like the OpenCL "barrier" function, that might 1813need to be run concurrently by all the threads that are executing in lockstep 1814on the hardware. For example this attribute applied on the function 1815"nodupfunc" in the code below avoids that: 1816 1817.. code-block:: c 1818 1819 void nodupfunc() __attribute__((noduplicate)); 1820 // Setting it as a C++11 attribute is also valid 1821 // void nodupfunc() [[clang::noduplicate]]; 1822 void foo(); 1823 void bar(); 1824 1825 nodupfunc(); 1826 if (a > n) { 1827 foo(); 1828 } else { 1829 bar(); 1830 } 1831 1832gets possibly modified by some optimizations into code similar to this: 1833 1834.. code-block:: c 1835 1836 if (a > n) { 1837 nodupfunc(); 1838 foo(); 1839 } else { 1840 nodupfunc(); 1841 bar(); 1842 } 1843 1844where the call to "nodupfunc" is duplicated and sunk into the two branches 1845of the condition. 1846 1847 1848nomicromips 1849----------- 1850.. csv-table:: Supported Syntaxes 1851 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1852 1853 "``nomicromips``","``gnu::nomicromips``","","","","","Yes" 1854 1855Clang supports the GNU style ``__attribute__((micromips))`` and 1856``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes 1857may be attached to a function definition and instructs the backend to generate 1858or not to generate microMIPS code for that function. 1859 1860These attributes override the `-mmicromips` and `-mno-micromips` options 1861on the command line. 1862 1863 1864noreturn 1865-------- 1866.. csv-table:: Supported Syntaxes 1867 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1868 1869 "","``noreturn``","","","","","Yes" 1870 1871A function declared as ``[[noreturn]]`` shall not return to its caller. The 1872compiler will generate a diagnostic for a function declared as ``[[noreturn]]`` 1873that appears to be capable of returning to its caller. 1874 1875 1876not_tail_called 1877--------------- 1878.. csv-table:: Supported Syntaxes 1879 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1880 1881 "``not_tail_called``","``clang::not_tail_called``","``clang::not_tail_called``","","","","Yes" 1882 1883The ``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``. 1884 1885For example, it prevents tail-call optimization in the following case: 1886 1887 .. code-block:: c 1888 1889 int __attribute__((not_tail_called)) foo1(int); 1890 1891 int foo2(int a) { 1892 return foo1(a); // No tail-call optimization on direct calls. 1893 } 1894 1895However, it doesn't prevent tail-call optimization in this case: 1896 1897 .. code-block:: c 1898 1899 int __attribute__((not_tail_called)) foo1(int); 1900 1901 int foo2(int a) { 1902 int (*fn)(int) = &foo1; 1903 1904 // not_tail_called has no effect on an indirect call even if the call can be 1905 // resolved at compile time. 1906 return (*fn)(a); 1907 } 1908 1909Marking virtual functions as ``not_tail_called`` is an error: 1910 1911 .. code-block:: c++ 1912 1913 class Base { 1914 public: 1915 // not_tail_called on a virtual function is an error. 1916 [[clang::not_tail_called]] virtual int foo1(); 1917 1918 virtual int foo2(); 1919 1920 // Non-virtual functions can be marked ``not_tail_called``. 1921 [[clang::not_tail_called]] int foo3(); 1922 }; 1923 1924 class Derived1 : public Base { 1925 public: 1926 int foo1() override; 1927 1928 // not_tail_called on a virtual function is an error. 1929 [[clang::not_tail_called]] int foo2() override; 1930 }; 1931 1932 1933nothrow 1934------- 1935.. csv-table:: Supported Syntaxes 1936 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1937 1938 "``nothrow``","``gnu::nothrow``","","``nothrow``","","","Yes" 1939 1940Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style 1941``__declspec(nothrow)`` attribute as an equivalent of `noexcept` on function 1942declarations. This attribute informs the compiler that the annotated function 1943does not throw an exception. This prevents exception-unwinding. This attribute 1944is particularly useful on functions in the C Standard Library that are 1945guaranteed to not throw an exception. 1946 1947 1948ns_consumed 1949----------- 1950.. csv-table:: Supported Syntaxes 1951 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 1952 1953 "``ns_consumed``","``clang::ns_consumed``","``clang::ns_consumed``","","","","Yes" 1954 1955The behavior of a function with respect to reference counting for Foundation 1956(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 1957convention (e.g. functions starting with "get" are assumed to return at 1958``+0``). 1959 1960It can be overriden using a family of the following attributes. In 1961Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 1962a function communicates that the object is returned at ``+1``, and the caller 1963is responsible for freeing it. 1964Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 1965specifies that the object is returned at ``+0`` and the ownership remains with 1966the callee. 1967The annotation ``__attribute__((ns_consumes_self))`` specifies that 1968the Objective-C method call consumes the reference to ``self``, e.g. by 1969attaching it to a supplied parameter. 1970Additionally, parameters can have an annotation 1971``__attribute__((ns_consumed))``, which specifies that passing an owned object 1972as that parameter effectively transfers the ownership, and the caller is no 1973longer responsible for it. 1974These attributes affect code generation when interacting with ARC code, and 1975they are used by the Clang Static Analyzer. 1976 1977In C programs using CoreFoundation, a similar set of attributes: 1978``__attribute__((cf_returns_not_retained))``, 1979``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 1980have the same respective semantics when applied to CoreFoundation objects. 1981These attributes affect code generation when interacting with ARC code, and 1982they are used by the Clang Static Analyzer. 1983 1984Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 1985the same attribute family is present: 1986``__attribute__((os_returns_not_retained))``, 1987``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 1988with the same respective semantics. 1989Similar to ``__attribute__((ns_consumes_self))``, 1990``__attribute__((os_consumes_this))`` specifies that the method call consumes 1991the reference to "this" (e.g., when attaching it to a different object supplied 1992as a parameter). 1993Out parameters (parameters the function is meant to write into, 1994either via pointers-to-pointers or references-to-pointers) 1995may be annotated with ``__attribute__((os_returns_retained))`` 1996or ``__attribute__((os_returns_not_retained))`` which specifies that the object 1997written into the out parameter should (or respectively should not) be released 1998after use. 1999Since often out parameters may or may not be written depending on the exit 2000code of the function, 2001annotations ``__attribute__((os_returns_retained_on_zero))`` 2002and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2003an out parameter at ``+1`` is written if and only if the function returns a zero 2004(respectively non-zero) error code. 2005Observe that return-code-dependent out parameter annotations are only 2006available for retained out parameters, as non-retained object do not have to be 2007released by the callee. 2008These attributes are only used by the Clang Static Analyzer. 2009 2010The family of attributes ``X_returns_X_retained`` can be added to functions, 2011C++ methods, and Objective-C methods and properties. 2012Attributes ``X_consumed`` can be added to parameters of methods, functions, 2013and Objective-C methods. 2014 2015 2016ns_consumes_self 2017---------------- 2018.. csv-table:: Supported Syntaxes 2019 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2020 2021 "``ns_consumes_self``","``clang::ns_consumes_self``","``clang::ns_consumes_self``","","","","Yes" 2022 2023The behavior of a function with respect to reference counting for Foundation 2024(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2025convention (e.g. functions starting with "get" are assumed to return at 2026``+0``). 2027 2028It can be overriden using a family of the following attributes. In 2029Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2030a function communicates that the object is returned at ``+1``, and the caller 2031is responsible for freeing it. 2032Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2033specifies that the object is returned at ``+0`` and the ownership remains with 2034the callee. 2035The annotation ``__attribute__((ns_consumes_self))`` specifies that 2036the Objective-C method call consumes the reference to ``self``, e.g. by 2037attaching it to a supplied parameter. 2038Additionally, parameters can have an annotation 2039``__attribute__((ns_consumed))``, which specifies that passing an owned object 2040as that parameter effectively transfers the ownership, and the caller is no 2041longer responsible for it. 2042These attributes affect code generation when interacting with ARC code, and 2043they are used by the Clang Static Analyzer. 2044 2045In C programs using CoreFoundation, a similar set of attributes: 2046``__attribute__((cf_returns_not_retained))``, 2047``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2048have the same respective semantics when applied to CoreFoundation objects. 2049These attributes affect code generation when interacting with ARC code, and 2050they are used by the Clang Static Analyzer. 2051 2052Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2053the same attribute family is present: 2054``__attribute__((os_returns_not_retained))``, 2055``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2056with the same respective semantics. 2057Similar to ``__attribute__((ns_consumes_self))``, 2058``__attribute__((os_consumes_this))`` specifies that the method call consumes 2059the reference to "this" (e.g., when attaching it to a different object supplied 2060as a parameter). 2061Out parameters (parameters the function is meant to write into, 2062either via pointers-to-pointers or references-to-pointers) 2063may be annotated with ``__attribute__((os_returns_retained))`` 2064or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2065written into the out parameter should (or respectively should not) be released 2066after use. 2067Since often out parameters may or may not be written depending on the exit 2068code of the function, 2069annotations ``__attribute__((os_returns_retained_on_zero))`` 2070and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2071an out parameter at ``+1`` is written if and only if the function returns a zero 2072(respectively non-zero) error code. 2073Observe that return-code-dependent out parameter annotations are only 2074available for retained out parameters, as non-retained object do not have to be 2075released by the callee. 2076These attributes are only used by the Clang Static Analyzer. 2077 2078The family of attributes ``X_returns_X_retained`` can be added to functions, 2079C++ methods, and Objective-C methods and properties. 2080Attributes ``X_consumed`` can be added to parameters of methods, functions, 2081and Objective-C methods. 2082 2083 2084ns_returns_autoreleased 2085----------------------- 2086.. csv-table:: Supported Syntaxes 2087 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2088 2089 "``ns_returns_autoreleased``","``clang::ns_returns_autoreleased``","``clang::ns_returns_autoreleased``","","","","" 2090 2091The behavior of a function with respect to reference counting for Foundation 2092(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2093convention (e.g. functions starting with "get" are assumed to return at 2094``+0``). 2095 2096It can be overriden using a family of the following attributes. In 2097Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2098a function communicates that the object is returned at ``+1``, and the caller 2099is responsible for freeing it. 2100Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2101specifies that the object is returned at ``+0`` and the ownership remains with 2102the callee. 2103The annotation ``__attribute__((ns_consumes_self))`` specifies that 2104the Objective-C method call consumes the reference to ``self``, e.g. by 2105attaching it to a supplied parameter. 2106Additionally, parameters can have an annotation 2107``__attribute__((ns_consumed))``, which specifies that passing an owned object 2108as that parameter effectively transfers the ownership, and the caller is no 2109longer responsible for it. 2110These attributes affect code generation when interacting with ARC code, and 2111they are used by the Clang Static Analyzer. 2112 2113In C programs using CoreFoundation, a similar set of attributes: 2114``__attribute__((cf_returns_not_retained))``, 2115``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2116have the same respective semantics when applied to CoreFoundation objects. 2117These attributes affect code generation when interacting with ARC code, and 2118they are used by the Clang Static Analyzer. 2119 2120Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2121the same attribute family is present: 2122``__attribute__((os_returns_not_retained))``, 2123``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2124with the same respective semantics. 2125Similar to ``__attribute__((ns_consumes_self))``, 2126``__attribute__((os_consumes_this))`` specifies that the method call consumes 2127the reference to "this" (e.g., when attaching it to a different object supplied 2128as a parameter). 2129Out parameters (parameters the function is meant to write into, 2130either via pointers-to-pointers or references-to-pointers) 2131may be annotated with ``__attribute__((os_returns_retained))`` 2132or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2133written into the out parameter should (or respectively should not) be released 2134after use. 2135Since often out parameters may or may not be written depending on the exit 2136code of the function, 2137annotations ``__attribute__((os_returns_retained_on_zero))`` 2138and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2139an out parameter at ``+1`` is written if and only if the function returns a zero 2140(respectively non-zero) error code. 2141Observe that return-code-dependent out parameter annotations are only 2142available for retained out parameters, as non-retained object do not have to be 2143released by the callee. 2144These attributes are only used by the Clang Static Analyzer. 2145 2146The family of attributes ``X_returns_X_retained`` can be added to functions, 2147C++ methods, and Objective-C methods and properties. 2148Attributes ``X_consumed`` can be added to parameters of methods, functions, 2149and Objective-C methods. 2150 2151 2152ns_returns_not_retained 2153----------------------- 2154.. csv-table:: Supported Syntaxes 2155 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2156 2157 "``ns_returns_not_retained``","``clang::ns_returns_not_retained``","``clang::ns_returns_not_retained``","","","","" 2158 2159The behavior of a function with respect to reference counting for Foundation 2160(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2161convention (e.g. functions starting with "get" are assumed to return at 2162``+0``). 2163 2164It can be overriden using a family of the following attributes. In 2165Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2166a function communicates that the object is returned at ``+1``, and the caller 2167is responsible for freeing it. 2168Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2169specifies that the object is returned at ``+0`` and the ownership remains with 2170the callee. 2171The annotation ``__attribute__((ns_consumes_self))`` specifies that 2172the Objective-C method call consumes the reference to ``self``, e.g. by 2173attaching it to a supplied parameter. 2174Additionally, parameters can have an annotation 2175``__attribute__((ns_consumed))``, which specifies that passing an owned object 2176as that parameter effectively transfers the ownership, and the caller is no 2177longer responsible for it. 2178These attributes affect code generation when interacting with ARC code, and 2179they are used by the Clang Static Analyzer. 2180 2181In C programs using CoreFoundation, a similar set of attributes: 2182``__attribute__((cf_returns_not_retained))``, 2183``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2184have the same respective semantics when applied to CoreFoundation objects. 2185These attributes affect code generation when interacting with ARC code, and 2186they are used by the Clang Static Analyzer. 2187 2188Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2189the same attribute family is present: 2190``__attribute__((os_returns_not_retained))``, 2191``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2192with the same respective semantics. 2193Similar to ``__attribute__((ns_consumes_self))``, 2194``__attribute__((os_consumes_this))`` specifies that the method call consumes 2195the reference to "this" (e.g., when attaching it to a different object supplied 2196as a parameter). 2197Out parameters (parameters the function is meant to write into, 2198either via pointers-to-pointers or references-to-pointers) 2199may be annotated with ``__attribute__((os_returns_retained))`` 2200or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2201written into the out parameter should (or respectively should not) be released 2202after use. 2203Since often out parameters may or may not be written depending on the exit 2204code of the function, 2205annotations ``__attribute__((os_returns_retained_on_zero))`` 2206and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2207an out parameter at ``+1`` is written if and only if the function returns a zero 2208(respectively non-zero) error code. 2209Observe that return-code-dependent out parameter annotations are only 2210available for retained out parameters, as non-retained object do not have to be 2211released by the callee. 2212These attributes are only used by the Clang Static Analyzer. 2213 2214The family of attributes ``X_returns_X_retained`` can be added to functions, 2215C++ methods, and Objective-C methods and properties. 2216Attributes ``X_consumed`` can be added to parameters of methods, functions, 2217and Objective-C methods. 2218 2219 2220ns_returns_retained 2221------------------- 2222.. csv-table:: Supported Syntaxes 2223 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2224 2225 "``ns_returns_retained``","``clang::ns_returns_retained``","``clang::ns_returns_retained``","","","","" 2226 2227The behavior of a function with respect to reference counting for Foundation 2228(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2229convention (e.g. functions starting with "get" are assumed to return at 2230``+0``). 2231 2232It can be overriden using a family of the following attributes. In 2233Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2234a function communicates that the object is returned at ``+1``, and the caller 2235is responsible for freeing it. 2236Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2237specifies that the object is returned at ``+0`` and the ownership remains with 2238the callee. 2239The annotation ``__attribute__((ns_consumes_self))`` specifies that 2240the Objective-C method call consumes the reference to ``self``, e.g. by 2241attaching it to a supplied parameter. 2242Additionally, parameters can have an annotation 2243``__attribute__((ns_consumed))``, which specifies that passing an owned object 2244as that parameter effectively transfers the ownership, and the caller is no 2245longer responsible for it. 2246These attributes affect code generation when interacting with ARC code, and 2247they are used by the Clang Static Analyzer. 2248 2249In C programs using CoreFoundation, a similar set of attributes: 2250``__attribute__((cf_returns_not_retained))``, 2251``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2252have the same respective semantics when applied to CoreFoundation objects. 2253These attributes affect code generation when interacting with ARC code, and 2254they are used by the Clang Static Analyzer. 2255 2256Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2257the same attribute family is present: 2258``__attribute__((os_returns_not_retained))``, 2259``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2260with the same respective semantics. 2261Similar to ``__attribute__((ns_consumes_self))``, 2262``__attribute__((os_consumes_this))`` specifies that the method call consumes 2263the reference to "this" (e.g., when attaching it to a different object supplied 2264as a parameter). 2265Out parameters (parameters the function is meant to write into, 2266either via pointers-to-pointers or references-to-pointers) 2267may be annotated with ``__attribute__((os_returns_retained))`` 2268or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2269written into the out parameter should (or respectively should not) be released 2270after use. 2271Since often out parameters may or may not be written depending on the exit 2272code of the function, 2273annotations ``__attribute__((os_returns_retained_on_zero))`` 2274and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2275an out parameter at ``+1`` is written if and only if the function returns a zero 2276(respectively non-zero) error code. 2277Observe that return-code-dependent out parameter annotations are only 2278available for retained out parameters, as non-retained object do not have to be 2279released by the callee. 2280These attributes are only used by the Clang Static Analyzer. 2281 2282The family of attributes ``X_returns_X_retained`` can be added to functions, 2283C++ methods, and Objective-C methods and properties. 2284Attributes ``X_consumed`` can be added to parameters of methods, functions, 2285and Objective-C methods. 2286 2287 2288objc_boxable 2289------------ 2290.. csv-table:: Supported Syntaxes 2291 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2292 2293 "``objc_boxable``","``clang::objc_boxable``","``clang::objc_boxable``","","","","Yes" 2294 2295Structs and unions marked with the ``objc_boxable`` attribute can be used 2296with the Objective-C boxed expression syntax, ``@(...)``. 2297 2298**Usage**: ``__attribute__((objc_boxable))``. This attribute 2299can only be placed on a declaration of a trivially-copyable struct or union: 2300 2301.. code-block:: objc 2302 2303 struct __attribute__((objc_boxable)) some_struct { 2304 int i; 2305 }; 2306 union __attribute__((objc_boxable)) some_union { 2307 int i; 2308 float f; 2309 }; 2310 typedef struct __attribute__((objc_boxable)) _some_struct some_struct; 2311 2312 // ... 2313 2314 some_struct ss; 2315 NSValue *boxed = @(ss); 2316 2317 2318objc_method_family 2319------------------ 2320.. csv-table:: Supported Syntaxes 2321 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2322 2323 "``objc_method_family``","``clang::objc_method_family``","``clang::objc_method_family``","","","","Yes" 2324 2325Many methods in Objective-C have conventional meanings determined by their 2326selectors. It is sometimes useful to be able to mark a method as having a 2327particular conventional meaning despite not having the right selector, or as 2328not having the conventional meaning that its selector would suggest. For these 2329use cases, we provide an attribute to specifically describe the "method family" 2330that a method belongs to. 2331 2332**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of 2333``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This 2334attribute can only be placed at the end of a method declaration: 2335 2336.. code-block:: objc 2337 2338 - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); 2339 2340Users who do not wish to change the conventional meaning of a method, and who 2341merely want to document its non-standard retain and release semantics, should 2342use the retaining behavior attributes (``ns_returns_retained``, 2343``ns_returns_not_retained``, etc). 2344 2345Query for this feature with ``__has_attribute(objc_method_family)``. 2346 2347 2348objc_requires_super 2349------------------- 2350.. csv-table:: Supported Syntaxes 2351 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2352 2353 "``objc_requires_super``","``clang::objc_requires_super``","``clang::objc_requires_super``","","","","Yes" 2354 2355Some Objective-C classes allow a subclass to override a particular method in a 2356parent class but expect that the overriding method also calls the overridden 2357method in the parent class. For these cases, we provide an attribute to 2358designate that a method requires a "call to ``super``" in the overriding 2359method in the subclass. 2360 2361**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only 2362be placed at the end of a method declaration: 2363 2364.. code-block:: objc 2365 2366 - (void)foo __attribute__((objc_requires_super)); 2367 2368This attribute can only be applied the method declarations within a class, and 2369not a protocol. Currently this attribute does not enforce any placement of 2370where the call occurs in the overriding method (such as in the case of 2371``-dealloc`` where the call must appear at the end). It checks only that it 2372exists. 2373 2374Note that on both OS X and iOS that the Foundation framework provides a 2375convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this 2376attribute: 2377 2378.. code-block:: objc 2379 2380 - (void)foo NS_REQUIRES_SUPER; 2381 2382This macro is conditionally defined depending on the compiler's support for 2383this attribute. If the compiler does not support the attribute the macro 2384expands to nothing. 2385 2386Operationally, when a method has this annotation the compiler will warn if the 2387implementation of an override in a subclass does not call super. For example: 2388 2389.. code-block:: objc 2390 2391 warning: method possibly missing a [super AnnotMeth] call 2392 - (void) AnnotMeth{}; 2393 ^ 2394 2395 2396objc_runtime_name 2397----------------- 2398.. csv-table:: Supported Syntaxes 2399 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2400 2401 "``objc_runtime_name``","``clang::objc_runtime_name``","``clang::objc_runtime_name``","","","","Yes" 2402 2403By default, the Objective-C interface or protocol identifier is used 2404in the metadata name for that object. The `objc_runtime_name` 2405attribute allows annotated interfaces or protocols to use the 2406specified string argument in the object's metadata name instead of the 2407default name. 2408 2409**Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute 2410can only be placed before an @protocol or @interface declaration: 2411 2412.. code-block:: objc 2413 2414 __attribute__((objc_runtime_name("MyLocalName"))) 2415 @interface Message 2416 @end 2417 2418 2419objc_runtime_visible 2420-------------------- 2421.. csv-table:: Supported Syntaxes 2422 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2423 2424 "``objc_runtime_visible``","``clang::objc_runtime_visible``","``clang::objc_runtime_visible``","","","","Yes" 2425 2426This 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. 2427 2428 2429optnone 2430------- 2431.. csv-table:: Supported Syntaxes 2432 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2433 2434 "``optnone``","``clang::optnone``","``clang::optnone``","","","","Yes" 2435 2436The ``optnone`` attribute suppresses essentially all optimizations 2437on a function or method, regardless of the optimization level applied to 2438the compilation unit as a whole. This is particularly useful when you 2439need to debug a particular function, but it is infeasible to build the 2440entire application without optimization. Avoiding optimization on the 2441specified function can improve the quality of the debugging information 2442for that function. 2443 2444This attribute is incompatible with the ``always_inline`` and ``minsize`` 2445attributes. 2446 2447 2448os_consumed 2449----------- 2450.. csv-table:: Supported Syntaxes 2451 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2452 2453 "``os_consumed``","``clang::os_consumed``","``clang::os_consumed``","","","","Yes" 2454 2455The behavior of a function with respect to reference counting for Foundation 2456(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2457convention (e.g. functions starting with "get" are assumed to return at 2458``+0``). 2459 2460It can be overriden using a family of the following attributes. In 2461Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2462a function communicates that the object is returned at ``+1``, and the caller 2463is responsible for freeing it. 2464Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2465specifies that the object is returned at ``+0`` and the ownership remains with 2466the callee. 2467The annotation ``__attribute__((ns_consumes_self))`` specifies that 2468the Objective-C method call consumes the reference to ``self``, e.g. by 2469attaching it to a supplied parameter. 2470Additionally, parameters can have an annotation 2471``__attribute__((ns_consumed))``, which specifies that passing an owned object 2472as that parameter effectively transfers the ownership, and the caller is no 2473longer responsible for it. 2474These attributes affect code generation when interacting with ARC code, and 2475they are used by the Clang Static Analyzer. 2476 2477In C programs using CoreFoundation, a similar set of attributes: 2478``__attribute__((cf_returns_not_retained))``, 2479``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2480have the same respective semantics when applied to CoreFoundation objects. 2481These attributes affect code generation when interacting with ARC code, and 2482they are used by the Clang Static Analyzer. 2483 2484Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2485the same attribute family is present: 2486``__attribute__((os_returns_not_retained))``, 2487``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2488with the same respective semantics. 2489Similar to ``__attribute__((ns_consumes_self))``, 2490``__attribute__((os_consumes_this))`` specifies that the method call consumes 2491the reference to "this" (e.g., when attaching it to a different object supplied 2492as a parameter). 2493Out parameters (parameters the function is meant to write into, 2494either via pointers-to-pointers or references-to-pointers) 2495may be annotated with ``__attribute__((os_returns_retained))`` 2496or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2497written into the out parameter should (or respectively should not) be released 2498after use. 2499Since often out parameters may or may not be written depending on the exit 2500code of the function, 2501annotations ``__attribute__((os_returns_retained_on_zero))`` 2502and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2503an out parameter at ``+1`` is written if and only if the function returns a zero 2504(respectively non-zero) error code. 2505Observe that return-code-dependent out parameter annotations are only 2506available for retained out parameters, as non-retained object do not have to be 2507released by the callee. 2508These attributes are only used by the Clang Static Analyzer. 2509 2510The family of attributes ``X_returns_X_retained`` can be added to functions, 2511C++ methods, and Objective-C methods and properties. 2512Attributes ``X_consumed`` can be added to parameters of methods, functions, 2513and Objective-C methods. 2514 2515 2516os_consumes_this 2517---------------- 2518.. csv-table:: Supported Syntaxes 2519 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2520 2521 "``os_consumes_this``","``clang::os_consumes_this``","``clang::os_consumes_this``","","","","" 2522 2523The behavior of a function with respect to reference counting for Foundation 2524(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2525convention (e.g. functions starting with "get" are assumed to return at 2526``+0``). 2527 2528It can be overriden using a family of the following attributes. In 2529Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2530a function communicates that the object is returned at ``+1``, and the caller 2531is responsible for freeing it. 2532Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2533specifies that the object is returned at ``+0`` and the ownership remains with 2534the callee. 2535The annotation ``__attribute__((ns_consumes_self))`` specifies that 2536the Objective-C method call consumes the reference to ``self``, e.g. by 2537attaching it to a supplied parameter. 2538Additionally, parameters can have an annotation 2539``__attribute__((ns_consumed))``, which specifies that passing an owned object 2540as that parameter effectively transfers the ownership, and the caller is no 2541longer responsible for it. 2542These attributes affect code generation when interacting with ARC code, and 2543they are used by the Clang Static Analyzer. 2544 2545In C programs using CoreFoundation, a similar set of attributes: 2546``__attribute__((cf_returns_not_retained))``, 2547``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2548have the same respective semantics when applied to CoreFoundation objects. 2549These attributes affect code generation when interacting with ARC code, and 2550they are used by the Clang Static Analyzer. 2551 2552Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2553the same attribute family is present: 2554``__attribute__((os_returns_not_retained))``, 2555``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2556with the same respective semantics. 2557Similar to ``__attribute__((ns_consumes_self))``, 2558``__attribute__((os_consumes_this))`` specifies that the method call consumes 2559the reference to "this" (e.g., when attaching it to a different object supplied 2560as a parameter). 2561Out parameters (parameters the function is meant to write into, 2562either via pointers-to-pointers or references-to-pointers) 2563may be annotated with ``__attribute__((os_returns_retained))`` 2564or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2565written into the out parameter should (or respectively should not) be released 2566after use. 2567Since often out parameters may or may not be written depending on the exit 2568code of the function, 2569annotations ``__attribute__((os_returns_retained_on_zero))`` 2570and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2571an out parameter at ``+1`` is written if and only if the function returns a zero 2572(respectively non-zero) error code. 2573Observe that return-code-dependent out parameter annotations are only 2574available for retained out parameters, as non-retained object do not have to be 2575released by the callee. 2576These attributes are only used by the Clang Static Analyzer. 2577 2578The family of attributes ``X_returns_X_retained`` can be added to functions, 2579C++ methods, and Objective-C methods and properties. 2580Attributes ``X_consumed`` can be added to parameters of methods, functions, 2581and Objective-C methods. 2582 2583 2584os_returns_not_retained 2585----------------------- 2586.. csv-table:: Supported Syntaxes 2587 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2588 2589 "``os_returns_not_retained``","``clang::os_returns_not_retained``","``clang::os_returns_not_retained``","","","","Yes" 2590 2591The behavior of a function with respect to reference counting for Foundation 2592(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2593convention (e.g. functions starting with "get" are assumed to return at 2594``+0``). 2595 2596It can be overriden using a family of the following attributes. In 2597Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2598a function communicates that the object is returned at ``+1``, and the caller 2599is responsible for freeing it. 2600Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2601specifies that the object is returned at ``+0`` and the ownership remains with 2602the callee. 2603The annotation ``__attribute__((ns_consumes_self))`` specifies that 2604the Objective-C method call consumes the reference to ``self``, e.g. by 2605attaching it to a supplied parameter. 2606Additionally, parameters can have an annotation 2607``__attribute__((ns_consumed))``, which specifies that passing an owned object 2608as that parameter effectively transfers the ownership, and the caller is no 2609longer responsible for it. 2610These attributes affect code generation when interacting with ARC code, and 2611they are used by the Clang Static Analyzer. 2612 2613In C programs using CoreFoundation, a similar set of attributes: 2614``__attribute__((cf_returns_not_retained))``, 2615``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2616have the same respective semantics when applied to CoreFoundation objects. 2617These attributes affect code generation when interacting with ARC code, and 2618they are used by the Clang Static Analyzer. 2619 2620Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2621the same attribute family is present: 2622``__attribute__((os_returns_not_retained))``, 2623``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2624with the same respective semantics. 2625Similar to ``__attribute__((ns_consumes_self))``, 2626``__attribute__((os_consumes_this))`` specifies that the method call consumes 2627the reference to "this" (e.g., when attaching it to a different object supplied 2628as a parameter). 2629Out parameters (parameters the function is meant to write into, 2630either via pointers-to-pointers or references-to-pointers) 2631may be annotated with ``__attribute__((os_returns_retained))`` 2632or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2633written into the out parameter should (or respectively should not) be released 2634after use. 2635Since often out parameters may or may not be written depending on the exit 2636code of the function, 2637annotations ``__attribute__((os_returns_retained_on_zero))`` 2638and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2639an out parameter at ``+1`` is written if and only if the function returns a zero 2640(respectively non-zero) error code. 2641Observe that return-code-dependent out parameter annotations are only 2642available for retained out parameters, as non-retained object do not have to be 2643released by the callee. 2644These attributes are only used by the Clang Static Analyzer. 2645 2646The family of attributes ``X_returns_X_retained`` can be added to functions, 2647C++ methods, and Objective-C methods and properties. 2648Attributes ``X_consumed`` can be added to parameters of methods, functions, 2649and Objective-C methods. 2650 2651 2652os_returns_retained 2653------------------- 2654.. csv-table:: Supported Syntaxes 2655 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2656 2657 "``os_returns_retained``","``clang::os_returns_retained``","``clang::os_returns_retained``","","","","Yes" 2658 2659The behavior of a function with respect to reference counting for Foundation 2660(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2661convention (e.g. functions starting with "get" are assumed to return at 2662``+0``). 2663 2664It can be overriden using a family of the following attributes. In 2665Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2666a function communicates that the object is returned at ``+1``, and the caller 2667is responsible for freeing it. 2668Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2669specifies that the object is returned at ``+0`` and the ownership remains with 2670the callee. 2671The annotation ``__attribute__((ns_consumes_self))`` specifies that 2672the Objective-C method call consumes the reference to ``self``, e.g. by 2673attaching it to a supplied parameter. 2674Additionally, parameters can have an annotation 2675``__attribute__((ns_consumed))``, which specifies that passing an owned object 2676as that parameter effectively transfers the ownership, and the caller is no 2677longer responsible for it. 2678These attributes affect code generation when interacting with ARC code, and 2679they are used by the Clang Static Analyzer. 2680 2681In C programs using CoreFoundation, a similar set of attributes: 2682``__attribute__((cf_returns_not_retained))``, 2683``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2684have the same respective semantics when applied to CoreFoundation objects. 2685These attributes affect code generation when interacting with ARC code, and 2686they are used by the Clang Static Analyzer. 2687 2688Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2689the same attribute family is present: 2690``__attribute__((os_returns_not_retained))``, 2691``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2692with the same respective semantics. 2693Similar to ``__attribute__((ns_consumes_self))``, 2694``__attribute__((os_consumes_this))`` specifies that the method call consumes 2695the reference to "this" (e.g., when attaching it to a different object supplied 2696as a parameter). 2697Out parameters (parameters the function is meant to write into, 2698either via pointers-to-pointers or references-to-pointers) 2699may be annotated with ``__attribute__((os_returns_retained))`` 2700or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2701written into the out parameter should (or respectively should not) be released 2702after use. 2703Since often out parameters may or may not be written depending on the exit 2704code of the function, 2705annotations ``__attribute__((os_returns_retained_on_zero))`` 2706and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2707an out parameter at ``+1`` is written if and only if the function returns a zero 2708(respectively non-zero) error code. 2709Observe that return-code-dependent out parameter annotations are only 2710available for retained out parameters, as non-retained object do not have to be 2711released by the callee. 2712These attributes are only used by the Clang Static Analyzer. 2713 2714The family of attributes ``X_returns_X_retained`` can be added to functions, 2715C++ methods, and Objective-C methods and properties. 2716Attributes ``X_consumed`` can be added to parameters of methods, functions, 2717and Objective-C methods. 2718 2719 2720os_returns_retained_on_non_zero 2721------------------------------- 2722.. csv-table:: Supported Syntaxes 2723 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2724 2725 "``os_returns_retained_on_non_zero``","``clang::os_returns_retained_on_non_zero``","``clang::os_returns_retained_on_non_zero``","","","","Yes" 2726 2727The behavior of a function with respect to reference counting for Foundation 2728(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2729convention (e.g. functions starting with "get" are assumed to return at 2730``+0``). 2731 2732It can be overriden using a family of the following attributes. In 2733Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2734a function communicates that the object is returned at ``+1``, and the caller 2735is responsible for freeing it. 2736Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2737specifies that the object is returned at ``+0`` and the ownership remains with 2738the callee. 2739The annotation ``__attribute__((ns_consumes_self))`` specifies that 2740the Objective-C method call consumes the reference to ``self``, e.g. by 2741attaching it to a supplied parameter. 2742Additionally, parameters can have an annotation 2743``__attribute__((ns_consumed))``, which specifies that passing an owned object 2744as that parameter effectively transfers the ownership, and the caller is no 2745longer responsible for it. 2746These attributes affect code generation when interacting with ARC code, and 2747they are used by the Clang Static Analyzer. 2748 2749In C programs using CoreFoundation, a similar set of attributes: 2750``__attribute__((cf_returns_not_retained))``, 2751``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2752have the same respective semantics when applied to CoreFoundation objects. 2753These attributes affect code generation when interacting with ARC code, and 2754they are used by the Clang Static Analyzer. 2755 2756Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2757the same attribute family is present: 2758``__attribute__((os_returns_not_retained))``, 2759``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2760with the same respective semantics. 2761Similar to ``__attribute__((ns_consumes_self))``, 2762``__attribute__((os_consumes_this))`` specifies that the method call consumes 2763the reference to "this" (e.g., when attaching it to a different object supplied 2764as a parameter). 2765Out parameters (parameters the function is meant to write into, 2766either via pointers-to-pointers or references-to-pointers) 2767may be annotated with ``__attribute__((os_returns_retained))`` 2768or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2769written into the out parameter should (or respectively should not) be released 2770after use. 2771Since often out parameters may or may not be written depending on the exit 2772code of the function, 2773annotations ``__attribute__((os_returns_retained_on_zero))`` 2774and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2775an out parameter at ``+1`` is written if and only if the function returns a zero 2776(respectively non-zero) error code. 2777Observe that return-code-dependent out parameter annotations are only 2778available for retained out parameters, as non-retained object do not have to be 2779released by the callee. 2780These attributes are only used by the Clang Static Analyzer. 2781 2782The family of attributes ``X_returns_X_retained`` can be added to functions, 2783C++ methods, and Objective-C methods and properties. 2784Attributes ``X_consumed`` can be added to parameters of methods, functions, 2785and Objective-C methods. 2786 2787 2788os_returns_retained_on_zero 2789--------------------------- 2790.. csv-table:: Supported Syntaxes 2791 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2792 2793 "``os_returns_retained_on_zero``","``clang::os_returns_retained_on_zero``","``clang::os_returns_retained_on_zero``","","","","Yes" 2794 2795The behavior of a function with respect to reference counting for Foundation 2796(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming 2797convention (e.g. functions starting with "get" are assumed to return at 2798``+0``). 2799 2800It can be overriden using a family of the following attributes. In 2801Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to 2802a function communicates that the object is returned at ``+1``, and the caller 2803is responsible for freeing it. 2804Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` 2805specifies that the object is returned at ``+0`` and the ownership remains with 2806the callee. 2807The annotation ``__attribute__((ns_consumes_self))`` specifies that 2808the Objective-C method call consumes the reference to ``self``, e.g. by 2809attaching it to a supplied parameter. 2810Additionally, parameters can have an annotation 2811``__attribute__((ns_consumed))``, which specifies that passing an owned object 2812as that parameter effectively transfers the ownership, and the caller is no 2813longer responsible for it. 2814These attributes affect code generation when interacting with ARC code, and 2815they are used by the Clang Static Analyzer. 2816 2817In C programs using CoreFoundation, a similar set of attributes: 2818``__attribute__((cf_returns_not_retained))``, 2819``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))`` 2820have the same respective semantics when applied to CoreFoundation objects. 2821These attributes affect code generation when interacting with ARC code, and 2822they are used by the Clang Static Analyzer. 2823 2824Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject), 2825the same attribute family is present: 2826``__attribute__((os_returns_not_retained))``, 2827``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``, 2828with the same respective semantics. 2829Similar to ``__attribute__((ns_consumes_self))``, 2830``__attribute__((os_consumes_this))`` specifies that the method call consumes 2831the reference to "this" (e.g., when attaching it to a different object supplied 2832as a parameter). 2833Out parameters (parameters the function is meant to write into, 2834either via pointers-to-pointers or references-to-pointers) 2835may be annotated with ``__attribute__((os_returns_retained))`` 2836or ``__attribute__((os_returns_not_retained))`` which specifies that the object 2837written into the out parameter should (or respectively should not) be released 2838after use. 2839Since often out parameters may or may not be written depending on the exit 2840code of the function, 2841annotations ``__attribute__((os_returns_retained_on_zero))`` 2842and ``__attribute__((os_returns_retained_on_non_zero))`` specify that 2843an out parameter at ``+1`` is written if and only if the function returns a zero 2844(respectively non-zero) error code. 2845Observe that return-code-dependent out parameter annotations are only 2846available for retained out parameters, as non-retained object do not have to be 2847released by the callee. 2848These attributes are only used by the Clang Static Analyzer. 2849 2850The family of attributes ``X_returns_X_retained`` can be added to functions, 2851C++ methods, and Objective-C methods and properties. 2852Attributes ``X_consumed`` can be added to parameters of methods, functions, 2853and Objective-C methods. 2854 2855 2856overloadable 2857------------ 2858.. csv-table:: Supported Syntaxes 2859 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2860 2861 "``overloadable``","``clang::overloadable``","``clang::overloadable``","","","","Yes" 2862 2863Clang provides support for C++ function overloading in C. Function overloading 2864in C is introduced using the ``overloadable`` attribute. For example, one 2865might provide several overloaded versions of a ``tgsin`` function that invokes 2866the appropriate standard function computing the sine of a value with ``float``, 2867``double``, or ``long double`` precision: 2868 2869.. code-block:: c 2870 2871 #include <math.h> 2872 float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } 2873 double __attribute__((overloadable)) tgsin(double x) { return sin(x); } 2874 long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } 2875 2876Given these declarations, one can call ``tgsin`` with a ``float`` value to 2877receive a ``float`` result, with a ``double`` to receive a ``double`` result, 2878etc. Function overloading in C follows the rules of C++ function overloading 2879to pick the best overload given the call arguments, with a few C-specific 2880semantics: 2881 2882* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a 2883 floating-point promotion (per C99) rather than as a floating-point conversion 2884 (as in C++). 2885 2886* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is 2887 considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are 2888 compatible types. 2889 2890* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` 2891 and ``U`` are compatible types. This conversion is given "conversion" rank. 2892 2893* If no viable candidates are otherwise available, we allow a conversion from a 2894 pointer of type ``T*`` to a pointer of type ``U*``, where ``T`` and ``U`` are 2895 incompatible. This conversion is ranked below all other types of conversions. 2896 Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient 2897 for ``T`` and ``U`` to be incompatible. 2898 2899The declaration of ``overloadable`` functions is restricted to function 2900declarations and definitions. If a function is marked with the ``overloadable`` 2901attribute, then all declarations and definitions of functions with that name, 2902except for at most one (see the note below about unmarked overloads), must have 2903the ``overloadable`` attribute. In addition, redeclarations of a function with 2904the ``overloadable`` attribute must have the ``overloadable`` attribute, and 2905redeclarations of a function without the ``overloadable`` attribute must *not* 2906have the ``overloadable`` attribute. e.g., 2907 2908.. code-block:: c 2909 2910 int f(int) __attribute__((overloadable)); 2911 float f(float); // error: declaration of "f" must have the "overloadable" attribute 2912 int f(int); // error: redeclaration of "f" must have the "overloadable" attribute 2913 2914 int g(int) __attribute__((overloadable)); 2915 int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute 2916 2917 int h(int); 2918 int h(int) __attribute__((overloadable)); // error: declaration of "h" must not 2919 // have the "overloadable" attribute 2920 2921Functions marked ``overloadable`` must have prototypes. Therefore, the 2922following code is ill-formed: 2923 2924.. code-block:: c 2925 2926 int h() __attribute__((overloadable)); // error: h does not have a prototype 2927 2928However, ``overloadable`` functions are allowed to use a ellipsis even if there 2929are no named parameters (as is permitted in C++). This feature is particularly 2930useful when combined with the ``unavailable`` attribute: 2931 2932.. code-block:: c++ 2933 2934 void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error 2935 2936Functions declared with the ``overloadable`` attribute have their names mangled 2937according to the same rules as C++ function names. For example, the three 2938``tgsin`` functions in our motivating example get the mangled names 2939``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two 2940caveats to this use of name mangling: 2941 2942* Future versions of Clang may change the name mangling of functions overloaded 2943 in C, so you should not depend on an specific mangling. To be completely 2944 safe, we strongly urge the use of ``static inline`` with ``overloadable`` 2945 functions. 2946 2947* The ``overloadable`` attribute has almost no meaning when used in C++, 2948 because names will already be mangled and functions are already overloadable. 2949 However, when an ``overloadable`` function occurs within an ``extern "C"`` 2950 linkage specification, it's name *will* be mangled in the same way as it 2951 would in C. 2952 2953For the purpose of backwards compatibility, at most one function with the same 2954name as other ``overloadable`` functions may omit the ``overloadable`` 2955attribute. In this case, the function without the ``overloadable`` attribute 2956will not have its name mangled. 2957 2958For example: 2959 2960.. code-block:: c 2961 2962 // Notes with mangled names assume Itanium mangling. 2963 int f(int); 2964 int f(double) __attribute__((overloadable)); 2965 void foo() { 2966 f(5); // Emits a call to f (not _Z1fi, as it would with an overload that 2967 // was marked with overloadable). 2968 f(1.0); // Emits a call to _Z1fd. 2969 } 2970 2971Support for unmarked overloads is not present in some versions of clang. You may 2972query for it using ``__has_extension(overloadable_unmarked)``. 2973 2974Query for this attribute with ``__has_attribute(overloadable)``. 2975 2976 2977reinitializes 2978------------- 2979.. csv-table:: Supported Syntaxes 2980 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 2981 2982 "``reinitializes``","``clang::reinitializes``","","","","","" 2983 2984The ``reinitializes`` attribute can be applied to a non-static, non-const C++ 2985member function to indicate that this member function reinitializes the entire 2986object to a known state, independent of the previous state of the object. 2987 2988This attribute can be interpreted by static analyzers that warn about uses of an 2989object that has been left in an indeterminate state by a move operation. If a 2990member function marked with the ``reinitializes`` attribute is called on a 2991moved-from object, the analyzer can conclude that the object is no longer in an 2992indeterminate state. 2993 2994A typical example where this attribute would be used is on functions that clear 2995a container class: 2996 2997.. code-block:: c++ 2998 2999 template <class T> 3000 class Container { 3001 public: 3002 ... 3003 [[clang::reinitializes]] void Clear(); 3004 ... 3005 }; 3006 3007 3008release_capability, release_shared_capability 3009--------------------------------------------- 3010.. csv-table:: Supported Syntaxes 3011 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3012 3013 "``release_capability`` |br| ``release_shared_capability`` |br| ``release_generic_capability`` |br| ``unlock_function``","``clang::release_capability`` |br| ``clang::release_shared_capability`` |br| ``clang::release_generic_capability`` |br| ``clang::unlock_function``","","","","","" 3014 3015Marks a function as releasing a capability. 3016 3017 3018short_call, near 3019---------------- 3020.. csv-table:: Supported Syntaxes 3021 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3022 3023 "``short_call`` |br| ``near``","``gnu::short_call`` |br| ``gnu::near``","","","","","Yes" 3024 3025Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``, 3026``__attribute__((short__call))``, and ``__attribute__((near))`` attributes 3027on MIPS targets. These attributes may only be added to function declarations 3028and change the code generated by the compiler when directly calling 3029the function. The ``short_call`` and ``near`` attributes are synonyms and 3030allow calls to the function to be made using the ``jal`` instruction, which 3031requires the function to be located in the same naturally aligned 256MB segment 3032as the caller. The ``long_call`` and ``far`` attributes are synonyms and 3033require the use of a different call sequence that works regardless 3034of the distance between the functions. 3035 3036These attributes have no effect for position-independent code. 3037 3038These attributes take priority over command line switches such 3039as ``-mlong-calls`` and ``-mno-long-calls``. 3040 3041 3042signal 3043------ 3044.. csv-table:: Supported Syntaxes 3045 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3046 3047 "``signal``","``gnu::signal``","","","","","Yes" 3048 3049Clang supports the GNU style ``__attribute__((signal))`` attribute on 3050AVR targets. This attribute may be attached to a function definition and instructs 3051the backend to generate appropriate function entry/exit code so that it can be used 3052directly as an interrupt service routine. 3053 3054Interrupt handler functions defined with the signal attribute do not re-enable interrupts. 3055 3056 3057speculative_load_hardening 3058-------------------------- 3059.. csv-table:: Supported Syntaxes 3060 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3061 3062 "``speculative_load_hardening``","``clang::speculative_load_hardening``","``clang::speculative_load_hardening``","","","","Yes" 3063 3064This attribute can be applied to a function declaration in order to indicate 3065 that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_ 3066 should be enabled for the function body. This can also be applied to a method 3067 in Objective C. 3068 3069 Speculative Load Hardening is a best-effort mitigation against 3070 information leak attacks that make use of control flow 3071 miss-speculation - specifically miss-speculation of whether a branch 3072 is taken or not. Typically vulnerabilities enabling such attacks are 3073 classified as "Spectre variant #1". Notably, this does not attempt to 3074 mitigate against miss-speculation of branch target, classified as 3075 "Spectre variant #2" vulnerabilities. 3076 3077 When inlining, the attribute is sticky. Inlining a function that 3078 carries this attribute will cause the caller to gain the 3079 attribute. This is intended to provide a maximally conservative model 3080 where the code in a function annotated with this attribute will always 3081 (even after inlining) end up hardened. 3082 3083 3084target 3085------ 3086.. csv-table:: Supported Syntaxes 3087 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3088 3089 "``target``","``gnu::target``","","","","","Yes" 3090 3091Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute. 3092This attribute may be attached to a function definition and instructs 3093the backend to use different code generation options than were passed on the 3094command line. 3095 3096The current set of options correspond to the existing "subtarget features" for 3097the target with or without a "-mno-" in front corresponding to the absence 3098of the feature, as well as ``arch="CPU"`` which will change the default "CPU" 3099for the function. 3100 3101Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2", 3102"avx", "xop" and largely correspond to the machine specific options handled by 3103the front end. 3104 3105Additionally, this attribute supports function multiversioning for ELF based 3106x86/x86-64 targets, which can be used to create multiple implementations of the 3107same function that will be resolved at runtime based on the priority of their 3108``target`` attribute strings. A function is considered a multiversioned function 3109if either two declarations of the function have different ``target`` attribute 3110strings, or if it has a ``target`` attribute string of ``default``. For 3111example: 3112 3113 .. code-block:: c++ 3114 3115 __attribute__((target("arch=atom"))) 3116 void foo() {} // will be called on 'atom' processors. 3117 __attribute__((target("default"))) 3118 void foo() {} // will be called on any other processors. 3119 3120All multiversioned functions must contain a ``default`` (fallback) 3121implementation, otherwise usages of the function are considered invalid. 3122Additionally, a function may not become multiversioned after its first use. 3123 3124 3125try_acquire_capability, try_acquire_shared_capability 3126----------------------------------------------------- 3127.. csv-table:: Supported Syntaxes 3128 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3129 3130 "``try_acquire_capability`` |br| ``try_acquire_shared_capability``","``clang::try_acquire_capability`` |br| ``clang::try_acquire_shared_capability``","","","","","" 3131 3132Marks a function that attempts to acquire a capability. This function may fail to 3133actually acquire the capability; they accept a Boolean value determining 3134whether acquiring the capability means success (true), or failing to acquire 3135the capability means success (false). 3136 3137 3138xray_always_instrument, xray_never_instrument, xray_log_args 3139------------------------------------------------------------ 3140.. csv-table:: Supported Syntaxes 3141 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3142 3143 "``xray_always_instrument`` |br| ``xray_never_instrument``","``clang::xray_always_instrument`` |br| ``clang::xray_never_instrument``","``clang::xray_always_instrument`` |br| ``clang::xray_never_instrument``","","","","Yes" 3144 3145``__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. 3146 3147Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points. 3148 3149If 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. 3150 3151``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function. Currently, only N==1 is supported. 3152 3153 3154xray_always_instrument, xray_never_instrument, xray_log_args 3155------------------------------------------------------------ 3156.. csv-table:: Supported Syntaxes 3157 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3158 3159 "``xray_log_args``","``clang::xray_log_args``","``clang::xray_log_args``","","","","Yes" 3160 3161``__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. 3162 3163Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points. 3164 3165If 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. 3166 3167``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function. Currently, only N==1 is supported. 3168 3169 3170Variable Attributes 3171=================== 3172 3173 3174always_destroy 3175-------------- 3176.. csv-table:: Supported Syntaxes 3177 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3178 3179 "``always_destroy``","``clang::always_destroy``","","","","","Yes" 3180 3181The ``always_destroy`` attribute specifies that a variable with static or thread 3182storage duration should have its exit-time destructor run. This attribute is the 3183default unless clang was invoked with -fno-c++-static-destructors. 3184 3185 3186dllexport 3187--------- 3188.. csv-table:: Supported Syntaxes 3189 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3190 3191 "``dllexport``","``gnu::dllexport``","","``dllexport``","","","Yes" 3192 3193The ``__declspec(dllexport)`` attribute declares a variable, function, or 3194Objective-C interface to be exported from the module. It is available under the 3195``-fdeclspec`` flag for compatibility with various compilers. The primary use 3196is for COFF object files which explicitly specify what interfaces are available 3197for external use. See the dllexport_ documentation on MSDN for more 3198information. 3199 3200.. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx 3201 3202 3203dllimport 3204--------- 3205.. csv-table:: Supported Syntaxes 3206 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3207 3208 "``dllimport``","``gnu::dllimport``","","``dllimport``","","","Yes" 3209 3210The ``__declspec(dllimport)`` attribute declares a variable, function, or 3211Objective-C interface to be imported from an external module. It is available 3212under the ``-fdeclspec`` flag for compatibility with various compilers. The 3213primary use is for COFF object files which explicitly specify what interfaces 3214are imported from external modules. See the dllimport_ documentation on MSDN 3215for more information. 3216 3217.. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx 3218 3219 3220init_seg 3221-------- 3222.. csv-table:: Supported Syntaxes 3223 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3224 3225 "","","","","","``init_seg``","" 3226 3227The attribute applied by ``pragma init_seg()`` controls the section into 3228which global initialization function pointers are emitted. It is only 3229available with ``-fms-extensions``. Typically, this function pointer is 3230emitted into ``.CRT$XCU`` on Windows. The user can change the order of 3231initialization by using a different section name with the same 3232``.CRT$XC`` prefix and a suffix that sorts lexicographically before or 3233after the standard ``.CRT$XCU`` sections. See the init_seg_ 3234documentation on MSDN for more information. 3235 3236.. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx 3237 3238 3239maybe_unused, unused 3240-------------------- 3241.. csv-table:: Supported Syntaxes 3242 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3243 3244 "``unused``","``maybe_unused`` |br| ``gnu::unused``","``maybe_unused``","","","","" 3245 3246When passing the ``-Wunused`` flag to Clang, entities that are unused by the 3247program may be diagnosed. The ``[[maybe_unused]]`` (or 3248``__attribute__((unused))``) attribute can be used to silence such diagnostics 3249when the entity cannot be removed. For instance, a local variable may exist 3250solely for use in an ``assert()`` statement, which makes the local variable 3251unused when ``NDEBUG`` is defined. 3252 3253The attribute may be applied to the declaration of a class, a typedef, a 3254variable, a function or method, a function parameter, an enumeration, an 3255enumerator, a non-static data member, or a label. 3256 3257.. code-block: c++ 3258 #include <cassert> 3259 3260 [[maybe_unused]] void f([[maybe_unused]] bool thing1, 3261 [[maybe_unused]] bool thing2) { 3262 [[maybe_unused]] bool b = thing1 && thing2; 3263 assert(b); 3264 } 3265 3266 3267no_destroy 3268---------- 3269.. csv-table:: Supported Syntaxes 3270 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3271 3272 "``no_destroy``","``clang::no_destroy``","","","","","Yes" 3273 3274The ``no_destroy`` attribute specifies that a variable with static or thread 3275storage duration shouldn't have its exit-time destructor run. Annotating every 3276static and thread duration variable with this attribute is equivalent to 3277invoking clang with -fno-c++-static-destructors. 3278 3279 3280nodebug 3281------- 3282.. csv-table:: Supported Syntaxes 3283 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3284 3285 "``nodebug``","``gnu::nodebug``","","","","","Yes" 3286 3287The ``nodebug`` attribute allows you to suppress debugging information for a 3288function or method, or for a variable that is not a parameter or a non-static 3289data member. 3290 3291 3292noescape 3293-------- 3294.. csv-table:: Supported Syntaxes 3295 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3296 3297 "``noescape``","``clang::noescape``","``clang::noescape``","","","","Yes" 3298 3299``noescape`` placed on a function parameter of a pointer type is used to inform 3300the compiler that the pointer cannot escape: that is, no reference to the object 3301the pointer points to that is derived from the parameter value will survive 3302after the function returns. Users are responsible for making sure parameters 3303annotated with ``noescape`` do not actuallly escape. 3304 3305For example: 3306 3307.. code-block:: c 3308 3309 int *gp; 3310 3311 void nonescapingFunc(__attribute__((noescape)) int *p) { 3312 *p += 100; // OK. 3313 } 3314 3315 void escapingFunc(__attribute__((noescape)) int *p) { 3316 gp = p; // Not OK. 3317 } 3318 3319Additionally, when the parameter is a `block pointer 3320<https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction 3321applies to copies of the block. For example: 3322 3323.. code-block:: c 3324 3325 typedef void (^BlockTy)(); 3326 BlockTy g0, g1; 3327 3328 void nonescapingFunc(__attribute__((noescape)) BlockTy block) { 3329 block(); // OK. 3330 } 3331 3332 void escapingFunc(__attribute__((noescape)) BlockTy block) { 3333 g0 = block; // Not OK. 3334 g1 = Block_copy(block); // Not OK either. 3335 } 3336 3337 3338nosvm 3339----- 3340.. csv-table:: Supported Syntaxes 3341 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3342 3343 "``nosvm``","","","","","","Yes" 3344 3345OpenCL 2.0 supports the optional ``__attribute__((nosvm))`` qualifier for 3346pointer variable. It informs the compiler that the pointer does not refer 3347to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details. 3348 3349Since it is not widely used and has been removed from OpenCL 2.1, it is ignored 3350by Clang. 3351 3352 3353objc_externally_retained 3354------------------------ 3355.. csv-table:: Supported Syntaxes 3356 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3357 3358 "``objc_externally_retained``","``clang::objc_externally_retained``","``clang::objc_externally_retained``","","","","Yes" 3359 3360The ``objc_externally_retained`` attribute can be applied to strong local 3361variables, functions, methods, or blocks to opt into 3362`externally-retained semantics 3363<https://clang.llvm.org/docs/AutomaticReferenceCounting.html#externally-retained-variables>`_. 3364 3365When applied to the definition of a function, method, or block, every parameter 3366of the function with implicit strong retainable object pointer type is 3367considered externally-retained, and becomes ``const``. By explicitly annotating 3368a parameter with ``__strong``, you can opt back into the default 3369non-externally-retained behaviour for that parameter. For instance, 3370``first_param`` is externally-retained below, but not ``second_param``: 3371 3372.. code-block:: objc 3373 3374 __attribute__((objc_externally_retained)) 3375 void f(NSArray *first_param, __strong NSArray *second_param) { 3376 // ... 3377 } 3378 3379Likewise, when applied to a strong local variable, that variable becomes 3380``const`` and is considered externally-retained. 3381 3382When compiled without ``-fobjc-arc``, this attribute is ignored. 3383 3384 3385pass_object_size 3386---------------- 3387.. csv-table:: Supported Syntaxes 3388 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3389 3390 "``pass_object_size``","``clang::pass_object_size``","``clang::pass_object_size``","","","","Yes" 3391 3392.. Note:: The mangling of functions with parameters that are annotated with 3393 ``pass_object_size`` is subject to change. You can get around this by 3394 using ``__asm__("foo")`` to explicitly name your functions, thus preserving 3395 your ABI; also, non-overloadable C functions with ``pass_object_size`` are 3396 not mangled. 3397 3398The ``pass_object_size(Type)`` attribute can be placed on function parameters to 3399instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite 3400of said function, and implicitly pass the result of this call in as an invisible 3401argument of type ``size_t`` directly after the parameter annotated with 3402``pass_object_size``. Clang will also replace any calls to 3403``__builtin_object_size(param, Type)`` in the function by said implicit 3404parameter. 3405 3406Example usage: 3407 3408.. code-block:: c 3409 3410 int bzero1(char *const p __attribute__((pass_object_size(0)))) 3411 __attribute__((noinline)) { 3412 int i = 0; 3413 for (/**/; i < (int)__builtin_object_size(p, 0); ++i) { 3414 p[i] = 0; 3415 } 3416 return i; 3417 } 3418 3419 int main() { 3420 char chars[100]; 3421 int n = bzero1(&chars[0]); 3422 assert(n == sizeof(chars)); 3423 return 0; 3424 } 3425 3426If successfully evaluating ``__builtin_object_size(param, Type)`` at the 3427callsite is not possible, then the "failed" value is passed in. So, using the 3428definition of ``bzero1`` from above, the following code would exit cleanly: 3429 3430.. code-block:: c 3431 3432 int main2(int argc, char *argv[]) { 3433 int n = bzero1(argv); 3434 assert(n == -1); 3435 return 0; 3436 } 3437 3438``pass_object_size`` plays a part in overload resolution. If two overload 3439candidates are otherwise equally good, then the overload with one or more 3440parameters with ``pass_object_size`` is preferred. This implies that the choice 3441between two identical overloads both with ``pass_object_size`` on one or more 3442parameters will always be ambiguous; for this reason, having two such overloads 3443is illegal. For example: 3444 3445.. code-block:: c++ 3446 3447 #define PS(N) __attribute__((pass_object_size(N))) 3448 // OK 3449 void Foo(char *a, char *b); // Overload A 3450 // OK -- overload A has no parameters with pass_object_size. 3451 void Foo(char *a PS(0), char *b PS(0)); // Overload B 3452 // Error -- Same signature (sans pass_object_size) as overload B, and both 3453 // overloads have one or more parameters with the pass_object_size attribute. 3454 void Foo(void *a PS(0), void *b); 3455 3456 // OK 3457 void Bar(void *a PS(0)); // Overload C 3458 // OK 3459 void Bar(char *c PS(1)); // Overload D 3460 3461 void main() { 3462 char known[10], *unknown; 3463 Foo(unknown, unknown); // Calls overload B 3464 Foo(known, unknown); // Calls overload B 3465 Foo(unknown, known); // Calls overload B 3466 Foo(known, known); // Calls overload B 3467 3468 Bar(known); // Calls overload D 3469 Bar(unknown); // Calls overload D 3470 } 3471 3472Currently, ``pass_object_size`` is a bit restricted in terms of its usage: 3473 3474* Only one use of ``pass_object_size`` is allowed per parameter. 3475 3476* It is an error to take the address of a function with ``pass_object_size`` on 3477 any of its parameters. If you wish to do this, you can create an overload 3478 without ``pass_object_size`` on any parameters. 3479 3480* It is an error to apply the ``pass_object_size`` attribute to parameters that 3481 are not pointers. Additionally, any parameter that ``pass_object_size`` is 3482 applied to must be marked ``const`` at its function's definition. 3483 3484 3485require_constant_initialization 3486------------------------------- 3487.. csv-table:: Supported Syntaxes 3488 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3489 3490 "``require_constant_initialization``","``clang::require_constant_initialization``","","","","","Yes" 3491 3492This attribute specifies that the variable to which it is attached is intended 3493to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_ 3494according to the rules of [basic.start.static]. The variable is required to 3495have static or thread storage duration. If the initialization of the variable 3496is not a constant initializer an error will be produced. This attribute may 3497only be used in C++. 3498 3499Note that in C++03 strict constant expression checking is not done. Instead 3500the attribute reports if Clang can emit the variable as a constant, even if it's 3501not technically a 'constant initializer'. This behavior is non-portable. 3502 3503Static storage duration variables with constant initializers avoid hard-to-find 3504bugs caused by the indeterminate order of dynamic initialization. They can also 3505be safely used during dynamic initialization across translation units. 3506 3507This attribute acts as a compile time assertion that the requirements 3508for constant initialization have been met. Since these requirements change 3509between dialects and have subtle pitfalls it's important to fail fast instead 3510of silently falling back on dynamic initialization. 3511 3512.. code-block:: c++ 3513 3514 // -std=c++14 3515 #define SAFE_STATIC [[clang::require_constant_initialization]] 3516 struct T { 3517 constexpr T(int) {} 3518 ~T(); // non-trivial 3519 }; 3520 SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor. 3521 SAFE_STATIC T y = 42; // error: variable does not have a constant initializer 3522 // copy initialization is not a constant expression on a non-literal type. 3523 3524 3525section, __declspec(allocate) 3526----------------------------- 3527.. csv-table:: Supported Syntaxes 3528 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3529 3530 "``section``","``gnu::section``","","``allocate``","","","Yes" 3531 3532The ``section`` attribute allows you to specify a specific section a 3533global variable or function should be in after translation. 3534 3535 3536swift_context 3537------------- 3538.. csv-table:: Supported Syntaxes 3539 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3540 3541 "``swift_context``","``clang::swift_context``","``clang::swift_context``","","","","Yes" 3542 3543The ``swift_context`` attribute marks a parameter of a ``swiftcall`` 3544function as having the special context-parameter ABI treatment. 3545 3546This treatment generally passes the context value in a special register 3547which is normally callee-preserved. 3548 3549A ``swift_context`` parameter must either be the last parameter or must be 3550followed by a ``swift_error_result`` parameter (which itself must always be 3551the last parameter). 3552 3553A context parameter must have pointer or reference type. 3554 3555 3556swift_error_result 3557------------------ 3558.. csv-table:: Supported Syntaxes 3559 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3560 3561 "``swift_error_result``","``clang::swift_error_result``","``clang::swift_error_result``","","","","Yes" 3562 3563The ``swift_error_result`` attribute marks a parameter of a ``swiftcall`` 3564function as having the special error-result ABI treatment. 3565 3566This treatment generally passes the underlying error value in and out of 3567the function through a special register which is normally callee-preserved. 3568This is modeled in C by pretending that the register is addressable memory: 3569 3570- The caller appears to pass the address of a variable of pointer type. 3571 The current value of this variable is copied into the register before 3572 the call; if the call returns normally, the value is copied back into the 3573 variable. 3574 3575- The callee appears to receive the address of a variable. This address 3576 is actually a hidden location in its own stack, initialized with the 3577 value of the register upon entry. When the function returns normally, 3578 the value in that hidden location is written back to the register. 3579 3580A ``swift_error_result`` parameter must be the last parameter, and it must be 3581preceded by a ``swift_context`` parameter. 3582 3583A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some 3584type T. Note that no qualifiers are permitted on the intermediate level. 3585 3586It is undefined behavior if the caller does not pass a pointer or 3587reference to a valid object. 3588 3589The standard convention is that the error value itself (that is, the 3590value stored in the apparent argument) will be null upon function entry, 3591but this is not enforced by the ABI. 3592 3593 3594swift_indirect_result 3595--------------------- 3596.. csv-table:: Supported Syntaxes 3597 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3598 3599 "``swift_indirect_result``","``clang::swift_indirect_result``","``clang::swift_indirect_result``","","","","Yes" 3600 3601The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall`` 3602function as having the special indirect-result ABI treatment. 3603 3604This treatment gives the parameter the target's normal indirect-result 3605ABI treatment, which may involve passing it differently from an ordinary 3606parameter. However, only the first indirect result will receive this 3607treatment. Furthermore, low-level lowering may decide that a direct result 3608must be returned indirectly; if so, this will take priority over the 3609``swift_indirect_result`` parameters. 3610 3611A ``swift_indirect_result`` parameter must either be the first parameter or 3612follow another ``swift_indirect_result`` parameter. 3613 3614A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for 3615some object type ``T``. If ``T`` is a complete type at the point of 3616definition of a function, it is undefined behavior if the argument 3617value does not point to storage of adequate size and alignment for a 3618value of type ``T``. 3619 3620Making indirect results explicit in the signature allows C functions to 3621directly construct objects into them without relying on language 3622optimizations like C++'s named return value optimization (NRVO). 3623 3624 3625swiftcall 3626--------- 3627.. csv-table:: Supported Syntaxes 3628 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3629 3630 "``swiftcall``","``clang::swiftcall``","``clang::swiftcall``","","","","" 3631 3632The ``swiftcall`` attribute indicates that a function should be called 3633using the Swift calling convention for a function or function pointer. 3634 3635The lowering for the Swift calling convention, as described by the Swift 3636ABI documentation, occurs in multiple phases. The first, "high-level" 3637phase breaks down the formal parameters and results into innately direct 3638and indirect components, adds implicit paraameters for the generic 3639signature, and assigns the context and error ABI treatments to parameters 3640where applicable. The second phase breaks down the direct parameters 3641and results from the first phase and assigns them to registers or the 3642stack. The ``swiftcall`` convention only handles this second phase of 3643lowering; the C function type must accurately reflect the results 3644of the first phase, as follows: 3645 3646- Results classified as indirect by high-level lowering should be 3647 represented as parameters with the ``swift_indirect_result`` attribute. 3648 3649- Results classified as direct by high-level lowering should be represented 3650 as follows: 3651 3652 - First, remove any empty direct results. 3653 3654 - If there are no direct results, the C result type should be ``void``. 3655 3656 - If there is one direct result, the C result type should be a type with 3657 the exact layout of that result type. 3658 3659 - If there are a multiple direct results, the C result type should be 3660 a struct type with the exact layout of a tuple of those results. 3661 3662- Parameters classified as indirect by high-level lowering should be 3663 represented as parameters of pointer type. 3664 3665- Parameters classified as direct by high-level lowering should be 3666 omitted if they are empty types; otherwise, they should be represented 3667 as a parameter type with a layout exactly matching the layout of the 3668 Swift parameter type. 3669 3670- The context parameter, if present, should be represented as a trailing 3671 parameter with the ``swift_context`` attribute. 3672 3673- The error result parameter, if present, should be represented as a 3674 trailing parameter (always following a context parameter) with the 3675 ``swift_error_result`` attribute. 3676 3677``swiftcall`` does not support variadic arguments or unprototyped functions. 3678 3679The parameter ABI treatment attributes are aspects of the function type. 3680A function type which which applies an ABI treatment attribute to a 3681parameter is a different type from an otherwise-identical function type 3682that does not. A single parameter may not have multiple ABI treatment 3683attributes. 3684 3685Support for this feature is target-dependent, although it should be 3686supported on every target that Swift supports. Query for this support 3687with ``__has_attribute(swiftcall)``. This implies support for the 3688``swift_context``, ``swift_error_result``, and ``swift_indirect_result`` 3689attributes. 3690 3691 3692thread 3693------ 3694.. csv-table:: Supported Syntaxes 3695 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3696 3697 "","","","``thread``","","","" 3698 3699The ``__declspec(thread)`` attribute declares a variable with thread local 3700storage. It is available under the ``-fms-extensions`` flag for MSVC 3701compatibility. See the documentation for `__declspec(thread)`_ on MSDN. 3702 3703.. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx 3704 3705In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the 3706GNU ``__thread`` keyword. The variable must not have a destructor and must have 3707a constant initializer, if any. The attribute only applies to variables 3708declared with static storage duration, such as globals, class static data 3709members, and static locals. 3710 3711 3712tls_model 3713--------- 3714.. csv-table:: Supported Syntaxes 3715 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3716 3717 "``tls_model``","``gnu::tls_model``","","","","","Yes" 3718 3719The ``tls_model`` attribute allows you to specify which thread-local storage 3720model to use. It accepts the following strings: 3721 3722* global-dynamic 3723* local-dynamic 3724* initial-exec 3725* local-exec 3726 3727TLS models are mutually exclusive. 3728 3729 3730trivial_abi 3731----------- 3732.. csv-table:: Supported Syntaxes 3733 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3734 3735 "``trivial_abi``","``clang::trivial_abi``","","","","","Yes" 3736 3737The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union. 3738It instructs the compiler to pass and return the type using the C ABI for the 3739underlying type when the type would otherwise be considered non-trivial for the 3740purpose of calls. 3741A class annotated with `trivial_abi` can have non-trivial destructors or copy/move constructors without automatically becoming non-trivial for the purposes of calls. For example: 3742 3743 .. code-block:: c++ 3744 3745 // A is trivial for the purposes of calls because `trivial_abi` makes the 3746 // user-provided special functions trivial. 3747 struct __attribute__((trivial_abi)) A { 3748 ~A(); 3749 A(const A &); 3750 A(A &&); 3751 int x; 3752 }; 3753 3754 // B's destructor and copy/move constructor are considered trivial for the 3755 // purpose of calls because A is trivial. 3756 struct B { 3757 A a; 3758 }; 3759 3760If a type is trivial for the purposes of calls, has a non-trivial destructor, 3761and is passed as an argument by value, the convention is that the callee will 3762destroy the object before returning. 3763 3764Attribute ``trivial_abi`` has no effect in the following cases: 3765 3766- The class directly declares a virtual base or virtual methods. 3767- The class has a base class that is non-trivial for the purposes of calls. 3768- The class has a non-static data member whose type is non-trivial for the purposes of calls, which includes: 3769 3770 - classes that are non-trivial for the purposes of calls 3771 - __weak-qualified types in Objective-C++ 3772 - arrays of any of the above 3773 3774 3775uninitialized 3776------------- 3777.. csv-table:: Supported Syntaxes 3778 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3779 3780 "``uninitialized``","``clang::uninitialized``","","","","","" 3781 3782The command-line parameter ``-ftrivial-auto-var-init=*`` can be used to 3783initialize trivial automatic stack variables. By default, trivial automatic 3784stack variables are uninitialized. This attribute is used to override the 3785command-line parameter, forcing variables to remain uninitialized. It has no 3786semantic meaning in that using uninitialized values is undefined behavior, 3787it rather documents the programmer's intent. 3788 3789 3790Type Attributes 3791=============== 3792 3793 3794__single_inhertiance, __multiple_inheritance, __virtual_inheritance 3795------------------------------------------------------------------- 3796.. csv-table:: Supported Syntaxes 3797 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3798 3799 "","","","","``__single_inheritance`` |br| ``__multiple_inheritance`` |br| ``__virtual_inheritance`` |br| ``__unspecified_inheritance``","","" 3800 3801This collection of keywords is enabled under ``-fms-extensions`` and controls 3802the pointer-to-member representation used on ``*-*-win32`` targets. 3803 3804The ``*-*-win32`` targets utilize a pointer-to-member representation which 3805varies in size and alignment depending on the definition of the underlying 3806class. 3807 3808However, this is problematic when a forward declaration is only available and 3809no definition has been made yet. In such cases, Clang is forced to utilize the 3810most general representation that is available to it. 3811 3812These keywords make it possible to use a pointer-to-member representation other 3813than the most general one regardless of whether or not the definition will ever 3814be present in the current translation unit. 3815 3816This family of keywords belong between the ``class-key`` and ``class-name``: 3817 3818.. code-block:: c++ 3819 3820 struct __single_inheritance S; 3821 int S::*i; 3822 struct S {}; 3823 3824This keyword can be applied to class templates but only has an effect when used 3825on full specializations: 3826 3827.. code-block:: c++ 3828 3829 template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template 3830 template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization 3831 template <> struct __single_inheritance A<int, float>; 3832 3833Note that choosing an inheritance model less general than strictly necessary is 3834an error: 3835 3836.. code-block:: c++ 3837 3838 struct __multiple_inheritance S; // error: inheritance model does not match definition 3839 int S::*i; 3840 struct S {}; 3841 3842 3843align_value 3844----------- 3845.. csv-table:: Supported Syntaxes 3846 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3847 3848 "``align_value``","","","","","","Yes" 3849 3850The align_value attribute can be added to the typedef of a pointer type or the 3851declaration of a variable of pointer or reference type. It specifies that the 3852pointer will point to, or the reference will bind to, only objects with at 3853least the provided alignment. This alignment value must be some positive power 3854of 2. 3855 3856 .. code-block:: c 3857 3858 typedef double * aligned_double_ptr __attribute__((align_value(64))); 3859 void foo(double & x __attribute__((align_value(128)), 3860 aligned_double_ptr y) { ... } 3861 3862If the pointer value does not have the specified alignment at runtime, the 3863behavior of the program is undefined. 3864 3865 3866empty_bases 3867----------- 3868.. csv-table:: Supported Syntaxes 3869 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3870 3871 "","","","``empty_bases``","","","" 3872 3873The empty_bases attribute permits the compiler to utilize the 3874empty-base-optimization more frequently. 3875This attribute only applies to struct, class, and union types. 3876It is only supported when using the Microsoft C++ ABI. 3877 3878 3879enum_extensibility 3880------------------ 3881.. csv-table:: Supported Syntaxes 3882 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3883 3884 "``enum_extensibility``","``clang::enum_extensibility``","``clang::enum_extensibility``","","","","Yes" 3885 3886Attribute ``enum_extensibility`` is used to distinguish between enum definitions 3887that are extensible and those that are not. The attribute can take either 3888``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the 3889enum type takes a value that corresponds to one of the enumerators listed in the 3890enum definition or, when the enum is annotated with ``flag_enum``, a value that 3891can be constructed using values corresponding to the enumerators. ``open`` 3892indicates a variable of the enum type can take any values allowed by the 3893standard and instructs clang to be more lenient when issuing warnings. 3894 3895.. code-block:: c 3896 3897 enum __attribute__((enum_extensibility(closed))) ClosedEnum { 3898 A0, A1 3899 }; 3900 3901 enum __attribute__((enum_extensibility(open))) OpenEnum { 3902 B0, B1 3903 }; 3904 3905 enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum { 3906 C0 = 1 << 0, C1 = 1 << 1 3907 }; 3908 3909 enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum { 3910 D0 = 1 << 0, D1 = 1 << 1 3911 }; 3912 3913 void foo1() { 3914 enum ClosedEnum ce; 3915 enum OpenEnum oe; 3916 enum ClosedFlagEnum cfe; 3917 enum OpenFlagEnum ofe; 3918 3919 ce = A1; // no warnings 3920 ce = 100; // warning issued 3921 oe = B1; // no warnings 3922 oe = 100; // no warnings 3923 cfe = C0 | C1; // no warnings 3924 cfe = C0 | C1 | 4; // warning issued 3925 ofe = D0 | D1; // no warnings 3926 ofe = D0 | D1 | 4; // no warnings 3927 } 3928 3929 3930flag_enum 3931--------- 3932.. csv-table:: Supported Syntaxes 3933 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3934 3935 "``flag_enum``","``clang::flag_enum``","``clang::flag_enum``","","","","Yes" 3936 3937This attribute can be added to an enumerator to signal to the compiler that it 3938is intended to be used as a flag type. This will cause the compiler to assume 3939that the range of the type includes all of the values that you can get by 3940manipulating bits of the enumerator when issuing warnings. 3941 3942 3943layout_version 3944-------------- 3945.. csv-table:: Supported Syntaxes 3946 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3947 3948 "","","","``layout_version``","","","" 3949 3950The layout_version attribute requests that the compiler utilize the class 3951layout rules of a particular compiler version. 3952This attribute only applies to struct, class, and union types. 3953It is only supported when using the Microsoft C++ ABI. 3954 3955 3956lto_visibility_public 3957--------------------- 3958.. csv-table:: Supported Syntaxes 3959 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3960 3961 "``lto_visibility_public``","``clang::lto_visibility_public``","``clang::lto_visibility_public``","","","","Yes" 3962 3963See :doc:`LTOVisibility`. 3964 3965 3966noderef 3967------- 3968.. csv-table:: Supported Syntaxes 3969 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 3970 3971 "``noderef``","``clang::noderef``","``clang::noderef``","","","","" 3972 3973The ``noderef`` attribute causes clang to diagnose dereferences of annotated pointer types. 3974This is ideally used with pointers that point to special memory which cannot be read 3975from or written to, but allowing for the pointer to be used in pointer arithmetic. 3976The following are examples of valid expressions where dereferences are diagnosed: 3977 3978.. code-block:: c 3979 3980 int __attribute__((noderef)) *p; 3981 int x = *p; // warning 3982 3983 int __attribute__((noderef)) **p2; 3984 x = **p2; // warning 3985 3986 int * __attribute__((noderef)) *p3; 3987 p = *p3; // warning 3988 3989 struct S { 3990 int a; 3991 }; 3992 struct S __attribute__((noderef)) *s; 3993 x = s->a; // warning 3994 x = (*s).a; // warning 3995 3996Not all dereferences may diagnose a warning if the value directed by the pointer may not be 3997accessed. The following are examples of valid expressions where may not be diagnosed: 3998 3999.. code-block:: c 4000 4001 int *q; 4002 int __attribute__((noderef)) *p; 4003 q = &*p; 4004 q = *&p; 4005 4006 struct S { 4007 int a; 4008 }; 4009 struct S __attribute__((noderef)) *s; 4010 p = &s->a; 4011 p = &(*s).a; 4012 4013``noderef`` is currently only supported for pointers and arrays and not usable for 4014references or Objective-C object pointers. 4015 4016.. code-block: c++ 4017 4018 int x = 2; 4019 int __attribute__((noderef)) &y = x; // warning: 'noderef' can only be used on an array or pointer type 4020 4021.. code-block: objc 4022 4023 id __attribute__((noderef)) obj = [NSObject new]; // warning: 'noderef' can only be used on an array or pointer type 4024 4025 4026novtable 4027-------- 4028.. csv-table:: Supported Syntaxes 4029 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4030 4031 "","","","``novtable``","","","" 4032 4033This attribute can be added to a class declaration or definition to signal to 4034the compiler that constructors and destructors will not reference the virtual 4035function table. It is only supported when using the Microsoft C++ ABI. 4036 4037 4038objc_subclassing_restricted 4039--------------------------- 4040.. csv-table:: Supported Syntaxes 4041 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4042 4043 "``objc_subclassing_restricted``","``clang::objc_subclassing_restricted``","``clang::objc_subclassing_restricted``","","","","Yes" 4044 4045This attribute can be added to an Objective-C ``@interface`` declaration to 4046ensure that this class cannot be subclassed. 4047 4048 4049selectany 4050--------- 4051.. csv-table:: Supported Syntaxes 4052 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4053 4054 "``selectany``","``gnu::selectany``","","``selectany``","","","" 4055 4056This attribute appertains to a global symbol, causing it to have a weak 4057definition ( 4058`linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_ 4059), allowing the linker to select any definition. 4060 4061For more information see 4062`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_ 4063or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_. 4064 4065 4066transparent_union 4067----------------- 4068.. csv-table:: Supported Syntaxes 4069 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4070 4071 "``transparent_union``","``gnu::transparent_union``","","","","","" 4072 4073This attribute can be applied to a union to change the behaviour of calls to 4074functions that have an argument with a transparent union type. The compiler 4075behaviour is changed in the following manner: 4076 4077- A value whose type is any member of the transparent union can be passed as an 4078 argument without the need to cast that value. 4079 4080- The argument is passed to the function using the calling convention of the 4081 first member of the transparent union. Consequently, all the members of the 4082 transparent union should have the same calling convention as its first member. 4083 4084Transparent unions are not supported in C++. 4085 4086 4087Statement Attributes 4088==================== 4089 4090 4091#pragma clang loop 4092------------------ 4093.. csv-table:: Supported Syntaxes 4094 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4095 4096 "","","","","","``clang loop`` |br| ``unroll`` |br| ``nounroll`` |br| ``unroll_and_jam`` |br| ``nounroll_and_jam``","" 4097 4098The ``#pragma clang loop`` directive allows loop optimization hints to be 4099specified for the subsequent loop. The directive allows pipelining to be 4100disabled, or vectorization, interleaving, and unrolling to be enabled or disabled. 4101Vector width, interleave count, unrolling count, and the initiation interval 4102for pipelining can be explicitly specified. See `language extensions 4103<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ 4104for details. 4105 4106 4107#pragma unroll, #pragma nounroll 4108-------------------------------- 4109.. csv-table:: Supported Syntaxes 4110 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4111 4112 "","","","","","``clang loop`` |br| ``unroll`` |br| ``nounroll`` |br| ``unroll_and_jam`` |br| ``nounroll_and_jam``","" 4113 4114Loop unrolling optimization hints can be specified with ``#pragma unroll`` and 4115``#pragma nounroll``. The pragma is placed immediately before a for, while, 4116do-while, or c++11 range-based for loop. 4117 4118Specifying ``#pragma unroll`` without a parameter directs the loop unroller to 4119attempt to fully unroll the loop if the trip count is known at compile time and 4120attempt to partially unroll the loop if the trip count is not known at compile 4121time: 4122 4123.. code-block:: c++ 4124 4125 #pragma unroll 4126 for (...) { 4127 ... 4128 } 4129 4130Specifying the optional parameter, ``#pragma unroll _value_``, directs the 4131unroller to unroll the loop ``_value_`` times. The parameter may optionally be 4132enclosed in parentheses: 4133 4134.. code-block:: c++ 4135 4136 #pragma unroll 16 4137 for (...) { 4138 ... 4139 } 4140 4141 #pragma unroll(16) 4142 for (...) { 4143 ... 4144 } 4145 4146Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled: 4147 4148.. code-block:: c++ 4149 4150 #pragma nounroll 4151 for (...) { 4152 ... 4153 } 4154 4155``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to 4156``#pragma clang loop unroll(full)`` and 4157``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll`` 4158is equivalent to ``#pragma clang loop unroll(disable)``. See 4159`language extensions 4160<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ 4161for further details including limitations of the unroll hints. 4162 4163 4164__read_only, __write_only, __read_write (read_only, write_only, read_write) 4165--------------------------------------------------------------------------- 4166.. csv-table:: Supported Syntaxes 4167 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4168 4169 "","","","","``__read_only`` |br| ``read_only`` |br| ``__write_only`` |br| ``write_only`` |br| ``__read_write`` |br| ``read_write``","","" 4170 4171The access qualifiers must be used with image object arguments or pipe arguments 4172to declare if they are being read or written by a kernel or function. 4173 4174The read_only/__read_only, write_only/__write_only and read_write/__read_write 4175names are reserved for use as access qualifiers and shall not be used otherwise. 4176 4177.. code-block:: c 4178 4179 kernel void 4180 foo (read_only image2d_t imageA, 4181 write_only image2d_t imageB) { 4182 ... 4183 } 4184 4185In the above example imageA is a read-only 2D image object, and imageB is a 4186write-only 2D image object. 4187 4188The read_write (or __read_write) qualifier can not be used with pipe. 4189 4190More details can be found in the OpenCL C language Spec v2.0, Section 6.6. 4191 4192 4193fallthrough 4194----------- 4195.. csv-table:: Supported Syntaxes 4196 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4197 4198 "","``fallthrough`` |br| ``clang::fallthrough``","``fallthrough``","","","","" 4199 4200The ``fallthrough`` (or ``clang::fallthrough``) attribute is used 4201to annotate intentional fall-through 4202between switch labels. It can only be applied to a null statement placed at a 4203point of execution between any statement and the next switch label. It is 4204common to mark these places with a specific comment, but this attribute is 4205meant to replace comments with a more strict annotation, which can be checked 4206by the compiler. This attribute doesn't change semantics of the code and can 4207be used wherever an intended fall-through occurs. It is designed to mimic 4208control-flow statements like ``break;``, so it can be placed in most places 4209where ``break;`` can, but only if there are no statements on the execution path 4210between it and the next switch label. 4211 4212By default, Clang does not warn on unannotated fallthrough from one ``switch`` 4213case to another. Diagnostics on fallthrough without a corresponding annotation 4214can be enabled with the ``-Wimplicit-fallthrough`` argument. 4215 4216Here is an example: 4217 4218.. code-block:: c++ 4219 4220 // compile with -Wimplicit-fallthrough 4221 switch (n) { 4222 case 22: 4223 case 33: // no warning: no statements between case labels 4224 f(); 4225 case 44: // warning: unannotated fall-through 4226 g(); 4227 [[clang::fallthrough]]; 4228 case 55: // no warning 4229 if (x) { 4230 h(); 4231 break; 4232 } 4233 else { 4234 i(); 4235 [[clang::fallthrough]]; 4236 } 4237 case 66: // no warning 4238 p(); 4239 [[clang::fallthrough]]; // warning: fallthrough annotation does not 4240 // directly precede case label 4241 q(); 4242 case 77: // warning: unannotated fall-through 4243 r(); 4244 } 4245 4246 4247intel_reqd_sub_group_size 4248------------------------- 4249.. csv-table:: Supported Syntaxes 4250 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4251 4252 "``intel_reqd_sub_group_size``","","","","","","Yes" 4253 4254The optional attribute intel_reqd_sub_group_size can be used to indicate that 4255the kernel must be compiled and executed with the specified subgroup size. When 4256this attribute is present, get_max_sub_group_size() is guaranteed to return the 4257specified integer value. This is important for the correctness of many subgroup 4258algorithms, and in some cases may be used by the compiler to generate more optimal 4259code. See `cl_intel_required_subgroup_size 4260<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>` 4261for details. 4262 4263 4264opencl_unroll_hint 4265------------------ 4266.. csv-table:: Supported Syntaxes 4267 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4268 4269 "``opencl_unroll_hint``","","","","","","" 4270 4271The opencl_unroll_hint attribute qualifier can be used to specify that a loop 4272(for, while and do loops) can be unrolled. This attribute qualifier can be 4273used to specify full unrolling or partial unrolling by a specified amount. 4274This is a compiler hint and the compiler may ignore this directive. See 4275`OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_ 4276s6.11.5 for details. 4277 4278 4279suppress 4280-------- 4281.. csv-table:: Supported Syntaxes 4282 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4283 4284 "","``gsl::suppress``","","","","","" 4285 4286The ``[[gsl::suppress]]`` attribute suppresses specific 4287clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable 4288way. The attribute can be attached to declarations, statements, and at 4289namespace scope. 4290 4291.. code-block:: c++ 4292 4293 [[gsl::suppress("Rh-public")]] 4294 void f_() { 4295 int *p; 4296 [[gsl::suppress("type")]] { 4297 p = reinterpret_cast<int*>(7); 4298 } 4299 } 4300 namespace N { 4301 [[clang::suppress("type", "bounds")]]; 4302 ... 4303 } 4304 4305.. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement 4306 4307 4308AMD GPU Attributes 4309================== 4310 4311 4312amdgpu_flat_work_group_size 4313--------------------------- 4314.. csv-table:: Supported Syntaxes 4315 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4316 4317 "``amdgpu_flat_work_group_size``","``clang::amdgpu_flat_work_group_size``","","","","","Yes" 4318 4319The flat work-group size is the number of work-items in the work-group size 4320specified when the kernel is dispatched. It is the product of the sizes of the 4321x, y, and z dimension of the work-group. 4322 4323Clang supports the 4324``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the 4325AMDGPU target. This attribute may be attached to a kernel function definition 4326and is an optimization hint. 4327 4328``<min>`` parameter specifies the minimum flat work-group size, and ``<max>`` 4329parameter specifies the maximum flat work-group size (must be greater than 4330``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0`` 4331as ``<min>, <max>`` implies the default behavior (``128, 256``). 4332 4333If specified, the AMDGPU target backend might be able to produce better machine 4334code for barriers and perform scratch promotion by estimating available group 4335segment size. 4336 4337An error will be given if: 4338 - Specified values violate subtarget specifications; 4339 - Specified values are not compatible with values provided through other 4340 attributes. 4341 4342 4343amdgpu_num_sgpr 4344--------------- 4345.. csv-table:: Supported Syntaxes 4346 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4347 4348 "``amdgpu_num_sgpr``","``clang::amdgpu_num_sgpr``","","","","","Yes" 4349 4350Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and 4351``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU 4352target. These attributes may be attached to a kernel function definition and are 4353an optimization hint. 4354 4355If these attributes are specified, then the AMDGPU target backend will attempt 4356to limit the number of SGPRs and/or VGPRs used to the specified value(s). The 4357number of used SGPRs and/or VGPRs may further be rounded up to satisfy the 4358allocation requirements or constraints of the subtarget. Passing ``0`` as 4359``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits). 4360 4361These attributes can be used to test the AMDGPU target backend. It is 4362recommended that the ``amdgpu_waves_per_eu`` attribute be used to control 4363resources such as SGPRs and VGPRs since it is aware of the limits for different 4364subtargets. 4365 4366An error will be given if: 4367 - Specified values violate subtarget specifications; 4368 - Specified values are not compatible with values provided through other 4369 attributes; 4370 - The AMDGPU target backend is unable to create machine code that can meet the 4371 request. 4372 4373 4374amdgpu_num_vgpr 4375--------------- 4376.. csv-table:: Supported Syntaxes 4377 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4378 4379 "``amdgpu_num_vgpr``","``clang::amdgpu_num_vgpr``","","","","","Yes" 4380 4381Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and 4382``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU 4383target. These attributes may be attached to a kernel function definition and are 4384an optimization hint. 4385 4386If these attributes are specified, then the AMDGPU target backend will attempt 4387to limit the number of SGPRs and/or VGPRs used to the specified value(s). The 4388number of used SGPRs and/or VGPRs may further be rounded up to satisfy the 4389allocation requirements or constraints of the subtarget. Passing ``0`` as 4390``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits). 4391 4392These attributes can be used to test the AMDGPU target backend. It is 4393recommended that the ``amdgpu_waves_per_eu`` attribute be used to control 4394resources such as SGPRs and VGPRs since it is aware of the limits for different 4395subtargets. 4396 4397An error will be given if: 4398 - Specified values violate subtarget specifications; 4399 - Specified values are not compatible with values provided through other 4400 attributes; 4401 - The AMDGPU target backend is unable to create machine code that can meet the 4402 request. 4403 4404 4405amdgpu_waves_per_eu 4406------------------- 4407.. csv-table:: Supported Syntaxes 4408 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4409 4410 "``amdgpu_waves_per_eu``","``clang::amdgpu_waves_per_eu``","","","","","Yes" 4411 4412A compute unit (CU) is responsible for executing the wavefronts of a work-group. 4413It is composed of one or more execution units (EU), which are responsible for 4414executing the wavefronts. An EU can have enough resources to maintain the state 4415of more than one executing wavefront. This allows an EU to hide latency by 4416switching between wavefronts in a similar way to symmetric multithreading on a 4417CPU. In order to allow the state for multiple wavefronts to fit on an EU, the 4418resources used by a single wavefront have to be limited. For example, the number 4419of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding, 4420but can result in having to spill some register state to memory. 4421 4422Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))`` 4423attribute for the AMDGPU target. This attribute may be attached to a kernel 4424function definition and is an optimization hint. 4425 4426``<min>`` parameter specifies the requested minimum number of waves per EU, and 4427*optional* ``<max>`` parameter specifies the requested maximum number of waves 4428per EU (must be greater than ``<min>`` if specified). If ``<max>`` is omitted, 4429then there is no restriction on the maximum number of waves per EU other than 4430the one dictated by the hardware for which the kernel is compiled. Passing 4431``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits). 4432 4433If specified, this attribute allows an advanced developer to tune the number of 4434wavefronts that are capable of fitting within the resources of an EU. The AMDGPU 4435target backend can use this information to limit resources, such as number of 4436SGPRs, number of VGPRs, size of available group and private memory segments, in 4437such a way that guarantees that at least ``<min>`` wavefronts and at most 4438``<max>`` wavefronts are able to fit within the resources of an EU. Requesting 4439more wavefronts can hide memory latency but limits available registers which 4440can result in spilling. Requesting fewer wavefronts can help reduce cache 4441thrashing, but can reduce memory latency hiding. 4442 4443This attribute controls the machine code generated by the AMDGPU target backend 4444to ensure it is capable of meeting the requested values. However, when the 4445kernel is executed, there may be other reasons that prevent meeting the request, 4446for example, there may be wavefronts from other kernels executing on the EU. 4447 4448An error will be given if: 4449 - Specified values violate subtarget specifications; 4450 - Specified values are not compatible with values provided through other 4451 attributes; 4452 - The AMDGPU target backend is unable to create machine code that can meet the 4453 request. 4454 4455 4456OpenCL Address Spaces 4457===================== 4458The address space qualifier may be used to specify the region of memory that is 4459used to allocate the object. OpenCL supports the following address spaces: 4460__generic(generic), __global(global), __local(local), __private(private), 4461__constant(constant). 4462 4463 .. code-block:: c 4464 4465 __constant int c = ...; 4466 4467 __generic int* foo(global int* g) { 4468 __local int* l; 4469 private int p; 4470 ... 4471 return l; 4472 } 4473 4474More details can be found in the OpenCL C language Spec v2.0, Section 6.5. 4475 4476constant 4477-------- 4478.. csv-table:: Supported Syntaxes 4479 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4480 4481 "","","","","``__constant`` |br| ``constant``","","" 4482 4483The constant address space attribute signals that an object is located in 4484a constant (non-modifiable) memory region. It is available to all work items. 4485Any type can be annotated with the constant address space attribute. Objects 4486with the constant address space qualifier can be declared in any scope and must 4487have an initializer. 4488 4489 4490generic 4491------- 4492.. csv-table:: Supported Syntaxes 4493 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4494 4495 "","","","","``__generic`` |br| ``generic``","","" 4496 4497The generic address space attribute is only available with OpenCL v2.0 and later. 4498It can be used with pointer types. Variables in global and local scope and 4499function parameters in non-kernel functions can have the generic address space 4500type attribute. It is intended to be a placeholder for any other address space 4501except for '__constant' in OpenCL code which can be used with multiple address 4502spaces. 4503 4504 4505global 4506------ 4507.. csv-table:: Supported Syntaxes 4508 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4509 4510 "","","","","``__global`` |br| ``global``","","" 4511 4512The global address space attribute specifies that an object is allocated in 4513global memory, which is accessible by all work items. The content stored in this 4514memory area persists between kernel executions. Pointer types to the global 4515address space are allowed as function parameters or local variables. Starting 4516with OpenCL v2.0, the global address space can be used with global (program 4517scope) variables and static local variable as well. 4518 4519 4520local 4521----- 4522.. csv-table:: Supported Syntaxes 4523 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4524 4525 "","","","","``__local`` |br| ``local``","","" 4526 4527The local address space specifies that an object is allocated in the local (work 4528group) memory area, which is accessible to all work items in the same work 4529group. The content stored in this memory region is not accessible after 4530the kernel execution ends. In a kernel function scope, any variable can be in 4531the local address space. In other scopes, only pointer types to the local address 4532space are allowed. Local address space variables cannot have an initializer. 4533 4534 4535private 4536------- 4537.. csv-table:: Supported Syntaxes 4538 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4539 4540 "","","","","``__private`` |br| ``private``","","" 4541 4542The private address space specifies that an object is allocated in the private 4543(work item) memory. Other work items cannot access the same memory area and its 4544content is destroyed after work item execution ends. Local variables can be 4545declared in the private address space. Function arguments are always in the 4546private address space. Kernel function arguments of a pointer or an array type 4547cannot point to the private address space. 4548 4549 4550Calling Conventions 4551=================== 4552Clang supports several different calling conventions, depending on the target 4553platform and architecture. The calling convention used for a function determines 4554how parameters are passed, how results are returned to the caller, and other 4555low-level details of calling a function. 4556 4557aarch64_vector_pcs 4558------------------ 4559.. csv-table:: Supported Syntaxes 4560 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4561 4562 "``aarch64_vector_pcs``","``clang::aarch64_vector_pcs``","``clang::aarch64_vector_pcs``","","","","" 4563 4564On AArch64 targets, this attribute changes the calling convention of a 4565function to preserve additional floating-point and Advanced SIMD registers 4566relative to the default calling convention used for AArch64. 4567 4568This means it is more efficient to call such functions from code that performs 4569extensive floating-point and vector calculations, because fewer live SIMD and FP 4570registers need to be saved. This property makes it well-suited for e.g. 4571floating-point or vector math library functions, which are typically leaf 4572functions that require a small number of registers. 4573 4574However, using this attribute also means that it is more expensive to call 4575a function that adheres to the default calling convention from within such 4576a function. Therefore, it is recommended that this attribute is only used 4577for leaf functions. 4578 4579For more information, see the documentation for `aarch64_vector_pcs`_ on 4580the Arm Developer website. 4581 4582.. _`aarch64_vector_pcs`: https://developer.arm.com/products/software-development-tools/hpc/arm-compiler-for-hpc/vector-function-abi 4583 4584 4585fastcall 4586-------- 4587.. csv-table:: Supported Syntaxes 4588 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4589 4590 "``fastcall``","``gnu::fastcall``","","","``__fastcall`` |br| ``_fastcall``","","" 4591 4592On 32-bit x86 targets, this attribute changes the calling convention of a 4593function to use ECX and EDX as register parameters and clear parameters off of 4594the stack on return. This convention does not support variadic calls or 4595unprototyped functions in C, and has no effect on x86_64 targets. This calling 4596convention is supported primarily for compatibility with existing code. Users 4597seeking register parameters should use the ``regparm`` attribute, which does 4598not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN. 4599 4600.. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx 4601 4602 4603ms_abi 4604------ 4605.. csv-table:: Supported Syntaxes 4606 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4607 4608 "``ms_abi``","``gnu::ms_abi``","","","","","" 4609 4610On non-Windows x86_64 targets, this attribute changes the calling convention of 4611a function to match the default convention used on Windows x86_64. This 4612attribute has no effect on Windows targets or non-x86_64 targets. 4613 4614 4615pcs 4616--- 4617.. csv-table:: Supported Syntaxes 4618 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4619 4620 "``pcs``","``gnu::pcs``","","","","","" 4621 4622On ARM targets, this attribute can be used to select calling conventions 4623similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and 4624"aapcs-vfp". 4625 4626 4627preserve_all 4628------------ 4629.. csv-table:: Supported Syntaxes 4630 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4631 4632 "``preserve_all``","``clang::preserve_all``","``clang::preserve_all``","","","","" 4633 4634On X86-64 and AArch64 targets, this attribute changes the calling convention of 4635a function. The ``preserve_all`` calling convention attempts to make the code 4636in the caller even less intrusive than the ``preserve_most`` calling convention. 4637This calling convention also behaves identical to the ``C`` calling convention 4638on how arguments and return values are passed, but it uses a different set of 4639caller/callee-saved registers. This removes the burden of saving and 4640recovering a large register set before and after the call in the caller. If 4641the arguments are passed in callee-saved registers, then they will be 4642preserved by the callee across the call. This doesn't apply for values 4643returned in callee-saved registers. 4644 4645- On X86-64 the callee preserves all general purpose registers, except for 4646 R11. R11 can be used as a scratch register. Furthermore it also preserves 4647 all floating-point registers (XMMs/YMMs). 4648 4649The idea behind this convention is to support calls to runtime functions 4650that don't need to call out to any other functions. 4651 4652This calling convention, like the ``preserve_most`` calling convention, will be 4653used by a future version of the Objective-C runtime and should be considered 4654experimental at this time. 4655 4656 4657preserve_most 4658------------- 4659.. csv-table:: Supported Syntaxes 4660 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4661 4662 "``preserve_most``","``clang::preserve_most``","``clang::preserve_most``","","","","" 4663 4664On X86-64 and AArch64 targets, this attribute changes the calling convention of 4665a function. The ``preserve_most`` calling convention attempts to make the code 4666in the caller as unintrusive as possible. This convention behaves identically 4667to the ``C`` calling convention on how arguments and return values are passed, 4668but it uses a different set of caller/callee-saved registers. This alleviates 4669the burden of saving and recovering a large register set before and after the 4670call in the caller. If the arguments are passed in callee-saved registers, 4671then they will be preserved by the callee across the call. This doesn't 4672apply for values returned in callee-saved registers. 4673 4674- On X86-64 the callee preserves all general purpose registers, except for 4675 R11. R11 can be used as a scratch register. Floating-point registers 4676 (XMMs/YMMs) are not preserved and need to be saved by the caller. 4677 4678The idea behind this convention is to support calls to runtime functions 4679that have a hot path and a cold path. The hot path is usually a small piece 4680of code that doesn't use many registers. The cold path might need to call out to 4681another function and therefore only needs to preserve the caller-saved 4682registers, which haven't already been saved by the caller. The 4683`preserve_most` calling convention is very similar to the ``cold`` calling 4684convention in terms of caller/callee-saved registers, but they are used for 4685different types of function calls. ``coldcc`` is for function calls that are 4686rarely executed, whereas `preserve_most` function calls are intended to be 4687on the hot path and definitely executed a lot. Furthermore ``preserve_most`` 4688doesn't prevent the inliner from inlining the function call. 4689 4690This calling convention will be used by a future version of the Objective-C 4691runtime and should therefore still be considered experimental at this time. 4692Although this convention was created to optimize certain runtime calls to 4693the Objective-C runtime, it is not limited to this runtime and might be used 4694by other runtimes in the future too. The current implementation only 4695supports X86-64 and AArch64, but the intention is to support more architectures 4696in the future. 4697 4698 4699regcall 4700------- 4701.. csv-table:: Supported Syntaxes 4702 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4703 4704 "``regcall``","``gnu::regcall``","","","``__regcall``","","" 4705 4706On x86 targets, this attribute changes the calling convention to 4707`__regcall`_ convention. This convention aims to pass as many arguments 4708as possible in registers. It also tries to utilize registers for the 4709return value whenever it is possible. 4710 4711.. _`__regcall`: https://software.intel.com/en-us/node/693069 4712 4713 4714regparm 4715------- 4716.. csv-table:: Supported Syntaxes 4717 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4718 4719 "``regparm``","``gnu::regparm``","","","","","" 4720 4721On 32-bit x86 targets, the regparm attribute causes the compiler to pass 4722the first three integer parameters in EAX, EDX, and ECX instead of on the 4723stack. This attribute has no effect on variadic functions, and all parameters 4724are passed via the stack as normal. 4725 4726 4727stdcall 4728------- 4729.. csv-table:: Supported Syntaxes 4730 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4731 4732 "``stdcall``","``gnu::stdcall``","","","``__stdcall`` |br| ``_stdcall``","","" 4733 4734On 32-bit x86 targets, this attribute changes the calling convention of a 4735function to clear parameters off of the stack on return. This convention does 4736not support variadic calls or unprototyped functions in C, and has no effect on 4737x86_64 targets. This calling convention is used widely by the Windows API and 4738COM applications. See the documentation for `__stdcall`_ on MSDN. 4739 4740.. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx 4741 4742 4743thiscall 4744-------- 4745.. csv-table:: Supported Syntaxes 4746 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4747 4748 "``thiscall``","``gnu::thiscall``","","","``__thiscall`` |br| ``_thiscall``","","" 4749 4750On 32-bit x86 targets, this attribute changes the calling convention of a 4751function to use ECX for the first parameter (typically the implicit ``this`` 4752parameter of C++ methods) and clear parameters off of the stack on return. This 4753convention does not support variadic calls or unprototyped functions in C, and 4754has no effect on x86_64 targets. See the documentation for `__thiscall`_ on 4755MSDN. 4756 4757.. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx 4758 4759 4760vectorcall 4761---------- 4762.. csv-table:: Supported Syntaxes 4763 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4764 4765 "``vectorcall``","``clang::vectorcall``","``clang::vectorcall``","","``__vectorcall`` |br| ``_vectorcall``","","" 4766 4767On 32-bit x86 *and* x86_64 targets, this attribute changes the calling 4768convention of a function to pass vector parameters in SSE registers. 4769 4770On 32-bit x86 targets, this calling convention is similar to ``__fastcall``. 4771The first two integer parameters are passed in ECX and EDX. Subsequent integer 4772parameters are passed in memory, and callee clears the stack. On x86_64 4773targets, the callee does *not* clear the stack, and integer parameters are 4774passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling 4775convention. 4776 4777On both 32-bit x86 and x86_64 targets, vector and floating point arguments are 4778passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are 4779passed in sequential SSE registers if enough are available. If AVX is enabled, 4780256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that 4781cannot be passed in registers for any reason is passed by reference, which 4782allows the caller to align the parameter memory. 4783 4784See the documentation for `__vectorcall`_ on MSDN for more details. 4785 4786.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx 4787 4788 4789Consumed Annotation Checking 4790============================ 4791Clang supports additional attributes for checking basic resource management 4792properties, specifically for unique objects that have a single owning reference. 4793The following attributes are currently supported, although **the implementation 4794for these annotations is currently in development and are subject to change.** 4795 4796callable_when 4797------------- 4798.. csv-table:: Supported Syntaxes 4799 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4800 4801 "``callable_when``","``clang::callable_when``","","","","","Yes" 4802 4803Use ``__attribute__((callable_when(...)))`` to indicate what states a method 4804may be called in. Valid states are unconsumed, consumed, or unknown. Each 4805argument to this attribute must be a quoted string. E.g.: 4806 4807``__attribute__((callable_when("unconsumed", "unknown")))`` 4808 4809 4810consumable 4811---------- 4812.. csv-table:: Supported Syntaxes 4813 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4814 4815 "``consumable``","``clang::consumable``","","","","","Yes" 4816 4817Each ``class`` that uses any of the typestate annotations must first be marked 4818using the ``consumable`` attribute. Failure to do so will result in a warning. 4819 4820This attribute accepts a single parameter that must be one of the following: 4821``unknown``, ``consumed``, or ``unconsumed``. 4822 4823 4824param_typestate 4825--------------- 4826.. csv-table:: Supported Syntaxes 4827 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4828 4829 "``param_typestate``","``clang::param_typestate``","","","","","Yes" 4830 4831This attribute specifies expectations about function parameters. Calls to an 4832function with annotated parameters will issue a warning if the corresponding 4833argument isn't in the expected state. The attribute is also used to set the 4834initial state of the parameter when analyzing the function's body. 4835 4836 4837return_typestate 4838---------------- 4839.. csv-table:: Supported Syntaxes 4840 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4841 4842 "``return_typestate``","``clang::return_typestate``","","","","","Yes" 4843 4844The ``return_typestate`` attribute can be applied to functions or parameters. 4845When applied to a function the attribute specifies the state of the returned 4846value. The function's body is checked to ensure that it always returns a value 4847in the specified state. On the caller side, values returned by the annotated 4848function are initialized to the given state. 4849 4850When applied to a function parameter it modifies the state of an argument after 4851a call to the function returns. The function's body is checked to ensure that 4852the parameter is in the expected state before returning. 4853 4854 4855set_typestate 4856------------- 4857.. csv-table:: Supported Syntaxes 4858 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4859 4860 "``set_typestate``","``clang::set_typestate``","","","","","Yes" 4861 4862Annotate methods that transition an object into a new state with 4863``__attribute__((set_typestate(new_state)))``. The new state must be 4864unconsumed, consumed, or unknown. 4865 4866 4867test_typestate 4868-------------- 4869.. csv-table:: Supported Syntaxes 4870 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4871 4872 "``test_typestate``","``clang::test_typestate``","","","","","Yes" 4873 4874Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method 4875returns true if the object is in the specified state.. 4876 4877 4878Type Safety Checking 4879==================== 4880Clang supports additional attributes to enable checking type safety properties 4881that can't be enforced by the C type system. To see warnings produced by these 4882checks, ensure that -Wtype-safety is enabled. Use cases include: 4883 4884* MPI library implementations, where these attributes enable checking that 4885 the buffer type matches the passed ``MPI_Datatype``; 4886* for HDF5 library there is a similar use case to MPI; 4887* checking types of variadic functions' arguments for functions like 4888 ``fcntl()`` and ``ioctl()``. 4889 4890You can detect support for these attributes with ``__has_attribute()``. For 4891example: 4892 4893.. code-block:: c++ 4894 4895 #if defined(__has_attribute) 4896 # if __has_attribute(argument_with_type_tag) && \ 4897 __has_attribute(pointer_with_type_tag) && \ 4898 __has_attribute(type_tag_for_datatype) 4899 # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) 4900 /* ... other macros ... */ 4901 # endif 4902 #endif 4903 4904 #if !defined(ATTR_MPI_PWT) 4905 # define ATTR_MPI_PWT(buffer_idx, type_idx) 4906 #endif 4907 4908 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 4909 ATTR_MPI_PWT(1,3); 4910 4911argument_with_type_tag 4912---------------------- 4913.. csv-table:: Supported Syntaxes 4914 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4915 4916 "``argument_with_type_tag`` |br| ``pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","","","","" 4917 4918Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, 4919type_tag_idx)))`` on a function declaration to specify that the function 4920accepts a type tag that determines the type of some other argument. 4921 4922This attribute is primarily useful for checking arguments of variadic functions 4923(``pointer_with_type_tag`` can be used in most non-variadic cases). 4924 4925In the attribute prototype above: 4926 * ``arg_kind`` is an identifier that should be used when annotating all 4927 applicable type tags. 4928 * ``arg_idx`` provides the position of a function argument. The expected type of 4929 this function argument will be determined by the function argument specified 4930 by ``type_tag_idx``. In the code example below, "3" means that the type of the 4931 function's third argument will be determined by ``type_tag_idx``. 4932 * ``type_tag_idx`` provides the position of a function argument. This function 4933 argument will be a type tag. The type tag will determine the expected type of 4934 the argument specified by ``arg_idx``. In the code example below, "2" means 4935 that the type tag associated with the function's second argument should agree 4936 with the type of the argument specified by ``arg_idx``. 4937 4938For example: 4939 4940.. code-block:: c++ 4941 4942 int fcntl(int fd, int cmd, ...) 4943 __attribute__(( argument_with_type_tag(fcntl,3,2) )); 4944 // The function's second argument will be a type tag; this type tag will 4945 // determine the expected type of the function's third argument. 4946 4947 4948pointer_with_type_tag 4949--------------------- 4950.. csv-table:: Supported Syntaxes 4951 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4952 4953 "``argument_with_type_tag`` |br| ``pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","","","","" 4954 4955Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` 4956on a function declaration to specify that the function accepts a type tag that 4957determines the pointee type of some other pointer argument. 4958 4959In the attribute prototype above: 4960 * ``ptr_kind`` is an identifier that should be used when annotating all 4961 applicable type tags. 4962 * ``ptr_idx`` provides the position of a function argument; this function 4963 argument will have a pointer type. The expected pointee type of this pointer 4964 type will be determined by the function argument specified by 4965 ``type_tag_idx``. In the code example below, "1" means that the pointee type 4966 of the function's first argument will be determined by ``type_tag_idx``. 4967 * ``type_tag_idx`` provides the position of a function argument; this function 4968 argument will be a type tag. The type tag will determine the expected pointee 4969 type of the pointer argument specified by ``ptr_idx``. In the code example 4970 below, "3" means that the type tag associated with the function's third 4971 argument should agree with the pointee type of the pointer argument specified 4972 by ``ptr_idx``. 4973 4974For example: 4975 4976.. code-block:: c++ 4977 4978 typedef int MPI_Datatype; 4979 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 4980 __attribute__(( pointer_with_type_tag(mpi,1,3) )); 4981 // The function's 3rd argument will be a type tag; this type tag will 4982 // determine the expected pointee type of the function's 1st argument. 4983 4984 4985type_tag_for_datatype 4986--------------------- 4987.. csv-table:: Supported Syntaxes 4988 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 4989 4990 "``type_tag_for_datatype``","``clang::type_tag_for_datatype``","``clang::type_tag_for_datatype``","","","","" 4991 4992When declaring a variable, use 4993``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that 4994is tied to the ``type`` argument given to the attribute. 4995 4996In the attribute prototype above: 4997 * ``kind`` is an identifier that should be used when annotating all applicable 4998 type tags. 4999 * ``type`` indicates the name of the type. 5000 5001Clang supports annotating type tags of two forms. 5002 5003 * **Type tag that is a reference to a declared identifier.** 5004 Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that 5005 identifier: 5006 5007 .. code-block:: c++ 5008 5009 typedef int MPI_Datatype; 5010 extern struct mpi_datatype mpi_datatype_int 5011 __attribute__(( type_tag_for_datatype(mpi,int) )); 5012 #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) 5013 // &mpi_datatype_int is a type tag. It is tied to type "int". 5014 5015 * **Type tag that is an integral literal.** 5016 Declare a ``static const`` variable with an initializer value and attach 5017 ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration: 5018 5019 .. code-block:: c++ 5020 5021 typedef int MPI_Datatype; 5022 static const MPI_Datatype mpi_datatype_int 5023 __attribute__(( type_tag_for_datatype(mpi,int) )) = 42; 5024 #define MPI_INT ((MPI_Datatype) 42) 5025 // The number 42 is a type tag. It is tied to type "int". 5026 5027 5028The ``type_tag_for_datatype`` attribute also accepts an optional third argument 5029that determines how the type of the function argument specified by either 5030``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type 5031tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the 5032function argument specified by ``arg_idx`` is compared against the type 5033associated with the type tag. Also recall that for the ``pointer_with_type_tag`` 5034attribute, the pointee type of the function argument specified by ``ptr_idx`` is 5035compared against the type associated with the type tag.) There are two supported 5036values for this optional third argument: 5037 5038 * ``layout_compatible`` will cause types to be compared according to 5039 layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the 5040 layout-compatibility rules for two standard-layout struct types and for two 5041 standard-layout union types). This is useful when creating a type tag 5042 associated with a struct or union type. For example: 5043 5044 .. code-block:: c++ 5045 5046 /* In mpi.h */ 5047 typedef int MPI_Datatype; 5048 struct internal_mpi_double_int { double d; int i; }; 5049 extern struct mpi_datatype mpi_datatype_double_int 5050 __attribute__(( type_tag_for_datatype(mpi, 5051 struct internal_mpi_double_int, layout_compatible) )); 5052 5053 #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) 5054 5055 int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...) 5056 __attribute__(( pointer_with_type_tag(mpi,1,3) )); 5057 5058 /* In user code */ 5059 struct my_pair { double a; int b; }; 5060 struct my_pair *buffer; 5061 MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning because the 5062 // layout of my_pair is 5063 // compatible with that of 5064 // internal_mpi_double_int 5065 5066 struct my_int_pair { int a; int b; } 5067 struct my_int_pair *buffer2; 5068 MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning because the 5069 // layout of my_int_pair 5070 // does not match that of 5071 // internal_mpi_double_int 5072 5073 * ``must_be_null`` specifies that the function argument specified by either 5074 ``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for 5075 the ``pointer_with_type_tag`` attribute) should be a null pointer constant. 5076 The second argument to the ``type_tag_for_datatype`` attribute is ignored. For 5077 example: 5078 5079 .. code-block:: c++ 5080 5081 /* In mpi.h */ 5082 typedef int MPI_Datatype; 5083 extern struct mpi_datatype mpi_datatype_null 5084 __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); 5085 5086 #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) 5087 int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...) 5088 __attribute__(( pointer_with_type_tag(mpi,1,3) )); 5089 5090 /* In user code */ 5091 struct my_pair { double a; int b; }; 5092 struct my_pair *buffer; 5093 MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL 5094 // was specified but buffer 5095 // is not a null pointer 5096 5097 5098Nullability Attributes 5099====================== 5100Whether 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``). 5101 5102The 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: 5103 5104 .. code-block:: c 5105 5106 // No meaningful result when 'ptr' is null (here, it happens to be undefined behavior). 5107 int fetch(int * _Nonnull ptr) { return *ptr; } 5108 5109 // 'ptr' may be null. 5110 int fetch_or_zero(int * _Nullable ptr) { 5111 return ptr ? *ptr : 0; 5112 } 5113 5114 // A nullable pointer to non-null pointers to const characters. 5115 const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n); 5116 5117In 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: 5118 5119 .. code-block:: objective-c 5120 5121 @interface NSView : NSResponder 5122 - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView; 5123 @property (assign, nullable) NSView *superview; 5124 @property (readonly, nonnull) NSArray *subviews; 5125 @end 5126 5127_Nonnull 5128-------- 5129.. csv-table:: Supported Syntaxes 5130 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 5131 5132 "","","","","``_Nonnull``","","" 5133 5134The ``_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: 5135 5136 .. code-block:: c 5137 5138 int fetch(int * _Nonnull ptr); 5139 5140a 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. 5141 5142 5143_Null_unspecified 5144----------------- 5145.. csv-table:: Supported Syntaxes 5146 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 5147 5148 "","","","","``_Null_unspecified``","","" 5149 5150The ``_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. 5151 5152 5153_Nullable 5154--------- 5155.. csv-table:: Supported Syntaxes 5156 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 5157 5158 "","","","","``_Nullable``","","" 5159 5160The ``_Nullable`` nullability qualifier indicates that a value of the ``_Nullable`` pointer type can be null. For example, given: 5161 5162 .. code-block:: c 5163 5164 int fetch_or_zero(int * _Nullable ptr); 5165 5166a caller of ``fetch_or_zero`` can provide null. 5167 5168 5169nonnull 5170------- 5171.. csv-table:: Supported Syntaxes 5172 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 5173 5174 "``nonnull``","``gnu::nonnull``","","","","","" 5175 5176The ``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: 5177 5178 .. code-block:: c 5179 5180 extern void * my_memcpy (void *dest, const void *src, size_t len) 5181 __attribute__((nonnull (1, 2))); 5182 5183Here, the ``nonnull`` attribute indicates that parameters 1 and 2 5184cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null: 5185 5186 .. code-block:: c 5187 5188 extern void * my_memcpy (void *dest, const void *src, size_t len) 5189 __attribute__((nonnull)); 5190 5191Clang 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: 5192 5193 .. code-block:: c 5194 5195 extern void * my_memcpy (void *dest __attribute__((nonnull)), 5196 const void *src __attribute__((nonnull)), size_t len); 5197 5198Note 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. 5199 5200 5201returns_nonnull 5202--------------- 5203.. csv-table:: Supported Syntaxes 5204 :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``" 5205 5206 "``returns_nonnull``","``gnu::returns_nonnull``","","","","","Yes" 5207 5208The ``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: 5209 5210 .. code-block:: c 5211 5212 extern void * malloc (size_t size) __attribute__((returns_nonnull)); 5213 5214The ``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 5215 5216 5217