__has_builtin¶

This function-like macro takes a single identifier argument that is the name ofa builtin function, a builtin pseudo-function (taking one or more typearguments), or a builtin template.It evaluates to 1 if the builtin is supported or 0 if not.It can be used like this:

#ifndef __has_builtin// Optional of course.#define __has_builtin(x) 0// Compatibility with non-clang compilers.#endif...#if __has_builtin(__builtin_trap)__builtin_trap();#elseabort();#endif...

__has_feature and__has_extension¶

These function-like macros take a single identifier argument that is the nameof a feature.__has_feature evaluates to 1 if the feature is bothsupported by Clang and standardized in the current language standard or 0 ifnot (but seebelow), while__has_extension evaluates to 1 if the feature is supported by Clang in thecurrent language (either as a language extension or a standard languagefeature) or 0 if not. They can be used like this:

#ifndef __has_feature// Optional of course.#define __has_feature(x) 0// Compatibility with non-clang compilers.#endif#ifndef __has_extension#define __has_extension __has_feature// Compatibility with pre-3.0 compilers.#endif...#if __has_feature(cxx_rvalue_references)// This code will only be compiled with the -std=c++11 and -std=gnu++11// options, because rvalue references are only standardized in C++11.#endif#if __has_extension(cxx_rvalue_references)// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98// and -std=gnu++98 options, because rvalue references are supported as a// language extension in C++98.#endif

For backward compatibility,__has_feature can also be used to testfor support for non-standardized features, i.e. features not prefixedc_,cxx_ orobjc_.

Another use of__has_feature is to check for compiler features not relatedto the language standard, such as e.g.AddressSanitizer.

If the-pedantic-errors option is given,__has_extension is equivalentto__has_feature.

The feature tag is described along with the language feature below.

The feature name or extension name can also be specified with a preceding andfollowing__ (double underscore) to avoid interference from a macro withthe same name. For instance,__cxx_rvalue_references__ can be used insteadofcxx_rvalue_references.

__has_cpp_attribute¶

This function-like macro is available in C++20 by default, and is provided as anextension in earlier language standards. It takes a single argument that is thename of a double-square-bracket-style attribute. The argument can either be asingle identifier or a scoped identifier. If the attribute is supported, anonzero value is returned. If the attribute is a standards-based attribute, thismacro returns a nonzero value based on the year and month in which the attributewas voted into the working draft. SeeWG21 SD-6for the list of values returned for standards-based attributes. If the attributeis not supported by the current compilation target, this macro evaluates to 0.It can be used like this:

#ifndef __has_cpp_attribute// For backwards compatibility#define __has_cpp_attribute(x) 0#endif...#if __has_cpp_attribute(clang::fallthrough)#define FALLTHROUGH [[clang::fallthrough]]#else#define FALLTHROUGH#endif...

The attribute scope tokensclang and_Clang are interchangeable, as arethe attribute scope tokensgnu and__gnu__. Attribute tokens in eitherof these namespaces can be specified with a preceding and following__(double underscore) to avoid interference from a macro with the same name. Forinstance,gnu::__const__ can be used instead ofgnu::const.

__has_c_attribute¶

This function-like macro takes a single argument that is the name of anattribute exposed with the double square-bracket syntax in C mode. The argumentcan either be a single identifier or a scoped identifier. If the attribute issupported, a nonzero value is returned. If the attribute is not supported by thecurrent compilation target, this macro evaluates to 0. It can be used like this:

#ifndef __has_c_attribute// Optional of course.#define __has_c_attribute(x) 0// Compatibility with non-clang compilers.#endif...#if __has_c_attribute(fallthrough)#define FALLTHROUGH [[fallthrough]]#else#define FALLTHROUGH#endif...

The attribute scope tokensclang and_Clang are interchangeable, as arethe attribute scope tokensgnu and__gnu__. Attribute tokens in eitherof these namespaces can be specified with a preceding and following__(double underscore) to avoid interference from a macro with the same name. Forinstance,gnu::__const__ can be used instead ofgnu::const.

__has_attribute¶

This function-like macro takes a single identifier argument that is the name ofa GNU-style attribute. It evaluates to 1 if the attribute is supported by thecurrent compilation target, or 0 if not. It can be used like this:

#ifndef __has_attribute// Optional of course.#define __has_attribute(x) 0// Compatibility with non-clang compilers.#endif...#if __has_attribute(always_inline)#define ALWAYS_INLINE __attribute__((always_inline))#else#define ALWAYS_INLINE#endif...

The attribute name can also be specified with a preceding and following__(double underscore) to avoid interference from a macro with the same name. Forinstance,__always_inline__ can be used instead ofalways_inline.

__has_declspec_attribute¶

This function-like macro takes a single identifier argument that is the name ofan attribute implemented as a Microsoft-style__declspec attribute. Itevaluates to 1 if the attribute is supported by the current compilation target,or 0 if not. It can be used like this:

#ifndef __has_declspec_attribute// Optional of course.#define __has_declspec_attribute(x) 0// Compatibility with non-clang compilers.#endif...#if __has_declspec_attribute(dllexport)#define DLLEXPORT __declspec(dllexport)#else#define DLLEXPORT#endif...

The attribute name can also be specified with a preceding and following__(double underscore) to avoid interference from a macro with the same name. Forinstance,__dllexport__ can be used instead ofdllexport.

__is_identifier¶

This function-like macro takes a single identifier argument that might be eithera reserved word or a regular identifier. It evaluates to 1 if the argument is justa regular identifier and not a reserved word, in the sense that it can then beused as the name of a user-defined function or variable. Otherwise it evaluatesto 0. It can be used like this:

...#ifdef __is_identifier// Compatibility with non-clang compilers.#if __is_identifier(__wchar_t)typedefwchar_t__wchar_t;#endif#endif__wchar_tWideCharacter;...

__has_include¶

This function-like macro takes a single file name string argument that is thename of an include file. It evaluates to 1 if the file can be found using theinclude paths, or 0 otherwise:

// Note the two possible file name string formats.#if __has_include("myinclude.h") && __has_include(<stdint.h>)#include"myinclude.h"#endif

To test for this feature, use#ifdefined(__has_include):

// To avoid problem with non-clang compilers not having this macro.#if defined(__has_include)#if __has_include("myinclude.h")#include"myinclude.h"#endif#endif

