1.Dd November 14, 2012 2.Os Darwin 3.Dt KEXTCACHE 8 4.Sh NAME 5.Nm kextcache 6.Nd create kext cache files 7.Sh SYNOPSIS 8.Nm 9.Ar mkext_option Op Ar filename 10.Op Ar options 11.Op Fl - 12.Ar kext_or_directory Li \&.\|.\|. 13.Nm 14.Fl prelinked-kernel Ar filename 15.Op Ar options 16.Op Fl - 17.Op Ar kext_or_directory Li \&.\|.\|. 18.Nm 19.Fl system-prelinked-kernel 20.Op Ar options 21.Op Fl - 22.Op Ar kext_or_directory Li \&.\|.\|. 23.Nm 24.Fl system-caches 25.Op Ar options 26.Nm 27.Fl update-volume Ar os_volume 28.Op Ar options 29.Sh DESCRIPTION 30The 31.Nm 32program creates kext caches, which speed up kext loading operations. 33It is invoked automatically as needed to rebuild system caches. 34.Pp 35.Em Caution: 36Incorrect use of 37.Nm 38can render a volume incapable of startup. 39Installers and administrators should not use this program 40to update system kext caches. 41Instead they should run 42.Xr touch 1 43on the 44.Pa /System/Library/Extensions/ 45directory of the installation target volume after they have finished, 46which invalidates the existing caches and causes the system to 47update all necessary kext caches. 48.Nm 49.Fl update-volume 50can be used to wait for this process to complete. 51See 52.Dq "Apple Developer Technical Q&A QA1319: Installing an I/O Kit Kext Without Rebooting" 53for information on updating kext caches on prior releases of Mac OS X. 54.Pp 55.Nm 56creates several kinds of kext caches. 57The first is the prelinked kernel (also known as a \*(Lqkernelcache\*(Rq), 58which contains the kernel code 59and the essential files (info dictionary and executable) 60for an arbitrary set of kexts, 61with kext executables linked for their run-time locations. 62A prelinked kernel speeds early system startup 63by collecting these many files in one place for the booter to locate, 64and by having each kext linked in place and ready to start as needed. 65To create or update a prelinked kernel, use the 66.Fl prelinked-kernel 67or 68.Fl system-prelinked-kernel 69option. 70.Pp 71Other kext caches collect specific data 72from the info dictionaries of kexts. 73There are many individual caches for specific subsets of data; 74they care collectively called system info caches. 75These caches are used to optimize disk I/O when working with kexts 76during late system startup and beyond. 77To update the system kext info caches for the root volume, 78use the 79.Fl system-caches 80option. 81.Pp 82The last type of kext cache is the mkext cache, 83which contains the essential files (info dictionary and executable) 84for an arbitrary set of kexts; 85executables are unrelocated. 86Mkext is a legacy format that was used on prior releases of Mac OS X. 87To create an mkext cache, use one of the 88.Fl mkext , 89.Fl mkext1 , 90or 91.Fl mkext2 92options, 93with appropriate filtering options, described below. 94.Sh PRIMARY OPTIONS 95You must specify one of these options to have 96.Nm 97do anything: 98.Bl -tag -width -indent 99.It Fl c [ Ar filename ] , Fl prelinked-kernel Ar [ filename ] 100Create a prelinked kernel. 101.Ar filename 102is required unless this option is the last argument. 103If this option is the last argument and no 104.Ar filename 105is given, 106the startup prelinked kernel for the system is created. 107See 108.Fl all-loaded . 109.It Fl system-prelinked-kernel 110This option is a convenience to update the prelinked kernel 111used for startup on the root volume, 112with all kexts in /System/Library/Extensions and /Library/Extensions 113that have been loaded to date. 114This option implies 115.Fl all-loaded . 116.It Fl system-caches 117Rebuild the info caches for system kexts on the root volume. 118.It Fl i Ar os_volume , Fl invalidate Ar os_volume 119Rebuild out-of-date caches and update any helper partitions associated 120with 121.Ar os_volume . 122.Pp 123This option mimics sudo touch /System/Library/Extensions on 124.Ar os_volume . 125If 126.Nm 127cannot find or make sense of 128.Ar os_volume Ns Pa /usr/standalone/bootcaches.plist , 129the volume is treated as if no caches need updating: success is returned. 130.It Fl u Ar os_volume , Fl update-volume Ar os_volume 131Rebuild out-of-date caches and update any helper partitions associated 132with 133.Ar os_volume . 134.Ar os_volume Ns Pa /System/Library/Caches/com.apple.bootstamps/ 135is used as a cache of metadata from any helper partitions. 136See 137.Fl caches-only 138and 139.Fl force . 140.Pp 141Which caches are rebuilt depends on the Mac OS X release installed on 142.Ar os_volume . 143If 144.Nm 145cannot find or make sense of 146.Ar os_volume Ns Pa /usr/standalone/bootcaches.plist 147the volume is treated as if no caches need updating: success is returned. 148.It Fl U Ar os_volume 149Exit EX_OSFILE (72) if any updates were needed and were successfully made. 150.Fl U 151is used during system startup to check whether the cache from which the 152currently-running kernel was loaded is out of date. System startup 153interprets an EX_OSFILE exit code to mean that the system should be 154immediately rebooted off the newer kernel cache. 155.It Fl Boot 156Enable early boot behaviors such as not expecting 157.Xr kextd 8 158to be available. 159.It Fl m Ar filename , Fl mkext Ar filename 160Create an mkext of the latest supported format. 161.It Fl mkext1 Ar filename 162Create an mkext of format 1, used on Mac OS X versions 10.5 (Leopard) 163and earlier. 164.It Fl mkext2 Ar filename 165Create an mkext of format 2, used on Mac OS X version 10.6 (Snow Leopard). 166.It Fl e , Fl system-mkext 167This option is provided for legacy compatibility, and is simply an alias to 168.Fl system-prelinked-kernel . 169.El 170.Sh PRELINKED KERNEL AND MKEXT FILTERING OPTIONS 171These options restrict which kexts are included in a prelinked kernel or mkext. 172The options 173.Fl arch 174and 175.Fl bundle-id 176select kexts by supported architecture and bundle identifier; 177the remaining filtering options select kexts based on the value 178of their OSBundleRequired property. 179If these options are specified, 180the cache will contain only kexts 181whose OSBundleRequired property matches any of these options, 182or whose OSBundleRequired property is 183.Dq Root 184or 185.Dq Console . 186.Pp 187A prelinked kernel or mkext cache intended for a startup from a local disk 188should be created with the 189.Fl local-root 190option, while a cache intended for startup from the network 191should be created with the 192.Fl network-root 193option. 194When creating a prelinked kernel, 195if the 196.Fl all-loaded 197option is specified, 198kexts requested by the kernel are always included 199regardless of these filtering options. 200.Bl -tag -width -indent 201.It Fl a Ar arch , Fl arch Ar arch 202Include in an mkext or prelinked kernel only kexts 203loadable on 204.Ar arch , 205thinning executables to that architecture before inclusion. 206Multiple architectures are allowed; 207in this case a multi-architecture file is created 208containing an embedded cache 209for each of the specified architectures. 210If no architectures are specified, 211a default set of architectures supported 212by the current Mac OS X version is used (Mac OS X 10.6 and later). 213.It Fl b Ar identifier , Fl bundle-id Ar identifier 214Find the kext whose CFBundleIdentifier is 215.Ar identifier 216amongst known kexts and repository directories 217and include it in the mkext or prelinked kernel. 218The kext of the highest CFBundleVersion with the given identifier is used; 219in the case of version ties, 220the last such kext specified on the command line is used. 221This option may be specified multiple times; 222if so, the specified bundle identifiers select 223a subset from all named repositories and kexts, 224to which the remaining filters 225described in this section are then applied. 226.It Fl l , Fl local-root 227Specifies that for directory arguments, 228only extensions required for local disk boot 229be included in a cache. 230Kexts explicitly indicated by name or identifier 231are included unconditionally; 232to apply this filter to all kexts, use the 233.Fl local-root-all 234option. 235.It Fl L , Fl local-root-all 236Specifies that only extensions required for local disk boot 237be included in a cache, 238regardless of whether they are from a repository directory 239or are explicitly indicated by name or identifier. 240To apply this restriction only to kexts from repository directories, use the 241.Fl local-root 242option. 243.It Fl n , Fl network-root 244Specifies that for directory arguments, 245only extensions required for network disk boot 246be included in a cache. 247Kexts explicitly indicated by name or identifier 248are included unconditionally; 249to apply this filter to all kexts, use the 250.Fl network-root-all 251option. 252.It Fl N , Fl network-root-all 253Specifies that only extensions required for network disk boot 254be included in a cache, 255regardless of whether they are from a repository directory 256or are explicitly indicated by name or identifier. 257To apply this restriction only to kexts from repository directories, use the 258.Fl network-root 259option. 260.It Fl s , Fl safe-boot 261Specifies that for directory arguments, 262only extensions required for safe boot 263be included in a cache. 264Kexts explicitly indicated by name or identifier 265are included unconditionally; 266to apply this filter to all kexts, use the 267.Fl safe-boot-all 268option. 269.It Fl S , Fl safe-boot-all 270Specifies that only extensions required for safe boot 271be included in a cache, 272regardless of whether they are from a repository directory 273or are explicitly indicated by name or identifier. 274To apply this restriction only to kexts from repository directories, use the 275.Fl safe-boot 276option. 277.El 278.Sh OTHER OPTIONS AND ARGUMENTS 279.Bl -tag -width -indent 280.It Ar kext_or_directory 281A kext bundle or a repository directory containing kexts 282to consider for inclusion in an mkext or prelinked kernel. 283The filtering options described under 284.Dq PRELINKED KERNEL AND MKEXT FILTERING OPTIONS 285select the individual kexts to be included in the archive. 286If no filtering options are specified, then all kexts 287named as arguments are included (this is probably not what you want). 288.It Fl caches-only 289With 290.Fl update-volume , 291skips updating any helper partitions even if they appear out of to date. 292.It Fl f , Fl force 293With 294.Fl update-volume , 295rebuilds any helper partitions even if they appear up to date. If this 296version of 297.Nm 298does not understand 299.Pa bootcaches.plist 300well enough to be able to update the helpers, exit with EX_OSFILE (72). 301.It Fl Installer 302With 303.Fl update-volume , 304implies 305.Fl force 306while making helper partition updates optional. 307.It Fl F 308Run in low-priority mode, as when forked and executed by 309.Xr kextd 8 . 310(This used to actually fork, but no longer does, as 311.Xr kextd 8 312handles the forking.) 313.It Fl h , Fl help 314Print a help message describing each option flag and exit with a success result, 315regardless of any other options on the command line. 316.It Fl K Ar kernel_filename , Fl kernel Ar kernel_filename 317The name of the kernel file to use as the base 318of a prelinked kernel file (the default is 319.Pa /System/Library/Kernels/kernel Ns No ). 320.It Fl q , Fl quiet 321Quiet mode; print no informational or error messages. 322.It Fl r , Fl all-loaded 323When creating a prelinked kernel, 324include all kexts in /System/Library/Extensions and /Library/Extensions 325that have been loaded by the machine running 326this command during this startup session. 327This include kexts loaded and later unloaded. 328.It Fl compressed 329Compress the mkext or prelinked kernel (enabled by default). 330.It Fl uncompressed 331Do not compress the mkext or prelinked kernel. 332If specified as the only other argument with 333.Fl c , 334uncompresses an existing prelinked kernel file in place. 335.It Fl symbols Ar symbol_directory 336Generate symbols for every kext in the prelinked kernel and save them in 337.Ar symbol_directory . 338The directory must already exist. 339Symbol files are named after the CFBundleIdentifier 340of each kext with a 341.Pa .sym 342suffix attached. 343.It Fl t , Fl print-diagnostics 344If a kext has validation, authentication, or dependency resolution problems, 345print them. 346Note that tests are performed in three stages: 347validation, authentication, and dependency resolution; 348a failure at any stage can make tests in further stages impossible. 349Thus, a kext with validation failures may have unreported 350authentication problems or missing dependencies. 351.It Fl v Li [ 0-6 | 0x#### Ns Li ] , Fl verbose Li [ 0-6 | 0x#### Ns Li ] 352Verbose mode; print information about program operation. 353Higher levels of verbosity include all lower levels. 354By default 355.Nm 356prints only warnings and errors. 357You can specify a level from 0-6, 358or a hexadecimal log specification 359(as described in 360.Xr kext_logging 8 Ns No ). 361The levels of verbose output are: 362.Bl -tag -width "1 (or none)" 363.It 0 364Print only errors (that is, suppress warnings); see also 365.Fl quiet . 366.It 1 (or none) 367Print basic information about program operation. 368.It 2 369Print basic information about program progress and files created. 370.It 3 371Print information about individual kexts; 372for example, when a kext is added to or omitted from an archive. 373.It 4 374Print information about compression and architectures processed. 375.It 5 376Print debug-level information about internal operations. 377.It 6 378Identical to level 5 for 379.Nm . 380.El 381.Pp 382Unlike in other kext tools, 383the 384.Fl verbose 385flag in 386.Nm 387applies to all kexts 388(that is, it turns on hexadecimal bit 0x8 by default). 389See 390.Xr kext_logging 8 391for more information on verbose logging. 392.It Fl volume-root Ar path 393When creating caches for a volume other than the root volume, 394remove 395.Ar path 396from the beginning of absolute kext paths stored in the cache file. 397This ensures that the kext paths stored in the kernel are accurate 398when the caches are used for startup with that volume. 399.It Fl z , Fl no-authentication 400Don't authenticate kexts. 401This option is for convenience in building cache files. 402Caches used for startup must have 403proper ownership (root:wheel) and permissions (0644) 404in order to be used by the system. 405.It Fl - 406End of all options. Only kext or directory names follow. 407.El 408.Sh FILES 409.Bl -tag -width 410.It Pa /System/Library/Extensions/ 411The standard system repository of kernel extensions. 412.It Pa /Library/Extensions/ 413The standard repository of non Apple kernel extensions. 414.It Pa /System/Library/Caches/com.apple.kext.caches/ 415Contains all kext caches for a Mac OS X 10.6 system: prelinked kernel, 416mkext, and system kext info caches. 417.It Pa /System/Library/Kernels/kernel 418The default kernel file. 419.It Pa /usr/standalone/bootcaches.plist 420Describes specific kext cache files for a Mac OS X volume. 421.It Pa /System/Library/Caches/com.apple.bootstamps/ 422Contains timestamp information about kext caches. 423.El 424.Sh DIAGNOSTICS 425.Nm 426exits with a zero status upon success. 427Upon failure, it prints an error message 428and exits with a nonzero status. 429.Sh BUGS 430Many single-letter options are inconsistent in meaning 431with (or directly contradictory to) the same letter options 432in other kext tools. 433.Sh SEE ALSO 434.Xr mkextunpack 8 , 435.Xr kext_logging 8 , 436.Xr kextd 8 , 437.Xr kextload 8 , 438.Xr kextutil 8 , 439.Xr kextstat 8 , 440.Xr kextunload 8 441