1.Dd November 14, 2012 2.Os Darwin 3.Dt KEXTFIND 8 4.Sh NAME 5.Nm kextfind 6.Nd find kernel extensions (kexts) based on a variety of criteria and print information 7.Sh SYNOPSIS 8.Nm 9.Op Ar options 10.Op Fl - 11.Op Ar kext_or_directory Li \&.\|.\|. 12.Op Ar query 13.Op Fl report Oo Fl no-header Oc Ar report_predicate Li \&.\|.\|. 14.Sh DESCRIPTION 15The 16.Nm 17utility locates and prints information, or generates reports, 18about kernel extensions (kexts) 19matching the search criteria in 20.Ar query 21from among those in the named directory and extension arguments. 22If no directories or extensions are specified, 23.Nm 24searches /System/Library/Extensions and /Library/Extensions. 25Searches are performed via kext management logic 26as used by 27.Xr kextload 8 28and 29.Xr kextd 8 , 30by which only kexts directly in the repository directory 31or kexts explicitly named 32(and their immediate plugins) are eligible; 33this is specifically not an exhaustive, recursive filesystem search. 34.Pp 35Construct your search using any of the 36query and command predicates listed below. 37You can combine predicates with the 38logical operators 39.Fl and , 40.Fl or , 41and 42.Fl not , 43and group them with parentheses. 44.Pp 45Query command predicates generally print 46some bit of information about a kext, 47such as its pathname or bundle identifier, 48followed by either a newline or an ASCII NUL. 49You can also generate a tab-delimited report 50using the 51.Fl report 52keyword after the query expression; 53if you do, you must not specify 54any of the command predicates described below. 55.Pp 56If no command predicate or report is specified, 57.Nm 58implicitly executes a 59.Fl print 60command predicate for each kext matching the query. 61.Sh OPTIONS 62.Bl -tag -width indent -compact 63.It Fl h , Fl help 64Print a help message describing each option flag and exit with a success result, 65regardless of any other options on the command line. 66.It Fl set-arch Ar arch 67Set the architecture used for such things as architecture-specific 68properties to 69.Ar arch . 70You can only perform a query with one such architecture; 71searches for multiple executable architectures are possible, 72for example, 73but you can't search for two architecture-specific values 74of a single property. 75.It Fl i , Fl case-insensitive 76Perform case-insensitive comparisons for all property, match property, 77and bundle identifier query predicates when values are strings. 78Has no effect when property values are numbers or booleans. 79You can also use this option with individual property query predicates. 80.It Fl s , Fl substring 81Perform substring searches for all property, match property, 82and bundle identifier query predicates when values are strings. 83Has no effect when property values are numbers or booleans. 84You can also use this option with individual property query predicates. 85.It Fl no-paths 86Print no paths for kexts, just their bundle names, 87and for info dictionary and executable files, 88their paths relative to the kext itself. 89This can be ambiguous with plugins of the same name 90and when searching multiple repositories. 91.It Fl relative-paths 92Print pathnames relative to kexts' repositories 93(which can be ambiguous if multiple repositories are being searched). 94.It Fl 0 , Fl nul 95Make the 96.Fl echo 97and all 98.Fl print Ns \&.\|.\|. 99command predicates except for 100.Fl print-diagnostics 101emit an ASCII NUL character (character code 0) 102in place of any newlines. 103This is useful when sending the output to 104.Xr xargs 1 . 105You can also use this flag individually with those command predicates. 106.It Fl f Ar kext_or_directory , Fl search-item Ar kext_or_directory 107Specifies a kext or directory of kexts to search. 108May be specified multiple times. 109While you can normally just list them 110without an option flag, 111these are provided to prevent ambiguity with the query expression. 112.It Fl e , Fl system-extensions 113Adds /System/Library/Extensions and /Library/Extensions to the list of directories to search. 114If you don't specify any directories or kexts, this is used by default. 115.It Fl - 116End of options. 117.El 118.Sh QUERY PREDICATES 119Descriptions of all available search criteria and commands follow, 120grouped by general category. 121.Sh Search by Bundle Name, or Info Dictionary or Match (Personality) Properties 122Most of these predicates take the 123.Fl case-insensitive Li ( Ns Fl i Ns Li ) 124and 125.Fl substring Li ( Ns Fl s Ns Li ) 126options as described above. 127.Pp 128.Bl -tag -width indent -compact 129.It Fl b Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar identifier 130.It Fl bundle-id Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar identifier 131True if the kext's bundle identifier matches 132.Ar identifier . 133This is equivalent to 134.Fl property Cm CFBundleIdentifier Ar identifier Ns Li . 135.It Fl dup 136.It Fl duplicate-id 137True if any other kext has the same bundle identifier as the current kext. 138.It Fl B Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar name 139.It Fl bundle-name Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar name 140True if the kext's bundle name matches 141.Ar name . 142.It Fl m Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar name value 143.It Fl match-property Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar name Ar value 144True if the kext has at least one personality 145that contains 146.Ar value 147as a string, number, or boolean value 148(expressible as 149.Dq Li true , 150.Dq Li yes , 151.Dq Li 1 152or 153.Dq Li false , 154.Dq Li no , 155.Dq Li 0 ) 156for the named property. 157.It Fl me Ar name 158.It Fl match-property-exists Ar name 159True if the kext has at least one personality 160containing any value for the named property. 161.It Fl p Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar name Ar value 162.It Fl property Oo Fl i Ns Li | Ns Fl case-insensitive Oc Oo Fl s Ns Li | Ns Fl substring Oc Ar name Ar value 163True if the kext's info dictionary contains 164.Ar value 165as a string, number, or boolean value 166(expressible as 167.Dq Li true , 168.Dq Li yes , 169.Dq Li 1 170or 171.Dq Li false , 172.Dq Li no , 173.Dq Li 0 ) 174for the named property. 175.It Fl pe Ar name 176.It Fl property-exists Ar name 177True if the kext's info dictionary 178contains any value for the named property. 179.El 180.Sh Search by Loaded/Loadable 181.Bl -tag -width indent -compact 182.It Fl a , Fl authentic 183True if the kext is owned by root:wheel and has proper permissions. 184.It Fl d , Fl dependencies-met 185True if the kext has all its dependencies met. 186.It Fl nd , Fl dependencies-missing 187True if the kext is missing dependencies 188(or can't have its dependencies resolved). 189.It Fl na , Fl inauthentic 190True if the kext is not owned by root:wheel or has improper permissions 191(or can't be so authenticated). 192.It Fl nv , Fl invalid 193True if the kext is not valid. 194.It Fl l , Fl loadable 195True if the kext appears to be loadable. 196(It may still fail to load due to link errors.) 197.It Fl loaded 198True if the kext is currently loaded 199(if its bundle identifier, version, and executable UUID match 200a kext loaded in the kernel). 201.It Fl nl , Fl nonloadable 202True if the kext can't be loaded because it is invalid, inauthentic, 203or missing dependencies. 204.It Fl v , Fl valid 205True if the kext is valid. 206.It Fl w , Fl warnings 207True if any warnings are noted while validating the kext. 208.El 209.Sh Search by Executable, Architecture, or Symbol 210.Bl -tag -width indent -compact 211.It Fl arch Ar arch1 Ns Oo Ns Cm , Ns Ar arch2 Ns Li \&.\|.\|. Oc 212True if the kext contains 213all of the named CPU architectures (separated by commas only with no spaces), 214and possibly others, 215in its executable. 216.It Fl ax Ar arch1 Ns Oo Ns Cm , Ns Ar arch2 Ns Li \&.\|.\|. Oc , Fl arch-exact Ar arch1 Ns Oo Ns Cm , Ns Ar arch2 Ns Li \&.\|.\|. Oc 217True if the kext contains 218.Em all 219of the named CPU architectures (separated by commas only with no spaces), 220and no others, 221in its executable. 222.It Fl dsym Ar symbol , Fl defines-symbol Ar symbol 223True if the kext defines the named 224.Ar symbol 225in any of its architectures. 226The name must match exactly 227with the (possibly mangled) symbol 228in the kext's executable. 229Such names typically begin with at lease one underscore; 230see 231.Xr nm 1 . 232A kext must also be a library for others to link against it 233(see 234.Fl "library" Ns ). 235.It Fl x , Fl executable 236True if the kext declares an executable via the CFBundleExecutable property 237(whether it actually has one or not; 238that is, if the kext declares one but it's missing, 239this predicate is true even though the kext is invalid). 240.It Fl nx , Fl no-executable 241True if the kext does not declare an executable via the CFBundleExecutable property. 242.It Fl rsym Ar symbol , Fl references-symbol Ar symbol 243True if the kext has an undefined reference to the named 244.Ar symbol 245in any of its architectures. 246The name must match exactly 247with the (possibly mangled) symbol 248in the kext's executable. 249Such names typically begin with at lease one underscore; 250see 251.Xr nm 1 . 252.El 253.Sh Search by Miscellaneous Attribute 254.Bl -tag -width indent -compact 255.It Fl debug 256True if the kext has a top-level OSBundleEnableKextLogging property set to true, 257or if any of its personalities has an IOKitDebug property other than zero. 258(Note: As of Mac OS X 10.6 (Snow Leopard), the property OSBundleDebugLevel is no longer used.) 259.It Fl has-plugins 260True if the kext contains plugins. 261.It Fl integrity Li { Cm correct Ns | Ns Cm modified Ns | Ns Cm no-receipt Ns | Ns Cm not-apple Ns | Ns Cm unknown Li } 262OBSOLETE. As of Mac OS X 10.6 (Snow Leopard), 263kext integrity is not used and this predicate always evaluates to false. 264.It Fl kernel-resource 265True if the kext represents a resource built into the kernel. 266.It Fl lib , Fl library 267True if the kext is a library that other kexts can link against. 268.It Fl plugin 269True if the kext is a plugin of another kext. 270.El 271.Sh Search by Startup Requirement 272These options find kexts that are used at startup or allowed 273to load during safe boot. 274They should be combined with the 275.Fl or 276operator. 277(The standard system mkext file contains 278console, local-root, and root kexts, 279so you would specify 280.Do Li \\e( -console -or -local-root -or -root \\e) Dc Ns . 281.Pp 282.Bl -tag -width indent -compact 283.It Fl C , Fl console 284True if the kext is potentially required for console-mode startup 285(same as 286.Fl p Cm OSBundleRequired Console 287but always case-sensitive). 288.It Fl L , Fl local-root 289True if the kext is potentially required for local-root startup 290(same as 291.Fl p Cm OSBundleRequired Local-Root 292but always case-sensitive). 293.It Fl N , Fl network-root 294True if the kext is potentially required for network-root startup 295(same as 296.Fl p Cm OSBundleRequired Network-Root 297but always case-sensitive). 298.It Fl R , Fl root 299True if the kext is potentially required for root startup 300(same as 301.Fl p Cm OSBundleRequired Root 302but always case-sensitive). 303.It Fl S , Fl safe-boot 304True if the kext is potentially allowed to load during safe boot 305(same as 306.Fl p Cm OSBundleRequired 'Safe Boot' 307but always case-sensitive). 308.El 309.Sh Search by Version 310.Bl -tag -width indent -compact 311.It Fl compatible-with-version Ar version 312True if the kext is a library kext compatible with the given version. 313.It Fl V Xo 314.Oo Cm ne Ns | Ns Cm gt Ns | Ns Cm ge Ns | Ns Cm lt Ns | Ns Cm le Oc Ns Ar version Ns 315.Oo Ns Cm - Ns Ar version Oc 316.Xc 317.It Fl version Xo 318.Oo Cm ne Ns | Ns Cm gt Ns | Ns Cm ge Ns | Ns Cm lt Ns | Ns Cm le Oc Ns Ar version Ns 319.Oo Ns Cm - Ns Ar version Oc 320.Xc 321True if the kext's version matches the version expression. 322You can either specify an operator before a single version, 323or a range of versions. 324Remember that nonfinal versions such as 1.0d21 325compare as less than final versions (in this case 1.0); 326construct your version expression accordingly. 327See also 328.Fl library . 329.El 330.Sh QUERY COMMAND PREDICATES 331These predicates print information about kexts that match the query, 332or run a utility on the kext bundle directory, its info dictionary file, 333or its executable. 334Execpt for 335.Fl exec , 336these all have a true result for purposes of query evaluation. 337.Pp 338The 339.Fl echo 340and all 341.Fl print Ns \&.\|.\|. 342command predicates except for 343.Fl print-diagnostics 344accept a 345.Fl nul Li ( Ns Fl 0 Ns Li ) 346option to emit an ASCII NUL character (character code 0) 347in place of any newlines. 348This is useful when sending the output to 349.Xr xargs 1 . 350.Pp 351.Bl -tag -width indent -compact 352.It Fl echo Oo Fl n Ns | Ns Fl no-newline Oc Oo Fl 0 Ns | Ns Fl nul Oc Ar string 353Prints 354.Ar string 355followed by a newline. 356You can specify 357.Fl n 358or 359.Fl no-newline 360to omit the newline. 361If you specify both 362.Fl n 363and 364.Fl nul , 365.Ar string 366is not followed 367by either a newline or an ASCII NUL character. 368.It Ic -exec Ar utility Oo Ar argument Li \&.\|.\|. Oc Li \&; 369True if the program named 370.Ar utility 371returns a zero value as its exit status. 372Optional 373.Ar arguments 374may be passed to the utility. 375The expression must be terminated by a semicolon 376.Pq Dq Li \&; . 377If you invoke 378.Nm 379from a shell you may need to quote the semicolon if the shell would 380otherwise treat it as a control operator. 381The strings 382.Dq Li {} , 383.Dq Li {info-dictionary} , 384and 385.Dq Li {executable} , 386appearing anywhere in the utility name or the 387arguments are replaced by the pathname of the current kext, 388its info dictionary, or its executable, respectively. 389.Ar utility 390will be executed from the directory from which 391.Nm 392was executed. 393.Ar utility 394and 395.Ar arguments 396are not subject to the further expansion of shell patterns 397and constructs. 398.It Fl print Oo Fl 0 Ns | Ns Fl nul Oc 399Prints the pathname of the kext. 400If no command predicate is specified, 401the query as a whole becomes equivalent to 402.Cm \&( Ar query Cm \&) Fl and Fl print . 403.It Fl print0 404Equivalent to 405.Fl print 406.Fl nul , 407for all you 408.Xr find 1 409users out there. 410.It Fl pa Oo Fl 0 Ns | Ns Fl nul Oc 411.It Fl print-arches Oo Fl 0 Ns | Ns Fl nul Oc 412Prints the names of all the architectures 413in the kext executable (if it has one), 414separated by commas. 415.It Fl print-dependencies Oo Fl 0 Ns | Ns Fl nul Oc 416Prints the pathnames of all direct and indirect dependencies of the kext. 417.It Fl print-dependents Oo Fl 0 Ns | Ns Fl nul Oc 418Prints the pathnames of all direct and indirect dependents of the kext. 419.It Fl pdiag 420.It Fl print-diagnostics 421Prints validation and authentication failures, 422missing dependencies, 423and warnings for the kext. 424.It Fl px Oo Fl 0 Ns | Ns Fl nul Oc 425.It Fl print-executable Oo Fl 0 Ns | Ns Fl nul Oc 426Prints the pathname to the kext's executable file. 427.It Fl pid Oo Fl 0 Ns | Ns Fl nul Oc 428.It Fl print-info-dictionary Oo Fl 0 Ns | Ns Fl nul Oc 429Prints the pathname to the kext's info dictionary file. 430(You can use 431.Do Li "-exec cat {info-dictionary} \e;" Dc 432or 433.Do Li "-exec pl -input {info-dictionary} \e;" Dc 434to print the contents of the file.) 435.It Fl print-integrity Oo Fl 0 Ns | Ns Fl nul Oc 436OBSOLETE. As of Mac OS X 10.6 (Snow Leopard), 437kext integrity is not used and this command prints 438.Dq n/a 439for 440.Dq "not applicable" . 441.It Fl print-plugins Oo Fl 0 Ns | Ns Fl nul Oc 442Prints the pathnames of all plugins of the kext. 443.It Fl pm Oo Fl 0 Ns | Ns Fl nul Oc Ar name 444.It Fl print-match-property Oo Fl 0 Ns | Ns Fl nul Oc Ar name 445For each matching personality in the kext, if the named property exists, 446prints the personality's name, a colon, then 447.Ar name 448followed by an equals sign and the property's value. 449Results in true even if the property does not exist for any personality. 450.It Fl pp Oo Fl 0 Ns | Ns Fl nul Oc Ar name 451.It Fl print-property Oo Fl 0 Ns | Ns Fl nul Oc Ar name 452If the top-level property exists, prints 453.Ar name 454followed by an equals sign and its value. 455Results in true even if the property does not exist. 456.El 457.Sh OPERATORS 458The query primaries may be combined using the following operators. 459The operators are listed in order of decreasing precedence. 460.Pp 461.Bl -tag -width indent -compact 462.It Cm \&( Ar expression Cm \&) 463This evaluates to true if the parenthesized 464.Ar expression 465evaluates to true. 466Note that in many shells parentheses are special characters 467and must be escaped or quoted. 468.It Cm \&! Ar expression 469.It Fl not Ar expression 470This is the unary NOT operator. 471It evaluates to true if 472.Ar expression 473is false, 474to false if 475.Ar expression 476is true. 477Note that in many shells 478.Dq Li \&! 479is a special character 480and must be escaped or quoted. 481.It Ar expression Fl and Ar expression 482.It Ar expression Ar expression 483The 484.Ar and 485operator is the logical AND operator. 486It is implied by the juxtaposition of two expressions 487and therefore need not be specified. 488It evaluates to true if both expressions are true. 489If the first expression is false, the second expression is not evaluated. 490.It Ar expression Fl or Ar expression 491The 492.Fl or 493operator is the logical OR operator. 494It evaluates to true if either expression is true. 495If the first expression is true, the second expression is not evaluated. 496.El 497.Sh REPORTS 498Use the following predicates in a report expression 499to generate a tab-delimited format, 500one kext per line, 501suitable for further processing (or immediate edification). 502The report normally starts with a header line labeling each column; 503you can skip this by following 504.Fl report 505directly with 506.Fl no-header . 507.Pp 508The report predicate keywords are almost all the same as query predicates, 509but have different purposes (and arguments in several cases). 510In general, where a query predicate is looking for a value, 511a report predicate is retrieving it. 512Thus, the property predicates only take the name of the property, 513and print the value of that property for the kext being examined. 514Report predicates based on attributes with multiple values, 515such as 516.Fl print-dependencies , 517print the number of values rather than the values themselves. 518Finally, report predicates for yes/no questions print 519.Dq yes 520or 521.Dq no . 522.Pp 523Note that many shorthands for inverted meanings, such as 524.Fl invalid , 525are not available for reports (they would only be confusing). 526Others, such as 527.Fl match-property , 528could generate multiple values that would be impossible 529to embed meaningfully in plain tab-delimited text 530(and knowing how many of them there are is not useful). 531.Pp 532.Sh Value Report Predicates 533.Bl -tag -width indent -compact 534.It Fl b , Fl bundle-id 535Prints the kext's bundle identifier. 536.It Fl B , Fl bundle-name 537Prints the kext's bundle name. 538.It Fl integrity , Fl print-integrity 539OBSOLETE. As of Mac OS X 10.6 (Snow Leopard), 540kext integrity is not used and this command prints 541.Dq n/a 542for 543.Dq "not applicable" . 544.It Fl V , Fl version 545Prints the kext's version. 546.It Fl print 547Prints the kext's pathname. 548.It Fl pa , Fl print-arches 549Prints the names of the architectures, if any, in the kext executable. 550.It Fl print-dependencies 551Prints the number of dependencies found for the kext. 552.It Fl print-dependents 553Prints the number of kexts found that depend on the kext. 554.It Fl px , Fl print-executable 555Prints the pathname of the kext's executable (if it has one). 556.It Fl pid , Fl print-info-dictionary 557Prints the pathname of the kext's info dictionary. 558.It Fl print-plugins 559Prints the number of plugin kexts the kext has. 560.It Fl p Ar name , Fl property Ar name 561.It Fl pp Ar name , Fl print-property Ar name 562Prints the value for the top-level info dictionary property with key 563.Ar name . 564If the key is not defined, prints 565.Dq Li "<null>" . 566.It Fl sym Ar symbol , Fl symbol Ar symbol 567Prints 568.Dq references 569or 570.Dq defines 571if the kext 572references or defines 573.Ar symbol . 574(This is the only report predicate that is not also a query predicate.) 575.El 576.Sh Yes/No Report Predicates 577.Bl -tag -width indent -compact 578.It Fl arch Ar arch1 Ns Oo Ns Cm , Ns Ar arch2 Ns \&.\|.\|. Oc 579.Dq Li yes 580if the kexts contains 581.Em all 582the named architectures (and possibly others), 583.Dq Li no 584otherwise. 585.It Fl ax Ar arch1 Ns Oo Ns Cm , Ns Ar arch2 Ns \&.\|.\|. Oc , Fl arch-exact Ar arch1 Ns Oo Ns Cm , Ns Ar arch2 Ns \&.\|.\|. Oc 586.Dq Li yes 587if the kexts contains 588.Em exactly 589the named architectures (and no others), 590.Dq Li no 591otherwise. 592.It Fl a , Fl authentic 593.It Fl debug 594.It Fl d , Fl dependencies-met 595.It Fl dup, Fl duplicate-identifier 596.It Fl x , Fl executable 597.It Fl has-plugins 598.It Fl kernel-resource 599.It Fl lib , Fl library 600.It Fl l , Fl loadable 601.It Fl loaded 602.It Fl plugin 603.It Fl w , Fl warnings 604.It Fl v , Fl valid 605.El 606.Sh EXAMPLES 607The following examples are shown as given to the shell: 608.Pp 609.Bl -tag -width indent 610.It Li "kextfind -case-insensitive -not -bundle-id -substring 'com.apple.' -print" 611Print a list of all non-Apple kexts. 612.It Li "kextfind \e( -nonloadable -or -warnings \e) -print -print-diagnostics" 613Print a list of all kexts that aren't loadable or that have any warnings, 614along with what's wrong with each. 615.It Li "kextfind -nonloadable -print-dependents | sort | uniq" 616Print a list of all kexts that can't be loaded because 617of problems with their dependencies. 618.It Li "kextfind -defines-symbol __ZTV14IONetworkStack" 619Print a list of all kexts that define the symbol 620__ZTV14IONetworkStack. 621.It Li "kextfind -relative-paths -arch-exact ppc,i386" 622Print a list of all kexts kexts that contain only ppc and i386 code. 623.It Li "kextfind -debug -print -pp OSBundleDebugLevel -pm IOKitDebug" 624Print a list of all kexts that have debug options set, 625along with the values of the debug options. 626.It Li "kextfind -m IOProviderClass IOMedia -print -exec pl -input {info-dictionary} \;" 627Print a list of all kexts that match on IOMedia, 628along with their info dictionaries. 629.It Li "kextfind -no-paths -nl -report -print -v -a -d" 630Print a report of kexts that can't be loaded, 631with hints as to the problems. 632.El 633.Sh DIAGNOSTICS 634The 635.Nm 636utility exits with a status of 0 on completion 637(whether or not any kexts are found), 638or with a nonzero status if an error occurs. 639.Sh SEE ALSO 640.Xr find 1 , 641.Xr kextcache 8 , 642.Xr kextd 8 , 643.Xr kextload 8 , 644.Xr kextstat 8 , 645.Xr kextunload 8 , 646.Xr xargs 1 647.Sh BUGS 648Many single-letter options are inconsistent in meaning 649with (or directly contradictory to) the same letter options 650in other kext tools. 651.Pp 652Several special characters used by 653.Nm 654are also special characters to many shell programs. 655In particular, the characters 656.Dq Li \&! , 657.Dq Li \&( , 658and 659.Dq Li \&) , 660may have to be escaped from the shell. 661