__arm_agnostic¶

The__arm_agnostic keyword applies to prototyped function types andaffects the function’s calling convention for a given state S. Thisattribute allows the user to describe a function that preserves S, withoutrequiring the function to share S with its callers and without makingthe assumption that S exists.

If a function has the__arm_agnostic(S) attribute and calls a functionwithout this attribute, then the function’s object code will contain codeto preserve state S. Otherwise, the function’s object code will be the sameas if it did not have the attribute.

The attribute takes string arguments to describe state S. The supportedstates are:

• "sme_za_state" for state enabled by PSTATE.ZA, such as ZA and ZT0.

The attribute__arm_agnostic("sme_za_state") cannot be used in conjunctionwith__arm_in(S),__arm_out(S),__arm_inout(S) or__arm_preserves(S) where state S describes state enabled by PSTATE.ZA,such as “za” or “zt0”.

__arm_in¶

The__arm_in keyword applies to prototyped function types and specifiesthat the function shares a given state S with its caller. For__arm_in, thefunction takes the state S as input and returns with the state S unchanged.

The attribute takes string arguments to instruct the compiler which stateis shared. The supported states for S are:

• "za" for Matrix Storage (requires SME)

The attributes__arm_in(S),__arm_out(S),__arm_inout(S) and__arm_preserves(S) are all mutually exclusive for the same state S.

__arm_inout¶

The__arm_inout keyword applies to prototyped function types and specifiesthat the function shares a given state S with its caller. For__arm_inout,the function takes the state S as input and returns new state for S.

The attribute takes string arguments to instruct the compiler which stateis shared. The supported states for S are:

• "za" for Matrix Storage (requires SME)

The attributes__arm_in(S),__arm_out(S),__arm_inout(S) and__arm_preserves(S) are all mutually exclusive for the same state S.

__arm_locally_streaming¶

The__arm_locally_streaming keyword applies to function declarationsand specifies that all the statements in the function are executed instreaming mode. This means that:

• the function requires that the target processor implements the Scalable MatrixExtension (SME).

• the program automatically puts the machine into streaming mode beforeexecuting the statements and automatically restores the previous modeafterwards.

Clang manages PSTATE.SM automatically; it is not the source code’sresponsibility to do this. For example, Clang will emit code to enablestreaming mode at the start of the function, and disable streaming modeat the end of the function.

__arm_new¶

The__arm_new keyword applies to function declarations and specifiesthat the function will create a new scope for state S.

The attribute takes string arguments to instruct the compiler for which stateto create new scope. The supported states for S are:

• "za" for Matrix Storage (requires SME)

For state"za", this means that:

• the function requires that the target processor implements the Scalable MatrixExtension (SME).

• the function will commit any lazily saved ZA data.

• the function will create a new ZA context and enable PSTATE.ZA.

• the function will disable PSTATE.ZA (by setting it to 0) before returning.

For__arm_new("za") functions Clang will set up the ZA context automaticallyon entry to the function and disable it before returning. For example, if ZA isin a dormant state Clang will generate the code to commit a lazy-save and set upa new ZA state before executing user code.

__arm_out¶

The__arm_out keyword applies to prototyped function types and specifiesthat the function shares a given state S with its caller. For__arm_out,the function ignores the incoming state for S and returns new state for S.

The attribute takes string arguments to instruct the compiler which stateis shared. The supported states for S are:

• "za" for Matrix Storage (requires SME)

The attributes__arm_in(S),__arm_out(S),__arm_inout(S) and__arm_preserves(S) are all mutually exclusive for the same state S.

__arm_preserves¶

The__arm_preserves keyword applies to prototyped function types andspecifies that the function does not read a given state S and returnswith state S unchanged.

The attribute takes string arguments to instruct the compiler which stateis shared. The supported states for S are:

• "za" for Matrix Storage (requires SME)

The attributes__arm_in(S),__arm_out(S),__arm_inout(S) and__arm_preserves(S) are all mutually exclusive for the same state S.

__arm_streaming¶

The__arm_streaming keyword applies to prototyped function types and specifiesthat the function has a “streaming interface”. This means that:

• the function requires that the processor implements the Scalable MatrixExtension (SME).

• the function must be entered in streaming mode (that is, with PSTATE.SMset to 1)

• the function must return in streaming mode

Clang manages PSTATE.SM automatically; it is not the source code’sresponsibility to do this. For example, if a non-streamingfunction calls an__arm_streaming function, Clang generates codethat switches into streaming mode before calling the function andswitches back to non-streaming mode on return.

__arm_streaming_compatible¶

The__arm_streaming_compatible keyword applies to prototyped function types andspecifies that the function has a “streaming compatible interface”. Thismeans that:

• the function may be entered in either non-streaming mode (PSTATE.SM=0) orin streaming mode (PSTATE.SM=1).

• the function must return in the same mode as it was entered.

• the code executed in the function is compatible with either mode.

Clang manages PSTATE.SM automatically; it is not the source code’sresponsibility to do this. Clang will ensure that the generated code instreaming-compatible functions is valid in either mode (PSTATE.SM=0 orPSTATE.SM=1). For example, if an__arm_streaming_compatible function calls anon-streaming function, Clang generates code to temporarily switch out of streamingmode before calling the function and switch back to streaming-mode on return ifPSTATE.SM is1 on entry of the caller. IfPSTATE.SM is0 onentry to the__arm_streaming_compatible function, the call will be executedwithout changing modes.

amdgpu_flat_work_group_size¶

The flat work-group size is the number of work-items in the work-group sizespecified when the kernel is dispatched. It is the product of the sizes of thex, y, and z dimension of the work-group.

Clang supports the__attribute__((amdgpu_flat_work_group_size(<min>,<max>))) attribute for theAMDGPU target. This attribute may be attached to a kernel function definitionand is an optimization hint.

<min> parameter specifies the minimum flat work-group size, and<max>parameter specifies the maximum flat work-group size (must be greater than<min>) to which all dispatches of the kernel will conform. Passing0,0as<min>,<max> implies the default behavior (128,256).

If specified, the AMDGPU target backend might be able to produce better machinecode for barriers and perform scratch promotion by estimating available groupsegment size.

An error will be given if:

• Specified values violate subtarget specifications;

• Specified values are not compatible with values provided through otherattributes.

amdgpu_max_num_work_groups¶

This attribute specifies the max number of work groups when the kernelis dispatched.

Clang supports the__attribute__((amdgpu_max_num_work_groups(<x>,<y>,<z>))) or[[clang::amdgpu_max_num_work_groups(<x>,<y>,<z>)]] attribute for theAMDGPU target. This attribute may be attached to HIP or OpenCL kernel functiondefinitions and is an optimization hint.

The<x> parameter specifies the maximum number of work groups in the x dimension.Similarly<y> and<z> are for the y and z dimensions respectively.Each of the three values must be greater than 0 when provided. The<x> parameteris required, while<y> and<z> are optional with default value of 1.

If specified, the AMDGPU target backend might be able to produce better machinecode.

An error will be given if:

• Specified values violate subtarget specifications;

• Specified values are not compatible with values provided through otherattributes.

amdgpu_num_sgpr, amdgpu_num_vgpr¶

Clang supports the__attribute__((amdgpu_num_sgpr(<num_sgpr>))) and__attribute__((amdgpu_num_vgpr(<num_vgpr>))) attributes for the AMDGPUtarget. These attributes may be attached to a kernel function definition and arean optimization hint.

If these attributes are specified, then the AMDGPU target backend will attemptto limit the number of SGPRs and/or VGPRs used to the specified value(s). Thenumber of used SGPRs and/or VGPRs may further be rounded up to satisfy theallocation requirements or constraints of the subtarget. Passing0 asnum_sgpr and/ornum_vgpr implies the default behavior (no limits).

