docs/CommandGuide/llvm-pdbutil.rst

   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\r
  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\r
  31     file, including CodeView records, hash tables, PDB streams, etc.
  32   * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,\r
  33     types, symbols, etc as raw bytes.
  34   * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce\r
  35     a valid PDB file that matches that description.
  36   * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML\r
  37     description of some or all of the file in a way that the PDB can be\r
  38     reconstructed.
  39   * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the\r
  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\r
  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\r
  59 program's debug info.  Since it is built on the Windows DIA SDK which is the\r
  60 standard API that Windows tools and debuggers query debug information, it\r
  61 presents a more authoritative view of how a debugger is going to interpret your\r
  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\r
  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\r
  77  symbols, this option instructs **llvm-pdbutil** to omit any compilands that\r
  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\r
  83  **llvm-pdbutil** to omit any symbols that match the specified regular\r
  84  expression.
  85
  86 .. option:: -exclude-types=<string>
  87
  88  When dumping types, this option instructs **llvm-pdbutil** to omit any types\r
  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\r
  94  symbols, limit the initial search to only those compilands that match the\r
  95  specified regular expression.
  96
  97 .. option:: -include-symbols=<string>
  98
  99  When dumping global, public, or per-compiland symbols, limit the initial\r
 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\r
 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\r
 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\r
 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\r
 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\r
 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\r
 235  terminal.
 236
 237 .. option:: -load-address=<uint>
 238
 239  When displaying relative virtual addresses, assume the process is loaded at the\r
 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\r
 255 PDB file.  It is used heavily by LLVM's testing infrastructure, but can also be\r
 256 used for PDB forensics.  It serves a role similar to that of Microsoft's\r
 257 `cvdump` tool.\r
 258 \r
 259 .. note::\r
 260    The **dump** subcommand exposes internal details of the file format.  As\r
 261    such, the reader should be familiar with :doc:`/PDB/index` before using this\r
 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\r
 390  `-dependents=0x4000`, then this would dump both records (as well as any other\r
 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.