OSKextLib.h Reference

Declared in
OSKextLib.h

Overview

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 by Task

See the Overview section above for header-level documentation.

Weak Linking

Support for weak references to symbols in kexts.

Kext Requests to User Space

Functions for making requests to kextd in user space.

Kext Loading C Functions

Functions for loading and tracking kexts in the kernel.

Kext Information

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

Functions

OSKextCancelRequest

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextGetCurrentIdentifier

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

const char * OSKextGetCurrentIdentifier(
   void);
Return Value

The CFBundleIdentifier for the calling kext as a C string.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextGetCurrentLoadTag

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextGetCurrentVersionString

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

const char * OSKextGetCurrentVersionString(
   void);
Return Value

The CFBundleVersion for the calling kext as a C string.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextLoadKextWithIdentifier

Request that a kext be loaded.

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextReleaseKextWithLoadTag

Release a loaded kext based on its load tag.

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextRequestResource

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextRetainKextWithLoadTag

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextSymbolIsResolved

Checks whether a weakly-referenced symbol has been resolved.

#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");
      }
 
 
Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

Callbacks

See the Overview section above for header-level documentation.

Functions for making requests to kextd in user space.

OSKextRequestResourceCallback

Invoked to provide results for a kext resource request.

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

Data Types

See the Overview section above for header-level documentation.

OSKextLoadTag

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

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

OSKextRequestTag

Identifies a kext request made to user space.

typedef uint32_t OSKextRequestTag;
Availability
  • Available in OS X v10.6 and later.
Declared In
OSKextLib.h

Constants

See the Overview section above for header-level documentation.

Miscellaneous Defines

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

kOSBundleIsInterfaceKey

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

kOSKernelResourceKey

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

kOSKextKernelIdentifier

This is the CFBundleIdentifier user for the kernel itself.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

kOSKextReturnArchNotFound

Kext does not contain code for the requested architecture.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnAuthentication

Authetication failures encountered; check diagnostics for details.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnBadData

Malformed data (not used for XML).

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnBootLevel

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnCache

An error occurred processing a system kext cache.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnDeferred

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnDependencies

Dependency resolution failures encountered; check diagnostics for details.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnDependencyLoadError

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnDisabled

Operation is currently disabled.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnInternalError

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnInUse

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnInvalidArgument

Invalid argument.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnLinkError

A link failure occured with this kext or a dependency.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

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.

Declared in OSKextLib.h.

kOSKextReturnNoMemory

Memory allocation failed.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnNoResources

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnNotAKext

Bundle is not a kernel extension.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnNotFound

Search item not found.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnNotLoadable

Kext cannot be loaded; check diagnostics for details.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnNotPrivileged

The caller lacks privileges to perform the requested operation.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnSerialization

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnStartStopError

The kext start or stop routine returned an error.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnStopping

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

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnTimeout

A kext request has timed out.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnUnsupported

Operation is no longer or not yet supported.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

kOSKextReturnValidation

Validation failures encountered; check diagnostics for details.

Available in OS X v10.6 and later.

Declared in OSKextLib.h.

Global Constants

extern const void * gOSKextUnresolved;
Constants
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.

Declared in OSKextLib.h.