1llvm-pdbutil - PDB File forensics and diagnostics 2================================================= 3 4.. program:: llvm-pdbutil 5 6.. contents:: 7 :local: 8 9Synopsis 10-------- 11 12:program:`llvm-pdbutil` [*subcommand*] [*options*] 13 14Description 15----------- 16 17Display types, symbols, CodeView records, and other information from a 18PDB 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 and 20writing functionality, but can also be used for general PDB file investigation 21and forensics, or as a replacement for cvdump. 22 23Subcommands 24----------- 25 26:program:`llvm-pdbutil` is separated into several subcommands each tailored to 27a different purpose. A brief summary of each command follows, with more detail 28in the sections that follow. 29 30 * :ref:`pretty_subcommand` - Dump symbol and type information in a format that 31 tries to look as much like the original source code as possible. 32 * :ref:`dump_subcommand` - Dump low level types and structures from the PDB 33 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, produce 37 a valid PDB file that matches that description. 38 * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML 39 description of some or all of the file in a way that the PDB can be 40 reconstructed. 41 * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the 42 result of merging the two input PDBs. 43 44.. _pretty_subcommand: 45 46pretty 47~~~~~~ 48 49.. program:: llvm-pdbutil pretty 50 51.. important:: 52 The **pretty** subcommand is built on the Windows DIA SDK, and as such is not 53 supported on non-Windows platforms. 54 55USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file> 56 57Summary 58^^^^^^^^^^^ 59 60The *pretty* subcommand displays a very high level representation of your 61program's debug info. Since it is built on the Windows DIA SDK which is the 62standard API that Windows tools and debuggers query debug information, it 63presents a more authoritative view of how a debugger is going to interpret your 64debug information than a mode which displays low-level CodeView records. 65 66Options 67^^^^^^^ 68 69Filtering and Sorting Options 70+++++++++++++++++++++++++++++ 71 72.. note:: 73 *exclude* filters take priority over *include* filters. So if a filter 74 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-compiland 79 symbols, this option instructs **llvm-pdbutil** to omit any compilands that 80 match the specified regular expression. 81 82.. option:: -exclude-symbols=<string> 83 84 When dumping global, public, or per-compiland symbols, this option instructs 85 **llvm-pdbutil** to omit any symbols that match the specified regular 86 expression. 87 88.. option:: -exclude-types=<string> 89 90 When dumping types, this option instructs **llvm-pdbutil** to omit any types 91 that match the specified regular expression. 92 93.. option:: -include-compilands=<string> 94 95 When dumping compilands, compiland source-file contributions, or per-compiland 96 symbols, limit the initial search to only those compilands that match the 97 specified regular expression. 98 99.. option:: -include-symbols=<string> 100 101 When dumping global, public, or per-compiland symbols, limit the initial 102 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 match 107 the specified regular expression. 108 109.. option:: -min-class-padding=<uint> 110 111 Only display types that have at least the specified amount of alignment 112 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 alignment 117 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 specified 122 amount. 123 124.. option:: -no-compiler-generated 125 126 Don't show compiler generated types and symbols 127 128.. option:: -no-enum-definitions 129 130 When dumping an enum, don't show the full enum (e.g. the individual enumerator 131 values). 132 133.. option:: -no-system-libs 134 135 Don't show symbols from system libraries 136 137Symbol Type Options 138+++++++++++++++++++ 139.. option:: -all 140 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:: text 148 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-order 154 155 Displays classes in the specified order. 156 157 .. code-block:: text 158 159 =none - Undefined / no particular sort order (default) 160 =name - Sort classes by name 161 =size - Sort classes by size 162 =padding - Sort classes by amount of padding 163 =padding-pct - Sort classes by percentage of space consumed by padding 164 =padding-imm - Sort classes by amount of immediate padding 165 =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding 166 167.. option:: -class-recurse-depth=<uint> 168 169 When dumping class definitions, stop after recursing the specified number of times. The 170 default is 0, which is no limit. 171 172.. option:: -classes 173 174 Display classes 175 176.. option:: -compilands 177 178 Display compilands (e.g. object files) 179 180.. option:: -enums 181 182 Display enums 183 184.. option:: -externals 185 186 Dump external (e.g. exported) symbols 187 188.. option:: -globals 189 190 Dump global symbols 191 192.. option:: -lines 193 194 Dump the mappings between source lines and code addresses. 195 196.. option:: -module-syms 197 198 Display symbols (variables, functions, etc) for each compiland 199 200.. option:: -sym-types=<types> 201 202 Type of symbols to dump when -globals, -externals, or -module-syms is 203 specified. (default all) 204 205 .. code-block:: text 206 207 =thunks - Display thunk symbols 208 =data - Display data symbols 209 =funcs - Display function symbols 210 =all - Display all symbols (default) 211 212.. option:: -symbol-order=<order> 213 214 For symbols dumped via the -module-syms, -globals, or -externals options, sort 215 the results in specified order. 216 217 .. code-block:: text 218 219 =none - Undefined / no particular sort order 220 =name - Sort symbols by name 221 =size - Sort symbols by size 222 223.. option:: -typedefs 224 225 Display typedef types 226 227.. option:: -types 228 229 Display all types (implies -classes, -enums, -typedefs) 230 231Other Options 232+++++++++++++ 233 234.. option:: -color-output 235 236 Force color output on or off. By default, color if used if outputting to a 237 terminal. 238 239.. option:: -load-address=<uint> 240 241 When displaying relative virtual addresses, assume the process is loaded at the 242 given address and display what would be the absolute address. 243 244.. _dump_subcommand: 245 246dump 247~~~~ 248 249USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file> 250 251.. program:: llvm-pdbutil dump 252 253Summary 254^^^^^^^^^^^ 255 256The **dump** subcommand displays low level information about the structure of a 257PDB file. It is used heavily by LLVM's testing infrastructure, but can also be 258used for PDB forensics. It serves a role similar to that of Microsoft's 259`cvdump` tool. 260 261.. note:: 262 The **dump** subcommand exposes internal details of the file format. As 263 such, the reader should be familiar with :doc:`/PDB/index` before using this 264 command. 265 266Options 267^^^^^^^ 268 269MSF Container Options 270+++++++++++++++++++++ 271 272.. option:: -streams 273 274 dump a summary of all of the streams in the PDB file. 275 276.. option:: -stream-blocks 277 278 In conjunction with :option:`-streams`, add information to the output about 279 what blocks the specified stream occupies. 280 281.. option:: -summary 282 283 Dump MSF and PDB header information. 284 285Module & File Options 286+++++++++++++++++++++ 287 288.. option:: -modi=<uint> 289 290 For all options that dump information from each module/compiland, limit to 291 the specified module. 292 293.. option:: -files 294 295 Dump the source files that contribute to each displayed module. 296 297.. option:: -il 298 299 Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection) 300 301.. option:: -l 302 303 Dump line information (DEBUG_S_LINES CodeView subsection) 304 305.. option:: -modules 306 307 Dump compiland information 308 309.. option:: -xme 310 311 Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection) 312 313.. option:: -xmi 314 315 Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection) 316 317Symbol Options 318++++++++++++++ 319 320.. option:: -globals 321 322 dump global symbol records 323 324.. option:: -global-extras 325 326 dump additional information about the globals, such as hash buckets and hash 327 values. 328 329.. option:: -publics 330 331 dump public symbol records 332 333.. option:: -public-extras 334 335 dump additional information about the publics, such as hash buckets and hash 336 values. 337 338.. option:: -symbols 339 340 dump symbols (functions, variables, etc) for each module dumped. 341 342.. option:: -sym-data 343 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 Options 348+++++++++++++++++++ 349 350.. option:: -types 351 352 Dump CodeView type records from TPI stream 353 354.. option:: -type-extras 355 356 Dump additional information from the TPI stream, such as hashes and the type 357 index offsets array. 358 359.. option:: -type-data 360 361 For each type record dumped, display the full bytes of the record in binary as 362 well. 363 364.. option:: -type-index=<uint> 365 366 Only dump types with the specified type index. 367 368.. option:: -ids 369 370 Dump CodeView type records from IPI stream. 371 372.. option:: -id-extras 373 374 Dump additional information from the IPI stream, such as hashes and the type 375 index offsets array. 376 377.. option:: -id-data 378 379 For each ID record dumped, display the full bytes of the record in binary as 380 well. 381 382.. option:: -id-index=<uint> 383 384 only dump ID records with the specified hexadecimal type index. 385 386.. option:: -dependents 387 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 the 390 single record with the specified index. For example, if type index 0x4000 is 391 a function whose return type has index 0x3000, and you specify 392 `-dependents=0x4000`, then this would dump both records (as well as any other 393 dependents in the tree). 394 395Miscellaneous Options 396+++++++++++++++++++++ 397 398.. option:: -all 399 400 Implies most other options. 401 402.. option:: -section-contribs 403 404 Dump section contributions. 405 406.. option:: -section-headers 407 408 Dump image section headers. 409 410.. option:: -section-map 411 412 Dump section map. 413 414.. option:: -string-table 415 416 Dump PDB string table. 417 418.. _bytes_subcommand: 419 420bytes 421~~~~~ 422 423USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file> 424 425.. program:: llvm-pdbutil bytes 426 427Summary 428^^^^^^^ 429 430Like the **dump** subcommand, the **bytes** subcommand displays low level 431information about the structure of a PDB file, but it is used for even deeper 432forensics. The **bytes** subcommand finds various structures in a PDB file 433based on the command line options specified, and dumps them in hex. Someone 434working on support for emitting PDBs would use this heavily, for example, to 435compare one PDB against another PDB to ensure byte-for-byte compatibility. It 436is not enough to simply compare the bytes of an entire file, or an entire stream 437because it's perfectly fine for the same structure to exist at different 438locations in two different PDBs, and "finding" the structure is half the battle. 439 440Options 441^^^^^^^ 442 443MSF File Options 444++++++++++++++++ 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:: -fpm 455 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, starting 462 at offset 3 in the stream. 463 464PDB Stream Options 465++++++++++++++++++ 466 467.. option:: -name-map 468 469 Dump bytes of PDB Name Map 470 471DBI Stream Options 472++++++++++++++++++ 473 474.. option:: -ec 475 476 Dump the edit and continue map substream of the DBI stream. 477 478.. option:: -files 479 480 Dump the file info substream of the DBI stream. 481 482.. option:: -modi 483 484 Dump the modi substream of the DBI stream. 485 486.. option:: -sc 487 488 Dump section contributions substream of the DBI stream. 489 490.. option:: -sm 491 492 Dump the section map from the DBI stream. 493 494.. option:: -type-server 495 496 Dump the type server map from the DBI stream. 497 498Module Options 499++++++++++++++ 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:: -chunks 507 508 Dump the bytes of each module's C13 debug subsection. 509 510.. option:: -split-chunks 511 512 When specified with :option:`-chunks`, split the C13 debug subsection into a 513 separate chunk for each subsection type, and dump them separately. 514 515.. option:: -syms 516 517 Dump the symbol record substream from each module. 518 519Type Record Options 520+++++++++++++++++++ 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 532pdb2yaml 533~~~~~~~~ 534 535USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file> 536 537.. program:: llvm-pdbutil pdb2yaml 538 539Summary 540^^^^^^^ 541 542Options 543^^^^^^^ 544 545.. _yaml2pdb_subcommand: 546 547yaml2pdb 548~~~~~~~~ 549 550USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file> 551 552.. program:: llvm-pdbutil yaml2pdb 553 554Summary 555^^^^^^^ 556 557Generate a PDB file from a YAML description. The YAML syntax is not described 558here. Instead, use :ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and 559examine the output for an example starting point. 560 561Options 562^^^^^^^ 563 564.. option:: -pdb=<file-name> 565 566Write the resulting PDB to the specified file. 567 568.. _merge_subcommand: 569 570merge 571~~~~~ 572 573USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2> 574 575.. program:: llvm-pdbutil merge 576 577Summary 578^^^^^^^ 579 580Merge two PDB files into a single file. 581 582Options 583^^^^^^^ 584 585.. option:: -pdb=<file-name> 586 587Write the resulting PDB to the specified file. 588