#include <libkern/c++/OSMetaClass.h>

libkern/c++/OSMetaClass.h Kernel.framework

LIBKERN_ macros below can be used to describe the ownership semantics of functions handling subclasses of OSObject. The attributes propagate with inheritance, but can be overriden. New versions of the Clang Static Analyzer can use this knowledge to check the code for leaks or uses-after-free.

includes: sys/types.h, Kernel/libkern/OSReturn.h, kern/debug.h, Kernel/ptrauth.h, TargetConditionals.h

67 macros · 3 classs

macroLIBKERN_RETURNS_RETAINED

By default, methods returning OSObjects are assumed to have the following owneship semantics: - Methods which start with "get" are "Get" and which are not returning a subclass of OSIterator are assumed to be getters. They return at "+0" and the caller is not responsible for releasing the returned object. - All other methods are assumed to return at "+1", and the caller is responsible for releasing the returned object. The semantics implied by the naming convention described above can be overriden using either LIBKERN_RETURNS_RETAINED or LIBKERN_RETURNS_NOT_RETAINED attribute applied to a function. In the former case, it stipulates that the function is returning at "+1", and in the latter case "+0". LIBKERN_RETURNS_RETAINED and LIBKERN_RETURNS_NOT_RETAINED attributes can be also applied to out parameters, in which case they specify that an out parameter is written into at +1 or +0 respectively. For out parameters of non-void functions an assumption is that an out parameter is written into iff the return value is non-zero unless the function returns a typedef to kern_return_t, in which case it is assumed to be written into on zero value (kIOReturnSuccess). This can be customized using the attributes LIBKERN_RETURNS_RETAINED_ON_ZERO and LIBKERN_RETURNS_RETAINED_ON_NONZERO.

#define LIBKERN_RETURNS_RETAINED __attribute__((os_returns_retained))

macroLIBKERN_RETURNS_NOT_RETAINED

#define LIBKERN_RETURNS_NOT_RETAINED __attribute__((os_returns_not_retained))

macroLIBKERN_CONSUMED

LIBKERN_CONSUMED attribute can be applied to parameters. It specifies that this function call would consume the reference to the annotated parameter.

#define LIBKERN_CONSUMED __attribute__((os_consumed))

macroLIBKERN_CONSUMES_THIS

LIBKERN_CONSUMES_THIS attribute can be applied to methods. It specifies that this method call consumes a reference to "this" (e.g. by storing a reference to "this" in a passed parameter).

#define LIBKERN_CONSUMES_THIS __attribute__((os_consumes_this))

macroLIBKERN_RETURNS_RETAINED_ON_ZERO

LIBKERN_RETURNS_RETAINED_ON_ZERO is an attribute applicable to out parameters. It specifies that an out parameter at +1 is written into an argument iff the function returns a zero return value.

#define LIBKERN_RETURNS_RETAINED_ON_ZERO __attribute__((os_returns_retained_on_zero))

macroLIBKERN_RETURNS_RETAINED_ON_NONZERO

LIBKERN_RETURNS_RETAINED_ON_NON_ZERO is an attribute applicable to out parameters. It specifies that an out parameter at +1 is written into an argument iff the function returns a non-zero return value.

#define LIBKERN_RETURNS_RETAINED_ON_NONZERO __attribute__((os_returns_retained_on_non_zero))

classOSInterface

macroAPPLE_KEXT_COMPATIBILITY

@parseOnly

#define APPLE_KEXT_COMPATIBILITY

macroAPPLE_KEXT_VTABLE_PADDING

#define APPLE_KEXT_VTABLE_PADDING 1

macroAPPLE_KEXT_ALIGN_CONTAINERS

#define APPLE_KEXT_ALIGN_CONTAINERS 1

macroAPPLE_KEXT_LEGACY_ABI

@parseOnly

#define APPLE_KEXT_LEGACY_ABI 0

macroAPPLE_KEXT_COMPATIBILITY_VIRTUAL

@parseOnly

#define APPLE_KEXT_COMPATIBILITY_VIRTUAL

macroAPPLE_KEXT_DEPRECATED

@parseOnly

#define APPLE_KEXT_DEPRECATED __attribute__((deprecated))

macroAPPLE_KEXT_OVERRIDE

<rdar://problem/44872498> AppleUSBAudio builds xnu's libkern headers in user space

#define APPLE_KEXT_OVERRIDE override

macroAPPLE_KEXT_COMPATIBILITY_OVERRIDE

#define APPLE_KEXT_COMPATIBILITY_OVERRIDE

macroAPPLE_KEXT_WSHADOW_PUSH

#define APPLE_KEXT_WSHADOW_PUSH _Pragma("clang diagnostic push")
	_Pragma("clang diagnostic ignored \"-Wunknown-warning-option\"")
	_Pragma("clang diagnostic ignored \"-Wshadow-field\"")

macroAPPLE_KEXT_WSHADOW_POP

#define APPLE_KEXT_WSHADOW_POP _Pragma("clang diagnostic pop")

classOSMetaClassBase

static _ptf_t _ptmf2ptf(const OSMetaClassBase * self, void (OSMetaClassBase::*func)(void))static

virtual void release(int freeWhen) const = 0pure virtual

@function release @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int) release(int freeWhen)@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int) release(int freeWhen)@/link</code>.

virtual int getRetainCount() const = 0pure virtual

@function getRetainCount @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/getRetainCount/virtualint/() getRetainCount()@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/getRetainCount/virtualint/() OSObject::getRetainCount()@/link</code>.

virtual void retain() const = 0pure virtual

@function retain @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() retain()@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() OSObject::retain()@/link</code>.

virtual void release() const = 0pure virtual

@function release @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/release/virtualvoid/() release@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/release/virtualvoid/() OSObject::release@/link</code>.

virtual bool serialize(OSSerialize * serializer) const = 0pure virtual

@function serialize @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*) serialize@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*) OSObject::serialize@/link</code>.

virtual bool isEqualTo(const OSMetaClassBase * anObject) constvirtual

@function isEqualTo @abstract Checks whether another object is equal to the receiver. @param anObject The object to copmare to the receiver. @result <code>true</code> if the objects are equal, <code>false</code> otherwise. @discussion OSMetaClassBase implements this as a direct pointer comparison, since it has no other information to judge equality by. Subclasses generally override this function to do a more meaningful comparison. For example, OSString implements it to return <code>true</code> if <code>anObject</code> is derived from OSString and represents the same C string.

OSMetaClassBase * metaCast(const OSMetaClass * toMeta) const

@function metaCast @abstract Casts this object is to the class managed by the given OSMetaClass. @param toMeta A pointer to a constant OSMetaClass for the desired target type. @result <code>this</code> if the object is derived from the class managed by <code>toMeta</code>, otherwise <code>NULL</code>. @discussion It is far more convenient to use <code>@link OSDynamicCast OSDynamicCast@/link</code>.

OSMetaClassBase * metaCast(const OSSymbol * toMeta) const

@function metaCast @abstract Casts this object is to the class managed by the named OSMetaClass. @param toMeta An OSSymbol naming the desired target type. @result <code>this</code> if the object is derived from the class named by <code>toMeta</code>, otherwise <code>NULL</code>. @discussion It is far more convenient to use <code>@link OSDynamicCast OSDynamicCast@/link</code>.

OSMetaClassBase * metaCast(const OSString * toMeta) const

@function metaCast @abstract Casts this object is to the class managed by the named OSMetaClass. @param toMeta An OSString naming the desired target type. @result <code>this</code> if the object is derived from the class named by <code>toMeta</code>, otherwise <code>NULL</code>. @discussion It is far more convenient to use <code>@link OSDynamicCast OSDynamicCast@/link</code>.

OSMetaClassBase * metaCast(const char * toMeta) const

@function metaCast @abstract Casts this object is to the class managed by the named OSMetaClass. @param toMeta A C string naming the desired target type. @result <code>this</code> if the object is derived from the class named by <code>toMeta</code>, otherwise <code>NULL</code>. @discussion It is far more convenient to use <code>@link OSDynamicCast OSDynamicCast@/link</code>.

static OSMetaClassBase * safeMetaCast(
	const OSMetaClassBase * anObject,
	const OSMetaClass * toMeta
)

static

Helper inlines for run-time type preprocessor macros @function safeMetaCast @abstract Casts an object is to the class managed by the given OSMetaClass. @param anObject A pointer to the object to be cast. @param toMeta A pointer to a constant OSMetaClass for the desired target type. @result <code>anObject</code> if the object is derived from the class managed by <code>toMeta</code>, otherwise <code>NULL</code>. @discussion It is far more convenient to use <code>@link OSDynamicCast OSDynamicCast@/link</code>.

static OSMetaClassBase *requiredMetaCast(
	const OSMetaClassBase * anObject,
	const OSMetaClass * toMeta
)

static

@function requiredMetaCast @abstract Casts an object to the class managed by the given OSMetaClass or fails with a kernel panic if the cast does not succeed. @param anObject A pointer to the object to be cast. @param toMeta A pointer to a constant OSMetaClass for the desired target type. @result <code>anObject</code> if the object is derived from the class managed by <code>toMeta</code>, <code>NULL</code> if <code>anObject</code> was <code>NULL</code>, kernel panic otherwise. @discussion It is far more convenient to use <code>@link OSRequiredCast OSRequiredCast@/link</code>.

static bool checkTypeInst(const OSMetaClassBase * inst, const OSMetaClassBase * typeinst)static

@function checkTypeInst @abstract Checks whether an object instance is of the same class as another object instance (or a subclass of that class). @param inst A pointer to the object to check. @param typeinst A pointer to an object of the class being checked. @result <code>true</code> if the object is derived from the class of <code>typeinst</code> or a subclass of that class, otherwise <code>false</code>. @discussion It is far more convenient to use <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.

static void initialize(void)static

virtual void taggedRetain(const void * tag = NULL) const = 0pure virtual

@function taggedRetain @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*) taggedRetain(const void *)@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*) OSObject::taggedRetain(const void *)@/link</code>. WAS: virtual void _RESERVEDOSMetaClassBase0();

virtual void taggedRelease(const void * tag = NULL) const = 0pure virtual

@function taggedRelease @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*) taggedRelease(const void *)@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*) OSObject::taggedRelease(const void *)@/link</code>. WAS: virtual void _RESERVEDOSMetaClassBase1();

virtual void taggedRelease(const void * tag, const int freeWhen) const = 0pure virtual protected

@function taggedRelease @abstract Abstract declaration of <code>@link //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint) taggedRelease(const void *, const int freeWhen)@/link</code>. @discussion See <code>@link //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint) OSObject::taggedRelease(const void *, const int freeWhen)@/link</code>. WAS: virtual void _RESERVEDOSMetaClassBase2();

virtual kern_return_t Dispatch(const IORPC rpc)virtual

kern_return_t Invoke(const IORPC rpc)

macroOSTypeAlloc

@define OSTypeAlloc @hidecontents @abstract Allocates an instance of the named object class. @param type The name of the desired class to be created, as a raw token, not a string or macro. @result A pointer to the new, uninitialized object on success; <code>NULL</code> on failure. @discussion See also <code>@link //apple_ref/cpp/clm/OSMetaClass/allocClassWithName/staticOSObject*\/(constchar*) OSMetaClass::allocClassWithName(const char *)@/link</code> and <code>@link //apple_ref/cpp/instm/OSMetaClass/alloc/virtualOSObject*\/() OSMetaClass::alloc@/link</code>. The OSTypeAlloc macro is used to avoid binary compatibility difficulties presented by the C++ <code>new</code> operator.

#define OSTypeAlloc(type) ((type *) ((type::metaClass)->alloc()))

macroOSTypeID

@define OSTypeID @hidecontents @abstract Returns the type ID (metaclass) of a class based on its name. @param type The name of the desired class, as a raw token, not a string or macro. @result The unique type ID (metaclass) for the class. @discussion It is typically more useful to determine whether a class is derived from another; see <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code> and <code>@link //apple_ref/cpp/macro/OSCheckTypeInst OSCheckTypeInst@/link</code>.

#define OSTypeID(type) (type::metaClass)

macroOSMTypeID

#define OSMTypeID(type) (const_cast<OSMetaClass *>(type::metaClass))

macroOSTypeIDInst

@define OSTypeIDInst @hidecontents @abstract Returns the type ID (metaclass) for the class of an object instance. @param typeinst An instance of an OSObject subclass. @result The type ID of that object's class; that is, its metaclass. @discussion It is typically more useful to determine whether an object is derived from a particular class; see <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code> and <code>@link //apple_ref/cpp/macro/OSCheckTypeInst OSCheckTypeInst@/link</code>.

#define OSTypeIDInst(typeinst) ((typeinst)->getMetaClass())

macroOSDynamicCast

@define OSDynamicCast @hidecontents @abstract Safe type-casting for Libkern C++ objects. @param type The name of the desired class type, as a raw token, not a string or macro. It is assumed you intend to cast to a pointer to an object of this type. Type qualifiers, such as <code>const</code>, are not recognized and will cause a (usually obscure) compile error. @param inst A pointer to the object instance to be cast. May be <code>NULL</code>. @result <code>inst</code> if it is non-<code>NULL</code> and derived from <code>type</code>; otherwise <code>NULL</code>. @discussion <code>OSDynamicCast</code> is a rough equivalent to the standard C++ RTTI <code>dynamic_cast<T></code> operator. Your code should use this instead of raw C type-casting, and check the resulting value. If the result is non-<code>NULL</code>, the object is safe to use as the type-cast class; if the result is <code>NULL</code>, the object does not derive from the type-cast class and your code should take appropriate steps to handle the error.

#define OSDynamicCast(type, inst) ((type *) OSMetaClassBase::safeMetaCast((inst), OSTypeID(type)))

macroOSRequiredCast

@define OSRequiredCast @hidecontents @abstract Safe type-casting for Libkern C++ objects; panics on failure. The input parameters are the same as for the {@code OSDynamicCast} macro. @result {@code inst} if it is NULL or derived from {@code type}; otherwise triggers a kernel panic. @discussion This macro should be used in place of C-style casts or <code>@link OSDynamicCast OSDynamicCast@/link</code>. when the caller is absolutely sure that the passed argument is a subclass of a required type. It is equivalent to using {@code OSDynamicCast} and crashing with a kernel panic on cast failure.

#define OSRequiredCast(type, inst) ((type *) OSMetaClassBase::requiredMetaCast((inst), OSTypeID(type)))

macroOSCheckTypeInst

@define OSCheckTypeInst @hidecontents @abstract Checks whether two objects are type-compatible. @param typeinst The reference object. @param inst The object to check for type compatibility. @result <code>true</code> if both <code>inst</code> and <code>typeinst</code> are non-<code>NULL</code> and <code>inst</code> is derived from the class of <code>typeinst</code>; otherwise <code>false</code>.

#define OSCheckTypeInst(typeinst, inst) OSMetaClassBase::checkTypeInst(inst, typeinst)

macroOSSafeRelease

#define OSSafeRelease(inst) do { int OSSafeRelease __attribute__ ((deprecated("Use OSSafeReleaseNULL"))); (OSSafeRelease);
	if (inst) (inst)->release(); } while (0)

macroOSSafeReleaseNULL

@function OSSafeReleaseNULL @abstract Release an object if not <code>NULL</code>, then set it to <code>NULL</code>. @param inst Instance of an OSObject, may be <code>NULL</code>.

#define OSSafeReleaseNULL(inst) do { if (inst != NULL) (inst)->release(); (inst) = NULL; } while (0)

macroOSMemberFunctionCast

#define OSMemberFunctionCast(cptrtype, self, func) (cptrtype) OSMetaClassBase::
	_ptmf2ptf(self, (void (OSMetaClassBase::*)(void)) func)

classOSMetaClass

