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