Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.




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 -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 invalidates the existing caches and causes the system to update all necessary kext caches.
     kextcache -update-volume can be used to wait for this process to complete.  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 prelinked kernel (also known as a
     ``kernelcache''), which contains the kernel code and the essential files (info dictionary and exe-cutable) executable)
     cutable) for an arbitrary set of kexts, with kext executables linked for their run-time locations.  A
     prelinked kernel speeds early system startup by collecting these many files in one place for the booter
     to locate, and by having each kext linked in place and ready to start as needed.  To create or update a
     prelinked kernel, use the -prelinked-kernel or -system-prelinked-kernel option.

     Other kext caches collect specific data from the info dictionaries of kexts.  There are many individual
     caches for specific subsets of data; they care collectively called system info caches.  These caches
     are used to optimize disk I/O when working with kexts during late system startup and beyond.  To update
     the system kext info caches for the root volume, use the -system-caches option.

     The last type of kext cache is the mkext cache, which contains the essential files (info dictionary and
     executable) for an arbitrary set of kexts; executables are unrelocated.  Mkext is a legacy format that
     was used on prior releases of Mac OS X.  To create an mkext cache, use one of the -mkext, -mkext1, or
     -mkext2 options, with appropriate filtering options, described below.

PRIMARY OPTIONS
     You must specify one of these options to have kextcache do anything:

     -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 /System/Library/Extensions and /Library/Extensions 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 update any helper partitions associated with os_volume.
              os_volume/System/Library/Caches/com.apple.bootstamps/ is used to track whether any helper par-titions partitions
              titions are up to date.  See -caches-only and -force.

              Which caches are rebuilt depends on the Mac OS X release installed on os_volume.  If kextcache
              cannot find or make sense of os_volume/usr/standalone/bootcaches.plist the volume is treated
              as if no caches need updating: success is returned.

     -U os_volume
              A special exit code is returned if any updates were needed.  -U should only be used by the
              system during startup.

     -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 version 10.6 (Snow Leopard).

     -e, -system-mkext
              This option is provided for legacy compatibility, and is simply an alias to
              -system-prelinked-kernel.

PRELINKED KERNEL AND MKEXT FILTERING OPTIONS
     These options restrict which kexts are included in a prelinked kernel or mkext.  The options -arch and
     -bundle-id select kexts by supported architecture and bundle identifier; the remaining filtering
     options select kexts based on the value of their OSBundleRequired property.  If these options are spec-ified, specified,
     ified, the cache will contain only kexts whose OSBundleRequired property matches any of these options,
     or whose OSBundleRequired property is ``Root'' or ``Console''.

     A prelinked kernel or 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.  When creating a prelinked kernel, if the -all-loaded option is specified, kexts
     requested by the kernel are always included regardless of these filtering options.

     -a arch, -arch arch
              Include in an mkext or prelinked kernel only kexts loadable on arch, thinning executables to
              that architecture before inclusion.  Multiple architectures are allowed; in this case a multi-architecture multiarchitecture
              architecture file is created containing an embedded cache for each of the specified architec-tures. architectures.
              tures.  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.  The kext of the highest CFBundleVer-sion CFBundleVersion
              sion with the given identifier is used; in the case of version ties, the last such kext speci-fied specified
              fied on the command line is used.  This option may be specified multiple times; if so, the
              specified bundle identifiers select a subset from all named repositories and kexts, to which
              the remaining filters described in this section are then applied.

     -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 consider for inclusion in an mkext
              or prelinked kernel.  The filtering options described under ``PRELINKED KERNEL AND MKEXT
              FILTERING OPTIONS'' select the individual kexts to be included in the archive.  If no filter-ing filtering
              ing options are specified, then all kexts named as arguments are included (this is probably
              not what you want).

     -caches-only
              With -update-volume, skips updating any helper partitions even if they appear out of to date.

     -f, -force
              With -update-volume, rebuilds any helper partitions even if they appear up to date.  If this
              version of kextcache does not understand bootcaches.plist well enough to be able to update the
              helpers, exit with EX_OSFILE (72).

     -Installer
              With -update-volume, implies -force while making helper partition updates optional.

     -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.)

     -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 /System/Library/Extensions and
              /Library/Extensions 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 cache files.  Caches
              used for startup must have proper ownership (root:wheel) and permissions (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.

     /Library/Extensions/
        The standard repository of non Apple 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                         November 14, 2012                        Darwin

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback