KEXTCACHE(8) BSD System Manager's Manual KEXTCACHE(8)

NAME
     kkeexxttccaacchhee - creates or updates kext caches

SYNOPSIS
     kkeexxttccaacchhee [-aa arch] [-cc kernelcachefilename] [-ee] [-FF] [-hh] [-kk]
               [-KK kernelfilename] [-ll | -LL] [-mm mkextfilename] [-nn | -NN]
               [-rr] [-ss | -SS] [-tt] [-vv [1-6]] [-zz] [kextordirectory] ...
     kkeexxttccaacchhee [-vv [#]] [-ff] -uu osvolume
     kkeexxttccaacchhee [-vv [#]] -UU osvolume

DESCRIPTION
     The kkeexxttccaacchhee program creates or updates kext caches, which are used to
     speed up kext loading operations 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 ar-
     chives 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/Exten-
     sions 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 dictionaries 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 -mm 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 repos-
     itory 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 -kk 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 -cc option.

     kkeexxttccaacchhee accepts these arguments and options:

     kextordirectory
              A kext bundle or a repository directory containing kexts to add
              to the cache.  When using the -mm option only, any number may be
              specified.  When using the -kk option, only a single directory
              may be named.

     -aa arch  Include in an mkext archive only kexts whose executable files
              contain code for the given arch, stripping the binaries before
              inclusion.  If multiple -aa options are used, a multi-architec-
              ture file will be created containing an embedded mkext archive
              for each of the specified architectures.

     -cc kernelcachefilename
              The name of the kernel cache file to create. If none is speci-
              fied, a cache file is created in the /Sys-
              tem/Library/Caches/com.apple.kernelcaches/ folder.

     -ee       This option is a convenience to update the mkext cache for the
              /System/Library/Extensions folder.

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

     -ff       Used with -uu to specify that all caches should be updated
              regardless of cached timestamp information.

     -hh       Extended usage statement

     -kk       Create or update the kext repository cache for any repository
              directories specified.

     -KK kernelfilename
              The name of the kernel file to use as the base of a kernel cache
              file (default is /machkernel).

     -ll       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 uncondition-
              ally; to apply this restriction to all kexts, use the -LL option.
              May be combined with the -nn, -NN, -ss, or -SS options to archive
              network-root and safe boot extensions as well.

     -LL       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 -ll option.  May be combined with
              the -nn, -NN, -ss, or -SS options to archive network-root and safe
              boot extensions as well.

     -mm mkextfilename
              The name of the mkext cache file to create.

     -nn       Specifies that for directory arguments, only extensions required
              for network boot be included in an mkext cache.  Kexts explic-
              itly named on the command line are included unconditionally; to
              apply this restriction to all kexts, use the -NN option.  May be
              combined with the -ll, -LL, -ss, or -SS options to archive local-
              root and safe boot extensions as well.

     -NN       Specifies that only extensions required for network boot be
              included in an mkext cache.  To apply this restriction only to
              repository directories, use the -nn option.  May be combined with
              the -ll, -LL, -ss, or -SS options to archive local-root and safe
              boot extensions as well.

     -rr       Include all kexts that have been loaded by the machine running
              this command during this boot. This include kexts loaded and
              later unloaded.

     -ss       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 -SS option.  May be com-
              bined with the -ll, -LL, -nn, or -NN options to archive local- and
              network-root extensions as well.

     -SS       Specifies that only extensions required for safe boot be
              included in an mkext cache.  To apply this restriction only to
              repository directories, use the -ss option.  May be combined with
              the -ll, -LL, -nn, or -NN options to archive local- and network-root
              extensions as well.

     -tt       Perform all possible tests on the named kext(s) and indicate
              whether the kext is loadable (and therefore eligible for inclu-
              sion 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 validation
              failures may have unreported authentication problems or missing
              dependencies.

     -uu osvolume
              Update out of date caches and any helper partitions associated
              with osvolume.  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 par-
              titions are updated.  If -ff is also specified, all helper parti-
              tion 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).

     -UU osvolume
              Similar to -uu, except EXOSFILE (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.

     -vv [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 kkeexxttccaacchhee, 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 warn-
                   ings when a kext lacks architectures explicitly specified
                   using -aa; 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 info dictionary property.  Its
              values are 1 and 2, for basic and detailed information, respec-
              tively.

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

     --       End of all options. Only kext or directory names follow.

DIAGNOSTICS     kkeexxttccaacchhee 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, kkeexxttccaacchhee typically
     prints an error message about that kext, even if it isn't involved in the
     cacheing request.

Darwin                           April 8, 2002                          Darwin