Mac Developer Library

Developer

OSKextLib.h Reference

Options
Deployment Target:

On This Page

OSKextLib.h Reference

Declares functions, basic return values, and other constants related to kernel extensions (kexts).

Included Headers

  • <sys/cdefs.h>

  • <stdint.h>

  • <mach/kmod.h>

  • <mach/vm_types.h>

  • <libkern/OSTypes.h>

  • <libkern/OSReturn.h>

Functions

Support for weak references to symbols in kexts.

  • Checks whether a weakly-referenced symbol has been resolved.

    Declaration

    Objective-C

    #define OSKextSymbolIsResolved(weak_sym) \ (&(weak_sym) != gOSKextUnresolved)

    Parameters

    weak_sym

    The weak symbol to be tested for resolution.

    Return Value

    TRUE if weak_sym is resolved, or FALSE if weak_sym is unresolved.

    Discussion

    This is a convenience macro for testing if weak symbols are resolved.

    Example for a weak symbol named foo:

    • if (OSKextSymbolIsResolved(foo)) {
    • foo();
    • } else {
    • printf("foo() is not resolved\n");
    • }

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

Functions for making requests to kextd in user space.

  • Cancels a pending user-space kext request without invoking the callback.

    Declaration

    Objective-C

    OSReturn OSKextCancelRequest ( OSKextRequestTag requestTag, void **contextOut );

    Parameters

    requestTag

    A tag identifying a pending request.

    contextOut

    If non-NULL, filled with the context pointer originally passed with the request.

    Return Value

    kOSReturnSuccess if the request is successfully canceled. kOSKextReturnNotFound if requestTag does not identify any pending request. Other OSKextReturn... errors are possible.

    Discussion

    This function cancels a pending request if it exists, so that its callback will not be invoked. It returns in contextOut the context pointer used to create the request so that any resources allocated for the request can be cleaned up.

    Kexts do not need to cancel outstanding requests in their module stop functions; when a kext is unloaded, all pending request callbacks are invoked with a result of kOSKextReturnTimeout before the stop function is called.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Requests data from a nonlocalized resource file in a kext bundle on disk.

    Declaration

    Objective-C

    OSReturn OSKextRequestResource ( const char *kextIdentifier, const char *resourceName, OSKextRequestResourceCallback callback, void *context, OSKextRequestTag *requestTagOut );

    Parameters

    kextIdentifier

    The CFBundleIdentifier of the kext from which to read the file.

    resourceName

    The name of the resource file to read.

    callback

    A pointer to a callback function; the address must be within a currently-loaded kext.

    context

    A pointer to arbitrary run-time data that will be passed to the callback when it is invoked. May be NULL.

    requestTagOut

    If non-NULL, filled on success with a tag identifying the pending request (or on failure with kOSKextRequestTagInvalid; can be used with OSKextCancelRequest.

    Return Value

    kOSReturnSuccess if the request is successfully queued. kOSKextReturnInvalidArgument if kextIdentifier or resourceName or if callback is not an address within a loaded kext executable. kOSKextReturnStopping if an unload attempt is being made on the kext containing callback. Other OSKextReturn... errors are possible.

    Discussion

    This function queues an asynchronous request to the user-space kext daemon kextd(8); requests for resources early in system startup will not be fulfilled until that daemon starts. Requests made by a kext while that kext is loading (specifically in the kext's module start routine) will not be fulfilled until after the start routine returns and the kext is completely loaded. Kexts requesting resources should be sure to perform appropriate locking in the callback function.

    Kext resources are stored in the kext's on-disk bundle under the Resources subdirectory. See Bundle Programming Guide for an overview of bundle structure. The localization context of the kext daemon (namely that of the superuser) will be used in retrieving resources; kext resources intended for use in the kernel should generally not be localized.

    callback is guaranteed to be invoked except when:

    • OSKextCancelRequest is used to cancel the request. In this case the kext gets the context pointer and can clean it up.

    • The request is made during a kext's module start routine and the start routine returns an error. In this case, callbacks cannot be safely invoked, so the kext should clean up all request contexts when returning the error from the start routine.

    Kexts with pending requests are not subject to autounload, but requests are subject to timeout after a few minutes. If that amount of time passes with no response from user space, callback is invoked with a result of. kOSKextReturnTimeout.

    Kexts that are explicitly unloaded have all pending request callbacks invoked with a result of kOSKextReturnStopping. The kext must handle these callbacks, even if its stop routine will prevent unloading. If the kext does prevent unloading, it can reissue resource requests outside of the stop function.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

Functions for loading and tracking kexts in the kernel.

  • Request that a kext be loaded.

    Declaration

    Objective-C

    OSReturn OSKextLoadKextWithIdentifier ( const char *kextIdentifier );

    Parameters

    kextIdentifier

    The bundle identifier of the kext to be loaded.

    Return Value

    kOSReturnSuccess if the kext was loaded (or was already loaded). kOSKextReturnDeferred if the kext was not found and a request was queued to kextd(8). Other return values indicate a failure to load the kext.

    Discussion

    If a kext is already in the kernel but not loaded, it is loaded immediately. If it isn't found, an asynchronous load request is made to kextd(8) and kOSKextReturnDeferred is returned. There is no general notification or callback mechanism for load requests.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Release a loaded kext based on its load tag.

    Declaration

    Objective-C

    OSReturn OSKextReleaseKextWithLoadTag ( OSKextLoadTag loadTag );

    Parameters

    loadTag

    The load tag of the kext to be released. See OSKextGetCurrentLoadTag.

    Return Value

    kOSReturnSuccess if the kext was released. kOSKextReturnNotFound if the kext was not found. kOSKextReturnInvalidArgument if loadTag is kOSKextInvalidLoadTag.

    Discussion

    The kext should have been retained previously via OSKextRetainKextWithLoadTag.

    This function schedules an autounload scan for all kexts. When that scan occurs, if a kext has autounload enabled, it will be unloaded if there are no outstanding references to it and there are no instances of its Libkern C++ classes (if any).

    Kexts that define subclasses of IOService have autounload enabled automatically. Other kexts can use the reference count to manage automatic unload without having to define and create Libkern C++ objects. For example, a filesystem kext can be retained whenever a new mount is created, and released when a mount is removed. When the last mount is removed, the kext will be unloaded after a brief delay.

    While the autounload scan takes place after a delay of at least a minute, a kext that manages its own reference counts for autounload should be prepared to have its module stop function called even while the function calling this function is still running.

    A kext can get its own load tag using the OSKextGetCurrentLoadTag.

    Kexts should not retain and release other kexts; linkage references are accounted for internally.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Retain a loaded kext based on its load tag, and enable autounload for that kext.

    Declaration

    Objective-C

    OSReturn OSKextRetainKextWithLoadTag ( OSKextLoadTag loadTag );

    Parameters

    loadTag

    The load tag of the kext to be retained. See OSKextGetCurrentLoadTag.

    Return Value

    kOSReturnSuccess if the kext was retained. kOSKextReturnNotFound if the kext was not found. kOSKextReturnInvalidArgument if loadTag is kOSKextInvalidLoadTag.

    Discussion

    Retaining a kext prevents it from being unloaded, either explicitly or automatically, and enables autounload for the kext. When autounload is enabled, then shortly after the kext's last reference is dropped, it will be unloaded if there are no outstanding references to it and there are no instances of its Libkern C++ subclasses (if any).

    Kexts that define subclasses of IOService have autounload enabled automatically. Other kexts can use the reference count to manage automatic unload without having to define and create Libkern C++ objects. For example, a filesystem kext can retain itself whenever a new mount is created, and release itself when a mount is removed. When the last mount is removed, the kext will be unloaded after a brief delay.

    A kext can get its own load tag using the OSKextGetCurrentLoadTag.

    Kexts should not retain and release other kexts; linkage references are accounted for internally.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

Types, constants, and macros providing a kext with information about itself.

  • Returns the CFBundleIdentifier for the calling kext as a C string.

    Declaration

    Objective-C

    const char * OSKextGetCurrentIdentifier ( void );

    Return Value

    The CFBundleIdentifier for the calling kext as a C string.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Returns the run-time load tag for the calling kext as an OSKextLoadTag.

    Declaration

    Objective-C

    OSKextLoadTag OSKextGetCurrentLoadTag ( void );

    Return Value

    The run-time load tag for the calling kext as an OSKextLoadTag.

    Discussion

    The load tag identifies this loaded instance of the kext to the kernel and to kernel functions that operate on kexts.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Returns the CFBundleVersion for the calling kext as a C string.

    Declaration

    Objective-C

    const char * OSKextGetCurrentVersionString ( void );

    Return Value

    The CFBundleVersion for the calling kext as a C string.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

Callbacks

Functions for making requests to kextd in user space.

  • Invoked to provide results for a kext resource request.

    Declaration

    Objective-C

    typedef void ( *OSKextRequestResourceCallback)( OSKextRequestTag requestTag, OSReturn result, const void *resourceData, uint32_t resourceDataLength, void *context);

    Parameters

    requestTag

    The tag of the request that the callback pertains to.

    result

    The result of the request: kOSReturnSuccess if the request was fulfilled; kOSKextReturnTimeout if the request has timed out; kOSKextReturnStopping if the kext containing the callback address for the kext is being unloaded; or other values on error.

    resourceData

    A pointer to the requested resource data. Owned by the system; the kext should make a copy if it needs to keep the data past the callback.

    resourceDataLength

    The length of resourceData.

    context

    The context pointer originally passed to OSKextRequestResource.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

Data Types

See the Overview section above for header-level documentation.

  • A unique identifier assigned to a loaded instanace of a kext.

    Declaration

    Objective-C

    typedef uint32_t OSKextLoadTag;

    Discussion

    If a kext is unloaded and later reloaded, the new instance has a different load tag.

    A kext can get its own load tag in the kmod_info_t structure passed into its module start routine, as the id field (cast to this type). You can use the load tag with the functions OSKextRetainKextWithLoadTag and OSKextReleaseKextWithLoadTag.

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

  • Identifies a kext request made to user space.

    Declaration

    Objective-C

    typedef uint32_t OSKextRequestTag;

    Import Statement

    Objective-C

    #include <OSKextLib.h>;

    Availability

    Available in OS X v10.6 and later.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    #define kIOKitPersonalitiesKey "IOKitPersonalities" #define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad" #define kOSBundleCompatibleVersionKey "OSBundleCompatibleVersion" #define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging" #define kOSBundleIsInterfaceKey "OSBundleIsInterface" #define kOSBundleLibrariesKey "OSBundleLibraries" #define kOSBundleRequiredConsole "Console" #define kOSBundleRequiredKey "OSBundleRequired" #define kOSBundleRequiredLocalRoot "Local-Root" #define kOSBundleRequiredNetworkRoot "Network-Root" #define kOSBundleRequiredRoot "Root" #define kOSBundleRequiredSafeBoot "Safe Boot" #define kOSBundleSharedExecutableIdentifierKey "OSBundleSharedExecutableIdentifier" #define kOSKernelResourceKey "OSKernelResource" #define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1)) #define kOSKextKernelIdentifier "__kernel__" #define kOSKextRequestTagInvalid ((OSKextRequestTag)-1) #define kOSKextReturnArchNotFound libkern_kext_err(0xf) #define kOSKextReturnAuthentication libkern_kext_err(0xd) #define kOSKextReturnBadData libkern_kext_err(0x7) #define kOSKextReturnBootLevel libkern_kext_err(0x12) #define kOSKextReturnCache libkern_kext_err(0x10) #define kOSKextReturnDeferred libkern_kext_err(0x11) #define kOSKextReturnDependencies libkern_kext_err(0xe) #define kOSKextReturnDependencyLoadError libkern_kext_err(0x15) #define kOSKextReturnDisabled libkern_kext_err(0xa) #define kOSKextReturnInternalError libkern_kext_err(0x1) #define kOSKextReturnInUse libkern_kext_err(0x18) #define kOSKextReturnInvalidArgument libkern_kext_err(0x5) #define kOSKextReturnLinkError libkern_kext_err(0x16) #define kOSKextReturnLoadedVersionDiffers libkern_kext_err(0x14) #define kOSKextReturnNoMemory libkern_kext_err(0x2) #define kOSKextReturnNoResources libkern_kext_err(0x3) #define kOSKextReturnNotAKext libkern_kext_err(0xb) #define kOSKextReturnNotFound libkern_kext_err(0x6) #define kOSKextReturnNotLoadable libkern_kext_err(0x13) #define kOSKextReturnNotPrivileged libkern_kext_err(0x4) #define kOSKextReturnSerialization libkern_kext_err(0x8) #define kOSKextReturnStartStopError libkern_kext_err(0x17) #define kOSKextReturnStopping libkern_kext_err(0x1a) #define kOSKextReturnTimeout libkern_kext_err(0x19) #define kOSKextReturnUnsupported libkern_kext_err(0x9) #define kOSKextReturnValidation libkern_kext_err(0xc)

    Constants

    • kIOKitPersonalitiesKey

      kIOKitPersonalitiesKey

      A dictionary of dictionaries used in matching for I/O Kit drivers.

      Available in OS X v10.6 and later.

    • kOSBundleAllowUserLoadKey

      kOSBundleAllowUserLoadKey

      A boolean value indicating whether kextcache(8) will honor a non-root process's request to load a kext.

      See KextManagerLoadKextWithURL and KextManagerLoadKextWithIdentifier.

      Available in OS X v10.6 and later.

    • kOSBundleCompatibleVersionKey

      kOSBundleCompatibleVersionKey

      A string giving the backwards-compatible version of a library kext in extended Mac OS 'vers' format (####.##.##s{1-255} where 's' is a build stage 'd', 'a', 'b', 'f' or 'fc').

      Available in OS X v10.6 and later.

    • kOSBundleEnableKextLoggingKey

      kOSBundleEnableKextLoggingKey

      Set to true to have the kernel kext logging spec applied to the kext. See OSKextLogSpec.

      Available in OS X v10.6 and later.

    • kOSBundleIsInterfaceKey

      kOSBundleIsInterfaceKey

      A boolean value indicating whether the kext executable contains only symbol references.

      Available in OS X v10.6 and later.

    • kOSBundleLibrariesKey

      kOSBundleLibrariesKey

      A dictionary listing link dependencies for this kext. Keys are bundle identifiers, values are version strings.

      Available in OS X v10.6 and later.

    • kOSBundleRequiredConsole

      kOSBundleRequiredConsole

      This OSBundleRequired value indicates that the kext may be needed for console access (specifically in a single-user startup when kextd(8). does not run) and should be loaded during early startup.

      Available in OS X v10.6 and later.

    • kOSBundleRequiredKey

      kOSBundleRequiredKey

      A string indicating in which kinds of startup this kext may need to load during early startup (before kextcache(8)).

      The value is one of:

      Use this property judiciously. Every kext that declares a value other than "OSBundleRequiredSafeBoot" increases startup time, as the booter must read it into memory, or startup kext caches must include it.

      Available in OS X v10.6 and later.

    • kOSBundleRequiredLocalRoot

      kOSBundleRequiredLocalRoot

      This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem when starting from a local disk.

      Available in OS X v10.6 and later.

    • kOSBundleRequiredNetworkRoot

      kOSBundleRequiredNetworkRoot

      This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem when starting over a network connection.

      Available in OS X v10.6 and later.

    • kOSBundleRequiredRoot

      kOSBundleRequiredRoot

      This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem whether starting from a local or a network volume.

      Available in OS X v10.6 and later.

    • kOSBundleRequiredSafeBoot

      kOSBundleRequiredSafeBoot

      This OSBundleRequired value indicates that the kext can be loaded during a safe startup. This value does not normally cause the kext to be read by the booter or included in startup kext caches.

      Available in OS X v10.6 and later.

    • kOSBundleSharedExecutableIdentifierKey

      kOSBundleSharedExecutableIdentifierKey

      Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard). Value is the bundle identifier of the pseudokext that contains an executable shared by this kext.

      Available in OS X v10.6 and later.

    • kOSKernelResourceKey

      kOSKernelResourceKey

      A boolean value indicating whether the kext represents a built-in component of the kernel.

      Available in OS X v10.6 and later.

    • kOSKextInvalidLoadTag

      kOSKextInvalidLoadTag

      A load tag value that will never be used for a loaded kext; indicates kext not found.

      Available in OS X v10.6 and later.

    • kOSKextKernelIdentifier

      kOSKextKernelIdentifier

      This is the CFBundleIdentifier user for the kernel itself.

      Available in OS X v10.6 and later.

    • kOSKextRequestTagInvalid

      kOSKextRequestTagInvalid

      A request tag value that will never be used for a kext request; indicates failure to create/queue the request.

      Available in OS X v10.6 and later.

    • kOSKextReturnArchNotFound

      kOSKextReturnArchNotFound

      Kext does not contain code for the requested architecture.

      Available in OS X v10.6 and later.

    • kOSKextReturnAuthentication

      kOSKextReturnAuthentication

      Authetication failures encountered; check diagnostics for details.

      Available in OS X v10.6 and later.

    • kOSKextReturnBadData

      kOSKextReturnBadData

      Malformed data (not used for XML).

      Available in OS X v10.6 and later.

    • kOSKextReturnBootLevel

      kOSKextReturnBootLevel

      Kext not loadable or operation not allowed at current boot level.

      Available in OS X v10.6 and later.

    • kOSKextReturnCache

      kOSKextReturnCache

      An error occurred processing a system kext cache.

      Available in OS X v10.6 and later.

    • kOSKextReturnDeferred

      kOSKextReturnDeferred

      Operation has been posted asynchronously to user space (kernel only).

      Available in OS X v10.6 and later.

    • kOSKextReturnDependencies

      kOSKextReturnDependencies

      Dependency resolution failures encountered; check diagnostics for details.

      Available in OS X v10.6 and later.

    • kOSKextReturnDependencyLoadError

      kOSKextReturnDependencyLoadError

      A load error occurred on a dependency of the kext being loaded.

      Available in OS X v10.6 and later.

    • kOSKextReturnDisabled

      kOSKextReturnDisabled

      Operation is currently disabled.

      Available in OS X v10.6 and later.

    • kOSKextReturnInternalError

      kOSKextReturnInternalError

      An internal error in the kext library. Contrast with OSReturnError.

      Available in OS X v10.6 and later.

    • kOSKextReturnInUse

      kOSKextReturnInUse

      The kext is currently in use or has outstanding references, and cannot be unloaded.

      Available in OS X v10.6 and later.

    • kOSKextReturnInvalidArgument

      kOSKextReturnInvalidArgument

      Invalid argument.

      Available in OS X v10.6 and later.

    • kOSKextReturnLinkError

      kOSKextReturnLinkError

      A link failure occured with this kext or a dependency.

      Available in OS X v10.6 and later.

    • kOSKextReturnLoadedVersionDiffers

      kOSKextReturnLoadedVersionDiffers

      A different version (or executable UUID, or executable by checksum) of the requested kext is already loaded.

      Available in OS X v10.6 and later.

    • kOSKextReturnNoMemory

      kOSKextReturnNoMemory

      Memory allocation failed.

      Available in OS X v10.6 and later.

    • kOSKextReturnNoResources

      kOSKextReturnNoResources

      Some resource other than memory (such as available load tags) is exhausted.

      Available in OS X v10.6 and later.

    • kOSKextReturnNotAKext

      kOSKextReturnNotAKext

      Bundle is not a kernel extension.

      Available in OS X v10.6 and later.

    • kOSKextReturnNotFound

      kOSKextReturnNotFound

      Search item not found.

      Available in OS X v10.6 and later.

    • kOSKextReturnNotLoadable

      kOSKextReturnNotLoadable

      Kext cannot be loaded; check diagnostics for details.

      Available in OS X v10.6 and later.

    • kOSKextReturnNotPrivileged

      kOSKextReturnNotPrivileged

      The caller lacks privileges to perform the requested operation.

      Available in OS X v10.6 and later.

    • kOSKextReturnSerialization

      kOSKextReturnSerialization

      Error converting or (un)serializing URL, string, or XML.

      Available in OS X v10.6 and later.

    • kOSKextReturnStartStopError

      kOSKextReturnStartStopError

      The kext start or stop routine returned an error.

      Available in OS X v10.6 and later.

    • kOSKextReturnStopping

      kOSKextReturnStopping

      The kext is in the process of stopping; requests cannot be made.

      Available in OS X v10.6 and later.

    • kOSKextReturnTimeout

      kOSKextReturnTimeout

      A kext request has timed out.

      Available in OS X v10.6 and later.

    • kOSKextReturnUnsupported

      kOSKextReturnUnsupported

      Operation is no longer or not yet supported.

      Available in OS X v10.6 and later.

    • kOSKextReturnValidation

      kOSKextReturnValidation

      Validation failures encountered; check diagnostics for details.

      Available in OS X v10.6 and later.

  • Declaration

    Objective-C

    extern const void * gOSKextUnresolved;

    Constants

    • gOSKextUnresolved

      gOSKextUnresolved

      The value to which a kext's unresolved, weakly-referenced symbols are bound.

      A kext must test a weak symbol before using it. A weak symbol is only safe to use if it is not equal to gOSKextUnresolved.

      Example for a weak symbol named foo:

      • if (&foo != gOSKextUnresolved) {
      • foo();
      • } else {
      • printf("foo() is not supported\n");
      • }

      Available in OS X v10.6 and later.