These attributes can be used to test the AMDGPU target backend. It isrecommended that theamdgpu_waves_per_eu attribute be used to controlresources such as SGPRs and VGPRs since it is aware of the limits for differentsubtargets.

An error will be given if:

• Specified values violate subtarget specifications;

• Specified values are not compatible with values provided through otherattributes;

• The AMDGPU target backend is unable to create machine code that can meet therequest.

amdgpu_waves_per_eu¶

A compute unit (CU) is responsible for executing the wavefronts of a work-group.It is composed of one or more execution units (EU), which are responsible forexecuting the wavefronts. An EU can have enough resources to maintain the stateof more than one executing wavefront. This allows an EU to hide latency byswitching between wavefronts in a similar way to symmetric multithreading on aCPU. In order to allow the state for multiple wavefronts to fit on an EU, theresources used by a single wavefront have to be limited. For example, the numberof SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,but can result in having to spill some register state to memory.

Clang supports the__attribute__((amdgpu_waves_per_eu(<min>[,<max>])))attribute for the AMDGPU target. This attribute may be attached to a kernelfunction definition and is an optimization hint.

<min> parameter specifies the requested minimum number of waves per EU, andoptional<max> parameter specifies the requested maximum number of wavesper EU (must be greater than<min> if specified). If<max> is omitted,then there is no restriction on the maximum number of waves per EU other thanthe one dictated by the hardware for which the kernel is compiled. Passing0,0 as<min>,<max> implies the default behavior (no limits).

If specified, this attribute allows an advanced developer to tune the number ofwavefronts that are capable of fitting within the resources of an EU. The AMDGPUtarget backend can use this information to limit resources, such as number ofSGPRs, number of VGPRs, size of available group and private memory segments, insuch a way that guarantees that at least<min> wavefronts and at most<max> wavefronts are able to fit within the resources of an EU. Requestingmore wavefronts can hide memory latency but limits available registers whichcan result in spilling. Requesting fewer wavefronts can help reduce cachethrashing, but can reduce memory latency hiding.

This attribute controls the machine code generated by the AMDGPU target backendto ensure it is capable of meeting the requested values. However, when thekernel is executed, there may be other reasons that prevent meeting the request,for example, there may be wavefronts from other kernels executing on the EU.

An error will be given if:

• Specified values violate subtarget specifications;

• Specified values are not compatible with values provided through otherattributes;

The AMDGPU target backend will emit a warning whenever it is unable tocreate machine code that meets the request.

aarch64_sve_pcs¶

On AArch64 targets, this attribute changes the calling convention of afunction to preserve additional Scalable Vector registers and ScalablePredicate registers relative to the default calling convention used forAArch64.

This means it is more efficient to call such functions from code that performsextensive scalable vector and scalable predicate calculations, because fewerlive SVE registers need to be saved. This property makes it well-suited for SVEmath library functions, which are typically leaf functions that require a smallnumber of registers.

However, using this attribute also means that it is more expensive to calla function that adheres to the default calling convention from within sucha function. Therefore, it is recommended that this attribute is only usedfor leaf functions.

For more information, see the documentation foraarch64_sve_pcs in theARM C Language Extension (ACLE) documentation.

aarch64_vector_pcs¶

On AArch64 targets, this attribute changes the calling convention of afunction to preserve additional floating-point and Advanced SIMD registersrelative to the default calling convention used for AArch64.

This means it is more efficient to call such functions from code that performsextensive floating-point and vector calculations, because fewer live SIMD and FPregisters need to be saved. This property makes it well-suited for e.g.floating-point or vector math library functions, which are typically leaffunctions that require a small number of registers.

However, using this attribute also means that it is more expensive to calla function that adheres to the default calling convention from within sucha function. Therefore, it is recommended that this attribute is only usedfor leaf functions.

For more information, see the documentation foraarch64_vector_pcs onthe Arm Developer website.

fastcall¶

On 32-bit x86 targets, this attribute changes the calling convention of afunction to use ECX and EDX as register parameters and clear parameters off ofthe stack on return. This convention does not support variadic calls orunprototyped functions in C, and has no effect on x86_64 targets. This callingconvention is supported primarily for compatibility with existing code. Usersseeking register parameters should use theregparm attribute, which doesnot require callee-cleanup. See the documentation for__fastcall on MSDN.

m68k_rtd¶

On M68k targets, this attribute changes the calling convention of a functionto clear parameters off the stack on return. In other words, callee isresponsible for cleaning out the stack space allocated for incoming paramters.This convention does not support variadic calls or unprototyped functions in C.When targeting M68010 or newer CPUs, this calling convention is implementedusing thertd instruction.

ms_abi¶

On non-Windows x86_64 targets, this attribute changes the calling convention ofa function to match the default convention used on Windows x86_64. Thisattribute has no effect on Windows targets or non-x86_64 targets.

pcs¶

On ARM targets, this attribute can be used to select calling conventionssimilar tostdcall on x86. Valid parameter values are “aapcs” and“aapcs-vfp”.

preserve_all¶

On X86-64 and AArch64 targets, this attribute changes the calling convention ofa function. Thepreserve_all calling convention attempts to make the codein the caller even less intrusive than thepreserve_most calling convention.This calling convention also behaves identical to theC calling conventionon how arguments and return values are passed, but it uses a different set ofcaller/callee-saved registers. This removes the burden of saving andrecovering a large register set before and after the call in the caller. Ifthe arguments are passed in callee-saved registers, then they will bepreserved by the callee across the call. This doesn’t apply for valuesreturned in callee-saved registers.

• On X86-64 the callee preserves all general purpose registers, except forR11. R11 can be used as a scratch register. Furthermore it also preservesall floating-point registers (XMMs/YMMs).

• On AArch64 the callee preserve all general purpose registers, except X0-X8 andX16-X18. Furthermore it also preserves lower 128 bits of V8-V31 SIMD - floatingpoint registers.

The idea behind this convention is to support calls to runtime functionsthat don’t need to call out to any other functions.

This calling convention, like thepreserve_most calling convention, will beused by a future version of the Objective-C runtime and should be consideredexperimental at this time.

preserve_most¶

On X86-64 and AArch64 targets, this attribute changes the calling convention ofa function. Thepreserve_most calling convention attempts to make the codein the caller as unintrusive as possible. This convention behaves identicallyto theC calling convention on how arguments and return values are passed,but it uses a different set of caller/callee-saved registers. This alleviatesthe burden of saving and recovering a large register set before and after thecall in the caller. If the arguments are passed in callee-saved registers,then they will be preserved by the callee across the call. This doesn’tapply for values returned in callee-saved registers.

• On X86-64 the callee preserves all general purpose registers, except forR11. R11 can be used as a scratch register. Floating-point registers(XMMs/YMMs) are not preserved and need to be saved by the caller.

• On AArch64 the callee preserve all general purpose registers, except X0-X8 andX16-X18.

The idea behind this convention is to support calls to runtime functionsthat have a hot path and a cold path. The hot path is usually a small pieceof code that doesn’t use many registers. The cold path might need to call out toanother function and therefore only needs to preserve the caller-savedregisters, which haven’t already been saved by the caller. Thepreserve_most calling convention is very similar to thecold callingconvention in terms of caller/callee-saved registers, but they are used fordifferent types of function calls.coldcc is for function calls that arerarely executed, whereaspreserve_most function calls are intended to beon the hot path and definitely executed a lot. Furthermorepreserve_mostdoesn’t prevent the inliner from inlining the function call.

