.Dd March 6, 2009 .Os Darwin .Dt KEXTCACHE 8 .Sh NAME .Nm kextcache .Nd create kext cache files .Sh SYNOPSIS .Nm .Ar mkext_option Op Ar filename .Op Ar options .Op Fl - .Ar kext_or_directory Li \&.\|.\|. .Nm .Fl system-mkext .Op Ar options .Op Fl - .Op Ar kext_or_directory Li \&.\|.\|. .Nm .Fl prelinked-kernel Ar filename .Op Ar options .Op Fl - .Op Ar kext_or_directory Li \&.\|.\|. .Nm .Fl system-prelinked-kernel .Op Ar options .Op Fl - .Op Ar kext_or_directory Li \&.\|.\|. .Nm .Fl system-caches .Op Ar options .Nm .Fl update-volume Ar os_volume .Op Ar options .Sh DESCRIPTION The .Nm program creates kext caches, which speed up kext loading operations. It is invoked automatically as needed to rebuild system caches. .Pp .Em Caution: Incorrect use of .Nm can render a volume incapable of startup. Installers and administrators should not use this program to update system kext caches. Instead they should run .Xr touch 1 on the .Pa /System/Library/Extensions/ directory of the installation target volume after they have finished, which causes the system to update all necessary kext caches. See .Dq "Apple Developer Technical Q&A QA1319: Installing an I/O Kit Kext Without Rebooting" for information on updating kext caches on prior releases of Mac OS X. .Pp .Nm creates several kinds of kext caches. The first is the mkext cache, which contains the essential files (Info plist and executable) for an arbitrary set of kexts; executables are unrelocated. Mkext caches are used during early system startup to load drivers essential for mounting the root filesystem and providing basic hardware services. To create an mkext cache use one of the .Fl mkext , .Fl mkext1 , .Fl mkext2 , or .Fl system-mkext (with .Fl local-root ) options. .Pp The second type of cache is the prelinked kernel, which contains the kernel code, kext executables already linked for their run-time locations, and other essential kext files for an arbitrary set of kexts. To create or update a prelinked kernel use the .Fl prelinked-kernel or .Fl system-prelinked-kernel option. .Pp The remaining caches contain specific information from the info dictionaries of system kexts, and are used to optimize disk I/O when working with kexts. To update the system kext info caches for the root volume, use the .Fl system-caches option. .Sh PRIMARY OPTIONS You must specify one of these options to have .Nm do anything: .Bl -tag -width -indent .It Fl m Ar filename , Fl mkext Ar filename Create an mkext of the latest supported format. .It Fl mkext1 Ar filename Create an mkext of format 1, used on Mac OS X versions 10.5 (Leopard) and earlier. .It Fl mkext2 Ar filename Create an mkext of format 2, used on Mac OS X versions 10.6 (Snow Leopard) and later. .It Fl e , Fl system-mkext This option is a convenience to update the startup mkext for the root volume. Using this option with .Fl local-root updates the startup mkext for a local disk startup. .It Fl c [ Ar filename ] , Fl prelinked-kernel Ar [ filename ] Create a prelinked kernel. .Ar filename is required unless this option is the last argument. If this option is the last argument and no .Ar filename is given, the startup prelinked kernel for the system is created. See .Fl all-loaded . .It Fl system-prelinked-kernel This option is a convenience to update the prelinked kernel used for startup on the root volume, with all kexts in the system extensions folder that have been loaded to date. This option implies .Fl all-loaded . .It Fl system-caches Rebuild the info caches for system kexts on the root volume. .It Fl u Ar os_volume , Fl update-volume Ar os_volume Rebuild out-of-date caches and any helper partitions associated with .Ar os_volume . The mkext is first checked and updated if needed. Then any modified files that belong in the helper partitions are updated. If .Fl force is also specified, all helper partition are fully updated regardless of whether the data in .Pa /System/Library/Caches/com.apple.bootstamps/ suggests that they are up to date. OS volumes without a .Pa /usr/standalone/bootcaches.plist file are ignored (success is returned). .It Fl U Ar os_volume Used by the system to update volumes during startup. Not for use otherwise. .El .Sh MKEXT FILTERING OPTIONS These options restrict which kexts are included in an mkext. If these options are specified, the cache will contain only kexts whose OSBundleRequired property matches any of these options, or whose OSBundleRequired property is .Dq Root or .Dq Console . .Pp An mkext cache intended for a startup from a local disk should be created with the .Fl local-root option, while a cache intended for startup from the network should be created with the .Fl network-root option. .Bl -tag -width -indent .It Fl l , Fl local-root Specifies that for directory arguments, only extensions required for local disk boot be included in a cache. Kexts explicitly indicated by name or identifier are included unconditionally; to apply this filter to all kexts, use the .Fl local-root-all option. .It Fl L , Fl local-root-all Specifies that only extensions required for local disk boot be included in a cache, regardless of whether they are from a repository directory or are explicitly indicated by name or identifier. To apply this restriction only to kexts from repository directories, use the .Fl local-root option. .It Fl n , Fl network-root Specifies that for directory arguments, only extensions required for network disk boot be included in a cache. Kexts explicitly indicated by name or identifier are included unconditionally; to apply this filter to all kexts, use the .Fl network-root-all option. .It Fl N , Fl network-root-all Specifies that only extensions required for network disk boot be included in a cache, regardless of whether they are from a repository directory or are explicitly indicated by name or identifier. To apply this restriction only to kexts from repository directories, use the .Fl network-root option. .It Fl s , Fl safe-boot Specifies that for directory arguments, only extensions required for safe boot be included in a cache. Kexts explicitly indicated by name or identifier are included unconditionally; to apply this filter to all kexts, use the .Fl safe-boot-all option. .It Fl S , Fl safe-boot-all Specifies that only extensions required for safe boot be included in a cache, regardless of whether they are from a repository directory or are explicitly indicated by name or identifier. To apply this restriction only to kexts from repository directories, use the .Fl safe-boot option. .El .Sh OTHER OPTIONS AND ARGUMENTS .Bl -tag -width -indent .It Ar kext_or_directory A kext bundle or a repository directory containing kexts to include in an mkext or prelinked kernel. The filtering options described under .Dq MKEXT FILTERING OPTIONS may prevent a kext from being included in an mkext. .It Fl a Ar arch , Fl arch Ar arch Include in an mkext or prelinked kernel only kexts whose executable files contain code for .Ar arch , thinning the executables to that architecture before inclusion. Only one architecture is allowed when creating a prelinked kernel. Multiple architectures are allowed when creating an mkext; in this case a multi-architecture file is created containing an embedded mkext archive for each of the specified architectures. If no architectures are specified, a default set of architectures supported by the current Mac OS X version is used (Mac OS X 10.6 and later). .It Fl b Ar identifier , Fl bundle-id Ar identifier Find the kext whose CFBundleIdentifier is .Ar identifier amongst known kexts and repository directories and include it in the mkext or prelinked kernel. This option may be specified multiple times. The filtering options described under .Dq MKEXT FILTERING OPTIONS may prevent a kext from being included in an mkext. .It Fl F Run in low-priority mode, as when forked and executed by .Xr kextd 8 . (This used to actually fork, but no longer does, as .Xr kextd 8 handles the forking.) .It Fl f , Fl force Used with .Fl update-volume to specify that all caches on a helper partition should be updated regardless of cached timestamp information. .It Fl h , Fl help Print a help message describing each option flag and exit with a success result, regardless of any other options on the command line. .It Fl K Ar kernel_filename , Fl kernel Ar kernel_filename The name of the kernel file to use as the base of a prelinked kernel file (the default is .Pa /mach_kernel Ns No ). .It Fl q , Fl quiet Quiet mode; print no informational or error messages. .It Fl r , Fl all-loaded When creating a prelinked kernel, include all kexts in the system extensions folder that have been loaded by the machine running this command during this startup session. This include kexts loaded and later unloaded. .It Fl compressed Compress the mkext or prelinked kernel. (Enabled by default.) .It Fl uncompressed Do not compress the mkext or prelinked kernel. If specified as the only other argument with .Fl c , uncompresses an existing prelinked kernel file in place. .It Fl symbols Ar symbol_directory Generate symbols for every kext in the prelinked kernel and save them in .Ar symbol_directory . The directory must already exist. Symbol files are named after the CFBundleIdentifier of each kext with a .Pa .sym suffix attached. .It Fl t , Fl print-diagnostics If a kext has validation, authentication, or dependency resolution problems, print them. Note that tests are performed in three stages: validation, authentication, and dependency resolution; a failure at any stage can make tests in further stages impossible. Thus, a kext with validation failures may have unreported authentication problems or missing dependencies. .It Fl v Li [ 0-6 | 0x#### Ns Li ] , Fl verbose Li [ 0-6 | 0x#### Ns Li ] Verbose mode; print information about program operation. Higher levels of verbosity include all lower levels. By default .Nm prints only warnings and errors. You can specify a level from 0-6, or a hexadecimal log specification (as described in .Xr kext_logging 8 Ns No ). The levels of verbose output are: .Bl -tag -width "1 (or none)" .It 0 Print only errors (that is, suppress warnings); see also .Fl quiet . .It 1 (or none) Print basic information about program operation. .It 2 Print basic information about program progress and files created. .It 3 Print information about individual kexts; for example, when a kext is added to or omitted from an archive. .It 4 Print information about compression and architectures processed. .It 5 Print debug-level information about internal operations. .It 6 Identical to level 5 for .Nm . .El .Pp Unlike in other kext tools, the .Fl verbose flag in .Nm applies to all kexts (that is, it turns on hexadecimal bit 0x8 by default). See .Xr kext_logging 8 for more information on verbose logging. .It Fl volume-root Ar path When creating caches for a volume other than the root volume, remove .Ar path from the beginning of absolute kext paths stored in the cache file. This ensures that the kext paths stored in the kernel are accurate when the caches are used for startup with that volume. .It Fl z , Fl no-authenticate Don't authenticate kexts. This option is for convenience in building archive and cache files. Mkext archives and kext repository caches must have proper ownership (root:wheel) and permissions (0644) in order to be used by the system. .It Fl - End of all options. Only kext or directory names follow. .El .Sh FILES .Bl -tag -width .It Pa /System/Library/Extensions/ The standard system repository of kernel extensions. .It Pa /System/Library/Caches/com.apple.kext.caches/ Contains all kext caches for a Mac OS X 10.6 system: prelinked kernel, mkext, and system kext info caches. .It Pa /mach_kernel The default kernel file. .It Pa /usr/standalone/bootcaches.plist Describes specific kext cache files for a Mac OS X volume. .It Pa /System/Library/Caches/com.apple.bootstamps/ Contains timestamp information about kext caches. .El .Sh DIAGNOSTICS .Nm exits with a zero status upon success. Upon failure, it prints an error message and exits with a nonzero status. .Sh BUGS Many single-letter options are inconsistent in meaning with (or directly contradictory to) the same letter options in other kext tools. .Sh SEE ALSO .Xr mkextunpack 8 , .Xr kext_logging 8 , .Xr kextd 8 , .Xr kextload 8 , .Xr kextutil 8 , .Xr kextstat 8 , .Xr kextunload 8