|
|
This manual page is for Mac OS X version 10.6.3If you are running a different version of Mac OS X, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
KEXTCACHE(8) BSD System Manager's Manual KEXTCACHE(8)
NAME
kextcache -- create kext cache files
SYNOPSIS
kextcache mkext_option [filename] [options] [--] kext_or_directory ...
kextcache -system-mkext [options] [--] [kext_or_directory ...]
kextcache -prelinked-kernel filename [options] [--] [kext_or_directory ...]
kextcache -system-prelinked-kernel [options] [--] [kext_or_directory ...]
kextcache -system-caches [options]
kextcache -update-volume os_volume [options]
DESCRIPTION
The kextcache program creates kext caches, which speed up kext loading operations. It is invoked auto-matically automatically
matically as needed to rebuild system caches.
Caution: Incorrect use of kextcache can render a volume incapable of startup. Installers and adminis-trators administrators
trators should not use this program to update system kext caches. Instead they should run touch(1) on
the /System/Library/Extensions/ directory of the installation target volume after they have finished,
which causes the system to update all necessary kext caches. See ``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.
kextcache 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 -mkext,
-mkext1, -mkext2, or -system-mkext (with -local-root) options.
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 -prelinked-kernel or -system-prelinked-kernel
option.
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 -system-caches option.
PRIMARY OPTIONS
You must specify one of these options to have kextcache do anything:
-m filename, -mkext filename
Create an mkext of the latest supported format.
-mkext1 filename
Create an mkext of format 1, used on Mac OS X versions 10.5 (Leopard) and earlier.
-mkext2 filename
Create an mkext of format 2, used on Mac OS X versions 10.6 (Snow Leopard) and later.
-e, -system-mkext
This option is a convenience to update the startup mkext for the root volume. Using this
option with -local-root updates the startup mkext for a local disk startup.
-c [filename], -prelinked-kernel [filename]
Create a prelinked kernel. filename is required unless this option is the last argument. If
this option is the last argument and no filename is given, the startup prelinked kernel for
the system is created. See -all-loaded.
-system-prelinked-kernel
This option is a convenience to update the prelinked kernel used for startup on the root vol-ume, volume,
ume, with all kexts in the system extensions folder that have been loaded to date. This
option implies -all-loaded.
-system-caches
Rebuild the info caches for system kexts on the root volume.
-u os_volume, -update-volume os_volume
Rebuild out-of-date caches and any helper partitions associated with os_volume. The mkext is
first checked and updated if needed. Then any modified files that belong in the helper parti-tions partitions
tions are updated. If -force is also specified, all helper partition are fully updated
regardless of whether the data in /System/Library/Caches/com.apple.bootstamps/ suggests that
they are up to date. OS volumes without a /usr/standalone/bootcaches.plist file are ignored
(success is returned).
-U os_volume
Used by the system to update volumes during startup. Not for use otherwise.
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 ``Root'' or ``Console''.
An mkext cache intended for a startup from a local disk should be created with the -local-root option,
while a cache intended for startup from the network should be created with the -network-root option.
-l, -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 uncondi-tionally; unconditionally;
tionally; to apply this filter to all kexts, use the -local-root-all option.
-L, -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 identi-fier. identifier.
fier. To apply this restriction only to kexts from repository directories, use the
-local-root option.
-n, -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 uncondi-tionally; unconditionally;
tionally; to apply this filter to all kexts, use the -network-root-all option.
-N, -network-root-all
Specifies that only extensions required for network disk boot be included in a cache, regard-less regardless
less 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
-network-root option.
-s, -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 -safe-boot-all option.
-S, -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 identi-fier. identifier.
fier. To apply this restriction only to kexts from repository directories, use the -safe-boot
option.
OTHER OPTIONS AND ARGUMENTS
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 ``MKEXT FILTERING OPTIONS'' may prevent a kext
from being included in an mkext.
-a arch, -arch arch
Include in an mkext or prelinked kernel only kexts whose executable files contain code for
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 ar-chive archive
chive 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).
-b identifier, -bundle-id identifier
Find the kext whose CFBundleIdentifier is identifier amongst known kexts and repository direc-tories directories
tories and include it in the mkext or prelinked kernel. This option may be specified multiple
times. The filtering options described under ``MKEXT FILTERING OPTIONS'' may prevent a kext
from being included in an mkext.
-F Run in low-priority mode, as when forked and executed by kextd(8). (This used to actually
fork, but no longer does, as kextd(8) handles the forking.)
-f, -force
Used with -update-volume to specify that all caches on a helper partition should be updated
regardless of cached timestamp information.
-h, -help
Print a help message describing each option flag and exit with a success result, regardless of
any other options on the command line.
-K kernel_filename, -kernel kernel_filename
The name of the kernel file to use as the base of a prelinked kernel file (the default is
/mach_kernel).
-q, -quiet
Quiet mode; print no informational or error messages.
-r, -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.
-compressed
Compress the mkext or prelinked kernel. (Enabled by default.)
-uncompressed
Do not compress the mkext or prelinked kernel. If specified as the only other argument with
-c, uncompresses an existing prelinked kernel file in place.
-symbols symbol_directory
Generate symbols for every kext in the prelinked kernel and save them in symbol_directory.
The directory must already exist. Symbol files are named after the CFBundleIdentifier of each
kext with a .sym suffix attached.
-t, -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 resolu-tion; resolution;
tion; 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.
-v [0-6 | 0x####], -verbose [0-6 | 0x####]
Verbose mode; print information about program operation. Higher levels of verbosity include
all lower levels. By default kextcache prints only warnings and errors. You can specify a
level from 0-6, or a hexadecimal log specification (as described in kext_logging(8)). The lev-els levels
els of verbose output are:
0 Print only errors (that is, suppress warnings); see also -quiet.
1 (or none) Print basic information about program operation.
2 Print basic information about program progress and files created.
3 Print information about individual kexts; for example, when a kext is added to or
omitted from an archive.
4 Print information about compression and architectures processed.
5 Print debug-level information about internal operations.
6 Identical to level 5 for kextcache.
Unlike in other kext tools, the -verbose flag in kextcache applies to all kexts (that is, it
turns on hexadecimal bit 0x8 by default). See kext_logging(8) for more information on verbose
logging.
-volume-root path
When creating caches for a volume other than the root volume, remove 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.
-z, -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 permis-sions permissions
sions (0644) in order to be used by the system.
-- End of all options. Only kext or directory names follow.
FILES
/System/Library/Extensions/
The standard system repository of kernel extensions.
/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.
/mach_kernel
The default kernel file.
/usr/standalone/bootcaches.plist
Describes specific kext cache files for a Mac OS X volume.
/System/Library/Caches/com.apple.bootstamps/
Contains timestamp information about kext caches.
DIAGNOSTICS
kextcache exits with a zero status upon success. Upon failure, it prints an error message and exits
with a nonzero status.
BUGS
Many single-letter options are inconsistent in meaning with (or directly contradictory to) the same
letter options in other kext tools.
SEE ALSO
mkextunpack(8), kext_logging(8), kextd(8), kextload(8), kextutil(8), kextstat(8), kextunload(8)
Darwin March 6, 2009 Darwin
|
The way to report a problem with this manual page depends on the type of problem: