/* * Copyright (c) 2008, 2012 Apple Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ #ifndef __OSKEXT_H__ #define __OSKEXT_H__ #include <sys/cdefs.h> __BEGIN_DECLS #include <CoreFoundation/CoreFoundation.h> #include <System/libkern/OSReturn.h> #include <System/libkern/OSKextLib.h> #include <System/libkern/OSKextLibPrivate.h> #include <mach/mach.h> #include <mach-o/arch.h> // xxx - should I use "Clear" everywhere I use "Flush" /*! * @header * @ignore CF_EXPORT * * The OSKext library provides a comprehensive interface for creating, * examining, and loading kernel extensions (kexts). * * <b>NOTICE:</b> This library is neither thread-safe nor garbage-collection * safe. You must use your own locking with threads sharing access to OSKext. * You can not use this library in an application with garbage collection. */ #pragma mark Types and Constants /******************************************************************************* * Types and Constants *******************************************************************************/ /*! * @typedef OSKextRef * @abstract A reference to a kernel extension object. * * @discussion * The OSKextRef type refers to a KXKext object, which represents a kernel * extension bundle on disk, from an archive, or loaded into the kernel. * OSKext is an opaque type that defines the characteristics and behavior of * OSKext objects. * * The kernel counterpart of OSKext is the OSKext libkern C++ class. */ typedef struct __OSKext * OSKextRef; #define kOSKextBundleExtension "kext" #define kOSKextMkextExtension "mkext" /*! * @typedef OSKextDiagnosticsFlags * @constant kOSKextDiagnosticsFlagAll * @constant kOSKextDiagnosticsFlagValidation * @constant kOSKextDiagnosticsFlagAuthentication * @constant kOSKextDiagnosticsFlagDependencies * @constant kOSKextDiagnosticsFlagWarnings * @constant kOSKextDiagnosticsFlagBootLevel */ enum { kOSKextDiagnosticsFlagNone = (UInt32) 0x0U, kOSKextDiagnosticsFlagValidation = (UInt32) 0x1U, kOSKextDiagnosticsFlagAuthentication = (UInt32) 0x2U, kOSKextDiagnosticsFlagDependencies = (UInt32) 0x4U, kOSKextDiagnosticsFlagWarnings = (UInt32) 0x8U, kOSKextDiagnosticsFlagBootLevel = (UInt32) 0x10U, kOSKextDiagnosticsFlagAll = (UInt32)0xFFFFFFFFU, }; typedef UInt32 OSKextDiagnosticsFlags; /* notify(3) identifiers. */ CF_EXPORT const char * kOSKextLoadNotification; CF_EXPORT const char * kOSKextUnloadNotification; /* Top-level keys for diagnostics dicts. See @link OSKextCopyDiagnostics@/link. */ // xxx - not sure we need to include these, but it's convenient CF_EXPORT const CFStringRef kOSKextDiagnosticsValidationKey; CF_EXPORT const CFStringRef kOSKextDiagnosticsAuthenticationKey; CF_EXPORT const CFStringRef kOSKextDiagnosticsDependenciesKey; CF_EXPORT const CFStringRef kOSKextDiagnosticsWarningsKey; CF_EXPORT const CFStringRef kOSKextDiagnosticsBootLevelKey; #pragma mark Basic CF Functions /********************************************************************* * Basic CF Functions *********************************************************************/ /*! * @function OSKextGetTypeID * @abstract Returns the type identifier for the OSKext opaque type. * * @result The type identifier for the OSKext opaque type. */ CF_EXPORT CFTypeID OSKextGetTypeID(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Module Configuration /********************************************************************* * Module Configuration *********************************************************************/ /*! * @function OSKextSetArchitecture * @abstract Sets the architecture used for operations on kexts. * * @param anArch * An <code>NXArchInfo</code> pointer with cputype/subtype or name set. * Ownership remains with the caller. * Pass <code>NULL</code> to set the architecture to taht of the running kernel. * * @result * <code>true</code> if the architecture was set as desired, * <code>false</code> if <code>anArch</code> was not found; * if <code>false</code>, the architecture will now be that * of the running kernel. * xxx - should it just be left unchanged instead? * * @discussion * The kext library uses this architecture for any architecture-specific * operation, such as property lookups * (see @link OSKextGetValueForInfoDictionaryKey@/link), * dependency resolution, executable access during validation and linking. * The kext architecture is initially that of the running kernel (not of * the user-space process). * * This function looks up the system <code>NXArchInfo</code> struct * for the struct passed in, first using the cputype/subtype, and if that fails, * the name. You can therefore use this function to set the architecture * from an architecture name alone by passing an <code>NXArchInfo</code> struct * with the desired name, * but the cputype/subtype set to CPU_TYPE_ANY and CPU_SUBTYPE_ANY. * * Changing the kext architecture causes all kexts to flush their load info * and dependencies with @link OSKextFlushLoadInfo@/link. */ // xxx - should this also have a flushDependenciesFlag? CF_EXPORT Boolean OSKextSetArchitecture(const NXArchInfo * archInfo) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetArchitecture * @abstract Gets the architecutre used for operations on kexts. * * @result * The architecture used for operations on kexts. * The caller does not own the returned pointer and should not free it. * * @discussion * The kext library uses this architecture for any architecture-specific * operation, such as property lookups * (see @link OSKextGetValueForInfoDictionaryKey@/link), * dependency resolution, executable access during validation and linking. * The kext architecture is initially that of the running kernel (not of * the user-space process). */ CF_EXPORT const NXArchInfo * OSKextGetArchitecture(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetRunningKernelArchitecture * @abstract Returns the architecture of the running kernel. * * @result * The architecture of the running kernel. * The caller does not own the returned pointer and should not free it. * * @discussion * This function consults the kernel task and returns a pointer to the * <code>NXArchInfo</code> struct representing its architecture. * The running kernel's architecture does not necessarily match that * of user space tasks (for example, a 32-bit user space task could be * running with a 64-bit kernel, or vice-versa). */ CF_EXPORT const NXArchInfo * OSKextGetRunningKernelArchitecture(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSetLogFilter * @abstract * Set the logging filter for messages from the kext library * or kernel. * * @param logFilter The log filter to set for user space. * @param kernelFlag <code>true</code> to set the kernel filter, * <code>false</code> to set the user filter. * * @discussion * The default log flag set for both user and kernel space is * <code>@link kOSKextLogWarningLevel@/link | * @link kOSKextLogVerboseFlagsMask@/link</code>. * Log messages are output through the log function set by * @link OSKextSetLogOutputFunction@/link. * * To suppress messages from the kext library or kernel completely, * set the log flags to code>@link kOSKextLogSilentFilter@/link</code>. * Functions whose explicit purpose is to print output, * such as @link OSKextPrintDiagnostics@/link, will still print. */ CF_EXPORT void OSKextSetLogFilter( OSKextLogSpec logFilter, Boolean kernelFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetLogFilter * @abstract Returns the logging filter for user or kernel space. * * @param kernelFlag <code>true</code> to get the kernel filter, * <code>false</code> to get the user filter. * * @result * The current log filter in effect. * * @discussion * The default log flag set for both user and kernel space is * <code>@link kOSKextLogWarningLevel@/link | * @link kOSKextLogVerboseFlagsMask@/link</code>. * Log messages are output through the log function set by * @link OSKextSetLogOutputFunction@/link. */ OSKextLogSpec OSKextGetLogFilter(Boolean kernelFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @typedef OSKextLogOutputFunction * @abstract * Prototype of a callback function used to log messages from the library. * * @param msgLogSpec The log specification that triggered the log message. * @param format A printf(3) style format string. * * @discussion * The default log function simply prints to <code>stderr</code * if <code>msgLogSpec</code> has any bits set. * If you set the log function to <code>NULL</code>, * no log messages will be printed. * * Log messages have no trailing newline, to accommodate system log facilities. */ /* xxx - no CF_EXPORT, compiler dies */ typedef void (*OSKextLogOutputFunction)( OSKextRef aKext, OSKextLogSpec msgLogSpec, const char * format, ...); /*! * @function OSKextSetLogOutputFunction * @abstract Sets the function called to log messages. * * @param funct The log function to set. * * @discussion * The default log function simply prints to stderr. If you set the * log function to <code>NULL</code>, no log messages will be printed. * * Log messages have no trailing newline, to accommodate system log facilities. */ CF_EXPORT void OSKextSetLogOutputFunction(OSKextLogOutputFunction func) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextLog * @abstract Log a message at a given level and with flags. * * @param aKext If not <code>NULL</code>, the OSKext object to which * the log message applies. * @param messageLogSpec The level and flags with which to log the message. * @param format A printf-style format string to log, * followed by optional arguments. * * @discussion * Log messages are filtered based on <code>aKext</code>, * <code>messageLogSpec</code>, and the current log filter as set by * @link <code>OSKextSetLogFilter</code>@/link. * * Log messages have no trailing newline, to accommodate system log facilities. */ CF_EXPORT void OSKextLog( OSKextRef aKext, OSKextLogSpec messageLogSpec, const char * format, ...) __attribute__((format(printf, 3, 4))) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextVLog * @abstract Log a message at a given level and with flags. * * @param aKext If not <code>NULL</code>, the OSKext object to which * the log message applies. * @param messageLogSpec The level and flags with which to log the message. * @param format A printf-style format string to log. * @param srcArgList The corresponding argument list for the format string. * * @discussion * Log messages are filtered based on <code>aKext</code>, * <code>messageLogSpec</code>, and the current log filter as set by * @link <code>OSKextSetLogFilter</code>@/link. * * Log messages have no trailing newline, to accommodate system log facilities. */ void OSKextVLog( OSKextRef aKext, OSKextLogSpec msgLogSpec, const char * format, va_list srcArgList) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextLogCFString * @abstract Log a message at a given level and with flags. * * @param aKext If not <code>NULL</code>, the OSKext object to which * the log message applies. * @param messageLogSpec The level and flags with which to log the message. * @param format A printf-style format CFString to log, * followed by optional arguments. * * @discussion * Log messages are filtered based on <code>aKext</code>, * <code>messageLogSpec</code>, and the current log filter as set by * @link <code>OSKextSetLogFilter</code>@/link. * * Log messages have no trailing newline, to accommodate system log facilities. */ CF_EXPORT void OSKextLogCFString( OSKextRef aKext, OSKextLogSpec messageLogSpec, CFStringRef format, ...) CF_FORMAT_FUNCTION(3,4) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); /*! * @function OSKextVLog * @abstract Log a message at a given level and with flags. * * @param aKext If not <code>NULL</code>, the OSKext object to which * the log message applies. * @param messageLogSpec The level and flags with which to log the message. * @param format A printf-style format string to log. * @param srcArgList The corresponding argument list for the format string. * * @discussion * Log messages are filtered based on <code>aKext</code>, * <code>messageLogSpec</code>, and the current log filter as set by * @link <code>OSKextSetLogFilter</code>@/link. * * Log messages have no trailing newline, to accommodate system log facilities. */ void OSKextVLogCFString( OSKextRef aKext, OSKextLogSpec msgLogSpec, CFStringRef format, va_list srcArgList) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); /*! * @function OSKextSetSimulatedSafeBoot * @abstract Sets whether safe boot mode is simulated in the library. * * @param flag <code>true</code> to simulate safe boot mode, * <code>false</code> to not simulate. * * @discussion * Kexts without a valid OSBundleRequired property are not allowed to load * by the kernel when the system has started in safe boot mode. * If you turn on simulated safe boot, the kext library can * catch non-loadable kexts and present appropriate diagnostics. */ CF_EXPORT void OSKextSetSimulatedSafeBoot(Boolean flag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetSimulatedSafeBoot * @abstract Returns whether safe boot mode is simulated in the library. * * @result * <code>true</code> if safe boot mode is being simulated, * <code>false</code> if not. * * @discussion * Kexts without a valid OSBundleRequired property are not allowed to load * by the kernel when the system has started in safe boot mode. * When simulated safe boot is on, the kext library can * catch non-loadable kexts and present appropriate diagnostics. */ CF_EXPORT Boolean OSKextGetSimulatedSafeBoot(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetActualSafeBoot * @abstract Returns whether safe boot mode is active. * * @result * <code>true</code> if safe boot mode is active, * <code>false</code> if not. * * @discussion * Kexts without a valid OSBundleRequired property are not allowed to load * by the kernel when the system has started in safe boot mode. * The kext library ignores actual safe boot mode, leaving decisions * regarding safe boot to the kernel. * If you want to analyze kexts in safe boot mode using the library, * call @link OSKextSetSimulatedSafeBoot@/link. */ // xxx - we used to disallow kexts w/debug-log flags in safe boot, too CF_EXPORT Boolean OSKextGetActualSafeBoot(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetSystemExtensionsFolderURLs * @abstract Returns the standard system extension folder URLs. * * @result * An array containing the standard system extension folder URLs. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * To open all the kexts normally considered for loading by the system, * pass the return value of this function to * @link OSKextCreateKextsFromURLs@/link. */ CF_EXPORT CFArrayRef OSKextGetSystemExtensionsFolderURLs(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSetRecordsDiagnostics * @abstract Sets whether kexts record diagnostic information. * * @param flags Indicates which diagnostics to record. * * @discussion * The kext library can record diagnostic information for kexts as * problems are encountered. These diagnostics can consume a fair * amount of memory, and should be generated only when desired. * Recording of diagnostics is set to * @link kOSKextDiagnosticsFlagNone@/link by default. * Use this function to turn diagnostics recording off (or back on) * for particular diagnostic types. * * Turning on diagnostics does not calculate or recalculate * diagnostics. Call the various functions that operate on kexts * to begin accumulating diagnostics. * * Turning diagnostics off does not clear any existing diagnostics. * Use @link OSKextFlushDiagnostics@/link explicitly to clear * any diagnostics currently stored. * * See also @link OSKextCopyDiagnostics@/link, * @link OSKextValidate@/link, * @link OSKextAuthenticate@/link, and * @link OSKextResolveDependencies@/link. */ // Could list a pile of see also's here.... CF_EXPORT void OSKextSetRecordsDiagnostics(OSKextDiagnosticsFlags flags) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetRecordsDiagnostics * @abstract * Returns what kinds of diagnostic information kexts record. * * @result * Flags indicating which types of diagnostics are currently * being recorded. You can bitwise-OR or -AND these with other flags * to add or remove diagnostics being recorded with * @link OSKextSetRecordsDiagnostics@/link. */ CF_EXPORT OSKextDiagnosticsFlags OSKextGetRecordsDiagnostics(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSetUsesCaches * @abstract Sets whether the kext library uses cache files. * * @param flag * <code>true</code> to use caches, * <code>false</code> to not use caches. * * @discussion * The kext library normally uses caches to speed up reading kexts from * the system extensions folders. * Use this function to turn off use of caches; this will cause reading * of kexts to be dramatically slower. * * See also @link OSKextGetUsesCaches@/link. */ CF_EXPORT void OSKextSetUsesCaches(Boolean flag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetUsesCaches * @abstract * Returns whether the OSKext library uses cache files. * * @result * <code>true</code> if the library uses caches to speed up reading of kexts, * <code>false</code> if it doesn't. * * @discussion * The kext library normally uses caches to speed up reading kexts from * the system extensions folders. * Use this function to check whether the library is using caches. * * See also @link OSKextGetUsesCaches@/link. */ CF_EXPORT Boolean OSKextGetUsesCaches(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Instance Management /********************************************************************* * Instance Management *********************************************************************/ /*! * @function OSKextCreate * @abstract Read a single kext from an on-disk bundle, without plugins. * * @param allocator * The allocator to use to allocate memory for the new object. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param anURL * The location of the bundle for which to create an OSKext object. * @result * An OSKext object created from the bundle at anURL. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * Returns <code>NULL</code> if there was a memory allocation problem or * if the bundle doesn't exist at anURL (see Discussion). * May return an existing OSKext object with the reference count incremented. * * @discussion * Once a kext has been created, it is cached in memory; the kext bundle cache * is flushed only periodically. OSKextCreate does not check that a cached kext * bundle still exists in the filesystem. If a kext bundle is deleted * from the filesystem, it is therefore possible for OSKextCreate * to return a cached bundle that has actually been deleted. * * OSKext uses a CFBundle briefly during initialization, but in order * to save memory and allow re-reading of kext bundle contents * from disk, does not retain it. Applications can save further memory * by flushing info dictionaries so that they are read from disk again * when needed; see @link OSKextFlushInfoDictionary@/link. */ CF_EXPORT OSKextRef OSKextCreate( CFAllocatorRef allocator, CFURLRef anURL) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateKextsFromURL * @abstract Reads all kexts at an on-disk URL along with their plugins. * * @param allocator * The allocator to use to allocate memory for the new objects. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param anURL The URL to scan for kernel extensions. * @result * Returns an array containing the kext objects created, * or <code>NULL</code> on failure. * * @discussion * This function scans <code>anURL</code> for kexts. * If <code>anURL</code> represents a kext, * this function reads that kext and its plugins. * If <code>anURL</code> represents a non-kext directory, * this functions scans the directory's immediate contents for kext bundles * and their plugins. It does not scan recursively; only plugins one level * deep are read. * * If given an URL for a kext that is a plugin of another kext, this * function does not scan for further plugins. * * This function does not scan for or read mkext files. Use * @link OSKextCreateKextsFromMkextFile@/link to read an mkext file. * * See @link OSKextCreate OSKextCreate @/link for information * about kext object caching. */ CFArrayRef OSKextCreateKextsFromURL( CFAllocatorRef allocator, CFURLRef anURL) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateKextsFromURLs * @abstract Reads all kexts at an array on-disk URLs along with their plugins. * * @param allocator * The allocator to use to allocate memory for the new objects. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param arrayOfURLs The URLs to scan for kernel extensions. * @result * Returns an array containing the kext objects created, * or <code>NULL</code> on failure. * * @discussion * This function scans each URL in <code>arrayOfURLs</code> for kexts. * If a given URL represents a kext, * this function reads that kext and its plugins. * If the URL represents a non-kext directory, this functions scans the * directory's immediate contents for kext bundles and their plugins. * It does not scan recursively; only plugins one level deep are read. * * If given an URL for a kext that is a plugin of another kext, this * function does not scan for further plugins. * * This function does not scan for or read mkext files. Use * @link OSKextCreateKextsFromMkextFile@/link to read an mkext file. * * See @link OSKextCreate@/link for discussion about kext object caching. */ CF_EXPORT CFArrayRef OSKextCreateKextsFromURLs( CFAllocatorRef allocator, CFArrayRef arrayOfURLs) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateWithIdentifier * @abstract Search for and create a kext given its bundle identifier. * * @param allocator * The allocator to use to allocate memory for the new object. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param kextIdentifier * The bundle identifier for which to create a OSKext object. * @result * A OSKext object with the requested bundle identifier, * created according to the search described below. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule @/link. * * Returns <code>NULL</code> if there was a memory allocation problem, * if no bundle can be found for <code>kextIdentifier</code>, * or if the bundle found can't be opened (see Discussion). * May return an existing OSKext object with the reference count incremented. * * @discussion * This function searches the system to create a kext * for <code>kextIdentifier</code>. * It first consults the kernel to get the path for a loaded kext * with that identifier. * If a kext bundle exists at that path and its identifier and version * match what's loaded in the kernel, a kext object for that bundle is returned. * Failing that, this function falls back to searching the directories * provided by * <code>@link OSKextGetSystemExtensionsFolderURLs OSKextGetSystemExtensionsFolderURLs@/link, * attempting to match a loaded kext's identifier and version, * and finally falling back to an identifier match only. * * The returned kext will have its load info set as if * <code>@link OSKextReadLoadedKextInfo OSKextReadLoadedKextInfo@/link * had been called (but other kexts are not affected). * You can use functions such as * <code>@link OSKextIsLoaded OSKextIsLoaded@/link</code> * to check whether the kext created is loaded in the kernel. * * See @link OSKextCreate OSKextCreate @/link for information * about kext object caching. */ CF_EXPORT OSKextRef OSKextCreateWithIdentifier( CFAllocatorRef allocator, CFStringRef kextIdentifier) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetAllKexts * @abstract * Returns an array containing all of the kexts currently open in the application. * * @result * A CFArray object containing OSKext objects for each open kext * in the application. Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * This function is potentially expensive, so use with care. */ CF_EXPORT CFArrayRef OSKextGetAllKexts(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetKextWithURL * @abstract Locate an opened kext given its URL. * * @param anURL * The URL of the opened kext to locate. * @result * An OSKext object, or <code>NULL</code> if the kext was not found * (either because it has not been opened or it failed to open). * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * For a kext to be located by this function, * the kext object must have already been created. * This function allows you to check quickly for a kext without actually * attempting to open it. */ CF_EXPORT OSKextRef OSKextGetKextWithURL( CFURLRef anURL) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetKextWithIdentifier * @abstract Locate a kext given its program-defined identifier. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @result * An OSKext object, or <code>NULL</code> if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * For a kext to be located using its identifier, * the kext object must have already been created. * The principal intended purpose for locating kexts by identifier * is resolving dependencies between kexts. * If a kext is created, then the kext bundle is deleted from the filesystem * and this function invoked afterwards, it will still return the original kext. * * If multiple kexts with the same identifier exist in the application * created from distinct kext bundles, this function returns the kext * with the greatest version. If multiple kexts with the same identifier * and version exist, this function returns the last such kext created. * * Kext identifiers are created by entering a value for the key * CFBundleIdentifier in the kext bundle's Info.plist file. * * To guarantee uniqueness, identifiers take the form * of Java style package names, such as com.myCompany.foo.bar. */ // xxx - check on same-version ordering with folks CF_EXPORT OSKextRef OSKextGetKextWithIdentifier( CFStringRef aBundleID) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyKextsWithIdentifiers * @abstract * Locate a list of kexts given their program-defined identifiers. * * @param bundleIDs * The array of identifiers of the kexts to locate. * Note that identifier names are case-sensitive. * @result * An array of OSKext objects, or <code>NULL</code> * if an allocation error occurs. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Create Rule@/link. * * @discussion * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT CFMutableArrayRef OSKextCopyKextsWithIdentifiers( CFArrayRef bundleIDs) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetKextWithIdentifierAndVersion * @abstract * Locate a kext given its program-defined identifier and version. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @param aVersion * The version of the kext to locate. * @result * An OSKext object, or <code>NULL</code> if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * For a kext to be located using its identifier and version, * the kext object must have already been created. * See @link OSKextGetKextWithIdentifierAndVersion@/link for more. */ // xxx - check on same-version ordering with folks CF_EXPORT OSKextRef OSKextGetKextWithIdentifierAndVersion( CFStringRef aBundleID, OSKextVersion aVersion) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetKextsWithIdentifier * @abstract Locate all kexts with a given program-defined identifier. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @result * An CFArray of kext objects with the given identifier, * or <code>NULL</code> on error. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * @discussion * This function is useful for locating duplicates of a given kext. * * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT CFArrayRef OSKextCopyKextsWithIdentifier( CFStringRef aBundleID) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetLoadedKextWithIdentifier * @abstract * Locate the loaded kext with a given program-defined identifier. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @result * An OSKext object, or <code>NULL</code> if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link before calling this * function for it to find anything. * * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT OSKextRef OSKextGetLoadedKextWithIdentifier( CFStringRef aBundleID) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetCompatibleKextWithIdentifier * @abstract * Locate the kext with a given program-defined identifier * that is compatible with a requested version. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @param requestedVersion * The version that the kext must be compatible with. * @result * An OSKext object, or <code>NULL</code> if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * A kext is compatible with a version if that version lies between * its CFBundleVersion and its OSBundleCompatibleVersion (inclusive). * * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT OSKextRef OSKextGetCompatibleKextWithIdentifier( CFStringRef aBundleID, OSKextVersion requestedVersion) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Basic Accessors /********************************************************************* * Basic Accessors *********************************************************************/ /*! * @function OSKextGetURL * @abstract Returns the CFURL of a kext bundle. * * @param aKext The kext to get the URL for. * @result A CFURL object. Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * This function returns the CFURL that <code>aKext</code> * was originally created with. * It should be resolved to its base for comparison with other kext * URLs. */ CF_EXPORT CFURLRef OSKextGetURL(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); // always absolute /*! * @function OSKextGetIdentifier * @abstract Returns the bundle identifier from a kext's information property list. * * @param aKext The kext to get the identifier for. * @result * A CFString object containing the kext bundle's identifier, * or <code>NULL</code> if none was specified in the information property list. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. */ CF_EXPORT CFStringRef OSKextGetIdentifier(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetValueForInfoDictionaryKey * @abstract * Returns a (possibly architecture-specific) value * in a kext's information dictionary. * * @param aKext The kext to get the property for. * @param key The base key identifying the property. * @result * A value corresponding to <code>key</code> in <code>aKext</code>'s * information dictionary. * If available, an architecture-specific value is returned, * otherwise the global value is returned. Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * This function first looks for a property value specific to the current kext * architecture, as set with @link OSKextSetArchitecture@/link, * by appending an underscore plus the architecture name to the base key. * If such a value is not found, it looks for the property using the base key. * For example, if the currently set architecture is i386, and * IOKitPersonalities is requested, this function looks up the key * IOKitPersonalities_i386; if that doesn't exist, then it uses * IOKitPersonalities. * * Some properties are not allowed to be made architecture-specific; * if such keys are defined, they are ignored by this function: * * * CFBundleIdentifier * * CFBundleVersion * * CFBundleExecutable * * OSBundleIsInterface * * OSKernelResource * * This function looks up architecture-specific values for generic bundle * properties, such as CFBundlePackageType, but such values are of course * ignored by CFBundle. * * If you want to look up a property with a raw key, get the information * dictionary directly using @link OSKextCopyInfoDictionary@/link or * by opening a CFBundle for the kext's URL. * * This function reads the info dictionary from disk if necessary. * See @link OSKextFlushInfoDictionary@/link. */ CF_EXPORT CFTypeRef OSKextGetValueForInfoDictionaryKey( OSKextRef aKext, CFStringRef key) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyInfoDictionary * @abstract Returns a copy of a kext's information dictionary. * * @param aKext The kext to get the information dictionary for. * @result * A CFDictionary object containing the data stored in the kext's * information property list. * OSKext may add extra keys to this dictionary for its own use. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * @discussion * This function uses @link IOCFUnserialize@/link to parse the XML * of the info dictionary, in order to match the parsing used in the kernel. */ CF_EXPORT CFMutableDictionaryRef OSKextCopyInfoDictionary(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextFlushInfoDictionary * @abstract Releases a kext's info dictionary. * * @param aKext The kext that should release its info dictionary. * If <code>NULL</code>, all open kexts' info dictionaries * are flushed. * * @discussion * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * Flushing info dictionaries also allows kext objects to synchronize * with updates on disk; they will automatically re-sort in the * internal lookup tables to reflect changed versions, for example. * (xxx - well they will! that's not fully implemented yet) * * See also @link OSKextFlushDependencies@/link, * @link OSKextFlushLoadInfo@/link, * and @link OSKextFlushDiagnostics@/link. * * Kext objects created from an mkext cannot flush their info * dictionaries. */ CF_EXPORT void OSKextFlushInfoDictionary(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetVersion * @abstract Returns the version of a kext. * * @param aKext The kext to get the version for. * @result The version of the kext as a 64-bit integer. * * @discussion * xxx - needs more info on version format * xxx - need to fix definition of OSKextVersion. */ CF_EXPORT OSKextVersion OSKextGetVersion(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetCompatibleVersion * @abstract Returns the compatible version of a kext * * @param aKext The kext to get the compatible version for. * @result The compatible version of the kext as a 64-bit integer. * * @discussion * This function returns the value of a kext's OSBundleCompatibleVersion * property, parsed into a 64-bit integer that can be compared using * standard integer comparison operators. * * xxx - needs more info on version format, ref to tn: http://developer.apple.com/technotes/tn/tn1132.html */ CF_EXPORT OSKextVersion OSKextGetCompatibleVersion(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyUUIDForArchitecture * @abstract * Returns the compiler-generated UUID of a kext for a given architecture. * * @param aKext The kext to get the UUID for. * @param anArch The architecture desired. * Pass <code>NULL</code> to get the UUID for the * current architecture. * @result * A CFData object containing the UUID of the kext's executable * for <code>anArch</code>, or the currently set architecture if * <code>anArch</code> is <code>NULL</code>. * * @discussion * UUIDs are used in addition to bundle versions to check the identify of * kexts loaded in the kernel. */ CF_EXPORT CFDataRef OSKextCopyUUIDForArchitecture(OSKextRef aKext, const NXArchInfo * anArch) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsKernelComponent * @abstract Returns whether a kext represents a kerne programming interface. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> represents * a kerne programming interface, <code>false</code> otherwise. * * @discussion * A small set of kexts represent interfaces built into the kernel that can * be linked against individually. These are commonly known as * kernel programming interfaces (KPIs), * and the kexts containing them as "pseudokexts". * * If a kext is a kernel component, then it is also always an interface * (see @link OSKextIsInterface@/link). */ CF_EXPORT Boolean OSKextIsKernelComponent(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsInterface * @abstract * Returns whether a kext acts as a linkage subset for another kext, * also known as a symbol set. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> is an interface kext, * <code>false</code> otherwise. * * @discussion * An interface kext has no actual code in its executable, but merely * re-exports a set of symbols (typically a subset) * from those of its dependencies. * * Currently the only interface kexts are the kernel component kexts * the define the kernel programming interfaces for Mac OS X. */ CF_EXPORT Boolean OSKextIsInterface(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsLibrary * @abstract Returns whether a kext can be declared as a library. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> is a library kext, <code>false</code> * otherwise. * * @discussion * A kext is a library kext if it has a valid OSBundleCompatibleVersion * property. Another kext can link against a library kext by listing * the library's identifier and required version in its OSBundleLibraries * property. */ CF_EXPORT Boolean OSKextIsLibrary(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextDeclaresExecutable * @abstract Returns whether a kext declares a CFBundleExecutable property. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> has a nonempty CFBundleExecutable * property, <code>false</code> otherwise. * * @discussion * A kext with an executable is either a loadable kext with actual executable * code, or an interface kext whose executable serves to restrict linkage * to a subset of the symbols of another kext. See @link OSKextIsInterface@/link * for more on the latter type. */ CF_EXPORT Boolean OSKextDeclaresExecutable(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextHasLogOrDebugFlags * @abstract * Returns whether a kext has OSBundleEnableKextLogging set to a true value or * any of its IOKitPersonalities has a nonzero IOKitDebug property. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> has a true OSBundleEnableKextLogging * property or if any personality for the currently set architecture has a * nonzero IOKitDebug property, <code>false</code> otherwise. * * @discussion * Kexts built for distribution should not have any logging or debug flags set. */ CF_EXPORT Boolean OSKextHasLogOrDebugFlags(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsLoggingEnabled * @abstract Returns whether a kext is included in more verbose logging. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> will be included in more * verbose logging, <code>false</code> if not. * * @discussion * Normally log messages about kexts are not logged above the basic level * (<code>@link OSKextLogSpec@/link</code>). * If this property is set on a kext, then such messages will be logged. * A kext can set this in its info dictionary with the * @link OSBundleEnableKextLogging@/link property. */ CF_EXPORT Boolean OSKextIsLoggingEnabled(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsLoggingEnabled * @abstract Sets whether a kext is included in more verbose logging. * * @param aKext The kext to examine. * @param flag <code>true</code> to enable verbose kext logging, * <code>false</code> to disable. * * @discussion * Normally log messages about kexts are not logged above the basic level * (<code>@link OSKextLogSpec@/link</code>). * If this property is set on a kext, then such messages will be logged. * * A kext can set this in its info dictionary with the * @link OSBundleEnableKextLogging@/link property. * This property is one of the few that can be changed at run time. */ CF_EXPORT void OSKextSetLoggingEnabled( OSKextRef aKext, Boolean flag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsLoadableInSafeBoot * @abstract Returns whether the kernel will load a kext during safe boot. * * @param aKext The kext to examine. * @result * <code>true</code> if the kernel will allow <code>aKext</code> during * safe boot, <code>false</code> otherwise. * * @discussion * A kext is loadable during safe boot if it has an OSBundleRequired * property for the kernel's architecture with a value of * "Root", "Local-Root", "Network-Root", "Console", or "Safe Boot". * * This function does not generally cover the issue of loadability due * to problems with validation, authentication, or dependency resolution. * To determine whether a kext can actually be loaded, use * @link OSKextIsLoadable@/link. */ CF_EXPORT Boolean OSKextIsLoadableInSafeBoot(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextDependenciesAreLoadableInSafeBoot * @abstract * Returns whether the kernel will load all of a kext's dependencies * during safe boot. * * @param aKext The kext whose dependencies to examine. * @result * <code>true</code> if the kernel will allow <code>aKext</code>'s dependencies * during safe boot, <code>false</code> otherwise. * * @discussion * A kext is loadable during safe boot if it has an OSBundleRequired * property for the kernel's architecture with a value of * "Root", "Local-Root", "Network-Root", "Console", or "Safe Boot". * * This function does not generally cover the issue of loadability due * to problems with validation, authentication, or dependency resolution. * To determine whether a kext can actually be loaded, use * @link OSKextIsLoadable@/link. */ CF_EXPORT Boolean OSKextDependenciesAreLoadableInSafeBoot(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); /*! * @function OSKextCopyArchitectures * @abstract * Returns a list of <code>NXArchInfo</code> structs for the architectures * found in a kext's executable. * * @param aKext The kext to examine. * @result * A <code>NULL</code>-terminated list of <code>NXArchInfo</code> * struct pointers describing * the architectures supported by <code>aKext</code>, * or <code>NULL</code> if <code>aKext</code> has no executable. * The caller is responsible for freeing the list, but not the individual * <code>NXArchInfo</code> pointers. */ CF_EXPORT const NXArchInfo ** OSKextCopyArchitectures(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSupportsArchitecture * @abstract Returns whether a kext has an executable for a given architecture. * * @param aKext The kext to examine. * @param anArch The <code>NXArchInfo</code> description to check. * If <code>NULL</code>, uses the currently set architecture. * @result * <code>true</code> if <code>aKext</code>'s executable contains code for * <code>anArch</code>. * * @discussion */ // null for current (NOT host) arch Boolean OSKextSupportsArchitecture(OSKextRef aKext, const NXArchInfo * anArch) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); // if NULL, uses current default /*! * @function OSKextCopyPlugins * @abstract Retrieve the plugins of a kext. * * @param aKext The kext to get plugins for. * @result * An array containing the kexts that are plugins of <code>aKext</code>. * * @discussion * This function scans the plugins folder of <code>aKext</code> * and returns an array of the kexts found. * This may result in the creation of new kext objects. * * If <code>aKext</code> is a plugin of another kext * see @link OSKextIsPlugin@/link), * this function returns an empty array. */ CF_EXPORT CFArrayRef OSKextCopyPlugins(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsPlugin * @abstract Returns whether a kext is a plugin of some other kext. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> is a plugin of another kext, * <code>false</code> otherwise. * * @discussion * This function uses a simple algorithm that just checks for the substring * ".kext/" in the absolute path leading up to the kext's bundle name. */ CF_EXPORT Boolean OSKextIsPlugin(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyContainerForPluginKext * @abstract Returns the kext that is the container for a plugin kext. * * @param aKext The kext to find a parent for. * @result * The kext that contains <code>aKext</code> in its PlugIns folder, * or <code>NULL</code> if <code>aKext</code> is not a plugin. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * @discussion * This function creates a kext object for the longest portion of the * path leading to <code>aKext</code>, then checks to see whether * <code>aKext</code> is a plugin of that kext by <code>CFBundle</code>'s * semantics. If so, that kext is returned. * This may result in the creation of a new kext. */ CF_EXPORT OSKextRef OSKextCopyContainerForPluginKext(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyPersonalitiesArray * @abstract Returns the personalities of a kext for the current kext architecture. * * @param aKext The kext to retrieve personalities for. * @result An array of IOKit personality dictionaries. * * @discussion * IOKitPersonalities in kexts require some processing before being sent * to the kernel, and the functions that send personalities expect an array * rather than a dictionary. This function facilitates such use. * * Use @link OSKextGetValueForInfoDictionaryKey@/link to retrieve the raw * personalities dictionary for the current architecture. */ CF_EXPORT CFArrayRef OSKextCopyPersonalitiesArray(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); // xxx - would it be awful to have a function that takes a CFTypeRef that's // xxx - a single kext, an array of kexts, or NULL for all open kexts? /*! * @function OSKextCopyPersonalitiesOfKexts * @abstract * Returns the personalities of multiple kexts for the current kext architecture. * * @param kextArray The kexts to retrieve personalities for. * Pass <code>NULL</code> to retrieve personalities for all open kexts. * @result An array of IOKit personality dictionaries. * * @discussion * IOKitPersonalities in kexts require some processing before being sent * to the kernel, and the functions that send personalities expect an array * rather than a dictionary. This function facilitates such use. */ CF_EXPORT CFArrayRef OSKextCopyPersonalitiesOfKexts(CFArrayRef kextArray) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyExecutableForArchitecture * @abstract * Returns a kext's Mach-O executable, thinned to a single architecture * if desired. * * @param aKext The kext to retrieve the executable from. * @param anArch The architecture desired. * Pass <code>NULL</code> to get the whole, unthinned exectuable. * @result * A <code>CFData</code> object containing the code * for the specified architecture, or <code>NULL</code> if it can't be found. * * @discussion * Note that this function does not use the default kext architecture set by * @link OSKextSetArchitecture@/link when given no architecture. */ CF_EXPORT CFDataRef OSKextCopyExecutableForArchitecture(OSKextRef aKext, const NXArchInfo * anArch) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyResource * @abstract Returns a named resource from a kext's bundle. * * @param aKext The kext to get a resource from. * @param resourceName The name of the requested resource. * @param resourceType The abstract type of the requested resource. * The type is expressed as a filename extension, * such as <code>jpg</code>. * Pass <code>NULL</code> if you don't need * to search by type. * * @result * A <code>CFData</code> object containing the resource file's contents, * or <code>NULL</code> if the resource can't be found. * * @discussion * For a kext created from an on-disk URL, this function uses CFBundle * semantics to locate the resource file. Note that localized resources * and resource subdirectories are not available to kexts calling * @link //apple_ref/c/func/OSKextRequestResource OSKextRequestResource@/link * from within the kernel (because the process providing them runs as root). * You can store such resources in a kext bundle and use them in applications, * but they will not be available to the kext loaded in kernel. */ CF_EXPORT CFDataRef OSKextCopyResource( OSKextRef aKext, CFStringRef resourceName, CFStringRef resourceType) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Dependency Resolution /********************************************************************* * Dependency Resolution *********************************************************************/ /*! * @function OSKextResolveDependencies * @abstract Calculate the dependency graph for a kext. * * @param aKext The kext to resolve dependencies for. * @result * <code>true</code> if all dependencies are successfully resolved, * <code>false</code> otherwise. * * @discussion * This function examines the OSBundleLibraries property of <code>aKext</code> * and looks for compatible open kexts. Priority is given to kexts marked as * loaded (see @link OSKextReadLoadedKextInfo@/link and * @link OSKextFlushLoadInfo@/link). Otherwise the most recent * compatible version is used; if multiple kexts with the same identifier and * version exist, the last one created is used. * * Any problems resolving dependencies are stored in a diagnostics dictionary, * which you can retrieve using @link OSKextCopyDiagnostics@/link. * * If a kext's dependencies have already been resolved, this function does * no work and returns <code>true</code>. * If you want to recalculate a kext's dependencies, call * @link OSKextFlushDependencies@/link first. */ // xxx - check on same-version ordering with folks CF_EXPORT Boolean OSKextResolveDependencies(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextFlushDependencies * @abstract Clears the dependency graph of a kext. * * @param aKext The kext to flush dependencies for. * Pass <code>NULL</code> to flush dependencies for all kexts. * * @discussion * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * Flushing dependencies is also useful when readling loaded kext * information from the kernel with @link OSKextReadLoadedKextInfo@/link * (in fact, that function takes a flag to do it as part of its work). * Dependency resolution gives priority to kexts marked as loaded, * so it's wise to call flush dependencies before reading load info * and before doing any operation that resolves dependencies. * Conversely, if you want to resolve dependencies without consideration * for which kexts are loaded, call @link OSKextFlushLoadInfo@/link * beforehand (with or without the flag to flush dependencies). * * This function also clears any dependency resolution diagnostics. * See also @link OSKextFlushInfoDictionary@/link, * @link OSKextFlushLoadInfo@/link, * and @link OSKextFlushDiagnostics@/link. */ CF_EXPORT void OSKextFlushDependencies(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyDeclaredDependencies * @abstract Returns the kexts identified in a kext's OSBundleLibraries property. * * @param aKext The kext to get dependencies for. * @param needAllFlag If <code>true</code>, the function returns * <code>NULL</code> if any dependency isn't found. * @result * A <code>CFArray</code> containing the kexts found. * If <code>needAllFlag</code> is <code>false</code>, the array may be missing * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all * dependencies are found, this function returns <code>NULL</code>. * * @discussion * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFArrayRef OSKextCopyDeclaredDependencies( OSKextRef aKext, Boolean needAllFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyLinkDependencies * @abstract Returns the kexts that a kext links directly against. * * @param aKext The kext to get dependencies for. * @param needAllFlag If <code>true</code>, the function returns * <code>NULL</code> if any dependency isn't found. * @result * A <code>CFArray</code> containing the kexts found. * If <code>needAllFlag</code> is <code>false</code>, the array may be missing * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all * dependencies are found, this function returns <code>NULL</code>. * * @discussion * Link dependencies are how loaded kext relationships are tracked * in the kernel (as shown by the <code>kextstat(8)</code> program). * Some library kexts contain no executable, merely collecting sets of * other libraries for convenience or compatiblity purposes. * This function follows through such indirect libraries to find kexts * with executables that <code>aKext</code> will actually link against. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ // xxx - need to insert a manpage link on kextstat CF_EXPORT CFArrayRef OSKextCopyLinkDependencies( OSKextRef aKext, Boolean needAllFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyLoadList * @abstract * Returns the entire list of kexts in the load graph of a kext * (including that kext). * * @param aKext The kext to get the load list for. * @param needAllFlag If <code>true</code>, the function returns * <code>NULL</code> if any dependency isn't found. * @result * A <code>CFArray</code> containing the kexts found. * If <code>needAllFlag</code> is <code>false</code>, the array may be missing * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all * dependencies are found, this function returns <code>NULL</code>. * * @discussion * The fully-resolved load list represents all the kexts needed to load * <code>aKext</code> into the kernel, in an order guaranteed to work for * sequential starting and matching with IOKit personalities. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFMutableArrayRef OSKextCopyLoadList( OSKextRef aKext, Boolean needAllFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyLoadListForKexts * @abstract * Returns the entire list of kexts in load order of the merged load graph * of the provided list of kexts (including those kexts). * * @param kexts The kexts to get the load list for. * @param needAllFlag If <code>true</code>, the function returns * <code>NULL</code> if any dependency isn't found. * * @result * A <code>CFArray</code> containing the kexts found. * If <code>needAllFlag</code> is <code>false</code>, the array may be missing * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all * dependencies are found, this function returns <code>NULL</code>. * * @discussion * The fully-resolved load list represents all of the kexts needed to load * every kext in <code>kexts</code> into the kernel, in an order guaranteed to * work for sequential starting and matching with IOKit personalities. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFMutableArrayRef OSKextCopyLoadListForKexts( CFArrayRef kexts, Boolean needAllFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyAllDependencies * @abstract * Returns all kexts that a given kexts depends on, directly or indirectly. * * @param aKext The kext to get dependencies for. * @param needAllFlag If <code>true</code>, the function returns * <code>NULL</code> if any dependency isn't found. * @result * A <code>CFArray</code> containing the kexts found. * If <code>needAllFlag</code> is <code>false</code>, the array may be missing * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all * dependencies are found, this function returns <code>NULL</code>. * * @discussion * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFMutableArrayRef OSKextCopyAllDependencies( OSKextRef aKext, Boolean needAllFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyIndirectDependencies * @abstract * Returns all kexts that a given kexts depends on indirectly. * * @param aKext The kext to get dependencies for. * @param needAllFlag If <code>true</code>, the function returns * <code>NULL</code> if any dependency isn't found. * @result * A <code>CFArray</code> containing the kexts found. * If <code>needAllFlag</code> is <code>false</code>, the array may be missing * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all * dependencies are found, this function returns <code>NULL</code>. * * @discussion * Note that the list of indirect dependencies includes all kexts declared * as dependencies by the direct dependencies of <code>aKext</code> - * it may therefore include a direct dependency as well if some other * kext in the load graph declares it. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ // xxx - This one isn't really useful, is it? CFMutableArrayRef OSKextCopyIndirectDependencies( OSKextRef aKext, Boolean needAllFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextDependsOnKext * @abstract * Returns whether a kext depends on a given library kext, * directly or indirectly. * * @param aKext The kext to examine. * @param libraryKext The possible library kext. * @param directFlag * If <code>true</code>, only checks for a direct declared dependency; * if <code>false</code> check for direct or indirect dependencies. * @result * <code>true</code> if <code>aKext</code> depends on <code>libraryKext</code>, * either directly or indirectly per <code>directFlag</code>. * Returns <code>false</code> otherwise. * * @discussion * This function calls @link OSKextResolveDependencies@/link to find * dependencies. * * This function works with actual dependency resolution, not potential. * If there are multiple kexts with the same bundle identifier, * <code>aKext</code> may not be the one chosen during resolution * and so it might appear that no kexts depend on it, even though they could. */ CF_EXPORT Boolean OSKextDependsOnKext( OSKextRef aKext, OSKextRef libraryKext, Boolean directFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyDependents * @abstract * Return all kexts that depend on a given kext, directly or indirectly. * * @param aKext The kext to get dependents for. * @param directFlag * <code>true</code> to get only kexts that declare a direct * dependency on <code>aKext</code>, * <code>false</code> to get all dependents, direct or indirect. * @result * An array of all kexts that ultimately depend on <code>aKext</code>, * directly or indirectly according to <code>directFlag</code>. * * @discussion * This function calls @link OSKextResolveDependencies@/link on all open * kexts to find dependencies. This can be somewhat expensive. * * This function works with actual dependency resolution, not potential. * If there are multiple kexts with the same bundle identifier, * <code>aKext</code> may not be the one chosen during resolution * and so it might appear that no kexts depend on it, even though they could. */ CF_EXPORT CFMutableArrayRef OSKextCopyDependents(OSKextRef aKext, Boolean directFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsCompatibleWithVersion * @abstract Returns whether a library kext is compatible with a given version. * * @param aKext The kext to examine. * @param aVersion The kext version to check compatibility with * * @result * <code>truer</code> if <code>aKext</code> has a compatible version and * if <code>aVersion</code> is between the version and compatible version of * <code>aKext</code> (inclusive), <code>false</code> otherwise. * * @discussion */ CF_EXPORT Boolean OSKextIsCompatibleWithVersion( OSKextRef aKext, OSKextVersion aVersion) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextLogDependencyGraph * @abstract Prints the resolved dependency graph of a kext. * * @param aKext The kext to log the dependency graph of. * @param bundleIDFlag <code>true</code> to log kexts by bundle ID, * <code>false</code> to log them by URL. * @param linkFlag <code>true</code> to log the link graph only, * <code>false</code> to log the full dependency graph. * * @discussion * <code>linkFlag</code> allows you to display the dependencies as they will * be recorded in the kernel when the kext is loaded. * If it is <code>true</code>, then only kexts with executables are included * in the logged dependency graph. If it is <code>false</code>, all kexts * needed to load </code>aKext</code> are included. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT void OSKextLogDependencyGraph(OSKextRef aKext, Boolean bundleIDFlag, Boolean linkFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextFindLinkDependencies * @abstract Finds kexts that define symbols a kext needs resolved. * * @param aKext The kext to examine. * @param nonKPIFlag * <code>false</code> to look in com.apple.kpi.* kernel component * for kernel symbols; * <code>true</code> to look in com.apple.kernel.* kernel components * instead (not recommended for later versions of Mac OS X). * @param allowUnsupportedFlag * <code>false</code> to skip unsupported libraries in the search; * <code>true</code> to include them. * @param onedefSymbolsOut * A dictionary containing symbols that were found once; * keys are the symbols, values are the kexts defining the key symbol. * Ownership follows the Create Rule. * Pass <code>NULL</code> to not retrieve. * @param undefinedSymbolsOut * A dictionary containing symbols that weren't found; * keys are the symbols, values are undefined. * Ownership follows the Create Rule. * Pass <code>NULL</code> to not retrieve. * @param multiplyDefinedSymbolsOut * A dictionary containing symbols found in multiple library kexts; * keys are the symbols, values are the kexts defining the key symbol. * Ownership follows the Create Rule. * Pass <code>NULL</code> to not retrieve. * @param multipleDefinitionLibraries * A array of all library kexts in which multiply defined symbols * were found; sorted by CFBundleIdentifier. * Ownership follows the Create Rule. * Pass <code>NULL</code> to not retrieve. * @result * An array of kexts that export symbols referenced by <code>aKext</code>, * sorted by CFBundleIdentifier. * * @discussion * This function searches in all open kexts for symbols referenced by * <code>aKext</code>, ignoring the OSBundleLibraries property. * You can use this function to find out what you should list * in a kext's OSBundleLibraries property. * * If <code>undefinedSymbolsOut</code> has a nonzero count, * the symbols named by its keys could not be found in any open kext. * * If <code>multiplyDefinedSymbolsOut</code> has a nonzero count, * some of the result kexts define the same symbol, * and if those duplicates are listed * in OSBundleLibraries a link failure will occur. * You can inspect the contents of <code>multiplyDefinedSymbolsOut</code> * and <code>multipleDefinitionLibraries</code> * by hand to sort out which libraries you should actually declare. * * This function is fairly expensive, as it has to search through all open * kexts' information dictionaries, and all library kexts' executables. */ CFArrayRef OSKextFindLinkDependencies( OSKextRef aKext, Boolean nonKPIFlag, Boolean allowUnsupportedFlag, CFDictionaryRef * undefinedSymbolsOut, CFDictionaryRef * onedefSymbolsOut, CFDictionaryRef * multiplyDefinedSymbolsOut, CFArrayRef * multipleDefinitionLibrariesOut) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Linking and Loading; Other Kernel Operations /********************************************************************* * Linking and Loading; Other Kernel Operations *********************************************************************/ /*! * @function OSKextLoad * @abstract Loads a kext and its dependencies into the kernel. * * @param aKext The kext to load. * @result * kOSReturnSuccess if <code>aKext</code> is successfully loaded * into the kernel, or was already loaded, or an error result if not. * * @discussion * The calling process must have an effective user ID of 0 (root) * to load kexts into the kernel. * * A kext and all its dependencies must pass all validation and authentication * tests to be loadable. See @link OSKextIsLoadable@/link for more information. * * All kexts loaded into the kernel are started, but IOKit personalities * are not sent to the IOCatalogue. * See @link OSKextSendPersonalitiesToKernel@/link. * * This function calls @link OSKextFlushLoadInfo@/link and clears dependencies * for all open kexts. It then calls @link OSKextCopyLoadList@/link * to find dependencies and @link OSKextReadLoadedKextInfo@/link on the * resulting load list. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextLoad(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextLoadWithOptions * @abstract Loads a kext and its dependencies into the kernel. * * @param aKext The kext to load. * @param startExclusion * <code>kOSKextExcludeAll</code> to omit starting <code>aKext</code> * and any of its dependencies not already started, * <code>kOSKextExcludeKext</code> to start the dependencies of * <code>aKext</code> but not <code>aKext</code> itself, * or <code>kOSKextExcludeNone</code> to start all loaded kexts. * @param addPersonalitiesExclusion * <code>kOSKextExcludeAll</code> to omit sending * IOKitPersonalities to the IOCatalogue for <code>aKext</code> * and any of its dependencies * (though they may already be in the IOCatalogue), * <code>kOSKextExcludeKext</code> to send personalities for the * dependencies of <code>aKext</code> but not <code>aKext</code> itself, * or <code>kOSKextExcludeNone</code> to send all personalities. * @param personalityNames * The names of IOKitPersonalities in <code>aKext</code> to send, * <code>addPersonalitiesExclusion</code> allowing. * If <code>NULL</code> all personalities are sent. * This parameter only affects <code>aKext</code>; if dependency * personalities are sent, they are all sent. * @param delayAutounloadFlag * <code>true</code> to cause the kernel's automatic kext unloader * to skip <code>aKext</code> for one cycle, giving extra time * to set up a debug session. <code>false</code> for normal behavior. * * @result * Returns <code>kOSReturnSuccess</code> on success, other values on failure. * * @discussion * This function allows a kext to be loaded but not started or matched * (for IOKit kexts), which is useful in some debug scenarios. * After calling this function, you may need to call @link OSKextStart@/link * to start <code>aKext</code> (along with its dependencies). * You may also need to call @link OSKextSendPersonalitiesToKernel@/link * for any kexts excluded from matching via * <code>addPersonalitiesExclusion</code>. * * The calling process must have an effective user ID of 0 (root) * to load kexts into the kernel. * * A kext and all its dependencies must pass all validation and authentication * tests to be loadable. See @link OSKextIsLoadable@/link for more information. * * This function calls @link OSKextFlushLoadInfo@/link and clears dependencies * for all open kexts. It then calls @link OSKextCopyLoadList@/link * to find dependencies and @link OSKextReadLoadedKextInfo@/link on the * resulting load list. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextLoadWithOptions( OSKextRef aKext, OSKextExcludeLevel startExclusion, OSKextExcludeLevel addPersonalitiesExclusion, CFArrayRef personalityNames, Boolean delayAutounloadFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGenerateDebugSymbols * @abstract Generate debug symbols for a kext and its dependencies. * * @param aKext * The kext to generate debug symbols for. * @param kernelImage * The kernel Mach-O or symbol file to use for linking. * If <code>NULL</code>, the running kernel is used. * * @result * A dictionary whose keys are the bundle IDs of the kexts for which symbols * have been generated with ".sym" appended, and whose values are CFData * objects containing the symbol files. Returns <code>NULL</code> on error. * * @discussion * The result includes only non-interface kexts that have an executable * and a load address set. * Load addresses are set by @link OSKextReadLoadedKextInfo@/link or by * @link OSKextSetLoadAddress@/link. * * If using the running kernel for load addresses, the current architecture * set with @link OSKextSetArchitecture@/link must match that of the running * kernel or this function returns <code>NULL</code>. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFDictionaryRef OSKextGenerateDebugSymbols( OSKextRef aKext, CFDataRef kernelImage) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA); /*! * @function OSKextNeedsLoadAddressForDebugSymbols * @abstract * Returns whether a kext needs a load address set to generate debug symbols. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> needs a load address set * in order to generate debug symbols with * @link OSKextGenerateDebugSymbols@/link, <code>false</code> otherwise. */ CF_EXPORT Boolean OSKextNeedsLoadAddressForDebugSymbols(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA); /*! * OSKextUnload * @abstract Unloads a kext from the kernel if possible. * * @param aKext The kext to unload. * @param terminateServiceAndRemovePersonalities * If <code>true</code>, and the kext to unload has no kexts loaded * against it, all IOService objects defined by that kext will be * asked to terminate so that the unload can proceed, and the personalities * for the kext will be removed from the IOCatalogue. * * @result * <code>kOSReturnSuccess</code> on success, an error code * (typically <code>kOSKextReturnInUse</code>) on failure. * * @discussion * The calling process must have an effective user ID of 0 (root) * to unload kexts from the kernel. * A kext cannot be unloaded if it has any loaed dependents. * * See also the @link IOCatalogueTerminate@/link function. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextUnload(OSKextRef aKext, Boolean terminateServiceAndRemovePersonalities) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * OSKextUnload * @abstract Unloads a kext from the kernel if possible, based on its * CFBundleIdentifier. * * @param kextIdentifier The CFBundleIDentifier of the kext to unload. * @param terminateServiceAndRemovePersonalities * If <code>true</code>, and the kext to unload has no kexts loaded * against it, all IOService objects defined by that kext will be * asked to terminate so that the unload can proceed, and the personalities * for the kext will be removed from the IOCatalogue. * * @result * <code>kOSReturnSuccess</code> on success, an error code * (typically <code>kOSKextReturnInUse</code>) on failure. * * @discussion * The calling process must have an effective user ID of 0 (root) * to unload kexts from the kernel. * A kext cannot be unloaded if it has any loaed dependents. * * See also the @link IOCatalogueTerminate@/link function. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextUnloadKextWithIdentifier(CFStringRef kextIdentifier, Boolean terminateServiceAndRemovePersonalities) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsStarted * @abstract Returns whether a kext loaded in the kernel is started. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> is active and running in the kernel, * <code>false</code> if not loaded or loaded and not started. * * @discussion * This function returns the state recorded the last time * @link OSKextReadLoadedKextInfo@/link was called. */ CF_EXPORT Boolean OSKextIsStarted(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextStart * @abstract Starts a kext loaded in the kernel if possible. * * @param aKext The kext to start. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * This function allows an application to start a kext that is loaded * in the kernel (typically via @link OSKextLoadWithOptions@/link), * and any of its dependencies that aren't also started. * If the kext is already started, this does nothing. * * To start a kext means to call its start function, which is distinct from * the start method of an IOService object. * * The calling process must have an effective user ID of 0 (root) * to start kexts in the kernel. // xxx - need to list errors that may be returned */ CF_EXPORT OSReturn OSKextStart(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextStop * @abstract Stops a kext loaded in the kernel if possible. * * @param aKext The kext to stop. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * This function allows an application to stop a kext that is loaded * in the kernel without unloading it. This may be useful in certain * debugging scenarios. * * A kext cannot be stopped via this function if it has any dependents * that reference it, any client references within the kernel, * or any instances of libkern/IOKit C++ classes. * * To stop a kext means to call its stop function, which is distinct from * the stop method of an IOService object. * * The calling process must have an effective user ID of 0 (root) * to stop kexts in the kernel. */ // xxx - should it be allowed to stop a kext with dependents that are // xxx - themselves not started? // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextStop(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSendPersonalitiesToKernel * @abstract Sends an array of IOKit personalities to the kernel. * * @param personalities The personalities to send. * @param resetFlag <code>TRUE</code> if the IOCatalogue should be reset, * <code>FALSE</code> not. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * This function sends an anonymous array of personalities to the * I/O Kit's IOCatalogue object in the kernel, * resetting the IOCatalogue if <code>resetFlag</code> is <code>TRUE</code>. * Resetting causes the IOCatalogue to contain only the kernel's built-in * personalities and those sent using this function. * (See also <code>@link IOCatalogueReset@/link</code>.) * * You can get personalities from kexts using * <code>@link OSKextCopyPersonalitiesArray@/link</code> or * <code>@link OSKextCopyPersonalitiesOfKexts@/link</code>. * * The calling process must have an effective user ID of 0 (root) * to send personalities to the kernel. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextSendPersonalitiesToKernel(CFArrayRef personalities, Boolean resetFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSendKextPersonalitiesToKernel * @abstract * Sends the personalities of a single kext to the kernel, optionally * filtered by name. * * @param aKext The kext whose personalities to send. * @param personalityNames * An array of names. Only personalities from <code>aKext</code> * with these names are sent to the kernel. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * If any names in <code>personalityNames</code> are not found, * they are simply skipped rather than causing an error. * * This function may be useful in certain debugging scenarios, * where a particular personality is causing problems. * * The calling process must have an effective user ID of 0 (root) * to send personalities to the kernel. */ // xxx - should names not found cause an error? // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextSendKextPersonalitiesToKernel( OSKextRef aKext, CFArrayRef personalityNames) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSendPersonalitiesOfKextsToKernel * Sends the personalities of multiple kexts to the kernel in a single * operation. * * @param kextArray The kexts whose personalities to send. * @param resetFlag <code>TRUE</code> if the IOCatalogue should be reset, * <code>FALSE</code> not. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * This function performs one data transfer to the kernel, collecting * all the personalities of the kexts in <code>kextArray</code>, * and resetting the IOCatalogue if <code>resetFlag</code> is <code>TRUE</code>. * Resetting causes the IOCatalogue to contain only the kernel's built-in * personalities and those sent using this function. * (See also <code>@link IOCatalogueReset@/link</code>.) * * The calling process must have an effective user ID of 0 (root) * to send personalities to the kernel. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextSendPersonalitiesOfKextsToKernel(CFArrayRef kextArray, Boolean resetFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextRemoveKextPersonalitiesFromKernel * Removes all personalities for a kext's bundle identifier from the kernel. * * @param aKext The kext whose personalities to remove. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * This function removes from the kernel's IOCatalogue all personalities * whose CFBundleIdentifiers match that of <code>aKext</code> so that no * further load requests for <code>aKext</code> will be made. This is * typically done when it is discovered that <code>aKext</code> cannot * be loaded from user space (if it fails to load in the kernel, matching * personalities are automatically removed). * * Note that kexts other than <code>aKext</code> might have published * personalities in the IOCatalogue under <code>aKext</code>'s identifier. * Such personalities will also be removed, since they trigger load requests * for a kext that cannot be loaded. The OSKext library adds an * IOPersonalityPublisher property to such personalities, that gives the * bundle identifier of the originating kext. * * This function differs from * @link OSKextRemovePersonalitiesForIdentifierFromKernel@/link * by having a kext object to check for logging or other purposes. * * The calling process must have an effective user ID of 0 (root) * to remove personalities from the kernel. */ // xxx - need to list errors that may be returned // xxx - this is a not-so-thin shim over IOCatalogueSendData (kIOCatalogueRemoveDrivers) // xxx - might we just want the function to take a bundle ID? // xxx - does IOCatalogueSendData really require root access? CF_EXPORT OSReturn OSKextRemoveKextPersonalitiesFromKernel(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextRemovePersonalitiesForIdentifierFromKernel * Removes all personalities for a given bundle identifier from the kernel. * * @param aBundleID The bundle identifier for which to remove personalities. * @result * <code>kOSReturnSuccess</code> on success, an error code on failure. * * @discussion * This function removes from the kernel's IOCatalogue all personalities * whose CFBundleIdentifiers are <code>aBundleID</code> so that no * further load requests for the kext with that identifier will be made. * This is typically done when it is discovered no kext can be found for * <code>aBundleID</code>. * * This function differs from * @link OSKextRemoveKextPersonalitiesFromKernel@/link * by not having a kext object to check for logging or other purposes. * * The calling process must have an effective user ID of 0 (root) * to remove personalities from the kernel. */ // xxx - need to list errors that may be returned // xxx - this is a not-so-thin shim over IOCatalogueSendData (kIOCatalogueRemoveDrivers) // xxx - I want 2 separate functions for logging; a kext can have flags in it // xxx - does IOCatalogueSendData really require root access? CF_EXPORT OSReturn OSKextRemovePersonalitiesForIdentifierFromKernel(CFStringRef aBundleID) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateLoadedKextInfo * @abstract Returns information about loaded kexts in a dictionary. * * @param kextIdentifiers An array of kext identifiers to read from the kernel. * Pass <code>NULL</code> to read info for all loaded kexts. * @result * An array of dictionaries containing information about loaded kexts. * * @discussion * This function is deprecated in Mac OS X 10.7. * Use @link OSKextCopyLoadedKextInfo/@link instead. * * This function gets information from the kernel without affecting any * kext objects. If you want to update open kext objects to reflect * whether they are loaded in the kernel, use @link OSKextReadLoadedKextInfo@/link. * * See <code>@link OSKextCopyLoadedKextInfo@/link</code> for the list of properties * returned. */ // xxx - need to document the keys from OSKextLib.h. CF_EXPORT CFArrayRef OSKextCreateLoadedKextInfo( CFArrayRef kextIdentifiers) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6, __MAC_10_7, __IPHONE_3_2, __IPHONE_4_3); /*! * @function OSKextCopyLoadedKextInfo * @abstract Returns information about loaded kexts in a dictionary. * * @param kextIdentifiers An array of kext identifiers to read from the kernel. * Pass <code>NULL</code> to read info for all loaded kexts. * @param infoKeys An array of info keys to read from the kernel. * Pass <code>NULL</code> to read all information. * @result * A dictionary, keyed by bundle identifier, of dictionaries containing information about loaded kexts. * * @discussion * This function gets information from the kernel without affecting any * kext objects in process memory. * If you want to update open kext objects to reflect * whether they are loaded in the kernel, * use @link OSKextReadLoadedKextInfo@/link. * * The properties returned by this function are listed below. * Some are taken directly from the kext's information property list, * and some are generated at run time. * Never assume a given key will be present for a kext. * * <ul> * <li><code>CFBundleIdentifier</code> - CFString</li> * <li><code>CFBundleVersion</code> - CFString (note: version strings may be canonicalized * but their numeric values will be the same; "1.2.0" may become "1.2", for example)</li> * <li><code>OSBundleCompatibleVersion</code> - CFString</li> * <li><code>OSBundleIsInterface</code> - CFBoolean</li> * <li><code>OSKernelResource</code> - CFBoolean</li> * <li><code>OSBundleCPUType</code> - CFNumber</li> * <li><code>OSBundleCPUSubtype</code> - CFNumber</li> * <li><code>OSBundleMachOHeaders</code> - CFData (this property is not available via the * public @link KextManagerCopyLoadedKextInfo/@link function)</li> * <li><code>OSBundlePath</code> - CFString (this is merely a hint stored in the kernel; * the kext is not guaranteed to be at this path)</li> * <li><code>OSBundleExecutablePath</code> - CFString * (the absolute path to the executable within the kext bundle; a hint as above)</li> * <li><code>OSBundleUUID</code> - CFData (the UUID of the kext executable, if it has one)</li> * <li><code>OSBundleStarted</code> - CFBoolean (true if the kext is running)</li> * <li><code>OSBundlePrelinked</code> - CFBoolean (true if the kext is loaded from a prelinked kernel)</li> * <li><code>OSBundleLoadTag</code> - CFNumber (the "Index" given by kextstat)</li> * <li><code>OSBundleLoadAddress</code> - CFNumber</li> * <li><code>OSBundleLoadSize</code> - CFNumber</li> * <li><code>OSBundleWiredSize</code> - CFNumber</li> * <li><code>OSBundleDependencies</code> - CFArray of load tags identifying immediate link dependencies</li> * <li><code>OSBundleRetainCount</code> - CFNumber (the OSObject retain count of the kext itself)</li> * <li><code>OSBundleClasses</code> - CFArray of CFDictionary containing info on C++ classes * defined by the kext:</li> * <ul> * <li><code>OSMetaClassName</code> - CFString</li> * <li><code>OSMetaClassSuperclassName</code> - CFString, absent for root classes</li> * <li><code>OSMetaClassTrackingCount</code> - CFNumber giving the instance count * of the class itself, <i>plus</i> 1 for each direct subclass with any instances</li> * </ul> * </ul> */ CF_EXPORT CFDictionaryRef OSKextCopyLoadedKextInfo( CFArrayRef kextIdentifiers, CFArrayRef infoKeys) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); /*! * @function OSKextReadLoadedKextInfo * @abstract Updates kext objects with load info from the kernel. * * @param kextIdentifiers An array of kext identifiers to read * from the kernel; * all matching kexts have their load info updated. * Pass <code>NULL</code> to update load info for all kexts. * @param flushDependenciesFlag * <code>true</code> to clear dependency information from kexts, * <code>false</code> to leave it in place. * * @result * <code>kOSReturnSuccess</code> if all information is successfully updated, * an error code otherwise. Specifically, if the current architecture set * by @link OSKextSetArchitecture@/link is not that of the running kernel, * this function returns <code>kOSKextReturnExecutableArchNotFound</code>. * * @discussion * The load status of kexts primarily affects dependency resolution in the * kext library, in that kexts marked as loaded are given priority over * all other kexts of the same identifier. * See @link OSKextResolveDependencies@/link for more. * * This function calls @link OSKextFlushLoadInfo@/link on the kexts, * which clears any previous load info for them * (or for all kexts if <code>kextIdentifiers</code> is <code>NULL</code>). * If <code>flushDependenciesFlag</code> is <code>true</code>, * resolved dependencies (which may not match the loaded kexts * in the kernel) are also flushed. * Load addresses are then set from the kernel, * but dependencies are resolved as needed. * * If <code>flushDependenciesFlag</code> is <code>false</code>, * existing dependency graphs are maintained, allowing you to * check whether the dependencies, as resolved before reading * load information, reflect loaded kexts (by getting the load list * via @link OSKextCopyLoadList@/link and checking the kexts in it * with @link OSKextIsLoaded@/link). */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextReadLoadedKextInfo( CFArrayRef kexts, Boolean flushDependenciesFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsLoaded * @abstract Returns whether a kext is loaded in the kernel. * * @param aKext The kext to examine. * @result * <code>true</code> if a kext with the same identifier, version, and UUID * as <code>aKext</code> is loaded in the kernel, <code>false</code> otherwise. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link for this flag to be meaningful, * which in turn requires the current library architecture to match that * of the running kernel. * Use @link OSKextOtherVersionIsLoaded@/link to check whether * a different version of <code>aKext</code> is loaded. */ CF_EXPORT Boolean OSKextIsLoaded(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetLoadAddress * @abstract Returns the actual or simulated kernel load address of a kext. * * @param aKext The kext to examine. * @result * The load address of <code>aKext</code>, whether read from the kernel using * @link OSKextReadLoadedKextInfo@/link or set for symbol generation using * @link OSKextSetLoadAddress@/link. * * @discussion * Load addresses are accessed as 64-bit numbers even for 32-bit architectures; * cast or truncate the value as necessary. * * You must call @link OSKextReadLoadedKextInfo@/link or * @link OSKextSetLoadAddress@/link for the load address to be nonzero. */ CF_EXPORT uint64_t OSKextGetLoadAddress(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextSetLoadAddress * @abstract * Sets the simulated kernel load address of a kext for symbol generation. * * @param aKext The kext to set a load address for. * @result * <code>true</code> if the address was set, <code>false</code> if not * (because it's too large for the current architecture). * * @discussion * Load addresses are accessed as 64-bit numbers even for 32-bit architectures. * If you attempt to set a load address that is too large for a 32-bit link, * this function returns <code>false</code>. * See @link OSKextSetArchitecture@/link. * * Setting a load address manually is useful for generating debug symbols * with @link OSKextGenerateDebugSymbols@/link. */ CF_EXPORT Boolean OSKextSetLoadAddress(OSKextRef aKext, uint64_t anAddress) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextOtherVersionIsLoaded * @abstract * Returns whether another version of a given kext is loaded in the kernel. * * @param aKext The kext to examine. * @result * <code>true</code> if a kext with the same identifier, * but a different version or UUID * from <code>aKext</code>, is loaded in the kernel. * Returns <code>false</code> if <code>aKext</code> is loaded or if * no kext with the same identifier is loaded. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link for this flag to be meaningful, * which in turn requires the current library architecture to match that * of the running kernel. * Use @link OSKextIsLoaded@/link to check whether <code>aKext</code> * itself is loaded. */ CF_EXPORT Boolean OSKextOtherVersionIsLoaded(OSKextRef aKext, Boolean * uuidFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextGetLoadTag * @abstract * Returns the load tag of a kext if it's loaded in the kernel. * * @param aKext The kext to examine. * @result * The load tag (also known as the index or kmod id) of <code>aKext</code>, * if it's loaded in the kernel (use @link OSKextIsLoaded@/link to check that). * Returns 0 if <code>aKext</code> is not loaded or if it can't be determined * whether it is loaded. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link for the load tag * to be meaningful, which in turn requires the current library architecture * to match that of the running kernel. * Use @link OSKextIsLoaded@/link to check whether <code>aKext</code> * is loaded. */ CF_EXPORT uint32_t OSKextGetLoadTag(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextFlushLoadInfo * @abstract Clears all load and dependency information from a kext. * * @param aKext * The kext to clear. If <code>NULL</code>, all open * kexts have their load info flushed. * @param flushDependenciesFlag * <code>true</code> to clear dependency information from kexts, * <code>false</code> to leave it in place. * * @discussion * Flushing load information releases the internal load information * structs of a kext, including load flags, the bundle executable, * link/load diagnostics, and if <code>flushDependenciesFlag</code> is true, * the dependencies. * * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * Flushing load info is also useful after readling loaded kext * information from the kernel with @link OSKextReadLoadedKextInfo@/link * or after working with executables. Executables in particular * consume a lot of application memory, often unnecessarily, since * the code is loaded and running in the kernel. * * See also @link OSKextFlushInfoDictionaries@/link, * @link OSKextFlushDependencies@/link, * and @link OSKextFlushDiagnostics@/link. */ CF_EXPORT void OSKextFlushLoadInfo( OSKextRef aKext, Boolean flushDependenciesFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyAllRequestedIdentifiers * @abstract * Copies the list of all unique bundle identifiers of kext load requests * that the kernel has received since power-on. * * @result * A CFArray object, or <code>NULL</code> if the copy failed. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * */ CF_EXPORT CFArrayRef OSKextCopyAllRequestedIdentifiers(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Sanity Checking and Diagnostics /********************************************************************* * Sanity Checking and Diagnostics *********************************************************************/ /*! * @function OSKextParseVersionCFString * @abstract * Parses a kext version from a CFString. * * @param versionString The kext version string to parse. * @result * The numeric rendering of <code>versionString</code>, which can * compared arithmetically with other valid version numbers. * Returns -1 if the version couldn't be parsed. */ CF_EXPORT OSKextVersion OSKextParseVersionCFString(CFStringRef versionString) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextValidate * @abstract * Sanity checks a kext's info dictionary and executable for the currently * set architecture. * * @param aKext The kext to validate. * @result * <code>true</code> if <code>aKext</code> passes all validation tests, * <code>false</code> otherwise. * * @discussion * This function forces full validation of a kext, collecting all * errors found in the validation diagnostics if recording is turned on * (with @link OSKextSetRecordsDiagnostics@/link). You can get the diagnostics * using @link OSKextCopyDiagnostics@/link. * * If safe boot is currently simulated (see * @link OSKextSetSimulatedSafeBoot@/link), * any kext not loadable during safe boot will fail validation. */ // compare with CFBundlePreflightExecutable() CF_EXPORT Boolean OSKextValidate(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsValid * @abstract * Returns whether a kext is valid or not. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> passes all validation tests, * <code>false</code> otherwise. * * @discussion * This function avoids doing full validation if any problems have been * discovered with the kext during other operations. To perform a full * validation of all possible problems, use @link OSKextValidate@/link. */ CF_EXPORT Boolean OSKextIsValid(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextValidateDependencies * @abstract Validates all dependencies of a kext. * * @param aKext The kexts whose dependencies to validate. * @result * <code>true</code> if all dependencies of <code>aKext</code> are valid, * <code>false</code> if any of them are not. * * @discussion * This function calls @link OSKextValidate@/link on <code>aKext</code> and * all the current dependencies of <code>aKext</code>. * Use @link OSKextCopyDiagnostics@/link * with a flag of @link kOSKextDiagnosticsFlagDependencies@/link * to get the dependency-resolution failures caused by invalid dependencies. * * If safe boot is currently simulated (see * @link OSKextSetSimulatedSafeBoot@/link), * any kext not loadable during safe boot will fail validation. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT Boolean OSKextValidateDependencies(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextAuthenticate * @abstract Authenticates file ownership and permissions of a kext. * * @param aKext The kext to examine. * @result * <code>true</code> if all directories and files in <code>aKext</code>'s * bundle or mkext source have secure ownership and permissions, * <code>false</code> if they do not, or if authentication could not be done. * * @discussion * This function forces full authentication of a kext, collecting all * errors found in the authentication diagnostics, collecting all * errors found in the validation diagnostics if recording is turned on * (with @link OSKextSetRecordsDiagnostics@/link). You can get the diagnostics * using @link OSKextCopyDiagnostics@/link. * * For a kext to be loadable into the kernel, it must be owned by * user root, group wheel, and its constituent files and directories * must be nonwritable by group and other. * A kext created from an mkext file uses that mkext file for authentication * (see @link OSKextCreateKextsFromMkextFile@/link. */ CF_EXPORT Boolean OSKextAuthenticate(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsAuthentic * @abstract * Returns whether a kext is authentic or not. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> passes all authentication tests, * <code>false</code> otherwise. * * @discussion * This function avoids doing full authentication if any problems have been * discovered with the kext during other operations. To perform a full * validation of all possible problems, use @link OSKextValidate@/link. */ CF_EXPORT Boolean OSKextIsAuthentic(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextAuthenticateDependencies * @abstract Authenticates all dependencies of a kext. * * @param aKext The kexts whose dependencies to authenticate. * @result * <code>true</code> if all dependencies of <code>aKext</code> are authentic, * <code>false</code> if any of them are not. * * @discussion * This function calls @link OSKextAuthenticate@/link on <code>aKext</code> * and all the current dependencies of <code>aKext</code>. * Use @link OSKextCopyDiagnostics@/link * with a flag of @link kOSKextDiagnosticsFlagDependencies@/link * to get the dependency-resolution failures caused by inauthentic dependencies. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT Boolean OSKextAuthenticateDependencies(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextIsLoadable * @abstract * Returns whether a kext appears loadable for the current architecture. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> has no problems with validation, * authentication, or dependency resolution for the current architecture, * and if it's eligible for the current safe boot mode. * Returns <code>false</code> otherwise. * * @discussion * This function resolves dependencies for <code>aKext</code>, * validates and authenticsates <code>aKext</code> and its dependencies, * and if safe boot is simulated also checks the OSBundleRequired property * of <code>aKext</code> and its dependencies. If all these tests pass, * the kext is considered loadable for the current architecture * (which need not match that of the running kernel). * * See @link OSKextSetArchitecture@/link and * @link OSKextSetSimulatedSafeBoot@/link. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT Boolean OSKextIsLoadable(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCopyDiagnostics * @abstract Returns diagnostics information for a kext. * * @param aKext The kext to get diagnostics for. * @param typeFlags Flags indicating which diagnostics to retrieve. * @result * A dictionary containing diagnostics for <cod>aKext</code>, suitable * for display in an outline view or printout. * * @discussion * You can use this function after validating, authenticating, resolving * dependencies, or generating debug symbols to get all the problems encountered * with those operations. * * The exact keys and values used for diagnostics are for informational purposes * only, are not formally defined, and may change without warning. * * You can use @link OSKextLogDiagnostics@/link to print nicely-formatted * reports of any problems found with kexts. */ // xxx - need to tie in with the kernel & linker to get link failures CFDictionaryRef OSKextCopyDiagnostics(OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextLogDiagnostics * @abstract Logs specified diagnostics for a kext. * * @param aKext The kext to log diagnostics for. * @param typeFlags Flags indicating which diagnostics to log. * * @discussion * You can use this function after validating, authenticating, resolving * dependencies, or generating debug symbols to display all the problems * encountered with those operations. */ CF_EXPORT void OSKextLogDiagnostics( OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextFlushDiagnostics * @abstract Clears all diagnostics information from a kext. * * @param aKext * The kext to clear diagnostics from. * Pass <code>NULL</code> to flush diagnostics from all open kexts. * @param typeFlags Flags indicating which diagnostics to flush. * * @discussion * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * See also @link OSKextFlushInfoDictionaries@/link, * @link OSKextFlushDependencies@/link, * and @link OSKextFlushLoadInfo@/link. */ CF_EXPORT void OSKextFlushDiagnostics(OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); #pragma mark Mkext and Prelinked Kernel Files /********************************************************************* * Mkext and Prelinked Kernel Files *********************************************************************/ // xxx - Use "Flag" or "Mask"? typedef uint32_t OSKextRequiredFlags; #define kOSKextOSBundleRequiredNone 0x0 #define kOSKextOSBundleRequiredRootFlag 0x1ULL #define kOSKextOSBundleRequiredLocalRootFlag 0x1ULL << 1 #define kOSKextOSBundleRequiredNetworkRootFlag 0x1ULL << 2 #define kOSKextOSBundleRequiredSafeBootFlag 0x1ULL << 3 #define kOSKextOSBundleRequiredConsoleFlag 0x1ULL << 4 /*! * @function OSKextIsFromMkext * @abstract Returns whether a kext was created from an mkext archive. * * @param aKext The kext to examine. * @result * <code>true</code> if <code>aKext</code> was created from an mkext archive, * <code>false</code> if it was created from an on-disk bundle. * * @discussion * A kext created from an mkext will have only its info dictionary, executable, * and any resources listed in its the OSBundleStartupResources property. */ CF_EXPORT Boolean OSKextIsFromMkext(OSKextRef aKext) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextMatchesRequiredFlags * @abstract * Returns whether a kext matches a given set of flags for inclusion in an * mkext archive. * * @param aKext The kext to examine. * @param requiredFlags * Flags indicating which values of OSBundleRequired * are needed. * @result * <code>true</code> if <code>aKext</code>'s OSBundleRequired property * matches one of the specified flags, <code>false</code> otherwise. * * @discussion * This function is used to select kexts for inclusion in an mkext archive. * See @link OSKextFilterRequiredKexts@/link and * @link OSKextCreateMkext@/link. */ CF_EXPORT Boolean OSKextMatchesRequiredFlags(OSKextRef aKext, OSKextRequiredFlags requiredFlags) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextFilterRequiredKexts * @abstract * Filters an array of kexts based on a set of flags * for inclusion in an mkext archive. * * @param kextArray * The kexts to filter. * Pass <code>NULL</code> to filter all open kexts. * @param requiredFlags * Flags indicating which values of OSBundleRequired * are needed. * @result * An array of kexts matching <code>requiredFlags</code>. * * @discussion * This function is used to select kexts for inclusion in an mkext archive. * See @link OSKextCreateMkext@/link. * */ CF_EXPORT CFArrayRef OSKextFilterRequiredKexts(CFArrayRef kextArray, OSKextRequiredFlags requiredFlags) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateMkext * @abstract Create an mkext file from an array of kexts and set of flags. * * @param allocator * The allocator to use to allocate memory for the new object. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param kextArray * The kexts to include in the mkext. * Pass <code>NULL</code> to use all open kexts. * @param volumeRootURL * If non-<code>NULL</code>, kexts with this URL as a prefix * strip it when saving their paths in the mkext. * This allows creation of mkexts for volumes * other than the current startup volume. * @param requiredFlags * A set of flags that filters <code>kextArray</code> to a subset * of kexts required for specific startup scenarios * (typically local disk vs. network). * @param compressFlag * <code>true</code> to compress data in the mkext, * <code>false</code> to include them at full size. * COMPRESSED MKEXTS ARE NOT SUPPORTED IN THE KERNEL YET. * @result * A <code>CFData</code> object containing the mkext file data on success, * <code>NULL</code> on failure. * * @discussion * This function creates a single-architecture mkext file for the currently * set library architecture (see @link OSKextSetArchitecture@/link). Kexts * with executables lacking code for that architecture are not included. * * If you want to create a multi-architecture mkext, create a set of single * architecture mkext files and use lipo(1) or combine them programmatically. * * This function generates mkext files in a new format that only works on * Mac OS X 10.6 or later. */ // xxx - add a version param and generate old-format mkexts? // xxx - add flag to take only most recent version of a given bundle ID? CF_EXPORT CFDataRef OSKextCreateMkext( CFAllocatorRef allocator, CFArrayRef kextArray, CFURLRef volumeRootURL, OSKextRequiredFlags requiredFlags, Boolean compressFlag) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateKextsFromMkextFile * @abstract Reads all kexts from an mkext file on disk. * * @param alocator * The allocator to use to allocate memory for the new objects. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param mkextURL * The mkext file URL from which to create kexts. * @result * Returns an array containing the kext objects created, * or <code>NULL</code> on failure. * * @discussion * This function creates kext objects from an mkext file rather than from * bundles on disk. Kexts created with this function are authenticated using * the mkext file at <code>mkextURL</code>. * * A kext created from an mkext has only its info dictionary, executable, * and any resources listed in its the OSBundleStartupResources property. * * Kexts created from an mkext are not uniqued using filesystem URLs, * which belong to bundles actually in the filesystem; * @link OSKextCreate@/link will never return a kext extracted from an mkext * that originally had the URL given (even though the new mkext format * stores that original URL). * This also means that if you open the same mkext file multiple times, * you will create distinct, identical copies of the kexts in that mkext file. */ CF_EXPORT CFArrayRef OSKextCreateKextsFromMkextFile(CFAllocatorRef allocator, CFURLRef mkextURL) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @function OSKextCreateKextsFromMkextData * @abstract Reads all kexts from an mkext file in memory. * * @param alocator * The allocator to use to allocate memory for the new objects. * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> * to use the current default allocator. * @param mkextData * The mkext file data from which to create kexts. * @result * Returns an array containing the kext objects created, * or <code>NULL</code> on failure. * * @discussion * This function creates kext objects from an mkext file in memory * rather than from bundles on disk. Lacking any file in the filesystem, * kexts created with this function can not be authenticated. * * A kext created from an mkext has only its info dictionary, executable, * and any resources listed in its the OSBundleStartupResources property. * * Kexts created from an mkext are not uniqued using filesystem URLs, * which belong to bundles actually in the filesystem; * @link OSKextCreate@/link will never return a kext extracted from an mkext * that originally had the URL given (even though the new mkext format * stores that original URL). * This also means that if you open the same mkext file multiple times, * you will create distinct, identical copies of the kexts in that mkext file. */ CF_EXPORT CFArrayRef OSKextCreateKextsFromMkextData(CFAllocatorRef allocator, CFDataRef mkextData) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); /*! * @enum OSKextKernelcacheFlags * @abstract The flags that affect the behavior of * @link OSKextCreatePrelinkedKernel@/link. * * @constant kOSKextKernelcacheNeedAllFlag * If set and any kext fails to link, * @link OSKextCreatePrelinkedKernel@/link returns <code>NULL</code>. * @constant kOSKextKernelcacheSkipAuthenticationFlag * If set, kexts are not authenticated for inclusion in the prelinked * kernel. * @constant kOSKextKernelcachePrintDiagnosticsFlag * If set, problems with the kexts that prevent inclusion of a kext in * the prelinked kernel are logged via * @link OSKextLogDiagnostics OSKextLogDiagnostics@/link. * @constant kOSKextKernelcacheIncludeAllPersonalitiesFlag * If set, all kext personalities will be included in the prelinked * kernel, regardless of whether they're required. * @constant kOSKextKernelcacheStripSymbols * If set, symbol tables are stripped from kexts before they are * placed in the prelinked kernel. If symbolsOut is * non-<code>NULL</code>, symbolicated binaries will still be returned * to the caller. * @constant kOSKextKernelcacheKASLRFlag * If set, generate DYSYMTAB load commands for KASLR support. */ enum { kOSKextKernelcacheNeedAllFlag = (1 << 0), kOSKextKernelcacheSkipAuthenticationFlag = (1 << 1), kOSKextKernelcachePrintDiagnosticsFlag = (1 << 2), kOSKextKernelcacheIncludeAllPersonalitiesFlag = (1 << 3), kOSKextKernelcacheStripSymbolsFlag = (1 << 4), kOSKextKernelcacheKASLRFlag = (1 << 5), }; /*! * @function OSKextCreatePrelinkedKernel * @abstract Creates a prelinked kernel from a kernel file and all open kexts. * * @param kernelImage The kernel image to use. * @param kextArray * The kexts to include in the prelinked kernel. * Pass <code>NULL</code> to consult the running kernel * for kexts to include from those open; * the current architecture must match the runninng kernel's. * @param volumeRootURL * If non-<code>NULL</code>, kexts with this URL as a prefix * strip it when saving their paths in the prelinked kernel. * This allows creation of prelinked kernels from folders * other than /System/Library/Extensions. * @param flags * See @link OSKextKernelcacheFlags@/link. * @param symbolsOut * If non-<code>NULL</code> debug symbols for <code>kernelImage</code> * and all kexts included in the result are returned by reference. * * @result * A <code>CFData</code> object containing the prelinked kernel image based * on the running kernel. * Returns <code>NULL</code> if <code>needAllFlag</code> is <code>true</code> * and any kext fails to link. */ CF_EXPORT CFDataRef OSKextCreatePrelinkedKernel( CFDataRef kernelImage, CFArrayRef kextArray, CFURLRef volumeRootURL, uint32_t flags, CFDictionaryRef * symbolsOut) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA); __END_DECLS #endif /* __OSKEXT_H__ */