@class OSMetaClass @abstract OSMetaClass manages run-time type information for Libkern and I/O Kit C++ classes. @discussion OSMetaClass manages run-time type information for Libkern and I/O Kit C++ classes. An instance of OSMetaClass exists for (nearly) every such C++ class, keeping track of inheritance relationships, class lookup by name, instance counts, and more. OSMetaClass operates almost entirely behind the scenes, and kernel extensions should rarely, if ever, have to interact directly with OSMetaClass. Use by Kernel Extensions While kernel extensions rarey interact directly with OSMetaClass at run time, they must register their classes with the metaclass system using the macros declared here. The class declaration should use one of these two macros before its first member function declaration: <ul> <li><code>@link OSDeclareDefaultStructors OSDeclareDefaultStructors@/link</code> - for classes with no abstract member function declarations</li> <li><code>@link OSDeclareAbstractStructors OSDeclareAbstractStructors@/link</code> - for classes with at least one abstract member function declaration</li> <li><code>@link OSDeclareFinalStructors OSDeclareFinalStructors@/link</code> - for classes that should not be subclassable by another kext</li> </ul> The class implementation should then use one of these macros: <ul> <li><code>@link OSDefineMetaClassAndStructors OSDefineMetaClassAndStructors@/link</code> - for classes with no abstract member function declarations</li> <li><code>@link OSDefineMetaClassAndAbstractStructors OSDefineMetaClassAndAbstractStructors@/link</code> - for classes with at least one abstract member function declaration</li> <li><code>@link OSDefineMetaClassAndFinalStructors OSDefineMetaClassAndFinalStructors@/link</code> - for classes that should not be subclassable by another kext</li> </ul> Classes in kernel extensions that are intended for use as libraries may need to reserve vtable slots to preserve binary compatibility as new functions are added. They may do so with these macros: <ul> <li><code>@link OSMetaClassDeclareReservedUnused OSMetaClassDeclareReservedUnused@/link</code> - reserves a vtable slot</li> <li><code>@link OSMetaClassDefineReservedUnused OSMetaClassDefineReservedUnused@/link</code> - defines the reserved vtable slot as an unimplemented function</li> <li><code>@link OSMetaClassDeclareReservedUsed OSMetaClassDeclareReservedUsed@/link</code> - documents that a formerly reserved slot is now used</li> <li><code>@link OSMetaClassDefineReservedUsed OSMetaClassDefineReservedUsed@/link</code> - documents that a formerly reserved slot is now used</li> </ul> Use Restrictions OSMetaClass should not be explicitly subclassed by kernel extensions (the declare/define macros do that), nor should kernel extensions call its run-time type functions directly. OSMetaClass functions should be considered unsafe to call in a primary interrupt context. Concurrency Protection Kernel extensions should in general not interact with OSMetaClass objects directly, instead using the run-time type macros. Much of OSMetaClass's interface is intended for use by the run-time type information system, which handles concurrency and locking internally.

: public OSMetaClassBase

static const OSMetaClass * getMetaClassWithName(const OSSymbol * name)static

@function getMetaClassWithName @abstract Look up a metaclass in the run-time type information system. @param name The name of the desired class's metaclass. @result A pointer to the metaclass object if found, <code>NULL</code> otherwise.

override
virtual void retain() const

virtual protected

@function retain @abstract Implements the abstract <code>retain</code> function to do nothing. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

override
virtual void release() const

virtual protected

@function release @abstract Implements the abstract <code>release</code> function to do nothing. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

override
virtual void release(int freeWhen) const

virtual protected

@function release @abstract Implements the abstract <code>release(int freeWhen)</code> function to do nothing. @param freeWhen Unused. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

override
virtual void taggedRetain(const void * tag = NULL) const

virtual protected

@function taggedRetain @abstract Implements the abstract <code>taggedRetain(const void *)</code> function to do nothing. @param tag Unused. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

override
virtual void taggedRelease(const void * tag = NULL) const

virtual protected

@function taggedRelease @abstract Implements the abstract <code>taggedRelease(const void *)</code> function to do nothing. @param tag Unused. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

override
virtual void taggedRelease(const void * tag, const int freeWhen) const

virtual protected

@function taggedRelease @abstract Implements the abstract <code>taggedRelease(const void *, cont int)</code> function to do nothing. @param tag Unused. @param freeWhen Unused. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

override
virtual int getRetainCount() const

virtual protected

@function getRetainCount @abstract Implements the abstract <code>getRetainCount</code> function to return 0. @result Always returns 0. @discussion Since an OSMetaClass instance must remain in existence for as long as its kernel extension is loaded, OSMetaClass does not use reference-counting.

static void * preModLoad(const char * kextID)static

@function preModLoad @abstract Prepares the run-time type system for the creation of new metaclasses during loading of a kernel extension (module). @param kextID The bundle ID of the kext being loaded. @result An opaque handle to the load context for the kernel extension on success; <code>NULL</code> on failure. @discussion Not for use by kernel extensions. Prepares the run-time type information system to record and register metaclasses created by static constructors until a subsequent call to <code>@link postModLoad postModLoad@/link</code>. <code>preModLoad</code> takes a lock to ensure processing of a single load operation at a time; the lock is released by <code>@link postModLoad postModLoad@/link</code>. Any OSMetaClass constructed between these two function calls will be associated with <code>kextID</code>.

static bool checkModLoad(void * loadHandle)static

@function checkModLoad @abstract Checks whether the current kext load operation can proceed. @param loadHandle The opaque handle returned by <code>@link preModLoad preModLoad@/link</code>. @result <code>true</code> if no errors are outstanding and the system is ready to process more metaclasses. @discussion Not for use by kernel extensions.

static OSReturn postModLoad(void * loadHandle)static

@function postModLoad @abstract Registers the metaclasses created during loading of a kernel extension. @param loadHandle The opaque handle returned by <code>@link preModLoad preModLoad@/link</code>. @result The error code of the first error encountered, or <code>@link //apple_ref/cpp/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> if no error occurred. @discussion Not for use by kernel extensions. Called after all static constructors in a kernel extension have created metaclasses, this function checks for duplicate class names, then registers the new metaclasses under the kext ID that @link preModLoad preModLoad@/link was called with, so that they can be dynamically allocated and have their instance counts tracked. <code>postModLoad</code> releases the lock taken by <code>@link preModLoad preModLoad@/link</code>.