__has_include_next¶

This function-like macro takes a single file name string argument that is thename of an include file. It is like__has_include except that it looks forthe second instance of the given file found in the include paths. It evaluatesto 1 if the second instance of the file can be found using the include paths,or 0 otherwise:

// Note the two possible file name string formats.#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)# include_next "myinclude.h"#endif// To avoid problem with non-clang compilers not having this macro.#if defined(__has_include_next)#if __has_include_next("myinclude.h")# include_next "myinclude.h"#endif#endif

Note that__has_include_next, like the GNU extension#include_nextdirective, is intended for use in headers only, and will issue a warning ifused in the top-level compilation file. A warning will also be issued if anabsolute path is used in the file argument.

__has_warning¶

This function-like macro takes a string literal that represents a command lineoption for a warning and returns true if that is a valid warning option.

#if __has_warning("-Wformat")...#endif

Boolean Vectors¶

Clang also supports the ext_vector_type attribute with boolean element types inC and C++. For example:

// legal for Clang, error for GCC:typedefboolbool4__attribute__((ext_vector_type(4)));// Objects of bool4 type hold 8 bits, sizeof(bool4) == 1bool4foo(bool4a){bool4v;v=a;returnv;}

Boolean vectors are a Clang extension of the ext vector type. Boolean vectorsare intended, though not guaranteed, to map to vector mask registers. The sizeparameter of a boolean vector type is the number of bits in the vector. Theboolean vector is dense and each bit in the boolean vector is one vectorelement.

The semantics of boolean vectors borrows from C bit-fields with the followingdifferences:

• Distinct boolean vectors are always distinct memory objects (there is nopacking).

• Only the operators?:,!,~,|,&,^ and comparison are allowed onboolean vectors.

• Casting a scalar bool value to a boolean vector type means broadcasting thescalar value onto all lanes (same as general ext_vector_type).

• It is not possible to access or swizzle elements of a boolean vector(different than general ext_vector_type).

The size and alignment are both the number of bits rounded up to the next powerof two, but the alignment is at most the maximum vector alignment of thetarget.

Vector Literals¶

Vector literals can be used to create vectors from a set of scalars, orvectors. Either parentheses or braces form can be used. In the parenthesesform the number of literal values specified must be one, i.e. referring to ascalar value, or must match the size of the vector type being created. If asingle scalar literal value is specified, the scalar literal value will bereplicated to all the components of the vector type. In the brackets form anynumber of literals can be specified. For example:

typedefintv4si__attribute__((__vector_size__(16)));typedeffloatfloat4__attribute__((ext_vector_type(4)));typedeffloatfloat2__attribute__((ext_vector_type(2)));v4sivsi=(v4si){1,2,3,4};float4vf=(float4)(1.0f,2.0f,3.0f,4.0f);vectorintvi1=(vectorint)(1);// vi1 will be (1, 1, 1, 1).vectorintvi2=(vectorint){1};// vi2 will be (1, 0, 0, 0).vectorintvi3=(vectorint)(1,2);// errorvectorintvi4=(vectorint){1,2};// vi4 will be (1, 2, 0, 0).vectorintvi5=(vectorint)(1,2,3,4);float4vf=(float4)((float2)(1.0f,2.0f),(float2)(3.0f,4.0f));

Vector Operations¶

The table below shows the support for each operation by vector extension. Adash indicates that an operation is not accepted according to a correspondingspecification.

See also__builtin_shufflevector,__builtin_convertvector.

1

ternary operator(?:) has different behaviors depending on conditionoperand’s vector type. If the condition is a GNU vector (i.e. __vector_size__),a NEON vector or an SVE vector, it’s only available in C++ and uses normal boolconversions (that is, != 0).If it’s an extension (OpenCL) vector, it’s only available in C and OpenCL C.And it selects base on signedness of the condition operands (OpenCL v1.1 s6.3.9).

2

sizeof can only be used on vector length specific SVE types.

3

Clang does not allow the address of an element to be taken while GCCallows this. This is intentional for vectors with a boolean element type andnot implemented otherwise.

Vector Builtins¶

Note: The implementation of vector builtins is work-in-progress and incomplete.

In addition to the operators mentioned above, Clang provides a set of builtinsto perform additional operations on certain scalar and vector types.

LetT be one of the following types:

• an integer type (as in C2x 6.2.5p19), but excluding enumerated types and _Bool

• the standard floating types float or double

• a half-precision floating point type, if one is supported on the target

• a vector type.

For scalar types, consider the operation applied to a vector with a single element.

Elementwise Builtins

Each builtin returns a vector equivalent to applying the specified operationelementwise to the input.

Unless specified otherwise operation(±0) = ±0 and operation(±infinity) = ±infinity

Reduction Builtins

Each builtin returns a scalar equivalent to applying the specifiedoperation(x, y) as recursive even-odd pairwise reduction to all vectorelements.operation(x,y) is repeatedly applied to each non-overlappingeven-odd element pair with indicesi*2 andi*2+1 withiin[0,Numberofelements/2). If the numbers of elements is not apower of 2, the vector is widened with neutral elements for the reductionat the end to the next power of 2.

Example:

__builtin_reduce_add([e3,e2,e1,e0])=__builtin_reduced_add([e3+e2,e1+e0])=(e3+e2)+(e1+e0)

LetVT be a vector type andET the element type ofVT.

C++98¶

The features listed below are part of the C++98 standard. These features areenabled by default when compiling C++ code.

C++11¶

The features listed below are part of the C++11 standard. As a result, allthese features are enabled with the-std=c++11 or-std=gnu++11 optionwhen compiling C++ code.

C++14¶

The features listed below are part of the C++14 standard. As a result, allthese features are enabled with the-std=C++14 or-std=gnu++14 optionwhen compiling C++ code.

C11¶

The features listed below are part of the C11 standard. As a result, all thesefeatures are enabled with the-std=c11 or-std=gnu11 option whencompiling C code. Additionally, because these features are allbackward-compatible, they are available as extensions in all language modes.

Modules¶

Use__has_feature(modules) to determine if Modules have been enabled.For example, compiling code with-fmodules enables the use of Modules.

More information could be foundhere.

Related result types¶

According to Cocoa conventions, Objective-C methods with certain names(“init”, “alloc”, etc.) always return objects that are an instance ofthe receiving class’s type. Such methods are said to have a “related resulttype”, meaning that a message send to one of these methods will have the samestatic type as an instance of the receiver class. For example, given thefollowing classes:

