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

    #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:

    1. if (OSKextSymbolIsResolved(foo)) {
    2. foo();
    3. } else {
    4. printf("foo() is not resolved\n");
    5. }

Functions for making requests to kextd in user space.

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

    Declaration

    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.

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

    Declaration

    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.

Functions for loading and tracking kexts in the kernel.

  • Request that a kext be loaded.

    Declaration

    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.

  • Release a loaded kext based on its load tag.

    Declaration

    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.

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

    Declaration

    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.

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

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

    Declaration

    const char * OSKextGetCurrentIdentifier( void);

    Return Value

    The CFBundleIdentifier for the calling kext as a C string.

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

    Declaration

    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.

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

    Declaration

    const char * OSKextGetCurrentVersionString( void);

    Return Value

    The CFBundleVersion for the calling kext as a C string.

Callbacks

Functions for making requests to kextd in user space.

  • Invoked to provide results for a kext resource request.

    Declaration

    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.

Data Types

See the Overview section above for header-level documentation.

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

    Declaration

    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

  • Identifies a kext request made to user space.

    Declaration

    typedef uint32_t OSKextRequestTag;

    Import Statement

Constants

See the Overview section above for header-level documentation.

  • Declaration

    #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

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

    • kOSBundleAllowUserLoadKey

      See KextManagerLoadKextWithURL and KextManagerLoadKextWithIdentifier.

    • 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').

    • kOSBundleEnableKextLoggingKey

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

    • kOSBundleIsInterfaceKey

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

    • kOSBundleLibrariesKey

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

    • 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.

    • kOSBundleRequiredKey

      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.

    • kOSBundleRequiredLocalRoot

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

    • kOSBundleRequiredNetworkRoot

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

    • 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.

    • 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.

    • 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.

    • kOSKernelResourceKey

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

    • kOSKextInvalidLoadTag

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

    • kOSKextKernelIdentifier

      This is the CFBundleIdentifier user for the kernel itself.

    • kOSKextRequestTagInvalid

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

    • kOSKextReturnArchNotFound

      Kext does not contain code for the requested architecture.

    • kOSKextReturnAuthentication

      Authetication failures encountered; check diagnostics for details.

    • kOSKextReturnBadData

      Malformed data (not used for XML).

    • kOSKextReturnBootLevel

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

    • kOSKextReturnCache

      An error occurred processing a system kext cache.

    • kOSKextReturnDeferred

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

    • kOSKextReturnDependencies

      Dependency resolution failures encountered; check diagnostics for details.

    • kOSKextReturnDependencyLoadError

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

    • kOSKextReturnDisabled

      Operation is currently disabled.

    • kOSKextReturnInternalError

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

    • kOSKextReturnInUse

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

    • kOSKextReturnInvalidArgument

      Invalid argument.

    • kOSKextReturnLinkError

      A link failure occured with this kext or a dependency.

    • kOSKextReturnLoadedVersionDiffers

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

    • kOSKextReturnNoMemory

      Memory allocation failed.

    • kOSKextReturnNoResources

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

    • kOSKextReturnNotAKext

      Bundle is not a kernel extension.

    • kOSKextReturnNotFound

      Search item not found.

    • kOSKextReturnNotLoadable

      Kext cannot be loaded; check diagnostics for details.

    • kOSKextReturnNotPrivileged

      The caller lacks privileges to perform the requested operation.

    • kOSKextReturnSerialization

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

    • kOSKextReturnStartStopError

      The kext start or stop routine returned an error.

    • kOSKextReturnStopping

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

    • kOSKextReturnTimeout

      A kext request has timed out.

    • kOSKextReturnUnsupported

      Operation is no longer or not yet supported.

    • kOSKextReturnValidation

      Validation failures encountered; check diagnostics for details.

  • Declaration

    extern const void * gOSKextUnresolved;

    Constants

    • gOSKextUnresolved

      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:

      1. if (&foo != gOSKextUnresolved) {
      2. foo();
      3. } else {
      4. printf("foo() is not supported\n");
      5. }