static bool modHasInstance(const char * kextID)static

@function modHasInstance @abstract Returns whether any classes defined by the named kernel extension (or their subclasses) have existing instances. @param kextID The bundle ID of the kernel extension to check. @result <code>true</code> if the kext is found and if any class defined by that kext has a nonzero instance count, <code>false</code> otherwise. @discussion This function is called before a kernel extension's static destructors are invoked, prior to unloading the extension. If any classes stil have instances or subclasses with instances, those classes are logged (using <code>@link reportModInstances reportModInstances@/link</code>) and the kernel extension is not be unloaded.

static void reportModInstances(const char * kextID)static

@function reportModInstances @abstract Logs the instance counts for classes defined by a kernel extension. @param kextID The bundle ID of the kernel extension to report on. @discussion This function prints the names and instance counts of any class defined by <code>kextID</code> that has a nonzero instance count. It's called by <code>@link modHasInstance modHasInstance@/link</code> to help diagnose problems unloading kernel extensions.

static void considerUnloads()static

@function considerUnloads @abstract Schedule automatic unloading of unused kernel extensions. @discussion This function schedules a check for kernel extensions that can be automatically unloaded, canceling any currently scheduled check. At that time, any such kexts with no Libkern C++ instances and no external references are unloaded. The I/O Kit calls this function when matching goes idle. Kernel extensions that define subclasses of @link //apple_ref/doc/class/IOService IOService@/link are eligible for automatic unloading. (On releases of Mac OS X prior to Snow Leopard (10.6), any kernel extension defining any Libkern C++ class was eligible for automatic unloading, but that unload did not call the module stop routine. Non-I/O Kit kernel extensions that define Libkern C++ subclasses should be sure to have OSBundleLibraries declarations that ensure they will not load on releases prior to Snow Leopard.)

static OSObject * allocClassWithName(const OSSymbol * name)static

@function allocClassWithName @abstract Allocates an instance of a named OSObject-derived class. @param name The name of the desired class. @result A pointer to the newly-allocated, uninitialized object on success; <code>NULL</code> on failure. @discussion Kernel extensions should not need to use this function directly, instead using static instance-creation functions defined by classes. This function consults the run-time type information system to find the metaclass for the named class. If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code> function and returns the result.

static OSObject * allocClassWithName(const OSString * name)static

function allocClassWithName @abstract Allocates an instance of a named OSObject-derived class. @param name The name of the desired class. @result A pointer to the newly-allocated, uninitialized object on success; <code>NULL</code> on failure. @discussion Kernel extensions should not need to use this function directly, instead using static instance-creation functions defined by classes. This function consults the run-time type information system to find the metaclass for the named class. If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code> function and returns the result.

static OSObject * allocClassWithName(const char * name)static

static OSMetaClassBase * checkMetaCastWithName(
	const OSSymbol * className,
	const OSMetaClassBase * object
)

static

@function checkMetaCastWithName @abstract Search the metaclass inheritance hierarchy by name for an object instance. @param className The name of the desired class or superclass. @param object The object whose metaclass begins the search. @result <code>object</code> if it's derived from <code>className</code>; <code>NULL</code> otherwise. @discussion This function is the basis of the Libkern run-time type-checking system. Kernel extensions should not use it directly, instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.

static OSMetaClassBase * checkMetaCastWithName(
	const OSString * className,
	const OSMetaClassBase * object
)

static

@function checkMetaCastWithName @abstract Search the metaclass inheritance hierarchy by name for an object instance. @param className The name of the desired class or superclass. @param object The object whose metaclass begins the search. @result <code>object</code> if it's derived from <code>className</code>; <code>NULL</code> otherwise. @discussion Kernel extensions should not use this function directly, instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.

static OSMetaClassBase * checkMetaCastWithName(
	const char * className,
	const OSMetaClassBase * object
)

static

@function checkMetaCastWithName @abstract Search the metaclass inheritance hierarchy by name for an object instance. @param className The name of the desired class or superclass. @param object The object whose metaclass begins the search. @result <code>object</code> if it's derived from <code>className</code>; <code>NULL</code> otherwise. @discussion Kernel extensions should not use this function directly, instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.

void instanceConstructed() const

@function instanceConstructed @abstract Counts the instances of the class managed by this metaclass. @discussion Not for use by kernel extensions. Every non-abstract class that inherits from OSObject has a default constructor that calls it's own metaclass's <code>instanceConstructed</code> function. This constructor is defined by the <code>@link OSDefineMetaClassAndStructors OSDefineMetaClassAndStructors@/link</code> macro that all OSObject subclasses must use. If a class's instance count goes from 0 to 1--that is, upon the creation of the first instance of that class--the superclass's instance count is also incremented. This propagates reference counts up the inheritance chain so that superclasses are counted as "in use" when subclasses have instances.

void instanceDestructed() const

@function instanceDestructed @abstract Counts the instances of the class managed by this metaclass. @discussion Every non-abstract class that inherits from OSObject has a default destructor that calls it's own metaclass's <code>instanceDestructed</code> function. This constructor is defined by the @link OSDefineMetaClassAndStructors OSDefineMetaClassAndStructors@/link macro that all OSObject subclasses must use. If a class's instance count goes from 1 to 0--that is, upon the destruction of the last instance of that class--the superclass's instance count is also decremented. This reduces "in use" counts from superclasses when their subclasses no longer have instances.

OSMetaClassBase * checkMetaCast(const OSMetaClassBase * object) const

@function checkMetaCast @abstract Check whether a given object is an instance of the receiving metaclass's class or one derived from it. @param object The object to check for inheritance. @result <code>object</code> if it is derived from the receiver's class, <code>NULL</code> if not.

