588 lines · plain
1llvm-pdbutil - PDB File forensics and diagnostics2=================================================3 4.. program:: llvm-pdbutil5 6.. contents::7 :local:8 9Synopsis10--------11 12:program:`llvm-pdbutil` [*subcommand*] [*options*]13 14Description15-----------16 17Display types, symbols, CodeView records, and other information from a18PDB file, as well as manipulate and create PDB files. :program:`llvm-pdbutil`19is normally used by FileCheck-based tests to test LLVM's PDB reading and20writing functionality, but can also be used for general PDB file investigation21and forensics, or as a replacement for cvdump.22 23Subcommands24-----------25 26:program:`llvm-pdbutil` is separated into several subcommands each tailored to27a different purpose. A brief summary of each command follows, with more detail28in the sections that follow.29 30 * :ref:`pretty_subcommand` - Dump symbol and type information in a format that31 tries to look as much like the original source code as possible.32 * :ref:`dump_subcommand` - Dump low level types and structures from the PDB33 file, including CodeView records, hash tables, PDB streams, etc.34 * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,35 types, symbols, etc as raw bytes.36 * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce37 a valid PDB file that matches that description.38 * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML39 description of some or all of the file in a way that the PDB can be40 reconstructed.41 * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the42 result of merging the two input PDBs.43 44.. _pretty_subcommand:45 46pretty47~~~~~~48 49.. program:: llvm-pdbutil pretty50 51.. important::52 The **pretty** subcommand is built on the Windows DIA SDK, and as such is not53 supported on non-Windows platforms.54 55USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file>56 57Summary58^^^^^^^^^^^59 60The *pretty* subcommand displays a very high level representation of your61program's debug info. Since it is built on the Windows DIA SDK which is the62standard API that Windows tools and debuggers query debug information, it63presents a more authoritative view of how a debugger is going to interpret your64debug information than a mode which displays low-level CodeView records.65 66Options67^^^^^^^68 69Filtering and Sorting Options70+++++++++++++++++++++++++++++71 72.. note::73 *exclude* filters take priority over *include* filters. So if a filter74 matches both an include and an exclude rule, then it is excluded.75 76.. option:: -exclude-compilands=<string>77 78 When dumping compilands, compiland source-file contributions, or per-compiland79 symbols, this option instructs **llvm-pdbutil** to omit any compilands that80 match the specified regular expression.81 82.. option:: -exclude-symbols=<string>83 84 When dumping global, public, or per-compiland symbols, this option instructs85 **llvm-pdbutil** to omit any symbols that match the specified regular86 expression.87 88.. option:: -exclude-types=<string>89 90 When dumping types, this option instructs **llvm-pdbutil** to omit any types91 that match the specified regular expression.92 93.. option:: -include-compilands=<string>94 95 When dumping compilands, compiland source-file contributions, or per-compiland96 symbols, limit the initial search to only those compilands that match the97 specified regular expression.98 99.. option:: -include-symbols=<string>100 101 When dumping global, public, or per-compiland symbols, limit the initial102 search to only those symbols that match the specified regular expression.103 104.. option:: -include-types=<string>105 106 When dumping types, limit the initial search to only those types that match107 the specified regular expression.108 109.. option:: -min-class-padding=<uint>110 111 Only display types that have at least the specified amount of alignment112 padding, accounting for padding in base classes and aggregate field members.113 114.. option:: -min-class-padding-imm=<uint>115 116 Only display types that have at least the specified amount of alignment117 padding, ignoring padding in base classes and aggregate field members.118 119.. option:: -min-type-size=<uint>120 121 Only display types T where sizeof(T) is greater than or equal to the specified122 amount.123 124.. option:: -no-compiler-generated125 126 Don't show compiler generated types and symbols127 128.. option:: -no-enum-definitions129 130 When dumping an enum, don't show the full enum (e.g. the individual enumerator131 values).132 133.. option:: -no-system-libs134 135 Don't show symbols from system libraries136 137Symbol Type Options138+++++++++++++++++++139.. option:: -all140 141 Implies all other options in this category.142 143.. option:: -class-definitions=<format>144 145 Displays class definitions in the specified format.146 147 .. code-block:: text148 149 =all - Display all class members including data, constants, typedefs, functions, etc (default)150 =layout - Only display members that contribute to class size.151 =none - Don't display class definitions (e.g. only display the name and base list)152 153.. option:: -class-order154 155 Displays classes in the specified order.156 157 .. code-block:: text158 159 =none - Undefined / no particular sort order (default)160 =name - Sort classes by name161 =size - Sort classes by size162 =padding - Sort classes by amount of padding163 =padding-pct - Sort classes by percentage of space consumed by padding164 =padding-imm - Sort classes by amount of immediate padding165 =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding166 167.. option:: -class-recurse-depth=<uint>168 169 When dumping class definitions, stop after recursing the specified number of times. The170 default is 0, which is no limit.171 172.. option:: -classes173 174 Display classes175 176.. option:: -compilands177 178 Display compilands (e.g. object files)179 180.. option:: -enums181 182 Display enums183 184.. option:: -externals185 186 Dump external (e.g. exported) symbols187 188.. option:: -globals189 190 Dump global symbols191 192.. option:: -lines193 194 Dump the mappings between source lines and code addresses.195 196.. option:: -module-syms197 198 Display symbols (variables, functions, etc) for each compiland199 200.. option:: -sym-types=<types>201 202 Type of symbols to dump when -globals, -externals, or -module-syms is203 specified. (default all)204 205 .. code-block:: text206 207 =thunks - Display thunk symbols208 =data - Display data symbols209 =funcs - Display function symbols210 =all - Display all symbols (default)211 212.. option:: -symbol-order=<order>213 214 For symbols dumped via the -module-syms, -globals, or -externals options, sort215 the results in specified order.216 217 .. code-block:: text218 219 =none - Undefined / no particular sort order220 =name - Sort symbols by name221 =size - Sort symbols by size222 223.. option:: -typedefs224 225 Display typedef types226 227.. option:: -types228 229 Display all types (implies -classes, -enums, -typedefs)230 231Other Options232+++++++++++++233 234.. option:: -color-output235 236 Force color output on or off. By default, color if used if outputting to a237 terminal.238 239.. option:: -load-address=<uint>240 241 When displaying relative virtual addresses, assume the process is loaded at the242 given address and display what would be the absolute address.243 244.. _dump_subcommand:245 246dump247~~~~248 249USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file>250 251.. program:: llvm-pdbutil dump252 253Summary254^^^^^^^^^^^255 256The **dump** subcommand displays low level information about the structure of a257PDB file. It is used heavily by LLVM's testing infrastructure, but can also be258used for PDB forensics. It serves a role similar to that of Microsoft's259`cvdump` tool.260 261.. note::262 The **dump** subcommand exposes internal details of the file format. As263 such, the reader should be familiar with :doc:`/PDB/index` before using this264 command.265 266Options267^^^^^^^268 269MSF Container Options270+++++++++++++++++++++271 272.. option:: -streams273 274 dump a summary of all of the streams in the PDB file.275 276.. option:: -stream-blocks277 278 In conjunction with :option:`-streams`, add information to the output about279 what blocks the specified stream occupies.280 281.. option:: -summary282 283 Dump MSF and PDB header information.284 285Module & File Options286+++++++++++++++++++++287 288.. option:: -modi=<uint>289 290 For all options that dump information from each module/compiland, limit to291 the specified module.292 293.. option:: -files294 295 Dump the source files that contribute to each displayed module.296 297.. option:: -il298 299 Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)300 301.. option:: -l302 303 Dump line information (DEBUG_S_LINES CodeView subsection)304 305.. option:: -modules306 307 Dump compiland information308 309.. option:: -xme310 311 Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)312 313.. option:: -xmi314 315 Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)316 317Symbol Options318++++++++++++++319 320.. option:: -globals321 322 dump global symbol records323 324.. option:: -global-extras325 326 dump additional information about the globals, such as hash buckets and hash327 values.328 329.. option:: -publics330 331 dump public symbol records332 333.. option:: -public-extras334 335 dump additional information about the publics, such as hash buckets and hash336 values.337 338.. option:: -symbols339 340 dump symbols (functions, variables, etc) for each module dumped.341 342.. option:: -sym-data343 344 For each symbol record dumped as a result of the :option:`-symbols` option,345 display the full bytes of the record in binary as well.346 347Type Record Options348+++++++++++++++++++349 350.. option:: -types351 352 Dump CodeView type records from TPI stream353 354.. option:: -type-extras355 356 Dump additional information from the TPI stream, such as hashes and the type357 index offsets array.358 359.. option:: -type-data360 361 For each type record dumped, display the full bytes of the record in binary as362 well.363 364.. option:: -type-index=<uint>365 366 Only dump types with the specified type index.367 368.. option:: -ids369 370 Dump CodeView type records from IPI stream.371 372.. option:: -id-extras373 374 Dump additional information from the IPI stream, such as hashes and the type375 index offsets array.376 377.. option:: -id-data378 379 For each ID record dumped, display the full bytes of the record in binary as380 well.381 382.. option:: -id-index=<uint>383 384 only dump ID records with the specified hexadecimal type index.385 386.. option:: -dependents387 388 When used in conjunction with :option:`-type-index` or :option:`-id-index`,389 dumps the entire dependency graph for the specified index instead of just the390 single record with the specified index. For example, if type index 0x4000 is391 a function whose return type has index 0x3000, and you specify392 `-dependents=0x4000`, then this would dump both records (as well as any other393 dependents in the tree).394 395Miscellaneous Options396+++++++++++++++++++++397 398.. option:: -all399 400 Implies most other options.401 402.. option:: -section-contribs403 404 Dump section contributions.405 406.. option:: -section-headers407 408 Dump image section headers.409 410.. option:: -section-map411 412 Dump section map.413 414.. option:: -string-table415 416 Dump PDB string table.417 418.. _bytes_subcommand:419 420bytes421~~~~~422 423USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file>424 425.. program:: llvm-pdbutil bytes426 427Summary428^^^^^^^429 430Like the **dump** subcommand, the **bytes** subcommand displays low level431information about the structure of a PDB file, but it is used for even deeper432forensics. The **bytes** subcommand finds various structures in a PDB file433based on the command line options specified, and dumps them in hex. Someone434working on support for emitting PDBs would use this heavily, for example, to435compare one PDB against another PDB to ensure byte-for-byte compatibility. It436is not enough to simply compare the bytes of an entire file, or an entire stream437because it's perfectly fine for the same structure to exist at different438locations in two different PDBs, and "finding" the structure is half the battle.439 440Options441^^^^^^^442 443MSF File Options444++++++++++++++++445 446.. option:: -block-range=<start[-end]>447 448 Dump binary data from specified range of MSF file blocks.449 450.. option:: -byte-range=<start[-end]>451 452 Dump binary data from specified range of bytes in the file.453 454.. option:: -fpm455 456 Dump the MSF free page map.457 458.. option:: -stream-data=<string>459 460 Dump binary data from the specified streams. Format is SN[:Start][@Size].461 For example, `-stream-data=7:3@12` dumps 12 bytes from stream 7, starting462 at offset 3 in the stream.463 464PDB Stream Options465++++++++++++++++++466 467.. option:: -name-map468 469 Dump bytes of PDB Name Map470 471DBI Stream Options472++++++++++++++++++473 474.. option:: -ec475 476 Dump the edit and continue map substream of the DBI stream.477 478.. option:: -files479 480 Dump the file info substream of the DBI stream.481 482.. option:: -modi483 484 Dump the modi substream of the DBI stream.485 486.. option:: -sc487 488 Dump section contributions substream of the DBI stream.489 490.. option:: -sm491 492 Dump the section map from the DBI stream.493 494.. option:: -type-server495 496 Dump the type server map from the DBI stream.497 498Module Options499++++++++++++++500 501.. option:: -mod=<uint>502 503 Limit all options in this category to the specified module index. By default,504 options in this category will dump bytes from all modules.505 506.. option:: -chunks507 508 Dump the bytes of each module's C13 debug subsection.509 510.. option:: -split-chunks511 512 When specified with :option:`-chunks`, split the C13 debug subsection into a513 separate chunk for each subsection type, and dump them separately.514 515.. option:: -syms516 517 Dump the symbol record substream from each module.518 519Type Record Options520+++++++++++++++++++521 522.. option:: -id=<uint>523 524 Dump the record from the IPI stream with the given type index.525 526.. option:: -type=<uint>527 528 Dump the record from the TPI stream with the given type index.529 530.. _pdb2yaml_subcommand:531 532pdb2yaml533~~~~~~~~534 535USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file>536 537.. program:: llvm-pdbutil pdb2yaml538 539Summary540^^^^^^^541 542Options543^^^^^^^544 545.. _yaml2pdb_subcommand:546 547yaml2pdb548~~~~~~~~549 550USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file>551 552.. program:: llvm-pdbutil yaml2pdb553 554Summary555^^^^^^^556 557Generate a PDB file from a YAML description. The YAML syntax is not described558here. Instead, use :ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and559examine the output for an example starting point.560 561Options562^^^^^^^563 564.. option:: -pdb=<file-name>565 566Write the resulting PDB to the specified file.567 568.. _merge_subcommand:569 570merge571~~~~~572 573USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2>574 575.. program:: llvm-pdbutil merge576 577Summary578^^^^^^^579 580Merge two PDB files into a single file.581 582Options583^^^^^^^584 585.. option:: -pdb=<file-name>586 587Write the resulting PDB to the specified file.588