1/* 2 * Copyright (c) 2008, 2012 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28#ifndef __OSKEXT_H__ 29#define __OSKEXT_H__ 30 31#include <sys/cdefs.h> 32 33__BEGIN_DECLS 34 35#include <CoreFoundation/CoreFoundation.h> 36#include <System/libkern/OSReturn.h> 37#include <System/libkern/OSKextLib.h> 38#include <System/libkern/OSKextLibPrivate.h> 39#include <mach/mach.h> 40#include <mach-o/arch.h> 41 42// xxx - should I use "Clear" everywhere I use "Flush" 43 44/*! 45 * @header 46 * @ignore CF_EXPORT 47 * 48 * The OSKext library provides a comprehensive interface for creating, 49 * examining, and loading kernel extensions (kexts). 50 * 51 * <b>NOTICE:</b> This library is neither thread-safe nor garbage-collection 52 * safe. You must use your own locking with threads sharing access to OSKext. 53 * You can not use this library in an application with garbage collection. 54 */ 55 56#pragma mark Types and Constants 57/******************************************************************************* 58* Types and Constants 59*******************************************************************************/ 60 61/*! 62 * @typedef OSKextRef 63 * @abstract A reference to a kernel extension object. 64 * 65 * @discussion 66 * The OSKextRef type refers to a KXKext object, which represents a kernel 67 * extension bundle on disk, from an archive, or loaded into the kernel. 68 * OSKext is an opaque type that defines the characteristics and behavior of 69 * OSKext objects. 70 * 71 * The kernel counterpart of OSKext is the OSKext libkern C++ class. 72 */ 73typedef struct __OSKext * OSKextRef; 74 75#define kOSKextBundleExtension "kext" 76#define kOSKextMkextExtension "mkext" 77 78/*! 79 * @typedef OSKextDiagnosticsFlags 80 * @constant kOSKextDiagnosticsFlagAll 81 * @constant kOSKextDiagnosticsFlagValidation 82 * @constant kOSKextDiagnosticsFlagAuthentication 83 * @constant kOSKextDiagnosticsFlagDependencies 84 * @constant kOSKextDiagnosticsFlagWarnings 85 * @constant kOSKextDiagnosticsFlagBootLevel 86 */ 87enum { 88 kOSKextDiagnosticsFlagNone = (UInt32) 0x0U, 89 90 kOSKextDiagnosticsFlagValidation = (UInt32) 0x1U, 91 kOSKextDiagnosticsFlagAuthentication = (UInt32) 0x2U, 92 kOSKextDiagnosticsFlagDependencies = (UInt32) 0x4U, 93 kOSKextDiagnosticsFlagWarnings = (UInt32) 0x8U, 94 kOSKextDiagnosticsFlagBootLevel = (UInt32) 0x10U, 95 96 kOSKextDiagnosticsFlagAll = (UInt32)0xFFFFFFFFU, 97}; 98typedef UInt32 OSKextDiagnosticsFlags; 99 100/* notify(3) identifiers. 101 */ 102CF_EXPORT const char * kOSKextLoadNotification; 103CF_EXPORT const char * kOSKextUnloadNotification; 104 105/* Top-level keys for diagnostics dicts. See @link OSKextCopyDiagnostics@/link. 106 */ 107// xxx - not sure we need to include these, but it's convenient 108CF_EXPORT const CFStringRef kOSKextDiagnosticsValidationKey; 109CF_EXPORT const CFStringRef kOSKextDiagnosticsAuthenticationKey; 110CF_EXPORT const CFStringRef kOSKextDiagnosticsDependenciesKey; 111CF_EXPORT const CFStringRef kOSKextDiagnosticsWarningsKey; 112CF_EXPORT const CFStringRef kOSKextDiagnosticsBootLevelKey; 113 114#pragma mark Basic CF Functions 115/********************************************************************* 116* Basic CF Functions 117*********************************************************************/ 118 119/*! 120 * @function OSKextGetTypeID 121 * @abstract Returns the type identifier for the OSKext opaque type. 122 * 123 * @result The type identifier for the OSKext opaque type. 124 */ 125CF_EXPORT CFTypeID 126OSKextGetTypeID(void) 127 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 128 129#pragma mark Module Configuration 130/********************************************************************* 131* Module Configuration 132*********************************************************************/ 133 134/*! 135 * @function OSKextSetArchitecture 136 * @abstract Sets the architecture used for operations on kexts. 137 * 138 * @param anArch 139 * An <code>NXArchInfo</code> pointer with cputype/subtype or name set. 140 * Ownership remains with the caller. 141 * Pass <code>NULL</code> to set the architecture to taht of the running kernel. 142 * 143 * @result 144 * <code>true</code> if the architecture was set as desired, 145 * <code>false</code> if <code>anArch</code> was not found; 146 * if <code>false</code>, the architecture will now be that 147 * of the running kernel. 148 * xxx - should it just be left unchanged instead? 149 * 150 * @discussion 151 * The kext library uses this architecture for any architecture-specific 152 * operation, such as property lookups 153 * (see @link OSKextGetValueForInfoDictionaryKey@/link), 154 * dependency resolution, executable access during validation and linking. 155 * The kext architecture is initially that of the running kernel (not of 156 * the user-space process). 157 * 158 * This function looks up the system <code>NXArchInfo</code> struct 159 * for the struct passed in, first using the cputype/subtype, and if that fails, 160 * the name. You can therefore use this function to set the architecture 161 * from an architecture name alone by passing an <code>NXArchInfo</code> struct 162 * with the desired name, 163 * but the cputype/subtype set to CPU_TYPE_ANY and CPU_SUBTYPE_ANY. 164 * 165 * Changing the kext architecture causes all kexts to flush their load info 166 * and dependencies with @link OSKextFlushLoadInfo@/link. 167 */ 168// xxx - should this also have a flushDependenciesFlag? 169CF_EXPORT Boolean 170OSKextSetArchitecture(const NXArchInfo * archInfo) 171 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 172 173/*! 174 * @function OSKextGetArchitecture 175 * @abstract Gets the architecutre used for operations on kexts. 176 * 177 * @result 178 * The architecture used for operations on kexts. 179 * The caller does not own the returned pointer and should not free it. 180 * 181 * @discussion 182 * The kext library uses this architecture for any architecture-specific 183 * operation, such as property lookups 184 * (see @link OSKextGetValueForInfoDictionaryKey@/link), 185 * dependency resolution, executable access during validation and linking. 186 * The kext architecture is initially that of the running kernel (not of 187 * the user-space process). 188 */ 189CF_EXPORT const NXArchInfo * 190OSKextGetArchitecture(void) 191 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 192 193/*! 194 * @function OSKextGetRunningKernelArchitecture 195 * @abstract Returns the architecture of the running kernel. 196 * 197 * @result 198 * The architecture of the running kernel. 199 * The caller does not own the returned pointer and should not free it. 200 * 201 * @discussion 202 * This function consults the kernel task and returns a pointer to the 203 * <code>NXArchInfo</code> struct representing its architecture. 204 * The running kernel's architecture does not necessarily match that 205 * of user space tasks (for example, a 32-bit user space task could be 206 * running with a 64-bit kernel, or vice-versa). 207 */ 208CF_EXPORT const NXArchInfo * 209OSKextGetRunningKernelArchitecture(void) 210 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 211 212/*! 213 * @function OSKextSetLogFilter 214 * @abstract 215 * Set the logging filter for messages from the kext library 216 * or kernel. 217 * 218 * @param logFilter The log filter to set for user space. 219 * @param kernelFlag <code>true</code> to set the kernel filter, 220 * <code>false</code> to set the user filter. 221 * 222 * @discussion 223 * The default log flag set for both user and kernel space is 224 * <code>@link kOSKextLogWarningLevel@/link | 225 * @link kOSKextLogVerboseFlagsMask@/link</code>. 226 * Log messages are output through the log function set by 227 * @link OSKextSetLogOutputFunction@/link. 228 * 229 * To suppress messages from the kext library or kernel completely, 230 * set the log flags to code>@link kOSKextLogSilentFilter@/link</code>. 231 * Functions whose explicit purpose is to print output, 232 * such as @link OSKextPrintDiagnostics@/link, will still print. 233 */ 234CF_EXPORT void 235OSKextSetLogFilter( 236 OSKextLogSpec logFilter, 237 Boolean kernelFlag) 238 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 239 240/*! 241 * @function OSKextGetLogFilter 242 * @abstract Returns the logging filter for user or kernel space. 243 * 244 * @param kernelFlag <code>true</code> to get the kernel filter, 245 * <code>false</code> to get the user filter. 246 * 247 * @result 248 * The current log filter in effect. 249 * 250 * @discussion 251 * The default log flag set for both user and kernel space is 252 * <code>@link kOSKextLogWarningLevel@/link | 253 * @link kOSKextLogVerboseFlagsMask@/link</code>. 254 * Log messages are output through the log function set by 255 * @link OSKextSetLogOutputFunction@/link. 256 */ 257OSKextLogSpec OSKextGetLogFilter(Boolean kernelFlag) 258 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 259 260/*! 261 * @typedef OSKextLogOutputFunction 262 * @abstract 263 * Prototype of a callback function used to log messages from the library. 264 * 265 * @param msgLogSpec The log specification that triggered the log message. 266 * @param format A printf(3) style format string. 267 * 268 * @discussion 269 * The default log function simply prints to <code>stderr</code 270 * if <code>msgLogSpec</code> has any bits set. 271 * If you set the log function to <code>NULL</code>, 272 * no log messages will be printed. 273 * 274 * Log messages have no trailing newline, to accommodate system log facilities. 275 */ 276/* xxx - no CF_EXPORT, compiler dies */ 277typedef void (*OSKextLogOutputFunction)( 278 OSKextRef aKext, 279 OSKextLogSpec msgLogSpec, 280 const char * format, 281 ...); 282 283/*! 284 * @function OSKextSetLogOutputFunction 285 * @abstract Sets the function called to log messages. 286 * 287 * @param funct The log function to set. 288 * 289 * @discussion 290 * The default log function simply prints to stderr. If you set the 291 * log function to <code>NULL</code>, no log messages will be printed. 292 * 293 * Log messages have no trailing newline, to accommodate system log facilities. 294 */ 295CF_EXPORT void 296OSKextSetLogOutputFunction(OSKextLogOutputFunction func) 297 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 298 299/*! 300 * @function OSKextLog 301 * @abstract Log a message at a given level and with flags. 302 * 303 * @param aKext If not <code>NULL</code>, the OSKext object to which 304 * the log message applies. 305 * @param messageLogSpec The level and flags with which to log the message. 306 * @param format A printf-style format string to log, 307 * followed by optional arguments. 308 * 309 * @discussion 310 * Log messages are filtered based on <code>aKext</code>, 311 * <code>messageLogSpec</code>, and the current log filter as set by 312 * @link <code>OSKextSetLogFilter</code>@/link. 313 * 314 * Log messages have no trailing newline, to accommodate system log facilities. 315 */ 316CF_EXPORT void 317OSKextLog( 318 OSKextRef aKext, 319 OSKextLogSpec messageLogSpec, 320 const char * format, 321 ...) __attribute__((format(printf, 3, 4))) 322 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 323 324/*! 325 * @function OSKextVLog 326 * @abstract Log a message at a given level and with flags. 327 * 328 * @param aKext If not <code>NULL</code>, the OSKext object to which 329 * the log message applies. 330 * @param messageLogSpec The level and flags with which to log the message. 331 * @param format A printf-style format string to log. 332 * @param srcArgList The corresponding argument list for the format string. 333 * 334 * @discussion 335 * Log messages are filtered based on <code>aKext</code>, 336 * <code>messageLogSpec</code>, and the current log filter as set by 337 * @link <code>OSKextSetLogFilter</code>@/link. 338 * 339 * Log messages have no trailing newline, to accommodate system log facilities. 340 */ 341void OSKextVLog( 342 OSKextRef aKext, 343 OSKextLogSpec msgLogSpec, 344 const char * format, 345 va_list srcArgList) 346 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 347 348/*! 349 * @function OSKextLogCFString 350 * @abstract Log a message at a given level and with flags. 351 * 352 * @param aKext If not <code>NULL</code>, the OSKext object to which 353 * the log message applies. 354 * @param messageLogSpec The level and flags with which to log the message. 355 * @param format A printf-style format CFString to log, 356 * followed by optional arguments. 357 * 358 * @discussion 359 * Log messages are filtered based on <code>aKext</code>, 360 * <code>messageLogSpec</code>, and the current log filter as set by 361 * @link <code>OSKextSetLogFilter</code>@/link. 362 * 363 * Log messages have no trailing newline, to accommodate system log facilities. 364 */ 365CF_EXPORT void 366OSKextLogCFString( 367 OSKextRef aKext, 368 OSKextLogSpec messageLogSpec, 369 CFStringRef format, 370 ...) CF_FORMAT_FUNCTION(3,4) 371 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 372 373/*! 374 * @function OSKextVLog 375 * @abstract Log a message at a given level and with flags. 376 * 377 * @param aKext If not <code>NULL</code>, the OSKext object to which 378 * the log message applies. 379 * @param messageLogSpec The level and flags with which to log the message. 380 * @param format A printf-style format string to log. 381 * @param srcArgList The corresponding argument list for the format string. 382 * 383 * @discussion 384 * Log messages are filtered based on <code>aKext</code>, 385 * <code>messageLogSpec</code>, and the current log filter as set by 386 * @link <code>OSKextSetLogFilter</code>@/link. 387 * 388 * Log messages have no trailing newline, to accommodate system log facilities. 389 */ 390void OSKextVLogCFString( 391 OSKextRef aKext, 392 OSKextLogSpec msgLogSpec, 393 CFStringRef format, 394 va_list srcArgList) 395 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 396 397/*! 398 * @function OSKextSetSimulatedSafeBoot 399 * @abstract Sets whether safe boot mode is simulated in the library. 400 * 401 * @param flag <code>true</code> to simulate safe boot mode, 402 * <code>false</code> to not simulate. 403 * 404 * @discussion 405 * Kexts without a valid OSBundleRequired property are not allowed to load 406 * by the kernel when the system has started in safe boot mode. 407 * If you turn on simulated safe boot, the kext library can 408 * catch non-loadable kexts and present appropriate diagnostics. 409 */ 410CF_EXPORT void 411OSKextSetSimulatedSafeBoot(Boolean flag) 412 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 413 414/*! 415 * @function OSKextGetSimulatedSafeBoot 416 * @abstract Returns whether safe boot mode is simulated in the library. 417 * 418 * @result 419 * <code>true</code> if safe boot mode is being simulated, 420 * <code>false</code> if not. 421 * 422 * @discussion 423 * Kexts without a valid OSBundleRequired property are not allowed to load 424 * by the kernel when the system has started in safe boot mode. 425 * When simulated safe boot is on, the kext library can 426 * catch non-loadable kexts and present appropriate diagnostics. 427 */ 428CF_EXPORT Boolean 429OSKextGetSimulatedSafeBoot(void) 430 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 431 432/*! 433 * @function OSKextGetActualSafeBoot 434 * @abstract Returns whether safe boot mode is active. 435 * 436 * @result 437 * <code>true</code> if safe boot mode is active, 438 * <code>false</code> if not. 439 * 440 * @discussion 441 * Kexts without a valid OSBundleRequired property are not allowed to load 442 * by the kernel when the system has started in safe boot mode. 443 * The kext library ignores actual safe boot mode, leaving decisions 444 * regarding safe boot to the kernel. 445 * If you want to analyze kexts in safe boot mode using the library, 446 * call @link OSKextSetSimulatedSafeBoot@/link. 447 */ 448// xxx - we used to disallow kexts w/debug-log flags in safe boot, too 449CF_EXPORT Boolean 450OSKextGetActualSafeBoot(void) 451 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 452 453/*! 454 * @function OSKextGetSystemExtensionsFolderURLs 455 * @abstract Returns the standard system extension folder URLs. 456 * 457 * @result 458 * An array containing the standard system extension folder URLs. 459 * Ownership follows the 460 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 461 * 462 * @discussion 463 * To open all the kexts normally considered for loading by the system, 464 * pass the return value of this function to 465 * @link OSKextCreateKextsFromURLs@/link. 466 */ 467CF_EXPORT CFArrayRef 468OSKextGetSystemExtensionsFolderURLs(void) 469 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 470 471/*! 472 * @function OSKextSetRecordsDiagnostics 473 * @abstract Sets whether kexts record diagnostic information. 474 * 475 * @param flags Indicates which diagnostics to record. 476 * 477 * @discussion 478 * The kext library can record diagnostic information for kexts as 479 * problems are encountered. These diagnostics can consume a fair 480 * amount of memory, and should be generated only when desired. 481 * Recording of diagnostics is set to 482 * @link kOSKextDiagnosticsFlagNone@/link by default. 483 * Use this function to turn diagnostics recording off (or back on) 484 * for particular diagnostic types. 485 * 486 * Turning on diagnostics does not calculate or recalculate 487 * diagnostics. Call the various functions that operate on kexts 488 * to begin accumulating diagnostics. 489 * 490 * Turning diagnostics off does not clear any existing diagnostics. 491 * Use @link OSKextFlushDiagnostics@/link explicitly to clear 492 * any diagnostics currently stored. 493 * 494 * See also @link OSKextCopyDiagnostics@/link, 495 * @link OSKextValidate@/link, 496 * @link OSKextAuthenticate@/link, and 497 * @link OSKextResolveDependencies@/link. 498 */ 499// Could list a pile of see also's here.... 500CF_EXPORT void 501OSKextSetRecordsDiagnostics(OSKextDiagnosticsFlags flags) 502 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 503 504/*! 505 * @function OSKextGetRecordsDiagnostics 506 * @abstract 507 * Returns what kinds of diagnostic information kexts record. 508 * 509 * @result 510 * Flags indicating which types of diagnostics are currently 511 * being recorded. You can bitwise-OR or -AND these with other flags 512 * to add or remove diagnostics being recorded with 513 * @link OSKextSetRecordsDiagnostics@/link. 514 */ 515CF_EXPORT OSKextDiagnosticsFlags 516OSKextGetRecordsDiagnostics(void) 517 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 518 519 520/*! 521 * @function OSKextSetUsesCaches 522 * @abstract Sets whether the kext library uses cache files. 523 * 524 * @param flag 525 * <code>true</code> to use caches, 526 * <code>false</code> to not use caches. 527 * 528 * @discussion 529 * The kext library normally uses caches to speed up reading kexts from 530 * the system extensions folders. 531 * Use this function to turn off use of caches; this will cause reading 532 * of kexts to be dramatically slower. 533 * 534 * See also @link OSKextGetUsesCaches@/link. 535 */ 536CF_EXPORT void 537OSKextSetUsesCaches(Boolean flag) 538 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 539 540/*! 541 * @function OSKextGetUsesCaches 542 * @abstract 543 * Returns whether the OSKext library uses cache files. 544 * 545 * @result 546 * <code>true</code> if the library uses caches to speed up reading of kexts, 547 * <code>false</code> if it doesn't. 548 * 549 * @discussion 550 * The kext library normally uses caches to speed up reading kexts from 551 * the system extensions folders. 552 * Use this function to check whether the library is using caches. 553 * 554 * See also @link OSKextGetUsesCaches@/link. 555 */ 556CF_EXPORT Boolean 557OSKextGetUsesCaches(void) 558 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 559 560#pragma mark Instance Management 561/********************************************************************* 562* Instance Management 563*********************************************************************/ 564 565/*! 566 * @function OSKextCreate 567 * @abstract Read a single kext from an on-disk bundle, without plugins. 568 * 569 * @param allocator 570 * The allocator to use to allocate memory for the new object. 571 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 572 * to use the current default allocator. 573 * @param anURL 574 * The location of the bundle for which to create an OSKext object. 575 * @result 576 * An OSKext object created from the bundle at anURL. 577 * Ownership follows the 578 * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. 579 * 580 * Returns <code>NULL</code> if there was a memory allocation problem or 581 * if the bundle doesn't exist at anURL (see Discussion). 582 * May return an existing OSKext object with the reference count incremented. 583 * 584 * @discussion 585 * Once a kext has been created, it is cached in memory; the kext bundle cache 586 * is flushed only periodically. OSKextCreate does not check that a cached kext 587 * bundle still exists in the filesystem. If a kext bundle is deleted 588 * from the filesystem, it is therefore possible for OSKextCreate 589 * to return a cached bundle that has actually been deleted. 590 * 591 * OSKext uses a CFBundle briefly during initialization, but in order 592 * to save memory and allow re-reading of kext bundle contents 593 * from disk, does not retain it. Applications can save further memory 594 * by flushing info dictionaries so that they are read from disk again 595 * when needed; see @link OSKextFlushInfoDictionary@/link. 596 */ 597CF_EXPORT OSKextRef 598OSKextCreate( 599 CFAllocatorRef allocator, 600 CFURLRef anURL) 601 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 602 603/*! 604 * @function OSKextCreateKextsFromURL 605 * @abstract Reads all kexts at an on-disk URL along with their plugins. 606 * 607 * @param allocator 608 * The allocator to use to allocate memory for the new objects. 609 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 610 * to use the current default allocator. 611 * @param anURL The URL to scan for kernel extensions. 612 * @result 613 * Returns an array containing the kext objects created, 614 * or <code>NULL</code> on failure. 615 * 616 * @discussion 617 * This function scans <code>anURL</code> for kexts. 618 * If <code>anURL</code> represents a kext, 619 * this function reads that kext and its plugins. 620 * If <code>anURL</code> represents a non-kext directory, 621 * this functions scans the directory's immediate contents for kext bundles 622 * and their plugins. It does not scan recursively; only plugins one level 623 * deep are read. 624 * 625 * If given an URL for a kext that is a plugin of another kext, this 626 * function does not scan for further plugins. 627 * 628 * This function does not scan for or read mkext files. Use 629 * @link OSKextCreateKextsFromMkextFile@/link to read an mkext file. 630 * 631 * See @link OSKextCreate OSKextCreate @/link for information 632 * about kext object caching. 633 */ 634CFArrayRef OSKextCreateKextsFromURL( 635 CFAllocatorRef allocator, 636 CFURLRef anURL) 637 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 638 639/*! 640 * @function OSKextCreateKextsFromURLs 641 * @abstract Reads all kexts at an array on-disk URLs along with their plugins. 642 * 643 * @param allocator 644 * The allocator to use to allocate memory for the new objects. 645 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 646 * to use the current default allocator. 647 * @param arrayOfURLs The URLs to scan for kernel extensions. 648 * @result 649 * Returns an array containing the kext objects created, 650 * or <code>NULL</code> on failure. 651 * 652 * @discussion 653 * This function scans each URL in <code>arrayOfURLs</code> for kexts. 654 * If a given URL represents a kext, 655 * this function reads that kext and its plugins. 656 * If the URL represents a non-kext directory, this functions scans the 657 * directory's immediate contents for kext bundles and their plugins. 658 * It does not scan recursively; only plugins one level deep are read. 659 * 660 * If given an URL for a kext that is a plugin of another kext, this 661 * function does not scan for further plugins. 662 * 663 * This function does not scan for or read mkext files. Use 664 * @link OSKextCreateKextsFromMkextFile@/link to read an mkext file. 665 * 666 * See @link OSKextCreate@/link for discussion about kext object caching. 667 */ 668CF_EXPORT CFArrayRef 669OSKextCreateKextsFromURLs( 670 CFAllocatorRef allocator, 671 CFArrayRef arrayOfURLs) 672 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 673 674/*! 675 * @function OSKextCreateWithIdentifier 676 * @abstract Search for and create a kext given its bundle identifier. 677 * 678 * @param allocator 679 * The allocator to use to allocate memory for the new object. 680 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 681 * to use the current default allocator. 682 * @param kextIdentifier 683 * The bundle identifier for which to create a OSKext object. 684 * @result 685 * A OSKext object with the requested bundle identifier, 686 * created according to the search described below. 687 * Ownership follows the 688 * @link //apple_ref/doc/uid/20001148-103029 Create Rule @/link. 689 * 690 * Returns <code>NULL</code> if there was a memory allocation problem, 691 * if no bundle can be found for <code>kextIdentifier</code>, 692 * or if the bundle found can't be opened (see Discussion). 693 * May return an existing OSKext object with the reference count incremented. 694 * 695 * @discussion 696 * This function searches the system to create a kext 697 * for <code>kextIdentifier</code>. 698 * It first consults the kernel to get the path for a loaded kext 699 * with that identifier. 700 * If a kext bundle exists at that path and its identifier and version 701 * match what's loaded in the kernel, a kext object for that bundle is returned. 702 * Failing that, this function falls back to searching the directories 703 * provided by 704 * <code>@link OSKextGetSystemExtensionsFolderURLs OSKextGetSystemExtensionsFolderURLs@/link, 705 * attempting to match a loaded kext's identifier and version, 706 * and finally falling back to an identifier match only. 707 * 708 * The returned kext will have its load info set as if 709 * <code>@link OSKextReadLoadedKextInfo OSKextReadLoadedKextInfo@/link 710 * had been called (but other kexts are not affected). 711 * You can use functions such as 712 * <code>@link OSKextIsLoaded OSKextIsLoaded@/link</code> 713 * to check whether the kext created is loaded in the kernel. 714 * 715 * See @link OSKextCreate OSKextCreate @/link for information 716 * about kext object caching. 717 */ 718CF_EXPORT OSKextRef 719OSKextCreateWithIdentifier( 720 CFAllocatorRef allocator, 721 CFStringRef kextIdentifier) 722 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 723 724/*! 725 * @function OSKextGetAllKexts 726 * @abstract 727 * Returns an array containing all of the kexts currently open in the application. 728 * 729 * @result 730 * A CFArray object containing OSKext objects for each open kext 731 * in the application. Ownership follows the 732 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 733 * 734 * @discussion 735 * This function is potentially expensive, so use with care. 736 */ 737CF_EXPORT CFArrayRef 738OSKextGetAllKexts(void) 739 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 740 741/*! 742 * @function OSKextGetKextWithURL 743 * @abstract Locate an opened kext given its URL. 744 * 745 * @param anURL 746 * The URL of the opened kext to locate. 747 748 * @result 749 * An OSKext object, or <code>NULL</code> if the kext was not found 750 * (either because it has not been opened or it failed to open). 751 * Ownership follows the 752 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 753 * 754 * @discussion 755 * For a kext to be located by this function, 756 * the kext object must have already been created. 757 * This function allows you to check quickly for a kext without actually 758 * attempting to open it. 759*/ 760CF_EXPORT OSKextRef 761OSKextGetKextWithURL( 762 CFURLRef anURL) 763 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 764 765/*! 766 * @function OSKextGetKextWithIdentifier 767 * @abstract Locate a kext given its program-defined identifier. 768 * 769 * @param aBundleID 770 * The identifier of the kext to locate. 771 * Note that identifier names are case-sensitive. 772 * @result 773 * An OSKext object, or <code>NULL</code> if the kext was not found. 774 * Ownership follows the 775 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 776 * 777 * @discussion 778 * For a kext to be located using its identifier, 779 * the kext object must have already been created. 780 * The principal intended purpose for locating kexts by identifier 781 * is resolving dependencies between kexts. 782 * If a kext is created, then the kext bundle is deleted from the filesystem 783 * and this function invoked afterwards, it will still return the original kext. 784 * 785 * If multiple kexts with the same identifier exist in the application 786 * created from distinct kext bundles, this function returns the kext 787 * with the greatest version. If multiple kexts with the same identifier 788 * and version exist, this function returns the last such kext created. 789 * 790 * Kext identifiers are created by entering a value for the key 791 * CFBundleIdentifier in the kext bundle's Info.plist file. 792 * 793 * To guarantee uniqueness, identifiers take the form 794 * of Java style package names, such as com.myCompany.foo.bar. 795 */ 796// xxx - check on same-version ordering with folks 797CF_EXPORT OSKextRef 798OSKextGetKextWithIdentifier( 799 CFStringRef aBundleID) 800 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 801 802/*! 803 * @function OSKextCopyKextsWithIdentifiers 804 * @abstract 805 * Locate a list of kexts given their program-defined identifiers. 806 * 807 * @param bundleIDs 808 * The array of identifiers of the kexts to locate. 809 * Note that identifier names are case-sensitive. 810 * @result 811 * An array of OSKext objects, or <code>NULL</code> 812 * if an allocation error occurs. 813 * Ownership follows the 814 * @link //apple_ref/doc/uid/20001148-SW1 Create Rule@/link. 815 * 816 * @discussion 817 * See @link OSKextGetKextWithIdentifier@/link for general information 818 * on looking up kexts by identifier. 819 */ 820CF_EXPORT CFMutableArrayRef 821OSKextCopyKextsWithIdentifiers( 822 CFArrayRef bundleIDs) 823 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 824 825/*! 826 * @function OSKextGetKextWithIdentifierAndVersion 827 * @abstract 828 * Locate a kext given its program-defined identifier and version. 829 * 830 * @param aBundleID 831 * The identifier of the kext to locate. 832 * Note that identifier names are case-sensitive. 833 * @param aVersion 834 * The version of the kext to locate. 835 * @result 836 * An OSKext object, or <code>NULL</code> if the kext was not found. 837 * Ownership follows the 838 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 839 * 840 * @discussion 841 * For a kext to be located using its identifier and version, 842 * the kext object must have already been created. 843 * See @link OSKextGetKextWithIdentifierAndVersion@/link for more. 844 */ 845// xxx - check on same-version ordering with folks 846CF_EXPORT OSKextRef 847OSKextGetKextWithIdentifierAndVersion( 848 CFStringRef aBundleID, OSKextVersion aVersion) 849 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 850 851/*! 852 * @function OSKextGetKextsWithIdentifier 853 * @abstract Locate all kexts with a given program-defined identifier. 854 * 855 * @param aBundleID 856 * The identifier of the kext to locate. 857 * Note that identifier names are case-sensitive. 858 * @result 859 * An CFArray of kext objects with the given identifier, 860 * or <code>NULL</code> on error. 861 * Ownership follows the 862 * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. 863 * 864 * @discussion 865 * This function is useful for locating duplicates of a given kext. 866 * 867 * See @link OSKextGetKextWithIdentifier@/link for general information 868 * on looking up kexts by identifier. 869 */ 870CF_EXPORT CFArrayRef 871OSKextCopyKextsWithIdentifier( 872 CFStringRef aBundleID) 873 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 874 875/*! 876 * @function OSKextGetLoadedKextWithIdentifier 877 * @abstract 878 * Locate the loaded kext with a given program-defined identifier. 879 * 880 * @param aBundleID 881 * The identifier of the kext to locate. 882 * Note that identifier names are case-sensitive. 883 * @result 884 * An OSKext object, or <code>NULL</code> if the kext was not found. 885 * Ownership follows the 886 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 887 * 888 * @discussion 889 * You must call @link OSKextReadLoadedKextInfo@/link before calling this 890 * function for it to find anything. 891 * 892 * See @link OSKextGetKextWithIdentifier@/link for general information 893 * on looking up kexts by identifier. 894 */ 895CF_EXPORT OSKextRef 896OSKextGetLoadedKextWithIdentifier( 897 CFStringRef aBundleID) 898 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 899 900/*! 901 * @function OSKextGetCompatibleKextWithIdentifier 902 * @abstract 903 * Locate the kext with a given program-defined identifier 904 * that is compatible with a requested version. 905 * 906 * @param aBundleID 907 * The identifier of the kext to locate. 908 * Note that identifier names are case-sensitive. 909 * @param requestedVersion 910 * The version that the kext must be compatible with. 911 * @result 912 * An OSKext object, or <code>NULL</code> if the kext was not found. 913 * Ownership follows the 914 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 915 * 916 * @discussion 917 * A kext is compatible with a version if that version lies between 918 * its CFBundleVersion and its OSBundleCompatibleVersion (inclusive). 919 * 920 * See @link OSKextGetKextWithIdentifier@/link for general information 921 * on looking up kexts by identifier. 922 */ 923CF_EXPORT OSKextRef 924OSKextGetCompatibleKextWithIdentifier( 925 CFStringRef aBundleID, 926 OSKextVersion requestedVersion) 927 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 928 929#pragma mark Basic Accessors 930/********************************************************************* 931* Basic Accessors 932*********************************************************************/ 933 934/*! 935 * @function OSKextGetURL 936 * @abstract Returns the CFURL of a kext bundle. 937 * 938 * @param aKext The kext to get the URL for. 939 * @result A CFURL object. Ownership follows the 940 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 941 * 942 * @discussion 943 * This function returns the CFURL that <code>aKext</code> 944 * was originally created with. 945 * It should be resolved to its base for comparison with other kext 946 * URLs. 947 */ 948CF_EXPORT CFURLRef 949OSKextGetURL(OSKextRef aKext) 950 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); // always absolute 951 952/*! 953 * @function OSKextGetIdentifier 954 * @abstract Returns the bundle identifier from a kext's information property list. 955 * 956 * @param aKext The kext to get the identifier for. 957 * @result 958 * A CFString object containing the kext bundle's identifier, 959 * or <code>NULL</code> if none was specified in the information property list. 960 * Ownership follows the 961 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 962 */ 963CF_EXPORT CFStringRef 964OSKextGetIdentifier(OSKextRef aKext) 965 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 966 967/*! 968 * @function OSKextGetValueForInfoDictionaryKey 969 * @abstract 970 * Returns a (possibly architecture-specific) value 971 * in a kext's information dictionary. 972 * 973 * @param aKext The kext to get the property for. 974 * @param key The base key identifying the property. 975 * @result 976 * A value corresponding to <code>key</code> in <code>aKext</code>'s 977 * information dictionary. 978 * If available, an architecture-specific value is returned, 979 * otherwise the global value is returned. Ownership follows the 980 * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. 981 * 982 * @discussion 983 * This function first looks for a property value specific to the current kext 984 * architecture, as set with @link OSKextSetArchitecture@/link, 985 * by appending an underscore plus the architecture name to the base key. 986 * If such a value is not found, it looks for the property using the base key. 987 * For example, if the currently set architecture is i386, and 988 * IOKitPersonalities is requested, this function looks up the key 989 * IOKitPersonalities_i386; if that doesn't exist, then it uses 990 * IOKitPersonalities. 991 * 992 * Some properties are not allowed to be made architecture-specific; 993 * if such keys are defined, they are ignored by this function: 994 * 995 * * CFBundleIdentifier 996 * * CFBundleVersion 997 * * CFBundleExecutable 998 * * OSBundleIsInterface 999 * * OSKernelResource 1000 * 1001 * This function looks up architecture-specific values for generic bundle 1002 * properties, such as CFBundlePackageType, but such values are of course 1003 * ignored by CFBundle. 1004 * 1005 * If you want to look up a property with a raw key, get the information 1006 * dictionary directly using @link OSKextCopyInfoDictionary@/link or 1007 * by opening a CFBundle for the kext's URL. 1008 * 1009 * This function reads the info dictionary from disk if necessary. 1010 * See @link OSKextFlushInfoDictionary@/link. 1011 */ 1012CF_EXPORT CFTypeRef 1013OSKextGetValueForInfoDictionaryKey( 1014 OSKextRef aKext, 1015 CFStringRef key) 1016 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1017 1018/*! 1019 * @function OSKextCopyInfoDictionary 1020 * @abstract Returns a copy of a kext's information dictionary. 1021 * 1022 * @param aKext The kext to get the information dictionary for. 1023 * @result 1024 * A CFDictionary object containing the data stored in the kext's 1025 * information property list. 1026 * OSKext may add extra keys to this dictionary for its own use. 1027 * Ownership follows the 1028 * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. 1029 * 1030 * @discussion 1031 * This function uses @link IOCFUnserialize@/link to parse the XML 1032 * of the info dictionary, in order to match the parsing used in the kernel. 1033 */ 1034CF_EXPORT CFMutableDictionaryRef 1035OSKextCopyInfoDictionary(OSKextRef aKext) 1036 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1037 1038/*! 1039 * @function OSKextFlushInfoDictionary 1040 * @abstract Releases a kext's info dictionary. 1041 * 1042 * @param aKext The kext that should release its info dictionary. 1043 * If <code>NULL</code>, all open kexts' info dictionaries 1044 * are flushed. 1045 * 1046 * @discussion 1047 * OSKexts accumulate a fair amount of information as they are created 1048 * and used; when many kext objects are created the total memory 1049 * consumption can be significant. If an application won't be using 1050 * kexts for long periods of time, it can flush this information 1051 * to save memory; the information will later be re-read from disk 1052 * or recreated as necessary. 1053 * 1054 * Flushing info dictionaries also allows kext objects to synchronize 1055 * with updates on disk; they will automatically re-sort in the 1056 * internal lookup tables to reflect changed versions, for example. 1057 * (xxx - well they will! that's not fully implemented yet) 1058 * 1059 * See also @link OSKextFlushDependencies@/link, 1060 * @link OSKextFlushLoadInfo@/link, 1061 * and @link OSKextFlushDiagnostics@/link. 1062 * 1063 * Kext objects created from an mkext cannot flush their info 1064 * dictionaries. 1065 */ 1066CF_EXPORT void 1067OSKextFlushInfoDictionary(OSKextRef aKext) 1068 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1069 1070/*! 1071 * @function OSKextGetVersion 1072 * @abstract Returns the version of a kext. 1073 * 1074 * @param aKext The kext to get the version for. 1075 * @result The version of the kext as a 64-bit integer. 1076 * 1077 * @discussion 1078 * xxx - needs more info on version format 1079 * xxx - need to fix definition of OSKextVersion. 1080 */ 1081CF_EXPORT OSKextVersion 1082OSKextGetVersion(OSKextRef aKext) 1083 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1084 1085/*! 1086 * @function OSKextGetCompatibleVersion 1087 * @abstract Returns the compatible version of a kext 1088 * 1089 * @param aKext The kext to get the compatible version for. 1090 * @result The compatible version of the kext as a 64-bit integer. 1091 * 1092 * @discussion 1093 * This function returns the value of a kext's OSBundleCompatibleVersion 1094 * property, parsed into a 64-bit integer that can be compared using 1095 * standard integer comparison operators. 1096 * 1097 * xxx - needs more info on version format, ref to tn: http://developer.apple.com/technotes/tn/tn1132.html 1098 */ 1099CF_EXPORT OSKextVersion 1100OSKextGetCompatibleVersion(OSKextRef aKext) 1101 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1102 1103/*! 1104 * @function OSKextCopyUUIDForArchitecture 1105 * @abstract 1106 * Returns the compiler-generated UUID of a kext for a given architecture. 1107 * 1108 * @param aKext The kext to get the UUID for. 1109 * @param anArch The architecture desired. 1110 * Pass <code>NULL</code> to get the UUID for the 1111 * current architecture. 1112 * @result 1113 * A CFData object containing the UUID of the kext's executable 1114 * for <code>anArch</code>, or the currently set architecture if 1115 * <code>anArch</code> is <code>NULL</code>. 1116 * 1117 * @discussion 1118 * UUIDs are used in addition to bundle versions to check the identify of 1119 * kexts loaded in the kernel. 1120 */ 1121CF_EXPORT CFDataRef 1122OSKextCopyUUIDForArchitecture(OSKextRef aKext, 1123 const NXArchInfo * anArch) 1124 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1125 1126/*! 1127 * @function OSKextIsKernelComponent 1128 * @abstract Returns whether a kext represents a kerne programming interface. 1129 * 1130 * @param aKext The kext to examine. 1131 * @result 1132 * <code>true</code> if <code>aKext</code> represents 1133 * a kerne programming interface, <code>false</code> otherwise. 1134 * 1135 * @discussion 1136 * A small set of kexts represent interfaces built into the kernel that can 1137 * be linked against individually. These are commonly known as 1138 * kernel programming interfaces (KPIs), 1139 * and the kexts containing them as "pseudokexts". 1140 * 1141 * If a kext is a kernel component, then it is also always an interface 1142 * (see @link OSKextIsInterface@/link). 1143 */ 1144CF_EXPORT Boolean 1145OSKextIsKernelComponent(OSKextRef aKext) 1146 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1147 1148/*! 1149 * @function OSKextIsInterface 1150 * @abstract 1151 * Returns whether a kext acts as a linkage subset for another kext, 1152 * also known as a symbol set. 1153 * 1154 * @param aKext The kext to examine. 1155 * @result 1156 * <code>true</code> if <code>aKext</code> is an interface kext, 1157 * <code>false</code> otherwise. 1158 * 1159 * @discussion 1160 * An interface kext has no actual code in its executable, but merely 1161 * re-exports a set of symbols (typically a subset) 1162 * from those of its dependencies. 1163 * 1164 * Currently the only interface kexts are the kernel component kexts 1165 * the define the kernel programming interfaces for Mac OS X. 1166 */ 1167CF_EXPORT Boolean 1168OSKextIsInterface(OSKextRef aKext) 1169 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1170 1171/*! 1172 * @function OSKextIsLibrary 1173 * @abstract Returns whether a kext can be declared as a library. 1174 * 1175 * @param aKext The kext to examine. 1176 * @result 1177 * <code>true</code> if <code>aKext</code> is a library kext, <code>false</code> 1178 * otherwise. 1179 * 1180 * @discussion 1181 * A kext is a library kext if it has a valid OSBundleCompatibleVersion 1182 * property. Another kext can link against a library kext by listing 1183 * the library's identifier and required version in its OSBundleLibraries 1184 * property. 1185 */ 1186CF_EXPORT Boolean 1187OSKextIsLibrary(OSKextRef aKext) 1188 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1189 1190/*! 1191 * @function OSKextDeclaresExecutable 1192 * @abstract Returns whether a kext declares a CFBundleExecutable property. 1193 * 1194 * @param aKext The kext to examine. 1195 * @result 1196 * <code>true</code> if <code>aKext</code> has a nonempty CFBundleExecutable 1197 * property, <code>false</code> otherwise. 1198 * 1199 * @discussion 1200 * A kext with an executable is either a loadable kext with actual executable 1201 * code, or an interface kext whose executable serves to restrict linkage 1202 * to a subset of the symbols of another kext. See @link OSKextIsInterface@/link 1203 * for more on the latter type. 1204 */ 1205CF_EXPORT Boolean 1206OSKextDeclaresExecutable(OSKextRef aKext) 1207 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1208 1209/*! 1210 * @function OSKextHasLogOrDebugFlags 1211 * @abstract 1212 * Returns whether a kext has OSBundleEnableKextLogging set to a true value or 1213 * any of its IOKitPersonalities has a nonzero IOKitDebug property. 1214 * 1215 * @param aKext The kext to examine. 1216 * @result 1217 * <code>true</code> if <code>aKext</code> has a true OSBundleEnableKextLogging 1218 * property or if any personality for the currently set architecture has a 1219 * nonzero IOKitDebug property, <code>false</code> otherwise. 1220 * 1221 * @discussion 1222 * Kexts built for distribution should not have any logging or debug flags set. 1223 */ 1224CF_EXPORT Boolean 1225OSKextHasLogOrDebugFlags(OSKextRef aKext) 1226 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1227 1228/*! 1229 * @function OSKextIsLoggingEnabled 1230 * @abstract Returns whether a kext is included in more verbose logging. 1231 * 1232 * @param aKext The kext to examine. 1233 * @result 1234 * <code>true</code> if <code>aKext</code> will be included in more 1235 * verbose logging, <code>false</code> if not. 1236 * 1237 * @discussion 1238 * Normally log messages about kexts are not logged above the basic level 1239 * (<code>@link OSKextLogSpec@/link</code>). 1240 * If this property is set on a kext, then such messages will be logged. 1241 * A kext can set this in its info dictionary with the 1242 * @link OSBundleEnableKextLogging@/link property. 1243 */ 1244CF_EXPORT Boolean 1245OSKextIsLoggingEnabled(OSKextRef aKext) 1246 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1247 1248/*! 1249 * @function OSKextIsLoggingEnabled 1250 * @abstract Sets whether a kext is included in more verbose logging. 1251 * 1252 * @param aKext The kext to examine. 1253 * @param flag <code>true</code> to enable verbose kext logging, 1254 * <code>false</code> to disable. 1255 * 1256 * @discussion 1257 * Normally log messages about kexts are not logged above the basic level 1258 * (<code>@link OSKextLogSpec@/link</code>). 1259 * If this property is set on a kext, then such messages will be logged. 1260 * 1261 * A kext can set this in its info dictionary with the 1262 * @link OSBundleEnableKextLogging@/link property. 1263 * This property is one of the few that can be changed at run time. 1264 */ 1265CF_EXPORT void 1266OSKextSetLoggingEnabled( 1267 OSKextRef aKext, 1268 Boolean flag) 1269 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1270 1271/*! 1272 * @function OSKextIsLoadableInSafeBoot 1273 * @abstract Returns whether the kernel will load a kext during safe boot. 1274 * 1275 * @param aKext The kext to examine. 1276 * @result 1277 * <code>true</code> if the kernel will allow <code>aKext</code> during 1278 * safe boot, <code>false</code> otherwise. 1279 * 1280 * @discussion 1281 * A kext is loadable during safe boot if it has an OSBundleRequired 1282 * property for the kernel's architecture with a value of 1283 * "Root", "Local-Root", "Network-Root", "Console", or "Safe Boot". 1284 * 1285 * This function does not generally cover the issue of loadability due 1286 * to problems with validation, authentication, or dependency resolution. 1287 * To determine whether a kext can actually be loaded, use 1288 * @link OSKextIsLoadable@/link. 1289 */ 1290CF_EXPORT Boolean 1291OSKextIsLoadableInSafeBoot(OSKextRef aKext) 1292 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1293 1294/*! 1295 * @function OSKextDependenciesAreLoadableInSafeBoot 1296 * @abstract 1297 * Returns whether the kernel will load all of a kext's dependencies 1298 * during safe boot. 1299 * 1300 * @param aKext The kext whose dependencies to examine. 1301 * @result 1302 * <code>true</code> if the kernel will allow <code>aKext</code>'s dependencies 1303 * during safe boot, <code>false</code> otherwise. 1304 * 1305 * @discussion 1306 * A kext is loadable during safe boot if it has an OSBundleRequired 1307 * property for the kernel's architecture with a value of 1308 * "Root", "Local-Root", "Network-Root", "Console", or "Safe Boot". 1309 * 1310 * This function does not generally cover the issue of loadability due 1311 * to problems with validation, authentication, or dependency resolution. 1312 * To determine whether a kext can actually be loaded, use 1313 * @link OSKextIsLoadable@/link. 1314 */ 1315CF_EXPORT Boolean 1316OSKextDependenciesAreLoadableInSafeBoot(OSKextRef aKext) 1317 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 1318 1319/*! 1320 * @function OSKextCopyArchitectures 1321 * @abstract 1322 * Returns a list of <code>NXArchInfo</code> structs for the architectures 1323 * found in a kext's executable. 1324 * 1325 * @param aKext The kext to examine. 1326 * @result 1327 * A <code>NULL</code>-terminated list of <code>NXArchInfo</code> 1328 * struct pointers describing 1329 * the architectures supported by <code>aKext</code>, 1330 * or <code>NULL</code> if <code>aKext</code> has no executable. 1331 * The caller is responsible for freeing the list, but not the individual 1332 * <code>NXArchInfo</code> pointers. 1333 */ 1334CF_EXPORT const NXArchInfo ** 1335OSKextCopyArchitectures(OSKextRef aKext) 1336 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1337 1338/*! 1339 * @function OSKextSupportsArchitecture 1340 * @abstract Returns whether a kext has an executable for a given architecture. 1341 * 1342 * @param aKext The kext to examine. 1343 * @param anArch The <code>NXArchInfo</code> description to check. 1344 * If <code>NULL</code>, uses the currently set architecture. 1345 * @result 1346 * <code>true</code> if <code>aKext</code>'s executable contains code for 1347 * <code>anArch</code>. 1348 * 1349 * @discussion 1350 */ 1351// null for current (NOT host) arch 1352Boolean OSKextSupportsArchitecture(OSKextRef aKext, 1353 const NXArchInfo * anArch) 1354__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); // if NULL, uses current default 1355 1356/*! 1357 * @function OSKextCopyPlugins 1358 * @abstract Retrieve the plugins of a kext. 1359 * 1360 * @param aKext The kext to get plugins for. 1361 * @result 1362 * An array containing the kexts that are plugins of <code>aKext</code>. 1363 * 1364 * @discussion 1365 * This function scans the plugins folder of <code>aKext</code> 1366 * and returns an array of the kexts found. 1367 * This may result in the creation of new kext objects. 1368 * 1369 * If <code>aKext</code> is a plugin of another kext 1370 * see @link OSKextIsPlugin@/link), 1371 * this function returns an empty array. 1372 */ 1373CF_EXPORT CFArrayRef 1374OSKextCopyPlugins(OSKextRef aKext) 1375 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1376 1377/*! 1378 * @function OSKextIsPlugin 1379 * @abstract Returns whether a kext is a plugin of some other kext. 1380 * 1381 * @param aKext The kext to examine. 1382 * @result 1383 * <code>true</code> if <code>aKext</code> is a plugin of another kext, 1384 * <code>false</code> otherwise. 1385 * 1386 * @discussion 1387 * This function uses a simple algorithm that just checks for the substring 1388 * ".kext/" in the absolute path leading up to the kext's bundle name. 1389 */ 1390CF_EXPORT Boolean 1391OSKextIsPlugin(OSKextRef aKext) 1392 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1393 1394/*! 1395 * @function OSKextCopyContainerForPluginKext 1396 * @abstract Returns the kext that is the container for a plugin kext. 1397 * 1398 * @param aKext The kext to find a parent for. 1399 * @result 1400 * The kext that contains <code>aKext</code> in its PlugIns folder, 1401 * or <code>NULL</code> if <code>aKext</code> is not a plugin. 1402 * Ownership follows the 1403 * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. 1404 * 1405 * @discussion 1406 * This function creates a kext object for the longest portion of the 1407 * path leading to <code>aKext</code>, then checks to see whether 1408 * <code>aKext</code> is a plugin of that kext by <code>CFBundle</code>'s 1409 * semantics. If so, that kext is returned. 1410 * This may result in the creation of a new kext. 1411 */ 1412CF_EXPORT OSKextRef 1413OSKextCopyContainerForPluginKext(OSKextRef aKext) 1414 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1415 1416/*! 1417 * @function OSKextCopyPersonalitiesArray 1418 * @abstract Returns the personalities of a kext for the current kext architecture. 1419 * 1420 * @param aKext The kext to retrieve personalities for. 1421 * @result An array of IOKit personality dictionaries. 1422 * 1423 * @discussion 1424 * IOKitPersonalities in kexts require some processing before being sent 1425 * to the kernel, and the functions that send personalities expect an array 1426 * rather than a dictionary. This function facilitates such use. 1427 * 1428 * Use @link OSKextGetValueForInfoDictionaryKey@/link to retrieve the raw 1429 * personalities dictionary for the current architecture. 1430 */ 1431CF_EXPORT CFArrayRef 1432OSKextCopyPersonalitiesArray(OSKextRef aKext) 1433 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1434 1435// xxx - would it be awful to have a function that takes a CFTypeRef that's 1436// xxx - a single kext, an array of kexts, or NULL for all open kexts? 1437 1438/*! 1439 * @function OSKextCopyPersonalitiesOfKexts 1440 * @abstract 1441 * Returns the personalities of multiple kexts for the current kext architecture. 1442 * 1443 * @param kextArray The kexts to retrieve personalities for. 1444 * Pass <code>NULL</code> to retrieve personalities for all open kexts. 1445 * @result An array of IOKit personality dictionaries. 1446 * 1447 * @discussion 1448 * IOKitPersonalities in kexts require some processing before being sent 1449 * to the kernel, and the functions that send personalities expect an array 1450 * rather than a dictionary. This function facilitates such use. 1451 */ 1452CF_EXPORT CFArrayRef 1453OSKextCopyPersonalitiesOfKexts(CFArrayRef kextArray) 1454 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1455 1456/*! 1457 * @function OSKextCopyExecutableForArchitecture 1458 * @abstract 1459 * Returns a kext's Mach-O executable, thinned to a single architecture 1460 * if desired. 1461 * 1462 * @param aKext The kext to retrieve the executable from. 1463 * @param anArch The architecture desired. 1464 * Pass <code>NULL</code> to get the whole, unthinned exectuable. 1465 * @result 1466 * A <code>CFData</code> object containing the code 1467 * for the specified architecture, or <code>NULL</code> if it can't be found. 1468 * 1469 * @discussion 1470 * Note that this function does not use the default kext architecture set by 1471 * @link OSKextSetArchitecture@/link when given no architecture. 1472 */ 1473CF_EXPORT CFDataRef 1474OSKextCopyExecutableForArchitecture(OSKextRef aKext, 1475 const NXArchInfo * anArch) 1476 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1477 1478/*! 1479 * @function OSKextCopyResource 1480 * @abstract Returns a named resource from a kext's bundle. 1481 * 1482 * @param aKext The kext to get a resource from. 1483 * @param resourceName The name of the requested resource. 1484 * @param resourceType The abstract type of the requested resource. 1485 * The type is expressed as a filename extension, 1486 * such as <code>jpg</code>. 1487 * Pass <code>NULL</code> if you don't need 1488 * to search by type. 1489 * 1490 * @result 1491 * A <code>CFData</code> object containing the resource file's contents, 1492 * or <code>NULL</code> if the resource can't be found. 1493 * 1494 * @discussion 1495 * For a kext created from an on-disk URL, this function uses CFBundle 1496 * semantics to locate the resource file. Note that localized resources 1497 * and resource subdirectories are not available to kexts calling 1498 * @link //apple_ref/c/func/OSKextRequestResource OSKextRequestResource@/link 1499 * from within the kernel (because the process providing them runs as root). 1500 * You can store such resources in a kext bundle and use them in applications, 1501 * but they will not be available to the kext loaded in kernel. 1502 */ 1503CF_EXPORT CFDataRef 1504OSKextCopyResource( 1505 OSKextRef aKext, 1506 CFStringRef resourceName, 1507 CFStringRef resourceType) 1508 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1509 1510/*! 1511 * @function OSKextIsInExcludeList 1512 * @abstract Return true if given kext is in the kext exclude list. 1513 * 1514 * @param aKext The kext to check against exclude list. 1515 * @param useCache Tells us whether or not to use the cached exclude 1516 * list dictionary. 1517 * 1518 * @result 1519 * <code>true</code> if <code>aKext</code> is in the kext exclude list, 1520 * <code>false</code> otherwise. 1521 * 1522 * @discussion 1523 * Checks to see if the given kext is in the kext exclude list (see: 1524 * /System/Library/Extensions/AppleKextExcludeList.kext) 1525 * If useCache is TRUE, we will use the cached copy of the exclude list. 1526 * If useCache is FALSE, we will refresh the cache from disk. The 1527 * kext exclude list rarely changes but to insure you have the most 1528 * recent copy in the cache you may pass FALSE for the first call and TRUE for 1529 * subsequent calls (when dealing with a large list of kexts). 1530 * aKext can be NULL with useCache set to FALSE if you wish the invalidate the 1531 * cache without passing in a kext. 1532 */ 1533CF_EXPORT Boolean 1534OSKextIsInExcludeList( 1535 OSKextRef aKext, 1536 Boolean useCache) 1537__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_NA); 1538 1539#pragma mark Dependency Resolution 1540/********************************************************************* 1541* Dependency Resolution 1542*********************************************************************/ 1543 1544/*! 1545 * @function OSKextResolveDependencies 1546 * @abstract Calculate the dependency graph for a kext. 1547 * 1548 * @param aKext The kext to resolve dependencies for. 1549 * @result 1550 * <code>true</code> if all dependencies are successfully resolved, 1551 * <code>false</code> otherwise. 1552 * 1553 * @discussion 1554 * This function examines the OSBundleLibraries property of <code>aKext</code> 1555 * and looks for compatible open kexts. Priority is given to kexts marked as 1556 * loaded (see @link OSKextReadLoadedKextInfo@/link and 1557 * @link OSKextFlushLoadInfo@/link). Otherwise the most recent 1558 * compatible version is used; if multiple kexts with the same identifier and 1559 * version exist, the last one created is used. 1560 * 1561 * Any problems resolving dependencies are stored in a diagnostics dictionary, 1562 * which you can retrieve using @link OSKextCopyDiagnostics@/link. 1563 * 1564 * If a kext's dependencies have already been resolved, this function does 1565 * no work and returns <code>true</code>. 1566 * If you want to recalculate a kext's dependencies, call 1567 * @link OSKextFlushDependencies@/link first. 1568 */ 1569// xxx - check on same-version ordering with folks 1570CF_EXPORT Boolean 1571OSKextResolveDependencies(OSKextRef aKext) 1572 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1573 1574/*! 1575 * @function OSKextFlushDependencies 1576 * @abstract Clears the dependency graph of a kext. 1577 * 1578 * @param aKext The kext to flush dependencies for. 1579 * Pass <code>NULL</code> to flush dependencies for all kexts. 1580 * 1581 * @discussion 1582 * OSKexts accumulate a fair amount of information as they are created 1583 * and used; when many kext objects are created the total memory 1584 * consumption can be significant. If an application won't be using 1585 * kexts for long periods of time, it can flush this information 1586 * to save memory; the information will later be re-read from disk 1587 * or recreated as necessary. 1588 * 1589 * Flushing dependencies is also useful when readling loaded kext 1590 * information from the kernel with @link OSKextReadLoadedKextInfo@/link 1591 * (in fact, that function takes a flag to do it as part of its work). 1592 * Dependency resolution gives priority to kexts marked as loaded, 1593 * so it's wise to call flush dependencies before reading load info 1594 * and before doing any operation that resolves dependencies. 1595 * Conversely, if you want to resolve dependencies without consideration 1596 * for which kexts are loaded, call @link OSKextFlushLoadInfo@/link 1597 * beforehand (with or without the flag to flush dependencies). 1598 * 1599 * This function also clears any dependency resolution diagnostics. 1600 * See also @link OSKextFlushInfoDictionary@/link, 1601 * @link OSKextFlushLoadInfo@/link, 1602 * and @link OSKextFlushDiagnostics@/link. 1603 */ 1604CF_EXPORT void 1605OSKextFlushDependencies(OSKextRef aKext) 1606 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1607 1608/*! 1609 * @function OSKextCopyDeclaredDependencies 1610 * @abstract Returns the kexts identified in a kext's OSBundleLibraries property. 1611 * 1612 * @param aKext The kext to get dependencies for. 1613 * @param needAllFlag If <code>true</code>, the function returns 1614 * <code>NULL</code> if any dependency isn't found. 1615 * @result 1616 * A <code>CFArray</code> containing the kexts found. 1617 * If <code>needAllFlag</code> is <code>false</code>, the array may be missing 1618 * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all 1619 * dependencies are found, this function returns <code>NULL</code>. 1620 * 1621 * @discussion 1622 * This function calls @link OSKextResolveDependencies@/link to find 1623 * dependencies. 1624 */ 1625CF_EXPORT CFArrayRef 1626OSKextCopyDeclaredDependencies( 1627 OSKextRef aKext, 1628 Boolean needAllFlag) 1629 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1630 1631 1632/*! 1633 * @function OSKextCopyLinkDependencies 1634 * @abstract Returns the kexts that a kext links directly against. 1635 * 1636 * @param aKext The kext to get dependencies for. 1637 * @param needAllFlag If <code>true</code>, the function returns 1638 * <code>NULL</code> if any dependency isn't found. 1639 * @result 1640 * A <code>CFArray</code> containing the kexts found. 1641 * If <code>needAllFlag</code> is <code>false</code>, the array may be missing 1642 * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all 1643 * dependencies are found, this function returns <code>NULL</code>. 1644 * 1645 * @discussion 1646 * Link dependencies are how loaded kext relationships are tracked 1647 * in the kernel (as shown by the <code>kextstat(8)</code> program). 1648 * Some library kexts contain no executable, merely collecting sets of 1649 * other libraries for convenience or compatiblity purposes. 1650 * This function follows through such indirect libraries to find kexts 1651 * with executables that <code>aKext</code> will actually link against. 1652 * 1653 * This function calls @link OSKextResolveDependencies@/link to find 1654 * dependencies. 1655 */ 1656 // xxx - need to insert a manpage link on kextstat 1657CF_EXPORT CFArrayRef 1658OSKextCopyLinkDependencies( 1659 OSKextRef aKext, 1660 Boolean needAllFlag) 1661 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1662 1663/*! 1664 * @function OSKextCopyLoadList 1665 * @abstract 1666 * Returns the entire list of kexts in the load graph of a kext 1667 * (including that kext). 1668 * 1669 * @param aKext The kext to get the load list for. 1670 * @param needAllFlag If <code>true</code>, the function returns 1671 * <code>NULL</code> if any dependency isn't found. 1672 * @result 1673 * A <code>CFArray</code> containing the kexts found. 1674 * If <code>needAllFlag</code> is <code>false</code>, the array may be missing 1675 * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all 1676 * dependencies are found, this function returns <code>NULL</code>. 1677 * 1678 * @discussion 1679 * The fully-resolved load list represents all the kexts needed to load 1680 * <code>aKext</code> into the kernel, in an order guaranteed to work for 1681 * sequential starting and matching with IOKit personalities. 1682 * 1683 * This function calls @link OSKextResolveDependencies@/link to find 1684 * dependencies. 1685 */ 1686CF_EXPORT CFMutableArrayRef 1687OSKextCopyLoadList( 1688 OSKextRef aKext, 1689 Boolean needAllFlag) 1690 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1691 1692/*! 1693 * @function OSKextCopyLoadListForKexts 1694 * @abstract 1695 * Returns the entire list of kexts in load order of the merged load graph 1696 * of the provided list of kexts (including those kexts). 1697 * 1698 * @param kexts The kexts to get the load list for. 1699 * @param needAllFlag If <code>true</code>, the function returns 1700 * <code>NULL</code> if any dependency isn't found. 1701 * 1702 * @result 1703 * A <code>CFArray</code> containing the kexts found. 1704 * If <code>needAllFlag</code> is <code>false</code>, the array may be missing 1705 * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all 1706 * dependencies are found, this function returns <code>NULL</code>. 1707 * 1708 * @discussion 1709 * The fully-resolved load list represents all of the kexts needed to load 1710 * every kext in <code>kexts</code> into the kernel, in an order guaranteed to 1711 * work for sequential starting and matching with IOKit personalities. 1712 * 1713 * This function calls @link OSKextResolveDependencies@/link to find 1714 * dependencies. 1715 */ 1716CF_EXPORT CFMutableArrayRef 1717OSKextCopyLoadListForKexts( 1718 CFArrayRef kexts, 1719 Boolean needAllFlag) 1720 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1721 1722 1723/*! 1724 * @function OSKextCopyAllDependencies 1725 * @abstract 1726 * Returns all kexts that a given kexts depends on, directly or indirectly. 1727 * 1728 * @param aKext The kext to get dependencies for. 1729 * @param needAllFlag If <code>true</code>, the function returns 1730 * <code>NULL</code> if any dependency isn't found. 1731 * @result 1732 * A <code>CFArray</code> containing the kexts found. 1733 * If <code>needAllFlag</code> is <code>false</code>, the array may be missing 1734 * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all 1735 * dependencies are found, this function returns <code>NULL</code>. 1736 * 1737 * @discussion 1738 * This function calls @link OSKextResolveDependencies@/link to find 1739 * dependencies. 1740 */ 1741CF_EXPORT CFMutableArrayRef 1742OSKextCopyAllDependencies( 1743 OSKextRef aKext, 1744 Boolean needAllFlag) 1745 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1746 1747/*! 1748 * @function OSKextCopyIndirectDependencies 1749 * @abstract 1750 * Returns all kexts that a given kexts depends on indirectly. 1751 * 1752 * @param aKext The kext to get dependencies for. 1753 * @param needAllFlag If <code>true</code>, the function returns 1754 * <code>NULL</code> if any dependency isn't found. 1755 * @result 1756 * A <code>CFArray</code> containing the kexts found. 1757 * If <code>needAllFlag</code> is <code>false</code>, the array may be missing 1758 * some kexts. If <code>needAllFlag</code> is <code>true</code> and not all 1759 * dependencies are found, this function returns <code>NULL</code>. 1760 * 1761 * @discussion 1762 * Note that the list of indirect dependencies includes all kexts declared 1763 * as dependencies by the direct dependencies of <code>aKext</code> - 1764 * it may therefore include a direct dependency as well if some other 1765 * kext in the load graph declares it. 1766 * 1767 * This function calls @link OSKextResolveDependencies@/link to find 1768 * dependencies. 1769 */ 1770// xxx - This one isn't really useful, is it? 1771CFMutableArrayRef OSKextCopyIndirectDependencies( 1772 OSKextRef aKext, 1773 Boolean needAllFlag) 1774__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1775 1776/*! 1777 * @function OSKextDependsOnKext 1778 * @abstract 1779 * Returns whether a kext depends on a given library kext, 1780 * directly or indirectly. 1781 * 1782 * @param aKext The kext to examine. 1783 * @param libraryKext The possible library kext. 1784 * @param directFlag 1785 * If <code>true</code>, only checks for a direct declared dependency; 1786 * if <code>false</code> check for direct or indirect dependencies. 1787 * @result 1788 * <code>true</code> if <code>aKext</code> depends on <code>libraryKext</code>, 1789 * either directly or indirectly per <code>directFlag</code>. 1790 * Returns <code>false</code> otherwise. 1791 * 1792 * @discussion 1793 * This function calls @link OSKextResolveDependencies@/link to find 1794 * dependencies. 1795 * 1796 * This function works with actual dependency resolution, not potential. 1797 * If there are multiple kexts with the same bundle identifier, 1798 * <code>aKext</code> may not be the one chosen during resolution 1799 * and so it might appear that no kexts depend on it, even though they could. 1800 */ 1801CF_EXPORT Boolean 1802OSKextDependsOnKext( 1803 OSKextRef aKext, 1804 OSKextRef libraryKext, 1805 Boolean directFlag) 1806 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1807 1808/*! 1809 * @function OSKextCopyDependents 1810 * @abstract 1811 * Return all kexts that depend on a given kext, directly or indirectly. 1812 * 1813 * @param aKext The kext to get dependents for. 1814 * @param directFlag 1815 * <code>true</code> to get only kexts that declare a direct 1816 * dependency on <code>aKext</code>, 1817 * <code>false</code> to get all dependents, direct or indirect. 1818 * @result 1819 * An array of all kexts that ultimately depend on <code>aKext</code>, 1820 * directly or indirectly according to <code>directFlag</code>. 1821 * 1822 * @discussion 1823 * This function calls @link OSKextResolveDependencies@/link on all open 1824 * kexts to find dependencies. This can be somewhat expensive. 1825 * 1826 * This function works with actual dependency resolution, not potential. 1827 * If there are multiple kexts with the same bundle identifier, 1828 * <code>aKext</code> may not be the one chosen during resolution 1829 * and so it might appear that no kexts depend on it, even though they could. 1830 */ 1831CF_EXPORT CFMutableArrayRef 1832OSKextCopyDependents(OSKextRef aKext, 1833 Boolean directFlag) 1834 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1835 1836/*! 1837 * @function OSKextIsCompatibleWithVersion 1838 * @abstract Returns whether a library kext is compatible with a given version. 1839 * 1840 * @param aKext The kext to examine. 1841 * @param aVersion The kext version to check compatibility with 1842 * 1843 * @result 1844 * <code>truer</code> if <code>aKext</code> has a compatible version and 1845 * if <code>aVersion</code> is between the version and compatible version of 1846 * <code>aKext</code> (inclusive), <code>false</code> otherwise. 1847 * 1848 * @discussion 1849 */ 1850CF_EXPORT Boolean 1851OSKextIsCompatibleWithVersion( 1852 OSKextRef aKext, 1853 OSKextVersion aVersion) 1854 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1855 1856/*! 1857 * @function OSKextLogDependencyGraph 1858 * @abstract Prints the resolved dependency graph of a kext. 1859 * 1860 * @param aKext The kext to log the dependency graph of. 1861 * @param bundleIDFlag <code>true</code> to log kexts by bundle ID, 1862 * <code>false</code> to log them by URL. 1863 * @param linkFlag <code>true</code> to log the link graph only, 1864 * <code>false</code> to log the full dependency graph. 1865 * 1866 * @discussion 1867 * <code>linkFlag</code> allows you to display the dependencies as they will 1868 * be recorded in the kernel when the kext is loaded. 1869 * If it is <code>true</code>, then only kexts with executables are included 1870 * in the logged dependency graph. If it is <code>false</code>, all kexts 1871 * needed to load </code>aKext</code> are included. 1872 * 1873 * This function calls @link OSKextResolveDependencies@/link to find 1874 * dependencies. 1875 */ 1876CF_EXPORT void 1877OSKextLogDependencyGraph(OSKextRef aKext, 1878 Boolean bundleIDFlag, 1879 Boolean linkFlag) 1880 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1881 1882/*! 1883 * @function OSKextFindLinkDependencies 1884 * @abstract Finds kexts that define symbols a kext needs resolved. 1885 * 1886 * @param aKext The kext to examine. 1887 * @param nonKPIFlag 1888 * <code>false</code> to look in com.apple.kpi.* kernel component 1889 * for kernel symbols; 1890 * <code>true</code> to look in com.apple.kernel.* kernel components 1891 * instead (not recommended for later versions of Mac OS X). 1892 * @param allowUnsupportedFlag 1893 * <code>false</code> to skip unsupported libraries in the search; 1894 * <code>true</code> to include them. 1895 * @param onedefSymbolsOut 1896 * A dictionary containing symbols that were found once; 1897 * keys are the symbols, values are the kexts defining the key symbol. 1898 * Ownership follows the Create Rule. 1899 * Pass <code>NULL</code> to not retrieve. 1900 * @param undefinedSymbolsOut 1901 * A dictionary containing symbols that weren't found; 1902 * keys are the symbols, values are undefined. 1903 * Ownership follows the Create Rule. 1904 * Pass <code>NULL</code> to not retrieve. 1905 * @param multiplyDefinedSymbolsOut 1906 * A dictionary containing symbols found in multiple library kexts; 1907 * keys are the symbols, values are the kexts defining the key symbol. 1908 * Ownership follows the Create Rule. 1909 * Pass <code>NULL</code> to not retrieve. 1910 * @param multipleDefinitionLibraries 1911 * A array of all library kexts in which multiply defined symbols 1912 * were found; sorted by CFBundleIdentifier. 1913 1914 * Ownership follows the Create Rule. 1915 * Pass <code>NULL</code> to not retrieve. 1916 * @result 1917 * An array of kexts that export symbols referenced by <code>aKext</code>, 1918 * sorted by CFBundleIdentifier. 1919 * 1920 * @discussion 1921 * This function searches in all open kexts for symbols referenced by 1922 * <code>aKext</code>, ignoring the OSBundleLibraries property. 1923 * You can use this function to find out what you should list 1924 * in a kext's OSBundleLibraries property. 1925 * 1926 * If <code>undefinedSymbolsOut</code> has a nonzero count, 1927 * the symbols named by its keys could not be found in any open kext. 1928 * 1929 * If <code>multiplyDefinedSymbolsOut</code> has a nonzero count, 1930 * some of the result kexts define the same symbol, 1931 * and if those duplicates are listed 1932 * in OSBundleLibraries a link failure will occur. 1933 * You can inspect the contents of <code>multiplyDefinedSymbolsOut</code> 1934 * and <code>multipleDefinitionLibraries</code> 1935 * by hand to sort out which libraries you should actually declare. 1936 * 1937 * This function is fairly expensive, as it has to search through all open 1938 * kexts' information dictionaries, and all library kexts' executables. 1939 */ 1940CFArrayRef OSKextFindLinkDependencies( 1941 OSKextRef aKext, 1942 Boolean nonKPIFlag, 1943 Boolean allowUnsupportedFlag, 1944 CFDictionaryRef * undefinedSymbolsOut, 1945 CFDictionaryRef * onedefSymbolsOut, 1946 CFDictionaryRef * multiplyDefinedSymbolsOut, 1947 CFArrayRef * multipleDefinitionLibrariesOut) 1948 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1949 1950#pragma mark Linking and Loading; Other Kernel Operations 1951/********************************************************************* 1952* Linking and Loading; Other Kernel Operations 1953*********************************************************************/ 1954 1955/*! 1956 * @function OSKextLoad 1957 * @abstract Loads a kext and its dependencies into the kernel. 1958 * 1959 * @param aKext The kext to load. 1960 * @result 1961 * kOSReturnSuccess if <code>aKext</code> is successfully loaded 1962 * into the kernel, or was already loaded, or an error result if not. 1963 * 1964 * @discussion 1965 * The calling process must have an effective user ID of 0 (root) 1966 * to load kexts into the kernel. 1967 * 1968 * A kext and all its dependencies must pass all validation and authentication 1969 * tests to be loadable. See @link OSKextIsLoadable@/link for more information. 1970 * 1971 * All kexts loaded into the kernel are started, but IOKit personalities 1972 * are not sent to the IOCatalogue. 1973 * See @link OSKextSendPersonalitiesToKernel@/link. 1974 * 1975 * This function calls @link OSKextFlushLoadInfo@/link and clears dependencies 1976 * for all open kexts. It then calls @link OSKextCopyLoadList@/link 1977 * to find dependencies and @link OSKextReadLoadedKextInfo@/link on the 1978 * resulting load list. 1979 */ 1980// xxx - need to list errors that may be returned 1981CF_EXPORT OSReturn 1982OSKextLoad(OSKextRef aKext) 1983 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 1984 1985/*! 1986 * @function OSKextLoadWithOptions 1987 * @abstract Loads a kext and its dependencies into the kernel. 1988 * 1989 * @param aKext The kext to load. 1990 * @param startExclusion 1991 * <code>kOSKextExcludeAll</code> to omit starting <code>aKext</code> 1992 * and any of its dependencies not already started, 1993 * <code>kOSKextExcludeKext</code> to start the dependencies of 1994 * <code>aKext</code> but not <code>aKext</code> itself, 1995 * or <code>kOSKextExcludeNone</code> to start all loaded kexts. 1996 * @param addPersonalitiesExclusion 1997 * <code>kOSKextExcludeAll</code> to omit sending 1998 * IOKitPersonalities to the IOCatalogue for <code>aKext</code> 1999 * and any of its dependencies 2000 * (though they may already be in the IOCatalogue), 2001 * <code>kOSKextExcludeKext</code> to send personalities for the 2002 * dependencies of <code>aKext</code> but not <code>aKext</code> itself, 2003 * or <code>kOSKextExcludeNone</code> to send all personalities. 2004 * @param personalityNames 2005 * The names of IOKitPersonalities in <code>aKext</code> to send, 2006 * <code>addPersonalitiesExclusion</code> allowing. 2007 * If <code>NULL</code> all personalities are sent. 2008 * This parameter only affects <code>aKext</code>; if dependency 2009 * personalities are sent, they are all sent. 2010 * @param delayAutounloadFlag 2011 * <code>true</code> to cause the kernel's automatic kext unloader 2012 * to skip <code>aKext</code> for one cycle, giving extra time 2013 * to set up a debug session. <code>false</code> for normal behavior. 2014 * 2015 * @result 2016 * Returns <code>kOSReturnSuccess</code> on success, other values on failure. 2017 * 2018 * @discussion 2019 * This function allows a kext to be loaded but not started or matched 2020 * (for IOKit kexts), which is useful in some debug scenarios. 2021 * After calling this function, you may need to call @link OSKextStart@/link 2022 * to start <code>aKext</code> (along with its dependencies). 2023 * You may also need to call @link OSKextSendPersonalitiesToKernel@/link 2024 * for any kexts excluded from matching via 2025 * <code>addPersonalitiesExclusion</code>. 2026 * 2027 * The calling process must have an effective user ID of 0 (root) 2028 * to load kexts into the kernel. 2029 * 2030 * A kext and all its dependencies must pass all validation and authentication 2031 * tests to be loadable. See @link OSKextIsLoadable@/link for more information. 2032 * 2033 * This function calls @link OSKextFlushLoadInfo@/link and clears dependencies 2034 * for all open kexts. It then calls @link OSKextCopyLoadList@/link 2035 * to find dependencies and @link OSKextReadLoadedKextInfo@/link on the 2036 * resulting load list. 2037 */ 2038// xxx - need to list errors that may be returned 2039CF_EXPORT OSReturn 2040OSKextLoadWithOptions( 2041 OSKextRef aKext, 2042 OSKextExcludeLevel startExclusion, 2043 OSKextExcludeLevel addPersonalitiesExclusion, 2044 CFArrayRef personalityNames, 2045 Boolean delayAutounloadFlag) 2046 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2047 2048/*! 2049 * @function OSKextGenerateDebugSymbols 2050 * @abstract Generate debug symbols for a kext and its dependencies. 2051 * 2052 * @param aKext 2053 * The kext to generate debug symbols for. 2054 * @param kernelImage 2055 * The kernel Mach-O or symbol file to use for linking. 2056 * If <code>NULL</code>, the running kernel is used. 2057 * 2058 * @result 2059 * A dictionary whose keys are the bundle IDs of the kexts for which symbols 2060 * have been generated with ".sym" appended, and whose values are CFData 2061 * objects containing the symbol files. Returns <code>NULL</code> on error. 2062 * 2063 * @discussion 2064 * The result includes only non-interface kexts that have an executable 2065 * and a load address set. 2066 * Load addresses are set by @link OSKextReadLoadedKextInfo@/link or by 2067 * @link OSKextSetLoadAddress@/link. 2068 * 2069 * If using the running kernel for load addresses, the current architecture 2070 * set with @link OSKextSetArchitecture@/link must match that of the running 2071 * kernel or this function returns <code>NULL</code>. 2072 * 2073 * This function calls @link OSKextResolveDependencies@/link to find 2074 * dependencies. 2075 */ 2076CF_RETURNS_RETAINED 2077CF_EXPORT CFDictionaryRef 2078OSKextGenerateDebugSymbols( 2079 OSKextRef aKext, 2080 CFDataRef kernelImage) 2081 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA); 2082 2083/*! 2084 * @function OSKextNeedsLoadAddressForDebugSymbols 2085 * @abstract 2086 * Returns whether a kext needs a load address set to generate debug symbols. 2087 * 2088 * @param aKext The kext to examine. 2089 * @result 2090 * <code>true</code> if <code>aKext</code> needs a load address set 2091 * in order to generate debug symbols with 2092 * @link OSKextGenerateDebugSymbols@/link, <code>false</code> otherwise. 2093 */ 2094CF_EXPORT Boolean 2095OSKextNeedsLoadAddressForDebugSymbols(OSKextRef aKext) 2096 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA); 2097 2098/*! 2099 * OSKextUnload 2100 * @abstract Unloads a kext from the kernel if possible. 2101 * 2102 * @param aKext The kext to unload. 2103 * @param terminateServiceAndRemovePersonalities 2104 * If <code>true</code>, and the kext to unload has no kexts loaded 2105 * against it, all IOService objects defined by that kext will be 2106 * asked to terminate so that the unload can proceed, and the personalities 2107 * for the kext will be removed from the IOCatalogue. 2108 * 2109 * @result 2110 * <code>kOSReturnSuccess</code> on success, an error code 2111 * (typically <code>kOSKextReturnInUse</code>) on failure. 2112 * 2113 * @discussion 2114 * The calling process must have an effective user ID of 0 (root) 2115 * to unload kexts from the kernel. 2116 * A kext cannot be unloaded if it has any loaed dependents. 2117 * 2118 * See also the @link IOCatalogueTerminate@/link function. 2119 */ 2120// xxx - need to list errors that may be returned 2121CF_EXPORT OSReturn 2122OSKextUnload(OSKextRef aKext, 2123 Boolean terminateServiceAndRemovePersonalities) 2124 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2125 2126/*! 2127 * OSKextUnload 2128 * @abstract Unloads a kext from the kernel if possible, based on its 2129 * CFBundleIdentifier. 2130 * 2131 * @param kextIdentifier The CFBundleIDentifier of the kext to unload. 2132 * @param terminateServiceAndRemovePersonalities 2133 * If <code>true</code>, and the kext to unload has no kexts loaded 2134 * against it, all IOService objects defined by that kext will be 2135 * asked to terminate so that the unload can proceed, and the personalities 2136 * for the kext will be removed from the IOCatalogue. 2137 * 2138 * @result 2139 * <code>kOSReturnSuccess</code> on success, an error code 2140 * (typically <code>kOSKextReturnInUse</code>) on failure. 2141 * 2142 * @discussion 2143 * The calling process must have an effective user ID of 0 (root) 2144 * to unload kexts from the kernel. 2145 * A kext cannot be unloaded if it has any loaed dependents. 2146 * 2147 * See also the @link IOCatalogueTerminate@/link function. 2148 */ 2149// xxx - need to list errors that may be returned 2150CF_EXPORT OSReturn 2151OSKextUnloadKextWithIdentifier(CFStringRef kextIdentifier, 2152 Boolean terminateServiceAndRemovePersonalities) 2153 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2154 2155/*! 2156 * @function OSKextIsStarted 2157 * @abstract Returns whether a kext loaded in the kernel is started. 2158 * 2159 * @param aKext The kext to examine. 2160 * @result 2161 * <code>true</code> if <code>aKext</code> is active and running in the kernel, 2162 * <code>false</code> if not loaded or loaded and not started. 2163 * 2164 * @discussion 2165 * This function returns the state recorded the last time 2166 * @link OSKextReadLoadedKextInfo@/link was called. 2167 */ 2168CF_EXPORT Boolean 2169OSKextIsStarted(OSKextRef aKext) 2170 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2171 2172/*! 2173 * @function OSKextStart 2174 * @abstract Starts a kext loaded in the kernel if possible. 2175 * 2176 * @param aKext The kext to start. 2177 * @result 2178 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2179 * 2180 * @discussion 2181 * This function allows an application to start a kext that is loaded 2182 * in the kernel (typically via @link OSKextLoadWithOptions@/link), 2183 * and any of its dependencies that aren't also started. 2184 * If the kext is already started, this does nothing. 2185 * 2186 * To start a kext means to call its start function, which is distinct from 2187 * the start method of an IOService object. 2188 * 2189 * The calling process must have an effective user ID of 0 (root) 2190 * to start kexts in the kernel. 2191// xxx - need to list errors that may be returned 2192 */ 2193CF_EXPORT OSReturn 2194OSKextStart(OSKextRef aKext) 2195 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2196 2197/*! 2198 * @function OSKextStop 2199 * @abstract Stops a kext loaded in the kernel if possible. 2200 * 2201 * @param aKext The kext to stop. 2202 * @result 2203 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2204 * 2205 * @discussion 2206 * This function allows an application to stop a kext that is loaded 2207 * in the kernel without unloading it. This may be useful in certain 2208 * debugging scenarios. 2209 * 2210 * A kext cannot be stopped via this function if it has any dependents 2211 * that reference it, any client references within the kernel, 2212 * or any instances of libkern/IOKit C++ classes. 2213 * 2214 * To stop a kext means to call its stop function, which is distinct from 2215 * the stop method of an IOService object. 2216 * 2217 * The calling process must have an effective user ID of 0 (root) 2218 * to stop kexts in the kernel. 2219 */ 2220// xxx - should it be allowed to stop a kext with dependents that are 2221// xxx - themselves not started? 2222// xxx - need to list errors that may be returned 2223CF_EXPORT OSReturn 2224OSKextStop(OSKextRef aKext) 2225 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2226 2227/*! 2228 * @function OSKextSendPersonalitiesToKernel 2229 * @abstract Sends an array of IOKit personalities to the kernel. 2230 * 2231 * @param personalities The personalities to send. 2232 * @param resetFlag <code>TRUE</code> if the IOCatalogue should be reset, 2233 * <code>FALSE</code> not. 2234 * @result 2235 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2236 * 2237 * @discussion 2238 * This function sends an anonymous array of personalities to the 2239 * I/O Kit's IOCatalogue object in the kernel, 2240 * resetting the IOCatalogue if <code>resetFlag</code> is <code>TRUE</code>. 2241 * Resetting causes the IOCatalogue to contain only the kernel's built-in 2242 * personalities and those sent using this function. 2243 * (See also <code>@link IOCatalogueReset@/link</code>.) 2244 * 2245 * You can get personalities from kexts using 2246 * <code>@link OSKextCopyPersonalitiesArray@/link</code> or 2247 * <code>@link OSKextCopyPersonalitiesOfKexts@/link</code>. 2248 * 2249 * The calling process must have an effective user ID of 0 (root) 2250 * to send personalities to the kernel. 2251 */ 2252// xxx - need to list errors that may be returned 2253CF_EXPORT OSReturn 2254OSKextSendPersonalitiesToKernel(CFArrayRef personalities, Boolean resetFlag) 2255 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2256 2257/*! 2258 * @function OSKextSendKextPersonalitiesToKernel 2259 * @abstract 2260 * Sends the personalities of a single kext to the kernel, optionally 2261 * filtered by name. 2262 * 2263 * @param aKext The kext whose personalities to send. 2264 * @param personalityNames 2265 * An array of names. Only personalities from <code>aKext</code> 2266 * with these names are sent to the kernel. 2267 * @result 2268 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2269 * 2270 * @discussion 2271 * If any names in <code>personalityNames</code> are not found, 2272 * they are simply skipped rather than causing an error. 2273 * 2274 * This function may be useful in certain debugging scenarios, 2275 * where a particular personality is causing problems. 2276 * 2277 * The calling process must have an effective user ID of 0 (root) 2278 * to send personalities to the kernel. 2279 */ 2280// xxx - should names not found cause an error? 2281// xxx - need to list errors that may be returned 2282CF_EXPORT OSReturn 2283OSKextSendKextPersonalitiesToKernel( 2284 OSKextRef aKext, 2285 CFArrayRef personalityNames) 2286 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2287 2288/*! 2289 * @function OSKextSendPersonalitiesOfKextsToKernel 2290 * Sends the personalities of multiple kexts to the kernel in a single 2291 * operation. 2292 * 2293 * @param kextArray The kexts whose personalities to send. 2294 * @param resetFlag <code>TRUE</code> if the IOCatalogue should be reset, 2295 * <code>FALSE</code> not. 2296 * @result 2297 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2298 * 2299 * @discussion 2300 * This function performs one data transfer to the kernel, collecting 2301 * all the personalities of the kexts in <code>kextArray</code>, 2302 * and resetting the IOCatalogue if <code>resetFlag</code> is <code>TRUE</code>. 2303 * Resetting causes the IOCatalogue to contain only the kernel's built-in 2304 * personalities and those sent using this function. 2305 * (See also <code>@link IOCatalogueReset@/link</code>.) 2306 * 2307 * The calling process must have an effective user ID of 0 (root) 2308 * to send personalities to the kernel. 2309 */ 2310// xxx - need to list errors that may be returned 2311CF_EXPORT OSReturn 2312OSKextSendPersonalitiesOfKextsToKernel(CFArrayRef kextArray, Boolean resetFlag) 2313 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2314 2315/*! 2316 * @function OSKextRemoveKextPersonalitiesFromKernel 2317 * Removes all personalities for a kext's bundle identifier from the kernel. 2318 * 2319 * @param aKext The kext whose personalities to remove. 2320 * @result 2321 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2322 * 2323 * @discussion 2324 * This function removes from the kernel's IOCatalogue all personalities 2325 * whose CFBundleIdentifiers match that of <code>aKext</code> so that no 2326 * further load requests for <code>aKext</code> will be made. This is 2327 * typically done when it is discovered that <code>aKext</code> cannot 2328 * be loaded from user space (if it fails to load in the kernel, matching 2329 * personalities are automatically removed). 2330 * 2331 * Note that kexts other than <code>aKext</code> might have published 2332 * personalities in the IOCatalogue under <code>aKext</code>'s identifier. 2333 * Such personalities will also be removed, since they trigger load requests 2334 * for a kext that cannot be loaded. The OSKext library adds an 2335 * IOPersonalityPublisher property to such personalities, that gives the 2336 * bundle identifier of the originating kext. 2337 * 2338 * This function differs from 2339 * @link OSKextRemovePersonalitiesForIdentifierFromKernel@/link 2340 * by having a kext object to check for logging or other purposes. 2341 * 2342 * The calling process must have an effective user ID of 0 (root) 2343 * to remove personalities from the kernel. 2344 */ 2345// xxx - need to list errors that may be returned 2346// xxx - this is a not-so-thin shim over IOCatalogueSendData (kIOCatalogueRemoveDrivers) 2347// xxx - might we just want the function to take a bundle ID? 2348// xxx - does IOCatalogueSendData really require root access? 2349CF_EXPORT OSReturn 2350OSKextRemoveKextPersonalitiesFromKernel(OSKextRef aKext) 2351 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2352 2353/*! 2354 * @function OSKextRemovePersonalitiesForIdentifierFromKernel 2355 * Removes all personalities for a given bundle identifier from the kernel. 2356 * 2357 * @param aBundleID The bundle identifier for which to remove personalities. 2358 * @result 2359 * <code>kOSReturnSuccess</code> on success, an error code on failure. 2360 * 2361 * @discussion 2362 * This function removes from the kernel's IOCatalogue all personalities 2363 * whose CFBundleIdentifiers are <code>aBundleID</code> so that no 2364 * further load requests for the kext with that identifier will be made. 2365 * This is typically done when it is discovered no kext can be found for 2366 * <code>aBundleID</code>. 2367 * 2368 * This function differs from 2369 * @link OSKextRemoveKextPersonalitiesFromKernel@/link 2370 * by not having a kext object to check for logging or other purposes. 2371 * 2372 * The calling process must have an effective user ID of 0 (root) 2373 * to remove personalities from the kernel. 2374 */ 2375// xxx - need to list errors that may be returned 2376// xxx - this is a not-so-thin shim over IOCatalogueSendData (kIOCatalogueRemoveDrivers) 2377// xxx - I want 2 separate functions for logging; a kext can have flags in it 2378// xxx - does IOCatalogueSendData really require root access? 2379CF_EXPORT OSReturn 2380OSKextRemovePersonalitiesForIdentifierFromKernel(CFStringRef aBundleID) 2381 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2382 2383/*! 2384 * @function OSKextCreateLoadedKextInfo 2385 * @abstract Returns information about loaded kexts in a dictionary. 2386 * 2387 * @param kextIdentifiers An array of kext identifiers to read from the kernel. 2388 * Pass <code>NULL</code> to read info for all loaded kexts. 2389 * @result 2390 * An array of dictionaries containing information about loaded kexts. 2391 * 2392 * @discussion 2393 * This function is deprecated in Mac OS X 10.7. 2394 * Use @link OSKextCopyLoadedKextInfo/@link instead. 2395 * 2396 * This function gets information from the kernel without affecting any 2397 * kext objects. If you want to update open kext objects to reflect 2398 * whether they are loaded in the kernel, use @link OSKextReadLoadedKextInfo@/link. 2399 * 2400 * See <code>@link OSKextCopyLoadedKextInfo@/link</code> for the list of properties 2401 * returned. 2402 */ 2403// xxx - need to document the keys from OSKextLib.h. 2404CF_EXPORT CFArrayRef 2405OSKextCreateLoadedKextInfo( 2406 CFArrayRef kextIdentifiers) 2407 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_6, __MAC_10_7, __IPHONE_3_2, __IPHONE_4_3); 2408 2409/*! 2410 * @function OSKextCopyLoadedKextInfo 2411 * @abstract Returns information about loaded kexts in a dictionary. 2412 * 2413 * @param kextIdentifiers An array of kext identifiers to read from the kernel. 2414 * Pass <code>NULL</code> to read info for all loaded kexts. 2415 * @param infoKeys An array of info keys to read from the kernel. 2416 * Pass <code>NULL</code> to read all information. 2417 * @result 2418 * A dictionary, keyed by bundle identifier, of dictionaries containing information about loaded kexts. 2419 * 2420 * @discussion 2421 * This function gets information from the kernel without affecting any 2422 * kext objects in process memory. 2423 * If you want to update open kext objects to reflect 2424 * whether they are loaded in the kernel, 2425 * use @link OSKextReadLoadedKextInfo@/link. 2426 * 2427 * The properties returned by this function are listed below. 2428 * Some are taken directly from the kext's information property list, 2429 * and some are generated at run time. 2430 * Never assume a given key will be present for a kext. 2431 * 2432 * <ul> 2433 * <li><code>CFBundleIdentifier</code> - CFString</li> 2434 * <li><code>CFBundleVersion</code> - CFString (note: version strings may be canonicalized 2435 * but their numeric values will be the same; "1.2.0" may become "1.2", for example)</li> 2436 * <li><code>OSBundleCompatibleVersion</code> - CFString</li> 2437 * <li><code>OSBundleIsInterface</code> - CFBoolean</li> 2438 * <li><code>OSKernelResource</code> - CFBoolean</li> 2439 * <li><code>OSBundleCPUType</code> - CFNumber</li> 2440 * <li><code>OSBundleCPUSubtype</code> - CFNumber</li> 2441 * <li><code>OSBundleMachOHeaders</code> - CFData (this property is not available via the 2442 * public @link KextManagerCopyLoadedKextInfo/@link function)</li> 2443 * <li><code>OSBundlePath</code> - CFString (this is merely a hint stored in the kernel; 2444 * the kext is not guaranteed to be at this path)</li> 2445 * <li><code>OSBundleExecutablePath</code> - CFString 2446 * (the absolute path to the executable within the kext bundle; a hint as above)</li> 2447 * <li><code>OSBundleUUID</code> - CFData (the UUID of the kext executable, if it has one)</li> 2448 * <li><code>OSBundleStarted</code> - CFBoolean (true if the kext is running)</li> 2449 * <li><code>OSBundlePrelinked</code> - CFBoolean (true if the kext is loaded from a prelinked kernel)</li> 2450 * <li><code>OSBundleLoadTag</code> - CFNumber (the "Index" given by kextstat)</li> 2451 * <li><code>OSBundleLoadAddress</code> - CFNumber</li> 2452 * <li><code>OSBundleLoadSize</code> - CFNumber</li> 2453 * <li><code>OSBundleWiredSize</code> - CFNumber</li> 2454 * <li><code>OSBundleDependencies</code> - CFArray of load tags identifying immediate link dependencies</li> 2455 * <li><code>OSBundleRetainCount</code> - CFNumber (the OSObject retain count of the kext itself)</li> 2456 * <li><code>OSBundleClasses</code> - CFArray of CFDictionary containing info on C++ classes 2457 * defined by the kext:</li> 2458 * <ul> 2459 * <li><code>OSMetaClassName</code> - CFString</li> 2460 * <li><code>OSMetaClassSuperclassName</code> - CFString, absent for root classes</li> 2461 * <li><code>OSMetaClassTrackingCount</code> - CFNumber giving the instance count 2462 * of the class itself, <i>plus</i> 1 for each direct subclass with any instances</li> 2463 * </ul> 2464 * </ul> 2465 */ 2466CF_EXPORT CFDictionaryRef 2467OSKextCopyLoadedKextInfo( 2468 CFArrayRef kextIdentifiers, 2469 CFArrayRef infoKeys) 2470 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3); 2471 2472/*! 2473 * @function OSKextReadLoadedKextInfo 2474 * @abstract Updates kext objects with load info from the kernel. 2475 * 2476 * @param kextIdentifiers An array of kext identifiers to read 2477 * from the kernel; 2478 * all matching kexts have their load info updated. 2479 * Pass <code>NULL</code> to update load info for all kexts. 2480 * @param flushDependenciesFlag 2481 * <code>true</code> to clear dependency information from kexts, 2482 * <code>false</code> to leave it in place. 2483 * 2484 * @result 2485 * <code>kOSReturnSuccess</code> if all information is successfully updated, 2486 * an error code otherwise. Specifically, if the current architecture set 2487 * by @link OSKextSetArchitecture@/link is not that of the running kernel, 2488 * this function returns <code>kOSKextReturnExecutableArchNotFound</code>. 2489 * 2490 * @discussion 2491 * The load status of kexts primarily affects dependency resolution in the 2492 * kext library, in that kexts marked as loaded are given priority over 2493 * all other kexts of the same identifier. 2494 * See @link OSKextResolveDependencies@/link for more. 2495 * 2496 * This function calls @link OSKextFlushLoadInfo@/link on the kexts, 2497 * which clears any previous load info for them 2498 * (or for all kexts if <code>kextIdentifiers</code> is <code>NULL</code>). 2499 * If <code>flushDependenciesFlag</code> is <code>true</code>, 2500 * resolved dependencies (which may not match the loaded kexts 2501 * in the kernel) are also flushed. 2502 * Load addresses are then set from the kernel, 2503 * but dependencies are resolved as needed. 2504 * 2505 * If <code>flushDependenciesFlag</code> is <code>false</code>, 2506 * existing dependency graphs are maintained, allowing you to 2507 * check whether the dependencies, as resolved before reading 2508 * load information, reflect loaded kexts (by getting the load list 2509 * via @link OSKextCopyLoadList@/link and checking the kexts in it 2510 * with @link OSKextIsLoaded@/link). 2511 */ 2512// xxx - need to list errors that may be returned 2513CF_EXPORT OSReturn 2514OSKextReadLoadedKextInfo( 2515 CFArrayRef kexts, 2516 Boolean flushDependenciesFlag) 2517 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2518 2519/*! 2520 * @function OSKextIsLoaded 2521 * @abstract Returns whether a kext is loaded in the kernel. 2522 * 2523 * @param aKext The kext to examine. 2524 * @result 2525 * <code>true</code> if a kext with the same identifier, version, and UUID 2526 * as <code>aKext</code> is loaded in the kernel, <code>false</code> otherwise. 2527 * 2528 * @discussion 2529 * You must call @link OSKextReadLoadedKextInfo@/link for this flag to be meaningful, 2530 * which in turn requires the current library architecture to match that 2531 * of the running kernel. 2532 * Use @link OSKextOtherVersionIsLoaded@/link to check whether 2533 * a different version of <code>aKext</code> is loaded. 2534 */ 2535CF_EXPORT Boolean 2536OSKextIsLoaded(OSKextRef aKext) 2537 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2538 2539/*! 2540 * @function OSKextGetLoadAddress 2541 * @abstract Returns the actual or simulated kernel load address of a kext. 2542 * 2543 * @param aKext The kext to examine. 2544 * @result 2545 * The load address of <code>aKext</code>, whether read from the kernel using 2546 * @link OSKextReadLoadedKextInfo@/link or set for symbol generation using 2547 * @link OSKextSetLoadAddress@/link. 2548 * 2549 * @discussion 2550 * Load addresses are accessed as 64-bit numbers even for 32-bit architectures; 2551 * cast or truncate the value as necessary. 2552 * 2553 * You must call @link OSKextReadLoadedKextInfo@/link or 2554 * @link OSKextSetLoadAddress@/link for the load address to be nonzero. 2555 */ 2556CF_EXPORT uint64_t 2557OSKextGetLoadAddress(OSKextRef aKext) 2558 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2559 2560/*! 2561 * @function OSKextSetLoadAddress 2562 * @abstract 2563 * Sets the simulated kernel load address of a kext for symbol generation. 2564 * 2565 * @param aKext The kext to set a load address for. 2566 * @result 2567 * <code>true</code> if the address was set, <code>false</code> if not 2568 * (because it's too large for the current architecture). 2569 * 2570 * @discussion 2571 * Load addresses are accessed as 64-bit numbers even for 32-bit architectures. 2572 * If you attempt to set a load address that is too large for a 32-bit link, 2573 * this function returns <code>false</code>. 2574 * See @link OSKextSetArchitecture@/link. 2575 * 2576 * Setting a load address manually is useful for generating debug symbols 2577 * with @link OSKextGenerateDebugSymbols@/link. 2578 */ 2579CF_EXPORT Boolean 2580OSKextSetLoadAddress(OSKextRef aKext, uint64_t anAddress) 2581 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2582 2583/*! 2584 * @function OSKextOtherVersionIsLoaded 2585 * @abstract 2586 * Returns whether another version of a given kext is loaded in the kernel. 2587 * 2588 * @param aKext The kext to examine. 2589 * @result 2590 * <code>true</code> if a kext with the same identifier, 2591 * but a different version or UUID 2592 * from <code>aKext</code>, is loaded in the kernel. 2593 * Returns <code>false</code> if <code>aKext</code> is loaded or if 2594 * no kext with the same identifier is loaded. 2595 * 2596 * @discussion 2597 * You must call @link OSKextReadLoadedKextInfo@/link for this flag to be meaningful, 2598 * which in turn requires the current library architecture to match that 2599 * of the running kernel. 2600 * Use @link OSKextIsLoaded@/link to check whether <code>aKext</code> 2601 * itself is loaded. 2602 */ 2603CF_EXPORT Boolean 2604OSKextOtherVersionIsLoaded(OSKextRef aKext, Boolean * uuidFlag) 2605 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2606 2607/*! 2608 * @function OSKextGetLoadTag 2609 * @abstract 2610 * Returns the load tag of a kext if it's loaded in the kernel. 2611 * 2612 * @param aKext The kext to examine. 2613 * @result 2614 * The load tag (also known as the index or kmod id) of <code>aKext</code>, 2615 * if it's loaded in the kernel (use @link OSKextIsLoaded@/link to check that). 2616 * Returns 0 if <code>aKext</code> is not loaded or if it can't be determined 2617 * whether it is loaded. 2618 * 2619 * @discussion 2620 * You must call @link OSKextReadLoadedKextInfo@/link for the load tag 2621 * to be meaningful, which in turn requires the current library architecture 2622 * to match that of the running kernel. 2623 * Use @link OSKextIsLoaded@/link to check whether <code>aKext</code> 2624 * is loaded. 2625 */ 2626CF_EXPORT uint32_t 2627OSKextGetLoadTag(OSKextRef aKext) 2628 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2629 2630/*! 2631 * @function OSKextFlushLoadInfo 2632 * @abstract Clears all load and dependency information from a kext. 2633 * 2634 * @param aKext 2635 * The kext to clear. If <code>NULL</code>, all open 2636 * kexts have their load info flushed. 2637 * @param flushDependenciesFlag 2638 * <code>true</code> to clear dependency information from kexts, 2639 * <code>false</code> to leave it in place. 2640 * 2641 * @discussion 2642 * Flushing load information releases the internal load information 2643 * structs of a kext, including load flags, the bundle executable, 2644 * link/load diagnostics, and if <code>flushDependenciesFlag</code> is true, 2645 * the dependencies. 2646 * 2647 * OSKexts accumulate a fair amount of information as they are created 2648 * and used; when many kext objects are created the total memory 2649 * consumption can be significant. If an application won't be using 2650 * kexts for long periods of time, it can flush this information 2651 * to save memory; the information will later be re-read from disk 2652 * or recreated as necessary. 2653 * 2654 * Flushing load info is also useful after readling loaded kext 2655 * information from the kernel with @link OSKextReadLoadedKextInfo@/link 2656 * or after working with executables. Executables in particular 2657 * consume a lot of application memory, often unnecessarily, since 2658 * the code is loaded and running in the kernel. 2659 * 2660 * See also @link OSKextFlushInfoDictionaries@/link, 2661 * @link OSKextFlushDependencies@/link, 2662 * and @link OSKextFlushDiagnostics@/link. 2663 */ 2664CF_EXPORT void 2665OSKextFlushLoadInfo( 2666 OSKextRef aKext, 2667 Boolean flushDependenciesFlag) 2668 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2669 2670/*! 2671 * @function OSKextCopyAllRequestedIdentifiers 2672 * @abstract 2673 * Copies the list of all unique bundle identifiers of kext load requests 2674 * that the kernel has received since power-on. 2675 * 2676 * @result 2677 * A CFArray object, or <code>NULL</code> if the copy failed. 2678 * Ownership follows the 2679 * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. 2680 * 2681 */ 2682CF_EXPORT CFArrayRef 2683OSKextCopyAllRequestedIdentifiers(void) 2684 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2685 2686#pragma mark Sanity Checking and Diagnostics 2687/********************************************************************* 2688* Sanity Checking and Diagnostics 2689*********************************************************************/ 2690 2691/*! 2692 * @function OSKextParseVersionCFString 2693 * @abstract 2694 * Parses a kext version from a CFString. 2695 * 2696 * @param versionString The kext version string to parse. 2697 * @result 2698 * The numeric rendering of <code>versionString</code>, which can 2699 * compared arithmetically with other valid version numbers. 2700 * Returns -1 if the version couldn't be parsed. 2701 */ 2702CF_EXPORT OSKextVersion 2703OSKextParseVersionCFString(CFStringRef versionString) 2704 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2705 2706/*! 2707 * @function OSKextValidate 2708 * @abstract 2709 * Sanity checks a kext's info dictionary and executable for the currently 2710 * set architecture. 2711 * 2712 * @param aKext The kext to validate. 2713 * @result 2714 * <code>true</code> if <code>aKext</code> passes all validation tests, 2715 * <code>false</code> otherwise. 2716 * 2717 * @discussion 2718 * This function forces full validation of a kext, collecting all 2719 * errors found in the validation diagnostics if recording is turned on 2720 * (with @link OSKextSetRecordsDiagnostics@/link). You can get the diagnostics 2721 * using @link OSKextCopyDiagnostics@/link. 2722 * 2723 * If safe boot is currently simulated (see 2724 * @link OSKextSetSimulatedSafeBoot@/link), 2725 * any kext not loadable during safe boot will fail validation. 2726 */ 2727// compare with CFBundlePreflightExecutable() 2728CF_EXPORT Boolean 2729OSKextValidate(OSKextRef aKext) 2730 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2731 2732/*! 2733 * @function OSKextIsValid 2734 * @abstract 2735 * Returns whether a kext is valid or not. 2736 * 2737 * @param aKext The kext to examine. 2738 * @result 2739 * <code>true</code> if <code>aKext</code> passes all validation tests, 2740 * <code>false</code> otherwise. 2741 * 2742 * @discussion 2743 * This function avoids doing full validation if any problems have been 2744 * discovered with the kext during other operations. To perform a full 2745 * validation of all possible problems, use @link OSKextValidate@/link. 2746 */ 2747CF_EXPORT Boolean 2748OSKextIsValid(OSKextRef aKext) 2749 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2750 2751/*! 2752 * @function OSKextValidateDependencies 2753 * @abstract Validates all dependencies of a kext. 2754 * 2755 * @param aKext The kexts whose dependencies to validate. 2756 * @result 2757 * <code>true</code> if all dependencies of <code>aKext</code> are valid, 2758 * <code>false</code> if any of them are not. 2759 * 2760 * @discussion 2761 * This function calls @link OSKextValidate@/link on <code>aKext</code> and 2762 * all the current dependencies of <code>aKext</code>. 2763 * Use @link OSKextCopyDiagnostics@/link 2764 * with a flag of @link kOSKextDiagnosticsFlagDependencies@/link 2765 * to get the dependency-resolution failures caused by invalid dependencies. 2766 * 2767 * If safe boot is currently simulated (see 2768 * @link OSKextSetSimulatedSafeBoot@/link), 2769 * any kext not loadable during safe boot will fail validation. 2770 * 2771 * This function calls @link OSKextResolveDependencies@/link to find 2772 * dependencies. 2773 */ 2774CF_EXPORT Boolean 2775OSKextValidateDependencies(OSKextRef aKext) 2776 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2777 2778/*! 2779 * @function OSKextAuthenticate 2780 * @abstract Authenticates file ownership and permissions of a kext. 2781 * 2782 * @param aKext The kext to examine. 2783 * @result 2784 * <code>true</code> if all directories and files in <code>aKext</code>'s 2785 * bundle or mkext source have secure ownership and permissions, 2786 * <code>false</code> if they do not, or if authentication could not be done. 2787 * 2788 * @discussion 2789 * This function forces full authentication of a kext, collecting all 2790 * errors found in the authentication diagnostics, collecting all 2791 * errors found in the validation diagnostics if recording is turned on 2792 * (with @link OSKextSetRecordsDiagnostics@/link). You can get the diagnostics 2793 * using @link OSKextCopyDiagnostics@/link. 2794 * 2795 * For a kext to be loadable into the kernel, it must be owned by 2796 * user root, group wheel, and its constituent files and directories 2797 * must be nonwritable by group and other. 2798 * A kext created from an mkext file uses that mkext file for authentication 2799 * (see @link OSKextCreateKextsFromMkextFile@/link. 2800 */ 2801CF_EXPORT Boolean 2802OSKextAuthenticate(OSKextRef aKext) 2803 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2804 2805/*! 2806 * @function OSKextIsSigned 2807 * @abstract 2808 * Returns whether a kext is code signed or not. 2809 * 2810 * @param aKext The kext to examine. 2811 * @result 2812 * <code>true</code> if <code>aKext</code> is signed, 2813 * <code>false</code> otherwise. 2814 * 2815 * @discussion 2816 * This function checks to see if code signing resources are in place in the 2817 * kext bundle. 2818 */ 2819CF_EXPORT Boolean 2820OSKextIsSigned(OSKextRef aKext) 2821 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_NA); 2822 2823/*! 2824 * @function OSKextIsAuthentic 2825 * @abstract 2826 * Returns whether a kext is authentic or not. 2827 * 2828 * @param aKext The kext to examine. 2829 * @result 2830 * <code>true</code> if <code>aKext</code> passes all authentication tests, 2831 * <code>false</code> otherwise. 2832 * 2833 * @discussion 2834 * This function avoids doing full authentication if any problems have been 2835 * discovered with the kext during other operations. To perform a full 2836 * validation of all possible problems, use @link OSKextValidate@/link. 2837 */ 2838CF_EXPORT Boolean 2839OSKextIsAuthentic(OSKextRef aKext) 2840 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2841 2842/*! 2843 * @function OSKextAuthenticateDependencies 2844 * @abstract Authenticates all dependencies of a kext. 2845 * 2846 * @param aKext The kexts whose dependencies to authenticate. 2847 * @result 2848 * <code>true</code> if all dependencies of <code>aKext</code> are authentic, 2849 * <code>false</code> if any of them are not. 2850 * 2851 * @discussion 2852 * This function calls @link OSKextAuthenticate@/link on <code>aKext</code> 2853 * and all the current dependencies of <code>aKext</code>. 2854 * Use @link OSKextCopyDiagnostics@/link 2855 * with a flag of @link kOSKextDiagnosticsFlagDependencies@/link 2856 * to get the dependency-resolution failures caused by inauthentic dependencies. 2857 * 2858 * This function calls @link OSKextResolveDependencies@/link to find 2859 * dependencies. 2860 */ 2861CF_EXPORT Boolean 2862OSKextAuthenticateDependencies(OSKextRef aKext) 2863 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2864 2865/*! 2866 * @function OSKextIsLoadable 2867 * @abstract 2868 * Returns whether a kext appears loadable for the current architecture. 2869 * 2870 * @param aKext The kext to examine. 2871 * @result 2872 * <code>true</code> if <code>aKext</code> has no problems with validation, 2873 * authentication, or dependency resolution for the current architecture, 2874 * and if it's eligible for the current safe boot mode. 2875 * Returns <code>false</code> otherwise. 2876 * 2877 * @discussion 2878 * This function resolves dependencies for <code>aKext</code>, 2879 * validates and authenticsates <code>aKext</code> and its dependencies, 2880 * and if safe boot is simulated also checks the OSBundleRequired property 2881 * of <code>aKext</code> and its dependencies. If all these tests pass, 2882 * the kext is considered loadable for the current architecture 2883 * (which need not match that of the running kernel). 2884 * 2885 * See @link OSKextSetArchitecture@/link and 2886 * @link OSKextSetSimulatedSafeBoot@/link. 2887 * 2888 * This function calls @link OSKextResolveDependencies@/link to find 2889 * dependencies. 2890 */ 2891CF_EXPORT Boolean 2892OSKextIsLoadable(OSKextRef aKext) 2893 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2894 2895/*! 2896 * @function OSKextCopyDiagnostics 2897 * @abstract Returns diagnostics information for a kext. 2898 * 2899 * @param aKext The kext to get diagnostics for. 2900 * @param typeFlags Flags indicating which diagnostics to retrieve. 2901 * @result 2902 * A dictionary containing diagnostics for <cod>aKext</code>, suitable 2903 * for display in an outline view or printout. 2904 * 2905 * @discussion 2906 * You can use this function after validating, authenticating, resolving 2907 * dependencies, or generating debug symbols to get all the problems encountered 2908 * with those operations. 2909 * 2910 * The exact keys and values used for diagnostics are for informational purposes 2911 * only, are not formally defined, and may change without warning. 2912 * 2913 * You can use @link OSKextLogDiagnostics@/link to print nicely-formatted 2914 * reports of any problems found with kexts. 2915 */ 2916// xxx - need to tie in with the kernel & linker to get link failures 2917CFDictionaryRef OSKextCopyDiagnostics(OSKextRef aKext, 2918 OSKextDiagnosticsFlags typeFlags) 2919__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2920 2921/*! 2922 * @function OSKextLogDiagnostics 2923 * @abstract Logs specified diagnostics for a kext. 2924 * 2925 * @param aKext The kext to log diagnostics for. 2926 * @param typeFlags Flags indicating which diagnostics to log. 2927 * 2928 * @discussion 2929 * You can use this function after validating, authenticating, resolving 2930 * dependencies, or generating debug symbols to display all the problems 2931 * encountered with those operations. 2932 */ 2933CF_EXPORT void 2934OSKextLogDiagnostics( 2935 OSKextRef aKext, 2936 OSKextDiagnosticsFlags typeFlags) 2937 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2938 2939/*! 2940 * @function OSKextFlushDiagnostics 2941 * @abstract Clears all diagnostics information from a kext. 2942 * 2943 * @param aKext 2944 * The kext to clear diagnostics from. 2945 * Pass <code>NULL</code> to flush diagnostics from all open kexts. 2946 * @param typeFlags Flags indicating which diagnostics to flush. 2947 * 2948 * @discussion 2949 * OSKexts accumulate a fair amount of information as they are created 2950 * and used; when many kext objects are created the total memory 2951 * consumption can be significant. If an application won't be using 2952 * kexts for long periods of time, it can flush this information 2953 * to save memory; the information will later be re-read from disk 2954 * or recreated as necessary. 2955 * 2956 * See also @link OSKextFlushInfoDictionaries@/link, 2957 * @link OSKextFlushDependencies@/link, 2958 * and @link OSKextFlushLoadInfo@/link. 2959 */ 2960CF_EXPORT void 2961OSKextFlushDiagnostics(OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) 2962 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2963 2964#pragma mark Mkext and Prelinked Kernel Files 2965/********************************************************************* 2966* Mkext and Prelinked Kernel Files 2967*********************************************************************/ 2968// xxx - Use "Flag" or "Mask"? 2969typedef uint32_t OSKextRequiredFlags; 2970#define kOSKextOSBundleRequiredNone 0x0 2971#define kOSKextOSBundleRequiredRootFlag 0x1ULL 2972#define kOSKextOSBundleRequiredLocalRootFlag 0x1ULL << 1 2973#define kOSKextOSBundleRequiredNetworkRootFlag 0x1ULL << 2 2974#define kOSKextOSBundleRequiredSafeBootFlag 0x1ULL << 3 2975#define kOSKextOSBundleRequiredConsoleFlag 0x1ULL << 4 2976 2977/*! 2978 * @function OSKextIsFromMkext 2979 * @abstract Returns whether a kext was created from an mkext archive. 2980 * 2981 * @param aKext The kext to examine. 2982 * @result 2983 * <code>true</code> if <code>aKext</code> was created from an mkext archive, 2984 * <code>false</code> if it was created from an on-disk bundle. 2985 * 2986 * @discussion 2987 * A kext created from an mkext will have only its info dictionary, executable, 2988 * and any resources listed in its the OSBundleStartupResources property. 2989 */ 2990CF_EXPORT Boolean 2991OSKextIsFromMkext(OSKextRef aKext) 2992 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 2993 2994/*! 2995 * @function OSKextMatchesRequiredFlags 2996 * @abstract 2997 * Returns whether a kext matches a given set of flags for inclusion in an 2998 * mkext archive. 2999 * 3000 * @param aKext The kext to examine. 3001 * @param requiredFlags 3002 * Flags indicating which values of OSBundleRequired 3003 * are needed. 3004 * @result 3005 * <code>true</code> if <code>aKext</code>'s OSBundleRequired property 3006 * matches one of the specified flags, <code>false</code> otherwise. 3007 * 3008 * @discussion 3009 * This function is used to select kexts for inclusion in an mkext archive. 3010 * See @link OSKextFilterRequiredKexts@/link and 3011 * @link OSKextCreateMkext@/link. 3012 */ 3013CF_EXPORT Boolean 3014OSKextMatchesRequiredFlags(OSKextRef aKext, 3015 OSKextRequiredFlags requiredFlags) 3016 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 3017 3018/*! 3019 * @function OSKextFilterRequiredKexts 3020 * @abstract 3021 * Filters an array of kexts based on a set of flags 3022 * for inclusion in an mkext archive. 3023 * 3024 * @param kextArray 3025 * The kexts to filter. 3026 * Pass <code>NULL</code> to filter all open kexts. 3027 * @param requiredFlags 3028 * Flags indicating which values of OSBundleRequired 3029 * are needed. 3030 * @result 3031 * An array of kexts matching <code>requiredFlags</code>. 3032 * 3033 * @discussion 3034 * This function is used to select kexts for inclusion in an mkext archive. 3035 * See @link OSKextCreateMkext@/link. 3036 * 3037 */ 3038CF_EXPORT CFArrayRef 3039OSKextFilterRequiredKexts(CFArrayRef kextArray, 3040 OSKextRequiredFlags requiredFlags) 3041 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 3042 3043/*! 3044 * @function OSKextCreateMkext 3045 * @abstract Create an mkext file from an array of kexts and set of flags. 3046 * 3047 * @param allocator 3048 * The allocator to use to allocate memory for the new object. 3049 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 3050 * to use the current default allocator. 3051 * @param kextArray 3052 * The kexts to include in the mkext. 3053 * Pass <code>NULL</code> to use all open kexts. 3054 * @param volumeRootURL 3055 * If non-<code>NULL</code>, kexts with this URL as a prefix 3056 * strip it when saving their paths in the mkext. 3057 * This allows creation of mkexts for volumes 3058 * other than the current startup volume. 3059 * @param requiredFlags 3060 * A set of flags that filters <code>kextArray</code> to a subset 3061 * of kexts required for specific startup scenarios 3062 * (typically local disk vs. network). 3063 * @param compressFlag 3064 * <code>true</code> to compress data in the mkext, 3065 * <code>false</code> to include them at full size. 3066 * COMPRESSED MKEXTS ARE NOT SUPPORTED IN THE KERNEL YET. 3067 * @result 3068 * A <code>CFData</code> object containing the mkext file data on success, 3069 * <code>NULL</code> on failure. 3070 * 3071 * @discussion 3072 * This function creates a single-architecture mkext file for the currently 3073 * set library architecture (see @link OSKextSetArchitecture@/link). Kexts 3074 * with executables lacking code for that architecture are not included. 3075 * 3076 * If you want to create a multi-architecture mkext, create a set of single 3077 * architecture mkext files and use lipo(1) or combine them programmatically. 3078 * 3079 * This function generates mkext files in a new format that only works on 3080 * Mac OS X 10.6 or later. 3081 */ 3082// xxx - add a version param and generate old-format mkexts? 3083// xxx - add flag to take only most recent version of a given bundle ID? 3084CF_EXPORT CFDataRef 3085OSKextCreateMkext( 3086 CFAllocatorRef allocator, 3087 CFArrayRef kextArray, 3088 CFURLRef volumeRootURL, 3089 OSKextRequiredFlags requiredFlags, 3090 Boolean compressFlag) 3091 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 3092 3093/*! 3094 * @function OSKextCreateKextsFromMkextFile 3095 * @abstract Reads all kexts from an mkext file on disk. 3096 * 3097 * @param alocator 3098 * The allocator to use to allocate memory for the new objects. 3099 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 3100 * to use the current default allocator. 3101 * @param mkextURL 3102 * The mkext file URL from which to create kexts. 3103 * @result 3104 * Returns an array containing the kext objects created, 3105 * or <code>NULL</code> on failure. 3106 * 3107 * @discussion 3108 * This function creates kext objects from an mkext file rather than from 3109 * bundles on disk. Kexts created with this function are authenticated using 3110 * the mkext file at <code>mkextURL</code>. 3111 * 3112 * A kext created from an mkext has only its info dictionary, executable, 3113 * and any resources listed in its the OSBundleStartupResources property. 3114 * 3115 * Kexts created from an mkext are not uniqued using filesystem URLs, 3116 * which belong to bundles actually in the filesystem; 3117 * @link OSKextCreate@/link will never return a kext extracted from an mkext 3118 * that originally had the URL given (even though the new mkext format 3119 * stores that original URL). 3120 * This also means that if you open the same mkext file multiple times, 3121 * you will create distinct, identical copies of the kexts in that mkext file. 3122 */ 3123CF_EXPORT CFArrayRef 3124OSKextCreateKextsFromMkextFile(CFAllocatorRef allocator, 3125 CFURLRef mkextURL) 3126 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 3127 3128/*! 3129 * @function OSKextCreateKextsFromMkextData 3130 * @abstract Reads all kexts from an mkext file in memory. 3131 * 3132 * @param alocator 3133 * The allocator to use to allocate memory for the new objects. 3134 * Pass <code>NULL</code> or <code>kCFAllocatorDefault</code> 3135 * to use the current default allocator. 3136 * @param mkextData 3137 * The mkext file data from which to create kexts. 3138 * @result 3139 * Returns an array containing the kext objects created, 3140 * or <code>NULL</code> on failure. 3141 * 3142 * @discussion 3143 * This function creates kext objects from an mkext file in memory 3144 * rather than from bundles on disk. Lacking any file in the filesystem, 3145 * kexts created with this function can not be authenticated. 3146 * 3147 * A kext created from an mkext has only its info dictionary, executable, 3148 * and any resources listed in its the OSBundleStartupResources property. 3149 * 3150 * Kexts created from an mkext are not uniqued using filesystem URLs, 3151 * which belong to bundles actually in the filesystem; 3152 * @link OSKextCreate@/link will never return a kext extracted from an mkext 3153 * that originally had the URL given (even though the new mkext format 3154 * stores that original URL). 3155 * This also means that if you open the same mkext file multiple times, 3156 * you will create distinct, identical copies of the kexts in that mkext file. 3157 */ 3158CF_EXPORT CFArrayRef 3159OSKextCreateKextsFromMkextData(CFAllocatorRef allocator, 3160 CFDataRef mkextData) 3161 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_2); 3162 3163/*! 3164 * @enum OSKextKernelcacheFlags 3165 * @abstract The flags that affect the behavior of 3166 * @link OSKextCreatePrelinkedKernel@/link. 3167 * 3168 * @constant kOSKextKernelcacheNeedAllFlag 3169 * If set and any kext fails to link, 3170 * @link OSKextCreatePrelinkedKernel@/link returns <code>NULL</code>. 3171 * @constant kOSKextKernelcacheSkipAuthenticationFlag 3172 * If set, kexts are not authenticated for inclusion in the prelinked 3173 * kernel. 3174 * @constant kOSKextKernelcachePrintDiagnosticsFlag 3175 * If set, problems with the kexts that prevent inclusion of a kext in 3176 * the prelinked kernel are logged via 3177 * @link OSKextLogDiagnostics OSKextLogDiagnostics@/link. 3178 * @constant kOSKextKernelcacheIncludeAllPersonalitiesFlag 3179 * If set, all kext personalities will be included in the prelinked 3180 * kernel, regardless of whether they're required. 3181 * @constant kOSKextKernelcacheStripSymbols 3182 * If set, symbol tables are stripped from kexts before they are 3183 * placed in the prelinked kernel. If symbolsOut is 3184 * non-<code>NULL</code>, symbolicated binaries will still be returned 3185 * to the caller. 3186 * @constant kOSKextKernelcacheKASLRFlag 3187 * If set, generate DYSYMTAB load commands for KASLR support. 3188 */ 3189enum { 3190 kOSKextKernelcacheNeedAllFlag = (1 << 0), 3191 kOSKextKernelcacheSkipAuthenticationFlag = (1 << 1), 3192 kOSKextKernelcachePrintDiagnosticsFlag = (1 << 2), 3193 kOSKextKernelcacheIncludeAllPersonalitiesFlag = (1 << 3), 3194 kOSKextKernelcacheStripSymbolsFlag = (1 << 4), 3195 kOSKextKernelcacheKASLRFlag = (1 << 5), 3196}; 3197 3198/*! 3199 * @function OSKextCreatePrelinkedKernel 3200 * @abstract Creates a prelinked kernel from a kernel file and all open kexts. 3201 * 3202 * @param kernelImage The kernel image to use. 3203 * @param kextArray 3204 * The kexts to include in the prelinked kernel. 3205 * Pass <code>NULL</code> to consult the running kernel 3206 * for kexts to include from those open; 3207 * the current architecture must match the runninng kernel's. 3208 * @param volumeRootURL 3209 * If non-<code>NULL</code>, kexts with this URL as a prefix 3210 * strip it when saving their paths in the prelinked kernel. 3211 * This allows creation of prelinked kernels from folders 3212 * other than /System/Library/Extensions. 3213 * @param flags 3214 * See @link OSKextKernelcacheFlags@/link. 3215 * @param symbolsOut 3216 * If non-<code>NULL</code> debug symbols for <code>kernelImage</code> 3217 * and all kexts included in the result are returned by reference. 3218 * 3219 * @result 3220 * A <code>CFData</code> object containing the prelinked kernel image based 3221 * on the running kernel. 3222 * Returns <code>NULL</code> if <code>needAllFlag</code> is <code>true</code> 3223 * and any kext fails to link. 3224 */ 3225CF_EXPORT CFDataRef 3226OSKextCreatePrelinkedKernel( 3227 CFDataRef kernelImage, 3228 CFArrayRef kextArray, 3229 CFURLRef volumeRootURL, 3230 uint32_t flags, 3231 CFDictionaryRef * symbolsOut) 3232 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA); 3233 3234 3235__END_DECLS 3236 3237#endif /* __OSKEXT_H__ */ 3238