unsigned int getInstanceCount() const

@function getInstanceCount @abstract Returns the number of existing instances of the metaclass's class. @result The number of existing instances of the metaclass's class, plus 1 for each subclass with any instance.

const OSMetaClass * getSuperClass() const

@function getSuperClass @abstract Returns the super-metaclass of the receiver. @result Returns a pointer to the super-metaclass of the receiving OSMetaClass, or <code>NULL</code> for OSObject's metaclass.

const OSSymbol * getKmodName() const

@function getKmodName @abstract Returns the bundle identifier of the kernel extension that defines this metaclass. @result The bundle identifier of the kernel extension that defines this metaclass. @discussion "Kmod" is an older term for kernel extension.

const char * getClassName() const

@function getClassName @abstract Returns the name of the C++ class managed by this metaclass. @result Returns the name of the C++ class managed by this metaclass.

const OSSymbol * getClassNameSymbol() const

unsigned int getClassSize() const

@function getClassSize @abstract Returns the allocation size of the C++ class managed by this metaclass. @result The allocation size of the C++ class managed by this metaclass.

virtual OSObject * alloc() const = 0pure virtual

@function alloc @abstract Allocates an instance of the C++ class managed by this metaclass. @result A pointer to the newly allocated, uninitialized instance, with a retain count of 1; <code>NULL</code> on allocation failure. @discussion This function is automatically created by the metaclass-registration macros to enable dynamic instance allocation.

void reservedCalled(int ind) const

Dynamic vtable patchup support routines and types

static void printInstanceCounts()static

I/O Kit debug internal routines.

static void serializeClassDictionary(OSDictionary * dict)static

macro_OS_ADD_METAMETHODS

#define _OS_ADD_METAMETHODS(b) _OS_ADD_METAMETHODS_ ## b

macro_OS_ADD_METAMETHODS_

#define _OS_ADD_METAMETHODS_

macro_OS_ADD_METAMETHODS_dispatch

#define _OS_ADD_METAMETHODS_dispatch virtual kern_return_t Dispatch(const IORPC rpc) APPLE_KEXT_OVERRIDE;

macro_OS_ADD_METHODS

#define _OS_ADD_METHODS(className, b) _OS_ADD_METHODS_ ## b(className)

macro_OS_ADD_METHODS_

#define _OS_ADD_METHODS_(className)

macro_OS_ADD_METHODS_dispatch

#define _OS_ADD_METHODS_dispatch(className) className ## _Methods
    className ## _KernelMethods

macroSUPERDISPATCH

#define SUPERDISPATCH ((OSDispatchMethod)&super::_Dispatch)

macroOSDeclareCommonStructors

#define OSDeclareCommonStructors(className, dispatch) private:
    static const OSMetaClass * const superClass;
    public:
    static const OSMetaClass * const metaClass;
	static class MetaClass : public OSMetaClass {
	public:
	    MetaClass();
	    virtual OSObject *alloc() const APPLE_KEXT_OVERRIDE;
	    _OS_ADD_METAMETHODS(dispatch);
	} gMetaClass;
	friend class className ::MetaClass;
	virtual const OSMetaClass * getMetaClass() const APPLE_KEXT_OVERRIDE;
    protected:
    className (const OSMetaClass *);
    virtual ~ className () APPLE_KEXT_OVERRIDE;
    _OS_ADD_METHODS(className, dispatch)

macro_OS_ADD_OPERATOR_PROTO

#define _OS_ADD_OPERATOR_PROTO public:
    static void *operator new(size_t size);
    protected:
    static void operator delete(void *mem, size_t size);

macro_OSDeclareDefaultStructors

@define OSDeclareDefaultStructors @hidecontents @abstract Declares run-time type information and functions for a final (non-subclassable) Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @discussion Concrete Libkern C++ classes should "call" this macro immediately after the opening brace in a class declaration. It leaves the current privacy state as <code>protected:</code>.

#define _OSDeclareDefaultStructors(className, dispatch) OSDeclareCommonStructors(className, dispatch);
	public:
	className (void);
	_OS_ADD_OPERATOR_PROTO
    protected:

macroOSDeclareDefaultStructors

#define OSDeclareDefaultStructors(className) _OSDeclareDefaultStructors(className, )

macroOSDeclareDefaultStructorsWithDispatch

#define OSDeclareDefaultStructorsWithDispatch(className) _OSDeclareDefaultStructors(className, dispatch)

macro_OSDeclareAbstractStructors

@define OSDeclareAbstractStructors @hidecontents @abstract Declares run-time type information and functions for an abstract Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @discussion Abstract Libkern C++ classes--those with at least one pure virtual method--should "call" this macro immediately after the opening brace in a class declaration. It leaves the current privacy state as <code>protected:</code>.

#define _OSDeclareAbstractStructors(className, dispatch) OSDeclareCommonStructors(className, dispatch)
    private:
	/* Make primary constructor private in abstract */
	className (void);
    protected:

macroOSDeclareAbstractStructors

#define OSDeclareAbstractStructors(className) _OSDeclareAbstractStructors(className, )
	_OS_ADD_OPERATOR_PROTO

macroOSDeclareAbstractStructorsWithDispatch

#define OSDeclareAbstractStructorsWithDispatch(className) _OSDeclareAbstractStructors(className, dispatch)
	_OS_ADD_OPERATOR_PROTO

macroOSDeclareAbstractStructorsWithDispatchAndNoOperators

#define OSDeclareAbstractStructorsWithDispatchAndNoOperators(className) _OSDeclareAbstractStructors(className, dispatch)

macro_OSDeclareFinalStructors

