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