This calling convention will be used by a future version of the Objective-Cruntime and should therefore still be considered experimental at this time.Although this convention was created to optimize certain runtime calls tothe Objective-C runtime, it is not limited to this runtime and might be usedby other runtimes in the future too. The current implementation onlysupports X86-64 and AArch64, but the intention is to support more architecturesin the future.

preserve_none¶

On X86-64 and AArch64 targets, this attribute changes the calling convention of a function.Thepreserve_none calling convention tries to preserve as few generalregisters as possible. So all general registers are caller saved registers. Italso uses more general registers to pass arguments. This attribute doesn’timpact floating-point registers.preserve_none’s ABI is still unstable, andmay be changed in the future.

• On X86-64, only RSP and RBP are preserved by the callee.Registers R12, R13, R14, R15, RDI, RSI, RDX, RCX, R8, R9, R11, and RAX now canbe used to pass function arguments. Floating-point registers (XMMs/YMMs) stillfollow the C calling convention.

• On AArch64, only LR and FP are preserved by the callee.Registers X20-X28, X0-X7, and X9-X14 are used to pass function arguments.X8, X16-X19, SIMD and floating-point registers follow the AAPCS callingconvention. X15 is not available for argument passing on Windows, but isused to pass arguments on other platforms.

regcall¶

On x86 targets, this attribute changes the calling convention to__regcall convention. This convention aims to pass as many argumentsas possible in registers. It also tries to utilize registers for thereturn value whenever it is possible.

regparm¶

On 32-bit x86 targets, the regparm attribute causes the compiler to passthe first three integer parameters in EAX, EDX, and ECX instead of on thestack. This attribute has no effect on variadic functions, and all parametersare passed via the stack as normal.

riscv::vector_cc, riscv_vector_cc, clang::riscv_vector_cc¶

Theriscv_vector_cc attribute can be applied to a function. It preserves 15registers namely, v1-v7 and v24-v31 as callee-saved. Callers thus don’t needto save these registers before function calls, and callees only need to savethem if they use them.

riscv::vls_cc, riscv_vls_cc, clang::riscv_vls_cc¶

Theriscv_vls_cc attribute can be applied to a function. Functionsdeclared with this attribute will utilize the standard fixed-length vectorcalling convention variant instead of the default calling convention defined bythe ABI. This variant aims to pass fixed-length vectors via vector registers,if possible, rather than through general-purpose registers.

stdcall¶

On 32-bit x86 targets, this attribute changes the calling convention of afunction to clear parameters off of the stack on return. This convention doesnot support variadic calls or unprototyped functions in C, and has no effect onx86_64 targets. This calling convention is used widely by the Windows API andCOM applications. See the documentation for__stdcall on MSDN.

sysv_abi¶

On Windows x86_64 targets, this attribute changes the calling convention of afunction to match the default convention used on Sys V targets such as Linux,Mac, and BSD. This attribute has no effect on other targets.

thiscall¶

On 32-bit x86 targets, this attribute changes the calling convention of afunction to use ECX for the first parameter (typically the implicitthisparameter of C++ methods) and clear parameters off of the stack on return. Thisconvention does not support variadic calls or unprototyped functions in C, andhas no effect on x86_64 targets. See the documentation for__thiscall onMSDN.

vectorcall¶

On 32-bit x86and x86_64 targets, this attribute changes the callingconvention of a function to pass vector parameters in SSE registers.

On 32-bit x86 targets, this calling convention is similar to__fastcall.The first two integer parameters are passed in ECX and EDX. Subsequent integerparameters are passed in memory, and callee clears the stack. On x86_64targets, the callee doesnot clear the stack, and integer parameters arepassed in RCX, RDX, R8, and R9 as is done for the default Windows x64 callingconvention.

On both 32-bit x86 and x86_64 targets, vector and floating point arguments arepassed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements arepassed in sequential SSE registers if enough are available. If AVX is enabled,256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type thatcannot be passed in registers for any reason is passed by reference, whichallows the caller to align the parameter memory.

See the documentation for__vectorcall on MSDN for more details.

callable_when¶

Use__attribute__((callable_when(...))) to indicate what states a methodmay be called in. Valid states are unconsumed, consumed, or unknown. Eachargument to this attribute must be a quoted string. E.g.:

__attribute__((callable_when("unconsumed","unknown")))

consumable¶

Eachclass that uses any of the typestate annotations must first be markedusing theconsumable attribute. Failure to do so will result in a warning.

This attribute accepts a single parameter that must be one of the following:unknown,consumed, orunconsumed.

param_typestate¶

This attribute specifies expectations about function parameters. Calls to anfunction with annotated parameters will issue a warning if the correspondingargument isn’t in the expected state. The attribute is also used to set theinitial state of the parameter when analyzing the function’s body.

return_typestate¶

Thereturn_typestate attribute can be applied to functions or parameters.When applied to a function the attribute specifies the state of the returnedvalue. The function’s body is checked to ensure that it always returns a valuein the specified state. On the caller side, values returned by the annotatedfunction are initialized to the given state.

When applied to a function parameter it modifies the state of an argument aftera call to the function returns. The function’s body is checked to ensure thatthe parameter is in the expected state before returning.

set_typestate¶

Annotate methods that transition an object into a new state with__attribute__((set_typestate(new_state))). The new state must beunconsumed, consumed, or unknown.

test_typestate¶

Use__attribute__((test_typestate(tested_state))) to indicate that a methodreturns true if the object is in the specified state..

swift_async¶

Theswift_async attribute specifies if and how a particular function orObjective-C method is imported into a swift async method. For instance:

@interfaceMyClass :NSObject-(void)notActuallyAsync:(int)p1withCompletionHandler:(void(^)())handler__attribute__((swift_async(none)));-(void)actuallyAsync:(int)p1callThisAsync:(void(^)())fun__attribute__((swift_async(swift_private,1)));@end

Here,notActuallyAsync:withCompletionHandler would have been imported asasync (because it’s last parameter’s selector piece iswithCompletionHandler) if not for theswift_async(none) attribute.Conversely,actuallyAsync:callThisAsync wouldn’t have been imported asasync if not for theswift_async attribute because it doesn’t match thenaming convention.

When usingswift_async to enable importing, the first argument to theattribute is eitherswift_private ornot_swift_private to indicatewhether the function/method is private to the current framework, and the secondargument is the index of the completion handler parameter.

swift_async_error¶

Theswift_async_error attribute specifies how an error state will berepresented in a swift async method. It’s a bit analogous to theswift_errorattribute for the generated async method. Theswift_async_error attributecan indicate a variety of different ways of representing an error.

• __attribute__((swift_async_error(zero_argument,N))), specifies that theasync method is considered to have failed if the Nth argument to thecompletion handler is zero.

• __attribute__((swift_async_error(nonzero_argument,N))), specifies thatthe async method is considered to have failed if the Nth argument to thecompletion handler is non-zero.

• __attribute__((swift_async_error(nonnull_error))), specifies that theasync method is considered to have failed if theNSError* argument to thecompletion handler is non-null.

• __attribute__((swift_async_error(none))), specifies that the async methodcannot fail.

For instance:

@interfaceMyClass :NSObject-(void)asyncMethod:(void(^)(char,int,float))handler__attribute__((swift_async(swift_private,1)))__attribute__((swift_async_error(zero_argument,2)));@end

Here, theswift_async attribute specifies thathandler is the completionhandler for this method, and theswift_async_error attribute specifies thattheint parameter is the one that represents the error.

swift_async_name¶

Theswift_async_name attribute provides the name of theasync overload forthe given declaration in Swift. If this attribute is absent, the name istransformed according to the algorithm built into the Swift compiler.