@define OSDeclareFinalStructors @hidecontents @abstract Declares run-time type information and functions for a concrete Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @discussion Final Libkern C++ classes--those that do not allow subclassing--should "call" this macro immediately after the opening brace in a class declaration. (Final classes in the kernel may actually have subclasses in the kernel, but kexts cannot define any subclasses of a final class.) It leaves the current privacy state as <code>protected:</code>. Note: If the class is exported by a pseudokext (symbol set), the final symbol generated by this macro must be exported for the final-class attribute to be enforced. Warning: Changing a class from "Default" to "Final" will break binary compatibility.

#define _OSDeclareFinalStructors(className, dispatch) _OSDeclareDefaultStructors(className, dispatch)
    private:
	void __OSFinalClass(void);
    protected:

macroOSDeclareFinalStructors

#define OSDeclareFinalStructors(className) _OSDeclareFinalStructors(className, )

macroOSDeclareFinalStructorsWithDispatch

#define OSDeclareFinalStructorsWithDispatch(className) _OSDeclareFinalStructors(className, dispatch)

macroOSMetaClassConstructorInit

Not to be included in headerdoc. @define OSDefineMetaClassWithInit @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @param init A function to call in the constructor of the class's OSMetaClass. @discussion Note: Needs to be followed by <code>OSMetaClassConstructorInit</code> or <code>OSMetaClassConstructorInitWithZone</code> for initialization of class's <code>OSMetaClass</code> constructor.

#define OSMetaClassConstructorInit(className, superclassName, init) /* The ::MetaClass constructor */
	className ::MetaClass::MetaClass()
	: OSMetaClass(#className, className::superClass,
	                sizeof(className))
	{ init; }

macroOSDefineMetaClassWithInit

#define OSDefineMetaClassWithInit(className, superclassName, init) /* Class global data */
	className ::MetaClass className ::gMetaClass;
	const OSMetaClass * const className ::metaClass =
	& className ::gMetaClass;
	const OSMetaClass * const className ::superClass =
	& superclassName ::gMetaClass;
	/* Class member functions */
	className :: className(const OSMetaClass *meta)
	: superclassName (meta) { }
	className ::~ className() { }
	const OSMetaClass * className ::getMetaClass() const
	{ return &gMetaClass; }

macroOSDefineAbstractStructors

Not to be included in headerdoc. @define OSDefineAbstractStructors @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro.

#define OSDefineAbstractStructors(className, superclassName) OSObject * className ::MetaClass::alloc() const { return NULL; }

macroOSDefineBasicStructors

Not to be included in headerdoc. @define OSDefineDefaultStructors @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro.

#define OSDefineBasicStructors(className, superclassName) OSObject * className ::MetaClass::alloc() const
	{ return new className; }
	className :: className () : superclassName (&gMetaClass)
	{ gMetaClass.instanceConstructed(); }

macroOSDefineOperatorMethods

#define OSDefineOperatorMethods(className) void * className::operator new(size_t size) {
	  return OSObject::operator new(size);
	}
	void className::operator delete(void *mem, size_t size) {
	  return OSObject::operator delete(mem, size);
	}

macroOSDefineDefaultStructors

#define OSDefineDefaultStructors(className, superclassName) OSDefineBasicStructors(className, superclassName)
	OSDefineOperatorMethods(className)

macroOSDefineFinalStructors

#define OSDefineFinalStructors(className, superclassName) OSDefineBasicStructors(className, superclassName)
    void className ::__OSFinalClass(void) { }

macroOSDefineMetaClassAndStructorsWithInit

Not to be included in headerdoc. @define OSDefineMetaClassAndStructorsWithInit @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @param init A function to call in the constructor of the class's OSMetaClass.

#define OSDefineMetaClassAndStructorsWithInit(className, superclassName, init) OSDefineMetaClassWithInit(className, superclassName, init)
	OSMetaClassConstructorInit(className, superclassName, init)
	OSDefineDefaultStructors(className, superclassName)

macroOSDefineMetaClassAndAbstractStructorsWithInit

Not to be included in headerdoc. @define OSDefineMetaClassAndAbstractStructorsWithInit @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @param init A function to call in the constructor of the class's OSMetaClass.

#define OSDefineMetaClassAndAbstractStructorsWithInit(className, superclassName, init) OSDefineMetaClassWithInit(className, superclassName, init)
	OSMetaClassConstructorInit(className, superclassName, init)
	OSDefineAbstractStructors(className, superclassName)
	OSDefineOperatorMethods(className)

macroOSDefineMetaClassAndFinalStructorsWithInit

Not to be included in headerdoc. @define OSDefineMetaClassAndFinalStructorsWithInit @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @param init A function to call in the constructor of the class's OSMetaClass.

#define OSDefineMetaClassAndFinalStructorsWithInit(className, superclassName, init) OSDefineMetaClassWithInit(className, superclassName, init)
	OSMetaClassConstructorInit(className, superclassName, init)
	OSDefineFinalStructors(className, superclassName)
	OSDefineOperatorMethods(className)

macroOSDefineMetaClass

Not to be included in headerdoc. @define OSDefineMetaClass @hidecontents @abstract Helper macro for for the standard metaclass-registration macros. DO NOT USE. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @param init A function to call in the constructor of the class's OSMetaClass.

#define OSDefineMetaClass(className, superclassName) OSDefineMetaClassWithInit(className, superclassName, )
	OSMetaClassConstructorInit(className, superclassName, )
	OSDefineOperatorMethods(className)

macroOSDefineMetaClassAndStructors

