1 //==--- AttrDocs.td - Attribute documentation ----------------------------===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===---------------------------------------------------------------------===//
9 // To test that the documentation builds cleanly, you must run clang-tblgen to
10 // convert the .td file into a .rst file, and then run sphinx to convert the
11 // .rst file into an HTML file. After completing testing, you should revert the
12 // generated .rst file so that the modified version does not get checked in to
15 // To run clang-tblgen to generate the .rst file:
16 // clang-tblgen -gen-attr-docs -I <root>/llvm/tools/clang/include
17 // <root>/llvm/tools/clang/include/clang/Basic/Attr.td -o
18 // <root>/llvm/tools/clang/docs/AttributeReference.rst
20 // To run sphinx to generate the .html files (note that sphinx-build must be
21 // available on the PATH):
22 // Windows (from within the clang\docs directory):
24 // Non-Windows (from within the clang\docs directory):
25 // make -f Makefile.sphinx html
27 def GlobalDocumentation {
29 -------------------------------------------------------------------
30 NOTE: This file is automatically generated by running clang-tblgen
31 -gen-attr-docs. Do not edit this file by hand!!
32 -------------------------------------------------------------------
47 This page lists the attributes currently supported by Clang.
51 def SectionDocs : Documentation {
52 let Category = DocCatVariable;
54 The ``section`` attribute allows you to specify a specific section a
55 global variable or function should be in after translation.
57 let Heading = "section, __declspec(allocate)";
60 def InitSegDocs : Documentation {
61 let Category = DocCatVariable;
63 The attribute applied by ``pragma init_seg()`` controls the section into
64 which global initialization function pointers are emitted. It is only
65 available with ``-fms-extensions``. Typically, this function pointer is
66 emitted into ``.CRT$XCU`` on Windows. The user can change the order of
67 initialization by using a different section name with the same
68 ``.CRT$XC`` prefix and a suffix that sorts lexicographically before or
69 after the standard ``.CRT$XCU`` sections. See the init_seg_
70 documentation on MSDN for more information.
72 .. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx
76 def TLSModelDocs : Documentation {
77 let Category = DocCatVariable;
79 The ``tls_model`` attribute allows you to specify which thread-local storage
80 model to use. It accepts the following strings:
87 TLS models are mutually exclusive.
91 def DLLExportDocs : Documentation {
92 let Category = DocCatVariable;
94 The ``__declspec(dllexport)`` attribute declares a variable, function, or
95 Objective-C interface to be exported from the module. It is available under the
96 ``-fdeclspec`` flag for compatibility with various compilers. The primary use
97 is for COFF object files which explicitly specify what interfaces are available
98 for external use. See the dllexport_ documentation on MSDN for more
101 .. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
105 def DLLImportDocs : Documentation {
106 let Category = DocCatVariable;
108 The ``__declspec(dllimport)`` attribute declares a variable, function, or
109 Objective-C interface to be imported from an external module. It is available
110 under the ``-fdeclspec`` flag for compatibility with various compilers. The
111 primary use is for COFF object files which explicitly specify what interfaces
112 are imported from external modules. See the dllimport_ documentation on MSDN
113 for more information.
115 .. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
119 def ThreadDocs : Documentation {
120 let Category = DocCatVariable;
122 The ``__declspec(thread)`` attribute declares a variable with thread local
123 storage. It is available under the ``-fms-extensions`` flag for MSVC
124 compatibility. See the documentation for `__declspec(thread)`_ on MSDN.
126 .. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
128 In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the
129 GNU ``__thread`` keyword. The variable must not have a destructor and must have
130 a constant initializer, if any. The attribute only applies to variables
131 declared with static storage duration, such as globals, class static data
132 members, and static locals.
136 def NoEscapeDocs : Documentation {
137 let Category = DocCatVariable;
139 ``noescape`` placed on a function parameter of a pointer type is used to inform
140 the compiler that the pointer cannot escape: that is, no reference to the object
141 the pointer points to that is derived from the parameter value will survive
142 after the function returns. Users are responsible for making sure parameters
143 annotated with ``noescape`` do not actually escape. Calling ``free()`` on such
144 a parameter does not constitute an escape.
152 void nonescapingFunc(__attribute__((noescape)) int *p) {
156 void escapingFunc(__attribute__((noescape)) int *p) {
160 Additionally, when the parameter is a `block pointer
161 <https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction
162 applies to copies of the block. For example:
166 typedef void (^BlockTy)();
169 void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
173 void escapingFunc(__attribute__((noescape)) BlockTy block) {
174 g0 = block; // Not OK.
175 g1 = Block_copy(block); // Not OK either.
181 def CarriesDependencyDocs : Documentation {
182 let Category = DocCatFunction;
184 The ``carries_dependency`` attribute specifies dependency propagation into and
187 When specified on a function or Objective-C method, the ``carries_dependency``
188 attribute means that the return value carries a dependency out of the function,
189 so that the implementation need not constrain ordering upon return from that
190 function. Implementations of the function and its caller may choose to preserve
191 dependencies instead of emitting memory ordering instructions such as fences.
193 Note, this attribute does not change the meaning of the program, but may result
194 in generation of more efficient code.
198 def CPUSpecificCPUDispatchDocs : Documentation {
199 let Category = DocCatFunction;
201 The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
202 resolve multiversioned functions. This form of multiversioning provides a
203 mechanism for declaring versions across translation units and manually
204 specifying the resolved function list. A specified CPU defines a set of minimum
205 features that are required for the function to be called. The result of this is
206 that future processors execute the most restrictive version of the function the
207 new processor can execute.
209 Function versions are defined with ``cpu_specific``, which takes one or more CPU
210 names as a parameter. For example:
214 // Declares and defines the ivybridge version of single_cpu.
215 __attribute__((cpu_specific(ivybridge)))
216 void single_cpu(void){}
218 // Declares and defines the atom version of single_cpu.
219 __attribute__((cpu_specific(atom)))
220 void single_cpu(void){}
222 // Declares and defines both the ivybridge and atom version of multi_cpu.
223 __attribute__((cpu_specific(ivybridge, atom)))
224 void multi_cpu(void){}
226 A dispatching (or resolving) function can be declared anywhere in a project's
227 source code with ``cpu_dispatch``. This attribute takes one or more CPU names
228 as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
229 are not expected to be defined, only declared. If such a marked function has a
230 definition, any side effects of the function are ignored; trivial function
231 bodies are permissible for ICC compatibility.
235 // Creates a resolver for single_cpu above.
236 __attribute__((cpu_dispatch(ivybridge, atom)))
237 void single_cpu(void){}
239 // Creates a resolver for multi_cpu, but adds a 3rd version defined in another
241 __attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
242 void multi_cpu(void){}
244 Note that it is possible to have a resolving function that dispatches based on
245 more or fewer options than are present in the program. Specifying fewer will
246 result in the omitted options not being considered during resolution. Specifying
247 a version for resolution that isn't defined in the program will result in a
250 It is also possible to specify a CPU name of ``generic`` which will be resolved
251 if the executing processor doesn't satisfy the features required in the CPU
252 name. The behavior of a program executing on a processor that doesn't satisfy
253 any option of a multiversioned function is undefined.
257 def SYCLKernelDocs : Documentation {
258 let Category = DocCatFunction;
260 The ``sycl_kernel`` attribute specifies that a function template will be used
261 to outline device code and to generate an OpenCL kernel.
262 Here is a code example of the SYCL program, which demonstrates the compiler's
267 int foo(int x) { return ++x; }
269 using namespace cl::sycl;
271 buffer<int, 1> a(range<1>{1024});
272 Q.submit([&](handler& cgh) {
273 auto A = a.get_access<access::mode::write>(cgh);
274 cgh.parallel_for<init_a>(range<1>{1024}, [=](id<1> index) {
275 A[index] = index[0] + foo(42);
279 A C++ function object passed to the ``parallel_for`` is called a "SYCL kernel".
280 A SYCL kernel defines the entry point to the "device part" of the code. The
281 compiler will emit all symbols accessible from a "kernel". In this code
282 example, the compiler will emit "foo" function. More details about the
283 compilation of functions for the device part can be found in the SYCL 1.2.1
284 specification Section 6.4.
285 To show to the compiler entry point to the "device part" of the code, the SYCL
286 runtime can use the ``sycl_kernel`` attribute in the following way:
293 template <typename KernelName, typename KernelType/*, ...*/>
294 __attribute__((sycl_kernel)) void sycl_kernel_function(KernelType KernelFuncObj) {
299 template <typename KernelName, typename KernelType, int Dims>
300 void parallel_for(range<Dims> NumWorkItems, KernelType KernelFunc) {
301 #ifdef __SYCL_DEVICE_ONLY__
302 sycl_kernel_function<KernelName, KernelType, Dims>(KernelFunc);
304 // Host implementation
311 The compiler will also generate an OpenCL kernel using the function marked with
312 the ``sycl_kernel`` attribute.
313 Here is the list of SYCL device compiler expectations with regard to the
314 function marked with the ``sycl_kernel`` attribute:
316 - The function must be a template with at least two type template parameters.
317 The compiler generates an OpenCL kernel and uses the first template parameter
318 as a unique name for the generated OpenCL kernel. The host application uses
319 this unique name to invoke the OpenCL kernel generated for the SYCL kernel
320 specialized by this name and second template parameter ``KernelType`` (which
321 might be an unnamed function object type).
322 - The function must have at least one parameter. The first parameter is
323 required to be a function object type (named or unnamed i.e. lambda). The
324 compiler uses function object type fields to generate OpenCL kernel
326 - The function must return void. The compiler reuses the body of marked functions to
327 generate the OpenCL kernel body, and the OpenCL kernel must return ``void``.
329 The SYCL kernel in the previous code sample meets these expectations.
333 def C11NoReturnDocs : Documentation {
334 let Category = DocCatFunction;
336 A function declared as ``_Noreturn`` shall not return to its caller. The
337 compiler will generate a diagnostic for a function declared as ``_Noreturn``
338 that appears to be capable of returning to its caller. Despite being a type
339 specifier, the ``_Noreturn`` attribute cannot be specified on a function
344 def CXX11NoReturnDocs : Documentation {
345 let Category = DocCatFunction;
347 A function declared as ``[[noreturn]]`` shall not return to its caller. The
348 compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
349 that appears to be capable of returning to its caller.
353 def NoMergeDocs : Documentation {
354 let Category = DocCatFunction;
356 If a statement is marked ``nomerge`` and contains call experessions, those call
357 expressions inside the statement will not be merged during optimization. This
358 attribute can be used to prevent the optimizer from obscuring the source
359 location of certain calls. For example, it will prevent tail merging otherwise
360 identical code sequences that raise an exception or terminate the program. Tail
361 merging normally reduces the precision of source location information, making
362 stack traces less useful for debugging. This attribute gives the user control
363 over the tradeoff between code size and debug information precision.
367 def AssertCapabilityDocs : Documentation {
368 let Category = DocCatFunction;
369 let Heading = "assert_capability, assert_shared_capability";
371 Marks a function that dynamically tests whether a capability is held, and halts
372 the program if it is not held.
376 def AcquireCapabilityDocs : Documentation {
377 let Category = DocCatFunction;
378 let Heading = "acquire_capability, acquire_shared_capability";
380 Marks a function as acquiring a capability.
384 def TryAcquireCapabilityDocs : Documentation {
385 let Category = DocCatFunction;
386 let Heading = "try_acquire_capability, try_acquire_shared_capability";
388 Marks a function that attempts to acquire a capability. This function may fail to
389 actually acquire the capability; they accept a Boolean value determining
390 whether acquiring the capability means success (true), or failing to acquire
391 the capability means success (false).
395 def ReleaseCapabilityDocs : Documentation {
396 let Category = DocCatFunction;
397 let Heading = "release_capability, release_shared_capability";
399 Marks a function as releasing a capability.
403 def AssumeAlignedDocs : Documentation {
404 let Category = DocCatFunction;
406 Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function
407 declaration to specify that the return value of the function (which must be a
408 pointer type) has the specified offset, in bytes, from an address with the
409 specified alignment. The offset is taken to be zero if omitted.
413 // The returned pointer value has 32-byte alignment.
414 void *a() __attribute__((assume_aligned (32)));
416 // The returned pointer value is 4 bytes greater than an address having
417 // 32-byte alignment.
418 void *b() __attribute__((assume_aligned (32, 4)));
420 Note that this attribute provides information to the compiler regarding a
421 condition that the code already ensures is true. It does not cause the compiler
422 to enforce the provided alignment assumption.
426 def AllocSizeDocs : Documentation {
427 let Category = DocCatFunction;
429 The ``alloc_size`` attribute can be placed on functions that return pointers in
430 order to hint to the compiler how many bytes of memory will be available at the
431 returned pointer. ``alloc_size`` takes one or two arguments.
433 - ``alloc_size(N)`` implies that argument number N equals the number of
434 available bytes at the returned pointer.
435 - ``alloc_size(N, M)`` implies that the product of argument number N and
436 argument number M equals the number of available bytes at the returned
439 Argument numbers are 1-based.
441 An example of how to use ``alloc_size``
445 void *my_malloc(int a) __attribute__((alloc_size(1)));
446 void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
449 void *const p = my_malloc(100);
450 assert(__builtin_object_size(p, 0) == 100);
451 void *const a = my_calloc(20, 5);
452 assert(__builtin_object_size(a, 0) == 100);
455 .. Note:: This attribute works differently in clang than it does in GCC.
456 Specifically, clang will only trace ``const`` pointers (as above); we give up
457 on pointers that are not marked as ``const``. In the vast majority of cases,
458 this is unimportant, because LLVM has support for the ``alloc_size``
459 attribute. However, this may cause mildly unintuitive behavior when used with
460 other attributes, such as ``enable_if``.
464 def CodeSegDocs : Documentation {
465 let Category = DocCatFunction;
467 The ``__declspec(code_seg)`` attribute enables the placement of code into separate
468 named segments that can be paged or locked in memory individually. This attribute
469 is used to control the placement of instantiated templates and compiler-generated
470 code. See the documentation for `__declspec(code_seg)`_ on MSDN.
472 .. _`__declspec(code_seg)`: http://msdn.microsoft.com/en-us/library/dn636922.aspx
476 def AllocAlignDocs : Documentation {
477 let Category = DocCatFunction;
479 Use ``__attribute__((alloc_align(<alignment>))`` on a function
480 declaration to specify that the return value of the function (which must be a
481 pointer type) is at least as aligned as the value of the indicated parameter. The
482 parameter is given by its index in the list of formal parameters; the first
483 parameter has index 1 unless the function is a C++ non-static member function,
484 in which case the first parameter has index 2 to account for the implicit ``this``
489 // The returned pointer has the alignment specified by the first parameter.
490 void *a(size_t align) __attribute__((alloc_align(1)));
492 // The returned pointer has the alignment specified by the second parameter.
493 void *b(void *v, size_t align) __attribute__((alloc_align(2)));
495 // The returned pointer has the alignment specified by the second visible
496 // parameter, however it must be adjusted for the implicit 'this' parameter.
497 void *Foo::b(void *v, size_t align) __attribute__((alloc_align(3)));
499 Note that this attribute merely informs the compiler that a function always
500 returns a sufficiently aligned pointer. It does not cause the compiler to
501 emit code to enforce that alignment. The behavior is undefined if the returned
502 pointer is not sufficiently aligned.
506 def EnableIfDocs : Documentation {
507 let Category = DocCatFunction;
509 .. Note:: Some features of this attribute are experimental. The meaning of
510 multiple enable_if attributes on a single declaration is subject to change in
511 a future version of clang. Also, the ABI is not standardized and the name
512 mangling may change in future versions. To avoid that, use asm labels.
514 The ``enable_if`` attribute can be placed on function declarations to control
515 which overload is selected based on the values of the function's arguments.
516 When combined with the ``overloadable`` attribute, this feature is also
522 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")));
527 isdigit(-10); // results in a compile-time error.
530 The enable_if attribute takes two arguments, the first is an expression written
531 in terms of the function parameters, the second is a string explaining why this
532 overload candidate could not be selected to be displayed in diagnostics. The
533 expression is part of the function signature for the purposes of determining
534 whether it is a redeclaration (following the rules used when determining
535 whether a C++ template specialization is ODR-equivalent), but is not part of
538 The enable_if expression is evaluated as if it were the body of a
539 bool-returning constexpr function declared with the arguments of the function
540 it is being applied to, then called with the parameters at the call site. If the
541 result is false or could not be determined through constant expression
542 evaluation, then this overload will not be chosen and the provided string may
543 be used in a diagnostic if the compile fails as a result.
545 Because the enable_if expression is an unevaluated context, there are no global
546 state changes, nor the ability to pass information from the enable_if
547 expression to the function body. For example, suppose we want calls to
548 strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
549 strbuf) only if the size of strbuf can be determined:
553 __attribute__((always_inline))
554 static inline size_t strnlen(const char *s, size_t maxlen)
555 __attribute__((overloadable))
556 __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
557 "chosen when the buffer size is known but 'maxlen' is not")))
559 return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
562 Multiple enable_if attributes may be applied to a single declaration. In this
563 case, the enable_if expressions are evaluated from left to right in the
564 following manner. First, the candidates whose enable_if expressions evaluate to
565 false or cannot be evaluated are discarded. If the remaining candidates do not
566 share ODR-equivalent enable_if expressions, the overload resolution is
567 ambiguous. Otherwise, enable_if overload resolution continues with the next
568 enable_if attribute on the candidates that have not been discarded and have
569 remaining enable_if attributes. In this way, we pick the most specific
570 overload out of a number of viable overloads using enable_if.
574 void f() __attribute__((enable_if(true, ""))); // #1
575 void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
577 void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
578 void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
580 In this example, a call to f() is always resolved to #2, as the first enable_if
581 expression is ODR-equivalent for both declarations, but #1 does not have another
582 enable_if expression to continue evaluating, so the next round of evaluation has
583 only a single candidate. In a call to g(1, 1), the call is ambiguous even though
584 #2 has more enable_if attributes, because the first enable_if expressions are
587 Query for this feature with ``__has_attribute(enable_if)``.
589 Note that functions with one or more ``enable_if`` attributes may not have
590 their address taken, unless all of the conditions specified by said
591 ``enable_if`` are constants that evaluate to ``true``. For example:
595 const int TrueConstant = 1;
596 const int FalseConstant = 0;
597 int f(int a) __attribute__((enable_if(a > 0, "")));
598 int g(int a) __attribute__((enable_if(a == 0 || a != 0, "")));
599 int h(int a) __attribute__((enable_if(1, "")));
600 int i(int a) __attribute__((enable_if(TrueConstant, "")));
601 int j(int a) __attribute__((enable_if(FalseConstant, "")));
605 ptr = &f; // error: 'a > 0' is not always true
606 ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant
607 ptr = &h; // OK: 1 is a truthy constant
608 ptr = &i; // OK: 'TrueConstant' is a truthy constant
609 ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
612 Because ``enable_if`` evaluation happens during overload resolution,
613 ``enable_if`` may give unintuitive results when used with templates, depending
614 on when overloads are resolved. In the example below, clang will emit a
615 diagnostic about no viable overloads for ``foo`` in ``bar``, but not in ``baz``:
619 double foo(int i) __attribute__((enable_if(i > 0, "")));
620 void *foo(int i) __attribute__((enable_if(i <= 0, "")));
622 auto bar() { return foo(I); }
624 template <typename T>
625 auto baz() { return foo(T::number); }
627 struct WithNumber { constexpr static int number = 1; };
629 bar<sizeof(WithNumber)>();
633 This is because, in ``bar``, ``foo`` is resolved prior to template
634 instantiation, so the value for ``I`` isn't known (thus, both ``enable_if``
635 conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during
636 template instantiation, so the value for ``T::number`` is known.
640 def DiagnoseIfDocs : Documentation {
641 let Category = DocCatFunction;
643 The ``diagnose_if`` attribute can be placed on function declarations to emit
644 warnings or errors at compile-time if calls to the attributed function meet
645 certain user-defined criteria. For example:
650 __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
652 __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
654 int val = abs(1); // warning: Redundant abs call
655 int val2 = must_abs(1); // error: Redundant abs call
657 int val4 = must_abs(val); // Because run-time checks are not emitted for
658 // diagnose_if attributes, this executes without
662 ``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
664 * Overload resolution is not aware of ``diagnose_if`` attributes: they're
665 considered only after we select the best candidate from a given candidate set.
666 * Function declarations that differ only in their ``diagnose_if`` attributes are
667 considered to be redeclarations of the same function (not overloads).
668 * If the condition provided to ``diagnose_if`` cannot be evaluated, no
669 diagnostic will be emitted.
671 Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
673 As a result of bullet number two, ``diagnose_if`` attributes will stack on the
674 same function. For example:
678 int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
679 int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
681 int bar = foo(); // warning: diag1
683 int (*fooptr)(void) = foo; // warning: diag1
686 constexpr int supportsAPILevel(int N) { return N < 5; }
688 __attribute__((diagnose_if(!supportsAPILevel(10),
689 "Upgrade to API level 10 to use baz", "error")));
691 __attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
693 int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
694 int v = baz(0); // error: Upgrade to API level 10 to use baz
696 Query for this feature with ``__has_attribute(diagnose_if)``.
700 def PassObjectSizeDocs : Documentation {
701 let Category = DocCatVariable; // Technically it's a parameter doc, but eh.
702 let Heading = "pass_object_size, pass_dynamic_object_size";
704 .. Note:: The mangling of functions with parameters that are annotated with
705 ``pass_object_size`` is subject to change. You can get around this by
706 using ``__asm__("foo")`` to explicitly name your functions, thus preserving
707 your ABI; also, non-overloadable C functions with ``pass_object_size`` are
710 The ``pass_object_size(Type)`` attribute can be placed on function parameters to
711 instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite
712 of said function, and implicitly pass the result of this call in as an invisible
713 argument of type ``size_t`` directly after the parameter annotated with
714 ``pass_object_size``. Clang will also replace any calls to
715 ``__builtin_object_size(param, Type)`` in the function by said implicit
722 int bzero1(char *const p __attribute__((pass_object_size(0))))
723 __attribute__((noinline)) {
725 for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
733 int n = bzero1(&chars[0]);
734 assert(n == sizeof(chars));
738 If successfully evaluating ``__builtin_object_size(param, Type)`` at the
739 callsite is not possible, then the "failed" value is passed in. So, using the
740 definition of ``bzero1`` from above, the following code would exit cleanly:
744 int main2(int argc, char *argv[]) {
745 int n = bzero1(argv);
750 ``pass_object_size`` plays a part in overload resolution. If two overload
751 candidates are otherwise equally good, then the overload with one or more
752 parameters with ``pass_object_size`` is preferred. This implies that the choice
753 between two identical overloads both with ``pass_object_size`` on one or more
754 parameters will always be ambiguous; for this reason, having two such overloads
755 is illegal. For example:
759 #define PS(N) __attribute__((pass_object_size(N)))
761 void Foo(char *a, char *b); // Overload A
762 // OK -- overload A has no parameters with pass_object_size.
763 void Foo(char *a PS(0), char *b PS(0)); // Overload B
764 // Error -- Same signature (sans pass_object_size) as overload B, and both
765 // overloads have one or more parameters with the pass_object_size attribute.
766 void Foo(void *a PS(0), void *b);
769 void Bar(void *a PS(0)); // Overload C
771 void Bar(char *c PS(1)); // Overload D
774 char known[10], *unknown;
775 Foo(unknown, unknown); // Calls overload B
776 Foo(known, unknown); // Calls overload B
777 Foo(unknown, known); // Calls overload B
778 Foo(known, known); // Calls overload B
780 Bar(known); // Calls overload D
781 Bar(unknown); // Calls overload D
784 Currently, ``pass_object_size`` is a bit restricted in terms of its usage:
786 * Only one use of ``pass_object_size`` is allowed per parameter.
788 * It is an error to take the address of a function with ``pass_object_size`` on
789 any of its parameters. If you wish to do this, you can create an overload
790 without ``pass_object_size`` on any parameters.
792 * It is an error to apply the ``pass_object_size`` attribute to parameters that
793 are not pointers. Additionally, any parameter that ``pass_object_size`` is
794 applied to must be marked ``const`` at its function's definition.
796 Clang also supports the ``pass_dynamic_object_size`` attribute, which behaves
797 identically to ``pass_object_size``, but evaluates a call to
798 ``__builtin_dynamic_object_size`` at the callee instead of
799 ``__builtin_object_size``. ``__builtin_dynamic_object_size`` provides some extra
800 runtime checks when the object size can't be determined at compile-time. You can
801 read more about ``__builtin_dynamic_object_size`` `here
802 <https://clang.llvm.org/docs/LanguageExtensions.html#evaluating-object-size-dynamically>`_.
807 def OverloadableDocs : Documentation {
808 let Category = DocCatFunction;
810 Clang provides support for C++ function overloading in C. Function overloading
811 in C is introduced using the ``overloadable`` attribute. For example, one
812 might provide several overloaded versions of a ``tgsin`` function that invokes
813 the appropriate standard function computing the sine of a value with ``float``,
814 ``double``, or ``long double`` precision:
819 float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
820 double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
821 long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
823 Given these declarations, one can call ``tgsin`` with a ``float`` value to
824 receive a ``float`` result, with a ``double`` to receive a ``double`` result,
825 etc. Function overloading in C follows the rules of C++ function overloading
826 to pick the best overload given the call arguments, with a few C-specific
829 * Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
830 floating-point promotion (per C99) rather than as a floating-point conversion
833 * A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
834 considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
837 * A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
838 and ``U`` are compatible types. This conversion is given "conversion" rank.
840 * If no viable candidates are otherwise available, we allow a conversion from a
841 pointer of type ``T*`` to a pointer of type ``U*``, where ``T`` and ``U`` are
842 incompatible. This conversion is ranked below all other types of conversions.
843 Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
844 for ``T`` and ``U`` to be incompatible.
846 The declaration of ``overloadable`` functions is restricted to function
847 declarations and definitions. If a function is marked with the ``overloadable``
848 attribute, then all declarations and definitions of functions with that name,
849 except for at most one (see the note below about unmarked overloads), must have
850 the ``overloadable`` attribute. In addition, redeclarations of a function with
851 the ``overloadable`` attribute must have the ``overloadable`` attribute, and
852 redeclarations of a function without the ``overloadable`` attribute must *not*
853 have the ``overloadable`` attribute. e.g.,
857 int f(int) __attribute__((overloadable));
858 float f(float); // error: declaration of "f" must have the "overloadable" attribute
859 int f(int); // error: redeclaration of "f" must have the "overloadable" attribute
861 int g(int) __attribute__((overloadable));
862 int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
865 int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
866 // have the "overloadable" attribute
868 Functions marked ``overloadable`` must have prototypes. Therefore, the
869 following code is ill-formed:
873 int h() __attribute__((overloadable)); // error: h does not have a prototype
875 However, ``overloadable`` functions are allowed to use a ellipsis even if there
876 are no named parameters (as is permitted in C++). This feature is particularly
877 useful when combined with the ``unavailable`` attribute:
881 void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
883 Functions declared with the ``overloadable`` attribute have their names mangled
884 according to the same rules as C++ function names. For example, the three
885 ``tgsin`` functions in our motivating example get the mangled names
886 ``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
887 caveats to this use of name mangling:
889 * Future versions of Clang may change the name mangling of functions overloaded
890 in C, so you should not depend on an specific mangling. To be completely
891 safe, we strongly urge the use of ``static inline`` with ``overloadable``
894 * The ``overloadable`` attribute has almost no meaning when used in C++,
895 because names will already be mangled and functions are already overloadable.
896 However, when an ``overloadable`` function occurs within an ``extern "C"``
897 linkage specification, it's name *will* be mangled in the same way as it
900 For the purpose of backwards compatibility, at most one function with the same
901 name as other ``overloadable`` functions may omit the ``overloadable``
902 attribute. In this case, the function without the ``overloadable`` attribute
903 will not have its name mangled.
909 // Notes with mangled names assume Itanium mangling.
911 int f(double) __attribute__((overloadable));
913 f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
914 // was marked with overloadable).
915 f(1.0); // Emits a call to _Z1fd.
918 Support for unmarked overloads is not present in some versions of clang. You may
919 query for it using ``__has_extension(overloadable_unmarked)``.
921 Query for this attribute with ``__has_attribute(overloadable)``.
925 def ObjCMethodFamilyDocs : Documentation {
926 let Category = DocCatFunction;
928 Many methods in Objective-C have conventional meanings determined by their
929 selectors. It is sometimes useful to be able to mark a method as having a
930 particular conventional meaning despite not having the right selector, or as
931 not having the conventional meaning that its selector would suggest. For these
932 use cases, we provide an attribute to specifically describe the "method family"
933 that a method belongs to.
935 **Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
936 ``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
937 attribute can only be placed at the end of a method declaration:
941 - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
943 Users who do not wish to change the conventional meaning of a method, and who
944 merely want to document its non-standard retain and release semantics, should
945 use the retaining behavior attributes (``ns_returns_retained``,
946 ``ns_returns_not_retained``, etc).
948 Query for this feature with ``__has_attribute(objc_method_family)``.
952 def RetainBehaviorDocs : Documentation {
953 let Category = DocCatFunction;
955 The behavior of a function with respect to reference counting for Foundation
956 (Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
957 convention (e.g. functions starting with "get" are assumed to return at
960 It can be overridden using a family of the following attributes. In
961 Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
962 a function communicates that the object is returned at ``+1``, and the caller
963 is responsible for freeing it.
964 Similarly, the annotation ``__attribute__((ns_returns_not_retained))``
965 specifies that the object is returned at ``+0`` and the ownership remains with
967 The annotation ``__attribute__((ns_consumes_self))`` specifies that
968 the Objective-C method call consumes the reference to ``self``, e.g. by
969 attaching it to a supplied parameter.
970 Additionally, parameters can have an annotation
971 ``__attribute__((ns_consumed))``, which specifies that passing an owned object
972 as that parameter effectively transfers the ownership, and the caller is no
973 longer responsible for it.
974 These attributes affect code generation when interacting with ARC code, and
975 they are used by the Clang Static Analyzer.
977 In C programs using CoreFoundation, a similar set of attributes:
978 ``__attribute__((cf_returns_not_retained))``,
979 ``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
980 have the same respective semantics when applied to CoreFoundation objects.
981 These attributes affect code generation when interacting with ARC code, and
982 they are used by the Clang Static Analyzer.
984 Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
985 the same attribute family is present:
986 ``__attribute__((os_returns_not_retained))``,
987 ``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
988 with the same respective semantics.
989 Similar to ``__attribute__((ns_consumes_self))``,
990 ``__attribute__((os_consumes_this))`` specifies that the method call consumes
991 the reference to "this" (e.g., when attaching it to a different object supplied
993 Out parameters (parameters the function is meant to write into,
994 either via pointers-to-pointers or references-to-pointers)
995 may be annotated with ``__attribute__((os_returns_retained))``
996 or ``__attribute__((os_returns_not_retained))`` which specifies that the object
997 written into the out parameter should (or respectively should not) be released
999 Since often out parameters may or may not be written depending on the exit
1000 code of the function,
1001 annotations ``__attribute__((os_returns_retained_on_zero))``
1002 and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
1003 an out parameter at ``+1`` is written if and only if the function returns a zero
1004 (respectively non-zero) error code.
1005 Observe that return-code-dependent out parameter annotations are only
1006 available for retained out parameters, as non-retained object do not have to be
1007 released by the callee.
1008 These attributes are only used by the Clang Static Analyzer.
1010 The family of attributes ``X_returns_X_retained`` can be added to functions,
1011 C++ methods, and Objective-C methods and properties.
1012 Attributes ``X_consumed`` can be added to parameters of methods, functions,
1013 and Objective-C methods.
1017 def NoDebugDocs : Documentation {
1018 let Category = DocCatVariable;
1020 The ``nodebug`` attribute allows you to suppress debugging information for a
1021 function or method, or for a variable that is not a parameter or a non-static
1026 def NoDuplicateDocs : Documentation {
1027 let Category = DocCatFunction;
1029 The ``noduplicate`` attribute can be placed on function declarations to control
1030 whether function calls to this function can be duplicated or not as a result of
1031 optimizations. This is required for the implementation of functions with
1032 certain special requirements, like the OpenCL "barrier" function, that might
1033 need to be run concurrently by all the threads that are executing in lockstep
1034 on the hardware. For example this attribute applied on the function
1035 "nodupfunc" in the code below avoids that:
1039 void nodupfunc() __attribute__((noduplicate));
1040 // Setting it as a C++11 attribute is also valid
1041 // void nodupfunc() [[clang::noduplicate]];
1052 gets possibly modified by some optimizations into code similar to this:
1064 where the call to "nodupfunc" is duplicated and sunk into the two branches
1069 def ConvergentDocs : Documentation {
1070 let Category = DocCatFunction;
1072 The ``convergent`` attribute can be placed on a function declaration. It is
1073 translated into the LLVM ``convergent`` attribute, which indicates that the call
1074 instructions of a function with this attribute cannot be made control-dependent
1075 on any additional values.
1077 In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
1078 the call instructions of a function with this attribute must be executed by
1079 all work items or threads in a work group or sub group.
1081 This attribute is different from ``noduplicate`` because it allows duplicating
1082 function calls if it can be proved that the duplicated function calls are
1083 not made control-dependent on any additional values, e.g., unrolling a loop
1084 executed by all work items.
1089 void convfunc(void) __attribute__((convergent));
1090 // Setting it as a C++11 attribute is also valid in a C++ program.
1091 // void convfunc(void) [[clang::convergent]];
1096 def NoSplitStackDocs : Documentation {
1097 let Category = DocCatFunction;
1099 The ``no_split_stack`` attribute disables the emission of the split stack
1100 preamble for a particular function. It has no effect if ``-fsplit-stack``
1105 def NoUniqueAddressDocs : Documentation {
1106 let Category = DocCatField;
1108 The ``no_unique_address`` attribute allows tail padding in a non-static data
1109 member to overlap other members of the enclosing class (and in the special
1110 case when the type is empty, permits it to fully overlap other members).
1111 The field is laid out as if a base class were encountered at the corresponding
1112 point within the class (except that it does not share a vptr with the enclosing
1119 template<typename T, typename Alloc> struct my_vector {
1121 [[no_unique_address]] Alloc alloc;
1124 static_assert(sizeof(my_vector<int, std::allocator<int>>) == sizeof(int*));
1126 ``[[no_unique_address]]`` is a standard C++20 attribute. Clang supports its use
1131 def ObjCRequiresSuperDocs : Documentation {
1132 let Category = DocCatFunction;
1134 Some Objective-C classes allow a subclass to override a particular method in a
1135 parent class but expect that the overriding method also calls the overridden
1136 method in the parent class. For these cases, we provide an attribute to
1137 designate that a method requires a "call to ``super``" in the overriding
1138 method in the subclass.
1140 **Usage**: ``__attribute__((objc_requires_super))``. This attribute can only
1141 be placed at the end of a method declaration:
1143 .. code-block:: objc
1145 - (void)foo __attribute__((objc_requires_super));
1147 This attribute can only be applied the method declarations within a class, and
1148 not a protocol. Currently this attribute does not enforce any placement of
1149 where the call occurs in the overriding method (such as in the case of
1150 ``-dealloc`` where the call must appear at the end). It checks only that it
1153 Note that on both OS X and iOS that the Foundation framework provides a
1154 convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
1157 .. code-block:: objc
1159 - (void)foo NS_REQUIRES_SUPER;
1161 This macro is conditionally defined depending on the compiler's support for
1162 this attribute. If the compiler does not support the attribute the macro
1165 Operationally, when a method has this annotation the compiler will warn if the
1166 implementation of an override in a subclass does not call super. For example:
1168 .. code-block:: objc
1170 warning: method possibly missing a [super AnnotMeth] call
1171 - (void) AnnotMeth{};
1176 def ObjCRuntimeNameDocs : Documentation {
1177 let Category = DocCatDecl;
1179 By default, the Objective-C interface or protocol identifier is used
1180 in the metadata name for that object. The ``objc_runtime_name``
1181 attribute allows annotated interfaces or protocols to use the
1182 specified string argument in the object's metadata name instead of the
1185 **Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute
1186 can only be placed before an @protocol or @interface declaration:
1188 .. code-block:: objc
1190 __attribute__((objc_runtime_name("MyLocalName")))
1197 def ObjCRuntimeVisibleDocs : Documentation {
1198 let Category = DocCatDecl;
1200 This attribute specifies that the Objective-C class to which it applies is
1201 visible to the Objective-C runtime but not to the linker. Classes annotated
1202 with this attribute cannot be subclassed and cannot have categories defined for
1207 def ObjCClassStubDocs : Documentation {
1208 let Category = DocCatType;
1210 This attribute specifies that the Objective-C class to which it applies is
1211 instantiated at runtime.
1213 Unlike ``__attribute__((objc_runtime_visible))``, a class having this attribute
1214 still has a "class stub" that is visible to the linker. This allows categories
1215 to be defined. Static message sends with the class as a receiver use a special
1216 access pattern to ensure the class is lazily instantiated from the class stub.
1218 Classes annotated with this attribute cannot be subclassed and cannot have
1219 implementations defined for them. This attribute is intended for use in
1220 Swift-generated headers for classes defined in Swift.
1222 Adding or removing this attribute to a class is an ABI-breaking change.
1226 def ObjCBoxableDocs : Documentation {
1227 let Category = DocCatDecl;
1229 Structs and unions marked with the ``objc_boxable`` attribute can be used
1230 with the Objective-C boxed expression syntax, ``@(...)``.
1232 **Usage**: ``__attribute__((objc_boxable))``. This attribute
1233 can only be placed on a declaration of a trivially-copyable struct or union:
1235 .. code-block:: objc
1237 struct __attribute__((objc_boxable)) some_struct {
1240 union __attribute__((objc_boxable)) some_union {
1244 typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
1249 NSValue *boxed = @(ss);
1254 def AvailabilityDocs : Documentation {
1255 let Category = DocCatFunction;
1257 The ``availability`` attribute can be placed on declarations to describe the
1258 lifecycle of that declaration relative to operating system versions. Consider
1259 the function declaration for a hypothetical function ``f``:
1263 void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
1265 The availability attribute states that ``f`` was introduced in macOS 10.4,
1266 deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
1267 is used by Clang to determine when it is safe to use ``f``: for example, if
1268 Clang is instructed to compile code for macOS 10.5, a call to ``f()``
1269 succeeds. If Clang is instructed to compile code for macOS 10.6, the call
1270 succeeds but Clang emits a warning specifying that the function is deprecated.
1271 Finally, if Clang is instructed to compile code for macOS 10.7, the call
1272 fails because ``f()`` is no longer available.
1274 The availability attribute is a comma-separated list starting with the
1275 platform name and then including clauses specifying important milestones in the
1276 declaration's lifetime (in any order) along with additional information. Those
1279 introduced=\ *version*
1280 The first version in which this declaration was introduced.
1282 deprecated=\ *version*
1283 The first version in which this declaration was deprecated, meaning that
1284 users should migrate away from this API.
1286 obsoleted=\ *version*
1287 The first version in which this declaration was obsoleted, meaning that it
1288 was removed completely and can no longer be used.
1291 This declaration is never available on this platform.
1293 message=\ *string-literal*
1294 Additional message text that Clang will provide when emitting a warning or
1295 error about use of a deprecated or obsoleted declaration. Useful to direct
1296 users to replacement APIs.
1298 replacement=\ *string-literal*
1299 Additional message text that Clang will use to provide Fix-It when emitting
1300 a warning about use of a deprecated declaration. The Fix-It will replace
1301 the deprecated declaration with the new declaration specified.
1303 Multiple availability attributes can be placed on a declaration, which may
1304 correspond to different platforms. For most platforms, the availability
1305 attribute with the platform corresponding to the target platform will be used;
1306 any others will be ignored. However, the availability for ``watchOS`` and
1307 ``tvOS`` can be implicitly inferred from an ``iOS`` availability attribute.
1308 Any explicit availability attributes for those platforms are still preferred over
1309 the implicitly inferred availability attributes. If no availability attribute
1310 specifies availability for the current target platform, the availability
1311 attributes are ignored. Supported platforms are:
1314 Apple's iOS operating system. The minimum deployment target is specified by
1315 the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
1316 command-line arguments.
1319 Apple's macOS operating system. The minimum deployment target is
1320 specified by the ``-mmacosx-version-min=*version*`` command-line argument.
1321 ``macosx`` is supported for backward-compatibility reasons, but it is
1325 Apple's tvOS operating system. The minimum deployment target is specified by
1326 the ``-mtvos-version-min=*version*`` command-line argument.
1329 Apple's watchOS operating system. The minimum deployment target is specified by
1330 the ``-mwatchos-version-min=*version*`` command-line argument.
1332 A declaration can typically be used even when deploying back to a platform
1333 version prior to when the declaration was introduced. When this happens, the
1334 declaration is `weakly linked
1335 <https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
1336 as if the ``weak_import`` attribute were added to the declaration. A
1337 weakly-linked declaration may or may not be present a run-time, and a program
1338 can determine whether the declaration is present by checking whether the
1339 address of that declaration is non-NULL.
1341 The flag ``strict`` disallows using API when deploying back to a
1342 platform version prior to when the declaration was introduced. An
1343 attempt to use such API before its introduction causes a hard error.
1344 Weakly-linking is almost always a better API choice, since it allows
1345 users to query availability at runtime.
1347 If there are multiple declarations of the same entity, the availability
1348 attributes must either match on a per-platform basis or later
1349 declarations must not have availability attributes for that
1350 platform. For example:
1354 void g(void) __attribute__((availability(macos,introduced=10.4)));
1355 void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
1356 void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
1357 void g(void); // okay, inherits both macos and ios availability from above.
1358 void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
1360 When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
1362 .. code-block:: objc
1365 - (id)method __attribute__((availability(macos,introduced=10.4)));
1366 - (id)method2 __attribute__((availability(macos,introduced=10.4)));
1370 - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
1371 - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
1374 Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
1375 ``<os/availability.h>`` can simplify the spelling:
1377 .. code-block:: objc
1380 - (id)method API_AVAILABLE(macos(10.11)));
1381 - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
1384 Availability attributes can also be applied using a ``#pragma clang attribute``.
1385 Any explicit availability attribute whose platform corresponds to the target
1386 platform is applied to a declaration regardless of the availability attributes
1387 specified in the pragma. For example, in the code below,
1388 ``hasExplicitAvailabilityAttribute`` will use the ``macOS`` availability
1389 attribute that is specified with the declaration, whereas
1390 ``getsThePragmaAvailabilityAttribute`` will use the ``macOS`` availability
1391 attribute that is applied by the pragma.
1395 #pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function)
1396 void getsThePragmaAvailabilityAttribute(void);
1397 void hasExplicitAvailabilityAttribute(void) __attribute__((availability(macos,introduced=10.4)));
1398 #pragma clang attribute pop
1400 For platforms like ``watchOS`` and ``tvOS``, whose availability attributes can
1401 be implicitly inferred from an ``iOS`` availability attribute, the logic is
1402 slightly more complex. The explicit and the pragma-applied availability
1403 attributes whose platform corresponds to the target platform are applied as
1404 described in the previous paragraph. However, the implicitly inferred attributes
1405 are applied to a declaration only when there is no explicit or pragma-applied
1406 availability attribute whose platform corresponds to the target platform. For
1407 example, the function below will receive the ``tvOS`` availability from the
1408 pragma rather than using the inferred ``iOS`` availability from the declaration:
1412 #pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function)
1413 void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0)));
1414 #pragma clang attribute pop
1416 The compiler is also able to apply implicitly inferred attributes from a pragma
1417 as well. For example, when targeting ``tvOS``, the function below will receive
1418 a ``tvOS`` availability attribute that is implicitly inferred from the ``iOS``
1419 availability attribute applied by the pragma:
1423 #pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function)
1424 void infersTVOSAvailabilityFromPragma(void);
1425 #pragma clang attribute pop
1427 The implicit attributes that are inferred from explicitly specified attributes
1428 whose platform corresponds to the target platform are applied to the declaration
1429 even if there is an availability attribute that can be inferred from a pragma.
1430 For example, the function below will receive the ``tvOS, introduced=11.0``
1431 availability that is inferred from the attribute on the declaration rather than
1432 inferring availability from the pragma:
1436 #pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function)
1437 void infersTVOSAvailabilityFromAttributeNextToDeclaration(void)
1438 __attribute__((availability(iOS,introduced=11.0)));
1439 #pragma clang attribute pop
1441 Also see the documentation for `@available
1442 <http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_
1446 def ExternalSourceSymbolDocs : Documentation {
1447 let Category = DocCatDecl;
1449 The ``external_source_symbol`` attribute specifies that a declaration originates
1450 from an external source and describes the nature of that source.
1452 The fact that Clang is capable of recognizing declarations that were defined
1453 externally can be used to provide better tooling support for mixed-language
1454 projects or projects that rely on auto-generated code. For instance, an IDE that
1455 uses Clang and that supports mixed-language projects can use this attribute to
1456 provide a correct 'jump-to-definition' feature. For a concrete example,
1457 consider a protocol that's defined in a Swift file:
1459 .. code-block:: swift
1461 @objc public protocol SwiftProtocol {
1465 This protocol can be used from Objective-C code by including a header file that
1466 was generated by the Swift compiler. The declarations in that header can use
1467 the ``external_source_symbol`` attribute to make Clang aware of the fact
1468 that ``SwiftProtocol`` actually originates from a Swift module:
1470 .. code-block:: objc
1472 __attribute__((external_source_symbol(language="Swift",defined_in="module")))
1473 @protocol SwiftProtocol
1478 Consequently, when 'jump-to-definition' is performed at a location that
1479 references ``SwiftProtocol``, the IDE can jump to the original definition in
1480 the Swift source file rather than jumping to the Objective-C declaration in the
1481 auto-generated header file.
1483 The ``external_source_symbol`` attribute is a comma-separated list that includes
1484 clauses that describe the origin and the nature of the particular declaration.
1485 Those clauses can be:
1487 language=\ *string-literal*
1488 The name of the source language in which this declaration was defined.
1490 defined_in=\ *string-literal*
1491 The name of the source container in which the declaration was defined. The
1492 exact definition of source container is language-specific, e.g. Swift's
1493 source containers are modules, so ``defined_in`` should specify the Swift
1496 generated_declaration
1497 This declaration was automatically generated by some tool.
1499 The clauses can be specified in any order. The clauses that are listed above are
1500 all optional, but the attribute has to have at least one clause.
1504 def ConstInitDocs : Documentation {
1505 let Category = DocCatVariable;
1506 let Heading = "require_constant_initialization, constinit (C++20)";
1508 This attribute specifies that the variable to which it is attached is intended
1509 to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
1510 according to the rules of [basic.start.static]. The variable is required to
1511 have static or thread storage duration. If the initialization of the variable
1512 is not a constant initializer an error will be produced. This attribute may
1513 only be used in C++; the ``constinit`` spelling is only accepted in C++20
1516 Note that in C++03 strict constant expression checking is not done. Instead
1517 the attribute reports if Clang can emit the variable as a constant, even if it's
1518 not technically a 'constant initializer'. This behavior is non-portable.
1520 Static storage duration variables with constant initializers avoid hard-to-find
1521 bugs caused by the indeterminate order of dynamic initialization. They can also
1522 be safely used during dynamic initialization across translation units.
1524 This attribute acts as a compile time assertion that the requirements
1525 for constant initialization have been met. Since these requirements change
1526 between dialects and have subtle pitfalls it's important to fail fast instead
1527 of silently falling back on dynamic initialization.
1529 The first use of the attribute on a variable must be part of, or precede, the
1530 initializing declaration of the variable. C++20 requires the ``constinit``
1531 spelling of the attribute to be present on the initializing declaration if it
1532 is used anywhere. The other spellings can be specified on a forward declaration
1533 and omitted on a later initializing declaration.
1538 #define SAFE_STATIC [[clang::require_constant_initialization]]
1541 ~T(); // non-trivial
1543 SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
1544 SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
1545 // copy initialization is not a constant expression on a non-literal type.
1549 def WarnMaybeUnusedDocs : Documentation {
1550 let Category = DocCatVariable;
1551 let Heading = "maybe_unused, unused";
1553 When passing the ``-Wunused`` flag to Clang, entities that are unused by the
1554 program may be diagnosed. The ``[[maybe_unused]]`` (or
1555 ``__attribute__((unused))``) attribute can be used to silence such diagnostics
1556 when the entity cannot be removed. For instance, a local variable may exist
1557 solely for use in an ``assert()`` statement, which makes the local variable
1558 unused when ``NDEBUG`` is defined.
1560 The attribute may be applied to the declaration of a class, a typedef, a
1561 variable, a function or method, a function parameter, an enumeration, an
1562 enumerator, a non-static data member, or a label.
1567 [[maybe_unused]] void f([[maybe_unused]] bool thing1,
1568 [[maybe_unused]] bool thing2) {
1569 [[maybe_unused]] bool b = thing1 && thing2;
1575 def WarnUnusedResultsDocs : Documentation {
1576 let Category = DocCatFunction;
1577 let Heading = "nodiscard, warn_unused_result";
1579 Clang supports the ability to diagnose when the results of a function call
1580 expression are discarded under suspicious circumstances. A diagnostic is
1581 generated when a function or its return type is marked with ``[[nodiscard]]``
1582 (or ``__attribute__((warn_unused_result))``) and the function call appears as a
1583 potentially-evaluated discarded-value expression that is not explicitly cast to
1586 A string literal may optionally be provided to the attribute, which will be
1587 reproduced in any resulting diagnostics. Redeclarations using different forms
1588 of the attribute (with or without the string literal or with different string
1589 literal contents) are allowed. If there are redeclarations of the entity with
1590 differing string literals, it is unspecified which one will be used by Clang
1591 in any resulting diagnostics.
1594 struct [[nodiscard]] error_info { /*...*/ };
1595 error_info enable_missile_safety_mode();
1597 void launch_missiles();
1598 void test_missiles() {
1599 enable_missile_safety_mode(); // diagnoses
1603 void f() { foo(); } // Does not diagnose, error_info is a reference.
1605 Additionally, discarded temporaries resulting from a call to a constructor
1606 marked with ``[[nodiscard]]`` or a constructor of a type marked
1607 ``[[nodiscard]]`` will also diagnose. This also applies to type conversions that
1608 use the annotated ``[[nodiscard]]`` constructor or result in an annotated type.
1611 struct [[nodiscard]] marked_type {/*..*/ };
1612 struct marked_ctor {
1613 [[nodiscard]] marked_ctor();
1618 operator marked_type() const;
1619 [[nodiscard]] operator int() const;
1623 marked_type(); // diagnoses.
1624 marked_ctor(); // diagnoses.
1625 marked_ctor(3); // Does not diagnose, int constructor isn't marked nodiscard.
1628 static_cast<marked_type>(s); // diagnoses
1629 (int)s; // diagnoses
1634 def FallthroughDocs : Documentation {
1635 let Category = DocCatStmt;
1636 let Heading = "fallthrough";
1638 The ``fallthrough`` (or ``clang::fallthrough``) attribute is used
1639 to annotate intentional fall-through
1640 between switch labels. It can only be applied to a null statement placed at a
1641 point of execution between any statement and the next switch label. It is
1642 common to mark these places with a specific comment, but this attribute is
1643 meant to replace comments with a more strict annotation, which can be checked
1644 by the compiler. This attribute doesn't change semantics of the code and can
1645 be used wherever an intended fall-through occurs. It is designed to mimic
1646 control-flow statements like ``break;``, so it can be placed in most places
1647 where ``break;`` can, but only if there are no statements on the execution path
1648 between it and the next switch label.
1650 By default, Clang does not warn on unannotated fallthrough from one ``switch``
1651 case to another. Diagnostics on fallthrough without a corresponding annotation
1652 can be enabled with the ``-Wimplicit-fallthrough`` argument.
1658 // compile with -Wimplicit-fallthrough
1661 case 33: // no warning: no statements between case labels
1663 case 44: // warning: unannotated fall-through
1665 [[clang::fallthrough]];
1666 case 55: // no warning
1673 [[clang::fallthrough]];
1675 case 66: // no warning
1677 [[clang::fallthrough]]; // warning: fallthrough annotation does not
1678 // directly precede case label
1680 case 77: // warning: unannotated fall-through
1686 def ARMInterruptDocs : Documentation {
1687 let Category = DocCatFunction;
1688 let Heading = "interrupt (ARM)";
1690 Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
1691 ARM targets. This attribute may be attached to a function definition and
1692 instructs the backend to generate appropriate function entry/exit code so that
1693 it can be used directly as an interrupt service routine.
1695 The parameter passed to the interrupt attribute is optional, but if
1696 provided it must be a string literal with one of the following values: "IRQ",
1697 "FIQ", "SWI", "ABORT", "UNDEF".
1699 The semantics are as follows:
1701 - If the function is AAPCS, Clang instructs the backend to realign the stack to
1702 8 bytes on entry. This is a general requirement of the AAPCS at public
1703 interfaces, but may not hold when an exception is taken. Doing this allows
1704 other AAPCS functions to be called.
1705 - If the CPU is M-class this is all that needs to be done since the architecture
1706 itself is designed in such a way that functions obeying the normal AAPCS ABI
1707 constraints are valid exception handlers.
1708 - If the CPU is not M-class, the prologue and epilogue are modified to save all
1709 non-banked registers that are used, so that upon return the user-mode state
1710 will not be corrupted. Note that to avoid unnecessary overhead, only
1711 general-purpose (integer) registers are saved in this way. If VFP operations
1712 are needed, that state must be saved manually.
1714 Specifically, interrupt kinds other than "FIQ" will save all core registers
1715 except "lr" and "sp". "FIQ" interrupts will save r0-r7.
1716 - If the CPU is not M-class, the return instruction is changed to one of the
1717 canonical sequences permitted by the architecture for exception return. Where
1718 possible the function itself will make the necessary "lr" adjustments so that
1719 the "preferred return address" is selected.
1721 Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
1722 handler, where the offset from "lr" to the preferred return address depends on
1723 the execution state of the code which generated the exception. In this case
1724 a sequence equivalent to "movs pc, lr" will be used.
1728 def BPFPreserveAccessIndexDocs : Documentation {
1729 let Category = DocCatFunction;
1731 Clang supports the ``__attribute__((preserve_access_index))``
1732 attribute for the BPF target. This attribute may be attached to a
1733 struct or union declaration, where if -g is specified, it enables
1734 preserving struct or union member access debuginfo indices of this
1735 struct or union, similar to clang ``__builtin_preserve_acceess_index()``.
1739 def MipsInterruptDocs : Documentation {
1740 let Category = DocCatFunction;
1741 let Heading = "interrupt (MIPS)";
1743 Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` attribute on
1744 MIPS targets. This attribute may be attached to a function definition and instructs
1745 the backend to generate appropriate function entry/exit code so that it can be used
1746 directly as an interrupt service routine.
1748 By default, the compiler will produce a function prologue and epilogue suitable for
1749 an interrupt service routine that handles an External Interrupt Controller (eic)
1750 generated interrupt. This behavior can be explicitly requested with the "eic"
1753 Otherwise, for use with vectored interrupt mode, the argument passed should be
1754 of the form "vector=LEVEL" where LEVEL is one of the following values:
1755 "sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will
1756 then set the interrupt mask to the corresponding level which will mask all
1757 interrupts up to and including the argument.
1759 The semantics are as follows:
1761 - The prologue is modified so that the Exception Program Counter (EPC) and
1762 Status coprocessor registers are saved to the stack. The interrupt mask is
1763 set so that the function can only be interrupted by a higher priority
1764 interrupt. The epilogue will restore the previous values of EPC and Status.
1766 - The prologue and epilogue are modified to save and restore all non-kernel
1767 registers as necessary.
1769 - The FPU is disabled in the prologue, as the floating pointer registers are not
1770 spilled to the stack.
1772 - The function return sequence is changed to use an exception return instruction.
1774 - The parameter sets the interrupt mask for the function corresponding to the
1775 interrupt level specified. If no mask is specified the interrupt mask
1780 def MicroMipsDocs : Documentation {
1781 let Category = DocCatFunction;
1783 Clang supports the GNU style ``__attribute__((micromips))`` and
1784 ``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
1785 may be attached to a function definition and instructs the backend to generate
1786 or not to generate microMIPS code for that function.
1788 These attributes override the ``-mmicromips`` and ``-mno-micromips`` options
1789 on the command line.
1793 def MipsLongCallStyleDocs : Documentation {
1794 let Category = DocCatFunction;
1795 let Heading = "long_call, far";
1797 Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
1798 and ``__attribute__((near))`` attributes on MIPS targets. These attributes may
1799 only be added to function declarations and change the code generated
1800 by the compiler when directly calling the function. The ``near`` attribute
1801 allows calls to the function to be made using the ``jal`` instruction, which
1802 requires the function to be located in the same naturally aligned 256MB
1803 segment as the caller. The ``long_call`` and ``far`` attributes are synonyms
1804 and require the use of a different call sequence that works regardless
1805 of the distance between the functions.
1807 These attributes have no effect for position-independent code.
1809 These attributes take priority over command line switches such
1810 as ``-mlong-calls`` and ``-mno-long-calls``.
1814 def MipsShortCallStyleDocs : Documentation {
1815 let Category = DocCatFunction;
1816 let Heading = "short_call, near";
1818 Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
1819 ``__attribute__((short__call))``, and ``__attribute__((near))`` attributes
1820 on MIPS targets. These attributes may only be added to function declarations
1821 and change the code generated by the compiler when directly calling
1822 the function. The ``short_call`` and ``near`` attributes are synonyms and
1823 allow calls to the function to be made using the ``jal`` instruction, which
1824 requires the function to be located in the same naturally aligned 256MB segment
1825 as the caller. The ``long_call`` and ``far`` attributes are synonyms and
1826 require the use of a different call sequence that works regardless
1827 of the distance between the functions.
1829 These attributes have no effect for position-independent code.
1831 These attributes take priority over command line switches such
1832 as ``-mlong-calls`` and ``-mno-long-calls``.
1836 def RISCVInterruptDocs : Documentation {
1837 let Category = DocCatFunction;
1838 let Heading = "interrupt (RISCV)";
1840 Clang supports the GNU style ``__attribute__((interrupt))`` attribute on RISCV
1841 targets. This attribute may be attached to a function definition and instructs
1842 the backend to generate appropriate function entry/exit code so that it can be
1843 used directly as an interrupt service routine.
1845 Permissible values for this parameter are ``user``, ``supervisor``,
1846 and ``machine``. If there is no parameter, then it defaults to machine.
1848 Repeated interrupt attribute on the same declaration will cause a warning
1849 to be emitted. In case of repeated declarations, the last one prevails.
1852 https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html
1853 https://riscv.org/specifications/privileged-isa/
1854 The RISC-V Instruction Set Manual Volume II: Privileged Architecture
1859 def AVRInterruptDocs : Documentation {
1860 let Category = DocCatFunction;
1861 let Heading = "interrupt (AVR)";
1863 Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
1864 AVR targets. This attribute may be attached to a function definition and instructs
1865 the backend to generate appropriate function entry/exit code so that it can be used
1866 directly as an interrupt service routine.
1868 On the AVR, the hardware globally disables interrupts when an interrupt is executed.
1869 The first instruction of an interrupt handler declared with this attribute is a SEI
1870 instruction to re-enable interrupts. See also the signal attribute that
1871 does not insert a SEI instruction.
1875 def AVRSignalDocs : Documentation {
1876 let Category = DocCatFunction;
1878 Clang supports the GNU style ``__attribute__((signal))`` attribute on
1879 AVR targets. This attribute may be attached to a function definition and instructs
1880 the backend to generate appropriate function entry/exit code so that it can be used
1881 directly as an interrupt service routine.
1883 Interrupt handler functions defined with the signal attribute do not re-enable interrupts.
1887 def TargetDocs : Documentation {
1888 let Category = DocCatFunction;
1890 Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` attribute.
1891 This attribute may be attached to a function definition and instructs
1892 the backend to use different code generation options than were passed on the
1895 The current set of options correspond to the existing "subtarget features" for
1896 the target with or without a "-mno-" in front corresponding to the absence
1897 of the feature, as well as ``arch="CPU"`` which will change the default "CPU"
1900 For AArch64, the attribute also allows the "branch-protection=<args>" option,
1901 where the permissible arguments and their effect on code generation are the same
1902 as for the command-line option ``-mbranch-protection``.
1904 Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
1905 "avx", "xop" and largely correspond to the machine specific options handled by
1908 Additionally, this attribute supports function multiversioning for ELF based
1909 x86/x86-64 targets, which can be used to create multiple implementations of the
1910 same function that will be resolved at runtime based on the priority of their
1911 ``target`` attribute strings. A function is considered a multiversioned function
1912 if either two declarations of the function have different ``target`` attribute
1913 strings, or if it has a ``target`` attribute string of ``default``. For
1918 __attribute__((target("arch=atom")))
1919 void foo() {} // will be called on 'atom' processors.
1920 __attribute__((target("default")))
1921 void foo() {} // will be called on any other processors.
1923 All multiversioned functions must contain a ``default`` (fallback)
1924 implementation, otherwise usages of the function are considered invalid.
1925 Additionally, a function may not become multiversioned after its first use.
1929 def MinVectorWidthDocs : Documentation {
1930 let Category = DocCatFunction;
1932 Clang supports the ``__attribute__((min_vector_width(width)))`` attribute. This
1933 attribute may be attached to a function and informs the backend that this
1934 function desires vectors of at least this width to be generated. Target-specific
1935 maximum vector widths still apply. This means even if you ask for something
1936 larger than the target supports, you will only get what the target supports.
1937 This attribute is meant to be a hint to control target heuristics that may
1938 generate narrower vectors than what the target hardware supports.
1940 This is currently used by the X86 target to allow some CPUs that support 512-bit
1941 vectors to be limited to using 256-bit vectors to avoid frequency penalties.
1942 This is currently enabled with the ``-prefer-vector-width=256`` command line
1943 option. The ``min_vector_width`` attribute can be used to prevent the backend
1944 from trying to split vector operations to match the ``prefer-vector-width``. All
1945 X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
1946 use of any of the X86-specific vector builtins will implicitly set this
1947 attribute on the calling function. The intent is that explicitly writing vector
1948 code using the X86 intrinsics will prevent ``prefer-vector-width`` from
1953 def DocCatAMDGPUAttributes : DocumentationCategory<"AMD GPU Attributes">;
1955 def AMDGPUFlatWorkGroupSizeDocs : Documentation {
1956 let Category = DocCatAMDGPUAttributes;
1958 The flat work-group size is the number of work-items in the work-group size
1959 specified when the kernel is dispatched. It is the product of the sizes of the
1960 x, y, and z dimension of the work-group.
1963 ``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the
1964 AMDGPU target. This attribute may be attached to a kernel function definition
1965 and is an optimization hint.
1967 ``<min>`` parameter specifies the minimum flat work-group size, and ``<max>``
1968 parameter specifies the maximum flat work-group size (must be greater than
1969 ``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0``
1970 as ``<min>, <max>`` implies the default behavior (``128, 256``).
1972 If specified, the AMDGPU target backend might be able to produce better machine
1973 code for barriers and perform scratch promotion by estimating available group
1976 An error will be given if:
1977 - Specified values violate subtarget specifications;
1978 - Specified values are not compatible with values provided through other
1983 def AMDGPUWavesPerEUDocs : Documentation {
1984 let Category = DocCatAMDGPUAttributes;
1986 A compute unit (CU) is responsible for executing the wavefronts of a work-group.
1987 It is composed of one or more execution units (EU), which are responsible for
1988 executing the wavefronts. An EU can have enough resources to maintain the state
1989 of more than one executing wavefront. This allows an EU to hide latency by
1990 switching between wavefronts in a similar way to symmetric multithreading on a
1991 CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
1992 resources used by a single wavefront have to be limited. For example, the number
1993 of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
1994 but can result in having to spill some register state to memory.
1996 Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))``
1997 attribute for the AMDGPU target. This attribute may be attached to a kernel
1998 function definition and is an optimization hint.
2000 ``<min>`` parameter specifies the requested minimum number of waves per EU, and
2001 *optional* ``<max>`` parameter specifies the requested maximum number of waves
2002 per EU (must be greater than ``<min>`` if specified). If ``<max>`` is omitted,
2003 then there is no restriction on the maximum number of waves per EU other than
2004 the one dictated by the hardware for which the kernel is compiled. Passing
2005 ``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits).
2007 If specified, this attribute allows an advanced developer to tune the number of
2008 wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
2009 target backend can use this information to limit resources, such as number of
2010 SGPRs, number of VGPRs, size of available group and private memory segments, in
2011 such a way that guarantees that at least ``<min>`` wavefronts and at most
2012 ``<max>`` wavefronts are able to fit within the resources of an EU. Requesting
2013 more wavefronts can hide memory latency but limits available registers which
2014 can result in spilling. Requesting fewer wavefronts can help reduce cache
2015 thrashing, but can reduce memory latency hiding.
2017 This attribute controls the machine code generated by the AMDGPU target backend
2018 to ensure it is capable of meeting the requested values. However, when the
2019 kernel is executed, there may be other reasons that prevent meeting the request,
2020 for example, there may be wavefronts from other kernels executing on the EU.
2022 An error will be given if:
2023 - Specified values violate subtarget specifications;
2024 - Specified values are not compatible with values provided through other
2026 - The AMDGPU target backend is unable to create machine code that can meet the
2031 def AMDGPUNumSGPRNumVGPRDocs : Documentation {
2032 let Category = DocCatAMDGPUAttributes;
2034 Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
2035 ``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
2036 target. These attributes may be attached to a kernel function definition and are
2037 an optimization hint.
2039 If these attributes are specified, then the AMDGPU target backend will attempt
2040 to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
2041 number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
2042 allocation requirements or constraints of the subtarget. Passing ``0`` as
2043 ``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
2045 These attributes can be used to test the AMDGPU target backend. It is
2046 recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
2047 resources such as SGPRs and VGPRs since it is aware of the limits for different
2050 An error will be given if:
2051 - Specified values violate subtarget specifications;
2052 - Specified values are not compatible with values provided through other
2054 - The AMDGPU target backend is unable to create machine code that can meet the
2059 def DocCatCallingConvs : DocumentationCategory<"Calling Conventions"> {
2061 Clang supports several different calling conventions, depending on the target
2062 platform and architecture. The calling convention used for a function determines
2063 how parameters are passed, how results are returned to the caller, and other
2064 low-level details of calling a function.
2068 def PcsDocs : Documentation {
2069 let Category = DocCatCallingConvs;
2071 On ARM targets, this attribute can be used to select calling conventions
2072 similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and
2077 def AArch64VectorPcsDocs : Documentation {
2078 let Category = DocCatCallingConvs;
2080 On AArch64 targets, this attribute changes the calling convention of a
2081 function to preserve additional floating-point and Advanced SIMD registers
2082 relative to the default calling convention used for AArch64.
2084 This means it is more efficient to call such functions from code that performs
2085 extensive floating-point and vector calculations, because fewer live SIMD and FP
2086 registers need to be saved. This property makes it well-suited for e.g.
2087 floating-point or vector math library functions, which are typically leaf
2088 functions that require a small number of registers.
2090 However, using this attribute also means that it is more expensive to call
2091 a function that adheres to the default calling convention from within such
2092 a function. Therefore, it is recommended that this attribute is only used
2095 For more information, see the documentation for `aarch64_vector_pcs`_ on
2096 the Arm Developer website.
2098 .. _`aarch64_vector_pcs`: https://developer.arm.com/products/software-development-tools/hpc/arm-compiler-for-hpc/vector-function-abi
2102 def RegparmDocs : Documentation {
2103 let Category = DocCatCallingConvs;
2105 On 32-bit x86 targets, the regparm attribute causes the compiler to pass
2106 the first three integer parameters in EAX, EDX, and ECX instead of on the
2107 stack. This attribute has no effect on variadic functions, and all parameters
2108 are passed via the stack as normal.
2112 def SysVABIDocs : Documentation {
2113 let Category = DocCatCallingConvs;
2115 On Windows x86_64 targets, this attribute changes the calling convention of a
2116 function to match the default convention used on Sys V targets such as Linux,
2117 Mac, and BSD. This attribute has no effect on other targets.
2121 def MSABIDocs : Documentation {
2122 let Category = DocCatCallingConvs;
2124 On non-Windows x86_64 targets, this attribute changes the calling convention of
2125 a function to match the default convention used on Windows x86_64. This
2126 attribute has no effect on Windows targets or non-x86_64 targets.
2130 def StdCallDocs : Documentation {
2131 let Category = DocCatCallingConvs;
2133 On 32-bit x86 targets, this attribute changes the calling convention of a
2134 function to clear parameters off of the stack on return. This convention does
2135 not support variadic calls or unprototyped functions in C, and has no effect on
2136 x86_64 targets. This calling convention is used widely by the Windows API and
2137 COM applications. See the documentation for `__stdcall`_ on MSDN.
2139 .. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx
2143 def FastCallDocs : Documentation {
2144 let Category = DocCatCallingConvs;
2146 On 32-bit x86 targets, this attribute changes the calling convention of a
2147 function to use ECX and EDX as register parameters and clear parameters off of
2148 the stack on return. This convention does not support variadic calls or
2149 unprototyped functions in C, and has no effect on x86_64 targets. This calling
2150 convention is supported primarily for compatibility with existing code. Users
2151 seeking register parameters should use the ``regparm`` attribute, which does
2152 not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN.
2154 .. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx
2158 def RegCallDocs : Documentation {
2159 let Category = DocCatCallingConvs;
2161 On x86 targets, this attribute changes the calling convention to
2162 `__regcall`_ convention. This convention aims to pass as many arguments
2163 as possible in registers. It also tries to utilize registers for the
2164 return value whenever it is possible.
2166 .. _`__regcall`: https://software.intel.com/en-us/node/693069
2170 def ThisCallDocs : Documentation {
2171 let Category = DocCatCallingConvs;
2173 On 32-bit x86 targets, this attribute changes the calling convention of a
2174 function to use ECX for the first parameter (typically the implicit ``this``
2175 parameter of C++ methods) and clear parameters off of the stack on return. This
2176 convention does not support variadic calls or unprototyped functions in C, and
2177 has no effect on x86_64 targets. See the documentation for `__thiscall`_ on
2180 .. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx
2184 def VectorCallDocs : Documentation {
2185 let Category = DocCatCallingConvs;
2187 On 32-bit x86 *and* x86_64 targets, this attribute changes the calling
2188 convention of a function to pass vector parameters in SSE registers.
2190 On 32-bit x86 targets, this calling convention is similar to ``__fastcall``.
2191 The first two integer parameters are passed in ECX and EDX. Subsequent integer
2192 parameters are passed in memory, and callee clears the stack. On x86_64
2193 targets, the callee does *not* clear the stack, and integer parameters are
2194 passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
2197 On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
2198 passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
2199 passed in sequential SSE registers if enough are available. If AVX is enabled,
2200 256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
2201 cannot be passed in registers for any reason is passed by reference, which
2202 allows the caller to align the parameter memory.
2204 See the documentation for `__vectorcall`_ on MSDN for more details.
2206 .. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx
2210 def DocCatConsumed : DocumentationCategory<"Consumed Annotation Checking"> {
2212 Clang supports additional attributes for checking basic resource management
2213 properties, specifically for unique objects that have a single owning reference.
2214 The following attributes are currently supported, although **the implementation
2215 for these annotations is currently in development and are subject to change.**
2219 def SetTypestateDocs : Documentation {
2220 let Category = DocCatConsumed;
2222 Annotate methods that transition an object into a new state with
2223 ``__attribute__((set_typestate(new_state)))``. The new state must be
2224 unconsumed, consumed, or unknown.
2228 def CallableWhenDocs : Documentation {
2229 let Category = DocCatConsumed;
2231 Use ``__attribute__((callable_when(...)))`` to indicate what states a method
2232 may be called in. Valid states are unconsumed, consumed, or unknown. Each
2233 argument to this attribute must be a quoted string. E.g.:
2235 ``__attribute__((callable_when("unconsumed", "unknown")))``
2239 def TestTypestateDocs : Documentation {
2240 let Category = DocCatConsumed;
2242 Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
2243 returns true if the object is in the specified state..
2247 def ParamTypestateDocs : Documentation {
2248 let Category = DocCatConsumed;
2250 This attribute specifies expectations about function parameters. Calls to an
2251 function with annotated parameters will issue a warning if the corresponding
2252 argument isn't in the expected state. The attribute is also used to set the
2253 initial state of the parameter when analyzing the function's body.
2257 def ReturnTypestateDocs : Documentation {
2258 let Category = DocCatConsumed;
2260 The ``return_typestate`` attribute can be applied to functions or parameters.
2261 When applied to a function the attribute specifies the state of the returned
2262 value. The function's body is checked to ensure that it always returns a value
2263 in the specified state. On the caller side, values returned by the annotated
2264 function are initialized to the given state.
2266 When applied to a function parameter it modifies the state of an argument after
2267 a call to the function returns. The function's body is checked to ensure that
2268 the parameter is in the expected state before returning.
2272 def ConsumableDocs : Documentation {
2273 let Category = DocCatConsumed;
2275 Each ``class`` that uses any of the typestate annotations must first be marked
2276 using the ``consumable`` attribute. Failure to do so will result in a warning.
2278 This attribute accepts a single parameter that must be one of the following:
2279 ``unknown``, ``consumed``, or ``unconsumed``.
2283 def NoSanitizeDocs : Documentation {
2284 let Category = DocCatFunction;
2286 Use the ``no_sanitize`` attribute on a function or a global variable
2287 declaration to specify that a particular instrumentation or set of
2288 instrumentations should not be applied. The attribute takes a list of
2289 string literals, which have the same meaning as values accepted by the
2290 ``-fno-sanitize=`` flag. For example,
2291 ``__attribute__((no_sanitize("address", "thread")))`` specifies that
2292 AddressSanitizer and ThreadSanitizer should not be applied to the
2293 function or variable.
2295 See :ref:`Controlling Code Generation <controlling-code-generation>` for a
2296 full list of supported sanitizer flags.
2300 def NoSanitizeAddressDocs : Documentation {
2301 let Category = DocCatFunction;
2302 // This function has multiple distinct spellings, and so it requires a custom
2303 // heading to be specified. The most common spelling is sufficient.
2304 let Heading = "no_sanitize_address, no_address_safety_analysis";
2306 .. _langext-address_sanitizer:
2308 Use ``__attribute__((no_sanitize_address))`` on a function or a global
2309 variable declaration to specify that address safety instrumentation
2310 (e.g. AddressSanitizer) should not be applied.
2314 def NoSanitizeThreadDocs : Documentation {
2315 let Category = DocCatFunction;
2316 let Heading = "no_sanitize_thread";
2318 .. _langext-thread_sanitizer:
2320 Use ``__attribute__((no_sanitize_thread))`` on a function declaration to
2321 specify that checks for data races on plain (non-atomic) memory accesses should
2322 not be inserted by ThreadSanitizer. The function is still instrumented by the
2323 tool to avoid false positives and provide meaningful stack traces.
2327 def NoSanitizeMemoryDocs : Documentation {
2328 let Category = DocCatFunction;
2329 let Heading = "no_sanitize_memory";
2331 .. _langext-memory_sanitizer:
2333 Use ``__attribute__((no_sanitize_memory))`` on a function declaration to
2334 specify that checks for uninitialized memory should not be inserted
2335 (e.g. by MemorySanitizer). The function may still be instrumented by the tool
2336 to avoid false positives in other places.
2340 def CFICanonicalJumpTableDocs : Documentation {
2341 let Category = DocCatFunction;
2342 let Heading = "cfi_canonical_jump_table";
2344 .. _langext-cfi_canonical_jump_table:
2346 Use ``__attribute__((cfi_canonical_jump_table))`` on a function declaration to
2347 make the function's CFI jump table canonical. See :ref:`the CFI documentation
2348 <cfi-canonical-jump-tables>` for more details.
2352 def DocCatTypeSafety : DocumentationCategory<"Type Safety Checking"> {
2354 Clang supports additional attributes to enable checking type safety properties
2355 that can't be enforced by the C type system. To see warnings produced by these
2356 checks, ensure that -Wtype-safety is enabled. Use cases include:
2358 * MPI library implementations, where these attributes enable checking that
2359 the buffer type matches the passed ``MPI_Datatype``;
2360 * for HDF5 library there is a similar use case to MPI;
2361 * checking types of variadic functions' arguments for functions like
2362 ``fcntl()`` and ``ioctl()``.
2364 You can detect support for these attributes with ``__has_attribute()``. For
2369 #if defined(__has_attribute)
2370 # if __has_attribute(argument_with_type_tag) && \
2371 __has_attribute(pointer_with_type_tag) && \
2372 __has_attribute(type_tag_for_datatype)
2373 # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
2374 /* ... other macros ... */
2378 #if !defined(ATTR_MPI_PWT)
2379 # define ATTR_MPI_PWT(buffer_idx, type_idx)
2382 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
2387 def ArgumentWithTypeTagDocs : Documentation {
2388 let Category = DocCatTypeSafety;
2389 let Heading = "argument_with_type_tag";
2391 Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
2392 type_tag_idx)))`` on a function declaration to specify that the function
2393 accepts a type tag that determines the type of some other argument.
2395 This attribute is primarily useful for checking arguments of variadic functions
2396 (``pointer_with_type_tag`` can be used in most non-variadic cases).
2398 In the attribute prototype above:
2399 * ``arg_kind`` is an identifier that should be used when annotating all
2400 applicable type tags.
2401 * ``arg_idx`` provides the position of a function argument. The expected type of
2402 this function argument will be determined by the function argument specified
2403 by ``type_tag_idx``. In the code example below, "3" means that the type of the
2404 function's third argument will be determined by ``type_tag_idx``.
2405 * ``type_tag_idx`` provides the position of a function argument. This function
2406 argument will be a type tag. The type tag will determine the expected type of
2407 the argument specified by ``arg_idx``. In the code example below, "2" means
2408 that the type tag associated with the function's second argument should agree
2409 with the type of the argument specified by ``arg_idx``.
2415 int fcntl(int fd, int cmd, ...)
2416 __attribute__(( argument_with_type_tag(fcntl,3,2) ));
2417 // The function's second argument will be a type tag; this type tag will
2418 // determine the expected type of the function's third argument.
2422 def PointerWithTypeTagDocs : Documentation {
2423 let Category = DocCatTypeSafety;
2424 let Heading = "pointer_with_type_tag";
2426 Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
2427 on a function declaration to specify that the function accepts a type tag that
2428 determines the pointee type of some other pointer argument.
2430 In the attribute prototype above:
2431 * ``ptr_kind`` is an identifier that should be used when annotating all
2432 applicable type tags.
2433 * ``ptr_idx`` provides the position of a function argument; this function
2434 argument will have a pointer type. The expected pointee type of this pointer
2435 type will be determined by the function argument specified by
2436 ``type_tag_idx``. In the code example below, "1" means that the pointee type
2437 of the function's first argument will be determined by ``type_tag_idx``.
2438 * ``type_tag_idx`` provides the position of a function argument; this function
2439 argument will be a type tag. The type tag will determine the expected pointee
2440 type of the pointer argument specified by ``ptr_idx``. In the code example
2441 below, "3" means that the type tag associated with the function's third
2442 argument should agree with the pointee type of the pointer argument specified
2449 typedef int MPI_Datatype;
2450 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
2451 __attribute__(( pointer_with_type_tag(mpi,1,3) ));
2452 // The function's 3rd argument will be a type tag; this type tag will
2453 // determine the expected pointee type of the function's 1st argument.
2457 def TypeTagForDatatypeDocs : Documentation {
2458 let Category = DocCatTypeSafety;
2460 When declaring a variable, use
2461 ``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
2462 is tied to the ``type`` argument given to the attribute.
2464 In the attribute prototype above:
2465 * ``kind`` is an identifier that should be used when annotating all applicable
2467 * ``type`` indicates the name of the type.
2469 Clang supports annotating type tags of two forms.
2471 * **Type tag that is a reference to a declared identifier.**
2472 Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
2477 typedef int MPI_Datatype;
2478 extern struct mpi_datatype mpi_datatype_int
2479 __attribute__(( type_tag_for_datatype(mpi,int) ));
2480 #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
2481 // &mpi_datatype_int is a type tag. It is tied to type "int".
2483 * **Type tag that is an integral literal.**
2484 Declare a ``static const`` variable with an initializer value and attach
2485 ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
2489 typedef int MPI_Datatype;
2490 static const MPI_Datatype mpi_datatype_int
2491 __attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
2492 #define MPI_INT ((MPI_Datatype) 42)
2493 // The number 42 is a type tag. It is tied to type "int".
2496 The ``type_tag_for_datatype`` attribute also accepts an optional third argument
2497 that determines how the type of the function argument specified by either
2498 ``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
2499 tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
2500 function argument specified by ``arg_idx`` is compared against the type
2501 associated with the type tag. Also recall that for the ``pointer_with_type_tag``
2502 attribute, the pointee type of the function argument specified by ``ptr_idx`` is
2503 compared against the type associated with the type tag.) There are two supported
2504 values for this optional third argument:
2506 * ``layout_compatible`` will cause types to be compared according to
2507 layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
2508 layout-compatibility rules for two standard-layout struct types and for two
2509 standard-layout union types). This is useful when creating a type tag
2510 associated with a struct or union type. For example:
2515 typedef int MPI_Datatype;
2516 struct internal_mpi_double_int { double d; int i; };
2517 extern struct mpi_datatype mpi_datatype_double_int
2518 __attribute__(( type_tag_for_datatype(mpi,
2519 struct internal_mpi_double_int, layout_compatible) ));
2521 #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
2523 int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
2524 __attribute__(( pointer_with_type_tag(mpi,1,3) ));
2527 struct my_pair { double a; int b; };
2528 struct my_pair *buffer;
2529 MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning because the
2530 // layout of my_pair is
2531 // compatible with that of
2532 // internal_mpi_double_int
2534 struct my_int_pair { int a; int b; }
2535 struct my_int_pair *buffer2;
2536 MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning because the
2537 // layout of my_int_pair
2538 // does not match that of
2539 // internal_mpi_double_int
2541 * ``must_be_null`` specifies that the function argument specified by either
2542 ``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
2543 the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
2544 The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
2550 typedef int MPI_Datatype;
2551 extern struct mpi_datatype mpi_datatype_null
2552 __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
2554 #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
2555 int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
2556 __attribute__(( pointer_with_type_tag(mpi,1,3) ));
2559 struct my_pair { double a; int b; };
2560 struct my_pair *buffer;
2561 MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
2562 // was specified but buffer
2563 // is not a null pointer
2567 def FlattenDocs : Documentation {
2568 let Category = DocCatFunction;
2570 The ``flatten`` attribute causes calls within the attributed function to
2571 be inlined unless it is impossible to do so, for example if the body of the
2572 callee is unavailable or if the callee has the ``noinline`` attribute.
2576 def FormatDocs : Documentation {
2577 let Category = DocCatFunction;
2580 Clang supports the ``format`` attribute, which indicates that the function
2581 accepts a ``printf`` or ``scanf``-like format string and corresponding
2582 arguments or a ``va_list`` that contains these arguments.
2584 Please see `GCC documentation about format attribute
2585 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
2586 about attribute syntax.
2588 Clang implements two kinds of checks with this attribute.
2590 #. Clang checks that the function with the ``format`` attribute is called with
2591 a format string that uses format specifiers that are allowed, and that
2592 arguments match the format string. This is the ``-Wformat`` warning, it is
2595 #. Clang checks that the format string argument is a literal string. This is
2596 the ``-Wformat-nonliteral`` warning, it is off by default.
2598 Clang implements this mostly the same way as GCC, but there is a difference
2599 for functions that accept a ``va_list`` argument (for example, ``vprintf``).
2600 GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
2601 functions. Clang does not warn if the format string comes from a function
2602 parameter, where the function is annotated with a compatible attribute,
2603 otherwise it warns. For example:
2607 __attribute__((__format__ (__scanf__, 1, 3)))
2608 void foo(const char* s, char *buf, ...) {
2612 vprintf(s, ap); // warning: format string is not a string literal
2615 In this case we warn because ``s`` contains a format string for a
2616 ``scanf``-like function, but it is passed to a ``printf``-like function.
2618 If the attribute is removed, clang still warns, because the format string is
2619 not a string literal.
2625 __attribute__((__format__ (__printf__, 1, 3)))
2626 void foo(const char* s, char *buf, ...) {
2630 vprintf(s, ap); // warning
2633 In this case Clang does not warn because the format string ``s`` and
2634 the corresponding arguments are annotated. If the arguments are
2635 incorrect, the caller of ``foo`` will receive a warning.
2639 def AlignValueDocs : Documentation {
2640 let Category = DocCatType;
2642 The align_value attribute can be added to the typedef of a pointer type or the
2643 declaration of a variable of pointer or reference type. It specifies that the
2644 pointer will point to, or the reference will bind to, only objects with at
2645 least the provided alignment. This alignment value must be some positive power
2650 typedef double * aligned_double_ptr __attribute__((align_value(64)));
2651 void foo(double & x __attribute__((align_value(128)),
2652 aligned_double_ptr y) { ... }
2654 If the pointer value does not have the specified alignment at runtime, the
2655 behavior of the program is undefined.
2659 def FlagEnumDocs : Documentation {
2660 let Category = DocCatDecl;
2662 This attribute can be added to an enumerator to signal to the compiler that it
2663 is intended to be used as a flag type. This will cause the compiler to assume
2664 that the range of the type includes all of the values that you can get by
2665 manipulating bits of the enumerator when issuing warnings.
2669 def AsmLabelDocs : Documentation {
2670 let Category = DocCatDecl;
2672 This attribute can be used on a function or variable to specify its symbol name.
2674 On some targets, all C symbols are prefixed by default with a single character, typically ``_``. This was done historically to distinguish them from symbols used by other languages. (This prefix is also added to the standard Itanium C++ ABI prefix on "mangled" symbol names, so that e.g. on such targets the true symbol name for a C++ variable declared as ``int cppvar;`` would be ``__Z6cppvar``; note the two underscores.) This prefix is *not* added to the symbol names specified by the ``asm`` attribute; programmers wishing to match a C symbol name must compensate for this.
2676 For example, consider the following C code:
2680 int var1 asm("altvar") = 1; // "altvar" in symbol table.
2681 int var2 = 1; // "_var2" in symbol table.
2683 void func1(void) asm("altfunc");
2684 void func1(void) {} // "altfunc" in symbol table.
2685 void func2(void) {} // "_func2" in symbol table.
2687 Clang's implementation of this attribute is compatible with GCC's, `documented here <https://gcc.gnu.org/onlinedocs/gcc/Asm-Labels.html>`_.
2689 While it is possible to use this attribute to name a special symbol used internally by the compiler, such as an LLVM intrinsic, this is neither recommended nor supported and may cause the compiler to crash or miscompile. Users who wish to gain access to intrinsic behavior are strongly encouraged to request new builtin functions.
2693 def EnumExtensibilityDocs : Documentation {
2694 let Category = DocCatDecl;
2696 Attribute ``enum_extensibility`` is used to distinguish between enum definitions
2697 that are extensible and those that are not. The attribute can take either
2698 ``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the
2699 enum type takes a value that corresponds to one of the enumerators listed in the
2700 enum definition or, when the enum is annotated with ``flag_enum``, a value that
2701 can be constructed using values corresponding to the enumerators. ``open``
2702 indicates a variable of the enum type can take any values allowed by the
2703 standard and instructs clang to be more lenient when issuing warnings.
2707 enum __attribute__((enum_extensibility(closed))) ClosedEnum {
2711 enum __attribute__((enum_extensibility(open))) OpenEnum {
2715 enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
2716 C0 = 1 << 0, C1 = 1 << 1
2719 enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
2720 D0 = 1 << 0, D1 = 1 << 1
2726 enum ClosedFlagEnum cfe;
2727 enum OpenFlagEnum ofe;
2729 ce = A1; // no warnings
2730 ce = 100; // warning issued
2731 oe = B1; // no warnings
2732 oe = 100; // no warnings
2733 cfe = C0 | C1; // no warnings
2734 cfe = C0 | C1 | 4; // warning issued
2735 ofe = D0 | D1; // no warnings
2736 ofe = D0 | D1 | 4; // no warnings
2742 def EmptyBasesDocs : Documentation {
2743 let Category = DocCatDecl;
2745 The empty_bases attribute permits the compiler to utilize the
2746 empty-base-optimization more frequently.
2747 This attribute only applies to struct, class, and union types.
2748 It is only supported when using the Microsoft C++ ABI.
2752 def LayoutVersionDocs : Documentation {
2753 let Category = DocCatDecl;
2755 The layout_version attribute requests that the compiler utilize the class
2756 layout rules of a particular compiler version.
2757 This attribute only applies to struct, class, and union types.
2758 It is only supported when using the Microsoft C++ ABI.
2762 def LifetimeBoundDocs : Documentation {
2763 let Category = DocCatFunction;
2765 The ``lifetimebound`` attribute indicates that a resource owned by
2766 a function parameter or implicit object parameter
2767 is retained by the return value of the annotated function
2768 (or, for a parameter of a constructor, in the value of the constructed object).
2769 It is only supported in C++.
2771 This attribute provides an experimental implementation of the facility
2772 described in the C++ committee paper `P0936R0 <http://wg21.link/p0936r0>`_,
2773 and is subject to change as the design of the corresponding functionality
2778 def TrivialABIDocs : Documentation {
2779 let Category = DocCatDecl;
2781 The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
2782 It instructs the compiler to pass and return the type using the C ABI for the
2783 underlying type when the type would otherwise be considered non-trivial for the
2785 A class annotated with ``trivial_abi`` can have non-trivial destructors or
2786 copy/move constructors without automatically becoming non-trivial for the
2787 purposes of calls. For example:
2791 // A is trivial for the purposes of calls because ``trivial_abi`` makes the
2792 // user-provided special functions trivial.
2793 struct __attribute__((trivial_abi)) A {
2800 // B's destructor and copy/move constructor are considered trivial for the
2801 // purpose of calls because A is trivial.
2806 If a type is trivial for the purposes of calls, has a non-trivial destructor,
2807 and is passed as an argument by value, the convention is that the callee will
2808 destroy the object before returning.
2810 Attribute ``trivial_abi`` has no effect in the following cases:
2812 - The class directly declares a virtual base or virtual methods.
2813 - Copy constructors and move constructors of the class are all deleted.
2814 - The class has a base class that is non-trivial for the purposes of calls.
2815 - The class has a non-static data member whose type is non-trivial for the purposes of calls, which includes:
2817 - classes that are non-trivial for the purposes of calls
2818 - __weak-qualified types in Objective-C++
2819 - arrays of any of the above
2823 def MSInheritanceDocs : Documentation {
2824 let Category = DocCatDecl;
2825 let Heading = "__single_inhertiance, __multiple_inheritance, __virtual_inheritance";
2827 This collection of keywords is enabled under ``-fms-extensions`` and controls
2828 the pointer-to-member representation used on ``*-*-win32`` targets.
2830 The ``*-*-win32`` targets utilize a pointer-to-member representation which
2831 varies in size and alignment depending on the definition of the underlying
2834 However, this is problematic when a forward declaration is only available and
2835 no definition has been made yet. In such cases, Clang is forced to utilize the
2836 most general representation that is available to it.
2838 These keywords make it possible to use a pointer-to-member representation other
2839 than the most general one regardless of whether or not the definition will ever
2840 be present in the current translation unit.
2842 This family of keywords belong between the ``class-key`` and ``class-name``:
2846 struct __single_inheritance S;
2850 This keyword can be applied to class templates but only has an effect when used
2851 on full specializations:
2855 template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
2856 template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
2857 template <> struct __single_inheritance A<int, float>;
2859 Note that choosing an inheritance model less general than strictly necessary is
2864 struct __multiple_inheritance S; // error: inheritance model does not match definition
2870 def MSNoVTableDocs : Documentation {
2871 let Category = DocCatDecl;
2873 This attribute can be added to a class declaration or definition to signal to
2874 the compiler that constructors and destructors will not reference the virtual
2875 function table. It is only supported when using the Microsoft C++ ABI.
2879 def OptnoneDocs : Documentation {
2880 let Category = DocCatFunction;
2882 The ``optnone`` attribute suppresses essentially all optimizations
2883 on a function or method, regardless of the optimization level applied to
2884 the compilation unit as a whole. This is particularly useful when you
2885 need to debug a particular function, but it is infeasible to build the
2886 entire application without optimization. Avoiding optimization on the
2887 specified function can improve the quality of the debugging information
2890 This attribute is incompatible with the ``always_inline`` and ``minsize``
2895 def LoopHintDocs : Documentation {
2896 let Category = DocCatStmt;
2897 let Heading = "#pragma clang loop";
2899 The ``#pragma clang loop`` directive allows loop optimization hints to be
2900 specified for the subsequent loop. The directive allows pipelining to be
2901 disabled, or vectorization, vector predication, interleaving, and unrolling to
2902 be enabled or disabled. Vector width, vector predication, interleave count,
2903 unrolling count, and the initiation interval for pipelining can be explicitly
2904 specified. See `language extensions
2905 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
2910 def UnrollHintDocs : Documentation {
2911 let Category = DocCatStmt;
2912 let Heading = "#pragma unroll, #pragma nounroll";
2914 Loop unrolling optimization hints can be specified with ``#pragma unroll`` and
2915 ``#pragma nounroll``. The pragma is placed immediately before a for, while,
2916 do-while, or c++11 range-based for loop.
2918 Specifying ``#pragma unroll`` without a parameter directs the loop unroller to
2919 attempt to fully unroll the loop if the trip count is known at compile time and
2920 attempt to partially unroll the loop if the trip count is not known at compile
2930 Specifying the optional parameter, ``#pragma unroll _value_``, directs the
2931 unroller to unroll the loop ``_value_`` times. The parameter may optionally be
2932 enclosed in parentheses:
2946 Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled:
2955 ``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to
2956 ``#pragma clang loop unroll(full)`` and
2957 ``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll``
2958 is equivalent to ``#pragma clang loop unroll(disable)``. See
2959 `language extensions
2960 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
2961 for further details including limitations of the unroll hints.
2965 def PipelineHintDocs : Documentation {
2966 let Category = DocCatStmt;
2967 let Heading = "#pragma clang loop pipeline, #pragma clang loop pipeline_initiation_interval";
2969 Software Pipelining optimization is a technique used to optimize loops by
2970 utilizing instruction-level parallelism. It reorders loop instructions to
2971 overlap iterations. As a result, the next iteration starts before the previous
2972 iteration has finished. The module scheduling technique creates a schedule for
2973 one iteration such that when repeating at regular intervals, no inter-iteration
2974 dependencies are violated. This constant interval(in cycles) between the start
2975 of iterations is called the initiation interval. i.e. The initiation interval
2976 is the number of cycles between two iterations of an unoptimized loop in the
2977 newly created schedule. A new, optimized loop is created such that a single iteration
2978 of the loop executes in the same number of cycles as the initiation interval.
2979 For further details see <https://llvm.org/pubs/2005-06-17-LattnerMSThesis-book.pdf>.
2981 ``#pragma clang loop pipeline and #pragma loop pipeline_initiation_interval``
2982 could be used as hints for the software pipelining optimization. The pragma is
2983 placed immediately before a for, while, do-while, or a C++11 range-based for
2986 Using ``#pragma clang loop pipeline(disable)`` avoids the software pipelining
2987 optimization. The disable state can only be specified:
2991 #pragma clang loop pipeline(disable)
2996 Using ``#pragma loop pipeline_initiation_interval`` instructs
2997 the software pipeliner to try the specified initiation interval.
2998 If a schedule was found then the resulting loop iteration would have
2999 the specified cycle count. If a schedule was not found then loop
3000 remains unchanged. The initiation interval must be a positive number
3005 #pragma loop pipeline_initiation_interval(10)
3013 def OpenCLUnrollHintDocs : Documentation {
3014 let Category = DocCatStmt;
3016 The opencl_unroll_hint attribute qualifier can be used to specify that a loop
3017 (for, while and do loops) can be unrolled. This attribute qualifier can be
3018 used to specify full unrolling or partial unrolling by a specified amount.
3019 This is a compiler hint and the compiler may ignore this directive. See
3020 `OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_
3021 s6.11.5 for details.
3025 def OpenCLIntelReqdSubGroupSizeDocs : Documentation {
3026 let Category = DocCatStmt;
3028 The optional attribute intel_reqd_sub_group_size can be used to indicate that
3029 the kernel must be compiled and executed with the specified subgroup size. When
3030 this attribute is present, get_max_sub_group_size() is guaranteed to return the
3031 specified integer value. This is important for the correctness of many subgroup
3032 algorithms, and in some cases may be used by the compiler to generate more optimal
3033 code. See `cl_intel_required_subgroup_size
3034 <https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>`
3039 def OpenCLAccessDocs : Documentation {
3040 let Category = DocCatStmt;
3041 let Heading = "__read_only, __write_only, __read_write (read_only, write_only, read_write)";
3043 The access qualifiers must be used with image object arguments or pipe arguments
3044 to declare if they are being read or written by a kernel or function.
3046 The read_only/__read_only, write_only/__write_only and read_write/__read_write
3047 names are reserved for use as access qualifiers and shall not be used otherwise.
3052 foo (read_only image2d_t imageA,
3053 write_only image2d_t imageB) {
3057 In the above example imageA is a read-only 2D image object, and imageB is a
3058 write-only 2D image object.
3060 The read_write (or __read_write) qualifier can not be used with pipe.
3062 More details can be found in the OpenCL C language Spec v2.0, Section 6.6.
3066 def DocOpenCLAddressSpaces : DocumentationCategory<"OpenCL Address Spaces"> {
3068 The address space qualifier may be used to specify the region of memory that is
3069 used to allocate the object. OpenCL supports the following address spaces:
3070 __generic(generic), __global(global), __local(local), __private(private),
3071 __constant(constant).
3075 __constant int c = ...;
3077 __generic int* foo(global int* g) {
3084 More details can be found in the OpenCL C language Spec v2.0, Section 6.5.
3088 def OpenCLAddressSpaceGenericDocs : Documentation {
3089 let Category = DocOpenCLAddressSpaces;
3090 let Heading = "__generic, generic, [[clang::opencl_generic]]";
3092 The generic address space attribute is only available with OpenCL v2.0 and later.
3093 It can be used with pointer types. Variables in global and local scope and
3094 function parameters in non-kernel functions can have the generic address space
3095 type attribute. It is intended to be a placeholder for any other address space
3096 except for '__constant' in OpenCL code which can be used with multiple address
3101 def OpenCLAddressSpaceConstantDocs : Documentation {
3102 let Category = DocOpenCLAddressSpaces;
3103 let Heading = "__constant, constant, [[clang::opencl_constant]]";
3105 The constant address space attribute signals that an object is located in
3106 a constant (non-modifiable) memory region. It is available to all work items.
3107 Any type can be annotated with the constant address space attribute. Objects
3108 with the constant address space qualifier can be declared in any scope and must
3109 have an initializer.
3113 def OpenCLAddressSpaceGlobalDocs : Documentation {
3114 let Category = DocOpenCLAddressSpaces;
3115 let Heading = "__global, global, [[clang::opencl_global]]";
3117 The global address space attribute specifies that an object is allocated in
3118 global memory, which is accessible by all work items. The content stored in this
3119 memory area persists between kernel executions. Pointer types to the global
3120 address space are allowed as function parameters or local variables. Starting
3121 with OpenCL v2.0, the global address space can be used with global (program
3122 scope) variables and static local variable as well.
3126 def OpenCLAddressSpaceLocalDocs : Documentation {
3127 let Category = DocOpenCLAddressSpaces;
3128 let Heading = "__local, local, [[clang::opencl_local]]";
3130 The local address space specifies that an object is allocated in the local (work
3131 group) memory area, which is accessible to all work items in the same work
3132 group. The content stored in this memory region is not accessible after
3133 the kernel execution ends. In a kernel function scope, any variable can be in
3134 the local address space. In other scopes, only pointer types to the local address
3135 space are allowed. Local address space variables cannot have an initializer.
3139 def OpenCLAddressSpacePrivateDocs : Documentation {
3140 let Category = DocOpenCLAddressSpaces;
3141 let Heading = "__private, private, [[clang::opencl_private]]";
3143 The private address space specifies that an object is allocated in the private
3144 (work item) memory. Other work items cannot access the same memory area and its
3145 content is destroyed after work item execution ends. Local variables can be
3146 declared in the private address space. Function arguments are always in the
3147 private address space. Kernel function arguments of a pointer or an array type
3148 cannot point to the private address space.
3152 def OpenCLNoSVMDocs : Documentation {
3153 let Category = DocCatVariable;
3155 OpenCL 2.0 supports the optional ``__attribute__((nosvm))`` qualifier for
3156 pointer variable. It informs the compiler that the pointer does not refer
3157 to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.
3159 Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
3164 def Ptr32Docs : Documentation {
3165 let Category = DocCatType;
3167 The ``__ptr32`` qualifier represents a native pointer on a 32-bit system. On a
3168 64-bit system, a pointer with ``__ptr32`` is extended to a 64-bit pointer. The
3169 ``__sptr`` and ``__uptr`` qualifiers can be used to specify whether the pointer
3170 is sign extended or zero extended. This qualifier is enabled under
3171 ``-fms-extensions``.
3175 def Ptr64Docs : Documentation {
3176 let Category = DocCatType;
3178 The ``__ptr64`` qualifier represents a native pointer on a 64-bit system. On a
3179 32-bit system, a ``__ptr64`` pointer is truncated to a 32-bit pointer. This
3180 qualifier is enabled under ``-fms-extensions``.
3184 def SPtrDocs : Documentation {
3185 let Category = DocCatType;
3187 The ``__sptr`` qualifier specifies that a 32-bit pointer should be sign
3188 extended when converted to a 64-bit pointer.
3192 def UPtrDocs : Documentation {
3193 let Category = DocCatType;
3195 The ``__uptr`` qualifier specifies that a 32-bit pointer should be zero
3196 extended when converted to a 64-bit pointer.
3201 def NullabilityDocs : DocumentationCategory<"Nullability Attributes"> {
3203 Whether a particular pointer may be "null" is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the ``nonnull`` and ``returns_nonnull`` attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (``_Nullable``) or cannot be null (``_Nonnull``).
3205 The nullability (type) qualifiers express whether a value of a given pointer type can be null (the ``_Nullable`` qualifier), doesn't have a defined meaning for null (the ``_Nonnull`` qualifier), or for which the purpose of null is unclear (the ``_Null_unspecified`` qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the ``nonnull`` and ``returns_nonnull`` attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example:
3209 // No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).
3210 int fetch(int * _Nonnull ptr) { return *ptr; }
3212 // 'ptr' may be null.
3213 int fetch_or_zero(int * _Nullable ptr) {
3214 return ptr ? *ptr : 0;
3217 // A nullable pointer to non-null pointers to const characters.
3218 const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n);
3220 In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example:
3222 .. code-block:: objective-c
3224 @interface NSView : NSResponder
3225 - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView;
3226 @property (assign, nullable) NSView *superview;
3227 @property (readonly, nonnull) NSArray *subviews;
3232 def TypeNonNullDocs : Documentation {
3233 let Category = NullabilityDocs;
3235 The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful value for a value of the ``_Nonnull`` pointer type. For example, given a declaration such as:
3239 int fetch(int * _Nonnull ptr);
3241 a caller of ``fetch`` should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to ``fetch``. Note that, unlike the declaration attribute ``nonnull``, the presence of ``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch`` is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.
3245 def TypeNullableDocs : Documentation {
3246 let Category = NullabilityDocs;
3248 The ``_Nullable`` nullability qualifier indicates that a value of the ``_Nullable`` pointer type can be null. For example, given:
3252 int fetch_or_zero(int * _Nullable ptr);
3254 a caller of ``fetch_or_zero`` can provide null.
3258 def TypeNullUnspecifiedDocs : Documentation {
3259 let Category = NullabilityDocs;
3261 The ``_Null_unspecified`` nullability qualifier indicates that neither the ``_Nonnull`` nor ``_Nullable`` qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API.
3265 def NonNullDocs : Documentation {
3266 let Category = NullabilityDocs;
3268 The ``nonnull`` attribute indicates that some function parameters must not be null, and can be used in several different ways. It's original usage (`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example:
3272 extern void * my_memcpy (void *dest, const void *src, size_t len)
3273 __attribute__((nonnull (1, 2)));
3275 Here, the ``nonnull`` attribute indicates that parameters 1 and 2
3276 cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null:
3280 extern void * my_memcpy (void *dest, const void *src, size_t len)
3281 __attribute__((nonnull));
3283 Clang also allows the ``nonnull`` attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example:
3287 extern void * my_memcpy (void *dest __attribute__((nonnull)),
3288 const void *src __attribute__((nonnull)), size_t len);
3290 Note that the ``nonnull`` attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable.
3294 def ReturnsNonNullDocs : Documentation {
3295 let Category = NullabilityDocs;
3297 The ``returns_nonnull`` attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system ``malloc`` might be defined to terminate a process when memory is not available rather than returning a null pointer:
3301 extern void * malloc (size_t size) __attribute__((returns_nonnull));
3303 The ``returns_nonnull`` attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The ``_Nonnull`` type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable
3307 def NoAliasDocs : Documentation {
3308 let Category = DocCatFunction;
3310 The ``noalias`` attribute indicates that the only memory accesses inside
3311 function are loads and stores from objects pointed to by its pointer-typed
3312 arguments, with arbitrary offsets.
3316 def OMPDeclareSimdDocs : Documentation {
3317 let Category = DocCatFunction;
3318 let Heading = "#pragma omp declare simd";
3320 The ``declare simd`` construct can be applied to a function to enable the creation
3321 of one or more versions that can process multiple arguments using SIMD
3322 instructions from a single invocation in a SIMD loop. The ``declare simd``
3323 directive is a declarative directive. There may be multiple ``declare simd``
3324 directives for a function. The use of a ``declare simd`` construct on a function
3325 enables the creation of SIMD versions of the associated function that can be
3326 used to process multiple arguments from a single invocation from a SIMD loop
3328 The syntax of the ``declare simd`` construct is as follows:
3330 .. code-block:: none
3332 #pragma omp declare simd [clause[[,] clause] ...] new-line
3333 [#pragma omp declare simd [clause[[,] clause] ...] new-line]
3335 function definition or declaration
3337 where clause is one of the following:
3339 .. code-block:: none
3342 linear(argument-list[:constant-linear-step])
3343 aligned(argument-list[:alignment])
3344 uniform(argument-list)
3351 def OMPDeclareTargetDocs : Documentation {
3352 let Category = DocCatFunction;
3353 let Heading = "#pragma omp declare target";
3355 The ``declare target`` directive specifies that variables and functions are mapped
3356 to a device for OpenMP offload mechanism.
3358 The syntax of the declare target directive is as follows:
3362 #pragma omp declare target new-line
3363 declarations-definition-seq
3364 #pragma omp end declare target new-line
3370 #pragma omp declare target (extended-list) new-line
3376 #pragma omp declare target clause[ [,] clause ... ] new-line
3378 where clause is one of the following:
3385 device_type(host | nohost | any)
3389 def OMPDeclareVariantDocs : Documentation {
3390 let Category = DocCatFunction;
3391 let Heading = "#pragma omp declare variant";
3393 The ``declare variant`` directive declares a specialized variant of a base
3394 function and specifies the context in which that specialized variant is used.
3395 The declare variant directive is a declarative directive.
3396 The syntax of the ``declare variant`` construct is as follows:
3398 .. code-block:: none
3400 #pragma omp declare variant(variant-func-id) clause new-line
3401 [#pragma omp declare variant(variant-func-id) clause new-line]
3403 function definition or declaration
3405 where clause is one of the following:
3407 .. code-block:: none
3409 match(context-selector-specification)
3411 and where ``variant-func-id`` is the name of a function variant that is either a
3412 base language identifier or, for C++, a template-id.
3414 Clang provides the following context selector extensions, used via
3415 ``implementation={extension(EXTENSION)}``:
3417 .. code-block:: none
3423 The match extensions change when the *entire* context selector is considered a
3424 match for an OpenMP context. The default is ``all``, with ``none`` no trait in the
3425 selector is allowed to be in the OpenMP context, with ``any`` a single trait in
3426 both the selector and OpenMP context is sufficient. Only a single match
3427 extension trait is allowed per context selector.
3432 def NoStackProtectorDocs : Documentation {
3433 let Category = DocCatFunction;
3435 Clang supports the ``__attribute__((no_stack_protector))`` attribute which disables
3436 the stack protector on the specified function. This attribute is useful for
3437 selectively disabling the stack protector on some functions when building with
3438 ``-fstack-protector`` compiler option.
3440 For example, it disables the stack protector for the function ``foo`` but function
3441 ``bar`` will still be built with the stack protector with the ``-fstack-protector``
3446 int __attribute__((no_stack_protector))
3447 foo (int x); // stack protection will be disabled for foo.
3449 int bar(int y); // bar can be built with the stack protector.
3454 def NotTailCalledDocs : Documentation {
3455 let Category = DocCatFunction;
3457 The ``not_tail_called`` attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as ``always_inline`` cannot be marked as ``not_tail_called``.
3459 For example, it prevents tail-call optimization in the following case:
3463 int __attribute__((not_tail_called)) foo1(int);
3466 return foo1(a); // No tail-call optimization on direct calls.
3469 However, it doesn't prevent tail-call optimization in this case:
3473 int __attribute__((not_tail_called)) foo1(int);
3476 int (*fn)(int) = &foo1;
3478 // not_tail_called has no effect on an indirect call even if the call can be
3479 // resolved at compile time.
3483 Marking virtual functions as ``not_tail_called`` is an error:
3489 // not_tail_called on a virtual function is an error.
3490 [[clang::not_tail_called]] virtual int foo1();
3494 // Non-virtual functions can be marked ``not_tail_called``.
3495 [[clang::not_tail_called]] int foo3();
3498 class Derived1 : public Base {
3500 int foo1() override;
3502 // not_tail_called on a virtual function is an error.
3503 [[clang::not_tail_called]] int foo2() override;
3508 def NoThrowDocs : Documentation {
3509 let Category = DocCatFunction;
3511 Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style
3512 ``__declspec(nothrow)`` attribute as an equivalent of ``noexcept`` on function
3513 declarations. This attribute informs the compiler that the annotated function
3514 does not throw an exception. This prevents exception-unwinding. This attribute
3515 is particularly useful on functions in the C Standard Library that are
3516 guaranteed to not throw an exception.
3520 def InternalLinkageDocs : Documentation {
3521 let Category = DocCatFunction;
3523 The ``internal_linkage`` attribute changes the linkage type of the declaration to internal.
3524 This is similar to C-style ``static``, but can be used on classes and class methods. When applied to a class definition,
3525 this attribute affects all methods and static data members of that class.
3526 This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables.
3530 def ExcludeFromExplicitInstantiationDocs : Documentation {
3531 let Category = DocCatFunction;
3533 The ``exclude_from_explicit_instantiation`` attribute opts-out a member of a
3534 class template from being part of explicit template instantiations of that
3535 class template. This means that an explicit instantiation will not instantiate
3536 members of the class template marked with the attribute, but also that code
3537 where an extern template declaration of the enclosing class template is visible
3538 will not take for granted that an external instantiation of the class template
3539 would provide those members (which would otherwise be a link error, since the
3540 explicit instantiation won't provide those members). For example, let's say we
3541 don't want the ``data()`` method to be part of libc++'s ABI. To make sure it
3542 is not exported from the dylib, we give it hidden visibility:
3547 template <class CharT>
3548 class basic_string {
3550 __attribute__((__visibility__("hidden")))
3551 const value_type* data() const noexcept { ... }
3554 template class basic_string<char>;
3556 Since an explicit template instantiation declaration for ``basic_string<char>``
3557 is provided, the compiler is free to assume that ``basic_string<char>::data()``
3558 will be provided by another translation unit, and it is free to produce an
3559 external call to this function. However, since ``data()`` has hidden visibility
3560 and the explicit template instantiation is provided in a shared library (as
3561 opposed to simply another translation unit), ``basic_string<char>::data()``
3562 won't be found and a link error will ensue. This happens because the compiler
3563 assumes that ``basic_string<char>::data()`` is part of the explicit template
3564 instantiation declaration, when it really isn't. To tell the compiler that
3565 ``data()`` is not part of the explicit template instantiation declaration, the
3566 ``exclude_from_explicit_instantiation`` attribute can be used:
3571 template <class CharT>
3572 class basic_string {
3574 __attribute__((__visibility__("hidden")))
3575 __attribute__((exclude_from_explicit_instantiation))
3576 const value_type* data() const noexcept { ... }
3579 template class basic_string<char>;
3581 Now, the compiler won't assume that ``basic_string<char>::data()`` is provided
3582 externally despite there being an explicit template instantiation declaration:
3583 the compiler will implicitly instantiate ``basic_string<char>::data()`` in the
3584 TUs where it is used.
3586 This attribute can be used on static and non-static member functions of class
3587 templates, static data members of class templates and member classes of class
3592 def DisableTailCallsDocs : Documentation {
3593 let Category = DocCatFunction;
3595 The ``disable_tail_calls`` attribute instructs the backend to not perform tail call optimization inside the marked function.
3603 int foo(int a) __attribute__((disable_tail_calls)) {
3604 return callee(a); // This call is not tail-call optimized.
3607 Marking virtual functions as ``disable_tail_calls`` is legal.
3615 [[clang::disable_tail_calls]] virtual int foo1() {
3616 return callee(); // This call is not tail-call optimized.
3620 class Derived1 : public Base {
3622 int foo1() override {
3623 return callee(); // This call is tail-call optimized.
3630 def AnyX86NoCallerSavedRegistersDocs : Documentation {
3631 let Category = DocCatFunction;
3633 Use this attribute to indicate that the specified function has no
3634 caller-saved registers. That is, all registers are callee-saved except for
3635 registers used for passing parameters to the function or returning parameters
3637 The compiler saves and restores any modified registers that were not used for
3638 passing or returning arguments to the function.
3640 The user can call functions specified with the 'no_caller_saved_registers'
3641 attribute from an interrupt handler without saving and restoring all
3642 call-clobbered registers.
3644 Note that 'no_caller_saved_registers' attribute is not a calling convention.
3645 In fact, it only overrides the decision of which registers should be saved by
3646 the caller, but not how the parameters are passed from the caller to the callee.
3652 __attribute__ ((no_caller_saved_registers, fastcall))
3653 void f (int arg1, int arg2) {
3657 In this case parameters 'arg1' and 'arg2' will be passed in registers.
3658 In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
3659 register parameters. However, it will not assume any scratch registers and
3660 should save and restore any modified registers except for ECX and EDX.
3664 def X86ForceAlignArgPointerDocs : Documentation {
3665 let Category = DocCatFunction;
3667 Use this attribute to force stack alignment.
3669 Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
3670 (like 'movaps') that work with the stack require operands to be 16-byte aligned.
3671 This attribute realigns the stack in the function prologue to make sure the
3672 stack can be used with SSE instructions.
3674 Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
3675 Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
3676 rare cases where the caller does not align the stack properly (e.g. flow
3677 jumps from i386 arch code).
3681 __attribute__ ((force_align_arg_pointer))
3689 def AnyX86NoCfCheckDocs : Documentation {
3690 let Category = DocCatFunction;
3692 Jump Oriented Programming attacks rely on tampering with addresses used by
3693 indirect call / jmp, e.g. redirect control-flow to non-programmer
3694 intended bytes in the binary.
3695 X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
3696 Enforcement Technology (CET). IBT instruments ENDBR instructions used to
3697 specify valid targets of indirect call / jmp.
3698 The ``nocf_check`` attribute has two roles:
3699 1. Appertains to a function - do not add ENDBR instruction at the beginning of
3701 2. Appertains to a function pointer - do not track the target function of this
3702 pointer (by adding nocf_check prefix to the indirect-call instruction).
3706 def SwiftCallDocs : Documentation {
3707 let Category = DocCatVariable;
3709 The ``swiftcall`` attribute indicates that a function should be called
3710 using the Swift calling convention for a function or function pointer.
3712 The lowering for the Swift calling convention, as described by the Swift
3713 ABI documentation, occurs in multiple phases. The first, "high-level"
3714 phase breaks down the formal parameters and results into innately direct
3715 and indirect components, adds implicit parameters for the generic
3716 signature, and assigns the context and error ABI treatments to parameters
3717 where applicable. The second phase breaks down the direct parameters
3718 and results from the first phase and assigns them to registers or the
3719 stack. The ``swiftcall`` convention only handles this second phase of
3720 lowering; the C function type must accurately reflect the results
3721 of the first phase, as follows:
3723 - Results classified as indirect by high-level lowering should be
3724 represented as parameters with the ``swift_indirect_result`` attribute.
3726 - Results classified as direct by high-level lowering should be represented
3729 - First, remove any empty direct results.
3731 - If there are no direct results, the C result type should be ``void``.
3733 - If there is one direct result, the C result type should be a type with
3734 the exact layout of that result type.
3736 - If there are a multiple direct results, the C result type should be
3737 a struct type with the exact layout of a tuple of those results.
3739 - Parameters classified as indirect by high-level lowering should be
3740 represented as parameters of pointer type.
3742 - Parameters classified as direct by high-level lowering should be
3743 omitted if they are empty types; otherwise, they should be represented
3744 as a parameter type with a layout exactly matching the layout of the
3745 Swift parameter type.
3747 - The context parameter, if present, should be represented as a trailing
3748 parameter with the ``swift_context`` attribute.
3750 - The error result parameter, if present, should be represented as a
3751 trailing parameter (always following a context parameter) with the
3752 ``swift_error_result`` attribute.
3754 ``swiftcall`` does not support variadic arguments or unprototyped functions.
3756 The parameter ABI treatment attributes are aspects of the function type.
3757 A function type which applies an ABI treatment attribute to a
3758 parameter is a different type from an otherwise-identical function type
3759 that does not. A single parameter may not have multiple ABI treatment
3762 Support for this feature is target-dependent, although it should be
3763 supported on every target that Swift supports. Query for this support
3764 with ``__has_attribute(swiftcall)``. This implies support for the
3765 ``swift_context``, ``swift_error_result``, and ``swift_indirect_result``
3770 def SwiftContextDocs : Documentation {
3771 let Category = DocCatVariable;
3773 The ``swift_context`` attribute marks a parameter of a ``swiftcall``
3774 function as having the special context-parameter ABI treatment.
3776 This treatment generally passes the context value in a special register
3777 which is normally callee-preserved.
3779 A ``swift_context`` parameter must either be the last parameter or must be
3780 followed by a ``swift_error_result`` parameter (which itself must always be
3781 the last parameter).
3783 A context parameter must have pointer or reference type.
3787 def SwiftErrorResultDocs : Documentation {
3788 let Category = DocCatVariable;
3790 The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
3791 function as having the special error-result ABI treatment.
3793 This treatment generally passes the underlying error value in and out of
3794 the function through a special register which is normally callee-preserved.
3795 This is modeled in C by pretending that the register is addressable memory:
3797 - The caller appears to pass the address of a variable of pointer type.
3798 The current value of this variable is copied into the register before
3799 the call; if the call returns normally, the value is copied back into the
3802 - The callee appears to receive the address of a variable. This address
3803 is actually a hidden location in its own stack, initialized with the
3804 value of the register upon entry. When the function returns normally,
3805 the value in that hidden location is written back to the register.
3807 A ``swift_error_result`` parameter must be the last parameter, and it must be
3808 preceded by a ``swift_context`` parameter.
3810 A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some
3811 type T. Note that no qualifiers are permitted on the intermediate level.
3813 It is undefined behavior if the caller does not pass a pointer or
3814 reference to a valid object.
3816 The standard convention is that the error value itself (that is, the
3817 value stored in the apparent argument) will be null upon function entry,
3818 but this is not enforced by the ABI.
3822 def SwiftIndirectResultDocs : Documentation {
3823 let Category = DocCatVariable;
3825 The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
3826 function as having the special indirect-result ABI treatment.
3828 This treatment gives the parameter the target's normal indirect-result
3829 ABI treatment, which may involve passing it differently from an ordinary
3830 parameter. However, only the first indirect result will receive this
3831 treatment. Furthermore, low-level lowering may decide that a direct result
3832 must be returned indirectly; if so, this will take priority over the
3833 ``swift_indirect_result`` parameters.
3835 A ``swift_indirect_result`` parameter must either be the first parameter or
3836 follow another ``swift_indirect_result`` parameter.
3838 A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
3839 some object type ``T``. If ``T`` is a complete type at the point of
3840 definition of a function, it is undefined behavior if the argument
3841 value does not point to storage of adequate size and alignment for a
3842 value of type ``T``.
3844 Making indirect results explicit in the signature allows C functions to
3845 directly construct objects into them without relying on language
3846 optimizations like C++'s named return value optimization (NRVO).
3850 def SuppressDocs : Documentation {
3851 let Category = DocCatStmt;
3853 The ``[[gsl::suppress]]`` attribute suppresses specific
3854 clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable
3855 way. The attribute can be attached to declarations, statements, and at
3860 [[gsl::suppress("Rh-public")]]
3863 [[gsl::suppress("type")]] {
3864 p = reinterpret_cast<int*>(7);
3868 [[clang::suppress("type", "bounds")]];
3872 .. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement
3876 def AbiTagsDocs : Documentation {
3877 let Category = DocCatFunction;
3879 The ``abi_tag`` attribute can be applied to a function, variable, class or
3880 inline namespace declaration to modify the mangled name of the entity. It gives
3881 the ability to distinguish between different versions of the same entity but
3882 with different ABI versions supported. For example, a newer version of a class
3883 could have a different set of data members and thus have a different size. Using
3884 the ``abi_tag`` attribute, it is possible to have different mangled names for
3885 a global variable of the class type. Therefore, the old code could keep using
3886 the old mangled name and the new code will use the new mangled name with tags.
3890 def PreserveMostDocs : Documentation {
3891 let Category = DocCatCallingConvs;
3893 On X86-64 and AArch64 targets, this attribute changes the calling convention of
3894 a function. The ``preserve_most`` calling convention attempts to make the code
3895 in the caller as unintrusive as possible. This convention behaves identically
3896 to the ``C`` calling convention on how arguments and return values are passed,
3897 but it uses a different set of caller/callee-saved registers. This alleviates
3898 the burden of saving and recovering a large register set before and after the
3899 call in the caller. If the arguments are passed in callee-saved registers,
3900 then they will be preserved by the callee across the call. This doesn't
3901 apply for values returned in callee-saved registers.
3903 - On X86-64 the callee preserves all general purpose registers, except for
3904 R11. R11 can be used as a scratch register. Floating-point registers
3905 (XMMs/YMMs) are not preserved and need to be saved by the caller.
3907 The idea behind this convention is to support calls to runtime functions
3908 that have a hot path and a cold path. The hot path is usually a small piece
3909 of code that doesn't use many registers. The cold path might need to call out to
3910 another function and therefore only needs to preserve the caller-saved
3911 registers, which haven't already been saved by the caller. The
3912 ``preserve_most`` calling convention is very similar to the ``cold`` calling
3913 convention in terms of caller/callee-saved registers, but they are used for
3914 different types of function calls. ``coldcc`` is for function calls that are
3915 rarely executed, whereas ``preserve_most`` function calls are intended to be
3916 on the hot path and definitely executed a lot. Furthermore ``preserve_most``
3917 doesn't prevent the inliner from inlining the function call.
3919 This calling convention will be used by a future version of the Objective-C
3920 runtime and should therefore still be considered experimental at this time.
3921 Although this convention was created to optimize certain runtime calls to
3922 the Objective-C runtime, it is not limited to this runtime and might be used
3923 by other runtimes in the future too. The current implementation only
3924 supports X86-64 and AArch64, but the intention is to support more architectures
3929 def PreserveAllDocs : Documentation {
3930 let Category = DocCatCallingConvs;
3932 On X86-64 and AArch64 targets, this attribute changes the calling convention of
3933 a function. The ``preserve_all`` calling convention attempts to make the code
3934 in the caller even less intrusive than the ``preserve_most`` calling convention.
3935 This calling convention also behaves identical to the ``C`` calling convention
3936 on how arguments and return values are passed, but it uses a different set of
3937 caller/callee-saved registers. This removes the burden of saving and
3938 recovering a large register set before and after the call in the caller. If
3939 the arguments are passed in callee-saved registers, then they will be
3940 preserved by the callee across the call. This doesn't apply for values
3941 returned in callee-saved registers.
3943 - On X86-64 the callee preserves all general purpose registers, except for
3944 R11. R11 can be used as a scratch register. Furthermore it also preserves
3945 all floating-point registers (XMMs/YMMs).
3947 The idea behind this convention is to support calls to runtime functions
3948 that don't need to call out to any other functions.
3950 This calling convention, like the ``preserve_most`` calling convention, will be
3951 used by a future version of the Objective-C runtime and should be considered
3952 experimental at this time.
3956 def DeprecatedDocs : Documentation {
3957 let Category = DocCatDecl;
3959 The ``deprecated`` attribute can be applied to a function, a variable, or a
3960 type. This is useful when identifying functions, variables, or types that are
3961 expected to be removed in a future version of a program.
3963 Consider the function declaration for a hypothetical function ``f``:
3967 void f(void) __attribute__((deprecated("message", "replacement")));
3969 When spelled as ``__attribute__((deprecated))``, the deprecated attribute can have
3970 two optional string arguments. The first one is the message to display when
3971 emitting the warning; the second one enables the compiler to provide a Fix-It
3972 to replace the deprecated name with a new name. Otherwise, when spelled as
3973 ``[[gnu::deprecated]]`` or ``[[deprecated]]``, the attribute can have one optional
3974 string argument which is the message to display when emitting the warning.
3978 def IFuncDocs : Documentation {
3979 let Category = DocCatFunction;
3981 ``__attribute__((ifunc("resolver")))`` is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.
3983 The symbol name of the resolver function is given in quotes. A function with this name (after mangling) must be defined in the current translation unit; it may be ``static``. The resolver function should return a pointer.
3985 The ``ifunc`` attribute may only be used on a function declaration. A function declaration with an ``ifunc`` attribute is considered to be a definition of the declared entity. The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline.
3987 Not 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.
3991 def LTOVisibilityDocs : Documentation {
3992 let Category = DocCatDecl;
3994 See :doc:`LTOVisibility`.
3998 def RenderScriptKernelAttributeDocs : Documentation {
3999 let Category = DocCatFunction;
4001 ``__attribute__((kernel))`` is used to mark a ``kernel`` function in
4004 In RenderScript, ``kernel`` functions are used to express data-parallel
4005 computations. The RenderScript runtime efficiently parallelizes ``kernel``
4006 functions to run on computational resources such as multi-core CPUs and GPUs.
4007 See the RenderScript_ documentation for more information.
4009 .. _RenderScript: https://developer.android.com/guide/topics/renderscript/compute.html
4013 def XRayDocs : Documentation {
4014 let Category = DocCatFunction;
4015 let Heading = "xray_always_instrument, xray_never_instrument, xray_log_args";
4017 ``__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.
4019 Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points.
4021 If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.
4023 ``__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.
4027 def PatchableFunctionEntryDocs : Documentation {
4028 let Category = DocCatFunction;
4030 ``__attribute__((patchable_function_entry(N,M)))`` is used to generate M NOPs
4031 before the function entry and N-M NOPs after the function entry. This attribute
4032 takes precedence over the command line option ``-fpatchable-function-entry=N,M``.
4033 ``M`` defaults to 0 if omitted.
4037 def TransparentUnionDocs : Documentation {
4038 let Category = DocCatDecl;
4040 This attribute can be applied to a union to change the behavior of calls to
4041 functions that have an argument with a transparent union type. The compiler
4042 behavior is changed in the following manner:
4044 - A value whose type is any member of the transparent union can be passed as an
4045 argument without the need to cast that value.
4047 - The argument is passed to the function using the calling convention of the
4048 first member of the transparent union. Consequently, all the members of the
4049 transparent union should have the same calling convention as its first member.
4051 Transparent unions are not supported in C++.
4055 def ObjCSubclassingRestrictedDocs : Documentation {
4056 let Category = DocCatDecl;
4058 This attribute can be added to an Objective-C ``@interface`` declaration to
4059 ensure that this class cannot be subclassed.
4063 def ObjCNonLazyClassDocs : Documentation {
4064 let Category = DocCatDecl;
4066 This attribute can be added to an Objective-C ``@interface`` or
4067 ``@implementation`` declaration to add the class to the list of non-lazily
4068 initialized classes. A non-lazy class will be initialized eagerly when the
4069 Objective-C runtime is loaded. This is required for certain system classes which
4070 have instances allocated in non-standard ways, such as the classes for blocks
4071 and constant strings. Adding this attribute is essentially equivalent to
4072 providing a trivial ``+load`` method but avoids the (fairly small) load-time
4073 overheads associated with defining and calling such a method.
4077 def ObjCDirectDocs : Documentation {
4078 let Category = DocCatDecl;
4080 The ``objc_direct`` attribute can be used to mark an Objective-C method as
4081 being *direct*. A direct method is treated statically like an ordinary method,
4082 but dynamically it behaves more like a C function. This lowers some of the costs
4083 associated with the method but also sacrifices some of the ordinary capabilities
4084 of Objective-C methods.
4086 A message send of a direct method calls the implementation directly, as if it
4087 were a C function, rather than using ordinary Objective-C method dispatch. This
4088 is substantially faster and potentially allows the implementation to be inlined,
4089 but it also means the method cannot be overridden in subclasses or replaced
4090 dynamically, as ordinary Objective-C methods can.
4092 Furthermore, a direct method is not listed in the class's method lists. This
4093 substantially reduces the code-size overhead of the method but also means it
4094 cannot be called dynamically using ordinary Objective-C method dispatch at all;
4095 in particular, this means that it cannot override a superclass method or satisfy
4096 a protocol requirement.
4098 Because a direct method cannot be overridden, it is an error to perform
4099 a ``super`` message send of one.
4101 Although a message send of a direct method causes the method to be called
4102 directly as if it were a C function, it still obeys Objective-C semantics in other
4105 - If the receiver is ``nil``, the message send does nothing and returns the zero value
4106 for the return type.
4108 - A message send of a direct class method will cause the class to be initialized,
4109 including calling the ``+initialize`` method if present.
4111 - The implicit ``_cmd`` parameter containing the method's selector is still defined.
4112 In order to minimize code-size costs, the implementation will not emit a reference
4113 to the selector if the parameter is unused within the method.
4115 Symbols for direct method implementations are implicitly given hidden
4116 visibility, meaning that they can only be called within the same linkage unit.
4118 It is an error to do any of the following:
4120 - declare a direct method in a protocol,
4121 - declare an override of a direct method with a method in a subclass,
4122 - declare an override of a non-direct method with a direct method in a subclass,
4123 - declare a method with different directness in different class interfaces, or
4124 - implement a non-direct method (as declared in any class interface) with a direct method.
4126 If any of these rules would be violated if every method defined in an
4127 ``@implementation`` within a single linkage unit were declared in an
4128 appropriate class interface, the program is ill-formed with no diagnostic
4129 required. If a violation of this rule is not diagnosed, behavior remains
4130 well-defined; this paragraph is simply reserving the right to diagnose such
4131 conflicts in the future, not to treat them as undefined behavior.
4133 Additionally, Clang will warn about any ``@selector`` expression that
4134 names a selector that is only known to be used for direct methods.
4136 For the purpose of these rules, a "class interface" includes a class's primary
4137 ``@interface`` block, its class extensions, its categories, its declared protocols,
4138 and all the class interfaces of its superclasses.
4140 An Objective-C property can be declared with the ``direct`` property
4141 attribute. If a direct property declaration causes an implicit declaration of
4142 a getter or setter method (that is, if the given method is not explicitly
4143 declared elsewhere), the method is declared to be direct.
4145 Some programmers may wish to make many methods direct at once. In order
4146 to simplify this, the ``objc_direct_members`` attribute is provided; see its
4147 documentation for more information.
4151 def ObjCDirectMembersDocs : Documentation {
4152 let Category = DocCatDecl;
4154 The ``objc_direct_members`` attribute can be placed on an Objective-C
4155 ``@interface`` or ``@implementation`` to mark that methods declared
4156 therein should be considered direct by default. See the documentation
4157 for ``objc_direct`` for more information about direct methods.
4159 When ``objc_direct_members`` is placed on an ``@interface`` block, every
4160 method in the block is considered to be declared as direct. This includes any
4161 implicit method declarations introduced by property declarations. If the method
4162 redeclares a non-direct method, the declaration is ill-formed, exactly as if the
4163 method was annotated with the ``objc_direct`` attribute.
4165 When ``objc_direct_members`` is placed on an ``@implementation`` block,
4166 methods defined in the block are considered to be declared as direct unless
4167 they have been previously declared as non-direct in any interface of the class.
4168 This includes the implicit method definitions introduced by synthesized
4169 properties, including auto-synthesized properties.
4173 def SelectAnyDocs : Documentation {
4174 let Category = DocCatDecl;
4176 This attribute appertains to a global symbol, causing it to have a weak
4178 `linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_
4179 ), allowing the linker to select any definition.
4181 For more information see
4182 `gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_
4183 or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_.
4186 def WebAssemblyExportNameDocs : Documentation {
4187 let Category = DocCatFunction;
4189 Clang supports the ``__attribute__((export_name(<name>)))``
4190 attribute for the WebAssembly target. This attribute may be attached to a
4191 function declaration, where it modifies how the symbol is to be exported
4192 from the linked WebAssembly.
4194 WebAssembly functions are exported via string name. By default when a symbol
4195 is exported, the export name for C/C++ symbols are the same as their C/C++
4196 symbol names. This attribute can be used to override the default behavior, and
4197 request a specific string name be used instead.
4201 def WebAssemblyImportModuleDocs : Documentation {
4202 let Category = DocCatFunction;
4204 Clang supports the ``__attribute__((import_module(<module_name>)))``
4205 attribute for the WebAssembly target. This attribute may be attached to a
4206 function declaration, where it modifies how the symbol is to be imported
4207 within the WebAssembly linking environment.
4209 WebAssembly imports use a two-level namespace scheme, consisting of a module
4210 name, which typically identifies a module from which to import, and a field
4211 name, which typically identifies a field from that module to import. By
4212 default, module names for C/C++ symbols are assigned automatically by the
4213 linker. This attribute can be used to override the default behavior, and
4214 request a specific module name be used instead.
4218 def WebAssemblyImportNameDocs : Documentation {
4219 let Category = DocCatFunction;
4221 Clang supports the ``__attribute__((import_name(<name>)))``
4222 attribute for the WebAssembly target. This attribute may be attached to a
4223 function declaration, where it modifies how the symbol is to be imported
4224 within the WebAssembly linking environment.
4226 WebAssembly imports use a two-level namespace scheme, consisting of a module
4227 name, which typically identifies a module from which to import, and a field
4228 name, which typically identifies a field from that module to import. By
4229 default, field names for C/C++ symbols are the same as their C/C++ symbol
4230 names. This attribute can be used to override the default behavior, and
4231 request a specific field name be used instead.
4235 def ArtificialDocs : Documentation {
4236 let Category = DocCatFunction;
4238 The ``artificial`` attribute can be applied to an inline function. If such a
4239 function is inlined, the attribute indicates that debuggers should associate
4240 the resulting instructions with the call site, rather than with the
4241 corresponding line within the inlined callee.
4245 def NoDerefDocs : Documentation {
4246 let Category = DocCatType;
4248 The ``noderef`` attribute causes clang to diagnose dereferences of annotated pointer types.
4249 This is ideally used with pointers that point to special memory which cannot be read
4250 from or written to, but allowing for the pointer to be used in pointer arithmetic.
4251 The following are examples of valid expressions where dereferences are diagnosed:
4255 int __attribute__((noderef)) *p;
4256 int x = *p; // warning
4258 int __attribute__((noderef)) **p2;
4259 x = **p2; // warning
4261 int * __attribute__((noderef)) *p3;
4267 struct S __attribute__((noderef)) *s;
4268 x = s->a; // warning
4269 x = (*s).a; // warning
4271 Not all dereferences may diagnose a warning if the value directed by the pointer may not be
4272 accessed. The following are examples of valid expressions where may not be diagnosed:
4277 int __attribute__((noderef)) *p;
4284 struct S __attribute__((noderef)) *s;
4288 ``noderef`` is currently only supported for pointers and arrays and not usable for
4289 references or Objective-C object pointers.
4294 int __attribute__((noderef)) &y = x; // warning: 'noderef' can only be used on an array or pointer type
4298 id __attribute__((noderef)) obj = [NSObject new]; // warning: 'noderef' can only be used on an array or pointer type
4302 def ReinitializesDocs : Documentation {
4303 let Category = DocCatFunction;
4305 The ``reinitializes`` attribute can be applied to a non-static, non-const C++
4306 member function to indicate that this member function reinitializes the entire
4307 object to a known state, independent of the previous state of the object.
4309 This attribute can be interpreted by static analyzers that warn about uses of an
4310 object that has been left in an indeterminate state by a move operation. If a
4311 member function marked with the ``reinitializes`` attribute is called on a
4312 moved-from object, the analyzer can conclude that the object is no longer in an
4313 indeterminate state.
4315 A typical example where this attribute would be used is on functions that clear
4324 [[clang::reinitializes]] void Clear();
4330 def AlwaysDestroyDocs : Documentation {
4331 let Category = DocCatVariable;
4333 The ``always_destroy`` attribute specifies that a variable with static or thread
4334 storage duration should have its exit-time destructor run. This attribute is the
4335 default unless clang was invoked with -fno-c++-static-destructors.
4339 def NoDestroyDocs : Documentation {
4340 let Category = DocCatVariable;
4342 The ``no_destroy`` attribute specifies that a variable with static or thread
4343 storage duration shouldn't have its exit-time destructor run. Annotating every
4344 static and thread duration variable with this attribute is equivalent to
4345 invoking clang with -fno-c++-static-destructors.
4347 If a variable is declared with this attribute, clang doesn't access check or
4348 generate the type's destructor. If you have a type that you only want to be
4349 annotated with ``no_destroy``, you can therefore declare the destructor private:
4353 struct only_no_destroy {
4359 [[clang::no_destroy]] only_no_destroy global; // fine!
4361 Note that destructors are still required for subobjects of aggregates annotated
4362 with this attribute. This is because previously constructed subobjects need to
4363 be destroyed if an exception gets thrown before the initialization of the
4364 complete object is complete. For instance:
4370 [[clang::no_destroy]]
4371 static only_no_destroy array[10]; // error, only_no_destroy has a private destructor.
4377 Here, if the construction of ``array[9]`` fails with an exception, ``array[0..8]``
4378 will be destroyed, so the element's destructor needs to be accessible.
4382 def UninitializedDocs : Documentation {
4383 let Category = DocCatVariable;
4385 The command-line parameter ``-ftrivial-auto-var-init=*`` can be used to
4386 initialize trivial automatic stack variables. By default, trivial automatic
4387 stack variables are uninitialized. This attribute is used to override the
4388 command-line parameter, forcing variables to remain uninitialized. It has no
4389 semantic meaning in that using uninitialized values is undefined behavior,
4390 it rather documents the programmer's intent.
4394 def LoaderUninitializedDocs : Documentation {
4395 let Category = DocCatVariable;
4397 The ``loader_uninitialized`` attribute can be placed on global variables to
4398 indicate that the variable does not need to be zero initialized by the loader.
4399 On most targets, zero-initialization does not incur any additional cost.
4400 For example, most general purpose operating systems deliberately ensure
4401 that all memory is properly initialized in order to avoid leaking privileged
4402 information from the kernel or other programs. However, some targets
4403 do not make this guarantee, and on these targets, avoiding an unnecessary
4404 zero-initialization can have a significant impact on load times and/or code
4407 A declaration with this attribute is a non-tentative definition just as if it
4408 provided an initializer. Variables with this attribute are considered to be
4409 uninitialized in the same sense as a local variable, and the programs must
4410 write to them before reading from them. If the variable's type is a C++ class
4411 type with a non-trivial default constructor, or an array thereof, this attribute
4412 only suppresses the static zero-initialization of the variable, not the dynamic
4413 initialization provided by executing the default constructor.
4417 def CallbackDocs : Documentation {
4418 let Category = DocCatFunction;
4420 The ``callback`` attribute specifies that the annotated function may invoke the
4421 specified callback zero or more times. The callback, as well as the passed
4422 arguments, are identified by their parameter name or position (starting with
4423 1!) in the annotated function. The first position in the attribute identifies
4424 the callback callee, the following positions declare describe its arguments.
4425 The callback callee is required to be callable with the number, and order, of
4426 the specified arguments. The index ``0``, or the identifier ``this``, is used to
4427 represent an implicit "this" pointer in class methods. If there is no implicit
4428 "this" pointer it shall not be referenced. The index '-1', or the name "__",
4429 represents an unknown callback callee argument. This can be a value which is
4430 not present in the declared parameter list, or one that is, but is potentially
4431 inspected, captured, or modified. Parameter names and indices can be mixed in
4432 the callback attribute.
4434 The ``callback`` attribute, which is directly translated to ``callback``
4435 metadata <http://llvm.org/docs/LangRef.html#callback-metadata>, make the
4436 connection between the call to the annotated function and the callback callee.
4437 This can enable interprocedural optimizations which were otherwise impossible.
4438 If a function parameter is mentioned in the ``callback`` attribute, through its
4439 position, it is undefined if that parameter is used for anything other than the
4440 actual callback. Inspected, captured, or modified parameters shall not be
4441 listed in the ``callback`` metadata.
4443 Example encodings for the callback performed by ``pthread_create`` are shown
4444 below. The explicit attribute annotation indicates that the third parameter
4445 (``start_routine``) is called zero or more times by the ``pthread_create`` function,
4446 and that the fourth parameter (``arg``) is passed along. Note that the callback
4447 behavior of ``pthread_create`` is automatically recognized by Clang. In addition,
4448 the declarations of ``__kmpc_fork_teams`` and ``__kmpc_fork_call``, generated for
4449 ``#pragma omp target teams`` and ``#pragma omp parallel``, respectively, are also
4450 automatically recognized as broker functions. Further functions might be added
4455 __attribute__((callback (start_routine, arg)))
4456 int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
4457 void *(*start_routine) (void *), void *arg);
4459 __attribute__((callback (3, 4)))
4460 int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
4461 void *(*start_routine) (void *), void *arg);
4466 def GnuInlineDocs : Documentation {
4467 let Category = DocCatFunction;
4469 The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline
4472 * If any declaration that is declared ``inline`` is not declared ``extern``,
4473 then the ``inline`` keyword is just a hint. In particular, an out-of-line
4474 definition is still emitted for a function with external linkage, even if all
4475 call sites are inlined, unlike in C99 and C++ inline semantics.
4477 * If all declarations that are declared ``inline`` are also declared
4478 ``extern``, then the function body is present only for inlining and no
4479 out-of-line version is emitted.
4481 Some important consequences: ``static inline`` emits an out-of-line
4482 version if needed, a plain ``inline`` definition emits an out-of-line version
4483 always, and an ``extern inline`` definition (in a header) followed by a
4484 (non-``extern``) ``inline`` declaration in a source file emits an out-of-line
4485 version of the function in that source file but provides the function body for
4486 inlining to all includers of the header.
4488 Either ``__GNUC_GNU_INLINE__`` (GNU inline semantics) or
4489 ``__GNUC_STDC_INLINE__`` (C99 semantics) will be defined (they are mutually
4490 exclusive). If ``__GNUC_STDC_INLINE__`` is defined, then the ``gnu_inline``
4491 function attribute can be used to get GNU inline semantics on a per function
4492 basis. If ``__GNUC_GNU_INLINE__`` is defined, then the translation unit is
4493 already being compiled with GNU inline semantics as the implied default. It is
4494 unspecified which macro is defined in a C++ compilation.
4496 GNU inline semantics are the default behavior with ``-std=gnu89``,
4497 ``-std=c89``, ``-std=c94``, or ``-fgnu89-inline``.
4501 def SpeculativeLoadHardeningDocs : Documentation {
4502 let Category = DocCatFunction;
4504 This attribute can be applied to a function declaration in order to indicate
4505 that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
4506 should be enabled for the function body. This can also be applied to a method
4507 in Objective C. This attribute will take precedence over the command line flag in
4508 the case where `-mno-speculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
4510 Speculative Load Hardening is a best-effort mitigation against
4511 information leak attacks that make use of control flow
4512 miss-speculation - specifically miss-speculation of whether a branch
4513 is taken or not. Typically vulnerabilities enabling such attacks are
4514 classified as "Spectre variant #1". Notably, this does not attempt to
4515 mitigate against miss-speculation of branch target, classified as
4516 "Spectre variant #2" vulnerabilities.
4518 When inlining, the attribute is sticky. Inlining a function that
4519 carries this attribute will cause the caller to gain the
4520 attribute. This is intended to provide a maximally conservative model
4521 where the code in a function annotated with this attribute will always
4522 (even after inlining) end up hardened.
4526 def NoSpeculativeLoadHardeningDocs : Documentation {
4527 let Category = DocCatFunction;
4529 This attribute can be applied to a function declaration in order to indicate
4530 that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
4531 is *not* needed for the function body. This can also be applied to a method
4532 in Objective C. This attribute will take precedence over the command line flag in
4533 the case where `-mspeculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
4535 Warning: This attribute may not prevent Speculative Load Hardening from being
4536 enabled for a function which inlines a function that has the
4537 'speculative_load_hardening' attribute. This is intended to provide a
4538 maximally conservative model where the code that is marked with the
4539 'speculative_load_hardening' attribute will always (even when inlined)
4540 be hardened. A user of this attribute may want to mark functions called by
4541 a function they do not want to be hardened with the 'noinline' attribute.
4547 __attribute__((speculative_load_hardening))
4552 // Note: bar() may still have speculative load hardening enabled if
4553 // foo() is inlined into bar(). Mark foo() with __attribute__((noinline))
4554 // to avoid this situation.
4555 __attribute__((no_speculative_load_hardening))
4562 def ObjCExternallyRetainedDocs : Documentation {
4563 let Category = DocCatVariable;
4565 The ``objc_externally_retained`` attribute can be applied to strong local
4566 variables, functions, methods, or blocks to opt into
4567 `externally-retained semantics
4568 <https://clang.llvm.org/docs/AutomaticReferenceCounting.html#externally-retained-variables>`_.
4570 When applied to the definition of a function, method, or block, every parameter
4571 of the function with implicit strong retainable object pointer type is
4572 considered externally-retained, and becomes ``const``. By explicitly annotating
4573 a parameter with ``__strong``, you can opt back into the default
4574 non-externally-retained behavior for that parameter. For instance,
4575 ``first_param`` is externally-retained below, but not ``second_param``:
4577 .. code-block:: objc
4579 __attribute__((objc_externally_retained))
4580 void f(NSArray *first_param, __strong NSArray *second_param) {
4584 Likewise, when applied to a strong local variable, that variable becomes
4585 ``const`` and is considered externally-retained.
4587 When compiled without ``-fobjc-arc``, this attribute is ignored.
4590 def MIGConventionDocs : Documentation {
4591 let Category = DocCatFunction;
4593 The Mach Interface Generator release-on-success convention dictates
4594 functions that follow it to only release arguments passed to them when they
4595 return "success" (a ``kern_return_t`` error code that indicates that
4596 no errors have occurred). Otherwise the release is performed by the MIG client
4597 that called the function. The annotation ``__attribute__((mig_server_routine))``
4598 is applied in order to specify which functions are expected to follow the
4599 convention. This allows the Static Analyzer to find bugs caused by violations of
4600 that convention. The attribute would normally appear on the forward declaration
4601 of the actual server routine in the MIG server header, but it may also be
4602 added to arbitrary functions that need to follow the same convention - for
4603 example, a user can add them to auxiliary functions called by the server routine
4604 that have their return value of type ``kern_return_t`` unconditionally returned
4605 from the routine. The attribute can be applied to C++ methods, and in this case
4606 it will be automatically applied to overrides if the method is virtual. The
4607 attribute can also be written using C++11 syntax: ``[[mig::server_routine]]``.
4611 def MSAllocatorDocs : Documentation {
4612 let Category = DocCatFunction;
4614 The ``__declspec(allocator)`` attribute is applied to functions that allocate
4615 memory, such as operator new in C++. When CodeView debug information is emitted
4616 (enabled by ``clang -gcodeview`` or ``clang-cl /Z7``), Clang will attempt to
4617 record the code offset of heap allocation call sites in the debug info. It will
4618 also record the type being allocated using some local heuristics. The Visual
4619 Studio debugger uses this information to `profile memory usage`_.
4621 .. _profile memory usage: https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage
4623 This attribute does not affect optimizations in any way, unlike GCC's
4624 ``__attribute__((malloc))``.
4628 def CFGuardDocs : Documentation {
4629 let Category = DocCatFunction;
4631 Code can indicate CFG checks are not wanted with the ``__declspec(guard(nocf))``
4632 attribute. This directs the compiler to not insert any CFG checks for the entire
4633 function. This approach is typically used only sparingly in specific situations
4634 where the programmer has manually inserted "CFG-equivalent" protection. The
4635 programmer knows that they are calling through some read-only function table
4636 whose address is obtained through read-only memory references and for which the
4637 index is masked to the function table limit. This approach may also be applied
4638 to small wrapper functions that are not inlined and that do nothing more than
4639 make a call through a function pointer. Since incorrect usage of this directive
4640 can compromise the security of CFG, the programmer must be very careful using
4641 the directive. Typically, this usage is limited to very small functions that
4642 only call one function.
4644 `Control Flow Guard documentation <https://docs.microsoft.com/en-us/windows/win32/secbp/pe-metadata>`
4648 def CUDADeviceBuiltinSurfaceTypeDocs : Documentation {
4649 let Category = DocCatType;
4651 The ``device_builtin_surface_type`` attribute can be applied to a class
4652 template when declaring the surface reference. A surface reference variable
4653 could be accessed on the host side and, on the device side, might be translated
4654 into an internal surface object, which is established through surface bind and
4655 unbind runtime APIs.
4659 def CUDADeviceBuiltinTextureTypeDocs : Documentation {
4660 let Category = DocCatType;
4662 The ``device_builtin_texture_type`` attribute can be applied to a class
4663 template when declaring the texture reference. A texture reference variable
4664 could be accessed on the host side and, on the device side, might be translated
4665 into an internal texture object, which is established through texture bind and
4666 unbind runtime APIs.
4670 def LifetimeOwnerDocs : Documentation {
4671 let Category = DocCatDecl;
4673 .. Note:: This attribute is experimental and its effect on analysis is subject to change in
4674 a future version of clang.
4676 The attribute ``[[gsl::Owner(T)]]`` applies to structs and classes that own an
4677 object of type ``T``:
4681 class [[gsl::Owner(int)]] IntOwner {
4685 int *getInt() { return &value; }
4688 The argument ``T`` is optional and is ignored.
4689 This attribute may be used by analysis tools and has no effect on code
4690 generation. A ``void`` argument means that the class can own any type.
4692 See Pointer_ for an example.
4696 def LifetimePointerDocs : Documentation {
4697 let Category = DocCatDecl;
4699 .. Note:: This attribute is experimental and its effect on analysis is subject to change in
4700 a future version of clang.
4702 The attribute ``[[gsl::Pointer(T)]]`` applies to structs and classes that behave
4703 like pointers to an object of type ``T``:
4707 class [[gsl::Pointer(int)]] IntPointer {
4711 int *getInt() { return &valuePointer; }
4714 The argument ``T`` is optional and is ignored.
4715 This attribute may be used by analysis tools and has no effect on code
4716 generation. A ``void`` argument means that the pointer can point to any type.
4719 When constructing an instance of a class annotated like this (a Pointer) from
4720 an instance of a class annotated with ``[[gsl::Owner]]`` (an Owner),
4721 then the analysis will consider the Pointer to point inside the Owner.
4722 When the Owner's lifetime ends, it will consider the Pointer to be dangling.
4730 P = IntPointer(O); // P "points into" O
4732 return P.get(); // error: Using a dangling Pointer.
4738 def ArmBuiltinAliasDocs : Documentation {
4739 let Category = DocCatFunction;
4741 This attribute is used in the implementation of the ACLE intrinsics.
4742 It allows the intrinsic functions to
4743 be declared using the names defined in ACLE, and still be recognized
4744 as clang builtins equivalent to the underlying name. For example,
4745 ``arm_mve.h`` declares the function ``vaddq_u32`` with
4746 ``__attribute__((__clang_arm_mve_alias(__builtin_arm_mve_vaddq_u32)))``,
4747 and similarly, one of the type-overloaded declarations of ``vaddq``
4748 will have the same attribute. This ensures that both functions are
4749 recognized as that clang builtin, and in the latter case, the choice
4750 of which builtin to identify the function as can be deferred until
4751 after overload resolution.
4753 This attribute can only be used to set up the aliases for certain Arm
4754 intrinsic functions; it is intended for use only inside ``arm_*.h``
4755 and is not a general mechanism for declaring arbitrary aliases for
4756 clang builtin functions.
4760 def NoBuiltinDocs : Documentation {
4761 let Category = DocCatFunction;
4763 .. Note:: This attribute is not yet fully implemented, it is validated but has
4764 no effect on the generated code.
4766 The ``__attribute__((no_builtin))`` is similar to the ``-fno-builtin`` flag
4767 except it is specific to the body of a function. The attribute may also be
4768 applied to a virtual function but has no effect on the behavior of overriding
4769 functions in a derived class.
4771 It accepts one or more strings corresponding to the specific names of the
4772 builtins to disable (e.g. "memcpy", "memset").
4773 If the attribute is used without parameters it will disable all buitins at
4778 // The compiler is not allowed to add any builtin to foo's body.
4779 void foo(char* data, size_t count) __attribute__((no_builtin)) {
4780 // The compiler is not allowed to convert the loop into
4781 // `__builtin_memset(data, 0xFE, count);`.
4782 for (size_t i = 0; i < count; ++i)
4786 // The compiler is not allowed to add the `memcpy` builtin to bar's body.
4787 void bar(char* data, size_t count) __attribute__((no_builtin("memcpy"))) {
4788 // The compiler is allowed to convert the loop into
4789 // `__builtin_memset(data, 0xFE, count);` but cannot generate any
4790 // `__builtin_memcpy`
4791 for (size_t i = 0; i < count; ++i)
4797 def HandleDocs : DocumentationCategory<"Handle Attributes"> {
4799 Handles are a way to identify resources like files, sockets, and processes.
4800 They are more opaque than pointers and widely used in system programming. They
4801 have similar risks such as never releasing a resource associated with a handle,
4802 attempting to use a handle that was already released, or trying to release a
4803 handle twice. Using the annotations below it is possible to make the ownership
4804 of the handles clear: whose responsibility is to release them. They can also
4805 aid static analysis tools to find bugs.
4809 def AcquireHandleDocs : Documentation {
4810 let Category = HandleDocs;
4812 If this annotation is on a function or a function type it is assumed to return
4813 a new handle. In case this annotation is on an output parameter,
4814 the function is assumed to fill the corresponding argument with a new
4819 // Output arguments from Zircon.
4820 zx_status_t zx_socket_create(uint32_t options,
4821 zx_handle_t __attribute__((acquire_handle)) * out0,
4822 zx_handle_t* out1 [[clang::acquire_handle]]);
4826 [[clang::acquire_handle]] int open(const char *path, int oflag, ... );
4827 int open(const char *path, int oflag, ... ) __attribute__((acquire_handle));
4831 def UseHandleDocs : Documentation {
4832 let Category = HandleDocs;
4834 A function taking a handle by value might close the handle. If a function
4835 parameter is annotated with ``use_handle`` it is assumed to not to change
4836 the state of the handle. It is also assumed to require an open handle to work with.
4840 zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle]],
4842 zx_port_packet_t* packet);
4846 def ReleaseHandleDocs : Documentation {
4847 let Category = HandleDocs;
4849 If a function parameter is annotated with ``release_handle`` it is assumed to
4850 close the handle. It is also assumed to require an open handle to work with.
4854 zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle]]);
4858 def ArmMveStrictPolymorphismDocs : Documentation {
4859 let Category = DocCatType;
4861 This attribute is used in the implementation of the ACLE intrinsics for the Arm
4862 MVE instruction set. It is used to define the vector types used by the MVE
4865 Its effect is to modify the behavior of a vector type with respect to function
4866 overloading. If a candidate function for overload resolution has a parameter
4867 type with this attribute, then the selection of that candidate function will be
4868 disallowed if the actual argument can only be converted via a lax vector
4869 conversion. The aim is to prevent spurious ambiguity in ARM MVE polymorphic
4874 void overloaded(uint16x8_t vector, uint16_t scalar);
4875 void overloaded(int32x4_t vector, int32_t scalar);
4876 uint16x8_t myVector;
4879 // myScalar is promoted to int32_t as a side effect of the addition,
4880 // so if lax vector conversions are considered for myVector, then
4881 // the two overloads are equally good (one argument conversion
4882 // each). But if the vector has the __clang_arm_mve_strict_polymorphism
4883 // attribute, only the uint16x8_t,uint16_t overload will match.
4884 overloaded(myVector, myScalar + 1);
4886 However, this attribute does not prohibit lax vector conversions in contexts
4887 other than overloading.
4891 uint16x8_t function();
4893 // This is still permitted with lax vector conversion enabled, even
4894 // if the vector types have __clang_arm_mve_strict_polymorphism
4895 int32x4_t result = function();
4900 def ArmCmseNSCallDocs : Documentation {
4901 let Category = DocCatType;
4903 This attribute declares a non-secure function type. When compiling for secure
4904 state, a call to such a function would switch from secure to non-secure state.
4905 All non-secure function calls must happen only through a function pointer, and
4906 a non-secure function type should only be used as a base type of a pointer.
4907 See `ARMv8-M Security Extensions: Requirements on Development
4908 Tools - Engineering Specification Documentation
4909 <https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information.
4913 def ArmCmseNSEntryDocs : Documentation {
4914 let Category = DocCatFunction;
4916 This attribute declares a function that can be called from non-secure state, or
4917 from secure state. Entering from and returning to non-secure state would switch
4918 to and from secure state, respectively, and prevent flow of information
4919 to non-secure state, except via return values. See `ARMv8-M Security Extensions:
4920 Requirements on Development Tools - Engineering Specification Documentation
4921 <https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information.