The argument is a string literal that contains the Swift name of the function ormethod. The name may be a compound Swift name. The function or method with suchan attribute must have more than zero parameters, as its last parameter isassumed to be a callback that’s eliminated in the Swiftasync name.

@interfaceURL+(void)loadContentsFrom:(URL*)urlcallback:(void(^)(NSData*))data__attribute__((__swift_async_name__("URL.loadContentsFrom(_:)")))@end

swift_attr¶

Theswift_attr provides a Swift-specific annotation for the declarationor type to which the attribute appertains to. It can be used on any declarationor type in Clang. This kind of annotation is ignored by Clang as it doesn’t have anysemantic meaning in languages supported by Clang. The Swift compiler caninterpret these annotations according to its own rules when importing C orObjective-C declarations.

swift_bridge¶

Theswift_bridge attribute indicates that the declaration to which theattribute appertains is bridged to the named Swift type.

__attribute__((__objc_root__))@interfaceBase-(instancetype)init;@end__attribute__((__swift_bridge__("BridgedI")))@interfaceI :Base@end

In this example, the Objective-C interfaceI will be made available to Swiftwith the nameBridgedI. It would be possible for the compiler to refer toI still in order to bridge the type back to Objective-C.

swift_bridged¶

Theswift_bridged_typedef attribute indicates that when the typedef to whichthe attribute appertains is imported into Swift, it should refer to the bridgedSwift type (e.g. Swift’sString) rather than the Objective-C type as written(e.g.NSString).

@interfaceNSString;typedefNSString*AliasedString__attribute__((__swift_bridged_typedef__));externvoidacceptsAliasedString(AliasedString_Nonnullparameter);

In this case, the functionacceptsAliasedString will be imported into Swiftas a function which accepts aString type parameter.

swift_error¶

Theswift_error attribute controls whether a particular function (orObjective-C method) is imported into Swift as a throwing function, and if so,which dynamic convention it uses.

All of these conventions exceptnone require the function to have an errorparameter. Currently, the error parameter is always the last parameter of typeNSError** orCFErrorRef*. Swift will remove the error parameter fromthe imported API. When calling the API, Swift will always pass a valid addressinitialized to a null pointer.

• swift_error(none) means that the function should not be imported asthrowing. The error parameter and result type will be imported normally.

• swift_error(null_result) means that calls to the function should beconsidered to have thrown if they return a null value. The return type must bea pointer type, and it will be imported into Swift with a non-optional type.This is the default error convention for Objective-C methods that returnpointers.

• swift_error(zero_result) means that calls to the function should beconsidered to have thrown if they return a zero result. The return type must bean integral type. If the return type would have been imported asBool, itis instead imported asVoid. This is the default error convention forObjective-C methods that return a type that would be imported asBool.

• swift_error(nonzero_result) means that calls to the function should beconsidered to have thrown if they return a non-zero result. The return type mustbe an integral type. If the return type would have been imported asBool,it is instead imported asVoid.

• swift_error(nonnull_error) means that calls to the function should beconsidered to have thrown if they leave a non-null error in the error parameter.The return type is left unmodified.

swift_name¶

Theswift_name attribute provides the name of the declaration in Swift. Ifthis attribute is absent, the name is transformed according to the algorithmbuilt into the Swift compiler.

The argument is a string literal that contains the Swift name of the function,variable, or type. When renaming a function, the name may be a compound Swiftname. For a type, enum constant, property, or variable declaration, the namemust be a simple or qualified identifier.

@interfaceURL-(void)initWithString:(NSString*)s__attribute__((__swift_name__("URL.init(_:)")))@endvoid__attribute__((__swift_name__("squareRoot()")))sqrt(doublev){}

swift_newtype¶

Theswift_newtype attribute indicates that the typedef to which theattribute appertains is imported as a new Swift type of the typedef’s name.Previously, the attribute was speltswift_wrapper. While the behaviour ofthe attribute is identical with either spelling,swift_wrapper isdeprecated, only exists for compatibility purposes, and should not be used innew code.

• swift_newtype(struct) means that a Swift struct will be created for thistypedef.

• swift_newtype(enum) means that a Swift enum will be created for thistypedef.

  // Import UIFontTextStyle as an enum type, with enumerated values being// constants.typedefNSString*UIFontTextStyle__attribute__((__swift_newtype__(enum)));// Import UIFontDescriptorFeatureKey as a structure type, with enumerated// values being members of the type structure.typedefNSString*UIFontDescriptorFeatureKey__attribute__((__swift_newtype__(struct)));

swift_objc_members¶

This attribute indicates that Swift subclasses and members of Swift extensionsof this class will be implicitly marked with the@objcMembers Swiftattribute, exposing them back to Objective-C.

swift_private¶

Declarations marked with theswift_private attribute are hidden from theframework client but are still made available for use within the framework orSwift SDK overlay.

The purpose of this attribute is to permit a more idomatic implementation ofdeclarations in Swift while hiding the non-idiomatic one.

Owner¶

The attribute[[gsl::Owner(T)]] applies to structs and classes that own anobject of typeT:

class [[gsl::Owner(int)]] IntOwner {private:  int value;public:  int *getInt() { return &value; }};

The argumentT is optional and is ignored.This attribute may be used by analysis tools and has no effect on codegeneration. Avoid argument means that the class can own any type.

SeePointer for an example.

Pointer¶

The attribute[[gsl::Pointer(T)]] applies to structs and classes that behavelike pointers to an object of typeT:

class [[gsl::Pointer(int)]] IntPointer {private:  int *valuePointer;public:  IntPointer(const IntOwner&);  int *getInt() { return valuePointer; }};

The argumentT is optional and is ignored.This attribute may be used by analysis tools and has no effect on codegeneration. Avoid argument means that the pointer can point to any type.

Example:When constructing an instance of a class annotated like this (a Pointer) froman instance of a class annotated with[[gsl::Owner]] (an Owner),then the analysis will consider the Pointer to point inside the Owner.When the Owner’s lifetime ends, it will consider the Pointer to be dangling.

intf(){IntPointerP(IntOwner{});// P "points into" a temporary IntOwner objectP.getInt();// P is dangling}

If a template class is annotated with[[gsl::Owner]], and the firstinstantiated template argument is a pointer type (raw pointer, or[[gsl::Pointer]]),the analysis will consider the instantiated class as a container of the pointer.When constructing such an object from a GSL owner object, the analysis willassume that the container holds a pointer to the owner object. Consequently,when the owner object is destroyed, the pointer will be considered dangling.

intf(){std::vector<std::string_view>v={std::string()};// v holds a dangling pointer.std::optional<std::string_view>o=std::string();// o holds a dangling pointer.}

__single_inheritance, __multiple_inheritance, __virtual_inheritance¶

This collection of keywords is enabled under-fms-extensions and controlsthe pointer-to-member representation used on*-*-win32 targets.

The*-*-win32 targets utilize a pointer-to-member representation whichvaries in size and alignment depending on the definition of the underlyingclass.

However, this is problematic when a forward declaration is only available andno definition has been made yet. In such cases, Clang is forced to utilize themost general representation that is available to it.

These keywords make it possible to use a pointer-to-member representation otherthan the most general one regardless of whether or not the definition will everbe present in the current translation unit.

This family of keywords belong between theclass-key andclass-name:

struct__single_inheritanceS;intS::*i;structS{};

This keyword can be applied to class templates but only has an effect when usedon full specializations:

template<typenameT,typenameU>struct__single_inheritanceA;// warning: inheritance model ignored on primary templatetemplate<typenameT>struct__multiple_inheritanceA<T,T>;// warning: inheritance model ignored on partial specializationtemplate<>struct__single_inheritanceA<int,float>;

Note that choosing an inheritance model less general than strictly necessary isan error:

struct__multiple_inheritanceS;// error: inheritance model does not match definitionintS::*i;structS{};

asm¶

This attribute can be used on a function or variable to specify its symbol name.

On some targets, all C symbols are prefixed by default with a single character,typically_. This was done historically to distinguish them from symbolsused by other languages. (This prefix is also added to the standard ItaniumC++ ABI prefix on “mangled” symbol names, so that e.g. on such targets the truesymbol name for a C++ variable declared asintcppvar; would be__Z6cppvar; note the two underscores.) This prefix isnot added to thesymbol names specified by theasm attribute; programmers wishing to match aC symbol name must compensate for this.

For example, consider the following C code:

intvar1asm("altvar")=1;// "altvar" in symbol table.intvar2=1;// "_var2" in symbol table.voidfunc1(void)asm("altfunc");voidfunc1(void){}// "altfunc" in symbol table.voidfunc2(void){}// "_func2" in symbol table.

Clang’s implementation of this attribute is compatible with GCC’s,documented here.

While it is possible to use this attribute to name a special symbol usedinternally by the compiler, such as an LLVM intrinsic, this is neitherrecommended nor supported and may cause the compiler to crash or miscompile.Users who wish to gain access to intrinsic behavior are strongly encouraged torequest new builtin functions.

coro_await_elidable¶

The[[clang::coro_await_elidable]] is a class attribute which can beapplied to a coroutine return type. It provides a hint to the compiler to applyHeap Allocation Elision more aggressively.

When a coroutine function returns such a type, a direct call expression thereinthat returns a prvalue of a type attributed[[clang::coro_await_elidable]]is said to be under a safe elide context if one of the following is true:- it is the immediate right-hand side operand to a co_await expression.- it is an argument to a[[clang::coro_await_elidable_argument]] parameteror parameter pack of another direct call expression under a safe elide context.

Do note that the safe elide context applies only to the call expression itself,and the context does not transitively include any of its subexpressions unlessexceptional rules of[[clang::coro_await_elidable_argument]] apply.

The compiler performs heap allocation elision on call expressions under a safeelide context, if the callee is a coroutine.

Example:

class[[clang::coro_await_elidable]]Task{...};Taskfoo();Taskbar(){co_awaitfoo();// foo()'s coroutine frame on this line is elidableautot=foo();// foo()'s coroutine frame on this line is NOT elidableco_awaitt;}

Such elision replaces the heap allocated activation frame of the callee coroutinewith a local variable within the enclosing braces in the caller’s stack frame.The local variable, like other variables in coroutines, may be collected into thecoroutine frame, which may be allocated on the heap. The behavior is undefinedif the caller coroutine is destroyed earlier than the callee coroutine.

coro_await_elidable_argument¶

The[[clang::coro_await_elidable_argument]] is a function parameter attribute.It works in conjunction with[[clang::coro_await_elidable]] to propagate asafe elide context to a parameter or parameter pack if the function is calledunder a safe elide context.

This is sometimes necessary on utility functions used to compose or modify thebehavior of a callee coroutine.

Example:

template<typenameT>class[[clang::coro_await_elidable]]Task{...};template<typename...T>class[[clang::coro_await_elidable]]WhenAll{...};// `when_all` is a utility function that composes coroutines. It does not// need to be a coroutine to propagate.template<typename...T>WhenAll<T...>when_all([[clang::coro_await_elidable_argument]]Task<T>tasks...);Task<int>foo();Task<int>bar();Task<void>example1(){// `when_all``, `foo``, and `bar` are all elide safe because `when_all` is// under a safe elide context and, thanks to the [[clang::coro_await_elidable_argument]]// attribute, such context is propagated to foo and bar.co_awaitwhen_all(foo(),bar());}Task<void>example2(){// `when_all` and `bar` are elide safe. `foo` is not elide safe.autof=foo();co_awaitwhen_all(f,bar());}Task<void>example3(){// None of the calls are elide safe.autot=when_all(foo(),bar());co_awaitt;}

coro_disable_lifetimebound, coro_lifetimebound¶

The[[clang::coro_lifetimebound]] is a class attribute which can be appliedto a coroutine return type (coro_return_type, coro_wrapper) (i.e.it should also be annotated with[[clang::coro_return_type]]).

All parameters of a function are considered to be lifetime bound if the function returns acoroutine return type (CRT) annotated with[[clang::coro_lifetimebound]].This lifetime bound analysis can be disabled for a coroutine wrapper or a coroutine by annotating the functionwith[[clang::coro_disable_lifetimebound]] function attribute .See documentation oflifetimebound for details about lifetime bound analysis.

Reference parameters of a coroutine are susceptible to capturing references to temporaries or local variables.

For example,

task<int>coro(constint&a){co_returna+1;}task<int>dangling_refs(inta){// `coro` captures reference to a temporary. `foo` would now contain a dangling reference to `a`.autofoo=coro(1);// `coro` captures reference to local variable `a` which is destroyed after the return.returncoro(a);}

Lifetime bound static analysis can be used to detect such instances when coroutines capture referenceswhich may die earlier than the coroutine frame itself. In the above example, if the CRTtask is annotated with[[clang::coro_lifetimebound]], then lifetime bound analysis would detect capturing reference totemporaries or return address of a local variable.

Both coroutines and coroutine wrappers are part of this analysis.

template<typenameT>struct[[clang::coro_return_type,clang::coro_lifetimebound]]Task{usingpromise_type=some_promise_type;};Task<int>coro(constint&a){co_returna+1;}[[clang::coro_wrapper]]Task<int>coro_wrapper(constint&a,constint&b){returna>b?coro(a):coro(b);}Task<int>temporary_reference(){autofoo=coro(1);// warning: capturing reference to a temporary which would die after the expression.inta=1;autobar=coro_wrapper(a,0);// warning: `b` captures reference to a temporary.co_returnco_awaitcoro(1);// fine.}[[clang::coro_wrapper]]Task<int>stack_reference(inta){returncoro(a);// warning: returning address of stack variable `a`.}

This analysis can be disabled for all calls to a particular function by annotating the functionwith function attribute[[clang::coro_disable_lifetimebound]].For example, this could be useful for coroutine wrappers which accept reference parametersbut do not pass them to the underlying coroutine or pass them by value.

Task<int>coro(inta){co_returna+1;}[[clang::coro_wrapper,clang::coro_disable_lifetimebound]]Task<int>coro_wrapper(constint&a){returncoro(a+1);}voiduse(){autotask=coro_wrapper(1);// use of temporary is fine as the argument is not lifetime bound.}

coro_only_destroy_when_complete¶

Thecoro_only_destroy_when_complete attribute should be marked on a C++ class. The coroutineswhose return type is marked with the attribute are assumed to be destroyed only after the coroutine hasreached the final suspend point.

This is helpful for the optimizers to reduce the size of the destroy function for the coroutines.

For example,

Afoo(){dtord;co_awaitsomething();dtord1;co_awaitsomething();dtord2;co_return43;}

The compiler may generate the following pseudocode:

voidfoo.destroy(foo.Frame*frame){switch(frame->suspend_index()){case1:frame->d.~dtor();break;case2:frame->d.~dtor();frame->d1.~dtor();break;case3:frame->d.~dtor();frame->d1.~dtor();frame->d2.~dtor();break;default:// coroutine completed or haven't startedbreak;}frame->promise.~promise_type();deleteframe;}

Thefoo.destroy() function’s purpose is to release all of the resourcesinitialized for the coroutine when it is destroyed in a suspended state.However, if the coroutine is only ever destroyed at the final suspend state,the rest of the conditions are superfluous.

The user can use thecoro_only_destroy_when_complete attributo suppressgeneration of the other destruction cases, optimizing the abovefoo.destroy to:

voidfoo.destroy(foo.Frame*frame){frame->promise.~promise_type();deleteframe;}

coro_return_type, coro_wrapper¶

The[[clang::coro_return_type]] attribute is used to help static analyzers to recognizecoroutines from the function signatures.

Thecoro_return_type attribute should be marked on a C++ class to mark it asacoroutine return type (CRT).

A functionRfunc(P1,..,PN) has a coroutine return type (CRT)R ifRis marked by[[clang::coro_return_type]] andR has a promise type associated to it(i.e., std::coroutine_traits<R, P1, .., PN>::promise_type is a valid promise type).

If the return type of a function is aCRT then the function must be a coroutine.Otherwise the program is invalid. It is allowed for a non-coroutine to return aCRTif the function is marked with[[clang::coro_wrapper]].

The[[clang::coro_wrapper]] attribute should be marked on a C++ function to mark it asacoroutine wrapper. A coroutine wrapper is a function which returns aCRT,is not a coroutine itself and is marked with[[clang::coro_wrapper]].

Clang will enforce that all functions that return aCRT are either coroutines or markedwith[[clang::coro_wrapper]]. Clang will enforce this with an error.

From a language perspective, it is not possible to differentiate between a coroutine and afunction returning a CRT by merely looking at the function signature.

Coroutine wrappers, in particular, are susceptible to capturingreferences to temporaries and other lifetime issues. This allows to avoid such lifetimeissues with coroutine wrappers.

For example,

// This is a CRT.template<typenameT>struct[[clang::coro_return_type]]Task{usingpromise_type=some_promise_type;};Task<int>increment(inta){co_returna+1;}// Fine. This is a coroutine.Task<int>foo(){returnincrement(1);}// Error. foo is not a coroutine.// Fine for a coroutine wrapper to return a CRT.[[clang::coro_wrapper]]Task<int>foo(){returnincrement(1);}voidbar(){// Invalid. This intantiates a function which returns a CRT but is not marked as// a coroutine wrapper.std::function<Task<int>(int)>f=increment;}

Note:a_promise_type::get_return_object is exempted from this analysis as it is a necessaryimplementation detail of any coroutine library.

deprecated¶

Thedeprecated attribute can be applied to a function, a variable, or atype. This is useful when identifying functions, variables, or types that areexpected to be removed in a future version of a program.

Consider the function declaration for a hypothetical functionf:

voidf(void)__attribute__((deprecated("message","replacement")));

When spelled as__attribute__((deprecated)), the deprecated attribute can havetwo optional string arguments. The first one is the message to display whenemitting the warning; the second one enables the compiler to provide a Fix-Itto replace the deprecated name with a new name. Otherwise, when spelled as[[gnu::deprecated]] or[[deprecated]], the attribute can have one optionalstring argument which is the message to display when emitting the warning.

empty_bases¶

The empty_bases attribute permits the compiler to utilize theempty-base-optimization more frequently.This attribute only applies to struct, class, and union types.It is only supported when using the Microsoft C++ ABI.

enum_extensibility¶

Attributeenum_extensibility is used to distinguish between enum definitionsthat are extensible and those that are not. The attribute can take eitherclosed oropen as an argument.closed indicates a variable of theenum type takes a value that corresponds to one of the enumerators listed in theenum definition or, when the enum is annotated withflag_enum, a value thatcan be constructed using values corresponding to the enumerators.openindicates a variable of the enum type can take any values allowed by thestandard and instructs clang to be more lenient when issuing warnings.

enum__attribute__((enum_extensibility(closed)))ClosedEnum{A0,A1};enum__attribute__((enum_extensibility(open)))OpenEnum{B0,B1};enum__attribute__((enum_extensibility(closed),flag_enum))ClosedFlagEnum{C0=1<<0,C1=1<<1};enum__attribute__((enum_extensibility(open),flag_enum))OpenFlagEnum{D0=1<<0,D1=1<<1};voidfoo1(){enumClosedEnumce;enumOpenEnumoe;enumClosedFlagEnumcfe;enumOpenFlagEnumofe;ce=A1;// no warningsce=100;// warning issuedoe=B1;// no warningsoe=100;// no warningscfe=C0|C1;// no warningscfe=C0|C1|4;// warning issuedofe=D0|D1;// no warningsofe=D0|D1|4;// no warnings}

external_source_symbol¶

Theexternal_source_symbol attribute specifies that a declaration originatesfrom an external source and describes the nature of that source.

The fact that Clang is capable of recognizing declarations that were definedexternally can be used to provide better tooling support for mixed-languageprojects or projects that rely on auto-generated code. For instance, an IDE thatuses Clang and that supports mixed-language projects can use this attribute toprovide a correct ‘jump-to-definition’ feature. For a concrete example,consider a protocol that’s defined in a Swift file:

@objcpublicprotocolSwiftProtocol{funcmethod()}

This protocol can be used from Objective-C code by including a header file thatwas generated by the Swift compiler. The declarations in that header can usetheexternal_source_symbol attribute to make Clang aware of the factthatSwiftProtocol actually originates from a Swift module:

__attribute__((external_source_symbol(language="Swift",defined_in="module")))@protocolSwiftProtocol@required-(void)method;@end

Consequently, when ‘jump-to-definition’ is performed at a location thatreferencesSwiftProtocol, the IDE can jump to the original definition inthe Swift source file rather than jumping to the Objective-C declaration in theauto-generated header file.

Theexternal_source_symbol attribute is a comma-separated list that includesclauses that describe the origin and the nature of the particular declaration.Those clauses can be:

language=string-literal

The name of the source language in which this declaration was defined.

defined_in=string-literal

The name of the source container in which the declaration was defined. Theexact definition of source container is language-specific, e.g. Swift’ssource containers are modules, sodefined_in should specify the Swiftmodule name.

USR=string-literal

String that specifies a unified symbol resolution (USR) value for thisdeclaration. USR string uniquely identifies this particular declaration, andis typically used when constructing an index of a codebase.The USR value in this attribute is expected to be generated by an externalcompiler that compiled the native declaration using its original sourcelanguage. The exact format of the USR string and its other attributesare determined by the specification of this declaration’s source language.When not specified, Clang’s indexer will use the Clang USR for this symbol.User can query to see if Clang supports the use of theUSR clause intheexternal_source_symbol attribute with__has_attribute(external_source_symbol)>=20230206.

generated_declaration

This declaration was automatically generated by some tool.

The clauses can be specified in any order. The clauses that are listed above areall optional, but the attribute has to have at least one clause.

flag_enum¶

This attribute can be added to an enumerator to signal to the compiler that itis intended to be used as a flag type. This will cause the compiler to assumethat the range of the type includes all of the values that you can get bymanipulating bits of the enumerator when issuing warnings.

grid_constant¶

The__grid_constant__ attribute can be applied to aconst-qualified kernelfunction argument and allows compiler to take the address of that argument withoutmaking a copy. The argument applies to sm_70 or newer GPUs, during compilationwith CUDA-11.7(PTX 7.7) or newer, and is ignored otherwise.

layout_version¶

The layout_version attribute requests that the compiler utilize the classlayout rules of a particular compiler version.This attribute only applies to struct, class, and union types.It is only supported when using the Microsoft C++ ABI.

lto_visibility_public¶

SeeLTO Visibility.

managed¶

The__managed__ attribute can be applied to a global variable declaration in HIP.A managed variable is emitted as an undefined global symbol in the device binary and isregistered by__hipRegisterManagedVariable in init functions. The HIP runtime allocatesmanaged memory and uses it to define the symbol when loading the device binary.A managed variable can be accessed in both device and host code.

no_init_all¶

The__declspec(no_init_all) attribute disables the automatic initialization that the-ftrivial-auto-var-init flag would have applied to locals in a marked function, or instances ofa marked type. Note that this attribute has no effect for locals that are automatically initializedwithout the-ftrivial-auto-var-init flag.

no_specializations¶

[[clang::no_specializations]] can be applied to function, class, or variabletemplates which should not be explicitly specialized by users. This is primarilyused to diagnose user specializations of standard library type traits.

nonstring¶

Thenonstring attribute can be applied to the declaration of a variable ora field whose type is a character array to specify that the character array isnot intended to behave like a null-terminated string. This will silencediagnostics with code like:

charBadStr[3]="foo";// No space for the null terminator, diagnosed__attribute__((nonstring))charNotAStr[3]="foo";// Not diagnosed

novtable¶

This attribute can be added to a class declaration or definition to signal tothe compiler that constructors and destructors will not reference the virtualfunction table. It is only supported when using the Microsoft C++ ABI.

ns_error_domain¶

In Cocoa frameworks in Objective-C, one can group related error codes in enumsand categorize these enums with error domains.

Thens_error_domain attribute indicates a globalNSString orCFString constant representing the error domain that an error code belongsto. For pointer uniqueness and code size this is a constant symbol, not aliteral.

The domain and error code need to be used together. Thens_error_domainattribute links error codes to their domain at the source level.

This metadata is useful for documentation purposes, for static analysis, and forimproving interoperability between Objective-C and Swift. It is not used forcode generation in Objective-C.

For example:

#define NS_ERROR_ENUM(_type, _name, _domain)  \  enum _name : _type _name; enum __attribute__((ns_error_domain(_domain))) _name : _typeexternNSString*constMyErrorDomain;typedefNS_ERROR_ENUM(unsignedchar,MyErrorEnum,MyErrorDomain){MyErrFirst,MyErrSecond,};

objc_boxable¶

Structs and unions marked with theobjc_boxable attribute can be usedwith the Objective-C boxed expression syntax,@(...).

Usage:__attribute__((objc_boxable)). This attributecan only be placed on a declaration of a trivially-copyable struct or union:

struct__attribute__((objc_boxable))some_struct{inti;};union__attribute__((objc_boxable))some_union{inti;floatf;};typedefstruct__attribute__((objc_boxable))_some_structsome_struct;// ...some_structss;NSValue*boxed=@(ss);

objc_direct¶

Theobjc_direct attribute can be used to mark an Objective-C method asbeingdirect. A direct method is treated statically like an ordinary method,but dynamically it behaves more like a C function. This lowers some of the costsassociated with the method but also sacrifices some of the ordinary capabilitiesof Objective-C methods.

A message send of a direct method calls the implementation directly, as if itwere a C function, rather than using ordinary Objective-C method dispatch. Thisis substantially faster and potentially allows the implementation to be inlined,but it also means the method cannot be overridden in subclasses or replaceddynamically, as ordinary Objective-C methods can.

Furthermore, a direct method is not listed in the class’s method lists. Thissubstantially reduces the code-size overhead of the method but also means itcannot be called dynamically using ordinary Objective-C method dispatch at all;in particular, this means that it cannot override a superclass method or satisfya protocol requirement.

Because a direct method cannot be overridden, it is an error to performasuper message send of one.

Although a message send of a direct method causes the method to be calleddirectly as if it were a C function, it still obeys Objective-C semantics in otherways:

• If the receiver isnil, the message send does nothing and returns the zero valuefor the return type.

• A message send of a direct class method will cause the class to be initialized,including calling the+initialize method if present.

• The implicit_cmd parameter containing the method’s selector is still defined.In order to minimize code-size costs, the implementation will not emit a referenceto the selector if the parameter is unused within the method.

Symbols for direct method implementations are implicitly given hiddenvisibility, meaning that they can only be called within the same linkage unit.

It is an error to do any of the following:

• declare a direct method in a protocol,

• declare an override of a direct method with a method in a subclass,

• declare an override of a non-direct method with a direct method in a subclass,

• declare a method with different directness in different class interfaces, or

• implement a non-direct method (as declared in any class interface) with a direct method.

If any of these rules would be violated if every method defined in an@implementation within a single linkage unit were declared in anappropriate class interface, the program is ill-formed with no diagnosticrequired. If a violation of this rule is not diagnosed, behavior remainswell-defined; this paragraph is simply reserving the right to diagnose suchconflicts in the future, not to treat them as undefined behavior.

Additionally, Clang will warn about any@selector expression thatnames a selector that is only known to be used for direct methods.

For the purpose of these rules, a “class interface” includes a class’s primary@interface block, its class extensions, its categories, its declared protocols,and all the class interfaces of its superclasses.

An Objective-C property can be declared with thedirect propertyattribute. If a direct property declaration causes an implicit declaration ofa getter or setter method (that is, if the given method is not explicitlydeclared elsewhere), the method is declared to be direct.

Some programmers may wish to make many methods direct at once. In orderto simplify this, theobjc_direct_members attribute is provided; see itsdocumentation for more information.

objc_direct_members¶

Theobjc_direct_members attribute can be placed on an Objective-C@interface or@implementation to mark that methods declaredtherein should be considered direct by default. See the documentationforobjc_direct for more information about direct methods.

Whenobjc_direct_members is placed on an@interface block, everymethod in the block is considered to be declared as direct. This includes anyimplicit method declarations introduced by property declarations. If the methodredeclares a non-direct method, the declaration is ill-formed, exactly as if themethod was annotated with theobjc_direct attribute.

Whenobjc_direct_members is placed on an@implementation block,methods defined in the block are considered to be declared as direct unlessthey have been previously declared as non-direct in any interface of the class.This includes the implicit method definitions introduced by synthesizedproperties, including auto-synthesized properties.

objc_non_runtime_protocol¶

Theobjc_non_runtime_protocol attribute can be used to mark that anObjective-C protocol is only used during static type-checking and doesn’t needto be represented dynamically. This avoids several small code-size and run-timeoverheads associated with handling the protocol’s metadata. A non-runtimeprotocol cannot be used as the operand of a@protocol expression, anddynamic attempts to find it withobjc_getProtocol will fail.

If a non-runtime protocol inherits from any ordinary protocols, classes andderived protocols that declare conformance to the non-runtime protocol willdynamically list their conformance to those bare protocols.

objc_nonlazy_class¶

This attribute can be added to an Objective-C@interface or@implementation declaration to add the class to the list of non-lazilyinitialized classes. A non-lazy class will be initialized eagerly when theObjective-C runtime is loaded. This is required for certain system classes whichhave instances allocated in non-standard ways, such as the classes for blocksand constant strings. Adding this attribute is essentially equivalent toproviding a trivial+load method but avoids the (fairly small) load-timeoverheads associated with defining and calling such a method.

objc_runtime_name¶

By default, the Objective-C interface or protocol identifier is usedin the metadata name for that object. Theobjc_runtime_nameattribute allows annotated interfaces or protocols to use thespecified string argument in the object’s metadata name instead of thedefault name.

Usage:__attribute__((objc_runtime_name("MyLocalName"))). This attributecan only be placed before an @protocol or @interface declaration:

__attribute__((objc_runtime_name("MyLocalName")))@interfaceMessage@end

objc_runtime_visible¶

This attribute specifies that the Objective-C class to which it applies isvisible to the Objective-C runtime but not to the linker. Classes annotatedwith this attribute cannot be subclassed and cannot have categories defined forthem.

objc_subclassing_restricted¶

This attribute can be added to an Objective-C@interface declaration toensure that this class cannot be subclassed.

preferred_name¶

Thepreferred_name attribute can be applied to a class template, andspecifies a preferred way of naming a specialization of the template. Thepreferred name will be used whenever the corresponding template specializationwould otherwise be printed in a diagnostic or similar context.

The preferred name must be a typedef or type alias declaration that refers to aspecialization of the class template (not including any type qualifiers). Ingeneral this requires the template to be declared at least twice. For example:

template<typenameT>structbasic_string;usingstring=basic_string<char>;usingwstring=basic_string<wchar_t>;template<typenameT>struct[[clang::preferred_name(string),clang::preferred_name(wstring)]]basic_string{// ...};

Note that thepreferred_name attribute will be ignored when the compilerwrites a C++20 Module interface now. This is due to a compiler issue(https://github.com/llvm/llvm-project/issues/56490) that blocks users to modularizedeclarations withpreferred_name. This is intended to be fixed in the future.

randomize_layout, no_randomize_layout¶

The attributerandomize_layout, when attached to a C structure, selects itfor structure layout field randomization; a compile-time hardening technique. A“seed” value, is specified via the-frandomize-layout-seed= command line flag.For example:

SEED=`od-An-tx8-N32/dev/urandom|tr-d' \n'`make...CFLAGS="-frandomize-layout-seed=$SEED"...

You can also supply the seed in a file with-frandomize-layout-seed-file=.For example:

od-An-tx8-N32/dev/urandom|tr-d' \n'>/tmp/seed_file.txtmake...CFLAGS="-frandomize-layout-seed-file=/tmp/seed_file.txt"...

The randomization is deterministic based for a given seed, so the entireprogram should be compiled with the same seed, but keep the seed safeotherwise.

The attributeno_randomize_layout, when attached to a C structure,instructs the compiler that this structure should not have its field layoutrandomized.

selectany¶

This attribute appertains to a global symbol, causing it to have a weakdefinition (linkonce), allowing the linker to select any definition.

For more information seegcc documentationormsvc documentation.

transparent_union¶

This attribute can be applied to a union to change the behavior of calls tofunctions that have an argument with a transparent union type. The compilerbehavior is changed in the following manner:

• A value whose type is any member of the transparent union can be passed as anargument without the need to cast that value.

• The argument is passed to the function using the calling convention of thefirst member of the transparent union. Consequently, all the members of thetransparent union should have the same calling convention as its first member.

Transparent unions are not supported in C++.

trivial_abi¶

Thetrivial_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 theunderlying type when the type would otherwise be considered non-trivial for thepurpose of calls.A class annotated withtrivial_abi can have non-trivial destructors orcopy/move constructors without automatically becoming non-trivial for thepurposes of calls. For example:

// A is trivial for the purposes of calls because ``trivial_abi`` makes the// user-provided special functions trivial.struct__attribute__((trivial_abi))A{~A();A(constA&);A(A&&);intx;};// B's destructor and copy/move constructor are considered trivial for the// purpose of calls because A is trivial.structB{Aa;};

If a type is trivial for the purposes of calls, has a non-trivial destructor,and is passed as an argument by value, the convention is that the callee willdestroy the object before returning. The lifetime of the copy of the parameterin the caller ends without a destructor call when the call begins.

If a type is trivial for the purpose of calls, it is assumed to be triviallyrelocatable for the purpose of__is_trivially_relocatable and__builtin_is_cpp_trivially_relocatable.When a type marked with[[trivial_abi]] is used as a function argument,the compiler may omit the call to the copy constructor.Thus, side effects of the copy constructor are potentially not performed.For example, objects that contain pointers to themselves or otherwise dependon their address (or the address or their subobjects) should not be declared[[trivial_abi]].

Attributetrivial_abi has no effect in the following cases:

• The class directly declares a virtual base or virtual methods.

• Copy constructors and move constructors of the class are all deleted.

• The class has a base class that is non-trivial for the purposes of calls.

• The class has a non-static data member whose type is non-trivial for thepurposes of calls, which includes:

  • classes that are non-trivial for the purposes of calls

  • __weak-qualified types in Objective-C++

  • arrays of any of the above

using_if_exists¶

Theusing_if_exists attribute applies to a using-declaration. It allowsprogrammers to import a declaration that potentially does not exist, insteaddeferring any errors to the point of use. For instance:

namespaceempty_namespace{};__attribute__((using_if_exists))usingempty_namespace::does_not_exist;// no error!does_not_existx;// error: use of unresolved 'using_if_exists'

The C++ spelling of the attribute ([[clang::using_if_exists]]) is alsosupported as a clang extension, since ISO C++ doesn’t support attributes in thisposition. If the entity referred to by the using-declaration is found by namelookup, the attribute has no effect. This attribute is useful for libraries(primarily, libc++) that wish to redeclare a set of declarations in anothernamespace, when the availability of those declarations is difficult orimpossible to detect at compile time with the preprocessor.

weak¶

In supported output formats theweak attribute can be used tospecify that a variable or function should be emitted as a symbol withweak (if a definition) orextern_weak (if a declaration of anexternal symbol)linkage.

If there is a non-weak definition of the symbol the linker will selectthat over the weak. They must have same type and alignment (variablesmust also have the same size), but may have a different value.

If there are multiple weak definitions of same symbol, but no non-weakdefinition, they should have same type, size, alignment and value, thelinker will select one of them (see alsoselectany attribute).

If theweak attribute is applied to aconst qualified variabledefinition that variable is no longer consider a compiletime constantas its value can change during linking (or dynamic linking). Thismeans that it can e.g no longer be part of an initializer expression.

constintANSWER__attribute__((weak))=42;/* This function may be replaced link-time */__attribute__((weak))voiddebug_log(constchar*msg){fprintf(stderr,"DEBUG: %s\n",msg);}intmain(intargc,constchar**argv){debug_log("Starting up...");/* This may print something else than "6 * 7 = 42",       if there is a non-weak definition of "ANSWER" in       an object linked in */printf("6 * 7 = %d\n",ANSWER);return0;}

If an external declaration is marked weak and that symbol does notexist during linking (possibly dynamic) the address of the symbol willevaluate to NULL.

voidmay_not_exist(void)__attribute__((weak));intmain(intargc,constchar**argv){if(may_not_exist){may_not_exist();}else{printf("Function did not exist\n");}return0;}

counted_by, counted_by_or_null, sized_by, sized_by_or_null¶

Clang supports thecounted_by attribute on the flexible array member of astructure in C. The argument for the attribute is the name of a field memberholding the count of elements in the flexible array. This information can beused to improve the results of the array bound sanitizer and the__builtin_dynamic_object_size builtin. Thecount field member must bewithin the same non-anonymous, enclosing struct as the flexible array member.

This example specifies that the flexible array memberarray has the numberof elements allocated for it incount:

structbar;structfoo{size_tcount;charother;structbar*array[]__attribute__((counted_by(count)));};

This establishes a relationship betweenarray andcount. Specifically,array must have at leastcount number of elements available. It’s theuser’s responsibility to ensure that this relationship is maintained throughchanges to the structure.

In the following example, the allocated array erroneously has fewer elementsthan what’s specified byp->count. This would result in an out-of-boundsaccess not being detected.

#define SIZE_INCR 42structfoo*p;voidfoo_alloc(size_tcount){p=malloc(MAX(sizeof(structfoo),offsetof(structfoo,array[0])+count*sizeof(structbar*)));p->count=count+SIZE_INCR;}