@define OSDefineMetaClassAndStructors @hidecontents @abstract Defines an OSMetaClass and associated routines for a concrete Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @discussion Concrete Libkern C++ classes should "call" this macro at the beginning of their implementation files, before any function implementations for the class.

#define OSDefineMetaClassAndStructors(className, superclassName) OSDefineMetaClassAndStructorsWithInit(className,
	                superclassName, )

macroOSDefineMetaClassAndAbstractStructors

@define OSDefineMetaClassAndAbstractStructors @hidecontents @abstract Defines an OSMetaClass and associated routines for an abstract Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @discussion Abstract Libkern C++ classes--those with at least one pure virtual method--should "call" this macro at the beginning of their implementation files, before any function implementations for the class.

#define OSDefineMetaClassAndAbstractStructors(className, superclassName) OSDefineMetaClassAndAbstractStructorsWithInit (className,
	                superclassName, )

macroOSDefineMetaClassAndFinalStructors

@define OSDefineMetaClassAndFinalStructors @hidecontents @abstract Defines an OSMetaClass and associated routines for concrete Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param superclassName The name of the superclass of the C++ class, as a raw token, not a string or macro. @discussion Final Libkern C++ classes--those that do not allow subclassing--should "call" this macro at the beginning of their implementation files, before any function implementations for the class. (Final classes in the kernel may actually have subclasses in the kernel, but kexts cannot define any subclasses of a final class.) Note: If the class is exported by a pseudokext (symbol set), the final symbol generated by this macro must be exported for the final-class attribute to be enforced. Warning: Changing a class from "Default" to "Final" will break binary compatibility.

#define OSDefineMetaClassAndFinalStructors(className, superclassName) OSDefineMetaClassAndFinalStructorsWithInit(className,
	                superclassName, )

macroOSMetaClassDeclareReservedUnused

@define OSMetaClassDeclareReservedUnused @hidecontents @abstract Reserves vtable space for new virtual functions in a Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param index The numeric index of the vtable slot, as a raw constant, beginning from 0. @discussion Libkern C++ classes in kernel extensions that can be used as libraries can provide for backward compatibility by declaring a number of reserved vtable slots that can be replaced with new functions as they are added. Each reserved declaration must be accompanied in the implementation by a corresponding reference to <code>@link OSMetaClassDefineReservedUnused OSMetaClassDefineReservedUnused@/link</code>. When replacing a reserved slot, change the macro from "Unused" to "Used" to document the fact that the slot used to be reserved, and declare the new function immediately after the "Used" macro to preserve vtable ordering. See <code>@link OSMetaClassDeclareReservedUsed OSMetaClassDeclareReservedUsed@/link</code>.

#define OSMetaClassDeclareReservedUnused(className, index) virtual void _RESERVED ## className ## index ()

macroOSMetaClassDeclareReservedUsed

@define OSMetaClassDeclareReservedUsed @hidecontents @abstract Documents use of reserved vtable space for new virtual functions in a Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param index The numeric index of the vtable slot, as a raw constant, beginning from 0. @discussion This macro evaluates to nothing, and is used to document reserved vtable slots as they are filled. See <code>@link OSMetaClassDeclareReservedUnused OSMetaClassDeclareReservedUnused@/link</code>.

#define OSMetaClassDeclareReservedUsed(className, index)

macroOSMetaClassDeclareReservedUsedARM

#define OSMetaClassDeclareReservedUsedARM(className, x86index, armindex)

macroOSMetaClassDefineReservedUnused

@define OSMetaClassDefineReservedUnused @hidecontents @abstract Defines a reserved vtable slot for a Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param index The numeric index of the vtable slot, as a raw constant, beginning from 0. @discussion Libkern C++ classes in kernel extensions that can be used as libraries can provide for backward compatibility by declaring a number of reserved vtable slots that can be replaced with new functions as they are added. Each reserved defintion accompanies a corresponding declaration created with <code>@link OSMetaClassDeclareReservedUnused OSMetaClassDeclareReservedUnused@/link</code>. This macro is used in the implementation file to provide a placeholder definition for the reserved vtable slot, as a function that calls <code>panic</code> with an error message. When replacing a reserved slot, change the macro from "Unused" to "Used" to document the fact that the slot used to be reserved, and declare the new function immediately after the "Used" macro to preserve vtable ordering. See <code>@link OSMetaClassDefineReservedUsed OSMetaClassDefineReservedUsed@/link</code>.

#define OSMetaClassDefineReservedUnused(className, index) void className ::_RESERVED ## className ## index ()
	{ gMetaClass.reservedCalled(index); }

macroOSMetaClassDefineReservedUsed

@define OSMetaClassDefineReservedUsed @hidecontents @abstract Reserves vtable space for new virtual functions in a Libkern C++ class. @param className The name of the C++ class, as a raw token, not a string or macro. @param index The numeric index of the vtable slot, as a raw constant, beginning from 0. @discussion This macro evaluates to nothing, and is used to document reserved vtable slots as they are filled. See <code>@link OSMetaClassDefineReservedUnused OSMetaClassDefineReservedUnused@/link</code>.

#define OSMetaClassDefineReservedUsed(className, index)

macroOSMetaClassDefineReservedUsedARM

#define OSMetaClassDefineReservedUsedARM(className, x86index, armindex)

macroOSMetaClassDeclareReservedUsedX86

OSMetaClassDeclareReservedUsedX86 needs to be placed with the unused vtable slots since it will unused on arm targets.

#define OSMetaClassDeclareReservedUsedX86 OSMetaClassDeclareReservedUnused

macroOSMetaClassDefineReservedUsedX86

#define OSMetaClassDefineReservedUsedX86 OSMetaClassDefineReservedUnused