manpagez: man pages & more
man kextcache(8)
Home | html | info | man
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 automatically as needed to rebuild system
     caches.

     Caution: Incorrect use of kextcache can render a volume incapable of
     startup.  Installers and administrators 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 pre-
     linked kernel (also known as a ``kernelcache''), which contains the ker-
     nel code and the essential files (info dictionary and executable) 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 essen-
     tial 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 argu-
              ment 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 volume, 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 update any helper partitions
              associated with os_volume.
              os_volume/System/Library/Caches/com.apple.bootstamps/ is used to
              track whether any helper partitions 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
              Used by the system to update volumes during startup.  Not for
              use otherwise.

     -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 archi-
     tecture and bundle identifier; the remaining filtering options select
     kexts based on the value of their OSBundleRequired property.  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''.

     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 inclu-
              sion.  Multiple architectures are allowed; in this case a multi-
              architecture file is created containing an embedded cache for
              each of the specified architectures.  If no architectures are
              specified, a default set of architectures supported by the cur-
              rent 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 directories and include it in the
              mkext or prelinked kernel.  The kext of the highest CFBundleVer-
              sion with the given identifier is used; in the case of version
              ties, the last such kext specified on the command line is used.
              This option may be specified multiple times; if so, the speci-
              fied bundle identifiers select a subset from all named reposito-
              ries and kexts, to which the remaining filters described in this
              section are then applied.

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

     -force   With -update-volume, rebuilds any helper partitions even if they
              appear up to date.

     -Installer
              Currently used with -update-volume to trigger "best effort"
              behaviors for Apple's Installer.

     -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 unconditionally; 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
              identifier.  To apply this restriction only to kexts from repos-
              itory 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 unconditionally; 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, 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 repos-
              itory 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 indi-
              cated 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
              identifier.  To apply this restriction only to kexts from repos-
              itory directories, use the -safe-boot option.


OTHER OPTIONS AND ARGUMENTS

     kext_or_directory
              A kext bundle or a repository directory containing kexts to con-
              sider for inclusion in an mkext or prelinked kernel.  The fil-
              tering options described under ``PRELINKED KERNEL AND MKEXT
              FILTERING OPTIONS'' select the individual kexts to be included
              in the archive.  If no filtering options are specified, then all
              kexts named as arguments are included (this is probably not what
              you want).

     -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 sys-
              tem extensions folder that have been loaded by the machine run-
              ning 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 pre-
              linked 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 resolu-
              tion problems, print them.  Note that tests are performed in
              three stages: validation, authentication, and dependency resolu-
              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 levels 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 exam-
                           ple, when a kext is added to or omitted from an ar-
                           chive.

              4            Print information about compression and architec-
                           tures processed.

              5            Print debug-level information about internal opera-
                           tions.

              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 ver-
              bose 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.

     /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

Mac OS X 10.7 - Generated Thu Sep 1 10:49:05 CDT 2011
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.