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 u Ar os_volume , Fl update-volume Ar os_volume 119Rebuild out-of-date caches and update any helper partitions associated 120with 121.Ar os_volume . 122.Ar os_volume Ns Pa /System/Library/Caches/com.apple.bootstamps/ 123is used to track whether any helper partitions are up to date. 124See 125.Fl caches-only 126and 127.Fl force . 128.Pp 129Which caches are rebuilt depends on the Mac OS X release installed on 130.Ar os_volume . 131If 132.Nm 133cannot find or make sense of 134.Ar os_volume Ns Pa /usr/standalone/bootcaches.plist 135the volume is treated as if no caches need updating: success is returned. 136.It Fl U Ar os_volume 137A special exit code is returned if any updates were needed. 138.Fl U 139should only be used by the system during startup. 140.It Fl m Ar filename , Fl mkext Ar filename 141Create an mkext of the latest supported format. 142.It Fl mkext1 Ar filename 143Create an mkext of format 1, used on Mac OS X versions 10.5 (Leopard) 144and earlier. 145.It Fl mkext2 Ar filename 146Create an mkext of format 2, used on Mac OS X version 10.6 (Snow Leopard). 147.It Fl e , Fl system-mkext 148This option is provided for legacy compatibility, and is simply an alias to 149.Fl system-prelinked-kernel . 150.El 151.Sh PRELINKED KERNEL AND MKEXT FILTERING OPTIONS 152These options restrict which kexts are included in a prelinked kernel or mkext. 153The options 154.Fl arch 155and 156.Fl bundle-id 157select kexts by supported architecture and bundle identifier; 158the remaining filtering options select kexts based on the value 159of their OSBundleRequired property. 160If these options are specified, 161the cache will contain only kexts 162whose OSBundleRequired property matches any of these options, 163or whose OSBundleRequired property is 164.Dq Root 165or 166.Dq Console . 167.Pp 168A prelinked kernel or mkext cache intended for a startup from a local disk 169should be created with the 170.Fl local-root 171option, while a cache intended for startup from the network 172should be created with the 173.Fl network-root 174option. 175When creating a prelinked kernel, 176if the 177.Fl all-loaded 178option is specified, 179kexts requested by the kernel are always included 180regardless of these filtering options. 181.Bl -tag -width -indent 182.It Fl a Ar arch , Fl arch Ar arch 183Include in an mkext or prelinked kernel only kexts 184loadable on 185.Ar arch , 186thinning executables to that architecture before inclusion. 187Multiple architectures are allowed; 188in this case a multi-architecture file is created 189containing an embedded cache 190for each of the specified architectures. 191If no architectures are specified, 192a default set of architectures supported 193by the current Mac OS X version is used (Mac OS X 10.6 and later). 194.It Fl b Ar identifier , Fl bundle-id Ar identifier 195Find the kext whose CFBundleIdentifier is 196.Ar identifier 197amongst known kexts and repository directories 198and include it in the mkext or prelinked kernel. 199The kext of the highest CFBundleVersion with the given identifier is used; 200in the case of version ties, 201the last such kext specified on the command line is used. 202This option may be specified multiple times; 203if so, the specified bundle identifiers select 204a subset from all named repositories and kexts, 205to which the remaining filters 206described in this section are then applied. 207.It Fl l , Fl local-root 208Specifies that for directory arguments, 209only extensions required for local disk boot 210be included in a cache. 211Kexts explicitly indicated by name or identifier 212are included unconditionally; 213to apply this filter to all kexts, use the 214.Fl local-root-all 215option. 216.It Fl L , Fl local-root-all 217Specifies that only extensions required for local disk boot 218be included in a cache, 219regardless of whether they are from a repository directory 220or are explicitly indicated by name or identifier. 221To apply this restriction only to kexts from repository directories, use the 222.Fl local-root 223option. 224.It Fl n , Fl network-root 225Specifies that for directory arguments, 226only extensions required for network disk boot 227be included in a cache. 228Kexts explicitly indicated by name or identifier 229are included unconditionally; 230to apply this filter to all kexts, use the 231.Fl network-root-all 232option. 233.It Fl N , Fl network-root-all 234Specifies that only extensions required for network disk boot 235be included in a cache, 236regardless of whether they are from a repository directory 237or are explicitly indicated by name or identifier. 238To apply this restriction only to kexts from repository directories, use the 239.Fl network-root 240option. 241.It Fl s , Fl safe-boot 242Specifies that for directory arguments, 243only extensions required for safe boot 244be included in a cache. 245Kexts explicitly indicated by name or identifier 246are included unconditionally; 247to apply this filter to all kexts, use the 248.Fl safe-boot-all 249option. 250.It Fl S , Fl safe-boot-all 251Specifies that only extensions required for safe boot 252be included in a cache, 253regardless of whether they are from a repository directory 254or are explicitly indicated by name or identifier. 255To apply this restriction only to kexts from repository directories, use the 256.Fl safe-boot 257option. 258.El 259.Sh OTHER OPTIONS AND ARGUMENTS 260.Bl -tag -width -indent 261.It Ar kext_or_directory 262A kext bundle or a repository directory containing kexts 263to consider for inclusion in an mkext or prelinked kernel. 264The filtering options described under 265.Dq PRELINKED KERNEL AND MKEXT FILTERING OPTIONS 266select the individual kexts to be included in the archive. 267If no filtering options are specified, then all kexts 268named as arguments are included (this is probably not what you want). 269.It Fl caches-only 270With 271.Fl update-volume , 272skips updating any helper partitions even if they appear out of to date. 273.It Fl f , Fl force 274With 275.Fl update-volume , 276rebuilds any helper partitions even if they appear up to date. If this 277version of 278.Nm 279does not understand 280.Pa bootcaches.plist 281well enough to be able to update the helpers, exit with EX_OSFILE (72). 282.It Fl Installer 283With 284.Fl update-volume , 285implies 286.Fl force 287while making helper partition updates optional. 288.It Fl F 289Run in low-priority mode, as when forked and executed by 290.Xr kextd 8 . 291(This used to actually fork, but no longer does, as 292.Xr kextd 8 293handles the forking.) 294.It Fl h , Fl help 295Print a help message describing each option flag and exit with a success result, 296regardless of any other options on the command line. 297.It Fl K Ar kernel_filename , Fl kernel Ar kernel_filename 298The name of the kernel file to use as the base 299of a prelinked kernel file (the default is 300.Pa /mach_kernel Ns No ). 301.It Fl q , Fl quiet 302Quiet mode; print no informational or error messages. 303.It Fl r , Fl all-loaded 304When creating a prelinked kernel, 305include all kexts in /System/Library/Extensions and /Library/Extensions 306that have been loaded by the machine running 307this command during this startup session. 308This include kexts loaded and later unloaded. 309.It Fl compressed 310Compress the mkext or prelinked kernel (enabled by default). 311.It Fl uncompressed 312Do not compress the mkext or prelinked kernel. 313If specified as the only other argument with 314.Fl c , 315uncompresses an existing prelinked kernel file in place. 316.It Fl symbols Ar symbol_directory 317Generate symbols for every kext in the prelinked kernel and save them in 318.Ar symbol_directory . 319The directory must already exist. 320Symbol files are named after the CFBundleIdentifier 321of each kext with a 322.Pa .sym 323suffix attached. 324.It Fl t , Fl print-diagnostics 325If a kext has validation, authentication, or dependency resolution problems, 326print them. 327Note that tests are performed in three stages: 328validation, authentication, and dependency resolution; 329a failure at any stage can make tests in further stages impossible. 330Thus, a kext with validation failures may have unreported 331authentication problems or missing dependencies. 332.It Fl v Li [ 0-6 | 0x#### Ns Li ] , Fl verbose Li [ 0-6 | 0x#### Ns Li ] 333Verbose mode; print information about program operation. 334Higher levels of verbosity include all lower levels. 335By default 336.Nm 337prints only warnings and errors. 338You can specify a level from 0-6, 339or a hexadecimal log specification 340(as described in 341.Xr kext_logging 8 Ns No ). 342The levels of verbose output are: 343.Bl -tag -width "1 (or none)" 344.It 0 345Print only errors (that is, suppress warnings); see also 346.Fl quiet . 347.It 1 (or none) 348Print basic information about program operation. 349.It 2 350Print basic information about program progress and files created. 351.It 3 352Print information about individual kexts; 353for example, when a kext is added to or omitted from an archive. 354.It 4 355Print information about compression and architectures processed. 356.It 5 357Print debug-level information about internal operations. 358.It 6 359Identical to level 5 for 360.Nm . 361.El 362.Pp 363Unlike in other kext tools, 364the 365.Fl verbose 366flag in 367.Nm 368applies to all kexts 369(that is, it turns on hexadecimal bit 0x8 by default). 370See 371.Xr kext_logging 8 372for more information on verbose logging. 373.It Fl volume-root Ar path 374When creating caches for a volume other than the root volume, 375remove 376.Ar path 377from the beginning of absolute kext paths stored in the cache file. 378This ensures that the kext paths stored in the kernel are accurate 379when the caches are used for startup with that volume. 380.It Fl z , Fl no-authenticate 381Don't authenticate kexts. 382This option is for convenience in building cache files. 383Caches used for startup must have 384proper ownership (root:wheel) and permissions (0644) 385in order to be used by the system. 386.It Fl - 387End of all options. Only kext or directory names follow. 388.El 389.Sh FILES 390.Bl -tag -width 391.It Pa /System/Library/Extensions/ 392The standard system repository of kernel extensions. 393.It Pa /Library/Extensions/ 394The standard repository of non Apple kernel extensions. 395.It Pa /System/Library/Caches/com.apple.kext.caches/ 396Contains all kext caches for a Mac OS X 10.6 system: prelinked kernel, 397mkext, and system kext info caches. 398.It Pa /mach_kernel 399The default kernel file. 400.It Pa /usr/standalone/bootcaches.plist 401Describes specific kext cache files for a Mac OS X volume. 402.It Pa /System/Library/Caches/com.apple.bootstamps/ 403Contains timestamp information about kext caches. 404.El 405.Sh DIAGNOSTICS 406.Nm 407exits with a zero status upon success. 408Upon failure, it prints an error message 409and exits with a nonzero status. 410.Sh BUGS 411Many single-letter options are inconsistent in meaning 412with (or directly contradictory to) the same letter options 413in other kext tools. 414.Sh SEE ALSO 415.Xr mkextunpack 8 , 416.Xr kext_logging 8 , 417.Xr kextd 8 , 418.Xr kextload 8 , 419.Xr kextutil 8 , 420.Xr kextstat 8 , 421.Xr kextunload 8 422