KEXTCACHE(8) BSD System Manager's Manual KEXTCACHE(8)
NAME
kextcache -- creates or updates kext caches
SYNOPSIS
kextcache [-a arch] [-c kernel_cache_filename] [-e] [-F] [-h] [-k] [-K kernel_filename] [-l | -L]
[-m mkext_filename] [-n | -N] [-r] [-s | -S] [-t] [-v [1-6]] [-z] [kext_or_directory] ...
kextcache [-v [#]] [-f] -u os_volume
kextcache [-v [#]] -U os_volume
DESCRIPTION
The kextcache program creates or updates kext caches, which are used to speed up kext loading opera-tions operations
tions and to prepare kexts for inclusion in such media as device ROM. It is invoked automatically as
needed to rebuild the system caches, and can be used manually to build kext archives to be stored in
device ROM.
NOTE: Kernel extension installers should not use this program to update caches. Instead they should
merely touch(1) the /System/Library/Extensions directory after they have finished, which will cause the
system to update all necessary kernel extension caches.
There are three kinds of kext cache. The first is the mkext cache, which contains the info dictionar-ies dictionaries
ies and binary files for an arbitrary set of kexts. Mkext caches are used during early system startup
to load drivers essential to mounting the root filesystem and providing basic hardware services.
They're also used to package drivers in device ROM. To create an mkext cache use the -m option.
The second type of cache is the kext repository cache, which contains the info dictionaries for all the
kexts in a single repository directory, including their plugins, in a file with a .kextcache extension.
A repository cache speeds the startup of tools such as kextload(8) and kextd(8). A repository cache
must exist alongside its repository directory for the kext tools to find and use it. The kext tools
normally build or update repository caches as needed. To create or update a kext repository cache use
the -k option.
The third type of cache is the kernel cache, which contains the kernel code, linked kext code, and info
dictionaries for an arbitrary set of kexts. Having the kernel code and kexts already linked speeds the
startup of tools such as kextload(8) and kextd(8). To create or update a kernel cache use the -c
option.
kextcache accepts these arguments and options:
kext_or_directory
A kext bundle or a repository directory containing kexts to add to the cache. When using the
-m option only, any number may be specified. When using the -k option, only a single direc-tory directory
tory may be named.
-a arch Include in an mkext archive only kexts whose executable files contain code for the given arch,
stripping the binaries before inclusion. If multiple -a options are used, a multi-architec-ture multi-architecture
ture file will be created containing an embedded mkext archive for each of the specified
architectures.
-c kernel_cache_filename
The name of the kernel cache file to create. If none is specified, a cache file is created in
the /System/Library/Caches/com.apple.kernelcaches/ folder.
-e This option is a convenience to update the mkext cache for the /System/Library/Extensions
folder.
-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 handles the forking.)
-f Used with -u to specify that all caches should be updated regardless of cached timestamp
information.
-h Extended usage statement
-k Create or update the kext repository cache for any repository directories specified.
-K kernel_filename
The name of the kernel file to use as the base of a kernel cache file (default is /mach_ker-nel). /mach_kernel).
nel).
-l Specifies that for directory arguments, only extensions required for local disk boot be
included in an mkext cache. Kexts explicitly named on the command line are included uncondi-tionally; unconditionally;
tionally; to apply this restriction to all kexts, use the -L option. May be combined with the
-n, -N, -s, or -S options to archive network-root and safe boot extensions as well.
-L Specifies that only extensions required for local disk boot be included in an mkext cache. To
apply this restriction only to repository directories, use the -l option. May be combined
with the -n, -N, -s, or -S options to archive network-root and safe boot extensions as well.
-m mkext_filename
The name of the mkext cache file to create.
-n Specifies that for directory arguments, only extensions required for network boot be included
in an mkext cache. Kexts explicitly named on the command line are included unconditionally;
to apply this restriction to all kexts, use the -N option. May be combined with the -l, -L,
-s, or -S options to archive local-root and safe boot extensions as well.
-N Specifies that only extensions required for network boot be included in an mkext cache. To
apply this restriction only to repository directories, use the -n option. May be combined
with the -l, -L, -s, or -S options to archive local-root and safe boot extensions as well.
-r Include all kexts that have been loaded by the machine running this command during this boot.
This include kexts loaded and later unloaded.
-s Specifies that for directory arguments, only extensions required for safe boot be included in
an mkext cache. Kexts explicitly named on the command line are included unconditionally; to
apply this restriction to all kexts, use the -S option. May be combined with the -l, -L, -n,
or -N options to archive local- and network-root extensions as well.
-S Specifies that only extensions required for safe boot be included in an mkext cache. To apply
this restriction only to repository directories, use the -s option. May be combined with the
-l, -L, -n, or -N options to archive local- and network-root extensions as well.
-t Perform all possible tests on the named kext(s) and indicate whether the kext is loadable (and
therefore eligible for inclusion in the cache), or if not, what problems it has. 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 valida-tion validation
tion failures may have unreported authentication problems or missing dependencies.
-u os_volume
Update out of date caches and any helper partitions associated with os_volume. The mkext is
first checked and updated if needed (the updating sub-process will not inherit any verbose
flags). Then any modified files which belong in the helper partitions are updated. If -f is
also specified, all helper partition are fully updated regardless of whether the
com.apple.bootstamps data suggests that they are up to date. OS volumes without
/usr/standalone/bootcaches.plist are ignored (success is returned).
-U os_volume
Similar to -u, except EX_OSFILE (sysexits(3)) is returned after a helper partition update.
Also, no locks are taken with kextd(8), which means that it is only useful for its primary
purpose: determining during early boot whether updates and a reboot are needed to activate
kernel software which has been installed but not yet copied to the helper partitions.
-v [1-6]
Verbose mode; print information about the kext scanning and loading process. Higher levels of
verbosity include output from lower levels. For the purposes of kextcache, levels higher than
3 are not particularly relevant. The levels of verbose output are these:
1 prints basic kext scanning and archiving information
2 prints basic compression information
3 prints detailed kext scanning information, including warnings when a kext lacks architec-tures architectures
tures explicitly specified using -a; also uncompresses mkext cache entries to make sure
they do so without error
4 prints basic information on every kext encountered
5 prints detailed information on every kext encountered
6 prints detailed load information (not applicable)
A kext can also specify verbose printing for just itself using the OSBundleDebugLevel top-level toplevel
level info dictionary property. Its values are 1 and 2, for basic and detailed information,
respectively.
-z 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.
DIAGNOSTICS
kextcache exits with a zero status upon success. Upon failure, it prints an error message and exits
with a nonzero status.
SEE ALSO
kextd(8), kextload(8), kextstat(8), kextunload(8)
BUGS
Upon encountering a kext with validation errors, kextcache typically prints an error message about that
kext, even if it isn't involved in the cacheing request.
Darwin April 8, 2002 Darwin
|