@interfaceNSObject+(id)alloc;-(id)init;@end@interfaceNSArray :NSObject@end

and this common initialization pattern

NSArray*array=[[NSArrayalloc]init];

the type of the expression[NSArrayalloc] isNSArray* becausealloc implicitly has a related result type. Similarly, the type of theexpression[[NSArrayalloc]init] isNSArray*, sinceinit has arelated result type and its receiver is known to have the typeNSArray*.If neitheralloc norinit had a related result type, the expressionswould have had typeid, as declared in the method signature.

A method with a related result type can be declared by using the typeinstancetype as its result type.instancetype is a contextual keywordthat is only permitted in the result type of an Objective-C method, e.g.

@interfaceA+(instancetype)constructAnA;@end

The related result type can also be inferred for some methods. To determinewhether a method has an inferred related result type, the first word in thecamel-case selector (e.g., “init” in “initWithObjects”) is considered,and the method will have a related result type if its return type is compatiblewith the type of its class and if:

• the first word is “alloc” or “new”, and the method is a class method,or

• the first word is “autorelease”, “init”, “retain”, or “self”,and the method is an instance method.

If a method with a related result type is overridden by a subclass method, thesubclass method must also return a type that is compatible with the subclasstype. For example:

@interfaceNSString :NSObject-(NSUnrelated*)init;// incorrect usage: NSUnrelated is not NSString or a superclass of NSString@end

Related result types only affect the type of a message send or property accessvia the given method. In all other respects, a method with a related resulttype is treated the same way as method that returnsid.

Use__has_feature(objc_instancetype) to determine whether theinstancetype contextual keyword is available.

Automatic reference counting¶

Clang provides support forautomated reference counting in Objective-C, which eliminates the needfor manualretain/release/autorelease message sends. There are threefeature macros associated with automatic reference counting:__has_feature(objc_arc) indicates the availability of automated referencecounting in general, while__has_feature(objc_arc_weak) indicates thatautomated reference counting also includes support for__weak pointers toObjective-C objects.__has_feature(objc_arc_fields) indicates that C structsare allowed to have fields that are pointers to Objective-C objects managed byautomatic reference counting.

Weak references¶

Clang supports ARC-style weak and unsafe references in Objective-C evenoutside of ARC mode. Weak references must be explicitly enabled withthe-fobjc-weak option; use__has_feature((objc_arc_weak))to test whether they are enabled. Unsafe references are enabledunconditionally. ARC-style weak and unsafe references cannot be usedwhen Objective-C garbage collection is enabled.

Except as noted below, the language rules for the__weak and__unsafe_unretained qualifiers (and theweak andunsafe_unretained property attributes) are just as laid outin theARC specification.In particular, note that some classes do not support forming weakreferences to their instances, and note that special care must betaken when storing weak references in memory where initializationand deinitialization are outside the responsibility of the compiler(such as inmalloc-ed memory).

Loading from a__weak variable always implicitly retains theloaded value. In non-ARC modes, this retain is normally balancedby an implicit autorelease. This autorelease can be suppressedby performing the load in the receiver position of a-retainmessage send (e.g.[weakReferenceretain]); note that this performsonly a single retain (the retain done when primitively loading fromthe weak reference).

For the most part,__unsafe_unretained in non-ARC modes is just thedefault behavior of variables and therefore is not needed. However,it does have an effect on the semantics of block captures: normally,copying a block which captures an Objective-C object or block pointercauses the captured pointer to be retained or copied, respectively,but that behavior is suppressed when the captured variable is qualifiedwith__unsafe_unretained.

Note that the__weak qualifier formerly meant the GC qualifier inall non-ARC modes and was silently ignored outside of GC modes. It nowmeans the ARC-style qualifier in all non-GC modes and is no longerallowed if not enabled by either-fobjc-arc or-fobjc-weak.It is expected that-fobjc-weak will eventually be enabled by defaultin all non-GC Objective-C modes.

Enumerations with a fixed underlying type¶

Clang provides support for C++11 enumerations with a fixed underlying typewithin Objective-C. For example, one can write an enumeration type as:

typedefenum:unsignedchar{Red,Green,Blue}Color;

This specifies that the underlying type, which is used to store the enumerationvalue, isunsignedchar.

Use__has_feature(objc_fixed_enum) to determine whether support for fixedunderlying types is available in Objective-C.

Interoperability with C++11 lambdas¶

Clang provides interoperability between C++11 lambdas and blocks-based APIs, bypermitting a lambda to be implicitly converted to a block pointer with thecorresponding signature. For example, consider an API such asNSArray’sarray-sorting method:

-(NSArray*)sortedArrayUsingComparator:(NSComparator)cmptr;

NSComparator is simply a typedef for the block pointerNSComparisonResult(^)(id,id), and parameters of this type are generally provided with blockliterals as arguments. However, one can also use a C++11 lambda so long as itprovides the same signature (in this case, accepting two parameters of typeid and returning anNSComparisonResult):

NSArray*array=@[@"string 1",@"string 21",@"string 12",@"String 11",@"String 02"];constNSStringCompareOptionscomparisonOptions=NSCaseInsensitiveSearch|NSNumericSearch|NSWidthInsensitiveSearch|NSForcedOrderingSearch;NSLocale*currentLocale=[NSLocalecurrentLocale];NSArray*sorted=[arraysortedArrayUsingComparator:[=](ids1,ids2)->NSComparisonResult{NSRangestring1Range=NSMakeRange(0,[s1length]);return[s1compare:s2options:comparisonOptionsrange:string1Rangelocale:currentLocale];}];NSLog(@"sorted: %@",sorted);

This code relies on an implicit conversion from the type of the lambdaexpression (an unnamed, local class type called theclosure type) to thecorresponding block pointer type. The conversion itself is expressed by aconversion operator in that closure type that produces a block pointer with thesame signature as the lambda itself, e.g.,

operatorNSComparisonResult(^)(id,id)()const;

This conversion function returns a new block that simply forwards the twoparameters to the lambda object (which it captures by copy), then returns theresult. The returned block is first copied (withBlock_copy) and thenautoreleased. As an optimization, if a lambda expression is immediatelyconverted to a block pointer (as in the first example, above), then the blockis not copied and autoreleased: rather, it is given the same lifetime as ablock literal written at that point in the program, which avoids the overheadof copying a block to the heap in the common case.

The conversion from a lambda to a block pointer is only available inObjective-C++, and not in C++ with blocks, due to its use of Objective-C memorymanagement (autorelease).

Object Literals and Subscripting¶

Clang provides support forObject Literals and Subscripting in Objective-C, which simplifies common Objective-Cprogramming patterns, makes programs more concise, and improves the safety ofcontainer creation. There are several feature macros associated with objectliterals and subscripting:__has_feature(objc_array_literals) tests theavailability of array literals;__has_feature(objc_dictionary_literals)tests the availability of dictionary literals;__has_feature(objc_subscripting) tests the availability of objectsubscripting.

Objective-C Autosynthesis of Properties¶

Clang provides support for autosynthesis of declared properties. Using thisfeature, clang provides default synthesis of those properties not declared@dynamic and not having user provided backing getter and setter methods.__has_feature(objc_default_synthesize_properties) checks for availabilityof this feature in version of clang being used.

Objective-C retaining behavior attributes¶

In Objective-C, functions and methods are generally assumed to follow theCocoa Memory Managementconventions for ownership of object arguments andreturn values. However, there are exceptions, and so Clang provides attributesto allow these exceptions to be documented. This are used by ARC and thestatic analyzer Some exceptions may bebetter described using theobjc_method_family attribute instead.

Usage: Thens_returns_retained,ns_returns_not_retained,ns_returns_autoreleased,cf_returns_retained, andcf_returns_not_retained attributes can be placed on methods and functionsthat return Objective-C or CoreFoundation objects. They are commonly placed atthe end of a function prototype or method declaration:

idfoo()__attribute__((ns_returns_retained));-(NSString*)bar:(int)x__attribute__((ns_returns_retained));

The*_returns_retained attributes specify that the returned object has a +1retain count. The*_returns_not_retained attributes specify that the returnobject has a +0 retain count, even if the normal convention for its selectorwould be +1.ns_returns_autoreleased specifies that the returned object is+0, but is guaranteed to live at least as long as the next flush of anautorelease pool.

Usage: Thens_consumed andcf_consumed attributes can be placed onan parameter declaration; they specify that the argument is expected to have a+1 retain count, which will be balanced in some way by the function or method.Thens_consumes_self attribute can only be placed on an Objective-Cmethod; it specifies that the method expects itsself parameter to have a+1 retain count, which it will balance in some way.

voidfoo(__attribute__((ns_consumed))NSString*string);-(void)bar__attribute__((ns_consumes_self));-(void)baz:(id)__attribute__((ns_consumed))x;

Further examples of these attributes are available in the static analyzer’slist of annotations for analysis.

Query for these features with__has_attribute(ns_consumed),__has_attribute(ns_returns_retained), etc.

Objective-C @available¶

It is possible to use the newest SDK but still build a program that can run onolder versions of macOS and iOS by passing-mmacosx-version-min= /-miphoneos-version-min=.

Before LLVM 5.0, when calling a function that exists only in the OS that’snewer than the target OS (as determined by the minimum deployment version),programmers had to carefully check if the function exists at runtime, usingnull checks for weakly-linked C functions,+class for Objective-C classes,and-respondsToSelector: or+instancesRespondToSelector: forObjective-C methods. If such a check was missed, the program would compilefine, run fine on newer systems, but crash on older systems.

As of LLVM 5.0,-Wunguarded-availability uses theavailability attributes togetherwith the new@available() keyword to assist with this issue.When a method that’s introduced in the OS newer than the target OS is called, a-Wunguarded-availability warning is emitted if that call is not guarded:

