diff options
Diffstat (limited to 'include/clang/Basic/AttrDocs.td')
| -rw-r--r-- | include/clang/Basic/AttrDocs.td | 314 |
1 files changed, 276 insertions, 38 deletions
diff --git a/include/clang/Basic/AttrDocs.td b/include/clang/Basic/AttrDocs.td index 5773a92c9c..9990be3364 100644 --- a/include/clang/Basic/AttrDocs.td +++ b/include/clang/Basic/AttrDocs.td @@ -1,9 +1,8 @@ //==--- AttrDocs.td - Attribute documentation ----------------------------===// // -// The LLVM Compiler Infrastructure -// -// This file is distributed under the University of Illinois Open Source -// License. See LICENSE.TXT for details. +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===---------------------------------------------------------------------===// @@ -607,6 +606,7 @@ Query for this feature with ``__has_attribute(diagnose_if)``. def PassObjectSizeDocs : Documentation { let Category = DocCatVariable; // Technically it's a parameter doc, but eh. + let Heading = "pass_object_size, pass_dynamic_object_size"; let Content = [{ .. Note:: The mangling of functions with parameters that are annotated with ``pass_object_size`` is subject to change. You can get around this by @@ -699,6 +699,15 @@ Currently, ``pass_object_size`` is a bit restricted in terms of its usage: * It is an error to apply the ``pass_object_size`` attribute to parameters that are not pointers. Additionally, any parameter that ``pass_object_size`` is applied to must be marked ``const`` at its function's definition. + +Clang also supports the ``pass_dynamic_object_size`` attribute, which behaves +identically to ``pass_object_size``, but evaluates a call to +``__builtin_dynamic_object_size`` at the callee instead of +``__builtin_object_size``. ``__builtin_dynamic_object_size`` provides some extra +runtime checks when the object size can't be determined at compile-time. You can +read more about ``__builtin_dynamic_object_size`` `here +<https://clang.llvm.org/docs/LanguageExtensions.html#evaluating-object-size-dynamically>`_. + }]; } @@ -912,8 +921,6 @@ and Objective-C methods. }]; } - - def NoDebugDocs : Documentation { let Category = DocCatVariable; let Content = [{ @@ -1048,7 +1055,7 @@ implementation of an override in a subclass does not call super. For example: } def ObjCRuntimeNameDocs : Documentation { - let Category = DocCatFunction; + let Category = DocCatDecl; let Content = [{ By default, the Objective-C interface or protocol identifier is used in the metadata name for that object. The `objc_runtime_name` @@ -1069,14 +1076,17 @@ can only be placed before an @protocol or @interface declaration: } def ObjCRuntimeVisibleDocs : Documentation { - let Category = DocCatFunction; + let Category = DocCatDecl; let Content = [{ -This attribute specifies that the Objective-C class to which it applies is visible to the Objective-C runtime but not to the linker. Classes annotated with this attribute cannot be subclassed and cannot have categories defined for them. +This attribute specifies that the Objective-C class to which it applies is +visible to the Objective-C runtime but not to the linker. Classes annotated +with this attribute cannot be subclassed and cannot have categories defined for +them. }]; } def ObjCBoxableDocs : Documentation { - let Category = DocCatFunction; + let Category = DocCatDecl; let Content = [{ Structs and unions marked with the ``objc_boxable`` attribute can be used with the Objective-C boxed expression syntax, ``@(...)``. @@ -1153,11 +1163,14 @@ replacement=\ *string-literal* the deprecated declaration with the new declaration specified. Multiple availability attributes can be placed on a declaration, which may -correspond to different platforms. Only the availability attribute with the -platform corresponding to the target platform will be used; any others will be -ignored. If no availability attribute specifies availability for the current -target platform, the availability attributes are ignored. Supported platforms -are: +correspond to different platforms. For most platforms, the availability +attribute with the platform corresponding to the target platform will be used; +any others will be ignored. However, the availability for ``watchOS`` and +``tvOS`` can be implicitly inferred from an ``iOS`` availability attribute. +Any explicit availability attributes for those platforms are still prefered over +the implicitly inferred availability attributes. If no availability attribute +specifies availability for the current target platform, the availability +attributes are ignored. Supported platforms are: ``ios`` Apple's iOS operating system. The minimum deployment target is specified by @@ -1230,13 +1243,70 @@ Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0)); @end +Availability attributes can also be applied using a ``#pragma clang attribute``. +Any explicit availability attribute whose platform corresponds to the target +platform is applied to a declaration regardless of the availability attributes +specified in the pragma. For example, in the code below, +``hasExplicitAvailabilityAttribute`` will use the ``macOS`` availability +attribute that is specified with the declaration, whereas +``getsThePragmaAvailabilityAttribute`` will use the ``macOS`` availability +attribute that is applied by the pragma. + +.. code-block:: c + + #pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function) + void getsThePragmaAvailabilityAttribute(void); + void hasExplicitAvailabilityAttribute(void) __attribute__((availability(macos,introduced=10.4))); + #pragma clang attribute pop + +For platforms like ``watchOS`` and ``tvOS``, whose availability attributes can +be implicitly inferred from an ``iOS`` availability attribute, the logic is +slightly more complex. The explicit and the pragma-applied availability +attributes whose platform corresponds to the target platform are applied as +described in the previous paragraph. However, the implicitly inferred attributes +are applied to a declaration only when there is no explicit or pragma-applied +availability attribute whose platform corresponds to the target platform. For +example, the function below will receive the ``tvOS`` availability from the +pragma rather than using the inferred ``iOS`` availability from the declaration: + +.. code-block:: c + + #pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function) + void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0))); + #pragma clang attribute pop + +The compiler is also able to apply implicly inferred attributes from a pragma +as well. For example, when targeting ``tvOS``, the function below will receive +a ``tvOS`` availability attribute that is implicitly inferred from the ``iOS`` +availability attribute applied by the pragma: + +.. code-block:: c + + #pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function) + void infersTVOSAvailabilityFromPragma(void); + #pragma clang attribute pop + +The implicit attributes that are inferred from explicitly specified attributes +whose platform corresponds to the target platform are applied to the declaration +even if there is an availability attribute that can be inferred from a pragma. +For example, the function below will receive the ``tvOS, introduced=11.0`` +availability that is inferred from the attribute on the declaration rather than +inferring availability from the pragma: + +.. code-block:: c + + #pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function) + void infersTVOSAvailabilityFromAttributeNextToDeclaration(void) + __attribute__((availability(iOS,introduced=11.0))); + #pragma clang attribute pop + Also see the documentation for `@available <http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_ }]; } def ExternalSourceSymbolDocs : Documentation { - let Category = DocCatFunction; + let Category = DocCatDecl; let Content = [{ The ``external_source_symbol`` attribute specifies that a declaration originates from an external source and describes the nature of that source. @@ -2380,7 +2450,7 @@ behavior of the program is undefined. } def FlagEnumDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ This attribute can be added to an enumerator to signal to the compiler that it is intended to be used as a flag type. This will cause the compiler to assume @@ -2390,7 +2460,7 @@ manipulating bits of the enumerator when issuing warnings. } def EnumExtensibilityDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ Attribute ``enum_extensibility`` is used to distinguish between enum definitions that are extensible and those that are not. The attribute can take either @@ -2439,7 +2509,7 @@ standard and instructs clang to be more lenient when issuing warnings. } def EmptyBasesDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ The empty_bases attribute permits the compiler to utilize the empty-base-optimization more frequently. @@ -2449,7 +2519,7 @@ It is only supported when using the Microsoft C++ ABI. } def LayoutVersionDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ The layout_version attribute requests that the compiler utilize the class layout rules of a particular compiler version. @@ -2475,7 +2545,7 @@ changes. } def TrivialABIDocs : Documentation { - let Category = DocCatVariable; + let Category = DocCatDecl; let Content = [{ The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union. It instructs the compiler to pass and return the type using the C ABI for the @@ -2517,7 +2587,7 @@ Attribute ``trivial_abi`` has no effect in the following cases: } def MSInheritanceDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Heading = "__single_inhertiance, __multiple_inheritance, __virtual_inheritance"; let Content = [{ This collection of keywords is enabled under ``-fms-extensions`` and controls @@ -2564,7 +2634,7 @@ an error: } def MSNoVTableDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ This attribute can be added to a class declaration or definition to signal to the compiler that constructors and destructors will not reference the virtual @@ -2705,8 +2775,6 @@ def PipelineHintDocs : Documentation { }]; } - - def OpenCLUnrollHintDocs : Documentation { let Category = DocCatStmt; let Content = [{ @@ -3276,7 +3344,7 @@ jumps from i386 arch code). }]; } -def AnyX86NoCfCheckDocs : Documentation{ +def AnyX86NoCfCheckDocs : Documentation { let Category = DocCatFunction; let Content = [{ Jump Oriented Programming attacks rely on tampering with addresses used by @@ -3544,7 +3612,7 @@ experimental at this time. } def DeprecatedDocs : Documentation { - let Category = DocCatFunction; + let Category = DocCatDecl; let Content = [{ The ``deprecated`` attribute can be applied to a function, a variable, or a type. This is useful when identifying functions, variables, or types that are @@ -3579,7 +3647,7 @@ Not all targets support this attribute. ELF target support depends on both the l } def LTOVisibilityDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ See :doc:`LTOVisibility`. }]; @@ -3615,7 +3683,7 @@ If a function has neither of these attributes, they become subject to the XRay h } def TransparentUnionDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ This attribute can be applied to a union to change the behaviour of calls to functions that have an argument with a transparent union type. The compiler @@ -3633,16 +3701,29 @@ Transparent unions are not supported in C++. } def ObjCSubclassingRestrictedDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ This attribute can be added to an Objective-C ``@interface`` declaration to ensure that this class cannot be subclassed. }]; } +def ObjCNonLazyClassDocs : Documentation { + let Category = DocCatDecl; + let Content = [{ +This attribute can be added to an Objective-C ``@interface`` or +``@implementation`` declaration to add the class to the list of non-lazily +initialized classes. A non-lazy class will be initialized eagerly when the +Objective-C runtime is loaded. This is required for certain system classes which +have instances allocated in non-standard ways, such as the classes for blocks +and constant strings. Adding this attribute is essentially equivalent to +providing a trivial `+load` method but avoids the (fairly small) load-time +overheads associated with defining and calling such a method. + }]; +} def SelectAnyDocs : Documentation { - let Category = DocCatType; + let Category = DocCatDecl; let Content = [{ This attribute appertains to a global symbol, causing it to have a weak definition ( @@ -3652,7 +3733,40 @@ definition ( For more information see `gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_ or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_. -}]; +}]; } + +def WebAssemblyImportModuleDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +Clang supports the ``__attribute__((import_module(<module_name>)))`` +attribute for the WebAssembly target. This attribute may be attached to a +function declaration, where it modifies how the symbol is to be imported +within the WebAssembly linking environment. + +WebAssembly imports use a two-level namespace scheme, consisting of a module +name, which typically identifies a module from which to import, and a field +name, which typically identifies a field from that module to import. By +default, module names for C/C++ symbols are assigned automatically by the +linker. This attribute can be used to override the default behavior, and +reuqest a specific module name be used instead. + }]; +} + +def WebAssemblyImportNameDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +Clang supports the ``__attribute__((import_name(<name>)))`` +attribute for the WebAssembly target. This attribute may be attached to a +function declaration, where it modifies how the symbol is to be imported +within the WebAssembly linking environment. + +WebAssembly imports use a two-level namespace scheme, consisting of a module +name, which typically identifies a module from which to import, and a field +name, which typically identifies a field from that module to import. By +default, field names for C/C++ symbols are the same as their C/C++ symbol +names. This attribute can be used to override the default behavior, and +reuqest a specific field name be used instead. + }]; } def ArtificialDocs : Documentation { @@ -3781,6 +3895,55 @@ it rather documents the programmer's intent. }]; } +def CallbackDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +The ``callback`` attribute specifies that the annotated function may invoke the +specified callback zero or more times. The callback, as well as the passed +arguments, are identified by their parameter name or position (starting with +1!) in the annotated function. The first position in the attribute identifies +the callback callee, the following positions declare describe its arguments. +The callback callee is required to be callable with the number, and order, of +the specified arguments. The index `0`, or the identifier `this`, is used to +represent an implicit "this" pointer in class methods. If there is no implicit +"this" pointer it shall not be referenced. The index '-1', or the name "__", +represents an unknown callback callee argument. This can be a value which is +not present in the declared parameter list, or one that is, but is potentially +inspected, captured, or modified. Parameter names and indices can be mixed in +the callback attribute. + +The ``callback`` attribute, which is directly translated to ``callback`` +metadata <http://llvm.org/docs/LangRef.html#callback-metadata>, make the +connection between the call to the annotated function and the callback callee. +This can enable interprocedural optimizations which were otherwise impossible. +If a function parameter is mentioned in the ``callback`` attribute, through its +position, it is undefined if that parameter is used for anything other than the +actual callback. Inspected, captured, or modified parameters shall not be +listed in the ``callback`` metadata. + +Example encodings for the callback performed by `pthread_create` are shown +below. The explicit attribute annotation indicates that the third parameter +(`start_routine`) is called zero or more times by the `pthread_create` function, +and that the fourth parameter (`arg`) is passed along. Note that the callback +behavior of `pthread_create` is automatically recognized by Clang. In addition, +the declarations of `__kmpc_fork_teams` and `__kmpc_fork_call`, generated for +`#pragma omp target teams` and `#pragma omp parallel`, respectively, are also +automatically recognized as broker functions. Further functions might be added +in the future. + + .. code-block:: c + + __attribute__((callback (start_routine, arg))) + int pthread_create(pthread_t *thread, const pthread_attr_t *attr, + void *(*start_routine) (void *), void *arg); + + __attribute__((callback (3, 4))) + int pthread_create(pthread_t *thread, const pthread_attr_t *attr, + void *(*start_routine) (void *), void *arg); + + }]; +} + def GnuInlineDocs : Documentation { let Category = DocCatFunction; let Content = [{ @@ -3788,13 +3951,13 @@ The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline semantics, meaning: * If any declaration that is declared ``inline`` is not declared ``extern``, -then the ``inline`` keyword is just a hint. In particular, an out-of-line -definition is still emitted for a function with external linkage, even if all -call sites are inlined, unlike in C99 and C++ inline semantics. + then the ``inline`` keyword is just a hint. In particular, an out-of-line + definition is still emitted for a function with external linkage, even if all + call sites are inlined, unlike in C99 and C++ inline semantics. * If all declarations that are declared ``inline`` are also declared -``extern``, then the function body is present only for inlining and no -out-of-line version is emitted. + ``extern``, then the function body is present only for inlining and no + out-of-line version is emitted. Some important consequences: ``static inline`` emits an out-of-line version if needed, a plain ``inline`` definition emits an out-of-line version @@ -3822,7 +3985,8 @@ def SpeculativeLoadHardeningDocs : Documentation { This attribute can be applied to a function declaration in order to indicate that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_ should be enabled for the function body. This can also be applied to a method - in Objective C. + in Objective C. This attribute will take precedence over the command line flag in + the case where `-mno-speculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified. Speculative Load Hardening is a best-effort mitigation against information leak attacks that make use of control flow @@ -3840,6 +4004,42 @@ def SpeculativeLoadHardeningDocs : Documentation { }]; } +def NoSpeculativeLoadHardeningDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ + This attribute can be applied to a function declaration in order to indicate + that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_ + is *not* needed for the function body. This can also be applied to a method + in Objective C. This attribute will take precedence over the command line flag in + the case where `-mspeculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified. + + Warning: This attribute may not prevent Speculative Load Hardening from being + enabled for a function which inlines a function that has the + 'speculative_load_hardening' attribute. This is intended to provide a + maximally conservative model where the code that is marked with the + 'speculative_load_hardening' attribute will always (even when inlined) + be hardened. A user of this attribute may want to mark functions called by + a function they do not want to be hardened with the 'noinline' attribute. + + For example: + + .. code-block:: c + + __attribute__((speculative_load_hardening)) + int foo(int i) { + return i; + } + + // Note: bar() may still have speculative load hardening enabled if + // foo() is inlined into bar(). Mark foo() with __attribute__((noinline)) + // to avoid this situation. + __attribute__((no_speculative_load_hardening)) + int bar(int i) { + return foo(i); + } + }]; +} + def ObjCExternallyRetainedDocs : Documentation { let Category = DocCatVariable; let Content = [{ @@ -3867,3 +4067,41 @@ Likewise, when applied to a strong local variable, that variable becomes When compiled without ``-fobjc-arc``, this attribute is ignored. }]; } + +def MIGConventionDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ + The Mach Interface Generator release-on-success convention dictates +functions that follow it to only release arguments passed to them when they +return "success" (a ``kern_return_t`` error code that indicates that +no errors have occured). Otherwise the release is performed by the MIG client +that called the function. The annotation ``__attribute__((mig_server_routine))`` +is applied in order to specify which functions are expected to follow the +convention. This allows the Static Analyzer to find bugs caused by violations of +that convention. The attribute would normally appear on the forward declaration +of the actual server routine in the MIG server header, but it may also be +added to arbitrary functions that need to follow the same convention - for +example, a user can add them to auxiliary functions called by the server routine +that have their return value of type ``kern_return_t`` unconditionally returned +from the routine. The attribute can be applied to C++ methods, and in this case +it will be automatically applied to overrides if the method is virtual. The +attribute can also be written using C++11 syntax: ``[[mig::server_routine]]``. +}]; +} + +def MSAllocatorDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +The ``__declspec(allocator)`` attribute is applied to functions that allocate +memory, such as operator new in C++. When CodeView debug information is emitted +(enabled by ``clang -gcodeview`` or ``clang-cl /Z7``), Clang will attempt to +record the code offset of heap allocation call sites in the debug info. It will +also record the type being allocated using some local heuristics. The Visual +Studio debugger uses this information to `profile memory usage`_. + +.. _profile memory usage: https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage + +This attribute does not affect optimizations in any way, unlike GCC's +``__attribute__((malloc))``. +}]; +} |