voidmy_fun(NSSomeClass*var){// If fancyNewMethod was added in e.g. macOS 10.12, but the code is// built with -mmacosx-version-min=10.11, then this unconditional call// will emit a -Wunguarded-availability warning:[varfancyNewMethod];}

To fix the warning and to avoid the crash on macOS 10.11, wrap it inif(@available()):

voidmy_fun(NSSomeClass*var){if(@available(macOS10.12,*)){[varfancyNewMethod];}else{// Put fallback behavior for old macOS versions (and for non-mac// platforms) here.}}

The* is required and means that platforms not explicitly listed will takethe true branch, and the compiler will emit-Wunguarded-availabilitywarnings for unlisted platforms based on those platform’s deployment target.More than one platform can be listed in@available():

voidmy_fun(NSSomeClass*var){if(@available(macOS10.12,iOS10,*)){[varfancyNewMethod];}}

If the caller ofmy_fun() already checks thatmy_fun() is only calledon 10.12, then add anavailability attribute to it,which will also suppress the warning and require that calls to my_fun() arechecked:

API_AVAILABLE(macos(10.12))voidmy_fun(NSSomeClass*var){[varfancyNewMethod];// Now ok.}

@available() is only available in Objective-C code. To use the featurein C and C++ code, use the__builtin_available() spelling instead.

If existing code uses null checks or-respondsToSelector:, it shouldbe changed to use@available() (or__builtin_available) instead.

-Wunguarded-availability is disabled by default, but-Wunguarded-availability-new, which only emits this warning for APIsthat have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 andtvOS >= 11, is enabled by default.

Objective-C++ ABI: protocol-qualifier mangling of parameters¶

Starting with LLVM 3.4, Clang produces a new mangling for parameters whosetype is a qualified-id (e.g.,id<Foo>). This mangling allows suchparameters to be differentiated from those with the regular unqualifiedidtype.

This was a non-backward compatible mangling change to the ABI. This changeallows proper overloading, and also prevents mangling conflicts with templateparameters of protocol-qualified type.

Query the presence of this new mangling with__has_feature(objc_protocol_qualifier_mangling).

__cl_clang_bitfields¶

With this extension it is possible to enable bitfields in structsor unions using the OpenCL extension pragma mechanism detailed inthe OpenCL Extension Specification, section 1.2.

Use of bitfields in OpenCL kernels can result in reduced portability as structlayout is not guaranteed to be consistent when compiled by different compilers.If structs with bitfields are used as kernel function parameters, it can resultin incorrect functionality when the layout is different between the host anddevice code.

Example of Use:

#pragma OPENCL EXTENSION __cl_clang_bitfields : enablestructwith_bitfield{unsignedinti:5;// compiled - no diagnostic generated};#pragma OPENCL EXTENSION __cl_clang_bitfields : disablestructwithout_bitfield{unsignedinti:5;// error - bitfields are not supported};

__cl_clang_function_pointers¶

With this extension it is possible to enable various language features thatare relying on function pointers using regular OpenCL extension pragmamechanism detailed inthe OpenCL Extension Specification,section 1.2.

In C++ for OpenCL this also enables:

• Use of member function pointers;

• Unrestricted use of references to functions;

• Virtual member functions.

Such functionality is not conformant and does not guarantee to compilecorrectly in any circumstances. It can be used if:

• the kernel source does not contain call expressions to (member-) functionpointers, or virtual functions. For example this extension can be used inmetaprogramming algorithms to be able to specify/detect types generically.

• the generated kernel binary does not contain indirect calls because theyare eliminated using compiler optimizations e.g. devirtualization.

• the selected target supports the function pointer like functionality e.g.most CPU targets.

Example of Use:

#pragma OPENCL EXTENSION __cl_clang_function_pointers : enablevoidfoo(){void(*fp)();// compiled - no diagnostic generated}#pragma OPENCL EXTENSION __cl_clang_function_pointers : disablevoidbar(){void(*fp)();// error - pointers to function are not allowed}

__cl_clang_variadic_functions¶

With this extension it is possible to enable variadic arguments in functionsusing regular OpenCL extension pragma mechanism detailed inthe OpenCLExtension Specification, section 1.2.

This is not conformant behavior and it can only be used portably when thefunctions with variadic prototypes do not get generated in binary e.g. thevariadic prototype is used to specify a function type with any number ofarguments in metaprogramming algorithms in C++ for OpenCL.

This extensions can also be used when the kernel code is intended for targetssupporting the variadic arguments e.g. majority of CPU targets.

Example of Use:

#pragma OPENCL EXTENSION __cl_clang_variadic_functions : enablevoidfoo(inta,...);// compiled - no diagnostic generated#pragma OPENCL EXTENSION __cl_clang_variadic_functions : disablevoidbar(inta,...);// error - variadic prototype is not allowed

__cl_clang_non_portable_kernel_param_types¶

With this extension it is possible to enable the use of some restricted typesin kernel parameters specified inC++ for OpenCL v1.0 s2.4.The restrictions can be relaxed using regular OpenCL extension pragma mechanismdetailed inthe OpenCL Extension Specification, section 1.2.

This is not a conformant behavior and it can only be used when thekernel arguments are not accessed on the host side or the data layout/sizebetween the host and device is known to be compatible.

Example of Use:

// Plain Old Data type.structPod{inta;intb;};// Not POD type because of the constructor.// Standard layout type because there is only one access control.structOnlySL{inta;intb;NotPod():a(0),b(0){}};// Not standard layout type because of two different access controls.structNotSL{inta;private:intb;}kernelvoidkernel_main(Poda,#pragma OPENCL EXTENSION __cl_clang_non_portable_kernel_param_types : enableOnlySLb,globalNotSL*c,#pragma OPENCL EXTENSION __cl_clang_non_portable_kernel_param_types : disableglobalOnlySL*d,);

Remove address space builtin function¶

__remove_address_space allows to derive types in C++ for OpenCLthat have address space qualifiers removed. This utility only affectsaddress space qualifiers, therefore, other type qualifiers such asconst orvolatile remain unchanged.

Example of Use:

template<typenameT>voidfoo(T*par){Tvar1;// error - local function variable with global address space__privateTvar2;// error - conflicting address space qualifiers__private__remove_address_space<T>::typevar3;// var3 is __private int}voidbar(){__globalint*ptr;foo(ptr);}

Legacy 1.x atomics with generic address space¶

Clang allows use of atomic functions from the OpenCL 1.x standardswith the generic address space pointer in C++ for OpenCL mode.

This is a non-portable feature and might not be supported by alltargets.

Example of Use:

voidfoo(__genericvolatileunsignedint*a){atomic_add(a,1);}

__builtin_alloca¶

__builtin_alloca is used to dynamically allocate memory on the stack. Memoryis automatically freed upon function termination.

Syntax:

__builtin_alloca(size_tn)

Example of Use:

voidinit(float*data,size_tnbelems);voidprocess(float*data,size_tnbelems);intfoo(size_tn){automem=(float*)__builtin_alloca(n*sizeof(float));init(mem,n);process(mem,n);/* mem is automatically freed at this point */}

Description:

__builtin_alloca is meant to be used to allocate a dynamic amount of memoryon the stack. This amount is subject to stack allocation limits.

Query for this feature with__has_builtin(__builtin_alloca).

__builtin_alloca_with_align¶

__builtin_alloca_with_align is used to dynamically allocate memory on thestack while controlling its alignment. Memory is automatically freed uponfunction termination.

Syntax:

__builtin_alloca_with_align(size_tn,size_talign)

Example of Use:

voidinit(float*data,size_tnbelems);voidprocess(float*data,size_tnbelems);intfoo(size_tn){automem=(float*)__builtin_alloca_with_align(n*sizeof(float),CHAR_BIT*alignof(float));init(mem,n);process(mem,n);/* mem is automatically freed at this point */}

Description:

__builtin_alloca_with_align is meant to be used to allocate a dynamic amount of memoryon the stack. It is similar to__builtin_alloca but accepts a secondargument whose value is the alignment constraint, as a power of 2 inbits.

Query for this feature with__has_builtin(__builtin_alloca_with_align).

__builtin_assume¶

__builtin_assume is used to provide the optimizer with a booleaninvariant that is defined to be true.

Syntax:

__builtin_assume(bool)

Example of Use:

intfoo(intx){__builtin_assume(x!=0);// The optimizer may short-circuit this check using the invariant.if(x==0)returndo_something();returndo_something_else();}

Description:

The boolean argument to this function is defined to be true. The optimizer mayanalyze the form of the expression provided as the argument and deduce fromthat information used to optimize the program. If the condition is violatedduring execution, the behavior is undefined. The argument itself is neverevaluated, so any side effects of the expression will be discarded.

Query for this feature with__has_builtin(__builtin_assume).

__builtin_call_with_static_chain¶

__builtin_call_with_static_chain is used to perform a static call whilesetting updating the static chain register.

Syntax:

T__builtin_call_with_static_chain(Texpr,void*ptr)

Example of Use:

autov=__builtin_call_with_static_chain(foo(3),foo);

Description:

This builtin returnsexpr after checking thatexpr is a non-memberstatic call expression. The call to that expression is made while usingptras a function pointer stored in a dedicated register to implementstatic chaincalling convention, as used by some language to implement closures or nestedfunctions.

Query for this feature with__has_builtin(__builtin_call_with_static_chain).

__builtin_readcyclecounter¶

__builtin_readcyclecounter is used to access the cycle counter register (ora similar low-latency, high-accuracy clock) on those targets that support it.

Syntax:

__builtin_readcyclecounter()

Example of Use:

unsignedlonglongt0=__builtin_readcyclecounter();do_something();unsignedlonglongt1=__builtin_readcyclecounter();unsignedlonglongcycles_to_do_something=t1-t0;// assuming no overflow

Description:

The__builtin_readcyclecounter() builtin returns the cycle counter value,which may be either global or process/thread-specific depending on the target.As the backing counters often overflow quickly (on the order of seconds) thisshould only be used for timing small intervals. When not supported by thetarget, the return value is always zero. This builtin takes no arguments andproduces an unsigned long long result.

Query for this feature with__has_builtin(__builtin_readcyclecounter). Notethat even if present, its use may depend on run-time privilege or other OScontrolled state.

__builtin_dump_struct¶

Syntax:

__builtin_dump_struct(&some_struct,some_printf_func,args...);

Examples:

structS{intx,y;floatf;structT{inti;}t;};voidfunc(structS*s){__builtin_dump_struct(s,printf);}

Example output:

struct S {  int x = 100  int y = 42  float f = 3.141593  struct T t = {    int i = 1997  }}

#include<string>structT{inta,b;};constexprvoidconstexpr_sprintf(std::string&out,constchar*format,auto...args){// ...}constexprstd::stringdump_struct(auto&x){std::strings;__builtin_dump_struct(&x,constexpr_sprintf,s);returns;}static_assert(dump_struct(T{1,2})==R"(struct T {  int a = 1  int b = 2})");

Description:

The__builtin_dump_struct function is used to print the fields of a simplestructure and their values for debugging purposes. The first argument of thebuiltin should be a pointer to the struct to dump. The second argumentfshould be some callable expression, and can be a function object or an overloadset. The builtin callsf, passing any further argumentsargs...followed by aprintf-compatible format string and the correspondingarguments.f may be called more than once, andf andargs will beevaluated once per call. In C++,f may be a template or overload set andresolve to different functions for each call.

In the format string, a suitable format specifier will be used for builtintypes that Clang knows how to format. This includes standard builtin types, aswell as aggregate structures,void* (printed with%p), andconstchar* (printed with%s). A*%p specifier will be used for a fieldthat Clang doesn’t know how to format, and the corresopnding argument will be apointer to the field. This allows a C++ templated formatting function to detectthis case and implement custom formatting. A* will otherwise not precede aformat specifier.

This builtin does not return a value.

This builtin can be used in constant expressions.

Query for this feature with__has_builtin(__builtin_dump_struct)

__builtin_shufflevector¶

__builtin_shufflevector is used to express generic vectorpermutation/shuffle/swizzle operations. This builtin is also very importantfor the implementation of various target-specific header files like<xmmintrin.h>.

Syntax:

__builtin_shufflevector(vec1,vec2,index1,index2,...)

Examples:

// identity operation - return 4-element vector v1.__builtin_shufflevector(v1,v1,0,1,2,3)// "Splat" element 0 of V1 into a 4-element result.__builtin_shufflevector(V1,V1,0,0,0,0)// Reverse 4-element vector V1.__builtin_shufflevector(V1,V1,3,2,1,0)// Concatenate every other element of 4-element vectors V1 and V2.__builtin_shufflevector(V1,V2,0,2,4,6)// Concatenate every other element of 8-element vectors V1 and V2.__builtin_shufflevector(V1,V2,0,2,4,6,8,10,12,14)// Shuffle v1 with some elements being undefined__builtin_shufflevector(v1,v1,3,-1,1,-1)

Description:

The first two arguments to__builtin_shufflevector are vectors that havethe same element type. The remaining arguments are a list of integers thatspecify the elements indices of the first two vectors that should be extractedand returned in a new vector. These element indices are numbered sequentiallystarting with the first vector, continuing into the second vector. Thus, ifvec1 is a 4-element vector, index 5 would refer to the second element ofvec2. An index of -1 can be used to indicate that the corresponding elementin the returned vector is a don’t care and can be optimized by the backend.

The result of__builtin_shufflevector is a vector with the same elementtype asvec1/vec2 but that has an element count equal to the number ofindices specified.

Query for this feature with__has_builtin(__builtin_shufflevector).

__builtin_convertvector¶

__builtin_convertvector is used to express generic vectortype-conversion operations. The input vector and the output vectortype must have the same number of elements.

Syntax:

__builtin_convertvector(src_vec,dst_vec_type)

Examples:

typedefdoublevector4double__attribute__((__vector_size__(32)));typedeffloatvector4float__attribute__((__vector_size__(16)));typedefshortvector4short__attribute__((__vector_size__(8)));vector4floatvf;vector4shortvs;// convert from a vector of 4 floats to a vector of 4 doubles.__builtin_convertvector(vf,vector4double)// equivalent to:(vector4double){(double)vf[0],(double)vf[1],(double)vf[2],(double)vf[3]}// convert from a vector of 4 shorts to a vector of 4 floats.__builtin_convertvector(vs,vector4float)// equivalent to:(vector4float){(float)vs[0],(float)vs[1],(float)vs[2],(float)vs[3]}

Description:

The first argument to__builtin_convertvector is a vector, and the secondargument is a vector type with the same number of elements as the firstargument.

The result of__builtin_convertvector is a vector with the same elementtype as the second argument, with a value defined in terms of the action of aC-style cast applied to each element of the first argument.

Query for this feature with__has_builtin(__builtin_convertvector).

__builtin_bitreverse¶

• __builtin_bitreverse8

• __builtin_bitreverse16

• __builtin_bitreverse32

• __builtin_bitreverse64

Syntax:

__builtin_bitreverse32(x)

Examples:

uint8_trev_x=__builtin_bitreverse8(x);uint16_trev_x=__builtin_bitreverse16(x);uint32_trev_y=__builtin_bitreverse32(y);uint64_trev_z=__builtin_bitreverse64(z);

Description:

The ‘__builtin_bitreverse’ family of builtins is used to reversethe bitpattern of an integer value; for example0b10110110 becomes0b01101101. These builtins can be used within constant expressions.

__builtin_rotateleft¶

• __builtin_rotateleft8

• __builtin_rotateleft16

• __builtin_rotateleft32

• __builtin_rotateleft64

Syntax:

__builtin_rotateleft32(x,y)

Examples:

uint8_trot_x=__builtin_rotateleft8(x,y);uint16_trot_x=__builtin_rotateleft16(x,y);uint32_trot_x=__builtin_rotateleft32(x,y);uint64_trot_x=__builtin_rotateleft64(x,y);

Description:

The ‘__builtin_rotateleft’ family of builtins is used to rotatethe bits in the first argument by the amount in the second argument.For example,0b10000110 rotated left by 11 becomes0b00110100.The shift value is treated as an unsigned amount modulo the size ofthe arguments. Both arguments and the result have the bitwidth specifiedby the name of the builtin. These builtins can be used within constantexpressions.

__builtin_rotateright¶

• __builtin_rotateright8

• __builtin_rotateright16

• __builtin_rotateright32

• __builtin_rotateright64

Syntax:

__builtin_rotateright32(x,y)

Examples:

uint8_trot_x=__builtin_rotateright8(x,y);uint16_trot_x=__builtin_rotateright16(x,y);uint32_trot_x=__builtin_rotateright32(x,y);uint64_trot_x=__builtin_rotateright64(x,y);

Description:

The ‘__builtin_rotateright’ family of builtins is used to rotatethe bits in the first argument by the amount in the second argument.For example,0b10000110 rotated right by 3 becomes0b11010000.The shift value is treated as an unsigned amount modulo the size ofthe arguments. Both arguments and the result have the bitwidth specifiedby the name of the builtin. These builtins can be used within constantexpressions.

__builtin_unreachable¶

__builtin_unreachable is used to indicate that a specific point in theprogram cannot be reached, even if the compiler might otherwise think it can.This is useful to improve optimization and eliminates certain warnings. Forexample, without the__builtin_unreachable in the example below, thecompiler assumes that the inline asm can fall through and prints a “functiondeclared ‘noreturn’ should not return” warning.

Syntax:

__builtin_unreachable()

Example of use:

voidmyabort(void)__attribute__((noreturn));voidmyabort(void){asm("int3");__builtin_unreachable();}

Description:

The__builtin_unreachable() builtin has completely undefined behavior.Since it has undefined behavior, it is a statement that it is never reached andthe optimizer can take advantage of this to produce better code. This builtintakes no arguments and produces a void result.

Query for this feature with__has_builtin(__builtin_unreachable).

__builtin_unpredictable¶

__builtin_unpredictable is used to indicate that a branch condition isunpredictable by hardware mechanisms such as branch prediction logic.

Syntax:

__builtin_unpredictable(longlong)

Example of use:

if(__builtin_unpredictable(x>0)){foo();}

Description:

The__builtin_unpredictable() builtin is expected to be used with controlflow conditions such as inif andswitch statements.

Query for this feature with__has_builtin(__builtin_unpredictable).

__builtin_expect¶

__builtin_expect is used to indicate that the value of an expression isanticipated to be the same as a statically known result.

Syntax:

long__builtin_expect(longexpr,longval)

Example of use:

if(__builtin_expect(x,0)){bar();}

Description:

The__builtin_expect() builtin is typically used with control flowconditions such as inif andswitch statements to help branchprediction. It means that its first argumentexpr is expected to take thevalue of its second argumentval. It always returnsexpr.

Query for this feature with__has_builtin(__builtin_expect).

__builtin_expect_with_probability¶

__builtin_expect_with_probability is similar to__builtin_expect but ittakes a probability as third argument.

Syntax:

long__builtin_expect_with_probability(longexpr,longval,doublep)

Example of use:

if(__builtin_expect_with_probability(x,0,.3)){bar();}

Description:

The__builtin_expect_with_probability() builtin is typically used withcontrol flow conditions such as inif andswitch statements to helpbranch prediction. It means that its first argumentexpr is expected to takethe value of its second argumentval with probabilityp.p must bewithin[0.0;1.0] bounds. This builtin always returns the value ofexpr.

Query for this feature with__has_builtin(__builtin_expect_with_probability).

__builtin_prefetch¶

__builtin_prefetch is used to communicate with the cache handler to bringdata into the cache before it gets used.

Syntax:

void__builtin_prefetch(constvoid*addr,intrw=0,intlocality=3)

Example of use:

__builtin_prefetch(a+i);

Description:

The__builtin_prefetch(addr,rw,locality) builtin is expected to be used toavoid cache misses when the developper has a good understanding of which dataare going to be used next.addr is the address that needs to be brought intothe cache.rw indicates the expected access mode:0 forread and1forwrite. In case ofread write access,1 is to be used.localityindicates the expected persistance of data in cache, from0 which means thatdata can be discarded from cache after its next use to3 which means thatdata is going to be reused a lot once in cache.1 and2 provideintermediate behavior between these two extremes.

Query for this feature with__has_builtin(__builtin_prefetch).

__sync_swap¶

__sync_swap is used to atomically swap integers or pointers in memory.

Syntax:

type__sync_swap(type*ptr,typevalue,...)

Example of Use:

intold_value=__sync_swap(&value,new_value);

Description:

The__sync_swap() builtin extends the existing__sync_*() family ofatomic intrinsics to allow code to atomically swap the current value with thenew value. More importantly, it helps developers write more efficient andcorrect code by avoiding expensive loops around__sync_bool_compare_and_swap() or relying on the platform specificimplementation details of__sync_lock_test_and_set(). The__sync_swap() builtin is a full barrier.

__builtin_addressof¶

__builtin_addressof performs the functionality of the built-in&operator, ignoring anyoperator& overload. This is useful in constantexpressions in C++11, where there is no other way to take the address of anobject that overloadsoperator&.

Example of use:

template<typenameT>constexprT*addressof(T&value){return__builtin_addressof(value);}

__builtin_function_start¶

__builtin_function_start returns the address of a function body.

Syntax:

void*__builtin_function_start(function)

Example of use:

voida(){}void*p=__builtin_function_start(a);classA{public:voida(intn);voida();};voidA::a(intn){}voidA::a(){}void*pa1=__builtin_function_start((void(A::*)(int))&A::a);void*pa2=__builtin_function_start((void(A::*)())&A::a);

Description:

The__builtin_function_start builtin accepts an argument that can beconstant-evaluated to a function, and returns the address of the functionbody. This builtin is not supported on all targets.

The returned pointer may differ from the normally taken function addressand is not safe to call. For example, with-fsanitize=cfi, taking afunction address produces a callable pointer to a CFI jump table, while__builtin_function_start returns an address that failscfi-icall checks.

__builtin_operator_new and__builtin_operator_delete¶

A call to__builtin_operator_new(args) is exactly the same as a call to::operatornew(args), except that it allows certain optimizationsthat the C++ standard does not permit for a direct function call to::operatornew (in particular, removingnew /delete pairs andmerging allocations), and that the call is required to resolve to areplaceable global allocation function.

Likewise,__builtin_operator_delete is exactly the same as a call to::operatordelete(args), except that it permits optimizationsand that the call is required to resolve to areplaceable global deallocation function.

These builtins are intended for use in the implementation ofstd::allocatorand other similar allocation libraries, and are only available in C++.

Query for this feature with__has_builtin(__builtin_operator_new) or__has_builtin(__builtin_operator_delete):

• If the value is at least201802L, the builtins behave as described above.

• If the value is non-zero, the builtins may not support calling arbitraryreplaceable global (de)allocation functions, but do support calling at least::operatornew(size_t) and::operatordelete(void*).

__builtin_preserve_access_index¶

__builtin_preserve_access_index specifies a code section wherearray subscript access and structure/union member access are relocatableunder bpf compile-once run-everywhere framework. Debuginfo (typicallywith-g) is needed, otherwise, the compiler will exit with an error.The return type for the intrinsic is the same as the type of theargument.

Syntax:

type__builtin_preserve_access_index(typearg)

Example of Use:

structt{inti;intj;union{inta;intb;}c[4];};structt*v=...;int*pb=__builtin_preserve_access_index(&v->c[3].b);__builtin_preserve_access_index(v->j);

__builtin_debugtrap¶

__builtin_debugtrap causes the program to stop its execution in such a way that a debugger can catch it.

Syntax:

__builtin_debugtrap()

Description

__builtin_debugtrap is lowered to the `llvm.debugtrap <https://llvm.org/docs/LangRef.html#llvm-debugtrap-intrinsic>`_ builtin. It should have the same effect as setting a breakpoint on the line where the builtin is called.

Query for this feature with__has_builtin(__builtin_debugtrap).

__builtin_trap¶

__builtin_trap causes the program to stop its execution abnormally.

Syntax:

__builtin_trap()

Description

__builtin_trap is lowered to the `llvm.trap <https://llvm.org/docs/LangRef.html#llvm-trap-intrinsic>`_ builtin.

Query for this feature with__has_builtin(__builtin_trap).

__builtin_sycl_unique_stable_name¶

__builtin_sycl_unique_stable_name() is a builtin that takes a type andproduces a string literal containing a unique name for the type that is stableacross split compilations, mainly to support SYCL/Data Parallel C++ language.

In cases where the split compilation needs to share a unique token for a typeacross the boundary (such as in an offloading situation), this name can be usedfor lookup purposes, such as in the SYCL Integration Header.

The value of this builtin is computed entirely at compile time, so it can beused in constant expressions. This value encodes lambda functions based on astable numbering order in which they appear in their local declaration contexts.Once this builtin is evaluated in a constexpr context, it is erroneous to useit in an instantiation which changes its value.

In order to produce the unique name, the current implementation of the bultinuses Itanium mangling even if the host compilation uses a different namemangling scheme at runtime. The mangler marks all the lambdas required to namethe SYCL kernel and emits a stable local ordering of the respective lambdas.The resulting pattern is demanglable. When non-lambda types are passed to thebuiltin, the mangler emits their usual pattern without any special treatment.

Syntax:

// Computes a unique stable name for the given type.constexprconstchar*__builtin_sycl_unique_stable_name(type-id);

Multiprecision Arithmetic Builtins¶

Clang provides a set of builtins which expose multiprecision arithmetic in amanner amenable to C. They all have the following form:

unsignedx=...,y=...,carryin=...,carryout;unsignedsum=__builtin_addc(x,y,carryin,&carryout);

Thus one can form a multiprecision addition chain in the following manner:

unsigned*x,*y,*z,carryin=0,carryout;z[0]=__builtin_addc(x[0],y[0],carryin,&carryout);carryin=carryout;z[1]=__builtin_addc(x[1],y[1],carryin,&carryout);carryin=carryout;z[2]=__builtin_addc(x[2],y[2],carryin,&carryout);carryin=carryout;z[3]=__builtin_addc(x[3],y[3],carryin,&carryout);

The complete list of builtins are:

unsignedchar__builtin_addcb(unsignedcharx,unsignedchary,unsignedcharcarryin,unsignedchar*carryout);unsignedshort__builtin_addcs(unsignedshortx,unsignedshorty,unsignedshortcarryin,unsignedshort*carryout);unsigned__builtin_addc(unsignedx,unsignedy,unsignedcarryin,unsigned*carryout);unsignedlong__builtin_addcl(unsignedlongx,unsignedlongy,unsignedlongcarryin,unsignedlong*carryout);unsignedlonglong__builtin_addcll(unsignedlonglongx,unsignedlonglongy,unsignedlonglongcarryin,unsignedlonglong*carryout);unsignedchar__builtin_subcb(unsignedcharx,unsignedchary,unsignedcharcarryin,unsignedchar*carryout);unsignedshort__builtin_subcs(unsignedshortx,unsignedshorty,unsignedshortcarryin,unsignedshort*carryout);unsigned__builtin_subc(unsignedx,unsignedy,unsignedcarryin,unsigned*carryout);unsignedlong__builtin_subcl(unsignedlongx,unsignedlongy,unsignedlongcarryin,unsignedlong*carryout);unsignedlonglong__builtin_subcll(unsignedlonglongx,unsignedlonglongy,unsignedlonglongcarryin,unsignedlonglong*carryout);